Skip to content

command-options.md

Latest commit

 

History

History
112 lines (79 loc) · 3.11 KB

command-options.md

File metadata and controls

112 lines (79 loc) · 3.11 KB

Command Options

⚠️ The command options API in v5 has breaking changes from the previous version. For more details, refer to the v4-to-v5 guide.

Command Options are used to create "proxy clients" that change the behavior of executed commands. See the sections below for details.

Type Mapping

Some RESP types can be mapped to more than one JavaScript type. For example, "Blob String" can be mapped to string or Buffer. You can override the default type mapping using the withTypeMapping function:

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

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

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

See RESP for a full list of types.

DUMP/RESTORE and Binary Data

DUMP returns serialized binary data. If blob strings are decoded as string (the default), the payload can be lossy and RESTORE may fail with ERR DUMP payload version or checksum are wrong.

Use Buffer mapping for blob strings:

import { createClient, RESP_TYPES } from 'redis';

const client = createClient().withTypeMapping({
  [RESP_TYPES.BLOB_STRING]: Buffer
});

const dump = await client.dump('source');
await client.restore('destination', 0, dump);

You can also set it as a default:

const client = createClient({
  commandOptions: {
    typeMapping: {
      [RESP_TYPES.BLOB_STRING]: Buffer
    }
  }
});

In v5, use withTypeMapping or createClient({ commandOptions: { typeMapping } }) instead of the v4 client.commandOptions({ returnBuffers: true }) call style.

Abort Signal

The client batches commands before sending them to Redis. Commands that haven't been written to the socket yet can be aborted using the AbortSignal API:

const controller = new AbortController(),
  client = client.withAbortSignal(controller.signal);

try {
  const promise = client.get('key');
  controller.abort();
  await promise;
} catch (err) {
  // AbortError
}

Timeout

This option is similar to the Abort Signal one, but provides an easier way to set timeout for commands. Again, this applies to commands that haven't been written to the socket yet.

const client = createClient({
  commandOptions: {
    timeout: 1000
  }
})

ASAP

Commands that are executed in the "asap" mode are added to the beginning of the "to sent" queue.

const asapClient = client.asap();
await asapClient.ping();

withCommandOptions

You can set all of the above command options in a single call with the withCommandOptions function:

client.withCommandOptions({
  typeMapping: ...,
  abortSignal: ...,
  asap: ...
});

If any of the above options are omitted, the default value will be used. For example, the following client would not be in ASAP mode:

client.asap().withCommandOptions({
  typeMapping: ...,
  abortSignal: ...
});