@node-ts-cache/ioredis-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,179 @@
+# @node-ts-cache/ioredis-storage
+
+[![npm](https://img.shields.io/npm/v/@node-ts-cache/ioredis-storage.svg)](https://www.npmjs.org/package/@node-ts-cache/ioredis-storage)
+
+Modern Redis storage adapter for [@node-ts-cache/core](https://www.npmjs.com/package/@node-ts-cache/core) using [ioredis](https://github.com/redis/ioredis) with optional Snappy compression.
+
+## Features
+
+- Modern `ioredis` client
+- Optional Snappy compression for reduced bandwidth
+- Multi-get/set operations for batch caching
+- Built-in TTL support (uses Redis native SETEX)
+- Custom error handler support
+- Non-blocking write operations (optional)
+
+## Installation
+
+```bash
+npm install @node-ts-cache/core @node-ts-cache/ioredis-storage ioredis
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { Cache, ExpirationStrategy } from '@node-ts-cache/core';
+import RedisIOStorage from '@node-ts-cache/ioredis-storage';
+import Redis from 'ioredis';
+
+const redisClient = new Redis({
+	host: 'localhost',
+	port: 6379
+});
+
+const storage = new RedisIOStorage(
+	() => redisClient,
+	{ maxAge: 3600 } // TTL in seconds (default: 86400 = 24 hours)
+);
+
+const strategy = new ExpirationStrategy(storage);
+
+class UserService {
+	@Cache(strategy, { ttl: 300 })
+	async getUser(id: string): Promise<User> {
+		return await db.users.findById(id);
+	}
+}
+```
+
+### With Compression
+
+Enable Snappy compression to reduce bandwidth usage (useful for large objects):
+
+```typescript
+const storage = new RedisIOStorage(() => redisClient, { maxAge: 3600, compress: true });
+```
+
+### With Error Handler
+
+Configure a custom error handler for non-blocking write operations:
+
+```typescript
+const storage = new RedisIOStorage(() => redisClient, { maxAge: 3600 });
+
+storage.onError(error => {
+	// Log errors without blocking the application
+	console.error('Redis cache error:', error);
+	metrics.incrementCacheError();
+});
+```
+
+When an error handler is set, write operations don't await the Redis response, making them non-blocking.
+
+### Multi-Operations with @MultiCache
+
+This storage supports batch operations, making it ideal for multi-tier caching:
+
+```typescript
+import { MultiCache, ExpirationStrategy } from '@node-ts-cache/core';
+import RedisIOStorage from '@node-ts-cache/ioredis-storage';
+import NodeCacheStorage from '@node-ts-cache/node-cache-storage';
+
+const localCache = new ExpirationStrategy(new NodeCacheStorage());
+const redisCache = new RedisIOStorage(() => redisClient, { maxAge: 3600 });
+
+class UserService {
+	@MultiCache([localCache, redisCache], 0, id => `user:${id}`)
+	async getUsersByIds(ids: string[]): Promise<User[]> {
+		return await db.users.findByIds(ids);
+	}
+}
+```
+
+### Direct API Usage
+
+```typescript
+const storage = new RedisIOStorage(() => redisClient, { maxAge: 3600 });
+
+// Single item operations
+await storage.setItem('user:123', { name: 'John' }, { ttl: 60 });
+const user = await storage.getItem<{ name: string }>('user:123');
+
+// Multi-item operations
+const users = await storage.getItems<User>(['user:1', 'user:2', 'user:3']);
+await storage.setItems(
+	[
+		{ key: 'user:1', content: { name: 'Alice' } },
+		{ key: 'user:2', content: { name: 'Bob' } }
+	],
+	{ ttl: 60 }
+);
+
+// Clear all (uses FLUSHDB - use with caution!)
+await storage.clear();
+```
+
+## Constructor
+
+```typescript
+new RedisIOStorage(
+  redis: () => Redis.Redis,
+  options?: {
+    maxAge?: number;     // TTL in seconds (default: 86400)
+    compress?: boolean;  // Enable Snappy compression (default: false)
+  }
+)
+```
+
+| Parameter          | Type                | Description                                           |
+| ------------------ | ------------------- | ----------------------------------------------------- |
+| `redis`            | `() => Redis.Redis` | Factory function returning an ioredis client instance |
+| `options.maxAge`   | `number`            | Default TTL in seconds (default: 86400 = 24 hours)    |
+| `options.compress` | `boolean`           | Enable Snappy compression (default: false)            |
+
+## Interface
+
+```typescript
+interface IAsynchronousCacheType {
+	getItem<T>(key: string): Promise<T | undefined>;
+	setItem(key: string, content: any, options?: { ttl?: number }): Promise<void>;
+	clear(): Promise<void>;
+}
+
+interface IMultiIAsynchronousCacheType {
+	getItems<T>(keys: string[]): Promise<{ [key: string]: T | undefined }>;
+	setItems(values: { key: string; content: any }[], options?: { ttl?: number }): Promise<void>;
+	clear(): Promise<void>;
+}
+```
+
+## TTL Behavior
+
+This storage uses Redis native TTL (SETEX command) rather than relying solely on ExpirationStrategy:
+
+- `options.maxAge` in constructor sets the default TTL
+- `options.ttl` in setItem/setItems overrides the default
+- When used with ExpirationStrategy, both TTLs apply (Redis TTL for storage-level, strategy TTL for metadata)
+
+## Value Handling
+
+- `undefined`: Deletes the key from Redis
+- `null`: Stores as empty string `""`
+- Objects: JSON stringified before storage
+- Primitives: Stored directly
+
+## Dependencies
+
+- `ioredis` ^5.3.2 - Modern Redis client
+- `snappy` ^7.0.5 - Fast compression library
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Redis server
+
+## License
+
+MIT

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+import { RedisIOStorage } from './redisio.storage.js';
+export default RedisIOStorage;
+//# 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,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,eAAe,cAAc,CAAC"}

package/dist/redisio.storage.d.ts

@@ -0,0 +1,29 @@
+/// <reference types="node" />
+import { IAsynchronousCacheType, IMultiIAsynchronousCacheType } from '@node-ts-cache/core';
+import * as Redis from 'ioredis';
+export declare class RedisIOStorage implements IAsynchronousCacheType, IMultiIAsynchronousCacheType {
+    private redis;
+    private options;
+    constructor(redis: () => Redis.Redis, options?: {
+        maxAge: number;
+        compress?: boolean;
+    });
+    private errorHandler;
+    onError(listener: (error: Error) => void): void;
+    getItems<T>(keys: string[]): Promise<{
+        [key: string]: T | undefined;
+    }>;
+    compress(uncompressed: string): Promise<Buffer>;
+    uncompress(compressed: Buffer): Promise<string>;
+    setItems<T = unknown>(values: {
+        key: string;
+        content: T | undefined;
+    }[], options?: {
+        ttl?: number;
+    }): Promise<void>;
+    getItem<T>(key: string): Promise<T | undefined>;
+    setItem<T = unknown>(key: string, content: T | undefined, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/redisio.storage.js

@@ -0,0 +1,121 @@
+import * as snappy from 'snappy';
+export class RedisIOStorage {
+    constructor(redis, options = { maxAge: 86400 }) {
+        this.redis = redis;
+        this.options = options;
+    }
+    onError(listener) {
+        this.errorHandler = listener;
+    }
+    async getItems(keys) {
+        const mget = this.options.compress
+            ? await this.redis().mgetBuffer(...keys)
+            : await this.redis().mget(...keys);
+        const res = Object.fromEntries(await Promise.all(mget.map(async (entry, i) => {
+            if (entry === null) {
+                return [keys[i], undefined]; // value does not exist yet
+            }
+            if (entry === '') {
+                return [keys[i], null]; // value does exist, but is empty
+            }
+            // Decompress if needed, result is a string
+            const stringValue = entry && this.options.compress
+                ? await this.uncompress(entry)
+                : entry;
+            // Try to parse as JSON
+            let parsedItem = stringValue;
+            try {
+                if (stringValue) {
+                    parsedItem = JSON.parse(stringValue);
+                }
+            }
+            catch (error) {
+                /** Not JSON, keep as string */
+            }
+            return [keys[i], parsedItem];
+        })));
+        return res;
+    }
+    async compress(uncompressed) {
+        const result = await snappy.compress(uncompressed);
+        return result;
+    }
+    async uncompress(compressed) {
+        const result = await snappy.uncompress(compressed, { asBuffer: false });
+        return result.toString();
+    }
+    async setItems(values, options) {
+        const redisPipeline = this.redis().pipeline();
+        await Promise.all(values.map(async (val) => {
+            if (val.content === undefined)
+                return;
+            let content = JSON.stringify(val.content);
+            if (this.options.compress) {
+                content = await this.compress(content);
+            }
+            const ttl = options?.ttl ?? this.options.maxAge;
+            if (ttl) {
+                redisPipeline.setex(val.key, ttl, content);
+            }
+            else {
+                redisPipeline.set(val.key, content);
+            }
+        }));
+        const savePromise = redisPipeline.exec();
+        if (this.errorHandler) {
+            // if we have an error handler, we do not need to await the result
+            savePromise.catch(err => this.errorHandler && this.errorHandler(err));
+        }
+        else {
+            await savePromise;
+        }
+    }
+    async getItem(key) {
+        const entry = this.options.compress
+            ? await this.redis().getBuffer(key)
+            : await this.redis().get(key);
+        if (entry === null) {
+            return undefined;
+        }
+        if (entry === '') {
+            return null; // value exists but is empty
+        }
+        // Decompress if needed, result is a string
+        const stringValue = entry && this.options.compress ? await this.uncompress(entry) : entry;
+        // Try to parse as JSON
+        let parsedItem = stringValue;
+        try {
+            parsedItem = JSON.parse(stringValue);
+        }
+        catch (error) {
+            /** Not JSON, keep as string */
+        }
+        return parsedItem;
+    }
+    async setItem(key, content, options) {
+        if (content === undefined) {
+            await this.redis().del(key);
+            return;
+        }
+        // Serialize to string, then optionally compress
+        let serialized = typeof content === 'object' ? JSON.stringify(content) : String(content);
+        if (this.options.compress) {
+            serialized = await this.compress(serialized);
+        }
+        const ttl = options?.ttl ?? this.options.maxAge;
+        const savePromise = ttl
+            ? this.redis().setex(key, ttl, serialized)
+            : this.redis().set(key, serialized);
+        if (this.errorHandler) {
+            // if we have an error handler, we do not need to await the result
+            savePromise.catch(err => this.errorHandler && this.errorHandler(err));
+        }
+        else {
+            await savePromise;
+        }
+    }
+    async clear() {
+        await this.redis().flushdb();
+    }
+}
+//# sourceMappingURL=redisio.storage.js.map

package/dist/redisio.storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redisio.storage.js","sourceRoot":"","sources":["../src/redisio.storage.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@node-ts-cache/ioredis-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/redisio#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",
+    "snappy": "^7.0.5",
+    "@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",
+    "tdd": "mocha --loader=ts-node/esm -w",
+    "tdd-debug-brk": "mocha --loader=ts-node/esm --inspect-brk",
+    "test": "mocha --loader=ts-node/esm test/**/*.test.ts"
+  }
+}