node-redis README

The project's README from github.com/redis/node-redis. As one markdown file: README.md.

Node-Redis

Tests Coverage License

Discord Twitch YouTube Twitter

node-redis is a modern, high performance Redis client for Node.js.

How do I Redis?

Learn for free at Redis University

Build faster with the Redis Launchpad

Try the Redis Cloud

Dive in developer tutorials

Join the Redis community

Work at Redis

Installation

Start a redis via docker:

docker run -p 6379:6379 -d redis:8.0-rc1

To install node-redis, simply:

npm install redis

"redis" is the "whole in one" package that includes all the other packages. If you only need a subset of the commands, you can install the individual packages. See the list below.

Packages

Name Description
redis The client with all the "redis-stack" modules
@redis/client The base clients (i.e RedisClient, RedisCluster, etc.)
@redis/bloom Redis Bloom commands
@redis/json Redis JSON commands
@redis/search RediSearch commands
@redis/time-series Redis Time-Series commands
@redis/entraid Secure token-based authentication for Redis clients using Microsoft Entra ID

Looking for a high-level library to handle object mapping? See redis-om-node!

Usage

Basic Example

import { createClient } from "redis";

const client = await createClient()
  .on("error", (err) => console.log("Redis Client Error", err))
  .connect();

await client.set("key", "value");
const value = await client.get("key");
console.log(value); // 'value'
client.destroy();

The same example in CommonJS (for example node example.js without "type": "module" in package.json):

const { createClient } = require("redis");

async function main() {
  const client = await createClient()
    .on("error", (err) => console.log("Redis Client Error", err))
    .connect();

  await client.set("key", "value");
  const value = await client.get("key");
  console.log(value); // 'value'
  client.destroy();
}

main().catch(console.error);

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.

To check if the client is connected and ready to send commands, use client.isReady which returns a boolean. client.isOpen is also available. This returns true when the client's underlying socket is open, and false when it isn't (for example when the client is still connecting or reconnecting after a network error).

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

Buffers are supported as well:

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

await client.hSet("key", "field", Buffer.from("value")); // 'OK'
await client.hGet("key", "field"); // { field: <Buffer 76 61 6c 75 65> }

For commands that return serialized binary payloads, such as DUMP, map blob strings to Buffer before using the result with commands like RESTORE:

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

const dump = await binaryClient.dump("source");
await binaryClient.restore("destination", 0, dump);

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

Note: the API is different when using a cluster.

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.

Blocking Commands

In v4, RedisClient had the ability to create a pool of connections using an "Isolation Pool" on top of the "main" connection. However, there was no way to use the pool without a "main" connection:

const client = await createClient()
  .on("error", (err) => console.error(err))
  .connect();

await client.ping(client.commandOptions({ isolated: true }));

In v5 we've extracted this pool logic into its own class—RedisClientPool:

const pool = await createClientPool()
  .on("error", (err) => console.error(err))
  .connect();

await pool.ping();

Pub/Sub

See the Pub/Sub overview.

Scan Iterator

SCAN results can be looped over using async iterators:

for await (const keys of client.scanIterator()) {
  console.log(keys, await client.mGet(keys));
}

This works with HSCAN, SSCAN, and ZSCAN too:

for await (const { field, value } of client.hScanIterator("hash")) {
}
for await (const member of client.sScanIterator("set")) {
}
for await (const { score, value } of client.zScanIterator("sorted-set")) {
}

You can override the default options by providing a configuration object:

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

Compare-and-Set/Delete (CAS/CAD)

Note: CAS/CAD operations were introduced in Redis 8.4

// Conditionally update only if the current value matches
await client.set("key", "new-value", { condition: "IFEQ", matchValue: "old-value" });

// Conditionally delete only if the current value matches
await client.delEx("key", { condition: "IFEQ", matchValue: "expected-value" });

Local Digest

Note: This feature requires the optional @node-rs/xxhash peer dependency.

The digest helper computes an XXH3 64-bit hash locally, matching what Redis computes via the DIGEST command. This is useful for CAS/CAD operations with large values where comparing the full value would be inefficient.

npm install @node-rs/xxhash

import { digest } from "redis";

const hash = await digest("my-value");

await client.set("key", "new-value", { condition: "IFDEQ", matchValue: hash });

Disconnecting

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.

client.QUIT/quit() is replaced by client.close(). and, to avoid confusion, client.disconnect() has been renamed to client.destroy().

client.destroy();

Client Side Caching

Node Redis v5 adds support for Client Side Caching, which enables clients to cache query results locally. The Redis server will notify the client when cached results are no longer valid.

// Enable client side caching with RESP3
const client = createClient({
  RESP: 3,
  clientSideCache: {
    ttl: 0,             // Time-to-live (0 = no expiration)
    maxEntries: 0,      // Maximum entries (0 = unlimited)
    evictPolicy: "LRU"  // Eviction policy: "LRU" or "FIFO"
  }
});

See the V5 documentation for more details and advanced usage.

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

Sentinel

Look at the sentinel section to figure out how to use this library with sentinels.

Programmability

See the Programmability overview.

Clustering

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

OpenTelemetry

