Node-Redis

Node-Redis (published to npm as redis) is the official Node.js client for Redis, maintained by Redis, Inc. and the community that built the RESP2/RESP3 wire protocol implementation. It exposes every out-of-the-box Redis command through both raw uppercase names (HSET, HGETALL) and friendlier camelCase equivalents (hSet, hGetAll), transforms replies into useful JavaScript data structures, and supports Buffers for binary payloads.

Beyond the core command set, it ships built-in connection pooling via RedisClientPool, cluster and Sentinel topology support, multi/exec transactions with optimistic locking (WATCH), Pub/Sub, scan iterators, client-side caching (RESP3), auto-pipelining within a tick, and modular support for Redis Stack capabilities (JSON, Search, Bloom filters, Time-Series) through companion @redis/* packages bundled together under the umbrella redis package.

What You Get

• A RedisClient with every Redis command as a typed method (raw and camelCase forms), plus sendCommand() for anything not yet wrapped
• RedisClientPool for managing a pool of connections instead of hand-rolling an isolation pool
• First-class Redis Cluster and Sentinel clients with the same command surface as the standalone client
• Multi/exec transactions with WATCH-based optimistic locking, plus Lua scripting and Redis Functions support
• Pub/Sub, SCAN/HSCAN/SSCAN/ZSCAN async iterators, and RESP3 client-side caching with configurable TTL/eviction
• Modular Redis Stack support (@redis/json, @redis/search, @redis/bloom, @redis/time-series, @redis/entraid) bundled through the single redis package
• OpenTelemetry metrics/tracing integration and Microsoft Entra ID token-based authentication

Common Use Cases

• Caching layer in front of a primary database, using SET/GET with EX/NX options or client-side caching to cut round trips
• Session storage for web applications, often paired with Sentinel or Cluster for high availability
• Pub/Sub messaging and lightweight event fan-out between Node.js services
• Rate limiting and counters via atomic INCR/EXPIRE combinations or Lua scripts
• Full-text search, JSON documents, probabilistic data structures (Bloom filters), and time-series data through the bundled Redis Stack modules

Under The Hood

Architecture - The @redis/client package (bundled under the redis umbrella) is built around a RedisClient that composes a RedisSocket (raw TCP/TLS/Unix socket handling), a Decoder/Encoder pair implementing the RESP2/RESP3 wire protocol (lib/RESP/), and a RedisCommandsQueue that pipelines outgoing commands and resolves replies as they arrive. Commands are generated from per-command modules under lib/commands/ and attached to the client via a shared commander.ts that wires up argument transformers and reply parsers; the same command table is reused by RedisClientMultiCommand (transactions), RedisCluster (topology-aware routing across lib/cluster/), and Sentinel support (lib/sentinel/), so cluster/Sentinel/pool clients all share one source of truth for command behavior instead of re-implementing it.

Tech Stack - Written entirely in TypeScript (95% of the codebase) targeting Node.js >= 20, with a minimal runtime dependency footprint (cluster-key-slot for cluster key routing) and optional peer dependencies (@opentelemetry/api for tracing/metrics, @node-rs/xxhash for local digest hashing in CAS operations). The monorepo uses npm workspaces to publish the umbrella redis package alongside standalone @redis/client, @redis/json, @redis/search, @redis/bloom, @redis/time-series, and @redis/entraid packages, built with tsc --build and tested with Mocha/nyc.

Code Quality - The client package has 435 spec files against 478 non-spec TypeScript files, indicating close to one test per implementation file, plus a separate test:types step that compiles against tsconfig.types-test.json to catch type-level regressions. Error handling is modeled as a set of dedicated error classes (ClientClosedError, WatchError, ConnectionTimeoutError, SocketTimeoutError, etc. in lib/errors.ts) rather than generic thrown strings, which makes failure modes catchable and distinguishable by callers. Naming is consistent throughout (raw Redis command names alongside camelCase aliases, *Error suffix for error classes, *Options/*Config suffix for config objects), and the RESP decoder is explicitly annotated (// @ts-nocheck -- decoder uses untyped continuation callbacks) where hand-optimized hot-path code trades strict typing for performance, showing deliberate, documented tradeoffs rather than accidental gaps.

API Design - The client exposes both raw uppercase Redis command names (HSET, HGETALL) and friendlier camelCase equivalents (hSet, hGetAll) on the same object, so users familiar with Redis’s own command reference can transfer that knowledge directly while still getting idiomatic JavaScript naming. Getting started requires a single createClient().connect() call with no boilerplate configuration, replies are auto-transformed into useful structures (e.g. HGETALL returns a plain object), and advanced features like transactions, client-side caching, and connection pools are opt-in via clearly named constructors (.multi(), createClientPool()) rather than being forced into the base API.