ioredis

A robust, performance-focused and full-featured Redis client for Node.js.

weekly downloads12.6M

versionv5.9.3

licenseMIT

categorybackend

redisclustersentinelpipelining

Overview

ioredis is a full-featured Redis client designed for production Node.js applications requiring reliable, high-performance access to Redis instances. It provides complete implementation of Redis commands with TypeScript type definitions, native Promise support, and advanced features like clustering, Sentinel management, and pipelining that make it suitable for distributed systems.

The package was created to address limitations in earlier Redis clients, particularly around cluster support, modern JavaScript patterns, and developer experience. It handles complex scenarios like automatic failover, connection pooling, and offline command queueing while maintaining a clean API that works with both callbacks and async/await syntax. The client is written in TypeScript, providing strong type safety and autocomplete support in modern editors.

With over 12 million weekly downloads, ioredis is widely adopted in production environments ranging from small services to large-scale distributed systems. It's particularly popular among teams building microservices architectures, real-time applications, caching layers, and session management systems where Redis serves as the primary data store or cache. The library supports Redis 2.6.12 and above, covering both legacy deployments and modern Redis features like Streams and GEO commands.

Quick Start

typescript

const Redis = require('ioredis');

// Basic connection
const redis = new Redis({
  host: '127.0.0.1',
  port: 6379,
  retryStrategy: (times) => {
    const delay = Math.min(times * 50, 2000);
    return delay;
  }
});

// Async/await usage
async function cacheUser(userId, userData) {
  await redis.setex(`user:${userId}`, 3600, JSON.stringify(userData));
  const cached = await redis.get(`user:${userId}`);
  return JSON.parse(cached);
}

// Pipelining for batch operations
async function batchUpdate(userIds) {
  const pipeline = redis.pipeline();
  userIds.forEach(id => {
    pipeline.incr(`user:${id}:visits`);
    pipeline.sadd('active_users', id);
  });
  const results = await pipeline.exec();
  return results;
}

// Pub/Sub
const subscriber = new Redis();
subscriber.subscribe('notifications', (err, count) => {
  console.log(`Subscribed to ${count} channels`);
});

subscriber.on('message', (channel, message) => {
  console.log(`Received from ${channel}: ${message}`);
});

redis.publish('notifications', 'Hello from ioredis');

// Custom Lua script command
redis.defineCommand('incrementIfExists', {
  numberOfKeys: 1,
  lua: 'if redis.call("exists", KEYS[1]) == 1 then return redis.call("incr", KEYS[1]) else return nil end'
});

async function conditionalIncrement(key) {
  const result = await redis.incrementIfExists(key);
  return result;
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await redis.quit();
  await subscriber.quit();
});

Use Cases

Distributed caching with Redis Cluster: Applications requiring horizontal scaling can use ioredis to connect to Redis Cluster deployments, with automatic slot calculation, node discovery, and transparent failover when nodes go down. The client handles resharding and automatically routes commands to the correct cluster nodes.

High-availability session storage with Sentinel: Web applications using Redis Sentinel for automatic failover can leverage ioredis to monitor master/replica topology changes, automatically reconnecting to the new master when failover occurs without manual intervention or application restarts.

Real-time pub/sub messaging: Building chat systems, notification services, or event-driven architectures where ioredis handles Redis Pub/Sub with support for binary messages, pattern subscriptions, and proper connection management for long-lived subscriber connections.

Lua script abstraction for atomic operations: Complex operations requiring atomicity can be implemented as Lua scripts with ioredis's defineCommand method, which automatically handles script loading, caching, and execution with proper argument serialization.

Optimized batch operations with pipelining: Applications processing large volumes of Redis commands can use pipelining or automatic pipelining features to batch multiple commands into single network round-trips, significantly improving throughput for bulk operations like cache warming or data migrations.

Pros & Cons

Pros

+Comprehensive feature set including clustering, Sentinel, Lua scripting, and all modern Redis commands with TypeScript definitions
+Excellent connection handling with automatic reconnection, offline queueing, and configurable retry strategies for production resilience
+Native Promise support with clean async/await patterns while maintaining backward compatibility with callbacks
+Active maintenance and strong community adoption with over 12 million weekly downloads and regular updates
+Performance optimizations like automatic pipelining and connection pooling built-in

Cons

−Larger bundle size compared to minimal Redis clients due to comprehensive feature set and TypeScript compilation
−Cluster and Sentinel configurations can be complex for developers unfamiliar with Redis topology management
−Memory overhead from connection pooling and command queueing may be excessive for simple, low-traffic use cases

Alternatives

redisv5.11.0

A modern, high performance Redis client

databaseredis

7.4M / week

Comparisons

@upstash/redis vs ioredis

database

Install

bash

npm install ioredis

bash

pnpm add ioredis

bash

bun add ioredis

Overview

Quick Start

typescript

const Redis = require('ioredis');

// Basic connection
const redis = new Redis({
  host: '127.0.0.1',
  port: 6379,
  retryStrategy: (times) => {
    const delay = Math.min(times * 50, 2000);
    return delay;
  }
});

// Async/await usage
async function cacheUser(userId, userData) {
  await redis.setex(`user:${userId}`, 3600, JSON.stringify(userData));
  const cached = await redis.get(`user:${userId}`);
  return JSON.parse(cached);
}

// Pipelining for batch operations
async function batchUpdate(userIds) {
  const pipeline = redis.pipeline();
  userIds.forEach(id => {
    pipeline.incr(`user:${id}:visits`);
    pipeline.sadd('active_users', id);
  });
  const results = await pipeline.exec();
  return results;
}

// Pub/Sub
const subscriber = new Redis();
subscriber.subscribe('notifications', (err, count) => {
  console.log(`Subscribed to ${count} channels`);
});

subscriber.on('message', (channel, message) => {
  console.log(`Received from ${channel}: ${message}`);
});

redis.publish('notifications', 'Hello from ioredis');

// Custom Lua script command
redis.defineCommand('incrementIfExists', {
  numberOfKeys: 1,
  lua: 'if redis.call("exists", KEYS[1]) == 1 then return redis.call("incr", KEYS[1]) else return nil end'
});

async function conditionalIncrement(key) {
  const result = await redis.incrementIfExists(key);
  return result;
}

// Graceful shutdown
process.on('SIGTERM', async () => {
  await redis.quit();
  await subscriber.quit();
});

Use Cases

Pros & Cons

Pros

+Comprehensive feature set including clustering, Sentinel, Lua scripting, and all modern Redis commands with TypeScript definitions
+Excellent connection handling with automatic reconnection, offline queueing, and configurable retry strategies for production resilience
+Native Promise support with clean async/await patterns while maintaining backward compatibility with callbacks
+Active maintenance and strong community adoption with over 12 million weekly downloads and regular updates
+Performance optimizations like automatic pipelining and connection pooling built-in

Cons

−Larger bundle size compared to minimal Redis clients due to comprehensive feature set and TypeScript compilation
−Cluster and Sentinel configurations can be complex for developers unfamiliar with Redis topology management
−Memory overhead from connection pooling and command queueing may be excessive for simple, low-traffic use cases