OpenTelemetry Metrics Instrumentation

import { createClient, OpenTelemetry } from "redis";

OpenTelemetry.init({
  metrics: {
    enabled: true
  }
});

const client = createClient()

await client.connect();
// ... use the client as usual

Important: Initializing OpenTelemetry only enables node-redis metrics instrumentation and requires both @opentelemetry/api and an OpenTelemetry SDK configured in your application.

Important: Initialize OpenTelemetry before creating Redis clients. For SDK/provider/exporter setup, verification, and advanced configuration, see:

Diagnostics Channel

Node Redis publishes telemetry through Node.js diagnostics_channel, enabling APM tools and custom instrumentation to observe commands, connections, and internal events. See the Diagnostics Channel guide for the full channel reference and usage examples.

Events

The Node Redis client class is an Nodejs EventEmitter and it emits an event each time the network status changes:

Name When Listener arguments
connect Initiating a connection to the server No arguments
ready Client is ready to use No arguments
end Connection has been closed (via .close() or .destroy()) No arguments
error An error has occurred—usually a network issue such as "Socket closed unexpectedly" (error: Error)
reconnecting Client is trying to reconnect to the server No arguments
terminated Reconnection has stopped because reconnectStrategy returned false or an Error; emitted before the companion error (cause: Error)
sharded-channel-moved See here See here
invalidate Client Tracking is on with emitInvalidate and a key is invalidated (key: RedisItem | null)

:warning: You MUST listen to error events. If a client doesn't have at least one error listener registered and an error occurs, that error will be thrown and the Node.js process will exit. See the > EventEmitter docs for more details.

The client will not emit any other events beyond those listed above.

Supported Redis versions

Node Redis is supported with the following versions of Redis:

See Supported Redis Versions.

Migration

Contributing

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

Thank you to all the people who already contributed to Node Redis!

Contributors

License

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

node-redis (redis/node-redis)

Searching Database…

17.6K ·GitHub
Node-redis
Что это такое?Node-Redis — это современный высокопроизводительный Redis-клиент для Node.js, то есть библиотека, через которую ваше приложение на JavaScript или TypeScript общается с сервером Redis. Поддерживает модули Redis Stack: JSON, Search и Time-Series.
Это библиотека, которую я добавляю в свой проект, или она работает как отдельный сервер?Это npm-библиотека, которую вы добавляете в проект — сам сервер Redis работает отдельно. Можно установить универсальный пакет 'redis' со всем сразу или отдельные пакеты вроде @redis/json или @redis/search, если нужна лишь часть возможностей.
Как подключить её к моему Redis?Выполните 'npm install redis', запустите сам Redis (в README показано, как это сделать через Docker), затем подключайтесь — по умолчанию это localhost:6379, либо передайте строку подключения redis[s]:// с именем пользователя, паролем, портом и номером базы данных. Свойство client.isReady сообщает, когда клиент готов к работе.
Что нужно установить, кроме самой библиотеки?Node.js и работающий сервер Redis — в README он запускается через Docker. Есть два необязательных дополнения: @node-rs/xxhash для функции Local Digest и @opentelemetry/api с SDK, если нужна телеметрия по метрикам.
Там есть все команды Redis, которые мне могут понадобиться?Все стандартные команды Redis уже встроены и доступны как в исходном написании (HSET), так и в camelCase (hSet). Для команд или аргументов, которых клиент ещё не знает, есть обходной путь — сырой метод .sendCommand(). Учтите, что API отличается при работе с кластером.
Можно использовать её в коммерческих проектах?Да — лицензия MIT, так что библиотека бесплатна и для личного, и для коммерческого использования.
Как возвращаются ответы на команды — сырые строки или уже разобранные данные?Ответы преобразуются в удобные структуры данных JavaScript, а поддержка Buffer охватывает бинарные данные, как в командах DUMP и RESTORE. Модификаторы команд передаются обычными объектами JavaScript.
Можно ли делать транзакции?Да — вызовите .multi(), добавьте нужные команды в цепочку, затем .exec() и получите массив результатов. Можно также ставить ключи на контроль через .watch(): транзакция прервётся, если любой из отслеживаемых ключей изменится.
Она работает с Redis Cluster и Sentinel?Да — в README есть руководство Clustering Guide для настройки Redis Cluster и раздел про Sentinel для развёртываний с sentinel. Имейте в виду, что API клиента работает иначе при подключении к кластеру.
Можно ли увидеть, чем клиент занят в продакшене?Да — телеметрия OpenTelemetry по метрикам встроена (OpenTelemetry нужно инициализировать до создания клиентов), а клиент публикует телеметрию через Node.js diagnostics_channel, так что APM-инструменты могут наблюдать за командами и подключениями.
What are similar projects?ioredis, phpredis, go-redis, redis-py, redis, emqx, dicedb, valkey
Which topics is it in?redis-client, redis-cluster, in-memory, pubsub, api-client, opentelemetry, key-value, caching, messaging, tls, redis, observability
Creator
redis
Size
315.1 MB
Stars
17.6K
Updated
CommitOct 16Release[email protected]Aug 11
Age
16y
Commits · 90 Days