@wfp99/async-lru-cache 1.0.0 → 1.1.0

package/README.md

@@ -12,9 +12,51 @@ An asynchronous LRU (Least Recently Used) memory cache that supports asynchronou
 - 🔄 **Automatic Merging**: Automatically merges concurrent GET requests for the same key
 - 📝 **Serialized Writes**: Serializes PUT operations for the same key to ensure execution order
 - 🗑️ **LRU Eviction**: Implements LRU algorithm to automatically remove least recently used items
+- ⏰ **TTL Support**: Automatic expiration of cache entries with configurable Time To Live
 - 🛡️ **Error Handling**: Comprehensive error handling with automatic cache cleanup on failures
 - 🧹 **Complete Clearing**: Support for clearing all cache entries at once
 
+## Why AsyncLRUCache?
+
+### The Problem
+Traditional caching solutions often struggle with asynchronous operations:
+- **Race Conditions**: Multiple concurrent requests for the same resource can trigger duplicate expensive operations
+- **Memory Leaks**: Failed operations may leave stale entries in cache without proper cleanup
+- **Complex State Management**: Coordinating cache updates with external persistence layers becomes error-prone
+- **External Dependencies**: Many caching solutions require external services (Redis, Memcached) adding infrastructure complexity, network latency, and deployment overhead
+
+### The Solution
+AsyncLRUCache addresses these challenges by providing:
+- **Smart Request Merging**: Multiple concurrent GET calls for the same key automatically share a single loader execution
+- **Automatic Error Recovery**: Failed operations are automatically cleaned up, preventing memory leaks and stale data
+- **Operation Serialization**: PUT operations for the same key are queued and executed sequentially, ensuring data consistency
+- **Zero External Dependencies**: Pure in-memory solution eliminates the need for external caching services, reducing infrastructure complexity, setup overhead, and network latency while increasing reliability and performance
+
+### When to Use
+AsyncLRUCache is perfect for scenarios involving:
+- **API Response Caching**: Cache expensive HTTP requests with automatic deduplication
+- **Database Query Results**: Reduce database load while maintaining data consistency
+- **Computed Values**: Cache expensive calculations with built-in invalidation
+- **File System Operations**: Cache file reads/writes with persistence hooks
+- **Microservices Communication**: Reduce inter-service calls with intelligent caching
+
+### Why Choose In-Memory Over External Cache Services?
+
+**Simplicity & Performance**
+- **No Setup Required**: Install and use immediately without configuring external services
+- **Zero Network Latency**: Direct memory access provides microsecond response times
+- **Reduced Infrastructure**: Eliminate cache servers, reducing operational complexity and costs
+
+**Reliability & Predictability**
+- **No Network Dependencies**: Cache operations never fail due to network issues
+- **Consistent Performance**: No variable network latency affecting cache performance
+- **Simplified Deployment**: Deploy as part of your application without managing separate cache infrastructure
+
+**Development Efficiency**
+- **Instant Development**: Start coding immediately without setting up Redis, Memcached, etc.
+- **Easy Testing**: Unit tests run without external service dependencies
+- **Simplified Debugging**: Cache behavior is predictable and traceable within your application process
+
 ## Installation
 
 ```bash
@@ -64,6 +106,59 @@ try {
 }
 ```
 
