node-redis/docs/v4-to-v5.md

v4 to v5 migration guide

Command Options

In v4, command options are passed as a first optional argument:

await client.get('key'); // `string | null`
await client.get(client.commandOptions({ returnBuffers: true }), 'key'); // `Buffer | null`

This has a couple of flaws:

1. The argument types are checked in runtime, which is a performance hit.
2. Code suggestions are less readable/usable, due to "function overloading".
3. Overall, "user code" is not as readable as it could be.

The new API for v5

With the new API, instead of passing the options directly to the commands we use a "proxy client" to store them:

await client.get('key'); // `string | null`

const proxyClient = client.withCommandOptions({
  flags: {
    [TYPES.BLOB_STRING]: Buffer
  }
});

await proxyClient.get('key'); // `Buffer | null`

withCommandOptions can be used to override all of the command options, without reusing any existing ones.

To override just a specific option, use the following functions:

• withFlags - override flags only.
• asap - override asap to true.
• isolated - override isolated to true.

Quit VS Disconnect

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.

Rather than using client.quit(), your code should use client.close() or client.disconnect().

TODO difference between close and disconnect...

Scan Iterators

TODO Yields chunks instead of individual items. Allows multi key operations. See the Scan Iterators guide.

Legacy Mode

TODO

const client = createClient(),
  legacyClient = client.legacy();

// use `client` for the new API
await client.set('key', 'value');

// use `legacyClient` for the "legacy" callback API
legacyClient.set('key', 'value', (err, reply) => {
  // ...
});

Isolation Pool

TODO The isolationPool has been moved to it's on class ClientPool. You can create pool from a client using client.createPool().

Commands

Some command arguments/replies have changed to align more closely to data types returned by Redis:

• ACL GETUSER: selectors
• CLIENT KILL: enum ClientKillFilters -> const CLIENT_KILL_FILTERS ¹
• CLUSTER FAILOVER: enum FailoverModes -> const FAILOVER_MODES ¹
• LCS IDX: length has been changed to len, matches has been changed from Array<{ key1: RangeReply; key2: RangeReply; }> to Array<[key1: RangeReply, key2: RangeReply]>
• HEXISTS: boolean -> number ²
• HRANDFIELD_COUNT_WITHVALUES: Record<BlobString, BlobString> -> Array<{ field: BlobString; value: BlobString; }> (it can return duplicates).
• SCAN, HSCAN, SSCAN, and ZSCAN: cursor type is string instead of number?
• HSETNX: boolean -> number ²
• ZINTER: instead of client.ZINTER('key', { WEIGHTS: [1] }) use client.ZINTER({ key: 'key', weight: 1 }])
• ZINTER_WITHSCORES: instead of client.ZINTER_WITHSCORES('key', { WEIGHTS: [1] }) use client.ZINTER_WITHSCORES({ key: 'key', weight: 1 }])
• ZUNION: instead of client.ZUNION('key', { WEIGHTS: [1] }) use client.ZUNION({ key: 'key', weight: 1 }])
• ZUNION_WITHSCORES: instead of client.ZUNION_WITHSCORES('key', { WEIGHTS: [1] }) use client.ZUNION_WITHSCORES({ key: 'key', weight: 1 }])
• SETNX: boolean -> number ²
• COPY: destinationDb -> DB, replace -> REPLACE, boolean -> number ²
• EXPIRE: boolean -> number ²
• EXPIREAT: boolean -> number ²
• MOVE: boolean -> number ²
• PEXPIRE: boolean -> number ²
• PEXPIREAT: boolean -> number ²
• RENAMENX: boolean -> number ²
• HSCAN: tuples has been renamed to entries
• PFADD: boolean -> number ²
• SCRIPT EXISTS: Array<boolean> -> Array<number> ²
• SISMEMBER: boolean -> number ²
• SMISMEMBER: Array<boolean> -> Array<number> ²
• SMOVE: boolean -> number ²
• TS.ADD: boolean -> number ²
• GEOSEARCH_WITH/GEORADIUS_WITH: GeoReplyWith -> GEO_REPLY_WITH ¹
• GEORADIUSSTORE -> GEORADIUS_STORE
• GEORADIUSBYMEMBERSTORE -> GEORADIUSBYMEMBER_STORE
• XACK: boolean -> number ²
• XADD: the INCR option has been removed, use XADD_INCR instead

---

1. TODO ↩︎

2. TODO ↩︎