fast-map-cache 1.0.1 → 1.1.1

package/README.md

@@ -13,7 +13,7 @@ A high-performance in-memory LRU cache for Node.js and browsers, implemented wit
 
 In real-world scenarios, `fast-map-cache` demonstrates significant performance gains by preventing expensive operations:
 
-- **🚀 Proven Performance**: Delivers a **2x to 3x** performance boost in real-world I/O and CPU-bound scenarios by preventing expensive operations.
+- **🚀 Measured Benefits**: In the simulated API and CPU-bound workloads included in this repo, caching reduced end-to-end work by roughly **2x to 6x** when it could avoid expensive operations. Results depend on hit rate and workload cost.
 
 For a detailed analysis, see the full [**Performance Report**](./docs/performance-report.md).
 
@@ -78,11 +78,13 @@ setTimeout(() => {
 }, 6000)
 ```
 
+> Note: TTL is based on the timestamp of the last `set()` operation. A `get()` does not refresh TTL (i.e., it is not access-renewal).
+
 ### ❗ Important Note for Node.js Users
 
-When using `FastCacheWithTTL` with the `autoCleanup: true` option in a Node.js environment, a `setInterval` is used to periodically clean up expired items. This timer will prevent the Node.js process from exiting gracefully on its own.
+When using `FastCacheWithTTL` with the `autoCleanup: true` option in Node.js, an internal `setInterval` is used for periodic cleanup. The timer is created with `unref()` when available, so it will not keep the process alive on its own.
 
-**You must manually call the `destroy()` method before your application exits to clear the timer.**
+**It is still recommended to call `destroy()` before your application exits** to proactively clear resources and avoid potential hangs in long-running tasks or test environments.
 
 ```typescript
 const cache = createCacheWithTTL({ maxSize: 100, autoCleanup: true, ttl: 60000 })
@@ -97,7 +99,7 @@ For more advanced use cases, including batch operations and presets, please see
 
 ## API Reference
 
-The cache instance, created by `createCache` or `createCacheWithTTL`, implements the `IFastCache` interface.
+The cache instance created by `createCache` implements `IFastCache`. `FastCacheWithTTL` additionally satisfies `IFastTTLCache` and exposes `cleanup()` and `destroy()`.
 
 ### `get(key: K): V | undefined`
 
@@ -123,11 +125,11 @@ Clears all items from the cache.
 
 ### `getMany(keys: K[]): Map<K, V>`
 
-Retrieves multiple values for an array of keys. Returns a `Map` containing the found key-value pairs.
+Retrieves multiple values for an array of keys. Returns a `Map` containing the found key-value pairs. This is a convenience API, not a guaranteed performance optimization.
 
 ### `setMany(entries: [K, V][]): void`
 
-Adds or updates multiple key-value pairs from an array of entries.
+Adds or updates multiple key-value pairs from an array of entries. This is a convenience API, not a guaranteed performance optimization.
 
 ### `size: number` (getter)
 
@@ -158,13 +160,13 @@ Manually triggers the cleanup of expired items. Returns the number of items that
 
 ### `destroy(): void` (For `FastCacheWithTTL` only)
 
-Clears the automatic cleanup timer if `autoCleanup` was enabled. **Crucial for graceful shutdown in Node.js.**
+Clears the automatic cleanup timer if `autoCleanup` was enabled. Useful for proactively releasing timer resources in long-lived processes or tests.
 
 ## Benchmark
 
 This library is designed for high performance in real-world scenarios. The core value of a cache is not just the raw speed of its `get`/`set` operations, but its ability to prevent expensive computations or network requests.
 
-Our benchmarks show that in realistic I/O-bound and CPU-bound scenarios, `fast-map-cache` provides a **2x to 3x performance boost on average**. The actual improvement depends heavily on the cost of the operation being cached.
+The included benchmarks show clear gains when cache hits avoid expensive work such as simulated API calls or CPU-heavy computations. Actual results depend on hit rate, cache size, and the real cost of the work being skipped.
 
 ## Contributing
 

package/README_zh-CN.md

@@ -13,7 +13,7 @@
 
 在真实业务场景中，`fast-map-cache` 通过有效避免高成本操作，展现出显著的性能优势：
 
-- **🚀 可靠性能**: 在真实的 I/O 和 CPU 密集型场景中，通过避免高成本操作，带来 **2-3 倍** 的性能提升。
+- **🚀 可复核收益**: 在仓库自带的模拟 API 与 CPU 密集场景里，当缓存命中能够避开昂贵操作时，端到端收益大致在 **2 到 6 倍**。实际效果仍取决于命中率和被缓存工作的成本。
 
 详细分析请参阅完整的 [**性能报告**](./docs/performance-report.md)。
 
