@wfp99/async-lru-cache 1.1.1 → 1.2.0

package/README.md

@@ -4,29 +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 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
+- 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
 
@@ -40,241 +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
+  capacity: 100,
+  defaultTtlMs: 5000,       // default TTL applied to every entry
+  cleanupIntervalMs: 10000, // periodic background cleanup of expired entries
 });
 
-// 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');
-}
+// Override the default TTL for a specific entry.
+await cache.get('key1', async () => fetchData(), 30000);
 
-// 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. |
-| `defaultTtlMs` | `number` | No | Default TTL for all cache entries (optional) |
-| `cleanupIntervalMs` | `number` | No | Automatic cleanup interval for expired entries (optional) |
+|---|---|---|---|
+| `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>, 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>, 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`
+| 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.
-
-##### `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
-
-AsyncLRUCache automatically handles concurrent operations:
-
-- **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
-const [data1, data2, data3] = await Promise.all([
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader)
-]);
-
-// 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
+This package is written in TypeScript and ships with type declarations; no separate `@types` package is required.
 
 ## License
 
@@ -284,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

@@ -4,29 +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/)
 
-一個支援非同步載入和保存操作的 LRU（Least Recently Used）記憶體快取，自動處理並發請求。
+一個支援非同步載入與保存操作、並自動處理並發請求的 LRU（Least Recently Used）記憶體快取，適用於 Node.js 與 TypeScript。
 
 ## 特色
 
-- 🚀 **非同步支援**：支援非同步的載入器（loader）和保存器（saver）函數
-- 🔄 **自動合併**：自動合併相同 key 的並發 GET 請求
-- 📝 **序列化寫入**：序列化同一 key 的 PUT 操作，確保順序執行
-- 🗑️ **LRU 淘汰策略**：實現 LRU 演算法，自動移除最久未使用的項目
-- ⏰ **TTL 支援**：支援可配置的生存時間（Time To Live），自動過期快取項目
-- 🛡️ **錯誤處理**：完善的錯誤處理機制，失敗時自動清理快取
-- 🧹 **完整清除**：支援一次性清除所有快取項目
-
-## 為什麼選擇記憶體內快取而非外部快取服務？
-
-**簡單性與效能**
-- 無需設定 - 安裝後立即使用
-- 零網路延遲 - 直接記憶體存取
-- 減少基礎架構複雜性
-
-**可靠性與開發**
-- 無外部依賴或網路故障風險
-- 簡化測試和除錯
-- 無需 Redis、Memcached 或其他快取伺服器
+- 支援非同步的載入器（loader）與保存器（saver）函數
+- 對同一 key 的並發 `get()` 呼叫共用單一載入器執行
+- 對同一 key 的多個 `put()` 呼叫會序列化並依序執行
+- 超出設定容量時自動執行 LRU 淘汰
+- 支援每筆項目的可選 TTL（存活時間），並可設定週期性背景清理
+- 可透過 `onError` 自訂錯誤處理，預設為記錄到 console
+- `get()` 可省略 loader 進行唯讀查詢；`peek()` 則提供完全不影響 LRU 順序的查詢方式
 
 ## 安裝
 
@@ -45,236 +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
 
-### TTL（生存時間）支援
+// peek() 無論命中或未命中都不會影響 LRU 順序。
+const peeked = await cache.peek('user:123'); // Promise<User> | undefined
+```
 
-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
-
-// 手動清理過期項目
-cache.cleanupExpired();
+// 為特定項目覆寫預設 TTL。
+await cache.get('key1', async () => fetchData(), 30000);
 
-// 檢查 key 是否存在且未過期
-if (cache.has('key1')) {
-    console.log('Key 存在且有效');
-}
-
-// 取得快取大小
-console.log('目前快取大小:', cache.size());
-
-// 銷毀快取（停止清理計時器並清除所有資料）
-cache.destroy();
+cache.has('key1');        // 項目過期後回傳 false
+cache.cleanupExpired();   // 手動移除過期項目
+cache.destroy();          // 停止清理計時器並清除所有資料
 ```
 
