@wfp99/async-lru-cache 1.0.0 → 1.1.1

package/README.md

@@ -12,9 +12,22 @@ 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 Choose In-Memory Over External Cache Services?
+
+**Simplicity & Performance**
+- No setup required - install and use immediately
+- Zero network latency - direct memory access
+- Reduced infrastructure complexity
+
+**Reliability & Development**
+- No external dependencies or network failures
+- Simplified testing and debugging
+- Works without Redis, Memcached, or other cache servers
+
 ## Installation
 
 ```bash
@@ -64,6 +77,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
@@ -106,24 +172,28 @@ constructor(option: AsyncLRUCacheOption)
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
 | `capacity` | `number` | Yes | Maximum number of items allowed in cache. Must be a positive number. |
+| `defaultTtlMs` | `number` | No | Default TTL for all cache entries (optional) |
+| `cleanupIntervalMs` | `number` | No | Automatic cleanup interval for expired entries (optional) |
 
 #### Methods
 
-##### `get(key: K, loader: () => Promise<V>): Promise<V>`
+##### `get(key: K, loader: () => Promise<V>, ttlMs?: number): Promise<V>`
 
 Retrieves data from cache. If not found, uses the loader to load data.
 
 - **key**: Cache key
 - **loader**: Asynchronous loader function executed on cache miss
+- **ttlMs**: Optional TTL override for this entry
 - **Returns**: Promise that resolves to the required data
 
-##### `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>`
 
 Puts a value into cache and optionally executes a saver function for persistence.
 
 - **key**: Cache key
 - **value**: Value to cache
 - **saver**: Optional asynchronous saver function
+- **ttlMs**: Optional TTL override for this entry
 - **Returns**: Promise that resolves to the latest value after saver operation completes
 
 ##### `invalidate(key: K): void`
@@ -136,11 +206,33 @@ Invalidates and removes the cache entry for the specified key.
 
 Clears all cache entries. This method removes all items from cache and manually clears node links to prevent potential memory leaks.
 
+##### `has(key: K): boolean`
+
+Checks if a key exists in cache and is not expired.
+
+- **key**: Cache key to check
+- **Returns**: True if key exists and is valid
+
+##### `size(): number`
+
+Returns the current number of items in cache.
+
+- **Returns**: Number of cached items
+
+##### `cleanupExpired(): void`
+
+Manually removes expired entries from cache.
+
+##### `destroy(): void`
+
+Destroys the cache, stops cleanup timers and clears all data.
+
 ## Concurrency Handling
 
-### GET Request Merging
+AsyncLRUCache automatically handles concurrent operations:
 
-When multiple concurrent requests fetch the same key, AsyncLRUCache automatically merges these requests, ensuring the loader function executes only once:
+- **GET Request Merging**: Multiple concurrent requests for the same key share a single loader execution
+- **PUT Operation Serialization**: Multiple PUT operations for the same key are serialized to ensure they execute in order
 
 ```typescript
 // These three concurrent requests will share the same loader execution
@@ -149,13 +241,7 @@ const [data1, data2, data3] = await Promise.all([
     cache.get('shared-key', loader),
     cache.get('shared-key', loader)
 ]);
-```
-
-### PUT Operation Serialization
 
-Multiple PUT operations for the same key are serialized to ensure they execute in order:
-
-```typescript
 // These operations will execute sequentially, even if started concurrently
 cache.put('key', 'value1', saver1);
 cache.put('key', 'value2', saver2);