+### TTL (Time To Live) Support
+
+AsyncLRUCache supports automatic expiration of cache entries using TTL (Time To Live):
+
+```typescript
+import { AsyncLRUCache } from '@wfp99/async-lru-cache';
+
+// Create cache with TTL support
+const cache = new AsyncLRUCache({
+    capacity: 100,
+    defaultTtlMs: 5000,        // Default TTL of 5 seconds
+    cleanupIntervalMs: 10000   // Cleanup expired entries every 10 seconds
+});
+
+// Use default TTL
+const data1 = await cache.get('key1', async () => {
+    return await fetchData();
+});
+
+// Override TTL for specific entries
+const data2 = await cache.get('key2', async () => {
+    return await fetchCriticalData();
+}, 30000); // 30 seconds TTL
+
+// Put with custom TTL
+await cache.put('key3', value, async (key, val) => {
+    await saveToDb(key, val);
+}, 60000); // 1 minute TTL
+
+// Manual cleanup of expired entries
+cache.cleanupExpired();
+
+// Check if key exists and is not expired
+if (cache.has('key1')) {
+    console.log('Key exists and is valid');
+}
+
+// Get cache size
+console.log('Current cache size:', cache.size());
+
+// Destroy cache (stops cleanup timer and clears all data)
+cache.destroy();
+```
+
+#### TTL Configuration Options
+
+- **`defaultTtlMs`**: Default TTL for all cache entries (optional)
+- **`cleanupIntervalMs`**: Automatic cleanup interval for expired entries (optional)
+- Individual `get()` and `put()` methods accept TTL overrides
+- Expired entries are automatically removed during normal operations
+- Call `cleanupExpired()` for manual cleanup
+- Call `destroy()` to stop timers and prevent memory leaks
+
 ### Advanced Usage
 
 ```typescript

package/README.zh-TW.md

@@ -8,9 +8,51 @@
 - 🔄 **自動合併**：自動合併相同 key 的並發 GET 請求
 - 📝 **序列化寫入**：序列化同一 key 的 PUT 操作，確保順序執行
 - 🗑️ **LRU 淘汰策略**：實現 LRU 演算法，自動移除最久未使用的項目
+- ⏰ **TTL 支援**：支援可配置的生存時間（Time To Live），自動過期快取項目
 - 🛡️ **錯誤處理**：完善的錯誤處理機制，載入或保存失敗時自動清理快取
 - 🧹 **完整清除**：支援一次性清除所有快取項目
 
+## 為什麼選擇 AsyncLRUCache？
+
+### 問題所在
+傳統的快取解決方案在處理非同步操作時經常遇到困難：
+- **競態條件**：對同一資源的多個並發請求可能觸發重複的昂貴操作
+- **記憶體洩漏**：失敗的操作可能在快取中留下過期項目而沒有適當的清理
+- **複雜的狀態管理**：協調快取更新與外部持久化層變得容易出錯
+- **外部依賴**：許多快取解決方案需要外部服務（Redis、Memcached），增加基礎架構複雜性、網路延遲和部署成本
+
+### 解決方案
+AsyncLRUCache 透過以下方式解決這些挑戰：
+- **智慧請求合併**：對同一 key 的多個並發 GET 呼叫自動共享單一載入器執行
+- **自動錯誤恢復**：失敗的操作會自動清理，防止記憶體洩漏和過期資料
+- **操作序列化**：同一 key 的 PUT 操作會排隊並依序執行，確保資料一致性
+- **零外部依賴**：純記憶體內解決方案，無需外部快取服務，減少基礎架構複雜性、設定成本和網路延遲，同時提高可靠性和效能
+
+### 適用場景
+AsyncLRUCache 非常適合以下情境：
+- **API 回應快取**：快取昂貴的 HTTP 請求並自動去重複
+- **資料庫查詢結果**：減少資料庫負載同時維持資料一致性
+- **計算值**：快取昂貴的計算結果並內建失效機制
+- **檔案系統操作**：快取檔案讀寫並提供持久化串接
+- **微服務通訊**：透過快取減少服務間呼叫
+
+### 為什麼選擇記憶體內快取而非外部快取服務？
+
+**簡單性與效能**
+- **無需設定**：安裝後立即使用，無需配置外部服務
+- **零網路延遲**：直接記憶體存取提供微秒級回應時間
+- **簡化基礎架構**：省去快取伺服器，減少營運複雜性和成本
+
+**可靠性與可預測性**
+- **無網路依賴**：快取操作不會因網路問題而失敗
+- **一致性效能**：沒有可變的網路延遲影響快取效能
+- **簡化部署**：作為應用程式的一部分部署，無需管理獨立的快取基礎架構
+
+**開發效率**
+- **即時開發**：無需設定 Redis、Memcached 等即可開始編碼
+- **輕鬆測試**：單元測試無需外部服務依賴即可執行
+- **簡化除錯**：快取行為在應用程式流程內可預測且可追蹤
+
 ## 安裝
 
 ```bash
