redis

:warning: Version 4 is still under development and isn't ready for production use. Use at your own risk.

---

Node Redis

A high performance Node.js Redis client.

---

---

Installation

npm install redis@next

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 only connects to localhost on port 6379. You probably want to connect to somewhere else. To do so, use a connection string in the format [redis[s]:]//[[username][:password@]][host][:port]:

createClient({
    socket: {
        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 in the Wiki.

The new interface is clean and cool, but if you have an existing code base, you might want to enable legacy mode.

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!) you can 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 can easily 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 just passing them in:

client.scanIterator({
    TYPE: 'string', // `SCAN` only
    MATCH: 'patter*',
    COUNT: 100
});

Lua Scripts

You can define Lua scripts to create efficient custom commands:

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<string> {
                    return [key, number.toString()];
                },
                transformReply(reply: number): number {
                    return reply;
                }
            })
        }
    });

    await client.connect();

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

Cluster

Connecting to a cluster is a bit different. Create the client by specifying some (or all) of the nodes in your cluster and then use it like a non-clustered client:

import { createCluster } from 'redis';

(async () => {
    const cluster = createCluster({
        rootNodes: [{
            host: '10.0.0.1',
            port: 30001
        }, {
            host: '10.0.0.2',
            port: 30002
        }]
    });

    cluster.on('error', (err) => console.log('Redis Cluster Error', err));

    await cluster.connect();

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

Legacy Mode

Need to use the new client in an existing codebase? You can use legacy mode to preserve backwards compatibility while still getting access to the updated experience:

const client = createClient({
    legacyMode: true
});

// legacy mode
client.set('key', 'value', 'NX', (err, reply) => {
    // ...
});

// version 4 interface is still accessible
await client.v4.set('key', 'value', {
    NX: true
});

Contributing

If you'd like to contribute, check out the contributing guide.

License

This repository is licensed under the "MIT" license. See LICENSE.