@heady/redis-client 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# Redis Client
+
+![Language](https://img.shields.io/badge/language-TypeScript-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Version](https://img.shields.io/badge/version-1.0.0-orange)
+
+**Redis Client** is a lightweight, type-safe wrapper for [ioredis](https://github.com/luin/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](#-features)
+- [Prerequisites](#-prerequisites)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Configuration](#-configuration)
+- [Architecture](#-architecture)
+- [Running Tests](#-running-tests)
+- [Contributing](#-contributing)
+- [License](#-license)
+
+---
+
+## ✨ Features
+
+* **Automatic Traffic Splitting:** Writes (`set`, `del`, `expire`) are sent to the Primary; Reads (`get`, `scan`, `hget`) 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:**
+   ```bash
+   npm install redis-client
+
+---
+
+## 💡 Usage
+
+``` typescript
+import { Redis } from 'redis-client';
+
+// 1. Initialize with separate endpoints
+const redis = new Redis({
+  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:
+```TypeScript
+{
+  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:
+``` Bash
+npm test
+```
+
+Expected Output:
+```Plaintext
+
+ PASS  test/client.test.ts
+  RedisClient
+    ✓ should create two separate Redis connections
+    ✓ set() should call primary node
+    ✓ get() should call replica node
+```
+
+## 🤝 Contributing
+
+Contributions are always welcome! Please follow these steps:
+
+    Fork the project.
+
+    Create your feature branch (git checkout -b feature/NewFeature).
+
+    Commit your changes (git commit -m 'Add some NewFeature').
+
+    Run tests to ensure no regressions (npm test).
+
+    Push to the branch.
+
+    Open a Pull Request.
+
+
+## 📜 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./redisClient";

package/dist/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./redisClient"), exports);

package/dist/redisClient.d.ts

@@ -0,0 +1,39 @@
+import { Redis as RedisType } from "ioredis";
+import { RedisConfig } from "./types";
+export declare class RedisClient {
+    private primary;
+    private replica;
+    constructor(config: RedisConfig);
+    /**
+     * -------------------------
+     * WRITE OPERATIONS (Primary)
+     * -------------------------
+     */
+    set(key: string, value: string | number, ttlSeconds?: number): Promise<string | null>;
+    hset(key: string, object: Record<string, string | number>): Promise<number>;
+    del(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    /**
+     * -------------------------
+     * READ OPERATIONS (Replica)
+     * -------------------------
+     */
+    get(key: string): Promise<string | null>;
+    hget(key: string, field: string): Promise<string | null>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    scan(cursor: string, matchPattern: string, count?: number): Promise<[string, string[]]>;
+    /**
+     * -------------------------
+     * UTILITIES
+     * -------------------------
+     */
+    /**
+     * Execute a custom command on the Primary node manually
+     */
+    getWriteClient(): RedisType;
+    /**
+     * Execute a custom command on the Replica node manually
+     */
+    getReadClient(): RedisType;
+    disconnect(): Promise<void>;
+}

package/dist/redisClient.js

@@ -0,0 +1,76 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisClient = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+class RedisClient {
+    constructor(config) {
+        // Initialize Write Connection
+        this.primary = new ioredis_1.default(config.primary);
+        // Initialize Read Connection
+        this.replica = new ioredis_1.default(config.replica);
+        // Error handling to prevent crashing the app
+        this.primary.on("error", (err) => console.error("Redis Primary Error:", err));
+        this.replica.on("error", (err) => console.error("Redis Replica Error:", err));
+    }
+    /**
+     * -------------------------
+     * WRITE OPERATIONS (Primary)
+     * -------------------------
+     */
+    async set(key, value, ttlSeconds) {
+        if (ttlSeconds) {
+            return this.primary.set(key, value, "EX", ttlSeconds);
+        }
+        return this.primary.set(key, value);
+    }
+    async hset(key, object) {
+        return this.primary.hset(key, object);
+    }
+    async del(key) {
+        return this.primary.del(key);
+    }
+    async expire(key, seconds) {
+        return this.primary.expire(key, seconds);
+    }
+    /**
+     * -------------------------
+     * READ OPERATIONS (Replica)
+     * -------------------------
+     */
+    async get(key) {
+        return this.replica.get(key);
+    }
+    async hget(key, field) {
+        return this.replica.hget(key, field);
+    }
+    async hgetall(key) {
+        return this.replica.hgetall(key);
+    }
+    async scan(cursor, matchPattern, count = 100) {
+        return this.replica.scan(cursor, "MATCH", matchPattern, "COUNT", count);
+    }
+    /**
+     * -------------------------
+     * UTILITIES
+     * -------------------------
+     */
+    /**
+     * Execute a custom command on the Primary node manually
+     */
+    getWriteClient() {
+        return this.primary;
+    }
+    /**
+     * Execute a custom command on the Replica node manually
+     */
+    getReadClient() {
+        return this.replica;
+    }
+    async disconnect() {
+        await Promise.all([this.primary.quit(), this.replica.quit()]);
+    }
+}
+exports.RedisClient = RedisClient;

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import { RedisOptions } from "ioredis";
+export interface RedisConfig {
+    /** Configuration for the Primary (Write) Node */
+    primary: RedisOptions;
+    /** Configuration for the Replica (Read) Node(s) */
+    replica: RedisOptions;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@heady/redis-client",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "@types/node": "^25.0.3",
+    "ioredis": "^5.9.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6"
+  }
+}