Core Module

The foundation of NestJS RedisX providing Redis client management with driver abstraction.

What is Core?

@nestjs-redisx/core is the foundation package that provides:

• RedisModule — NestJS module for Redis integration
• RedisService — High-level Redis operations wrapper
• Driver Abstraction — Switch between ioredis and node-redis
• Multi-Client Support — Manage multiple Redis connections
• Connection Types — Single, Cluster, and Sentinel configurations
• Health Monitoring — Automatic reconnection and health checks
• Plugin System — Extensible architecture for plugins

Installation

ioredis

npm install @nestjs-redisx/core ioredis

node-redis

npm install @nestjs-redisx/core redis

Quick Start

import { Module } from '@nestjs/common';
import { RedisModule } from '@nestjs-redisx/core';

@Module({
  imports: [
    RedisModule.forRoot({
      clients: {
        host: 'localhost',
        port: 6379,
      },
    }),
  ],
})
export class AppModule {}

Use in services:

import { Injectable } from '@nestjs/common';
import { RedisService } from '@nestjs-redisx/core';
import { User } from './types';

@Injectable()
export class UserService {
  constructor(private readonly redis: RedisService) {}

  async cacheUser(id: string, user: User): Promise<void> {
    await this.redis.set(`user:${id}`, JSON.stringify(user), { ex: 3600 });
  }

  async getUser(id: string): Promise<User | null> {
    const data = await this.redis.get(`user:${id}`);
    return data ? JSON.parse(data) : null;
  }
}

Architecture

Key Features

Feature	Description
Global Module	Import once, use everywhere
Lazy Connection	Connects on first use
Auto Reconnection	Exponential backoff with jitter
Health Checks	Monitor connection status
Multiple Clients	Named connections for different purposes
Driver Agnostic	Switch drivers without code changes
Type Safe	Full TypeScript support

Module Configuration

Synchronous

RedisModule.forRoot({
  clients: {
    host: 'localhost',
    port: 6379,
    password: 'secret',
  },
})

Asynchronous

RedisModule.forRootAsync({
  useFactory: (config: ConfigService) => ({
    clients: {
      host: config.get('REDIS_HOST'),
      port: config.get('REDIS_PORT'),
    },
  }),
  inject: [ConfigService],
})

With Plugins

import { CachePlugin } from '@nestjs-redisx/cache';
import { LocksPlugin } from '@nestjs-redisx/locks';

RedisModule.forRoot({
  clients: { host: 'localhost', port: 6379 },
  plugins: [
    new CachePlugin(),
    new LocksPlugin(),
  ],
})

Connection Types

Single Instance

{
  clients: {
    type: 'single',  // Optional, default
    host: 'localhost',
    port: 6379,
  }
}

Redis Cluster

{
  clients: {
    type: 'cluster',
    nodes: [
      { host: 'node1', port: 6379 },
      { host: 'node2', port: 6379 },
      { host: 'node3', port: 6379 },
    ],
  }
}

Redis Sentinel

{
  clients: {
    type: 'sentinel',
    sentinels: [
      { host: 'sentinel1', port: 26379 },
      { host: 'sentinel2', port: 26379 },
    ],
    name: 'mymaster',
  }
}

Documentation

• Configuration — Complete configuration reference
• RedisService — Service API documentation
• Multiple Clients — Named client management
• Connection Types — Single, Cluster, Sentinel
• Health Monitoring — Health checks and reconnection
• Decorators — @InjectRedis usage
• Driver Abstraction — ioredis vs node-redis
• Plugin System — Plugin architecture with lifecycle hooks
• Error Handling — Structured error system with error codes
• Troubleshooting — Common issues and solutions