node-redis/README.md

⚠️ 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

(async () => {
    const client = require('redis').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');
})();

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 (HGET, HSET, etc.) and a friendlier camel-cased version (hGet, hSet, etc.).

// raw Redis commands
await client.SET('key', 'value');
await client.GET('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 to useful data structures:

await client.hGetAll('key'); // { key1: 'value1', key2: 'value2' }
await client.hKeys('key'); // ['key1', 'key2']

Unsupported Redis Commands

If you want to run commands and 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']

Blocking Commands

Any command can be run on a new connection by specifying the duplicateConnection option. The newly created connection is closed when command's Promise is fulfilled.

This pattern works especially well for blocking commands—such as BLPOP and BRPOPLPUSH:

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

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

await blPopPromise; // '2'

Pub/Sub

Subscribing to a channel requires a dedicated Redis connection and is easily handled using events.

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

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

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

Lua Scripts

You can define Lua scripts to create efficient custom commands:

(async () => {
    const client = require('redis').createClient({
        scripts: {
            add: require('redis/lua-script').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
})();

Contributing

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

License

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