redis / ioredis

A robust, performance-focused and full-featured Redis client for Node.js. Supports Redis >= 2.6.12. Completely compatible with Redis 7.x. ioredis is a stable project and maintenance is done on a best-effort basis for relevant issues (contributions to ioredis will still be evaluated, reviewed, and merged when they benefit the project). For new projects, node-redis is the recommended client library. node-redis is the open-source (MIT license) Redis JavaScript client library redesigned from the ground up and actively maintained. node-redis supports new (hash-field expiration) and future commands and the capabilities available in Redis Stack and Redis 8 (search, JSON, time-series, probabilistic data structures). Features ioredis is a robust, full-featured Redis client that is used in the world's biggest online commerce company Alibaba and many other awesome companies. • Full-featured. It supports Cluster, Sentinel, Streams, Pipelining, and of course Lua scripting, Redis Functions, Pub/Sub (with the support of binary messages). • High performance 🚀. • Delightful API 😄. It works with Node callbacks and Native promises. • Transformation of command arguments and replies. • Transparent key prefixing. • Abstraction for Lua scripting, allowing you to define custom commands. • Supports binary data. • Supports TLS 🔒. • Supports offline queue and ready checking. • Supports ES6 types, such as and . • Supports GEO commands 📍. • Supports Redis ACL. • Sophisticated error handling strategy. • Supports NAT mapping. • Supports autopipelining. **100% written in TypeScript and official declarations are provided:** Versions | Version | Branch | Node.js Version | Redis Version | | -------------- | ------ | --------------- | --------------- | | 5.x.x (latest) | main | >= 12 | 2.6.12 ~ latest | | 4.x.x | v4 | >= 8 | 2.6.12 ~ 7 | Refer to CHANGELOG.md for features and bug fixes introduced in v5. 🚀 Upgrading from v4 to v5 Links • API Documentation (Redis, Cluster) • Changelog Quick Start Install In a TypeScript project, you may want to add TypeScript declarations for Node.js: Basic Usage See the folder for more examples. For example: • TTL • Strings • Hashes • Lists • Sets • Sorted Sets • Streams • Redis Modules e.g. RedisJSON All Redis commands are supported. See the documentation for details. Connect to Redis When a new instance is created, a connection to Redis will be created at the same time. You can specify which Redis to connect to by: You can also specify connection options as a URL or URL when using TLS encryption: See API Documentation for all available options. Pub/Sub Redis provides several commands for developers to implement the Publish–subscribe pattern. There are two roles in this pattern: publisher and subscriber. Publishers are not programmed to send their messages to specific subscribers. Rather, published messages are characterized into channels, without knowledge of what (if any) subscribers there may be. By leveraging Node.js's built-in events module, ioredis makes pub/sub very straightforward to use. Below is a simple example that consists of two files, one is publisher.js that publishes messages to a channel, the other is subscriber.js that listens for messages on specific channels. It's worth noticing that a connection (aka a instance) can't play both roles at the same time. More specifically, when a client issues or , it enters the "subscriber" mode. From that point, only commands that modify the subscription set are valid. Namely, they are: , , , , , and . When the subscription set is empty (via / ), the connection is put back into the regular mode. If you want to do pub/sub in the same file/process, you should create a separate connection: is also supported in a similar way when you want to subscribe all channels whose name matches a pattern: Streams Redis v5 introduces a new data type called streams. It doubles as a communication channel for building streaming architectures and as a log-like data structure for persisting data. With ioredis, the usage can be pretty straightforward. Say we have a producer publishes messages to a stream with (You may find the official documentation of Streams as a starter to understand the parameters used), to consume the messages, we'll have a consumer with the following code: Expiration Redis can set a timeout to expire your key, after the timeout has expired the key will be automatically deleted. (You can find the official Expire documentation to understand better the different parameters you can use), to set your key to expire in 60 seconds, we will have the following code: Handle Binary Data Binary data support is out of the box. Pass buffers to send binary data: Every command that returns a bulk string has a variant command with a suffix. The variant command returns a buffer instead of a UTF-8 string: It's worth noticing that you don't need the suffix variant in order to **send** binary data. That means in most case you should just use instead of unless you want to get the old value with the parameter: Pipelining If you want to send a batch of commands (e.g. > 5), you can use pipelining to queue the commands in memory and then send them to Redis all at once. This way the performance improves by 50%~300% (See benchmark section). creates a instance. You can call any Redis commands on it just like the instance. The commands are queued in memory and flushed to Redis by calling the method: Each chained command can also have a callback, which will be invoked when the command gets a reply: In addition to adding commands to the queue individually, you can also pass an array of commands and arguments to the constructor: property shows how many commands in the pipeline: Transaction Most of the time, the transaction commands & are used together with pipeline. Therefore, when is called, a instance is created automatically by default, so you can use just like : If there's a syntax error in the transaction's comman…