RedisConnectionFactory

Overview

RedisConnectionFactory is a static factory class that creates Redis connections in either single-node or cluster mode. It abstracts the differences between RedisHelper (single) and RedisClusterHelper (cluster) behind the common DefaultRedisHelper interface from IGNIS, allowing downstream code to work with either mode transparently.

Property	Value
Source	packages/core/src/helpers/redis/redis-connection.factory.ts
Extends	BaseHelper (from @venizia/ignis)
Returns	DefaultRedisHelper (common interface for RedisHelper and RedisClusterHelper)

API

RedisConnectionFactory.create()

Creates a Redis connection based on the provided mode.

static create(opts: TRedisConnectionOptions): DefaultRedisHelper

Parameter	Type	Required	Description
opts	TRedisConnectionOptions	Yes	Connection options (single or cluster)

Returns: DefaultRedisHelper -- either a RedisHelper or RedisClusterHelper instance.

Throws: Error if an invalid mode is provided.

RedisConnectionFactory.parseClusterNodes()

Parses a comma-separated string of host:port pairs into an array of node objects. Intended for reading cluster node lists from environment variables.

static parseClusterNodes(opts: { raw: string }): Array<{ host: string; port: number }>

Parameter	Type	Required	Description
opts.raw	string	Yes	Comma-separated string, e.g. "node1:6379,node2:6380,node3:6381"

Returns: Array of { host, port } objects. Defaults port to 6379 if parsing fails.

Type Interfaces

IRedisConnectionSingleOptions

Options for creating a single-node Redis connection.

interface IRedisConnectionSingleOptions {
  mode?: typeof RedisModes.SINGLE;  // 'single' (default when omitted)
  name: string;
  host?: string;        // Default: 'localhost'
  port?: number;        // Default: 6379
  password?: string;
  database?: number;    // Default: 0
  maxRetry?: number;    // Default: 5
  autoConnect?: boolean; // Default: false
}

Field	Type	Default	Description
mode	'single'	'single'	Connection mode identifier
name	string	--	Connection name for logging and identification
host	string	'localhost'	Redis server hostname
port	number	6379	Redis server port
password	string	--	Redis authentication password
database	number	0	Redis database index
maxRetry	number	5	Maximum reconnection attempts
autoConnect	boolean	false	Connect immediately on creation

IRedisConnectionClusterOptions

Options for creating a Redis cluster connection.

interface IRedisConnectionClusterOptions {
  mode: typeof RedisModes.CLUSTER;  // 'cluster' (required)
  name: string;
  nodes: Array<{ host: string; port: number }>;
  password?: string;
}

Field	Type	Default	Description
mode	'cluster'	--	Must be 'cluster'
name	string	--	Connection name for logging and identification
nodes	Array<{ host, port }>	--	List of cluster seed nodes
password	string	--	Redis authentication password (applied to all nodes)

TRedisConnectionOptions

Union type of both option interfaces:

type TRedisConnectionOptions = IRedisConnectionSingleOptions | IRedisConnectionClusterOptions;

Behavior by Mode

Single Mode

Creates a RedisHelper instance with the provided options. This is the default when mode is omitted.

const redis = RedisConnectionFactory.create({
  name: 'my-cache-redis',
  host: 'localhost',
  port: 6379,
  database: 0,
  maxRetry: 5,
});

Internally produces:

new RedisHelper({
  name: 'my-cache-redis',
  host: 'localhost',
  port: 6379,
  password: undefined,
  database: 0,
  maxRetry: 5,
  autoConnect: false,
});

Cluster Mode

Creates a RedisClusterHelper instance with sharded subscribers enabled, lazy connection, and offline queue support.

const redis = RedisConnectionFactory.create({
  mode: 'cluster',
  name: 'my-cache-cluster',
  nodes: [
    { host: 'node1', port: 6379 },
    { host: 'node2', port: 6379 },
    { host: 'node3', port: 6379 },
  ],
  password: 'secret',
});