@@ -77,6 +119,59 @@ await cache.put(`user:${userId}`, updatedUser, async (key, value) => {
 });
 ```
 
+### TTL（生存時間）支援
+
+AsyncLRUCache 支援使用 TTL（Time To Live）自動過期快取項目：
+
+```typescript
+import { AsyncLRUCache } from '@wfp99/async-lru-cache';
+
+// 建立支援 TTL 的快取
+const cache = new AsyncLRUCache({
+    capacity: 100,
+    defaultTtlMs: 5000,        // 預設 TTL 為 5 秒
+    cleanupIntervalMs: 10000   // 每 10 秒清理過期項目
+});
+
+// 使用預設 TTL
+const data1 = await cache.get('key1', async () => {
+    return await fetchData();
+});
+
+// 為特定項目覆寫 TTL
+const data2 = await cache.get('key2', async () => {
+    return await fetchCriticalData();
+}, 30000); // 30 秒 TTL
+
+// 使用自訂 TTL 進行 Put 操作
+await cache.put('key3', value, async (key, val) => {
+    await saveToDb(key, val);
+}, 60000); // 1 分鐘 TTL
+
+// 手動清理過期項目
+cache.cleanupExpired();
+
+// 檢查 key 是否存在且未過期
+if (cache.has('key1')) {
+    console.log('Key 存在且有效');
+}
+
+// 取得快取大小
+console.log('目前快取大小:', cache.size());
+
+// 銷毀快取（停止清理計時器並清除所有資料）
+cache.destroy();
+```
+
+#### TTL 配置選項
+
+- **`defaultTtlMs`**：所有快取項目的預設 TTL（可選）
+- **`cleanupIntervalMs`**：過期項目的自動清理間隔（可選）
+- 個別的 `get()` 和 `put()` 方法接受 TTL 覆寫
+- 過期項目在正常操作期間會自動移除
+- 呼叫 `cleanupExpired()` 進行手動清理
+- 呼叫 `destroy()` 停止計時器並防止記憶體洩漏
+
 ### 快取管理
 
 ```typescript

package/dist/index.d.ts

