@node-ts-cache/lru-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,153 @@
+# @node-ts-cache/lru-storage
+
+[![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-storage.svg)](https://www.npmjs.org/package/@node-ts-cache/lru-storage)
+
+LRU (Least Recently Used) cache storage adapter for [@node-ts-cache/core](https://www.npmjs.com/package/@node-ts-cache/core) using [lru-cache](https://www.npmjs.com/package/lru-cache).
+
+## Features
+
+- Synchronous operations
+- Automatic eviction of least recently used items
+- Configurable maximum size (items or memory)
+- Built-in TTL support
+- Multi-get/set operations
+- Memory-safe with bounded cache size
+
+## Installation
+
+```bash
+npm install @node-ts-cache/core @node-ts-cache/lru-storage
+```
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { SyncCache, ExpirationStrategy } from '@node-ts-cache/core';
+import { LRUStorage } from '@node-ts-cache/lru-storage';
+
+const storage = new LRUStorage({
+	max: 500 // Maximum 500 items
+});
+const strategy = new ExpirationStrategy(storage);
+
+class DataService {
+	@SyncCache(strategy, { ttl: 60 })
+	getData(key: string): Data {
+		return computeExpensiveData(key);
+	}
+}
+```
+
+### With TTL
+
+```typescript
+const storage = new LRUStorage({
+	max: 1000,
+	ttl: 300 // 5 minutes in seconds
+});
+```
+
+### Memory-Based Limit
+
+```typescript
+const storage = new LRUStorage({
+	max: 500,
+	maxSize: 5000 // Maximum total "size" units
+});
+```
+
+### Async Usage
+
+```typescript
+import { Cache, ExpirationStrategy } from '@node-ts-cache/core';
+import { LRUStorage } from '@node-ts-cache/lru-storage';
+
+const storage = new LRUStorage({ max: 1000 });
+const strategy = new ExpirationStrategy(storage);
+
+class UserService {
+	@Cache(strategy, { ttl: 300 })
+	async getUser(id: string): Promise<User> {
+		return await db.users.findById(id);
+	}
+}
+```
+
+### Multi-Operations
+
+```typescript
+import { MultiCache, ExpirationStrategy } from '@node-ts-cache/core';
+import { LRUStorage } from '@node-ts-cache/lru-storage';
+
+const storage = new LRUStorage({ max: 1000 });
+const strategy = new ExpirationStrategy(storage);
+
+class ProductService {
+	@MultiCache([strategy], 0, id => `product:${id}`)
+	async getProducts(ids: string[]): Promise<Product[]> {
+		return await db.products.findByIds(ids);
+	}
+}
+```
+
+### Direct API Usage
+
+```typescript
+const storage = new LRUStorage({ max: 100 });
+const strategy = new ExpirationStrategy(storage);
+
+// Store
+strategy.setItem('key', { data: 'value' }, { ttl: 60 });
+
+// Retrieve (also marks as "recently used")
+const value = strategy.getItem<{ data: string }>('key');
+
+// Clear all
+strategy.clear();
+```
+
+## Constructor Options
+
+| Option    | Type     | Default  | Description                                 |
+| --------- | -------- | -------- | ------------------------------------------- |
+| `max`     | `number` | Required | Maximum number of items                     |
+| `ttl`     | `number` | -        | Time to live in **seconds**                 |
+| `maxSize` | `number` | -        | Maximum total size (for memory-based limit) |
+
+## Interface
+
+```typescript
+interface ISynchronousCacheType {
+	getItem<T>(key: string): T | undefined;
+	setItem(key: string, content: any, options?: any): void;
+	clear(): void;
+}
+
+interface IMultiSynchronousCacheType {
+	getItems<T>(keys: string[]): { [key: string]: T | undefined };
+	setItems(values: { key: string; content: any }[], options?: any): void;
+	clear(): void;
+}
+```
+
+## LRU Eviction
+
+When the cache reaches `max` items, the least recently accessed items are automatically evicted to make room for new ones. This makes LRU ideal for:
+
+- Memory-constrained environments
+- Hot-data caching (frequently accessed items stay cached)
+- Preventing unbounded memory growth
+
+## Dependencies
+
+- `lru-cache` ^10.0.0
+
+## Requirements
+
+- Node.js >= 18.0.0
+
+## License
+
+MIT

package/dist/LRUStorage.d.ts

@@ -0,0 +1,24 @@
+import type { IMultiSynchronousCacheType, ISynchronousCacheType } from '@node-ts-cache/core';
+import { LRUCache } from 'lru-cache';
+export interface LRUStorageOptions {
+    /** Maximum number of items in cache (required) */
+    max: number;
+    /** Time to live in seconds */
+    ttl?: number;
+    /** Maximum size (if using sizeCalculation) */
+    maxSize?: number;
+}
+export declare class LRUStorage implements ISynchronousCacheType, IMultiSynchronousCacheType {
+    myCache: LRUCache<string, any>;
+    constructor(/** ttl in seconds! */ options: LRUStorageOptions);
+    getItems<T>(keys: string[]): {
+        [key: string]: T | undefined;
+    };
+    setItems<T = unknown>(values: {
+        key: string;
+        content: T | undefined;
+    }[]): void;
+    getItem<T>(key: string): T | undefined;
+    setItem<T = unknown>(key: string, content: T | undefined): void;
+    clear(): void;
+}

package/dist/LRUStorage.js

@@ -0,0 +1,28 @@
+import { LRUCache } from 'lru-cache';
+export class LRUStorage {
+    constructor(/** ttl in seconds! */ options) {
+        this.myCache = new LRUCache({
+            max: options.max,
+            ttl: options.ttl ? options.ttl * 1000 : undefined,
+            maxSize: options.maxSize
+        });
+    }
+    getItems(keys) {
+        return Object.fromEntries(keys.map(key => [key, this.myCache.get(key)]));
+    }
+    setItems(values) {
+        values.forEach(val => {
+            this.myCache.set(val.key, val.content);
+        });
+    }
+    getItem(key) {
+        return this.myCache.get(key);
+    }
+    setItem(key, content) {
+        this.myCache.set(key, content);
+    }
+    clear() {
+        this.myCache.clear();
+    }
+}
+//# sourceMappingURL=LRUStorage.js.map

package/dist/LRUStorage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LRUStorage.js","sourceRoot":"","sources":["../src/LRUStorage.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAWrC,MAAM,OAAO,UAAU;IAKtB,YAAY,sBAAsB,CAAC,OAA0B;QAC5D,IAAI,CAAC,OAAO,GAAG,IAAI,QAAQ,CAAC;YAC3B,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,SAAS;YACjD,OAAO,EAAE,OAAO,CAAC,OAAO;SACxB,CAAC,CAAC;IACJ,CAAC;IAED,QAAQ,CAAI,IAAc;QACzB,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAEtE,CAAC;IACH,CAAC;IAED,QAAQ,CAAc,MAAiD;QACtE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;YACpB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;IACJ,CAAC;IAEM,OAAO,CAAI,GAAW;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAkB,CAAC;IAC/C,CAAC;IAEM,OAAO,CAAc,GAAW,EAAE,OAAsB;QAC9D,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC;IAEM,KAAK;QACX,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACtB,CAAC;CACD"}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,3 @@
+import { LRUStorage } from './LRUStorage.js';
+export default LRUStorage;
+//# 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,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,eAAe,UAAU,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@node-ts-cache/lru-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#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": {
+    "lru-cache": "^10.0.0",
+    "@node-ts-cache/core": "1.0.0"
+  },
+  "devDependencies": {},
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p .",
+    "clean": "git clean -fdx src",
+    "dev": "tsc -p . -w",
+    "test": "mocha --loader=ts-node/esm test/**/*.test.ts"
+  }
+}