redis-messaging

A lightweight, type-safe Redis Pub/Sub library for Node.js and TypeScript.

redis-messaging provides a simple abstraction over Redis Pub/Sub with a consistent API for publishing and subscribing to messages. It supports both simple payloads and structured messages with headers, making it suitable for event-driven applications, microservices, notifications, and lightweight messaging.

Examples:

redis-messaging: An example for a message processing pipeline with redis:

• Message transport
• Message processing
• Validation
• Retry
• Persistence

Features

• Lightweight wrapper around the official redis client
• Type-safe APIs
• Simple Publisher/Subscriber
• Structured Publisher/Subscriber with message headers
• Generic message types
• Pluggable serialization/deserialization
• Built-in Redis health checker
• Minimal dependencies
• Promise-based API
• Enterprise-friendly design

Installation

npm install redis redis-messaging

Quick Start

Connect to Redis

import { createClient } from "redis";

const client = createClient({
  url: "redis://localhost:6379",
});

await client.connect();

Simple Publisher

Publish plain objects without headers.

import { Publisher } from "redis-messaging";

interface UserCreated {
  id: string;
  name: string;
}

const publisher = new Publisher<UserCreated>(
  client,
  "users.created"
);

await publisher.publish({
  id: "1001",
  name: "John"
});

Simple Subscriber

import { Subscriber } from "redis-messaging";

interface UserCreated {
  id: string;
  name: string;
}

const subscriber = new Subscriber<UserCreated, void>(
  client,
  "users.created",
  console.error
);

await subscriber.subscribe(async (user) => {
  console.log(user.id);
  console.log(user.name);
});

Publisher with Headers

When additional metadata is required, use RedisPublisher.

import { RedisPublisher } from "redis-messaging";

const publisher = new RedisPublisher<UserCreated>(
  client,
  "users.created"
);

await publisher.publish(
  {
    id: "1001",
    name: "John"
  },
  {
    correlationId: "abc-123",
    source: "user-service"
  }
);

Subscriber with Headers

import { RedisSubscriber } from "redis-messaging";

const subscriber = new RedisSubscriber<UserCreated, void>(
  client,
  "users.created",
  console.log
);

await subscriber.subscribe(async (user, headers) => {

  console.log(user);

  console.log(headers?.correlationId);

  console.log(headers?.source);

});

Custom Serializer

You can replace the default JSON serializer.

const publisher = new Publisher<MyData>(
    client,
    "events",
    serialize
);

Example

function serialize(data: MyData): string {
    return JSON.stringify(data);
}

Custom Deserializer

const subscriber = new Subscriber<MyData, void>(
    client,
    "events",
    console.error,
    deserialize
);

function deserialize(message: string): MyData {
    return JSON.parse(message);
}

Message Format

RedisPublisher automatically wraps data into the following structure.

{
    data: T,
    headers?: {
        [key: string]: string
    }
}

Example

{
  "data": {
    "id": "1001",
    "name": "John"
  },
  "headers": {
    "correlationId": "abc-123",
    "source": "user-service"
  }
}

Health Check

RedisChecker provides a lightweight health check implementation suitable for Kubernetes, Docker, or monitoring systems.

import { RedisChecker } from "redis-messaging";

const checker = new RedisChecker(client);

const result = await checker.check();

Example

Map {
  "status" => "UP",
  "connected" => true,
  "responseTime" => 4
}

You can customize the service name and timeout.

const checker = new RedisChecker(
    client,
    "cache",
    3000
);

API

Publisher

class Publisher<T> {
    publish(data: T): Promise<number>;
}

RedisPublisher

class RedisPublisher<T> {
    publish(
        data: T,
        headers?: Record<string, string>
    ): Promise<number>;
}

Subscriber

class Subscriber<T, R> {
    subscribe(
        process: (data: T) => Promise<R>
    ): Promise<void>;
}

RedisSubscriber

class RedisSubscriber<T, R> {
    subscribe(
        process: (
            data: T,
            headers?: Record<string, string>
        ) => Promise<R>
    ): Promise<void>;
}

RedisChecker

class RedisChecker {
    check(): Promise<Map<string, any>>;
}

Architecture

                    Redis Server
                         ▲
                         │
                Redis Pub/Sub Channel
                         ▲
         ┌───────────────┴───────────────┐
         │                               │
  RedisPublisher<T>             RedisSubscriber<T>
         ▲                               │
         │                               ▼
     Publisher<T>                  Business Logic

Why redis-messaging?

Unlike using the Redis client directly, redis-messaging provides:

• Strong typing
• Cleaner APIs
• Header support
• Pluggable serialization
• Consistent programming model
• Built-in health checking
• Enterprise-ready abstractions

Use Cases

• Event-driven architecture
• Internal microservice communication
• Notification systems
• Cache invalidation events
• Lightweight messaging
• Background workers
• Real-time updates

Limitations

redis-messaging is built on Redis Pub/Sub.

Redis Pub/Sub is designed for lightweight messaging and has the following characteristics:

• No message persistence
• No acknowledgements
• No retries
• No dead-letter queue
• Subscribers only receive messages while connected

If durable messaging is required, consider technologies such as Kafka, RabbitMQ, ActiveMQ, or Redis Streams.

Requirements

• Node.js 18+
• Redis 6+
• TypeScript 5+

License

MIT