@notross/redis-hub

A minimal connection hub for Redis in Node.js: lazily creates and reuses named Redis clients (e.g., publisher, subscriber, per-user, per-namespace) with centralized config and event tracking.

Features

• Single shared hub in your runtime (safe for multiple imports)
• Lazy instantiation: redisClient('publisher') creates on demand
• Event logging: ready, reconnecting, error, etc.
• Pub/Sub friendly: separate clients by role to avoid cross-use
• Single source of config (URI/options via defaults or per-client)

Installation

# NPM
npm install @notross/redis-hub

# Yarn
yarn add @notross/redis-hub

Quick Start

Redis client

import { redisHub, defaultClient } from "@notross/redis-hub";

// Initialize Redis Hub (optional but recommended)
redisHub.init({
  url: process.env.REDIS_URL,
});

// Use the default client without manual creation
await defaultClient().then((client) => {
  client.set('foo', 'bar');
  client.get('foo').then(console.log); // bar
})

Redis Pub/Sub

// redis.ts
import redisHub, { redisClient } from '@notross/redis-hub';

// Set global default options (optional)
redisHub.init({ url: process.env.REDIS_URL });

// Publisher
redisClient('publisher').then((pub) => pub.publish('my-channel', 'hello-world'));

// Subscriber
const sub = await redisClient('subscriber');
sub.subscribe('my-channel', (message) => {
  console.log('Received message:', message);
});

Default Client

In addition to named clients, Redis Hub exposes a default client for convenience.

Example: Key/Value

import { defaultClient } from "@notross/redis-hub";

defaultClient().then(async (client) => {
  await client.set('hello', 'world');
  client.get('hello').then(console.log) // "world"
});

Example: Pub/Sub

import { useClient } from "@notross/redis-hub";

const subscriber = useClient('subscriber');
const publisher = useClient('publisher');

// Subscribe (supports pSubscribe for patterns)
subscriber.then((client) => client.pSubscribe('chat*', (message, channel) => {
  console.log(`Message received on ${channel}: ${message}`);
}));

// Publish
publisher.publish('chat.room1', 'Hello, World!');

Notes

• The default client name is "default" unless overridden in init(...).
• Using multiple defaultClient() calls returns the same underlying client instance.
• You can still create additional named clients via redisHub.client("name") when needed.

API

redisClient(clientId: string, options?: RedisClientOptions): Promise<RedisClient>

Get or create a named Redis client.

• clientId — Logical name (e.g., "publisher", "user-123")
• options — Optional RedisClientOptions (only applied on first creation)

💡 Tip: Same clientId always returns the same connected client.

redisHub.init(options: RedisClientOptions): void

Sets default Redis connection options, used when no per-client options are provided.

redisHub.init({
  url: 'redis://localhost:6379'
});

redisHub.getClientById(clientId: string): RedisClient | null

Returns an existing connected client by ID (without creating it).

const pub = redisHub.getClientById('publisher');

redisHub.disconnectAll(): Promise<void>

Disconnects all active Redis clients and clears the hub.

await redisHub.disconnectAll();

redisHub.logs(): LogResult[]

Returns captured log entries (useful when logging is disabled).

const logs = redisHub.logs();

Event Logging

Every client automatically logs lifecycle events:

• connect
• ready
• reconnecting
• end
• error

You can disable or configure logging:

import { RedisHub } from '@notross/redis-hub';
const hub = new RedisHub({ logs: false });

Pub/Sub Best Practices

Because Redis doesn’t allow a single connection to both publish and subscribe without blocking, use distinct logical names:

const pub = await useClient('publisher');
const sub = await useClient('subscriber');

sub.subscribe('chat', (msg) => console.log('Received message:', msg));
pub.publish('chat', 'Hello!');

Config via Environment

Typical usage is to set REDIS_URL or REDIS_URI and apply it as default options:

redisHub.init({ url: process.env.REDIS_URL });

Example: Per-User Namespaced Clients

async function getUserClient(userId: string) {
  return redisClient(`user-${userId}`, {
    url: process.env.REDIS_URL
  });
}

const user123Client = await getUserClient('123');
await user123Client.set('lastLogin', Date.now());

License

MIT © @notross