ioredis

ioredis is a battle-tested Redis client for Node.js, originally created by Zihua Li at Alibaba and now maintained by the Redis team. It ships as a single TypeScript codebase with minimal, single-purpose runtime dependencies, exposing nearly every Redis command as a same-named Promise-returning method while still supporting the classic Node.js callback style.

Beyond basic get/set operations, ioredis provides first-class support for Redis Cluster and Sentinel-based high availability, transparent pipelining and autopipelining for throughput, MULTI/EXEC transactions, Lua scripting with automatic script caching, binary-safe Pub/Sub, and TLS. It has powered production traffic at large-scale deployments for a decade and remains one of the two most widely used Node.js Redis clients alongside node-redis.

What You Get

• Complete Redis command coverage exposed as Promise- and callback-based methods matching the official command names
• Native support for Redis Cluster (slot routing, MOVED/ASK redirection) and Sentinel-based automatic failover
• Pipelining, autopipelining, and MULTI/EXEC transactions for batching and atomic operations
• A Lua scripting abstraction (defineCommand) with automatic EVALSHA caching
• First-class TypeScript declarations, TLS support, and binary-safe Pub/Sub

Common Use Cases

• Caching layer in front of a primary database to cut read latency and DB load
• Session storage and rate-limiting counters for web APIs
• Distributed locks, leaderboards, and real-time counters built on Redis data structures
• Backing store for Pub/Sub messaging or lightweight job queues on Redis Streams/Lists

Under The Hood

Architecture - The Redis class (lib/Redis.ts, ~1,050 lines) extends a Commander mixin that generates a method per Redis command from the @ioredis/commands metadata table. Connection lifecycle is delegated to pluggable connectors (StandaloneConnector for direct connections, SentinelConnector for HA failover) and driven through explicit states (wait -> connecting -> connect -> ready -> close -> end) via lib/redis/event_handler.ts. Commands are serialized and matched to replies by Command.ts (~615 lines) working with DataHandler.ts (~295 lines), which parses the raw socket byte stream with redis-parser and resolves pending commands off a Deque-backed queue. Cluster support is a parallel implementation (lib/cluster/index.ts, ~1,260 lines) that wraps a pool of per-node Redis instances, handles MOVED/ASK redirection, and computes slot ownership via cluster-key-slot. Pipelining and transactions (Pipeline.ts, transaction.ts) and Lua script caching (Script.ts) are layered on top of this core, and autoPipelining.ts transparently batches same-tick commands into a single round trip.

Tech Stack - 100% TypeScript (98.7% of the codebase by bytes), compiled with tsc into a built/ directory that is the package’s actual entry point. Runtime dependencies are deliberately minimal and single-purpose: @ioredis/commands (command metadata/flags), redis-parser (RESP protocol parsing), redis-errors, cluster-key-slot (CRC16 slot hashing), denque (queue for pending commands), debug (namespaced logging), and standard-as-callback (dual promise/callback API). No framework dependencies. Targets Node.js >=12.22.0 and is compatible with Redis 2.6.12 through the latest 7.x/8.x releases.

Code Quality - 111 test files spread across a genuinely three-tiered strategy: test/unit for isolated logic, test/functional for command-by-command tests run against a real Redis server, test/cluster for Docker Compose-backed Cluster/Sentinel scenarios, and test/typing for tsd compile-time type assertions. ESLint extends eslint:recommended plus @typescript-eslint/recommended and prettier; coverage is tracked with nyc and reported to Coveralls. Error handling is centralized through the redis-errors package and a configurable ReconnectOnError policy. Releases are gated on the test suite and driven by semantic-release with commitizen-style conventional commits.

API Design - new Redis() connects to localhost:6379 with zero configuration, and every Redis command is exposed as a same-named method returning a Promise (Node-style callbacks are also supported via standard-as-callback), so the public API mirrors the Redis command reference almost 1:1. Chained .pipeline()/.multi() builders give fluent batch and transaction ergonomics, and defineCommand abstracts away hand-rolled EVALSHA caching for custom Lua scripts. A 69KB README covers connection options, Cluster/Sentinel setup, TLS, and scripting, backed by a generated TypeDoc API reference and a dedicated examples/ directory (including TypeScript and Express samples) — a fairly gentle learning curve for a low-level client, docked slightly by the inherent complexity of Cluster/Sentinel configuration.