@node-ts-cache/lru-redis-storage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Himmet Avsar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,208 @@
+# @node-ts-cache/lru-redis-storage
+
+[![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-redis-storage.svg)](https://www.npmjs.org/package/@node-ts-cache/lru-redis-storage)
+
+Two-tier cache storage adapter for [@node-ts-cache/core](https://www.npmjs.com/package/@node-ts-cache/core) combining local LRU cache with remote Redis fallback.
+
+## Features
+
+- **Two-tier architecture**: Fast local LRU cache + shared Redis backend
+- Local cache for hot data (sub-millisecond access)
+- Redis fallback for cache misses
+- Automatic population of local cache from Redis hits
+- Reduced Redis round-trips
+- Ideal for high-traffic, distributed applications
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                      Application                         │
+│                          │                               │
+│                          ▼                               │
+│              ┌───────────────────────┐                  │
+│              │   LRUWithRedisStorage │                  │
+│              └───────────┬───────────┘                  │
+│                          │                               │
+│            ┌─────────────┴─────────────┐                │
+│            ▼                           ▼                │
+│   ┌─────────────────┐         ┌─────────────────┐      │
+│   │   Local LRU     │  miss   │     Redis       │      │
+│   │   (in-memory)   │ ──────> │   (remote)      │      │
+│   │   ~0.01ms       │ <────── │   ~1-5ms        │      │
+│   └─────────────────┘  hit    └─────────────────┘      │
+│                     (populate)                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+1. **Get**: Check local LRU first. On miss, check Redis. If found in Redis, populate local LRU.
+2. **Set**: Write to both local LRU and Redis.
+3. **Clear**: Clear local LRU cache.
+
+## Installation
+
+```bash
+npm install @node-ts-cache/core @node-ts-cache/lru-redis-storage ioredis
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Cache, ExpirationStrategy } from '@node-ts-cache/core';
+import { LRUWithRedisStorage } from '@node-ts-cache/lru-redis-storage';
+import Redis from 'ioredis';
+
+const redisClient = new Redis({
+	host: 'localhost',
+	port: 6379
+});
+
+const storage = new LRUWithRedisStorage(
+	{ max: 1000 }, // LRU options: max 1000 items locally
+	() => redisClient // Redis client factory
+);
+
+const strategy = new ExpirationStrategy(storage);
+
+class UserService {
+	@Cache(strategy, { ttl: 300 })
+	async getUser(id: string): Promise<User> {
+		return await db.users.findById(id);
+	}
+}
+```
+
+### With TTL
+
+```typescript
+const storage = new LRUWithRedisStorage(
+	{
+		max: 500,
+		ttl: 60 // Local and Redis cache TTL: 1 minute (in seconds)
+	},
+	() => redisClient
+);
+```
+
+### Direct API Usage
+
+```typescript
+const storage = new LRUWithRedisStorage({ max: 100 }, () => redisClient);
+const strategy = new ExpirationStrategy(storage);
+
+// Store (writes to both LRU and Redis)
+await strategy.setItem('user:123', { name: 'John' }, { ttl: 60 });
+
+// First get - might hit Redis if not in LRU
+const user1 = await strategy.getItem<User>('user:123');
+
+// Second get - hits local LRU (fast!)
+const user2 = await strategy.getItem<User>('user:123');
+
+// Clear local LRU cache
+await strategy.clear();
+```
+
+## Constructor
+
+```typescript
+new LRUWithRedisStorage(
+  options: LRUWithRedisStorageOptions,
+  redis: () => Redis.Redis
+)
+```
+
+| Parameter | Type                         | Description                               |
+| --------- | ---------------------------- | ----------------------------------------- |
+| `options` | `LRUWithRedisStorageOptions` | Options for local LRU cache and TTL       |
+| `redis`   | `() => Redis.Redis`          | Factory function returning ioredis client |
+
+### Options
+
+| Option | Type     | Default | Description                                        |
+| ------ | -------- | ------- | -------------------------------------------------- |
+| `max`  | `number` | `500`   | Maximum items in local LRU cache                   |
+| `ttl`  | `number` | `86400` | Time to live in **seconds** (for both LRU & Redis) |
+
+## Interface
+
+```typescript
+interface IAsynchronousCacheType {
+	getItem<T>(key: string): Promise<T | undefined>;
+	setItem(key: string, content: any, options?: any): Promise<void>;
+	clear(): Promise<void>;
+}
+```
+
+## Use Cases
+
+### High-Traffic APIs
+
+```typescript
+class ProductAPI {
+	@Cache(strategy, { ttl: 60 })
+	async getProduct(id: string): Promise<Product> {
+		// Hot products served from local LRU (~0.01ms)
+		// Cold products fetched from Redis (~1-5ms)
+		// Very cold products hit database
+		return await db.products.findById(id);
+	}
+}
+```
+
+### Distributed Systems
+
+Multiple application instances share the same Redis cache while maintaining their own local LRU:
+
+```
+┌──────────────┐     ┌──────────────┐     ┌──────────────┐
+│  Instance 1  │     │  Instance 2  │     │  Instance 3  │
+│  ┌────────┐  │     │  ┌────────┐  │     │  ┌────────┐  │
+│  │  LRU   │  │     │  │  LRU   │  │     │  │  LRU   │  │
+│  └────┬───┘  │     │  └────┬───┘  │     │  └────┬───┘  │
+└───────┼──────┘     └───────┼──────┘     └───────┼──────┘
+        │                    │                    │
+        └────────────────────┼────────────────────┘
+                             │
+                      ┌──────┴──────┐
+                      │    Redis    │
+                      │  (shared)   │
+                      └─────────────┘
+```
+
+### Session Caching
+
+```typescript
+class SessionService {
+	@Cache(strategy, { ttl: 1800 }) // 30 minutes
+	async getSession(token: string): Promise<Session> {
+		// Active sessions stay in local LRU
+		// Inactive sessions fall back to Redis
+		return await db.sessions.findByToken(token);
+	}
+}
+```
+
+## Performance Considerations
+
+- **Local LRU hit**: ~0.01ms (in-process memory access)
+- **Redis hit**: ~1-5ms (network round-trip)
+- **Set local `max`** based on your memory budget and access patterns
+- **Shorter TTL** = fresher data but more Redis hits
+- **Longer TTL** = better performance but potentially stale data
+
+## Dependencies
+
+- `lru-cache` ^10.0.0
+- `ioredis` ^5.3.2
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Redis server
+
+## License
+
+MIT

package/dist/LRUWithRedisStorage.d.ts

@@ -0,0 +1,21 @@
+import { IAsynchronousCacheType } from '@node-ts-cache/core';
+import * as Redis from 'ioredis';
+export interface LRUWithRedisStorageOptions {
+    /** Maximum number of items in local LRU cache */
+    max?: number;
+    /** Time to live in seconds for both local and Redis cache */
+    ttl?: number;
+}
+export declare class LRUWithRedisStorage implements IAsynchronousCacheType {
+    private redis;
+    private myCache;
+    /** ttl in seconds! */
+    private options;
+    constructor(options: LRUWithRedisStorageOptions, redis: () => Redis.Redis);
+    getItem<T>(key: string): Promise<T | undefined>;
+    /** ttl in seconds! */
+    setItem<T = unknown>(key: string, content: T | undefined, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/LRUWithRedisStorage.js

@@ -0,0 +1,52 @@
+import { LRUCache } from 'lru-cache';
+export class LRUWithRedisStorage {
+    constructor(options, redis) {
+        this.redis = redis;
+        this.options = {
+            max: 500,
+            ttl: 86400,
+            ...options
+        };
+        this.myCache = new LRUCache({
+            max: this.options.max,
+            ttl: this.options.ttl * 1000 // convert to ms
+        });
+    }
+    async getItem(key) {
+        // check local cache
+        let localCache = this.myCache.get(key);
+        if (localCache === undefined) {
+            // check central cache
+            const redisValue = await this.redis().get(key);
+            if (redisValue !== null) {
+                try {
+                    localCache = JSON.parse(redisValue);
+                }
+                catch (err) {
+                    console.error('lru redis cache failed parsing data', err);
+                    localCache = undefined;
+                }
+                // if found on central cache, copy it to a local cache
+                if (localCache !== undefined) {
+                    this.myCache.set(key, localCache);
+                }
+            }
+        }
+        return localCache;
+    }
+    /** ttl in seconds! */
+    async setItem(key, content, options) {
+        this.myCache.set(key, content);
+        const ttl = options?.ttl || this.options.ttl;
+        if (ttl) {
+            await this.redis().setex(key, ttl, JSON.stringify(content));
+        }
+        else {
+            await this.redis().set(key, JSON.stringify(content));
+        }
+    }
+    async clear() {
+        this.myCache.clear();
+    }
+}
+//# sourceMappingURL=LRUWithRedisStorage.js.map

package/dist/LRUWithRedisStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LRUWithRedisStorage.js","sourceRoot":"","sources":["../src/LRUWithRedisStorage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAUrC,MAAM,OAAO,mBAAmB;IAQ/B,YAAY,OAAmC,EAAU,KAAwB;QAAxB,UAAK,GAAL,KAAK,CAAmB;QAChF,IAAI,CAAC,OAAO,GAAG;YACd,GAAG,EAAE,GAAG;YACR,GAAG,EAAE,KAAK;YACV,GAAG,OAAO;SACV,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,IAAI,QAAQ,CAAC;YAC3B,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG;YACrB,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,gBAAgB;SAC7C,CAAC,CAAC;IACJ,CAAC;IAEM,KAAK,CAAC,OAAO,CAAI,GAAW;QAClC,oBAAoB;QACpB,IAAI,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,UAAU,KAAK,SAAS,EAAE;YAC7B,sBAAsB;YACtB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAE/C,IAAI,UAAU,KAAK,IAAI,EAAE;gBACxB,IAAI;oBACH,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;iBACpC;gBAAC,OAAO,GAAG,EAAE;oBACb,OAAO,CAAC,KAAK,CAAC,qCAAqC,EAAE,GAAG,CAAC,CAAC;oBAC1D,UAAU,GAAG,SAAS,CAAC;iBACvB;gBACD,sDAAsD;gBACtD,IAAI,UAAU,KAAK,SAAS,EAAE;oBAC7B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;iBAClC;aACD;SACD;QAED,OAAO,UAA2B,CAAC;IACpC,CAAC;IAED,sBAAsB;IACf,KAAK,CAAC,OAAO,CACnB,GAAW,EACX,OAAsB,EACtB,OAA0B;QAE1B,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAC/B,MAAM,GAAG,GAAG,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC;QAC7C,IAAI,GAAG,EAAE;YACR,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;SAC5D;aAAM;YACN,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;SACrD;IACF,CAAC;IAEM,KAAK,CAAC,KAAK;QACjB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACD"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { LRUWithRedisStorage } from './LRUWithRedisStorage.js';
+export default LRUWithRedisStorage;

package/dist/index.js

@@ -0,0 +1,3 @@
+import { LRUWithRedisStorage } from './LRUWithRedisStorage.js';
+export default LRUWithRedisStorage;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,eAAe,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@node-ts-cache/lru-redis-storage",
+  "version": "1.0.0",
+  "description": "Simple and extensible caching module supporting decorators",
+  "keywords": [
+    "node",
+    "nodejs",
+    "cache",
+    "typescript",
+    "ts",
+    "caching",
+    "memcache",
+    "memory-cache",
+    "redis-cache",
+    "redis",
+    "file-cache",
+    "node-cache",
+    "ts-cache"
+  ],
+  "homepage": "https://github.com/simllll/node-ts-cache/tree/master/storages/lru-redis#readme",
+  "bugs": {
+    "url": "https://github.com/simllll/node-ts-cache/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/simllll/node-ts-cache.git"
+  },
+  "license": "MIT",
+  "author": "Simon Tretter <s.tretter@gmail.com>",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "ioredis": "^5.3.2",
+    "lru-cache": "^10.0.0",
+    "@node-ts-cache/core": "1.0.0"
+  },
+  "devDependencies": {
+    "ioredis-mock": "^8.9.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "c938eba762060f940a34bc192bec03bc76ea4017",
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "git clean -fdx src",
+    "dev": "tsc -p . -w",
+    "test": "mocha --loader=ts-node/esm test/**/*.test.ts"
+  }
+}