@@ -190,14 +276,6 @@ const user: User = await userCache.get('user:123', async () => {
 - **Operation Chain Errors**: PUT operations ignore previous operation errors, allowing new operations to proceed
 - **Error Logging**: All errors are automatically logged to console for debugging
 
-## Memory Management
-
-AsyncLRUCache provides comprehensive memory management:
-
-- **Automatic Eviction**: Automatically removes least recently used items based on capacity
-- **Manual Cleanup**: `clear()` method thoroughly cleans all node links to prevent memory leaks
-- **Error Cleanup**: Automatically cleans related cache entries when operations fail
-
 ## License
 
 MIT

package/README.zh-TW.md

@@ -1,6 +1,10 @@
 # Async LRU Cache
 
-一個支援非同步載入和保存操作的 LRU（Least Recently Used）記憶體快取類別，自動處理並發請求。
+[![npm version](https://badge.fury.io/js/@wfp99%2Fasync-lru-cache.svg)](https://badge.fury.io/js/@wfp99%2Fasync-lru-cache)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen.svg)](https://nodejs.org/)
+
+一個支援非同步載入和保存操作的 LRU（Least Recently Used）記憶體快取，自動處理並發請求。
 
 ## 特色
 
@@ -8,9 +12,22 @@
 - 🔄 **自動合併**：自動合併相同 key 的並發 GET 請求
 - 📝 **序列化寫入**：序列化同一 key 的 PUT 操作，確保順序執行
 - 🗑️ **LRU 淘汰策略**：實現 LRU 演算法，自動移除最久未使用的項目
-- 🛡️ **錯誤處理**：完善的錯誤處理機制，載入或保存失敗時自動清理快取
+- ⏰ **TTL 支援**：支援可配置的生存時間（Time To Live），自動過期快取項目
+- 🛡️ **錯誤處理**：完善的錯誤處理機制，失敗時自動清理快取
 - 🧹 **完整清除**：支援一次性清除所有快取項目
 
+## 為什麼選擇記憶體內快取而非外部快取服務？
+
+**簡單性與效能**
+- 無需設定 - 安裝後立即使用
+- 零網路延遲 - 直接記憶體存取
+- 減少基礎架構複雜性
+
+**可靠性與開發**
+- 無外部依賴或網路故障風險
+- 簡化測試和除錯
+- 無需 Redis、Memcached 或其他快取伺服器
+
 ## 安裝
 
 ```bash
@@ -60,6 +77,59 @@ try {
 }
 ```
 
+### 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
@@ -71,7 +141,7 @@ const user = await cache.get(`user:${userId}`, async () => {
     return await database.users.findById(userId);
 });
 
-// 同時儲存到快取和資料庫
+// 原子性地保存到快取和資料庫
 await cache.put(`user:${userId}`, updatedUser, async (key, value) => {
     await database.users.update(userId, value);
 });
@@ -102,24 +172,28 @@ constructor(option: AsyncLRUCacheOption)
 | 屬性 | 類型 | 必需 | 描述 |
 |-----|------|------|------|
 | `capacity` | `number` | 是 | 快取中允許的最大項目數量，必須為正數 |
+| `defaultTtlMs` | `number` | 否 | 所有快取項目的預設 TTL（可選） |
+| `cleanupIntervalMs` | `number` | 否 | 過期項目的自動清理間隔（可選） |
 
 #### 方法
 
-##### `get(key: K, loader: () => Promise<V>): Promise<V>`
+##### `get(key: K, loader: () => Promise<V>, ttlMs?: number): Promise<V>`
 
 從快取中獲取資料。如果不存在，使用載入器載入資料。
 
 - **key**: 快取鍵
 - **loader**: 快取未命中時執行的非同步載入函數
+- **ttlMs**: 此項目的可選 TTL 覆寫
 - **回傳**: Promise，解析為所需的資料
 
-##### `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>`
 
 將值放入快取中，並可選擇性地執行保存器函數進行持久化。
 
 - **key**: 快取鍵
 - **value**: 要快取的值
 - **saver**: 可選的非同步保存函數
+- **ttlMs**: 此項目的可選 TTL 覆寫
 - **回傳**: Promise，解析為保存操作完成後的最新值
 
 ##### `invalidate(key: K): void`
@@ -132,11 +206,33 @@ constructor(option: AsyncLRUCacheOption)
 
 清除所有快取項目。此方法會移除快取中的所有項目並手動清理節點連結以避免潛在的記憶體洩漏。
 
+##### `has(key: K): boolean`
+
+檢查快取中是否存在指定鍵且未過期。
+
+- **key**: 要檢查的快取鍵
+- **回傳**: 如果鍵存在且有效則回傳 true
+
+##### `size(): number`
+
+回傳快取中目前的項目數量。
+
+- **回傳**: 快取項目的數量
+
+##### `cleanupExpired(): void`
+
+手動從快取中移除過期項目。
+
+##### `destroy(): void`
+
+銷毀快取，停止清理計時器並清除所有資料。
+
 ## 並發處理
 
-### GET 請求合併
+AsyncLRUCache 會自動處理並發操作：
 
-當多個並發請求獲取相同的 key 時，AsyncLRUCache 會自動合併這些請求，確保載入器函數只執行一次：
+- **GET 請求合併**：對同一 key 的多個並發請求會共享單一載入器執行
+- **PUT 操作序列化**：對同一 key 的多個 PUT 操作會序列化執行以確保順序
 
 ```typescript
 // 這三個並發請求會共享同一個載入器執行
@@ -145,13 +241,7 @@ const [data1, data2, data3] = await Promise.all([
     cache.get('shared-key', loader),
     cache.get('shared-key', loader)
 ]);
-```
-
-### PUT 操作序列化
 
-對同一 key 的多個 PUT 操作會被序列化，確保它們按順序執行：
-
-```typescript
 // 這些操作會按順序執行，即使它們是並發啟動的
 cache.put('key', 'value1', saver1);
 cache.put('key', 'value2', saver2);
@@ -179,21 +269,13 @@ const user: User = await userCache.get('user:123', async () => {
 });
 ```
 
-## 錯誤處理機制
+## 錯誤處理
 
 - **載入器失敗**：如果載入器函數拋出異常，對應的快取項目會被自動移除
 - **保存器失敗**：如果保存器函數失敗，快取項目也會被移除，確保資料一致性
-- **操作鏈錯誤**：PUT 操作會忽略前一個操作的錯誤，確保新操作能夠繼續進行
+- **操作鏈錯誤**：PUT 操作會忽略前一個操作的錯誤，允許新操作繼續進行
 - **錯誤日誌**：所有錯誤都會自動記錄到控制台，便於除錯
 
-## 記憶體管理
-
-AsyncLRUCache 具備完善的記憶體管理機制：
-
-- **自動淘汰**：當快取項目數量超過容量限制時，自動移除最久未使用的項目
-- **手動清理**：`clear()` 方法會徹底清理所有節點連結，防止記憶體洩漏
-- **錯誤清理**：操作失敗時自動清理相關快取項目
-
 ## 授權
 
 MIT

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.1",
 	"description": "A simple memory cache using the LRU algorithm and supporting asynchronous data access.",
 	"keywords": [
 		"cache",