@@ -80,11 +80,13 @@ setTimeout(() => {
 }, 6000)
 ```
 
+> 提示：TTL 以最近一次 `set()` 的时间为基准；`get()` 不会刷新 TTL（非“访问续期”）。
+
 ### ❗ Node.js 用户重要提示
 
-在 Node.js 环境下使用 `FastCacheWithTTL` 并开启 `autoCleanup: true` 选项时，系统会使用 `setInterval` 定时清理过期缓存。这个定时器会阻止 Node.js 进程正常退出。
+在 Node.js 下使用 `autoCleanup: true` 时，内部会使用 `setInterval` 做周期清理；当环境支持时定时器会调用 `unref()`，因此不会单独阻止进程退出。
 
-**您必须在程序退出前手动调用 `destroy()` 方法来清除该定时器。**
+**仍然建议在应用退出前调用 `destroy()` 主动释放资源**，可避免长生命周期任务或测试环境中的潜在挂起。
 
 ```typescript
 const cache = createCacheWithTTL({ maxSize: 100, autoCleanup: true, ttl: 60000 })
@@ -97,7 +99,7 @@ cache.destroy()
 
 ## API 参考
 
-由 `createCache` 或 `createCacheWithTTL` 创建的缓存实例均实现了 `IFastCache` 接口。
+`createCache` 返回实现 `IFastCache` 的实例。`FastCacheWithTTL` 进一步满足 `IFastTTLCache`，并额外提供 `cleanup()` 和 `destroy()`。
 
 ### `get(key: K): V | undefined`
 
@@ -123,11 +125,11 @@ cache.destroy()
 
 ### `getMany(keys: K[]): Map<K, V>`
 
-根据键数组批量获取值。返回一个包含已找到的键值对的 `Map`。
+根据键数组批量获取值。返回一个包含已找到的键值对的 `Map`。这是便捷 API，不保证一定比逐个调用更快。
 
 ### `setMany(entries: [K, V][]): void`
 
-通过一个条目数组批量添加或更新键值对。
+通过一个条目数组批量添加或更新键值对。这是便捷 API，不保证一定比逐个调用更快。
 
 ### `size: number` (getter)
 
@@ -158,13 +160,13 @@ cache.destroy()
 
 ### `destroy(): void` (仅 `FastCacheWithTTL` 可用)
 
-如果开启了 `autoCleanup`，此方法用于清除自动清理定时器。**这对于在 Node.js 中实现优雅停机至关重要。**
+如果开启了 `autoCleanup`，此方法用于清除自动清理定时器，适合在长生命周期进程或测试中主动释放资源。
 
 ## 性能基准
 
 本库为真实场景下的高性能而设计。缓存的核心价值不仅在于 `get`/`set` 操作的原始速度，更在于它能够有效避免昂贵的计算或网络请求。
 
-我们的基准测试显示，在模拟真实世界的 I/O 密集和 CPU 密集场景下，`fast-map-cache` 平均能带来 **2 到 3 倍的性能提升**。实际提升效果取决于被缓存操作的成本。
+仓库内自带的 benchmark 显示：当缓存命中可以避开昂贵的 I/O 或 CPU 计算时，收益会很明显。实际效果主要取决于命中率、缓存容量是否覆盖热点集，以及被缓存工作的真实成本。
 
 ## 贡献
 

package/dist/main.d.mts

@@ -30,6 +30,10 @@ interface IFastCache<K extends CacheKey, V> {
   getStats(): CacheStats;
   cleanup?(): number;
 }
+interface IFastTTLCache<K extends CacheKey, V> extends IFastCache<K, V> {
+  cleanup(): number;
+  destroy(): void;
+}
 interface CacheNode<K extends CacheKey, V> {
   key: K;
   value: V;
@@ -66,6 +70,11 @@ declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
   protected addToHead(node: CacheNode<K, V>): void;
   protected removeNode(node: CacheNode<K, V>): void;
   protected moveToHead(node: CacheNode<K, V>): void;
+  /**
+   * 统一删除入口：删除 Map 记录并从 LRU 链表移除节点。
+   * 子类（如 TTL 版本）可覆写该方法以保证多链表同步删除。
+   */
+  protected deleteNode(node: CacheNode<K, V>): void;
   protected removeTail(): void;
 }
 //#endregion
@@ -76,12 +85,11 @@ declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
  * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
  *
  * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
- * 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
- * 否则定时器会阻止 Node.js 进程正常退出。
+ * 内部定时器在支持的运行时会调用 `unref()`，因此通常不会单独阻止进程退出。
+ * 如果缓存生命周期明确，仍建议调用 `destroy()` 主动清理定时器。
  */
-declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
+declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> implements IFastTTLCache<K, V> {
   private readonly ttl;
-  private readonly autoCleanup;
   private cleanupTimer;
   private readonly timeHead;
   private readonly timeTail;
@@ -92,17 +100,16 @@ declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
   delete(key: K): boolean;
   clear(): void;
   has(key: K): boolean;
-  get size(): number;
-  get capacity(): number;
-  setMany(entries: [K, V][]): void;
-  getMany(keys: K[]): Map<K, V>;
   getStats(): CacheStats;
   cleanup(): number;
   /**
-   * 清理定时器，防止在 Node.js 环境中进程无法正常退出。
-   * 如果开启了 `autoCleanup`，你应当在应用关闭前调用此方法。
+   * 清理自动清理定时器，适合在可控生命周期中主动释放资源。
    */
   destroy(): void;
+  /**
+   * 覆写统一删除入口：先维护 TTL 链表，再调用父类删除 LRU/Map。
+   */
+  protected deleteNode(node: CacheNode<K, V>): void;
   private isExpired;
   private _addToTimeListTail;
   private _removeFromTimeList;
@@ -119,4 +126,4 @@ declare const CachePresets: {
   readonly tempCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
 };
 //#endregion
-export { CacheKey, CacheNode, CacheOptions, CachePresets, CacheStats, FastCache, FastCacheWithTTL, IFastCache, createCache, createCacheWithTTL };
+export { type CacheKey, type CacheNode, type CacheOptions, CachePresets, type CacheStats, FastCache, FastCacheWithTTL, type IFastCache, type IFastTTLCache, createCache, createCacheWithTTL };

package/dist/main.d.ts

@@ -30,6 +30,10 @@ interface IFastCache<K extends CacheKey, V> {
   getStats(): CacheStats;
   cleanup?(): number;
 }
+interface IFastTTLCache<K extends CacheKey, V> extends IFastCache<K, V> {
+  cleanup(): number;
+  destroy(): void;
+}
 interface CacheNode<K extends CacheKey, V> {
   key: K;
   value: V;
@@ -66,6 +70,11 @@ declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
   protected addToHead(node: CacheNode<K, V>): void;
   protected removeNode(node: CacheNode<K, V>): void;
   protected moveToHead(node: CacheNode<K, V>): void;
+  /**
+   * 统一删除入口：删除 Map 记录并从 LRU 链表移除节点。
+   * 子类（如 TTL 版本）可覆写该方法以保证多链表同步删除。
+   */
+  protected deleteNode(node: CacheNode<K, V>): void;
   protected removeTail(): void;
 }
 //#endregion
@@ -76,12 +85,11 @@ declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
  * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
  *
  * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
- * 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
- * 否则定时器会阻止 Node.js 进程正常退出。
+ * 内部定时器在支持的运行时会调用 `unref()`，因此通常不会单独阻止进程退出。
+ * 如果缓存生命周期明确，仍建议调用 `destroy()` 主动清理定时器。
  */
-declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
+declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> implements IFastTTLCache<K, V> {
   private readonly ttl;
-  private readonly autoCleanup;
   private cleanupTimer;
   private readonly timeHead;
   private readonly timeTail;
@@ -92,17 +100,16 @@ declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
   delete(key: K): boolean;
   clear(): void;
   has(key: K): boolean;
-  get size(): number;
-  get capacity(): number;
-  setMany(entries: [K, V][]): void;
-  getMany(keys: K[]): Map<K, V>;
   getStats(): CacheStats;
   cleanup(): number;
   /**
-   * 清理定时器，防止在 Node.js 环境中进程无法正常退出。
-   * 如果开启了 `autoCleanup`，你应当在应用关闭前调用此方法。
+   * 清理自动清理定时器，适合在可控生命周期中主动释放资源。
    */
   destroy(): void;
+  /**
+   * 覆写统一删除入口：先维护 TTL 链表，再调用父类删除 LRU/Map。
+   */
+  protected deleteNode(node: CacheNode<K, V>): void;
   private isExpired;
   private _addToTimeListTail;
   private _removeFromTimeList;
@@ -119,4 +126,4 @@ declare const CachePresets: {
   readonly tempCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
 };
 //#endregion
-export { CacheKey, CacheNode, CacheOptions, CachePresets, CacheStats, FastCache, FastCacheWithTTL, IFastCache, createCache, createCacheWithTTL };
+export { type CacheKey, type CacheNode, type CacheOptions, CachePresets, type CacheStats, FastCache, FastCacheWithTTL, type IFastCache, type IFastTTLCache, createCache, createCacheWithTTL };

package/dist/main.js

@@ -1,102 +1,55 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __commonJS = (cb, mod) => function() {
-	return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
-
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/typeof.js
-var require_typeof = __commonJS({ "node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/typeof.js"(exports, module) {
-	function _typeof$2(o) {
-		"@babel/helpers - typeof";
-		return module.exports = _typeof$2 = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o$1) {
-			return typeof o$1;
-		} : function(o$1) {
-			return o$1 && "function" == typeof Symbol && o$1.constructor === Symbol && o$1 !== Symbol.prototype ? "symbol" : typeof o$1;
-		}, module.exports.__esModule = true, module.exports["default"] = module.exports, _typeof$2(o);
-	}
-	module.exports = _typeof$2, module.exports.__esModule = true, module.exports["default"] = module.exports;
-} });
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0@oxc-project+runtime@0.115.0/helpers/typeof.js
+function _typeof(o) {
+	"@babel/helpers - typeof";
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
+	}, _typeof(o);
+}
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/toPrimitive.js
-var require_toPrimitive = __commonJS({ "node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/toPrimitive.js"(exports, module) {
-	var _typeof$1 = require_typeof()["default"];
-	function toPrimitive$1(t, r) {
-		if ("object" != _typeof$1(t) || !t) return t;
-		var e = t[Symbol.toPrimitive];
-		if (void 0 !== e) {
-			var i = e.call(t, r || "default");
-			if ("object" != _typeof$1(i)) return i;
-			throw new TypeError("@@toPrimitive must return a primitive value.");
-		}
-		return ("string" === r ? String : Number)(t);
-	}
-	module.exports = toPrimitive$1, module.exports.__esModule = true, module.exports["default"] = module.exports;
-} });
-
+//#region \0@oxc-project+runtime@0.115.0/helpers/toPrimitive.js
+function toPrimitive(t, r) {
+	if ("object" != _typeof(t) || !t) return t;
+	var e = t[Symbol.toPrimitive];
+	if (void 0 !== e) {
+		var i = e.call(t, r || "default");
+		if ("object" != _typeof(i)) return i;
+		throw new TypeError("@@toPrimitive must return a primitive value.");
+	}
+	return ("string" === r ? String : Number)(t);
+}
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/toPropertyKey.js
-var require_toPropertyKey = __commonJS({ "node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/toPropertyKey.js"(exports, module) {
-	var _typeof = require_typeof()["default"];
-	var toPrimitive = require_toPrimitive();
-	function toPropertyKey$1(t) {
-		var i = toPrimitive(t, "string");
-		return "symbol" == _typeof(i) ? i : i + "";
-	}
-	module.exports = toPropertyKey$1, module.exports.__esModule = true, module.exports["default"] = module.exports;
-} });
-
+//#region \0@oxc-project+runtime@0.115.0/helpers/toPropertyKey.js
+function toPropertyKey(t) {
+	var i = toPrimitive(t, "string");
+	return "symbol" == _typeof(i) ? i : i + "";
+}
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js
-var require_defineProperty = __commonJS({ "node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/defineProperty.js"(exports, module) {
-	var toPropertyKey = require_toPropertyKey();
-	function _defineProperty$2(e, r, t) {
-		return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
-			value: t,
-			enumerable: !0,
-			configurable: !0,
-			writable: !0
-		}) : e[r] = t, e;
-	}
-	module.exports = _defineProperty$2, module.exports.__esModule = true, module.exports["default"] = module.exports;
-} });
-
+//#region \0@oxc-project+runtime@0.115.0/helpers/defineProperty.js
+function _defineProperty(e, r, t) {
+	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
+		value: t,
+		enumerable: !0,
+		configurable: !0,
+		writable: !0
+	}) : e[r] = t, e;
+}
 //#endregion
 //#region src/fast-cache.ts
