@node-ts-cache/valkey-storage 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simon Tretter
+
+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,105 @@
+# @node-ts-cache/valkey-storage
+
+Valkey storage adapter for [node-ts-cache](https://github.com/simllll/node-ts-cache).
+
+[Valkey](https://valkey.io/) is an open-source, Redis-compatible in-memory data store that emerged as a community-driven fork after Redis changed its license.
+
+## Installation
+
+```bash
+npm install @node-ts-cache/core @node-ts-cache/valkey-storage
+```
+
+## Usage
+
+```typescript
+import { Cache, ExpirationStrategy } from '@node-ts-cache/core';
+import { ValkeyStorage } from '@node-ts-cache/valkey-storage';
+import Valkey from 'iovalkey';
+
+const valkeyClient = new Valkey({
+	host: 'localhost',
+	port: 6379
+});
+
+const valkeyCache = new ExpirationStrategy(new ValkeyStorage(() => valkeyClient, { maxAge: 3600 }));
+
+class MyService {
+	@Cache(valkeyCache, { ttl: 60 })
+	async getUsers(): Promise<User[]> {
+		// expensive operation
+	}
+}
+```
+
+## Configuration Options
+
+```typescript
+new ValkeyStorage(
+	valkeyFactory: () => Valkey,
+	options?: {
+		maxAge: number;  // TTL in seconds (default: 86400 = 1 day)
+	}
+)
+```
+
+### Constructor Parameters
+
+| Parameter        | Type           | Description                                        |
+| ---------------- | -------------- | -------------------------------------------------- |
+| `valkeyFactory`  | `() => Valkey` | Factory function returning a Valkey client         |
+| `options`        | `object`       | Configuration options                              |
+| `options.maxAge` | `number`       | Default TTL in seconds (default: 86400 = 24 hours) |
+
+### Error Handling
+
+You can attach an error handler for non-blocking write operations:
+
+```typescript
+const storage = new ValkeyStorage(() => valkeyClient, { maxAge: 3600 });
+
+storage.onError(error => {
+	console.error('Valkey error:', error);
+	// Log to monitoring service, etc.
+});
+```
+
+### Batch Operations
+
+ValkeyStorage supports efficient batch operations:
+
+```typescript
+// Get multiple items
+const items = await storage.getItems<User>(['user:1', 'user:2', 'user:3']);
+
+// Set multiple items
+await storage.setItems([
+	{ key: 'user:1', content: user1 },
+	{ key: 'user:2', content: user2 }
+]);
+```
+
+## Running Tests Locally
+
+Start Valkey using Docker:
+
+```bash
+docker run -p 6379:6379 valkey/valkey:latest
+```
+
+Then run the tests:
+
+```bash
+npm test
+```
+
+## Why Valkey?
+
+- **Open Source**: Valkey is BSD-3 licensed, ensuring it remains truly open source
+- **Redis Compatible**: Drop-in replacement for Redis with full protocol compatibility
+- **Community Driven**: Backed by Linux Foundation with contributions from AWS, Google, Oracle, and more
+- **Active Development**: Regular releases with new features and improvements
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { ValkeyStorage } from './valkey.storage.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { ValkeyStorage } from './valkey.storage.js';
+//# 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,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/valkey.storage.d.ts

@@ -0,0 +1,25 @@
+import { IAsynchronousCacheType, IMultiIAsynchronousCacheType } from '@node-ts-cache/core';
+import * as Valkey from 'iovalkey';
+export declare class ValkeyStorage implements IAsynchronousCacheType, IMultiIAsynchronousCacheType {
+    private valkey;
+    private options;
+    constructor(valkey: () => Valkey.default, options?: {
+        maxAge: number;
+    });
+    private errorHandler;
+    onError(listener: (error: Error) => void): void;
+    getItems<T>(keys: string[]): Promise<{
+        [key: string]: T | undefined;
+    }>;
+    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/valkey.storage.js

@@ -0,0 +1,102 @@
+export class ValkeyStorage {
+    valkey;
+    options;
+    constructor(valkey, options = { maxAge: 86400 }) {
+        this.valkey = valkey;
+        this.options = options;
+    }
+    errorHandler;
+    onError(listener) {
+        this.errorHandler = listener;
+    }
+    async getItems(keys) {
+        const mget = await this.valkey().mget(...keys);
+        const res = {};
+        mget.forEach((entry, i) => {
+            if (entry === null) {
+                res[keys[i]] = undefined; // value does not exist yet
+                return;
+            }
+            if (entry === '') {
+                res[keys[i]] = null; // value does exist, but is empty
+                return;
+            }
+            // Try to parse as JSON
+            let parsedItem = entry;
+            try {
+                if (entry) {
+                    parsedItem = JSON.parse(entry);
+                }
+            }
+            catch {
+                /** Not JSON, keep as string */
+            }
+            res[keys[i]] = parsedItem;
+        });
+        return res;
+    }
+    async setItems(values, options) {
+        const pipeline = this.valkey().pipeline();
+        values.forEach(val => {
+            if (val.content === undefined)
+                return;
+            const content = JSON.stringify(val.content);
+            const ttl = options?.ttl ?? this.options.maxAge;
+            if (ttl) {
+                pipeline.setex(val.key, ttl, content);
+            }
+            else {
+                pipeline.set(val.key, content);
+            }
+        });
+        const savePromise = pipeline.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 = await this.valkey().get(key);
+        if (entry === null) {
+            return undefined;
+        }
+        if (entry === '') {
+            return null; // value exists but is empty
+        }
+        // Try to parse as JSON
+        let parsedItem = entry;
+        try {
+            parsedItem = JSON.parse(entry);
+        }
+        catch {
+            /** Not JSON, keep as string */
+        }
+        return parsedItem;
+    }
+    async setItem(key, content, options) {
+        if (content === undefined) {
+            await this.valkey().del(key);
+            return;
+        }
+        // Serialize to string
+        const serialized = typeof content === 'object' ? JSON.stringify(content) : String(content);
+        const ttl = options?.ttl ?? this.options.maxAge;
+        const savePromise = ttl
+            ? this.valkey().setex(key, ttl, serialized)
+            : this.valkey().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.valkey().flushdb();
+    }
+}
+//# sourceMappingURL=valkey.storage.js.map

package/dist/valkey.storage.js.map

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@node-ts-cache/valkey-storage",
+  "version": "1.0.0",
+  "description": "Valkey storage adapter for node-ts-cache",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "iovalkey": "^0.2.1",
+    "@node-ts-cache/core": "1.0.1"
+  },
+  "devDependencies": {
+    "ioredis-mock": "^8.9.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/simllll/node-ts-cache.git",
+    "directory": "storages/valkey"
+  },
+  "keywords": [
+    "cache",
+    "typescript",
+    "valkey",
+    "redis-compatible"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "git clean -fdx src",
+    "dev": "tsc -p . -w",
+    "test": "vitest run"
+  }
+}