Need help with node-redis?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

redis
14.3K Stars 1.5K Forks MIT License 1.4K Commits 129 Opened issues

Description

A high performance Node.js Redis client.

Services available

!
?

Need anything else?

Contributors list

Node Redis


Installation

npm install [email protected]

:warning: The new interface is clean and cool, but if you have an existing code base, you'll want to read the migration guide.

Usage

Basic Example

import { createClient } from 'redis';

(async () => { const client = createClient();

client.on('error', (err) => console.log('Redis Client Error', err));

await client.connect();

await client.set('key', 'value'); const value = await client.get('key'); })();

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:[email protected]:6380'
});

You can also use discrete parameters, UNIX sockets, and even TLS to connect. Details can be found in the client configuration guide.

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']

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.

To dig deeper into transactions, check out the Isolated Execution Guide.

Blocking Commands

Any command can be run on a new connection by specifying the

isolated
option. The newly created connection is closed when the command's
Promise
is fulfilled.

This pattern works especially well for blocking commands—such as

BLPOP
and
BLMOVE
:
import { commandOptions } from 'redis';

const blPopPromise = client.blPop(commandOptions({ isolated: true }), 'key');

await client.lPush('key', ['1', '2']);

await blPopPromise; // '2'

To learn more about isolated execution, check out the guide.

Pub/Sub

Subscribing to a channel requires a dedicated stand-alone connection. You can easily get one by

.duplicate()
ing an existing Redis connection.
const subscriber = client.duplicate();

await subscriber.connect();

Once you have one, simply subscribe and unsubscribe as needed:

await subscriber.subscribe('channel', (message) => {
  console.log(message); // 'message'
});

await subscriber.pSubscribe('channe*', (message, channel) => { console.log(message, channel); // 'message', 'channel' });

await subscriber.unsubscribe('channel');

await subscriber.pUnsubscribe('channe*');

Publish a message on a channel:

await publisher.publish('channel', 'message');

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 member of client.hScanIterator('hash')) {}
for await (const { field, value } of client.sScanIterator('set')) {}
for await (const { member, score } 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
});

Lua Scripts

Define new functions using Lua scripts which execute on the Redis server:

import { createClient, defineScript } from 'redis';

(async () => { const client = createClient({ scripts: { add: defineScript({ NUMBER_OF_KEYS: 1, SCRIPT: "local val = redis.pcall('GET', KEYS[1]);' + 'return val + ARGV[1];", transformArguments(key: string, toAdd: number): Array { return [key, number.toString()]; }, transformReply(reply: number): number { return reply; } }) } });

await client.connect();

await client.set('key', '1'); await client.add('key', 2); // 3 })();

Disconnecting

There are two functions that disconnect a client from the Redis server. In most scenarios you should use

.quit()
to ensure that pending commands are sent to Redis before closing a connection.

.QUIT()
/
.quit()

Gracefully close a client's connection to Redis, by sending the

QUIT
command to the server. Before quitting, the client executes any remaining commands in its queue, and will receive replies from Redis for each of them.

const [ping, get, quit] = await Promise.all([
  client.ping(),
  client.get('key'),
  client.quit()
]); // ['PONG', null, 'OK']

try { await client.get('key'); } catch (err) { // ClosedClient Error }

.disconnect()

Forcibly close a client's connection to Redis immediately. Calling

disconnect
will not send further pending commands to the Redis server, or wait for or parse outstanding responses.
await client.disconnect();

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==')
]);

Clustering

Check out the Clustering Guide when using Node Redis to connect to a Redis Cluster.

Supported Redis versions

Node Redis is supported with the following versions of Redis:

| Version | Supported | |---------|--------------------| | 6.2.z | :heavycheckmark: | | 6.0.z | :heavycheckmark: | | 5.y.z | :heavycheckmark: | | < 5.0 | :x: |

Node Redis should work with older versions of Redis, but it is not fully tested and we cannot offer support.

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.