-var import_defineProperty$1 = __toESM(require_defineProperty());
 /**
 * 高性能 LRU 缓存实现
 * 使用 Map + 双向链表实现 O(1) 复杂度的所有操作
 */
 var FastCache = class {
 	constructor(maxSize) {
-		(0, import_defineProperty$1.default)(this, "cache", void 0);
-		(0, import_defineProperty$1.default)(this, "head", void 0);
-		(0, import_defineProperty$1.default)(this, "tail", void 0);
-		(0, import_defineProperty$1.default)(this, "maxSize", void 0);
-		(0, import_defineProperty$1.default)(this, "hits", 0);
-		(0, import_defineProperty$1.default)(this, "misses", 0);
+		_defineProperty(this, "cache", void 0);
+		_defineProperty(this, "head", void 0);
+		_defineProperty(this, "tail", void 0);
+		_defineProperty(this, "maxSize", void 0);
+		_defineProperty(this, "hits", 0);
+		_defineProperty(this, "misses", 0);
 		if (maxSize <= 0) throw new Error("Cache size must be positive");
 		this.maxSize = maxSize;
 		this.cache = /* @__PURE__ */ new Map();
@@ -109,7 +62,7 @@ var FastCache = class {
 		const node = this.cache.get(key);
 		if (node === void 0) {
 			this.misses++;
-			return void 0;
+			return;
 		}
 		this.moveToHead(node);
 		this.hits++;
@@ -135,8 +88,7 @@ var FastCache = class {
 	delete(key) {
 		const node = this.cache.get(key);
 		if (node === void 0) return false;
-		this.cache.delete(key);
-		this.removeNode(node);
+		this.deleteNode(node);
 		return true;
 	}
 	clear() {
@@ -190,59 +142,64 @@ var FastCache = class {
 		this.removeNode(node);
 		this.addToHead(node);
 	}
+	/**
+	* 统一删除入口：删除 Map 记录并从 LRU 链表移除节点。
+	* 子类（如 TTL 版本）可覆写该方法以保证多链表同步删除。
+	*/
+	deleteNode(node) {
+		this.cache.delete(node.key);
+		this.removeNode(node);
+	}
 	removeTail() {
 		const lastNode = this.tail.prev;
-		if (lastNode && lastNode !== this.head) {
-			this.cache.delete(lastNode.key);
-			this.removeNode(lastNode);
-		}
+		if (lastNode && lastNode !== this.head) this.deleteNode(lastNode);
 	}
 };
-
 //#endregion
 //#region src/fast-cache-ttl.ts
-var import_defineProperty = __toESM(require_defineProperty());
 /**
 * 带 TTL (Time To Live) 支持的高性能缓存实现。
 * 继承自 FastCache，并增加了一个按时间排序的独立链表，
 * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
 *
 * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
-* 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
-* 否则定时器会阻止 Node.js 进程正常退出。
+* 内部定时器在支持的运行时会调用 `unref()`，因此通常不会单独阻止进程退出。
+* 如果缓存生命周期明确，仍建议调用 `destroy()` 主动清理定时器。
 */
 var FastCacheWithTTL = class extends FastCache {
 	constructor(options) {
 		super(options.maxSize);
-		(0, import_defineProperty.default)(this, "ttl", void 0);
-		(0, import_defineProperty.default)(this, "autoCleanup", void 0);
-		(0, import_defineProperty.default)(this, "cleanupTimer", void 0);
-		(0, import_defineProperty.default)(this, "timeHead", void 0);
-		(0, import_defineProperty.default)(this, "timeTail", void 0);
-		(0, import_defineProperty.default)(this, "expired", 0);
+		_defineProperty(this, "ttl", void 0);
+		_defineProperty(this, "cleanupTimer", void 0);
+		_defineProperty(this, "timeHead", void 0);
+		_defineProperty(this, "timeTail", void 0);
+		_defineProperty(this, "expired", 0);
 		if (options.ttl !== void 0 && options.ttl <= 0) throw new Error("TTL must be positive");
 		this.ttl = options.ttl ?? 0;
-		this.autoCleanup = options.autoCleanup ?? false;
+		const autoCleanup = options.autoCleanup ?? false;
 		this.timeHead = {};
 		this.timeTail = {};
 		this.timeHead.timeNext = this.timeTail;
 		this.timeTail.timePrev = this.timeHead;
-		if (this.autoCleanup && this.ttl > 0) {
+		if (autoCleanup && this.ttl > 0) {
 			const cleanupInterval = options.cleanupInterval ?? this.ttl;
+			if (cleanupInterval <= 0) throw new Error("cleanupInterval must be positive");
 			this.cleanupTimer = setInterval(() => this.cleanup(), cleanupInterval);
+			const anyTimer = this.cleanupTimer;
+			if (typeof anyTimer.unref === "function") anyTimer.unref();
 		}
 	}
 	get(key) {
 		const node = this.cache.get(key);
 		if (node === void 0) {
 			this.misses++;
-			return void 0;
+			return;
 		}
 		if (this.isExpired(node)) {
 			this.delete(key);
 			this.expired++;
 			this.misses++;
-			return void 0;
+			return;
 		}
 		return super.get(key);
 	}
@@ -277,27 +234,9 @@ var FastCacheWithTTL = class extends FastCache {
 		}
 		return true;
 	}
-	get size() {
-		return this.cache.size;
-	}
-	get capacity() {
-		return this.maxSize;
-	}
-	setMany(entries) {
-		for (const [key, value] of entries) this.set(key, value);
-	}
-	getMany(keys) {
-		const result = /* @__PURE__ */ new Map();
-		for (const key of keys) {
-			const value = this.get(key);
-			if (value !== void 0) result.set(key, value);
-		}
-		return result;
-	}
 	getStats() {
-		const stats = super.getStats();
 		return {
-			...stats,
+			...super.getStats(),
 			expired: this.expired
 		};
 	}
@@ -315,8 +254,7 @@ var FastCacheWithTTL = class extends FastCache {
 		return removedCount;
 	}
 	/**
-	* 清理定时器，防止在 Node.js 环境中进程无法正常退出。
-	* 如果开启了 `autoCleanup`，你应当在应用关闭前调用此方法。
+	* 清理自动清理定时器，适合在可控生命周期中主动释放资源。
 	*/
 	destroy() {
 		if (this.cleanupTimer) {
@@ -324,6 +262,13 @@ var FastCacheWithTTL = class extends FastCache {
 			this.cleanupTimer = void 0;
 		}
 	}
+	/**
+	* 覆写统一删除入口：先维护 TTL 链表，再调用父类删除 LRU/Map。
+	*/
+	deleteNode(node) {
+		this._removeFromTimeList(node);
+		super.deleteNode(node);
+	}
 	isExpired(node, now) {
 		if (this.ttl === 0 || node.timestamp === void 0) return false;
 		return (now ?? Date.now()) - node.timestamp > this.ttl;
@@ -344,7 +289,6 @@ var FastCacheWithTTL = class extends FastCache {
 		this._addToTimeListTail(node);
 	}
 };
-
 //#endregion
 //#region src/index.ts
 function createCache(maxSize) {
@@ -356,21 +300,20 @@ function createCacheWithTTL(options) {
 const CachePresets = {
 	apiCache: (maxSize = 1e3) => createCache(maxSize),
 	computeCache: (maxSize = 500) => createCache(maxSize),
-	sessionCache: (maxSize = 100, ttl = 30 * 60 * 1e3) => createCacheWithTTL({
+	sessionCache: (maxSize = 100, ttl = 1800 * 1e3) => createCacheWithTTL({
 		maxSize,
 		ttl,
 		autoCleanup: true
 	}),
-	tempCache: (maxSize = 200, ttl = 5 * 60 * 1e3) => createCacheWithTTL({
+	tempCache: (maxSize = 200, ttl = 300 * 1e3) => createCacheWithTTL({
 		maxSize,
 		ttl,
 		autoCleanup: true
 	})
 };
-
 //#endregion
 exports.CachePresets = CachePresets;
 exports.FastCache = FastCache;
 exports.FastCacheWithTTL = FastCacheWithTTL;
 exports.createCache = createCache;
-exports.createCacheWithTTL = createCacheWithTTL;
+exports.createCacheWithTTL = createCacheWithTTL;

package/dist/main.mjs

@@ -1,15 +1,14 @@
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/esm/typeof.js
+//#region \0@oxc-project+runtime@0.115.0/helpers/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
-	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o$1) {
-		return typeof o$1;
-	} : function(o$1) {
-		return o$1 && "function" == typeof Symbol && o$1.constructor === Symbol && o$1 !== Symbol.prototype ? "symbol" : typeof o$1;
+	return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function(o) {
+		return typeof o;
+	} : function(o) {
+		return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o;
 	}, _typeof(o);
 }
-
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/esm/toPrimitive.js
+//#region \0@oxc-project+runtime@0.115.0/helpers/toPrimitive.js
 function toPrimitive(t, r) {
 	if ("object" != _typeof(t) || !t) return t;
 	var e = t[Symbol.toPrimitive];
@@ -20,16 +19,14 @@ function toPrimitive(t, r) {
 	}
 	return ("string" === r ? String : Number)(t);
 }
-
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/esm/toPropertyKey.js
+//#region \0@oxc-project+runtime@0.115.0/helpers/toPropertyKey.js
 function toPropertyKey(t) {
 	var i = toPrimitive(t, "string");
 	return "symbol" == _typeof(i) ? i : i + "";
 }
-
 //#endregion
-//#region node_modules/.pnpm/@oxc-project+runtime@0.72.3/node_modules/@oxc-project/runtime/src/helpers/esm/defineProperty.js
+//#region \0@oxc-project+runtime@0.115.0/helpers/defineProperty.js
 function _defineProperty(e, r, t) {
 	return (r = toPropertyKey(r)) in e ? Object.defineProperty(e, r, {
 		value: t,
@@ -38,7 +35,6 @@ function _defineProperty(e, r, t) {
 		writable: !0
 	}) : e[r] = t, e;
 }
-
 //#endregion
 //#region src/fast-cache.ts
 /**
@@ -65,7 +61,7 @@ var FastCache = class {
 		const node = this.cache.get(key);
 		if (node === void 0) {
 			this.misses++;
-			return void 0;
+			return;
 		}
 		this.moveToHead(node);
 		this.hits++;
@@ -91,8 +87,7 @@ var FastCache = class {
 	delete(key) {
 		const node = this.cache.get(key);
 		if (node === void 0) return false;
-		this.cache.delete(key);
-		this.removeNode(node);
+		this.deleteNode(node);
 		return true;
 	}
 	clear() {
@@ -146,15 +141,19 @@ var FastCache = class {
 		this.removeNode(node);
 		this.addToHead(node);
 	}
+	/**
+	* 统一删除入口：删除 Map 记录并从 LRU 链表移除节点。
+	* 子类（如 TTL 版本）可覆写该方法以保证多链表同步删除。
+	*/
+	deleteNode(node) {
+		this.cache.delete(node.key);
+		this.removeNode(node);
+	}
 	removeTail() {
 		const lastNode = this.tail.prev;
-		if (lastNode && lastNode !== this.head) {
-			this.cache.delete(lastNode.key);
-			this.removeNode(lastNode);
-		}
+		if (lastNode && lastNode !== this.head) this.deleteNode(lastNode);
 	}
 };
-
 //#endregion
 //#region src/fast-cache-ttl.ts
 /**
@@ -163,41 +162,43 @@ var FastCache = class {
 * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
 *
 * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
-* 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
-* 否则定时器会阻止 Node.js 进程正常退出。
+* 内部定时器在支持的运行时会调用 `unref()`，因此通常不会单独阻止进程退出。
+* 如果缓存生命周期明确，仍建议调用 `destroy()` 主动清理定时器。
 */
 var FastCacheWithTTL = class extends FastCache {
 	constructor(options) {
 		super(options.maxSize);
 		_defineProperty(this, "ttl", void 0);
-		_defineProperty(this, "autoCleanup", void 0);
 		_defineProperty(this, "cleanupTimer", void 0);
 		_defineProperty(this, "timeHead", void 0);
 		_defineProperty(this, "timeTail", void 0);
 		_defineProperty(this, "expired", 0);
 		if (options.ttl !== void 0 && options.ttl <= 0) throw new Error("TTL must be positive");
 		this.ttl = options.ttl ?? 0;
-		this.autoCleanup = options.autoCleanup ?? false;
+		const autoCleanup = options.autoCleanup ?? false;
 		this.timeHead = {};
 		this.timeTail = {};
 		this.timeHead.timeNext = this.timeTail;
 		this.timeTail.timePrev = this.timeHead;
-		if (this.autoCleanup && this.ttl > 0) {
+		if (autoCleanup && this.ttl > 0) {
 			const cleanupInterval = options.cleanupInterval ?? this.ttl;
+			if (cleanupInterval <= 0) throw new Error("cleanupInterval must be positive");
 			this.cleanupTimer = setInterval(() => this.cleanup(), cleanupInterval);
+			const anyTimer = this.cleanupTimer;
+			if (typeof anyTimer.unref === "function") anyTimer.unref();
 		}
 	}
 	get(key) {
 		const node = this.cache.get(key);
 		if (node === void 0) {
 			this.misses++;
-			return void 0;
+			return;
 		}
 		if (this.isExpired(node)) {
 			this.delete(key);
 			this.expired++;
 			this.misses++;
-			return void 0;
+			return;
 		}
 		return super.get(key);
 	}
@@ -232,27 +233,9 @@ var FastCacheWithTTL = class extends FastCache {
 		}
 		return true;
 	}
-	get size() {
-		return this.cache.size;
-	}
-	get capacity() {
-		return this.maxSize;
-	}
-	setMany(entries) {
-		for (const [key, value] of entries) this.set(key, value);
-	}
-	getMany(keys) {
-		const result = /* @__PURE__ */ new Map();
-		for (const key of keys) {
-			const value = this.get(key);
-			if (value !== void 0) result.set(key, value);
-		}
-		return result;
-	}
 	getStats() {
-		const stats = super.getStats();
 		return {
-			...stats,
+			...super.getStats(),
 			expired: this.expired
 		};
 	}
@@ -270,8 +253,7 @@ var FastCacheWithTTL = class extends FastCache {
 		return removedCount;
 	}
 	/**
-	* 清理定时器，防止在 Node.js 环境中进程无法正常退出。
-	* 如果开启了 `autoCleanup`，你应当在应用关闭前调用此方法。
+	* 清理自动清理定时器，适合在可控生命周期中主动释放资源。
 	*/
 	destroy() {
 		if (this.cleanupTimer) {
@@ -279,6 +261,13 @@ var FastCacheWithTTL = class extends FastCache {
 			this.cleanupTimer = void 0;
 		}
 	}
+	/**
+	* 覆写统一删除入口：先维护 TTL 链表，再调用父类删除 LRU/Map。
+	*/
+	deleteNode(node) {
+		this._removeFromTimeList(node);
+		super.deleteNode(node);
+	}
 	isExpired(node, now) {
 		if (this.ttl === 0 || node.timestamp === void 0) return false;
 		return (now ?? Date.now()) - node.timestamp > this.ttl;
@@ -299,7 +288,6 @@ var FastCacheWithTTL = class extends FastCache {
 		this._addToTimeListTail(node);
 	}
 };
-
 //#endregion
 //#region src/index.ts
 function createCache(maxSize) {
@@ -311,17 +299,16 @@ function createCacheWithTTL(options) {
 const CachePresets = {
 	apiCache: (maxSize = 1e3) => createCache(maxSize),
 	computeCache: (maxSize = 500) => createCache(maxSize),
-	sessionCache: (maxSize = 100, ttl = 30 * 60 * 1e3) => createCacheWithTTL({
+	sessionCache: (maxSize = 100, ttl = 1800 * 1e3) => createCacheWithTTL({
 		maxSize,
 		ttl,
 		autoCleanup: true
 	}),
-	tempCache: (maxSize = 200, ttl = 5 * 60 * 1e3) => createCacheWithTTL({
+	tempCache: (maxSize = 200, ttl = 300 * 1e3) => createCacheWithTTL({
 		maxSize,
 		ttl,
 		autoCleanup: true
 	})
 };
-
 //#endregion
-export { CachePresets, FastCache, FastCacheWithTTL, createCache, createCacheWithTTL };
+export { CachePresets, FastCache, FastCacheWithTTL, createCache, createCacheWithTTL };

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "fast-map-cache",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "High-performance TypeScript LRU cache (with optional TTL) for Node.js & browsers.",
   "publishConfig": {
     "access": "public"
   },
+  "type": "commonjs",
   "main": "./dist/main.js",
   "module": "./dist/main.mjs",
   "types": "./dist/main.d.ts",
@@ -20,26 +21,17 @@
   },
   "exports": {
     ".": {
-      "import": "./dist/main.mjs",
-      "require": "./dist/main.js"
+      "import": {
+        "types": "./dist/main.d.mts",
+        "default": "./dist/main.mjs"
+      },
+      "require": {
+        "types": "./dist/main.d.ts",
+        "default": "./dist/main.js"
+      }
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "oxlint",
-    "build": "pnpm lint && pnpm type-check && tsdown",
-    "bench": "vitest bench --run",
-    "prepare": "simple-git-hooks install",
-    "run:example": "npx tsx examples/01-basic-example.ts",
-    "type-check": "tsc --noEmit",
-    "format": "prettier --write .",
-    "gen-report": "pnpm bench && tsx scripts/generate-performance-report.ts",
-    "changeset": "changeset",
-    "version:packages": "changeset version",
-    "release": "pnpm build && changeset publish"
-  },
   "keywords": [
     "cache",
     "lru",
@@ -59,19 +51,21 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@changesets/cli": "^2.29.5",
-    "@commitlint/cli": "^19.8.1",
-    "@commitlint/config-conventional": "^19.8.1",
-    "@vitest/coverage-v8": "^3.2.4",
-    "lint-staged": "^16.1.2",
-    "oxlint": "^1.2.0",
-    "pnpm": "^10.12.2",
-    "prettier": "^3.6.0",
+    "@changesets/cli": "^2.30.0",
+    "@commitlint/cli": "^20.4.4",
+    "@commitlint/config-conventional": "^20.4.4",
+    "@vitest/coverage-v8": "^4.1.0",
+    "lint-staged": "^16.3.3",
+    "oxlint": "^1.55.0",
+    "pnpm": "^10.32.1",
+    "prettier": "^3.8.1",
+    "publint": "^0.3.15",
     "simple-git-hooks": "^2.13.0",
-    "tsdown": "^0.12.8",
-    "tsx": "^4.20.3",
-    "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "tsdown": "^0.21.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged",
@@ -86,10 +80,24 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/crper/fast-map-cache.git"
+    "url": "git+https://github.com/crper/fast-map-cache.git"
   },
   "bugs": {
     "url": "https://github.com/crper/fast-map-cache/issues"
   },
-  "homepage": "https://github.com/crper/fast-map-cache#readme"
-}
+  "homepage": "https://github.com/crper/fast-map-cache#readme",
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint",
+    "build": "pnpm lint && pnpm type-check && tsdown",
+    "bench": "vitest bench --run",
+    "run:example": "npx tsx examples/01-basic-example.ts",
+    "type-check": "tsc --noEmit",
+    "format": "prettier --write .",
+    "gen-report": "pnpm bench && tsx scripts/generate-performance-report.ts",
+    "changeset": "changeset",
+    "version:packages": "changeset version",
+    "release": "pnpm build && changeset publish"
+  }
+}