CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ioredis

A robust, performance-focused and full-featured Redis client for Node.js with TypeScript support, clustering, sentinel management, and comprehensive Redis command coverage.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

ioredis

ioredis is a robust, performance-focused, and full-featured Redis client for Node.js written in TypeScript. It provides complete Redis command support, clustering capabilities, sentinel management, and advanced features like pipelining, pub/sub, and Lua scripting with strong type safety.

Package Information

  • Package Name: ioredis
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ioredis

Core Imports

import Redis from "ioredis";
import { Cluster } from "ioredis";

For CommonJS:

const Redis = require("ioredis");
const { Cluster } = Redis;

Basic Usage

import Redis from "ioredis";

// Connect to Redis
const redis = new Redis(); // defaults to localhost:6379

// Basic operations
await redis.set("key", "value");
const value = await redis.get("key");

// Using with configuration
const redis2 = new Redis({
  host: "redis.example.com",
  port: 6380,
  password: "secret",
  db: 1,
});

// Redis Cluster
import { Cluster } from "ioredis";

const cluster = new Cluster([
  { host: "127.0.0.1", port: 7000 },
  { host: "127.0.0.1", port: 7001 },
]);

await cluster.set("key", "value");

Architecture

ioredis is built around several key components:

  • Redis Client: Main client class supporting standalone Redis and Sentinel configurations
  • Cluster Client: Specialized client for Redis Cluster deployments with automatic slot management
  • Command System: Comprehensive Redis command interface with TypeScript typing
  • Connection Management: Robust connection handling with reconnection, retries, and pooling
  • Pipeline System: Command batching for performance optimization
  • Pub/Sub System: Full publish/subscribe support including pattern subscriptions
  • Event System: EventEmitter-based architecture for connection lifecycle management

Capabilities

Redis Client

Core Redis client for connecting to standalone Redis servers or Sentinel-managed deployments. Supports all Redis commands with full TypeScript typing.

class Redis extends EventEmitter {
  constructor();
  constructor(port: number);
  constructor(path: string);
  constructor(options: RedisOptions);
  constructor(port: number, options: RedisOptions);
  constructor(port: number, host: string);
  constructor(port: number, host: string, options: RedisOptions);
  constructor(path: string, options: RedisOptions);
  
  connect(callback?: Callback<void>): Promise<void>;
  quit(callback?: Callback<"OK">): Promise<"OK">;
  duplicate(override?: Partial<RedisOptions>): Redis;
}

Redis Client

Cluster Client

Redis Cluster client with automatic slot management, node discovery, and failover handling.

class Cluster extends EventEmitter {
  constructor(startupNodes: ClusterNode[], options?: ClusterOptions);
  
  connect(): Promise<void>;
  quit(callback?: Callback<"OK">): Promise<"OK">;
  nodes(role?: NodeRole): Redis[];
  refreshSlotsCache(callback?: Callback<void>): void;
}

type ClusterNode = string | number | {
  host?: string;
  port?: number;
};

Cluster Operations

Configuration Options

Comprehensive configuration interfaces for Redis connections including network settings, behavior options, and advanced features.

interface RedisOptions {
  host?: string;
  port?: number;
  password?: string;
  db?: number;
  retryStrategy?: (times: number) => number | void | null;
  enableAutoPipelining?: boolean;
  maxRetriesPerRequest?: number | null;
  // ... extensive additional options
}

interface ClusterOptions extends Partial<RedisOptions> {
  clusterRetryStrategy?: (times: number, reason?: Error) => number | void | null;
  scaleReads?: NodeRole | Function;
  maxRedirections?: number;
  // ... additional cluster-specific options
}

Configuration

Command Execution

Complete Redis command interface with promise-based returns, callback support, and proper TypeScript typing for all Redis operations.

// String operations
get(key: RedisKey): Promise<string | null>;
set(key: RedisKey, value: RedisValue): Promise<"OK">;
set(key: RedisKey, value: RedisValue, expiryMode: "EX", time: number): Promise<"OK">;

// Hash operations  
hget(key: RedisKey, field: string): Promise<string | null>;
hset(key: RedisKey, field: string, value: RedisValue): Promise<number>;

