@wfp99/async-lru-cache 1.1.0 → 1.2.0

package/README.md

@@ -4,58 +4,17 @@
 [![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/)
 
-An asynchronous LRU (Least Recently Used) memory cache that supports asynchronous loading and saving operations while automatically handling concurrent requests.
+An in-memory LRU (Least Recently Used) cache for Node.js and TypeScript, with support for asynchronous loading, saving, and automatic deduplication of concurrent requests.
 
 ## Features
 
-- 🚀 **Async Support**: Supports asynchronous loader and saver functions
-- 🔄 **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
+- Asynchronous loader (`get`) and saver (`put`) functions
+- Concurrent `get()` calls for the same key share a single loader execution
+- `put()` calls for the same key are serialized and execute in order
+- LRU eviction once the configured capacity is exceeded
+- Optional per-entry TTL (time to live), with optional periodic background cleanup
+- Configurable error handling via `onError`, defaulting to console logging
+- `get()` can be called without a loader for a read-only lookup, and `peek()` for a lookup that never affects LRU order
 
 ## Installation
 
@@ -69,229 +28,122 @@ npm install @wfp99/async-lru-cache
 
 ## Usage
 
-### Basic Usage
+### Basic usage
 
 ```typescript
 import { AsyncLRUCache } from '@wfp99/async-lru-cache';
 
-// Create a cache with maximum 100 items
-const cache = new AsyncLRUCache({
-    capacity: 100
-});
+const cache = new AsyncLRUCache<string, User>({ capacity: 100 });
 
-// Use get method to retrieve data
-const data = await cache.get('user:123', async () => {
-    // Loader function executed on cache miss
-    const response = await fetch('/api/users/123');
-    return response.json();
+// get() calls the loader on a cache miss and caches the resolved value.
+const user = await cache.get('user:123', async () => {
+  const response = await fetch('/api/users/123');
+  return response.json();
 });
 
-// Use put method to store data
+// put() stores a value directly and optionally persists it via a saver.
 await cache.put('user:456', userData, async (key, value) => {
-    // Optional saver function for data persistence
-    await saveToDatabase(key, value);
+  await saveToDatabase(key, value);
 });
 ```
 
-### Error Handling
+### Read-only lookups
 
 ```typescript
-try {
-    const data = await cache.get('problematic-key', async () => {
-        throw new Error('Load failed');
-    });
-} catch (error) {
-    console.error('Cache load failed:', error);
-    // Failed items are automatically removed from cache
-}
-```
+// get() without a loader performs a read-only lookup: on a hit it behaves like a
+// normal get() (and updates LRU order); on a miss it resolves to undefined without
+// adding anything to the cache or affecting LRU order.
+const cached = await cache.get('user:123'); // User | undefined
 
-### TTL (Time To Live) Support
+// peek() never affects LRU order, whether it is a hit or a miss.
+const peeked = await cache.peek('user:123'); // Promise<User> | undefined
+```
 
-AsyncLRUCache supports automatic expiration of cache entries using TTL (Time To Live):
+### 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();
+  capacity: 100,
+  defaultTtlMs: 5000,       // default TTL applied to every entry
+  cleanupIntervalMs: 10000, // periodic background cleanup of expired entries
 });
 
-// Override TTL for specific entries
-const data2 = await cache.get('key2', async () => {
-    return await fetchCriticalData();
-}, 30000); // 30 seconds TTL
+// Override the default TTL for a specific entry.
+await cache.get('key1', async () => fetchData(), 30000);
 
-// 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();
+cache.has('key1');        // false once the entry has expired
+cache.cleanupExpired();   // manually remove expired entries
+cache.destroy();          // stop the cleanup timer and clear all data
 ```
 
-#### 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
+### Concurrency handling
 
 ```typescript
-// Working with database
-const cache = new AsyncLRUCache<string, UserData>({ capacity: 500 });
-
-// Load from database with automatic caching
-const user = await cache.get(`user:${userId}`, async () => {
-    return await database.users.findById(userId);
-});
+// These concurrent get() calls share a single loader execution.
+const [a, b, c] = await Promise.all([
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+]);
 
-// Save to cache and database atomically
-await cache.put(`user:${userId}`, updatedUser, async (key, value) => {
-    await database.users.update(userId, value);
-});
+// These put() calls execute sequentially, even though they are started concurrently.
+cache.put('key', 'value1', saver1);
+cache.put('key', 'value2', saver2);
+cache.put('key', 'value3', saver3);
 ```
 
-### Cache Management
+### Error handling
 
-```typescript
-// Manually remove specific cache entry
-cache.invalidate('user:123');
+- If a loader (`get`) throws, the entry is removed from the cache and the rejection propagates to the caller.
+- If a saver (`put`) throws, the entry is also removed to avoid caching an unpersisted value.
+- A `put()` call ignores the failure of a previous, already-settled operation on the same key, so it can still proceed.
+- By default, these failures are logged with `console.error`/`console.warn`. Provide `onError` to handle them yourself instead:
 
-// Clear all cache entries
-cache.clear();
+```typescript
+const cache = new AsyncLRUCache({
+  capacity: 100,
+  onError(error, { key, source }) {
+    // source is 'loader' | 'saver' | 'put-chain'
+    myLogger.error(`cache ${source} failed for ${key}`, error);
+  },
+});
 ```
 
 ## API Reference
 
 ### `AsyncLRUCache<K, V>`
 
-#### Constructor
-
 ```typescript
-constructor(option: AsyncLRUCacheOption)
+constructor(option: AsyncLRUCacheOption<K>)
 ```
 
-#### `AsyncLRUCacheOption`
+#### `AsyncLRUCacheOption<K>`
 
 | Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| `capacity` | `number` | Yes | Maximum number of items allowed in cache. Must be a positive number. |
+|---|---|---|---|
+| `capacity` | `number` | Yes | Maximum number of items allowed in the cache. Must be at least 10. |
+| `defaultTtlMs` | `number` | No | Default TTL applied to entries that don't specify their own. |
+| `cleanupIntervalMs` | `number` | No | Interval for automatic background cleanup of expired entries. |
+| `onError` | `(error: unknown, context: { key: K; source: 'loader' \| 'saver' \| 'put-chain' }) => void` | No | Callback for loader/saver failures. Replaces the default console logging when provided. |
 
 #### Methods
 
-##### `get(key: K, loader: () => Promise<V>): 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
-- **Returns**: Promise that resolves to the required data
-
-##### `put(key: K, value: V, saver?: (key: K, value: V) => Promise<void>): 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
-- **Returns**: Promise that resolves to the latest value after saver operation completes
-
-##### `invalidate(key: K): void`
+| Method | Description |
+|---|---|
+| `get(key, loader, ttlMs?)` | Returns the cached value, or calls `loader()` on a miss and caches the result. |
+| `get(key)` | Read-only lookup without a loader. On a hit, behaves like the overload above (updates LRU order). On a miss, resolves to `undefined` without touching the cache. |
+| `peek(key)` | Returns the cached value's `Promise<V>`, or `undefined` if missing/expired. Never affects LRU order, even on a hit. |
+| `put(key, value, saver?, ttlMs?)` | Stores `value` and optionally awaits `saver(key, value)` to persist it. |
+| `invalidate(key)` | Removes the entry for `key`, if present. |
+| `clear()` | Removes all entries. |
+| `has(key)` | Returns whether `key` exists and has not expired. Expired entries are evicted as a side effect of this check; it does not affect LRU order. |
+| `size()` | Returns the current number of entries. |
+| `cleanupExpired()` | Immediately removes all expired entries. |
+| `destroy()` | Stops the cleanup timer (if any) and clears all data. |
 
-Invalidates and removes the cache entry for the specified key.
+## TypeScript
 
-- **key**: Cache key to invalidate
-
-##### `clear(): void`
-
-Clears all cache entries. This method removes all items from cache and manually clears node links to prevent potential memory leaks.
-
-## Concurrency Handling
-
-### GET Request Merging
-
-When multiple concurrent requests fetch the same key, AsyncLRUCache automatically merges these requests, ensuring the loader function executes only once:
-
-```typescript
-// These three concurrent requests will share the same loader execution
-const [data1, data2, data3] = await Promise.all([
-    cache.get('shared-key', loader),
-    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);
-cache.put('key', 'value3', saver3);
-```
-
-## TypeScript Support
-
-This package is fully written in TypeScript and provides complete type support:
-
-```typescript
-interface User {
-    id: string;
-    name: string;
-    email: string;
-}
-
-const userCache = new AsyncLRUCache<string, User>({
-    capacity: 1000
-});
-
-const user: User = await userCache.get('user:123', async () => {
-    // Loader must return User type
-    return fetchUserFromAPI('123');
-});
-```
-
-## Error Handling
-
-- **Loader Failures**: If loader function throws an exception, corresponding cache entry is automatically removed
-- **Saver Failures**: If saver function fails, cache entry is also removed to ensure data consistency
-- **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
+This package is written in TypeScript and ships with type declarations; no separate `@types` package is required.
 
 ## License
 
@@ -301,6 +153,3 @@ MIT
 
 Issues and pull requests are welcome on [GitHub](https://github.com/wfp99/async-lru-cache).
 
-## Author
-
-Wang Feng Ping

package/README.zh-TW.md

@@ -1,57 +1,20 @@
 # 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）記憶體快取，適用於 Node.js 與 TypeScript。
 
 ## 特色
 
-- 🚀 **非同步支援**：支援非同步的載入器（loader）和保存器（saver）函數
-- 🔄 **自動合併**：自動合併相同 key 的並發 GET 請求
-- 📝 **序列化寫入**：序列化同一 key 的 PUT 操作，確保順序執行
-- 🗑️ **LRU 淘汰策略**：實現 LRU 演算法，自動移除最久未使用的項目
-- ⏰ **TTL 支援**：支援可配置的生存時間（Time To Live），自動過期快取項目
-- 🛡️ **錯誤處理**：完善的錯誤處理機制，載入或保存失敗時自動清理快取
-- 🧹 **完整清除**：支援一次性清除所有快取項目
-
-## 為什麼選擇 AsyncLRUCache？
-
-### 問題所在
-傳統的快取解決方案在處理非同步操作時經常遇到困難：
-- **競態條件**：對同一資源的多個並發請求可能觸發重複的昂貴操作
-- **記憶體洩漏**：失敗的操作可能在快取中留下過期項目而沒有適當的清理
-- **複雜的狀態管理**：協調快取更新與外部持久化層變得容易出錯
-- **外部依賴**：許多快取解決方案需要外部服務（Redis、Memcached），增加基礎架構複雜性、網路延遲和部署成本
-
-### 解決方案
-AsyncLRUCache 透過以下方式解決這些挑戰：
-- **智慧請求合併**：對同一 key 的多個並發 GET 呼叫自動共享單一載入器執行
-- **自動錯誤恢復**：失敗的操作會自動清理，防止記憶體洩漏和過期資料
-- **操作序列化**：同一 key 的 PUT 操作會排隊並依序執行，確保資料一致性
-- **零外部依賴**：純記憶體內解決方案，無需外部快取服務，減少基礎架構複雜性、設定成本和網路延遲，同時提高可靠性和效能
-
-### 適用場景
-AsyncLRUCache 非常適合以下情境：
-- **API 回應快取**：快取昂貴的 HTTP 請求並自動去重複
-- **資料庫查詢結果**：減少資料庫負載同時維持資料一致性
-- **計算值**：快取昂貴的計算結果並內建失效機制
-- **檔案系統操作**：快取檔案讀寫並提供持久化串接
-- **微服務通訊**：透過快取減少服務間呼叫
-
-### 為什麼選擇記憶體內快取而非外部快取服務？
-
-**簡單性與效能**
-- **無需設定**：安裝後立即使用，無需配置外部服務
-- **零網路延遲**：直接記憶體存取提供微秒級回應時間
-- **簡化基礎架構**：省去快取伺服器，減少營運複雜性和成本
-
-**可靠性與可預測性**
-- **無網路依賴**：快取操作不會因網路問題而失敗
-- **一致性效能**：沒有可變的網路延遲影響快取效能
-- **簡化部署**：作為應用程式的一部分部署，無需管理獨立的快取基礎架構
-
-**開發效率**
-- **即時開發**：無需設定 Redis、Memcached 等即可開始編碼
-- **輕鬆測試**：單元測試無需外部服務依賴即可執行
-- **簡化除錯**：快取行為在應用程式流程內可預測且可追蹤
+- 支援非同步的載入器（loader）與保存器（saver）函數
+- 對同一 key 的並發 `get()` 呼叫共用單一載入器執行
+- 對同一 key 的多個 `put()` 呼叫會序列化並依序執行
+- 超出設定容量時自動執行 LRU 淘汰
+- 支援每筆項目的可選 TTL（存活時間），並可設定週期性背景清理
+- 可透過 `onError` 自訂錯誤處理，預設為記錄到 console
+- `get()` 可省略 loader 進行唯讀查詢；`peek()` 則提供完全不影響 LRU 順序的查詢方式
 
 ## 安裝
 
@@ -70,224 +33,116 @@ npm install @wfp99/async-lru-cache
 ```typescript
 import { AsyncLRUCache } from '@wfp99/async-lru-cache';
 
-// 創建一個最多容納 100 個項目的快取
-const cache = new AsyncLRUCache({
-    capacity: 100
-});
+const cache = new AsyncLRUCache<string, User>({ capacity: 100 });
 
-// 使用 get 方法獲取資料
-const data = await cache.get('user:123', async () => {
-    // 快取未命中時執行的載入器函數
-    const response = await fetch('/api/users/123');
-    return response.json();
+// get() 在快取未命中時呼叫 loader，並快取其回傳值。
+const user = await cache.get('user:123', async () => {
+  const response = await fetch('/api/users/123');
+  return response.json();
 });
 
-// 使用 put 方法儲存資料
+// put() 直接儲存值，並可選擇透過 saver 進行持久化。
 await cache.put('user:456', userData, async (key, value) => {
-    // 可選的保存器函數，用於持久化資料
-    await saveToDatabase(key, value);
+  await saveToDatabase(key, value);
 });
 ```
 
-### 錯誤處理
+### 唯讀查詢
 
 ```typescript
-try {
-    const data = await cache.get('problematic-key', async () => {
-        throw new Error('載入失敗');
-    });
-} catch (error) {
-    console.error('快取載入失敗:', error);
-    // 失敗的項目會自動從快取中移除
-}
-```
+// 省略 loader 的 get() 屬於唯讀查詢：命中時行為與一般 get() 相同（會更新 LRU 順序）；
+// 未命中時回傳 undefined，且不會新增任何項目或影響 LRU 順序。
+const cached = await cache.get('user:123'); // User | undefined
 
-### 進階使用
-
-```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);
-});
+// peek() 無論命中或未命中都不會影響 LRU 順序。
+const peeked = await cache.peek('user:123'); // Promise<User> | undefined
 ```
 
-### TTL（生存時間）支援
-
-AsyncLRUCache 支援使用 TTL（Time To Live）自動過期快取項目：
+### TTL（存活時間）
 
 ```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();
+  capacity: 100,
+  defaultTtlMs: 5000,       // 套用到每筆項目的預設 TTL
+  cleanupIntervalMs: 10000, // 週期性背景清理過期項目
 });
 
-// 為特定項目覆寫 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
+// 為特定項目覆寫預設 TTL。
+await cache.get('key1', async () => fetchData(), 30000);
 
-// 手動清理過期項目
-cache.cleanupExpired();
+cache.has('key1');        // 項目過期後回傳 false
+cache.cleanupExpired();   // 手動移除過期項目
+cache.destroy();          // 停止清理計時器並清除所有資料
+```
 
-// 檢查 key 是否存在且未過期
-if (cache.has('key1')) {
-    console.log('Key 存在且有效');
-}
+### 並發處理
 
-// 取得快取大小
-console.log('目前快取大小:', cache.size());
+```typescript
+// 以下並發的 get() 呼叫會共用同一個 loader 執行。
+const [a, b, c] = await Promise.all([
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+]);
 
-// 銷毀快取（停止清理計時器並清除所有資料）
-cache.destroy();
+// 以下 put() 呼叫即使並發啟動，也會依序序列化執行。
+cache.put('key', 'value1', saver1);
+cache.put('key', 'value2', saver2);
+cache.put('key', 'value3', saver3);
 ```
 
-#### TTL 配置選項
-
-- **`defaultTtlMs`**：所有快取項目的預設 TTL（可選）
-- **`cleanupIntervalMs`**：過期項目的自動清理間隔（可選）
-- 個別的 `get()` 和 `put()` 方法接受 TTL 覆寫
-- 過期項目在正常操作期間會自動移除
-- 呼叫 `cleanupExpired()` 進行手動清理
-- 呼叫 `destroy()` 停止計時器並防止記憶體洩漏
+### 錯誤處理
 
-### 快取管理
+- 若載入器（`get`）拋出例外，該項目會從快取中移除，錯誤會傳遞給呼叫端。
+- 若保存器（`put`）拋出例外，該項目也會被移除，避免快取到尚未持久化的值。
+- `put()` 會忽略同一 key 前一個已結束操作的失敗，讓新的操作可以繼續進行。
+- 預設情況下，上述失敗會透過 `console.error`/`console.warn` 記錄。若要自行處理，可提供 `onError`：
 
 ```typescript
-// 手動移除特定快取項目
-cache.invalidate('user:123');
-
-// 清除所有快取項目
-cache.clear();
+const cache = new AsyncLRUCache({
+  capacity: 100,
+  onError(error, { key, source }) {
+    // source 為 'loader' | 'saver' | 'put-chain'
+    myLogger.error(`cache ${source} failed for ${key}`, error);
+  },
+});
 ```
 
 ## API 參考
 
 ### `AsyncLRUCache<K, V>`
 
-#### 建構函數
-
 ```typescript
-constructor(option: AsyncLRUCacheOption)
+constructor(option: AsyncLRUCacheOption<K>)
 ```
 
-#### `AsyncLRUCacheOption`
+#### `AsyncLRUCacheOption<K>`
 
 | 屬性 | 類型 | 必需 | 描述 |
-|-----|------|------|------|
-| `capacity` | `number` | 是 | 快取中允許的最大項目數量，必須為正數 |
+|---|---|---|---|
+| `capacity` | `number` | 是 | 快取中允許的最大項目數量，最小值為 10 |
+| `defaultTtlMs` | `number` | 否 | 套用到未指定 TTL 之項目的預設 TTL |
+| `cleanupIntervalMs` | `number` | 否 | 自動背景清理過期項目的執行間隔 |
+| `onError` | `(error: unknown, context: { key: K; source: 'loader' \| 'saver' \| 'put-chain' }) => void` | 否 | 載入器/保存器失敗時的回呼函數。提供後將取代預設的 console 記錄行為 |
 
 #### 方法
 
-##### `get(key: K, loader: () => Promise<V>): Promise<V>`
-
-從快取中獲取資料。如果不存在，使用載入器載入資料。
-
-- **key**: 快取鍵
-- **loader**: 快取未命中時執行的非同步載入函數
-- **回傳**: Promise，解析為所需的資料
-
-##### `put(key: K, value: V, saver?: (key: K, value: V) => Promise<void>): Promise<V>`
-
-將值放入快取中，並可選擇性地執行保存器函數進行持久化。
+| 方法 | 描述 |
+|---|---|
+| `get(key, loader, ttlMs?)` | 回傳快取值；未命中時呼叫 `loader()` 並快取其結果 |
+| `get(key)` | 省略 loader 的唯讀查詢。命中時行為與上方多載相同（會更新 LRU 順序）；未命中時回傳 `undefined`，不會異動快取 |
+| `peek(key)` | 回傳快取值的 `Promise<V>`；若不存在或已過期則回傳 `undefined`。無論命中與否都不影響 LRU 順序 |
+| `put(key, value, saver?, ttlMs?)` | 儲存 `value`，並可選擇等待 `saver(key, value)` 進行持久化 |
+| `invalidate(key)` | 若存在，移除 `key` 對應的項目 |
+| `clear()` | 移除所有項目 |
+| `has(key)` | 回傳 `key` 是否存在且未過期。此檢查會順帶清除已過期的項目，但不影響 LRU 順序 |
+| `size()` | 回傳目前的項目數量 |
+| `cleanupExpired()` | 立即移除所有過期項目 |
+| `destroy()` | 停止清理計時器（若有）並清除所有資料 |
 
-- **key**: 快取鍵
-- **value**: 要快取的值
-- **saver**: 可選的非同步保存函數
-- **回傳**: Promise，解析為保存操作完成後的最新值
+## TypeScript
 
-##### `invalidate(key: K): void`
-
-使指定鍵的快取項目失效並移除。
-
-- **key**: 要失效的快取鍵
-
-##### `clear(): void`
-
-清除所有快取項目。此方法會移除快取中的所有項目並手動清理節點連結以避免潛在的記憶體洩漏。
-
-## 並發處理
-
-### GET 請求合併
-
-當多個並發請求獲取相同的 key 時，AsyncLRUCache 會自動合併這些請求，確保載入器函數只執行一次：
-
-```typescript
-// 這三個並發請求會共享同一個載入器執行
-const [data1, data2, data3] = await Promise.all([
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader)
-]);
-```
-
-### PUT 操作序列化
-
-對同一 key 的多個 PUT 操作會被序列化，確保它們按順序執行：
-
-```typescript
-// 這些操作會按順序執行，即使它們是並發啟動的
-cache.put('key', 'value1', saver1);
-cache.put('key', 'value2', saver2);
-cache.put('key', 'value3', saver3);
-```
-
-## TypeScript 支援
-
-此套件完全使用 TypeScript 編寫，提供完整的型別支援：
-
-```typescript
-interface User {
-    id: string;
-    name: string;
-    email: string;
-}
-
-const userCache = new AsyncLRUCache<string, User>({
-    capacity: 1000
-});
-
-const user: User = await userCache.get('user:123', async () => {
-    // 載入器必須回傳 User 型別
-    return fetchUserFromAPI('123');
-});
-```
-
-## 錯誤處理機制
-
-- **載入器失敗**：如果載入器函數拋出異常，對應的快取項目會被自動移除
-- **保存器失敗**：如果保存器函數失敗，快取項目也會被移除，確保資料一致性
-- **操作鏈錯誤**：PUT 操作會忽略前一個操作的錯誤，確保新操作能夠繼續進行
-- **錯誤日誌**：所有錯誤都會自動記錄到控制台，便於除錯
-
-## 記憶體管理
-
-AsyncLRUCache 具備完善的記憶體管理機制：
-
-- **自動淘汰**：當快取項目數量超過容量限制時，自動移除最久未使用的項目
-- **手動清理**：`clear()` 方法會徹底清理所有節點連結，防止記憶體洩漏
-- **錯誤清理**：操作失敗時自動清理相關快取項目
+此套件以 TypeScript 撰寫並內建型別宣告檔，無需另外安裝 `@types` 套件。
 
 ## 授權
 
@@ -297,6 +152,3 @@ MIT
 
 歡迎在 [GitHub](https://github.com/wfp99/async-lru-cache) 上提出問題和發送 Pull Request。
 
-## 作者
-
-Wang Feng Ping

package/dist/index.d.ts

@@ -5,10 +5,31 @@
  *
  * @module AsyncLRUCache
  */
+/**
+ * Identifies which internal operation produced an error passed to `AsyncLRUCacheOption.onError`.
+ * - `loader`: The loader function passed to `get()` rejected.
+ * - `saver`: The saver function passed to `put()` rejected.
+ * - `put-chain`: A previous (already-settled) operation for the same key failed; this is a
+ *   recoverable warning, since the new `put()` operation is still allowed to proceed.
+ */
+export type AsyncLRUCacheErrorSource = 'loader' | 'saver' | 'put-chain';
+/**
+ * Context information supplied alongside an error to `AsyncLRUCacheOption.onError`.
+ */
+export interface AsyncLRUCacheErrorContext<K> {
+    /**
+     * The cache key associated with the failed operation.
+     */
+    key: K;
+    /**
+     * Which internal operation produced the error.
+     */
+    source: AsyncLRUCacheErrorSource;
+}
 /**
  * Configuration options for the AsyncLRUCache.
  */
-export interface AsyncLRUCacheOption {
+export interface AsyncLRUCacheOption<K = unknown> {
     /**
      * Maximum capacity of the cache, this is the maximum number of items allowed.
      * Must not be less than 10.
@@ -26,6 +47,14 @@ export interface AsyncLRUCacheOption {
      * Setting this enables periodic background cleanup.
      */
     cleanupIntervalMs?: number;
+    /**
+     * Optional callback invoked whenever a loader/saver operation fails.
+     * When provided, this callback *replaces* the built-in `console.error`/`console.warn`
+     * logging, so you can forward errors to your own logger or monitoring system.
+     * If not provided, errors are logged to the console as before (default, backward-compatible behavior).
+     * This callback must not throw; any error thrown from it is ignored.
+     */
+    onError?: (error: unknown, context: AsyncLRUCacheErrorContext<K>) => void;
 }
 /**
  * Asynchronous LRU Cache class.
@@ -60,12 +89,16 @@ export declare class AsyncLRUCache<K, V> {
      * Timer ID for periodic cleanup of expired entries.
      */
     private cleanupTimer?;
+    /**
+     * Optional user-supplied error callback. When absent, errors are logged to the console.
+     */
+    private readonly onError?;
     /**
      * 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);
+    constructor(option: AsyncLRUCacheOption<K>);
     /**
      * Cleans up expired entries from the cache.
      * This method removes all nodes that have exceeded their TTL.
@@ -100,6 +133,15 @@ export declare class AsyncLRUCache<K, V> {
      * @param node - The node to add to the head of the list.
      */
     private _addToHead;
+    /**
+     * Reports an error that occurred during a loader/saver operation.
+     * Delegates to the user-supplied `onError` callback if one was provided in the
+     * constructor options; otherwise falls back to logging via `console.error`/`console.warn`.
+     * @param error - The error that was thrown/rejected.
+     * @param key - The cache key associated with the failed operation.
+     * @param source - Which internal operation produced the error.
+     */
+    private _reportError;
     /**
      * Retrieves data from the cache. If it does not exist, uses the loader to load it.
      * Automatically merges concurrent requests for the same key.
@@ -109,6 +151,25 @@ export declare class AsyncLRUCache<K, V> {
      * @returns A Promise that resolves to the required data.
      */
     get(key: K, loader: () => Promise<V>, ttlMs?: number): Promise<V>;
+    /**
+     * Retrieves data from the cache without loading it on a miss.
+     * On a cache hit, this behaves like the loader-based overload: the entry is moved to
+     * the head of the LRU list, same as a normal `get()`/`has()` hit.
+     * On a cache miss (including an expired entry), it resolves to `undefined` without
+     * adding anything to the cache, so it does not affect the LRU order.
+     * @param key - Cache key.
+     * @returns A Promise that resolves to the cached value, or `undefined` on a miss.
+     */
+    get(key: K): Promise<V | undefined>;
+    /**
+     * Returns the cached value for a key without triggering a loader and without
+     * affecting the LRU order, regardless of whether the key is a hit or a miss.
+     * If the entry has expired, it is evicted as a side effect of this check, the same
+     * way `has()` behaves; this does not count as an LRU-order-affecting access.
+     * @param key - Cache key.
+     * @returns The cached value's Promise if the key is present and not expired, otherwise `undefined`.
+     */
+    peek(key: K): Promise<V> | undefined;
     /**
      * 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.
@@ -145,8 +206,15 @@ export declare class AsyncLRUCache<K, V> {
     size(): number;
     /**
      * Checks if a key exists in the cache and is not expired.
+     *
+     * Note: this method is **not** side-effect-free. If the entry has expired, it is
+     * immediately evicted from the cache as part of this check (same as what would
+     * happen on the next `get()`/cleanup pass). It does **not** affect LRU order for
+     * entries that are still valid (unlike `get()`, calling `has()` does not move the
+     * entry to the head of the list).
      * @param key - The key to check.
      * @returns True if the key exists and is not expired, false otherwise.
      */
     has(key: K): boolean;
 }
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA8DH;;;;;;GAMG;AACH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAExE;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAE3C;;OAEG;IACH,GAAG,EAAE,CAAC,CAAC;IAEP;;OAEG;IACH,MAAM,EAAE,wBAAwB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAE/C;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,yBAAyB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CAC1E;AAED;;;;;;;GAOG;AACH,qBAAa,aAAa,CAAC,CAAC,EAAE,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAS;IAEvC;;OAEG;IACH,OAAO,CAAC,OAAO,CAA4B;IAE3C;;OAEG;IACH,OAAO,CAAC,IAAI,CAA2B;IAEvC;;OAEG;IACH,OAAO,CAAC,IAAI,CAA2B;IAEvC;;OAEG;IACH,OAAO,CAAC,YAAY,CAAC,CAAiB;IAEtC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAkE;IAE3F;;;;OAIG;gBACS,MAAM,EAAE,mBAAmB,CAAC,CAAC,CAAC;IAkB1C;;;OAGG;IACH,OAAO,CAAC,eAAe;IAyBvB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;;OAGG;IACH,OAAO,CAAC,cAAc;IAStB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAQnB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAanB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAYlB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IA6BpB;;;;;;;OAOG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAExE;;;;;;;;OAQG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAiD1C;;;;;;;OAOG;IACI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS;IAgB3C;;;;;;;;OAQG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IA4DrG;;;OAGG;IACI,UAAU,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI;IAW/B;;OAEG;IACI,KAAK,IAAI,IAAI;IA2BpB;;;OAGG;IACI,OAAO,IAAI,IAAI;IAatB;;;OAGG;IACI,cAAc,IAAI,IAAI;IAK7B;;;OAGG;IACI,IAAI,IAAI,MAAM;IAKrB;;;;;;;;;;OAUG;IACI,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;CAe3B"}

package/dist/index.js

@@ -79,6 +79,7 @@ class AsyncLRUCache {
             throw new Error("Capacity must be at least 10.");
         this.capacity = option.capacity;
         this.defaultTtlMs = option.defaultTtlMs;
+        this.onError = option.onError;
         // Setup periodic cleanup if specified
         if (option.cleanupIntervalMs && option.cleanupIntervalMs > 0) {
             this.cleanupTimer = setInterval(() => {
@@ -171,33 +172,60 @@ class AsyncLRUCache {
             this.tail = node;
     }
     /**
-     * Retrieves data from the cache. If it does not exist, uses the loader to load it.
-     * 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.
+     * Reports an error that occurred during a loader/saver operation.
+     * Delegates to the user-supplied `onError` callback if one was provided in the
+     * constructor options; otherwise falls back to logging via `console.error`/`console.warn`.
+     * @param error - The error that was thrown/rejected.
+     * @param key - The cache key associated with the failed operation.
+     * @param source - Which internal operation produced the error.
      */
+    _reportError(error, key, source) {
+        if (this.onError) {
+            try {
+                this.onError(error, { key, source });
+            }
+            catch {
+                // Swallow errors thrown by the user-supplied callback; it must not break cache operations.
+            }
+            return;
+        }
+        switch (source) {
+            case 'loader':
+                console.error(`[AsyncLRUCache ERROR] Loader for key ${key} failed. Removing from cache.`, error);
+                break;
+            case 'saver':
+                console.error(`[AsyncLRUCache ERROR] Saver operation for key ${key} failed. Removing from cache.`, error);
+                break;
+            case 'put-chain':
+                console.warn(`[AsyncLRUCache WARN] Previous operation for key ${key} failed. Chaining new PUT operation.`, error?.message ?? error);
+                break;
+        }
+    }
     get(key, loader, ttlMs) {
         const node = this.dataMap.get(key);
         if (node) {
             // Check if the node has expired
             if (this._checkAndRemoveExpired(key, node)) {
-                // Node was expired and removed, proceed to load fresh data
+                // Node was expired and removed, proceed to load fresh data (if a loader is provided)
             }
             else {
                 this._moveToHead(node);
                 return node.value;
             }
         }
+        if (!loader) {
+            // No loader was provided and there is no valid cached value.
+            // Resolve to undefined without touching the cache or its LRU order.
+            return Promise.resolve(undefined);
+        }
         const loadingPromise = loader();
-        const effectiveTtlMs = ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.defaultTtlMs;
+        const effectiveTtlMs = ttlMs ?? this.defaultTtlMs;
         const newNode = new Node(key, loadingPromise, effectiveTtlMs);
         this.dataMap.set(key, newNode);
         this._addToHead(newNode);
         this._evictIfNeeded();
         loadingPromise.catch(err => {
-            console.error(`[AsyncLRUCache ERROR] Loader for key ${key} failed. Removing from cache.`, err);
+            this._reportError(err, key, 'loader');
             if (this.dataMap.get(key) === newNode) {
                 this.dataMap.delete(key);
                 this._removeNode(newNode);
@@ -205,6 +233,24 @@ class AsyncLRUCache {
         });
         return loadingPromise;
     }
+    /**
+     * Returns the cached value for a key without triggering a loader and without
+     * affecting the LRU order, regardless of whether the key is a hit or a miss.
+     * If the entry has expired, it is evicted as a side effect of this check, the same
+     * way `has()` behaves; this does not count as an LRU-order-affecting access.
+     * @param key - Cache key.
+     * @returns The cached value's Promise if the key is present and not expired, otherwise `undefined`.
+     */
+    peek(key) {
+        const node = this.dataMap.get(key);
+        if (!node) {
+            return undefined;
+        }
+        if (this._checkAndRemoveExpired(key, node)) {
+            return undefined;
+        }
+        return node.value;
+    }
     /**
      * 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.
@@ -218,7 +264,7 @@ class AsyncLRUCache {
         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.
-            console.warn(`[AsyncLRUCache WARN] Previous operation for key ${key} failed. Chaining new PUT operation.`, err.message);
+            this._reportError(err, key, 'put-chain');
         })
             .then(() => {
             // After the previous operation (success or failure) completes, execute this saver.
@@ -230,7 +276,7 @@ class AsyncLRUCache {
             return value;
         });
         let node = this.dataMap.get(key);
-        const effectiveTtlMs = ttlMs !== null && ttlMs !== void 0 ? ttlMs : this.defaultTtlMs;
+        const effectiveTtlMs = ttlMs ?? this.defaultTtlMs;
         if (!node) {
             node = new Node(key, saverPromise, effectiveTtlMs);
             this.dataMap.set(key, node);
@@ -249,9 +295,8 @@ class AsyncLRUCache {
             this._moveToHead(node);
         }
         saverPromise.catch(err => {
-            var _a;
-            console.error(`[AsyncLRUCache ERROR] Saver operation for key ${key} failed. Removing from cache.`, err);
-            if (((_a = this.dataMap.get(key)) === null || _a === void 0 ? void 0 : _a.value) === saverPromise) {
+            this._reportError(err, key, 'saver');
+            if (this.dataMap.get(key)?.value === saverPromise) {
                 this.dataMap.delete(key);
                 this._removeNode(node);
             }
@@ -320,6 +365,12 @@ class AsyncLRUCache {
     }
     /**
      * Checks if a key exists in the cache and is not expired.
+     *
+     * Note: this method is **not** side-effect-free. If the entry has expired, it is
+     * immediately evicted from the cache as part of this check (same as what would
+     * happen on the next `get()`/cleanup pass). It does **not** affect LRU order for
+     * entries that are still valid (unlike `get()`, calling `has()` does not move the
+     * entry to the head of the list).
      * @param key - The key to check.
      * @returns True if the key exists and is not expired, false otherwise.
      */
@@ -335,3 +386,4 @@ class AsyncLRUCache {
     }
 }
 exports.AsyncLRUCache = AsyncLRUCache;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wfp99/async-lru-cache",
-	"version": "1.1.0",
+	"version": "1.2.0",
 	"description": "A simple memory cache using the LRU algorithm and supporting asynchronous data access.",
 	"keywords": [
 		"cache",
@@ -14,6 +14,13 @@
 	"type": "commonjs",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",
+	"sideEffects": false,
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.js"
+		}
+	},
 	"files": [
 		"dist/",
 		"README.md",
@@ -34,11 +41,13 @@
 	"scripts": {
 		"build": "tsc",
 		"clean": "rm -rf dist",
-		"prepublishOnly": "npm run clean && npm run build",
-		"test": "echo \"Error: no test specified\" && exit 1"
+		"prepublishOnly": "npm run clean && npm run build && npm test",
+		"test": "vitest run",
+		"test:watch": "vitest"
 	},
 	"devDependencies": {
 		"@types/node": "^24.0.7",
-		"typescript": "^5.8.3"
+		"typescript": "^5.8.3",
+		"vitest": "^3.2.4"
 	}
 }