docker run -p 6379:6379 -it redis/redis-stack-server:latest
+Installation
Start a redis via docker:
+docker run -p 6379:6379 -d redis:8.0-rc1
To install node-redis, simply:
npm install redis
-"redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands, you can install the individual packages. See the list below.
+"redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands,
+you can install the individual packages. See the list below.
Packages
@@ -58,10 +59,167 @@
-Looking for a high-level library to handle object mapping? See redis-om-node!
+Looking for a high-level library to handle object mapping?
+See redis-om-node!
+Usage
Basic Example
import { createClient } from "redis";
const client = await createClient()
.on("error", (err) => console.log("Redis Client Error", err))
.connect();
await client.set("key", "value");
const value = await client.get("key");
client.destroy();
+
+The above code connects to localhost on port 6379. To connect to a different host or port, use a connection string in
+the format redis[s]://[[username][:password]@][host][:port][/db-number]:
+createClient({
url: "redis://alice:foobared@awesome.redis.server:6380",
});
+
+You can also use discrete parameters, UNIX sockets, and even TLS to connect. Details can be found in
+the client configuration guide.
+To check if the the client is connected and ready to send commands, use client.isReady which returns a boolean.
+client.isOpen is also available. This returns true when the client's underlying socket is open, and false when it
+isn't (for example when the client is still connecting or reconnecting after a network error).
+Redis Commands
There is built-in support for all of the out-of-the-box Redis commands. They are exposed
+using the raw Redis command names (HSET, HGETALL, etc.) and a friendlier camel-cased version (hSet, hGetAll,
+etc.):
+// raw Redis commands
await client.HSET("key", "field", "value");
await client.HGETALL("key");
// friendly JavaScript commands
await client.hSet("key", "field", "value");
await client.hGetAll("key");
+
+Modifiers to commands are specified using a JavaScript object:
+await client.set("key", "value", {
EX: 10,
NX: true,
});
+
+Replies will be transformed into useful data structures:
+await client.hGetAll("key"); // { field1: 'value1', field2: 'value2' }
await client.hVals("key"); // ['value1', 'value2']
+
+Buffers are supported as well:
+const client = createClient().withTypeMapping({
[RESP_TYPES.BLOB_STRING]: Buffer
});
await client.hSet("key", "field", Buffer.from("value")); // 'OK'
await client.hGet("key", "field"); // { field: <Buffer 76 61 6c 75 65> }
+
+Unsupported Redis Commands
If you want to run commands and/or use arguments that Node Redis doesn't know about (yet!) use .sendCommand():
+await client.sendCommand(["SET", "key", "value", "NX"]); // 'OK'
await client.sendCommand(["HGETALL", "key"]); // ['key1', 'field1', 'key2', 'field2']
+
+Transactions (Multi/Exec)
Start a transaction by calling .multi(), then chaining your commands. When
+you're done, call .exec() and you'll get an array back with your results:
+await client.set("another-key", "another-value");
const [setKeyReply, otherKeyValue] = await client
.multi()
.set("key", "value")
.get("another-key")
.exec(); // ['OK', 'another-value']
+
+You can also watch keys by calling
+.watch(). Your transaction will abort if any of the watched keys change.
+Blocking Commands
In v4, RedisClient had the ability to create a pool of connections using an "Isolation Pool" on top of the "main"
+connection. However, there was no way to use the pool without a "main" connection:
+const client = await createClient()
.on("error", (err) => console.error(err))
.connect();
await client.ping(client.commandOptions({ isolated: true }));
+
+In v5 we've extracted this pool logic into its own class—RedisClientPool:
+const pool = await createClientPool()
.on("error", (err) => console.error(err))
.connect();
await pool.ping();
+
+Pub/Sub
See the Pub/Sub overview.
+Scan Iterator
SCAN results can be looped over
+using async iterators:
+for await (const key of client.scanIterator()) {
// use the key!
await client.get(key);
}
+
+This works with HSCAN, SSCAN, and ZSCAN too:
+for await (const { field, value } of client.hScanIterator("hash")) {
}
for await (const member of client.sScanIterator("set")) {
}
for await (const { score, value } of client.zScanIterator("sorted-set")) {
}
+
+You can override the default options by providing a configuration object:
+client.scanIterator({
TYPE: "string", // `SCAN` only
MATCH: "patter*",
COUNT: 100,
});
+
+Disconnecting
The QUIT command has been deprecated in Redis 7.2 and should now also be considered deprecated in Node-Redis. Instead
+of sending a QUIT command to the server, the client can simply close the network connection.
+client.QUIT/quit() is replaced by client.close(). and, to avoid confusion, client.disconnect() has been renamed to
+client.destroy().
+client.destroy();
+
+Auto-Pipelining
Node Redis will automatically pipeline requests that are made during the same "tick".
+client.set("Tm9kZSBSZWRpcw==", "users:1");
client.sAdd("users:1:tokens", "Tm9kZSBSZWRpcw==");
+
+Of course, if you don't do something with your Promises you're certain to
+get unhandled Promise exceptions. To take
+advantage of auto-pipelining and handle your Promises, use Promise.all().
+await Promise.all([
client.set("Tm9kZSBSZWRpcw==", "users:1"),
client.sAdd("users:1:tokens", "Tm9kZSBSZWRpcw=="),
]);
+
+Programmability
See the Programmability overview.
+Clustering
Check out the Clustering Guide when using Node Redis to connect to a Redis Cluster.
+Events
The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:
+
+
+
+Name
+When
+Listener arguments
+
+
+
+connectInitiating a connection to the server
+No arguments
+
+
+readyClient is ready to use
+No arguments
+
+
+endConnection has been closed (via .disconnect())
+No arguments
+
+
+errorAn error has occurred—usually a network issue such as "Socket closed unexpectedly"
+(error: Error)
+
+reconnectingClient is trying to reconnect to the server
+No arguments
+
+
+sharded-channel-movedSee here
+See here
+
+
+
+:warning: You MUST listen to error events. If a client doesn't have at least one error listener registered and
+an error occurs, that error will be thrown and the Node.js process will exit. See the > EventEmitter docs for more details.
+
+
+The client will not emit any other events beyond those listed above.
+
+Supported Redis versions
Node Redis is supported with the following versions of Redis:
+
+
+
+Version
+Supported
+
+
+
+8.0.z
+:heavy_check_mark:
+
+
+7.0.z
+:heavy_check_mark:
+
+
+6.2.z
+:heavy_check_mark:
+
+
+6.0.z
+:heavy_check_mark:
+
+
+5.0.z
+:heavy_check_mark:
+
+
+< 5.0
+:x:
+
+
+
+Node Redis should work with older versions of Redis, but it is not fully tested and we cannot offer support.
+
+Migration
+- From V3 to V4
+- From V4 to V5
+- V5
+
Contributing
If you'd like to contribute, check out the contributing guide.
Thank you to all the people who already contributed to Node Redis!
License
This repository is licensed under the "MIT" license. See LICENSE.
-Generated using TypeDoc