-#### TTL 配置選項
-
-- **`defaultTtlMs`**：所有快取項目的預設 TTL（可選）
-- **`cleanupIntervalMs`**：過期項目的自動清理間隔（可選）
-- 個別的 `get()` 和 `put()` 方法接受 TTL 覆寫
-- 過期項目在正常操作期間會自動移除
-- 呼叫 `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);
-});
+// 以下並發的 get() 呼叫會共用同一個 loader 執行。
+const [a, b, c] = await Promise.all([
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+  cache.get('shared-key', loader),
+]);
 
-// 原子性地保存到快取和資料庫
-await cache.put(`user:${userId}`, updatedUser, async (key, value) => {
-    await database.users.update(userId, value);
-});
+// 以下 put() 呼叫即使並發啟動，也會依序序列化執行。
+cache.put('key', 'value1', saver1);
+cache.put('key', 'value2', saver2);
+cache.put('key', 'value3', saver3);
 ```
 
-### 快取管理
+### 錯誤處理
 
-```typescript
-// 手動移除特定快取項目
-cache.invalidate('user:123');
+- 若載入器（`get`）拋出例外，該項目會從快取中移除，錯誤會傳遞給呼叫端。
+- 若保存器（`put`）拋出例外，該項目也會被移除，避免快取到尚未持久化的值。
+- `put()` 會忽略同一 key 前一個已結束操作的失敗，讓新的操作可以繼續進行。
+- 預設情況下，上述失敗會透過 `console.error`/`console.warn` 記錄。若要自行處理，可提供 `onError`：
 
-// 清除所有快取項目
-cache.clear();
+```typescript
+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` | 是 | 快取中允許的最大項目數量，必須為正數 |
-| `defaultTtlMs` | `number` | 否 | 所有快取項目的預設 TTL（可選） |
-| `cleanupIntervalMs` | `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>, ttlMs?: number): Promise<V>`
-
-從快取中獲取資料。如果不存在，使用載入器載入資料。
-
-- **key**: 快取鍵
-- **loader**: 快取未命中時執行的非同步載入函數
-- **ttlMs**: 此項目的可選 TTL 覆寫
-- **回傳**: Promise，解析為所需的資料
-
-##### `put(key: K, value: V, saver?: (key: K, value: V) => Promise<void>, ttlMs?: number): Promise<V>`
-
-將值放入快取中，並可選擇性地執行保存器函數進行持久化。
-
-- **key**: 快取鍵
-- **value**: 要快取的值
-- **saver**: 可選的非同步保存函數
-- **ttlMs**: 此項目的可選 TTL 覆寫
-- **回傳**: Promise，解析為保存操作完成後的最新值
+| 方法 | 描述 |
+|---|---|
+| `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()` | 停止清理計時器（若有）並清除所有資料 |
 
-##### `invalidate(key: K): void`
+## TypeScript
 
-使指定鍵的快取項目失效並移除。
-
-- **key**: 要失效的快取鍵
-
-##### `clear(): void`
-
-清除所有快取項目。此方法會移除快取中的所有項目並手動清理節點連結以避免潛在的記憶體洩漏。
-
-##### `has(key: K): boolean`
-
-檢查快取中是否存在指定鍵且未過期。
-
-- **key**: 要檢查的快取鍵
-- **回傳**: 如果鍵存在且有效則回傳 true
-
-##### `size(): number`
-
-回傳快取中目前的項目數量。
-
-- **回傳**: 快取項目的數量
-
-##### `cleanupExpired(): void`
-
-手動從快取中移除過期項目。
-
-##### `destroy(): void`
-
-銷毀快取，停止清理計時器並清除所有資料。
-
-## 並發處理
-
-AsyncLRUCache 會自動處理並發操作：
-
-- **GET 請求合併**：對同一 key 的多個並發請求會共享單一載入器執行
-- **PUT 操作序列化**：對同一 key 的多個 PUT 操作會序列化執行以確保順序
-
-```typescript
-// 這三個並發請求會共享同一個載入器執行
-const [data1, data2, data3] = await Promise.all([
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader),
-    cache.get('shared-key', loader)
-]);
-
-// 這些操作會按順序執行，即使它們是並發啟動的
-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 操作會忽略前一個操作的錯誤，允許新操作繼續進行
-- **錯誤日誌**：所有錯誤都會自動記錄到控制台，便於除錯
+此套件以 TypeScript 撰寫並內建型別宣告檔，無需另外安裝 `@types` 套件。
 
 ## 授權
 
@@ -284,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.1",
+	"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"
 	}
 }