Internally produces:

new RedisClusterHelper({
  name: 'my-cache-cluster',
  nodes: [
    { host: 'node1', port: 6379 },
    { host: 'node2', port: 6379 },
    { host: 'node3', port: 6379 },
  ],
  clusterOptions: {
    redisOptions: { password: 'secret' },
    shardedSubscribers: true,
    lazyConnect: true,
    enableOfflineQueue: true,
  },
});

Cluster Mode Options

Cluster Option	Value	Description
shardedSubscribers	true	Uses sharded pub/sub for Redis 7+ cluster subscriptions
lazyConnect	true	Does not connect until the first command is issued
enableOfflineQueue	true	Queues commands while the connection is being established

Usage in Downstream Packages

Seven packages use RedisConnectionFactory to create WebSocket emitter connections:

Typical Component Usage

The pattern used by every package's ApplicationWebSocketComponent:

import { EnvironmentKeys, RedisConnectionFactory, RedisModes } from '@nx/core';
import { applicationEnvironment, WebSocketEmitter } from '@venizia/ignis';

export class ApplicationWebSocketComponent extends BaseComponent {
  override async binding(): Promise<void> {
    const mode =
      applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_MODE) ??
      RedisModes.SINGLE;

    const redis =
      mode === RedisModes.CLUSTER
        ? this._createClusterRedis()
        : this._createSingleRedis();

    const emitter = new WebSocketEmitter({
      identifier: 'sale-ws-emitter',
      redisConnection: redis,
    });

    this.application.bind({ key: MyBindingKeys.WEBSOCKET_EMITTER }).toValue(emitter);
    this.application.service(MySocketEventService);
  }

  private _createSingleRedis() {
    return RedisConnectionFactory.create({
      mode: 'single',
      name: applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_IDENTIFIER)
        ?? 'my-ws-redis',
      host: applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_HOST)
        ?? 'localhost',
      port: int(applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_PORT))
        ?? 6379,
      password: applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_PASSWORD),
      database: int(applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_DB))
        ?? 0,
      maxRetry: int(applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_MAX_RETRY))
        ?? 5,
    });
  }

  private _createClusterRedis() {
    const clusterNodesStr = applicationEnvironment.get<string>(
      EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES,
    );

    if (!clusterNodesStr) {
      throw getError({ message: 'Missing cluster nodes env var' });
    }

    return RedisConnectionFactory.create({
      mode: 'cluster',
      name: applicationEnvironment.get(
        EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_CLUSTER_IDENTIFIER,
      ) ?? 'my-ws-redis-cluster',
      nodes: RedisConnectionFactory.parseClusterNodes({ raw: clusterNodesStr }),
      password: applicationEnvironment.get(EnvironmentKeys.APP_ENV_WEBSOCKET_REDIS_PASSWORD),
    });
  }
}

Environment Variables

Variable	Used For	Example
APP_ENV_WEBSOCKET_REDIS_MODE	Select single or cluster	single
APP_ENV_WEBSOCKET_REDIS_HOST	Single mode hostname	localhost
APP_ENV_WEBSOCKET_REDIS_PORT	Single mode port	6379
APP_ENV_WEBSOCKET_REDIS_PASSWORD	Authentication (both modes)	secret
APP_ENV_WEBSOCKET_REDIS_DB	Single mode database index	0
APP_ENV_WEBSOCKET_REDIS_MAX_RETRY	Single mode retry count	5
APP_ENV_WEBSOCKET_REDIS_CLUSTER_NODES	Cluster mode node list	node1:6379,node2:6379

Related Resources

• IGNIS Redis Helper -- RedisHelper and RedisClusterHelper implementation details
• IGNIS WebSocket Setup -- WebSocket component using Redis for scaling
• BaseSocketEventService -- Service that consumes the emitter created with this factory
• Signal Package -- Uses RedisConnectionFactory for WebSocket and pub/sub Redis connections