@wfp99/async-lru-cache 1.1.0 → 1.1.1

package/README.md

@@ -16,46 +16,17 @@ An asynchronous LRU (Least Recently Used) memory cache that supports asynchronou
 - 🛡️ **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?
+## 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
+- No setup required - install and use immediately
+- Zero network latency - direct memory access
+- Reduced infrastructure complexity
 
-**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
+**Reliability & Development**
+- No external dependencies or network failures
+- Simplified testing and debugging
+- Works without Redis, Memcached, or other cache servers
 
 ## Installation
 
@@ -201,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`
@@ -231,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
@@ -244,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);
@@ -285,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）記憶體快取，自動處理並發請求。
 
 ## 特色
 
@@ -9,49 +13,20 @@
 - 📝 **序列化寫入**：序列化同一 key 的 PUT 操作，確保順序執行
 - 🗑️ **LRU 淘汰策略**：實現 LRU 演算法，自動移除最久未使用的項目
 - ⏰ **TTL 支援**：支援可配置的生存時間（Time To Live），自動過期快取項目
-- 🛡️ **錯誤處理**：完善的錯誤處理機制，載入或保存失敗時自動清理快取
+- 🛡️ **錯誤處理**：完善的錯誤處理機制，失敗時自動清理快取
 - 🧹 **完整清除**：支援一次性清除所有快取項目
 
-## 為什麼選擇 AsyncLRUCache？
-
-### 問題所在
-傳統的快取解決方案在處理非同步操作時經常遇到困難：
-- **競態條件**：對同一資源的多個並發請求可能觸發重複的昂貴操作
-- **記憶體洩漏**：失敗的操作可能在快取中留下過期項目而沒有適當的清理
-- **複雜的狀態管理**：協調快取更新與外部持久化層變得容易出錯
-- **外部依賴**：許多快取解決方案需要外部服務（Redis、Memcached），增加基礎架構複雜性、網路延遲和部署成本
-
-### 解決方案
-AsyncLRUCache 透過以下方式解決這些挑戰：
-- **智慧請求合併**：對同一 key 的多個並發 GET 呼叫自動共享單一載入器執行
-- **自動錯誤恢復**：失敗的操作會自動清理，防止記憶體洩漏和過期資料
-- **操作序列化**：同一 key 的 PUT 操作會排隊並依序執行，確保資料一致性
-- **零外部依賴**：純記憶體內解決方案，無需外部快取服務，減少基礎架構複雜性、設定成本和網路延遲，同時提高可靠性和效能
-
-### 適用場景
-AsyncLRUCache 非常適合以下情境：
-- **API 回應快取**：快取昂貴的 HTTP 請求並自動去重複
-- **資料庫查詢結果**：減少資料庫負載同時維持資料一致性
-- **計算值**：快取昂貴的計算結果並內建失效機制
-- **檔案系統操作**：快取檔案讀寫並提供持久化串接
-- **微服務通訊**：透過快取減少服務間呼叫
-
-### 為什麼選擇記憶體內快取而非外部快取服務？
+## 為什麼選擇記憶體內快取而非外部快取服務？
 
 **簡單性與效能**
-- **無需設定**：安裝後立即使用，無需配置外部服務
-- **零網路延遲**：直接記憶體存取提供微秒級回應時間
-- **簡化基礎架構**：省去快取伺服器，減少營運複雜性和成本
-
-**可靠性與可預測性**
-- **無網路依賴**：快取操作不會因網路問題而失敗
-- **一致性效能**：沒有可變的網路延遲影響快取效能
-- **簡化部署**：作為應用程式的一部分部署，無需管理獨立的快取基礎架構
+- 無需設定 - 安裝後立即使用
+- 零網路延遲 - 直接記憶體存取
+- 減少基礎架構複雜性
 
-**開發效率**
-- **即時開發**：無需設定 Redis、Memcached 等即可開始編碼
-- **輕鬆測試**：單元測試無需外部服務依賴即可執行
-- **簡化除錯**：快取行為在應用程式流程內可預測且可追蹤
+**可靠性與開發**
+- 無外部依賴或網路故障風險
+- 簡化測試和除錯
+- 無需 Redis、Memcached 或其他快取伺服器
 
 ## 安裝
 
@@ -102,23 +77,6 @@ try {
 }
 ```
 
-### 進階使用
-
-```typescript
-// 與資料庫配合使用
-const cache = new AsyncLRUCache<string, UserData>({ capacity: 500 });
-
-// 從資料庫載入並自動快取
-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);
-});
-```
-
 ### TTL（生存時間）支援
 
 AsyncLRUCache 支援使用 TTL（Time To Live）自動過期快取項目：
@@ -172,6 +130,23 @@ cache.destroy();
 - 呼叫 `cleanupExpired()` 進行手動清理
 - 呼叫 `destroy()` 停止計時器並防止記憶體洩漏
 
+### 進階使用
+
+```typescript
+// 與資料庫配合使用
+const cache = new AsyncLRUCache<string, UserData>({ capacity: 500 });
+
+// 從資料庫載入並自動快取
+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);
+});
+```
+
 ### 快取管理
 
 ```typescript
@@ -197,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`
@@ -227,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
 // 這三個並發請求會共享同一個載入器執行
@@ -240,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);
@@ -274,21 +269,13 @@ const user: User = await userCache.get('user:123', async () => {
 });
 ```
 
-## 錯誤處理機制
+## 錯誤處理
 
 - **載入器失敗**：如果載入器函數拋出異常，對應的快取項目會被自動移除
 - **保存器失敗**：如果保存器函數失敗，快取項目也會被移除，確保資料一致性
-- **操作鏈錯誤**：PUT 操作會忽略前一個操作的錯誤，確保新操作能夠繼續進行
+- **操作鏈錯誤**：PUT 操作會忽略前一個操作的錯誤，允許新操作繼續進行
 - **錯誤日誌**：所有錯誤都會自動記錄到控制台，便於除錯
 
-## 記憶體管理
-
-AsyncLRUCache 具備完善的記憶體管理機制：
-
-- **自動淘汰**：當快取項目數量超過容量限制時，自動移除最久未使用的項目
-- **手動清理**：`clear()` 方法會徹底清理所有節點連結，防止記憶體洩漏
-- **錯誤清理**：操作失敗時自動清理相關快取項目
-
 ## 授權
 
 MIT

package/package.json

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