@@ -14,6 +14,18 @@ export interface AsyncLRUCacheOption {
      * Must not be less than 10.
      */
     capacity: number;
+    /**
+     * Default time to live for cache entries in milliseconds.
+     * If not specified, entries will not expire automatically.
+     * Individual entries can override this value.
+     */
+    defaultTtlMs?: number;
+    /**
+     * Interval in milliseconds for automatic cleanup of expired entries.
+     * If not specified, cleanup will only happen during normal operations.
+     * Setting this enables periodic background cleanup.
+     */
+    cleanupIntervalMs?: number;
 }
 /**
  * Asynchronous LRU Cache class.
@@ -21,12 +33,17 @@ export interface AsyncLRUCacheOption {
  * - Supports asynchronous savers for data persistence.
  * - Automatically merges concurrent requests (get) and serializes writes (put).
  * - Implements LRU eviction strategy.
+ * - Supports TTL (Time To Live) for automatic expiration of entries.
  */
 export declare class AsyncLRUCache<K, V> {
     /**
      * Maximum capacity of the cache.
      */
     private readonly capacity;
+    /**
+     * Default TTL for cache entries in milliseconds.
+     */
+    private readonly defaultTtlMs?;
     /**
      * Map for storing cache entries. The key is the cache key, and the value is the Node.
      */
@@ -39,12 +56,28 @@ export declare class AsyncLRUCache<K, V> {
      * Tail node of the linked list, pointing to the least recently used item.
      */
     private tail;
+    /**
+     * Timer ID for periodic cleanup of expired entries.
+     */
+    private cleanupTimer?;
     /**
      * Creates an instance of AsyncLRUCache with the specified options.
      * @param option - The configuration options for the cache.
      * @throws {Error} Throws an error if the provided capacity is less than 10.
      */
     constructor(option: AsyncLRUCacheOption);
+    /**
+     * Cleans up expired entries from the cache.
+     * This method removes all nodes that have exceeded their TTL.
+     */
+    private _cleanupExpired;
+    /**
+     * Checks if a node is expired and removes it if so.
+     * @param key - The key to check.
+     * @param node - The node to check.
+     * @returns True if the node was expired and removed, false otherwise.
+     */
+    private _checkAndRemoveExpired;
     /**
      * Checks if eviction is needed according to the cache strategy.
      * When the cache exceeds its capacity, automatically removes the tail (least recently used) node.
@@ -72,18 +105,20 @@ export declare class AsyncLRUCache<K, V> {
      * Automatically merges concurrent requests for the same key.
      * @param key - Cache key.
      * @param loader - Asynchronous loader function to execute on cache miss.
+     * @param ttlMs - Optional TTL override for this entry in milliseconds.
      * @returns A Promise that resolves to the required data.
      */
-    get(key: K, loader: () => Promise<V>): Promise<V>;
+    get(key: K, loader: () => Promise<V>, ttlMs?: number): Promise<V>;
     /**
      * Puts a value into the cache, and optionally executes a saver function to persist it.
      * This method serializes multiple put operations for the same key, ensuring they execute in order.
      * @param key - Cache key.
      * @param value - Value to cache.
      * @param saver - Optional asynchronous save function.
+     * @param ttlMs - Optional TTL override for this entry in milliseconds.
      * @returns A Promise that resolves to the latest value after the saver operation completes.
      */
-    put(key: K, value: V, saver?: (key: K, value: V) => Promise<void>): Promise<V>;
+    put(key: K, value: V, saver?: (key: K, value: V) => Promise<void>, ttlMs?: number): Promise<V>;
     /**
      * Invalidates and removes the cache entry associated with the specified key.
      * @param key - The key of the cache entry to invalidate.
@@ -93,4 +128,25 @@ export declare class AsyncLRUCache<K, V> {
      * Clears the entire cache, removing all entries.
      */
     clear(): void;
+    /**
+     * Destroys the cache instance, clearing all data and stopping any background timers.
+     * Call this method when you no longer need the cache to prevent memory leaks.
+     */
+    destroy(): void;
+    /**
+     * Manually triggers cleanup of expired entries.
+     * This is useful if you want to force cleanup without waiting for the automatic interval.
+     */
+    cleanupExpired(): void;
+    /**
+     * Gets the current number of entries in the cache.
+     * @returns The number of entries currently in the cache.
+     */
+    size(): number;
+    /**
+     * Checks if a key exists in the cache and is not expired.
+     * @param key - The key to check.
+     * @returns True if the key exists and is not expired, false otherwise.
+     */
+    has(key: K): boolean;
 }

package/dist/index.js

@@ -16,8 +16,9 @@ class Node {
      * Creates a new Node instance.
      * @param key - The key associated with this node.
      * @param value - A Promise that resolves to the value of this node.
+     * @param ttlMs - Time to live in milliseconds. If provided, sets the expiration time.
      */
-    constructor(key, value) {
+    constructor(key, value, ttlMs) {
         /**
          * Reference to the next node in the linked list.
          * This property is `null` if there is no next node.
@@ -28,8 +29,23 @@ class Node {
          * This property is `null` if there is no previous node.
          */
         this.prev = null;
+        /**
+         * The timestamp when this node expires (in milliseconds).
+         * If null, the node never expires.
+         */
+        this.expiresAt = null;
         this.key = key;
         this.value = value;
+        if (ttlMs !== undefined && ttlMs > 0) {
+            this.expiresAt = Date.now() + ttlMs;
+        }
+    }
+    /**
+     * Checks if this node has expired.
+     * @returns True if the node has expired, false otherwise.
+     */
+    isExpired() {
+        return this.expiresAt !== null && Date.now() > this.expiresAt;
     }
 }
 /**
@@ -38,6 +54,7 @@ class Node {
  * - Supports asynchronous savers for data persistence.
  * - Automatically merges concurrent requests (get) and serializes writes (put).
  * - Implements LRU eviction strategy.
+ * - Supports TTL (Time To Live) for automatic expiration of entries.
  */
 class AsyncLRUCache {
     /**
@@ -61,6 +78,48 @@ class AsyncLRUCache {
         if (option.capacity < 10)
             throw new Error("Capacity must be at least 10.");
         this.capacity = option.capacity;
+        this.defaultTtlMs = option.defaultTtlMs;
+        // Setup periodic cleanup if specified
+        if (option.cleanupIntervalMs && option.cleanupIntervalMs > 0) {
+            this.cleanupTimer = setInterval(() => {
+                this._cleanupExpired();
+            }, option.cleanupIntervalMs);
+        }
+    }
+    /**
+     * Cleans up expired entries from the cache.
+     * This method removes all nodes that have exceeded their TTL.
+     */
+    _cleanupExpired() {
+        const expiredKeys = [];
+        // Collect expired keys
+        for (const [key, node] of this.dataMap) {
+            if (node.isExpired()) {
+                expiredKeys.push(key);
+            }
+        }
+        // Remove expired entries
+        for (const key of expiredKeys) {
+            const node = this.dataMap.get(key);
+            if (node) {
+                this.dataMap.delete(key);
+                this._removeNode(node);
+            }
+        }
+    }
+    /**
+     * Checks if a node is expired and removes it if so.
+     * @param key - The key to check.
+     * @param node - The node to check.
+     * @returns True if the node was expired and removed, false otherwise.
+     */
+    _checkAndRemoveExpired(key, node) {
+        if (node.isExpired()) {
+            this.dataMap.delete(key);
+            this._removeNode(node);
+            return true;
+        }
+        return false;
     }
     /**
      * Checks if eviction is needed according to the cache strategy.
@@ -116,16 +175,24 @@ class AsyncLRUCache {
      * Automatically merges concurrent requests for the same key.
      * @param key - Cache key.
      * @param loader - Asynchronous loader function to execute on cache miss.
+     * @param ttlMs - Optional TTL override for this entry in milliseconds.
      * @returns A Promise that resolves to the required data.
      */
-    get(key, loader) {
+    get(key, loader, ttlMs) {
         const node = this.dataMap.get(key);
         if (node) {
-            this._moveToHead(node);
-            return node.value;
+            // Check if the node has expired
+            if (this._checkAndRemoveExpired(key, node)) {
+                // Node was expired and removed, proceed to load fresh data
+            }
+            else {
+                this._moveToHead(node);
+                return node.value;
+            }
         }
         const loadingPromise = loader();
-        const newNode = new Node(key, loadingPromise);
+        const effectiveTtlMs = ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.defaultTtlMs;
+        const newNode = new Node(key, loadingPromise, effectiveTtlMs);
         this.dataMap.set(key, newNode);
         this._addToHead(newNode);
         this._evictIfNeeded();
@@ -144,9 +211,10 @@ class AsyncLRUCache {
      * @param key - Cache key.
      * @param value - Value to cache.
      * @param saver - Optional asynchronous save function.
+     * @param ttlMs - Optional TTL override for this entry in milliseconds.
      * @returns A Promise that resolves to the latest value after the saver operation completes.
      */
-    put(key, value, saver) {
+    put(key, value, saver, ttlMs) {
         const lastPromise = this.dataMap.has(key) ? this.dataMap.get(key).value : Promise.resolve(undefined);
         const saverPromise = lastPromise.catch((err) => {
             // Ignore previous operation errors, so the new operation can proceed.
@@ -162,14 +230,22 @@ class AsyncLRUCache {
             return value;
         });
         let node = this.dataMap.get(key);
+        const effectiveTtlMs = ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.defaultTtlMs;
         if (!node) {
-            node = new Node(key, saverPromise);
+            node = new Node(key, saverPromise, effectiveTtlMs);
             this.dataMap.set(key, node);
             this._addToHead(node);
             this._evictIfNeeded();
         }
         else {
+            // Update existing node with new value and TTL
             node.value = saverPromise;
+            if (effectiveTtlMs !== undefined && effectiveTtlMs > 0) {
+                node.expiresAt = Date.now() + effectiveTtlMs;
+            }
+            else {
+                node.expiresAt = null;
+            }
             this._moveToHead(node);
         }
         saverPromise.catch(err => {
@@ -208,11 +284,54 @@ class AsyncLRUCache {
             node.next = null;
             node.key = null;
             node.value = Promise.resolve(undefined);
+            node.expiresAt = null;
             // Move to the next node.
             node = next;
         }
         this.head = null;
         this.tail = null;
     }
+    /**
+     * Destroys the cache instance, clearing all data and stopping any background timers.
+     * Call this method when you no longer need the cache to prevent memory leaks.
+     */
+    destroy() {
+        // Stop the cleanup timer if it exists
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        // Clear all cache data
+        this.clear();
+    }
+    /**
+     * Manually triggers cleanup of expired entries.
+     * This is useful if you want to force cleanup without waiting for the automatic interval.
+     */
+    cleanupExpired() {
+        this._cleanupExpired();
+    }
+    /**
+     * Gets the current number of entries in the cache.
+     * @returns The number of entries currently in the cache.
+     */
+    size() {
+        return this.dataMap.size;
+    }
+    /**
+     * Checks if a key exists in the cache and is not expired.
+     * @param key - The key to check.
+     * @returns True if the key exists and is not expired, false otherwise.
+     */
+    has(key) {
+        const node = this.dataMap.get(key);
+        if (!node) {
+            return false;
+        }
+        if (this._checkAndRemoveExpired(key, node)) {
+            return false;
+        }
+        return true;
+    }
 }
 exports.AsyncLRUCache = AsyncLRUCache;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wfp99/async-lru-cache",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"description": "A simple memory cache using the LRU algorithm and supporting asynchronous data access.",
 	"keywords": [
 		"cache",