Redis Client

Redis Client is a lightweight, type-safe wrapper for ioredis. It solves the problem of scaling Redis infrastructure by automatically routing Write operations to a Primary node and Read operations to Replica nodes.

📑 Table of Contents

• Features
• Prerequisites
• Installation
• Usage
• Configuration
• Architecture
• Running Tests
• Contributing
• License

✨ Features

• Automatic Traffic Splitting: Writes (set, del, expire) are sent to the Primary; Reads (get, scan, hget, keys) are sent to Replicas.
• Type Safety: Built with TypeScript, providing full IntelliSense and type checking out of the box.
• Performance: Offloads expensive read operations (like SCAN) from your Master node to prevent blocking critical write traffic.
• Flexible Access: Exposes the underlying ioredis instances if you need to run custom or unsupported commands.

🔧 Prerequisites

Before you begin, ensure you have met the following requirements:

• Node.js (v14 or higher)
• Redis: A Redis setup with at least one Master and one Replica (e.g., AWS ElastiCache Cluster Mode Disabled).

🚀 Installation

1. Install the package and the peer dependency:

   npm install @heady/redis-client

💡 Usage

import { RedisClient } from '@heady/redis-client';

// 1. Initialize with separate endpoints
const redis = new RedisClient({
  primary: {
    host: 'primary-node.redis.aws.internal',
    port: 6379,
  },
  replica: {
    host: 'replica-node.redis.aws.internal',
    port: 6379,
  }
});

async function main() {
  // ✍️ WRITE: Automatically routed to Primary
  await redis.set('user:101', 'John Doe', 3600); 
  console.log('User saved to Primary node');

  // 📖 READ: Automatically routed to Replica
  const user = await redis.get('user:101');
  console.log('User read from Replica node:', user);

  // 🧹 CLEANUP
  await redis.disconnect();
}

main();

⚙️ Configuration

The RedisClient constructor accepts a configuration object with two keys: primary and replica. Both accept standard ioredis options.

| Property | Type | Description | |:-----|:--------:|------:| | primary | RedisOptions | Configuration for the Master (Write) node. | | replica | RedisOptions | Configuration for the Read Replica

Example Config Object:

{
  primary: { host: '127.0.0.1', port: 6379, password: 'auth' },
  replica: { host: '127.0.0.1', port: 6380, password: 'auth' }
}

🏗 Architecture

This library implements the Read/Write Splitting pattern:

1. Command Interception: The client checks the method being called (e.g., set vs get).
2. Routing: * Mutating commands → Primary Connection
   • Read-only commands → Replica Connection
3. Result: This ensures high availability and prevents heavy read queries from slowing down data ingestion.

🧪 Running Tests

This project uses Jest with ts-jest for unit testing. The tests mock ioredis to ensure traffic is routed to the correct connection without needing a real Redis instance.

To run the test suite:

npm test

Expected Output:

 PASS  test/client.test.ts
  RedisClient
    ✓ should create two separate Redis connections
    ✓ set() should call primary node
    ✓ get() should call replica node

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.