@ferrox-node/redis 1.1.1

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import { Lock } from 'redlock';
+export * from './smart-cache';
+export declare class RedisHelper {
+    private client;
+    private redlock;
+    constructor(redisUrl: string);
+    /**
+     * Acquire a Distributed Lock to prevent race conditions across microservices
+     */
+    acquireLock(resource: string, ttlMs: number): Promise<Lock>;
+    /**
+     * Caches a value with a specific TTL
+     */
+    setCache(key: string, value: any, ttlSeconds: number): Promise<void>;
+    /**
+     * Retrieves a cached value
+     */
+    getCache<T>(key: string): Promise<T | null>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,69 @@
+"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);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RedisHelper = void 0;
+const ioredis_1 = __importDefault(require("ioredis"));
+const redlock_1 = __importDefault(require("redlock"));
+const logger_1 = require("@node-yalc/logger");
+__exportStar(require("./smart-cache"), exports);
+const logger = (0, logger_1.AppLoggerFactory)('RedisCloudHelper');
+class RedisHelper {
+    client;
+    redlock;
+    constructor(redisUrl) {
+        this.client = new ioredis_1.default(redisUrl);
+        // Configure Redlock for Distributed Locking
+        this.redlock = new redlock_1.default([this.client], {
+            driftFactor: 0.01,
+            retryCount: 10,
+            retryDelay: 200,
+            retryJitter: 200,
+            automaticExtensionThreshold: 500,
+        });
+        this.client.on('connect', () => logger.log('Connected to Redis successfully'));
+        this.client.on('error', (err) => logger.error(`Redis connection error: ${err.message}`));
+    }
+    /**
+     * Acquire a Distributed Lock to prevent race conditions across microservices
+     */
+    async acquireLock(resource, ttlMs) {
+        logger.debug?.(`[Redis] Acquiring lock for resource: ${resource} (${ttlMs}ms)`);
+        return this.redlock.acquire([resource], ttlMs);
+    }
+    /**
+     * Caches a value with a specific TTL
+     */
+    async setCache(key, value, ttlSeconds) {
+        const serialized = JSON.stringify(value);
+        await this.client.set(key, serialized, 'EX', ttlSeconds);
+    }
+    /**
+     * Retrieves a cached value
+     */
+    async getCache(key) {
+        const data = await this.client.get(key);
+        if (!data)
+            return null;
+        return JSON.parse(data);
+    }
+    async close() {
+        await this.client.quit();
+    }
+}
+exports.RedisHelper = RedisHelper;

package/dist/smart-cache.d.ts

@@ -0,0 +1,23 @@
+import { RedisHelper } from './index';
+export interface CacheFetchOptions {
+    userId: string;
+    resourceName: string;
+    ttlSeconds: number;
+    fetcher: () => Promise<any>;
+}
+export declare class SmartCacheManager {
+    private inFlightPromises;
+    private redis;
+    constructor(redisHelper: RedisHelper);
+    /**
+     * Generates a hyper-strict, isolated cache key.
+     */
+    private generateKey;
+    /**
+     * Fetches data with Thundering Herd & Cache Stampede Protection (Multi-tier).
+     * 1. In-Memory Promise Deduplication (Single-Node Lock)
+     * 2. Redis Distributed Lock (Multi-Node Lock)
+     */
+    getOrFetch<T>(options: CacheFetchOptions): Promise<T>;
+    private internalFetch;
+}

package/dist/smart-cache.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SmartCacheManager = void 0;
+const logger_1 = require("@node-yalc/logger");
+const logger = (0, logger_1.AppLoggerFactory)('SmartCacheManager');
+class SmartCacheManager {
+    inFlightPromises = new Map();
+    redis;
+    constructor(redisHelper) {
+        this.redis = redisHelper;
+    }
+    /**
+     * Generates a hyper-strict, isolated cache key.
+     */
+    generateKey(userId, resourceName) {
+        return `ferrox:cache:user:${userId}:res:${resourceName}`;
+    }
+    /**
+     * Fetches data with Thundering Herd & Cache Stampede Protection (Multi-tier).
+     * 1. In-Memory Promise Deduplication (Single-Node Lock)
+     * 2. Redis Distributed Lock (Multi-Node Lock)
+     */
+    async getOrFetch(options) {
+        const cacheKey = this.generateKey(options.userId, options.resourceName);
+        // TIER 1: In-Memory Promise Deduplication. 
+        // If 10k requests hit THIS node, 9999 will just await the existing promise without hitting Redis or DB!
+        if (this.inFlightPromises.has(cacheKey)) {
+            logger?.debug?.(`[Cache] Memory multiplex hit for ${cacheKey}. Awaiting existing promise...`);
+            return this.inFlightPromises.get(cacheKey);
+        }
+        const fetchPromise = this.internalFetch(cacheKey, options);
+        this.inFlightPromises.set(cacheKey, fetchPromise);
+        try {
+            return await fetchPromise;
+        }
+        finally {
+            // Always cleanup the in-flight promise regardless of success or failure
+            this.inFlightPromises.delete(cacheKey);
+        }
+    }
+    async internalFetch(cacheKey, options) {
+        // TIER 2: Check Redis Cache
+        const cachedValue = await this.redis.getCache(cacheKey);
+        if (cachedValue) {
+            logger?.debug?.(`[Cache] Redis hit for ${cacheKey}`);
+            return cachedValue;
+        }
+        // TIER 3: Redis Distributed Lock (Cache Stampede Protection across multiple Node instances)
+        const lockKey = `lock:${cacheKey}`;
+        logger?.debug?.(`[Cache] Cache miss for ${cacheKey}. Attempting to acquire distributed DB lock...`);
+        let lock;
+        try {
+            // Only 1 node across the whole cluster gets the lock. Others will fail and fallback
+            lock = await this.redis.acquireLock(lockKey, 5000); // 5 sec lock
+        }
+        catch (err) {
+            // Failed to acquire lock (another node is fetching). 
+            // We must wait a bit and retry reading from cache!
+            logger.warn(`[Cache] Lock busy for ${cacheKey}. Another instance is fetching. Waiting and retrying...`);
+            await new Promise(resolve => setTimeout(resolve, 200));
+            const retryCache = await this.redis.getCache(cacheKey);
+            if (retryCache)
+                return retryCache;
+            throw new Error(`Timeout waiting for cache resolution on ${cacheKey}`);
+        }
+        // We hold the lock! Hit the DB.
+        try {
+            logger?.debug?.(`[Cache] Lock acquired. Executing DB fetcher for ${cacheKey}`);
+            const freshData = await options.fetcher();
+            // Store in Redis
+            await this.redis.setCache(cacheKey, freshData, options.ttlSeconds);
+            return freshData;
+        }
+        catch (err) {
+            logger.error(`[Cache] Fetcher failed for ${cacheKey}: ${err.message}`);
+            throw err;
+        }
+        finally {
+            // Always release the lock
+            await lock.release().catch(e => logger.warn(`[Cache] Error releasing lock: ${e.message}`));
+        }
+    }
+}
+exports.SmartCacheManager = SmartCacheManager;

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@ferrox-node/redis",
+  "version": "1.1.1",
+  "description": "Advanced Redis, Distributed Locks, and Caching for Ferrox-Node",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@ferrox-node/core": "*",
+    "ioredis": "^5.4.1",
+    "redlock": "^5.0.0-beta.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^20.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,56 @@
+import Redis from 'ioredis';
+import Redlock, { Lock } from 'redlock';
+import { AppLoggerFactory } from '@node-yalc/logger';
+export * from './smart-cache';
+
+const logger = AppLoggerFactory('RedisCloudHelper');
+
+export class RedisHelper {
+  private client: Redis;
+  private redlock: Redlock;
+
+  constructor(redisUrl: string) {
+    this.client = new Redis(redisUrl);
+    
+    // Configure Redlock for Distributed Locking
+    this.redlock = new Redlock([this.client], {
+      driftFactor: 0.01,
+      retryCount: 10,
+      retryDelay: 200,
+      retryJitter: 200,
+      automaticExtensionThreshold: 500,
+    });
+
+    this.client.on('connect', () => logger.log('Connected to Redis successfully'));
+    this.client.on('error', (err) => logger.error(`Redis connection error: ${err.message}`));
+  }
+
+  /**
+   * Acquire a Distributed Lock to prevent race conditions across microservices
+   */
+  async acquireLock(resource: string, ttlMs: number): Promise<Lock> {
+    logger.debug?.(`[Redis] Acquiring lock for resource: ${resource} (${ttlMs}ms)`);
+    return this.redlock.acquire([resource], ttlMs);
+  }
+
+  /**
+   * Caches a value with a specific TTL
+   */
+  async setCache(key: string, value: any, ttlSeconds: number): Promise<void> {
+    const serialized = JSON.stringify(value);
+    await this.client.set(key, serialized, 'EX', ttlSeconds);
+  }
+
+  /**
+   * Retrieves a cached value
+   */
+  async getCache<T>(key: string): Promise<T | null> {
+    const data = await this.client.get(key);
+    if (!data) return null;
+    return JSON.parse(data) as T;
+  }
+
+  async close() {
+    await this.client.quit();
+  }
+}

package/src/smart-cache.ts

@@ -0,0 +1,100 @@
+import { RedisHelper } from './index';
+import { AppLoggerFactory } from '@node-yalc/logger';
+
+const logger = AppLoggerFactory('SmartCacheManager');
+
+export interface CacheFetchOptions {
+  userId: string;         // Mandatory to prevent returning one user's data to another!
+  resourceName: string;   // e.g. 'profile', 'billing'
+  ttlSeconds: number;
+  fetcher: () => Promise<any>; // The function that actually hits the DB
+}
+
+export class SmartCacheManager {
+  private inFlightPromises = new Map<string, Promise<any>>();
+  private redis: RedisHelper;
+
+  constructor(redisHelper: RedisHelper) {
+    this.redis = redisHelper;
+  }
+
+  /**
+   * Generates a hyper-strict, isolated cache key.
+   */
+  private generateKey(userId: string, resourceName: string): string {
+    return `ferrox:cache:user:${userId}:res:${resourceName}`;
+  }
+
+  /**
+   * Fetches data with Thundering Herd & Cache Stampede Protection (Multi-tier).
+   * 1. In-Memory Promise Deduplication (Single-Node Lock)
+   * 2. Redis Distributed Lock (Multi-Node Lock)
+   */
+  public async getOrFetch<T>(options: CacheFetchOptions): Promise<T> {
+    const cacheKey = this.generateKey(options.userId, options.resourceName);
+
+    // TIER 1: In-Memory Promise Deduplication. 
+    // If 10k requests hit THIS node, 9999 will just await the existing promise without hitting Redis or DB!
+    if (this.inFlightPromises.has(cacheKey)) {
+      logger?.debug?.(`[Cache] Memory multiplex hit for ${cacheKey}. Awaiting existing promise...`);
+      return this.inFlightPromises.get(cacheKey) as Promise<T>;
+    }
+
+    const fetchPromise = this.internalFetch<T>(cacheKey, options);
+    this.inFlightPromises.set(cacheKey, fetchPromise);
+
+    try {
+      return await fetchPromise;
+    } finally {
+      // Always cleanup the in-flight promise regardless of success or failure
+      this.inFlightPromises.delete(cacheKey);
+    }
+  }
+
+  private async internalFetch<T>(cacheKey: string, options: CacheFetchOptions): Promise<T> {
+    // TIER 2: Check Redis Cache
+    const cachedValue = await this.redis.getCache<T>(cacheKey);
+    if (cachedValue) {
+      logger?.debug?.(`[Cache] Redis hit for ${cacheKey}`);
+      return cachedValue;
+    }
+
+    // TIER 3: Redis Distributed Lock (Cache Stampede Protection across multiple Node instances)
+    const lockKey = `lock:${cacheKey}`;
+    logger?.debug?.(`[Cache] Cache miss for ${cacheKey}. Attempting to acquire distributed DB lock...`);
+    
+    let lock;
+    try {
+      // Only 1 node across the whole cluster gets the lock. Others will fail and fallback
+      lock = await this.redis.acquireLock(lockKey, 5000); // 5 sec lock
+    } catch (err) {
+      // Failed to acquire lock (another node is fetching). 
+      // We must wait a bit and retry reading from cache!
+      logger.warn(`[Cache] Lock busy for ${cacheKey}. Another instance is fetching. Waiting and retrying...`);
+      await new Promise(resolve => setTimeout(resolve, 200));
+      
+      const retryCache = await this.redis.getCache<T>(cacheKey);
+      if (retryCache) return retryCache;
+      
+      throw new Error(`Timeout waiting for cache resolution on ${cacheKey}`);
+    }
+
+    // We hold the lock! Hit the DB.
+    try {
+      logger?.debug?.(`[Cache] Lock acquired. Executing DB fetcher for ${cacheKey}`);
+      const freshData = await options.fetcher();
+      
+      // Store in Redis
+      await this.redis.setCache(cacheKey, freshData, options.ttlSeconds);
+      
+      return freshData;
+    } catch (err: any) {
+      logger.error(`[Cache] Fetcher failed for ${cacheKey}: ${err.message}`);
+      throw err;
+    } finally {
+      // Always release the lock
+      await lock.release().catch(e => logger.warn(`[Cache] Error releasing lock: ${e.message}`));
+    }
+  }
+}
+

package/tests/smart-cache.spec.ts

@@ -0,0 +1,91 @@
+import { SmartCacheManager } from '../src/smart-cache';
+
+describe('SmartCacheManager', () => {
+  it('should deduplicate in-flight promises (Cache Stampede Protection)', async () => {
+    // Mock RedisHelper
+    const mockRedis = {
+      getCache: jest.fn().mockResolvedValue(null),
+      acquireLock: jest.fn().mockResolvedValue({ release: jest.fn().mockResolvedValue(true) }),
+      setCache: jest.fn().mockResolvedValue(true),
+    };
+
+    const cache = new SmartCacheManager(mockRedis as any);
+    
+    let fetchCount = 0;
+    const fetcher = async () => {
+      fetchCount++;
+      return new Promise(r => setTimeout(() => r('DB_DATA'), 50));
+    };
+
+    // Fire 5 identical requests concurrently
+    const p1 = cache.getOrFetch({ userId: 'u1', resourceName: 'profile', ttlSeconds: 60, fetcher });
+    const p2 = cache.getOrFetch({ userId: 'u1', resourceName: 'profile', ttlSeconds: 60, fetcher });
+    const p3 = cache.getOrFetch({ userId: 'u1', resourceName: 'profile', ttlSeconds: 60, fetcher });
+
+    const results = await Promise.all([p1, p2, p3]);
+
+    expect(results).toEqual(['DB_DATA', 'DB_DATA', 'DB_DATA']);
+    // Important: fetcher should only be called ONCE despite 3 concurrent calls
+    expect(fetchCount).toBe(1);
+    expect(mockRedis.acquireLock).toHaveBeenCalledTimes(1);
+  });
+
+  it('should return from redis if cache hits (Tier 2)', async () => {
+    const mockRedis = {
+      getCache: jest.fn().mockResolvedValue('CACHED_DATA'),
+      acquireLock: jest.fn(),
+    };
+    const cache = new SmartCacheManager(mockRedis as any);
+    const result = await cache.getOrFetch({ userId: 'u2', resourceName: 'profile', ttlSeconds: 60, fetcher: async () => 'DB' });
+    expect(result).toBe('CACHED_DATA');
+    expect(mockRedis.acquireLock).not.toHaveBeenCalled();
+  });
+
+  it('should wait and retry cache if lock is busy (Tier 3 fallback)', async () => {
+    let getCacheCalls = 0;
+    const mockRedis = {
+      getCache: jest.fn().mockImplementation(async () => {
+        getCacheCalls++;
+        if (getCacheCalls === 1) return null; // First try: miss
+        return 'RETRY_CACHED_DATA'; // Second try after wait: hit!
+      }),
+      acquireLock: jest.fn().mockRejectedValue(new Error('Lock busy')),
+    };
+    const cache = new SmartCacheManager(mockRedis as any);
+    const result = await cache.getOrFetch({ userId: 'u3', resourceName: 'profile', ttlSeconds: 60, fetcher: async () => 'DB' });
+    expect(result).toBe('RETRY_CACHED_DATA');
+  });
+
+  it('should throw if wait and retry cache fails', async () => {
+    const mockRedis = {
+      getCache: jest.fn().mockResolvedValue(null),
+      acquireLock: jest.fn().mockRejectedValue(new Error('Lock busy')),
+    };
+    const cache = new SmartCacheManager(mockRedis as any);
+    await expect(cache.getOrFetch({ userId: 'u4', resourceName: 'profile', ttlSeconds: 60, fetcher: async () => 'DB' })).rejects.toThrow('Timeout waiting for cache resolution');
+  });
+
+  it('should handle fetcher failure and release lock', async () => {
+    const mockRelease = jest.fn().mockResolvedValue(true);
+    const mockRedis = {
+      getCache: jest.fn().mockResolvedValue(null),
+      acquireLock: jest.fn().mockResolvedValue({ release: mockRelease }),
+    };
+    const cache = new SmartCacheManager(mockRedis as any);
+    await expect(cache.getOrFetch({ userId: 'u5', resourceName: 'profile', ttlSeconds: 60, fetcher: async () => { throw new Error('DB Error'); } })).rejects.toThrow('DB Error');
+    expect(mockRelease).toHaveBeenCalled();
+  });
+
+  it('should handle lock release error gracefully', async () => {
+    const mockRelease = jest.fn().mockRejectedValue(new Error('Release Error'));
+    const mockRedis = {
+      getCache: jest.fn().mockResolvedValue(null),
+      acquireLock: jest.fn().mockResolvedValue({ release: mockRelease }),
+      setCache: jest.fn().mockResolvedValue(true),
+    };
+    const cache = new SmartCacheManager(mockRedis as any);
+    const result = await cache.getOrFetch({ userId: 'u6', resourceName: 'profile', ttlSeconds: 60, fetcher: async () => 'DB' });
+    expect(result).toBe('DB');
+    expect(mockRelease).toHaveBeenCalled();
+  });
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "extends": "../core/tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+  },
+  "include": [
+    "src/**/*"
+  ]
+}
+
+
+
+
+
+
+