// List operations
lpush(key: RedisKey, ...values: RedisValue[]): Promise<number>;
lrange(key: RedisKey, start: number, stop: number): Promise<string[]>;

Redis Commands

Pipelining & Transactions

Efficient command batching and atomic transaction support with MULTI/EXEC operations.

pipeline(commands?: unknown[][]): ChainableCommander;
multi(options?: { pipeline?: boolean }): ChainableCommander | Promise<"OK">;

interface ChainableCommander {
  exec(callback?: Callback): Promise<Array<[Error | null, any]>>;
  // All Redis commands available for chaining
}

Pipelining & Transactions

Pub/Sub Messaging

Complete publish/subscribe support including pattern subscriptions and message handling.

subscribe(...channels: string[]): Promise<number>;
unsubscribe(...channels: string[]): Promise<number>;
psubscribe(...patterns: string[]): Promise<number>;
publish(channel: string, message: string): Promise<number>;

// Event handlers
on(event: 'message', listener: (channel: string, message: string) => void): this;
on(event: 'pmessage', listener: (pattern: string, channel: string, message: string) => void): this;

Pub/Sub Messaging

Streaming Operations

Readable streams for efficient scanning of large datasets using Redis SCAN operations.

scanStream(options?: ScanStreamOptions): ScanStream;
sscanStream(key: string, options?: ScanStreamOptions): ScanStream;
hscanStream(key: string, options?: ScanStreamOptions): ScanStream;
zscanStream(key: string, options?: ScanStreamOptions): ScanStream;

interface ScanStreamOptions {
  match?: string;
  count?: number;
  type?: string;
}

class ScanStream extends Readable {
  close(): void;
}

Streaming

Lua Scripting

Define custom Redis commands using Lua scripts with automatic script caching and EVAL/EVALSHA optimization.

defineCommand(
  name: string,
  definition: {
    lua: string;
    numberOfKeys?: number;
    readOnly?: boolean;
  }
): void;

// Built-in scripting commands
eval(script: string, numKeys: number, ...keysAndArgs: any[]): Promise<any>;
evalsha(sha: string, numKeys: number, ...keysAndArgs: any[]): Promise<any>;
script(subcommand: "LOAD" | "EXISTS" | "FLUSH" | "KILL", ...args: any[]): Promise<any>;

Usage Examples:

import Redis from "ioredis";

const redis = new Redis();

// Define a custom command
redis.defineCommand("myecho", {
  numberOfKeys: 1,
  lua: "return KEYS[1] .. ARGV[1]",
});

// Use the custom command (TypeScript will provide typing)
const result = await redis.myecho("key", "value"); // Returns "keyvalue"

// Define command via constructor options (see Configuration docs)
const redis2 = new Redis({
  scripts: {
    increment: {
      lua: `
        local key = KEYS[1]
        local limit = tonumber(ARGV[1])
        local current = redis.call('GET', key) or 0
        if tonumber(current) < limit then
          return redis.call('INCR', key)
        else
          return current
        end
      `,
      numberOfKeys: 1,
    }
  }
});

Configuration

Core Types

type RedisKey = string | Buffer;
type RedisValue = string | Buffer | number;
type NodeRole = "master" | "slave" | "all";
type Callback<T> = (err?: Error | null, result?: T) => void;

interface SentinelAddress {
  host: string;
  port: number;
}

interface ClusterNode {
  host?: string;
  port?: number;
}

type NatMapFunction = (key: string) => { host: string; port: number } | null;
type NatMap = {
  [key: string]: { host: string; port: number };
} | NatMapFunction;

type DNSLookupFunction = (
  hostname: string,
  callback: (err: NodeJS.ErrnoException | null | undefined, address: string, family?: number) => void
) => void;

type DNSResolveSrvFunction = (
  hostname: string,
  callback: (err: NodeJS.ErrnoException | null | undefined, records?: any[]) => void
) => void;

// Utility function for debugging Redis responses
function print(err: Error | null, reply?: any): void;

// ReplyError is imported from redis-errors package
const ReplyError: typeof import("redis-errors").ReplyError;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ioredis@5.7.x
Publish Source
CLI
Badge
tessl/npm-ioredis badge