fast-map-cache 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 crper (crper@outlook.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+[简体中文](README_zh-CN.md) | English
+
+# Fast Map Cache
+
+[![NPM Version](https://img.shields.io/npm/v/fast-map-cache.svg?style=flat)](https://www.npmjs.com/package/fast-map-cache)
+[![NPM Downloads](https://img.shields.io/npm/dm/fast-map-cache.svg?style=flat)](https://www.npmjs.com/package/fast-map-cache)
+[![License](https://img.shields.io/npm/l/fast-map-cache.svg?style=flat)](https://github.com/crper/fast-map-cache/blob/main/LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/crper/fast-map-cache/test.yml?branch=main&label=tests&style=flat)](https://github.com/crper/fast-map-cache/actions/workflows/test.yml)
+
+A high-performance in-memory LRU cache for Node.js and browsers, implemented with a `Map` and a doubly linked list to achieve **O(1)** time complexity for all core operations.
+
+## ✨ Performance Highlights
+
+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.
+
+For a detailed analysis, see the full [**Performance Report**](./docs/performance-report.md).
+
+## Features
+
+- **🚀 High Performance**: O(1) time complexity for `get`, `set`, and `delete`.
+- **🛡️ LRU Strategy**: Automatically evicts the least recently used items when the cache is full.
+- **⏱️ TTL Support**: `FastCacheWithTTL` provides support for time-to-live expiration of cache items.
+- **💪 Type-Safe**: Written entirely in TypeScript with zero dependencies.
+- **🌐 Universal**: Works in both Node.js and browser environments.
+- **📊 Stats Tracking**: Built-in tracking for hits, misses, and hit rate.
+
+## Installation
+
+```bash
+# pnpm (recommended)
+pnpm add fast-map-cache
+
+# npm
+npm install fast-map-cache
+
+# yarn
+yarn add fast-map-cache
+```
+
+## Quick Start
+
+```typescript
+import { createCache } from 'fast-map-cache'
+
+// Create a cache with a maximum size of 2
+const cache = createCache<string, number>(2)
+
+cache.set('a', 1)
+cache.set('b', 2)
+
+console.log(cache.get('a')) // Output: 1
+
+// Adding 'c' will evict the least recently used item ('b')
+cache.set('c', 3)
+
+console.log(cache.get('b')) // Output: undefined
+console.log(cache.size) // Output: 2
+```
+
+### Usage with TTL
+
+For caches that require items to expire after a certain period, use `createCacheWithTTL`.
+
+```typescript
+import { createCacheWithTTL } from 'fast-map-cache'
+
+const cache = createCacheWithTTL<string, string>({
+  maxSize: 100,
+  ttl: 5000, // 5 seconds
+})
+
+cache.set('key', 'value')
+
+setTimeout(() => {
+  console.log(cache.get('key')) // Output: undefined
+}, 6000)
+```
+
+### ❗ 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.
+
+**You must manually call the `destroy()` method before your application exits to clear the timer.**
+
+```typescript
+const cache = createCacheWithTTL({ maxSize: 100, autoCleanup: true, ttl: 60000 })
+
+// ... your application logic ...
+
+// Before shutting down your application:
+cache.destroy()
+```
+
+For more advanced use cases, including batch operations and presets, please see the full example file in [`examples/01-basic-example.ts`](./examples/01-basic-example.ts). You can run it directly with `pnpm run:example`.
+
+## API Reference
+
+The cache instance, created by `createCache` or `createCacheWithTTL`, implements the `IFastCache` interface.
+
+### `get(key: K): V | undefined`
+
+Retrieves the value for a given key. Returns `undefined` if the key does not exist or has expired. This operation marks the item as recently used.
+
+### `set(key: K, value: V): void`
+
+Adds or updates a key-value pair. If the key already exists, its value is updated and it is marked as recently used. If the cache is full, the least recently used item is evicted.
+
+> **Note**: While JavaScript's `Map` allows any type as a key, it is recommended to use primitive types (`string`, `number`, `symbol`, `bigint`) for better performance and predictability.
+
+### `delete(key: K): boolean`
+
+Deletes a key-value pair. Returns `true` if the key existed and was deleted, `false` otherwise.
+
+### `has(key: K): boolean`
+
+Checks if a key exists in the cache without updating its "recently used" status. Note: For TTL caches, this will lazily delete the item if it's found to be expired, and then return `false`.
+
+### `clear(): void`
+
+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.
+
+### `setMany(entries: [K, V][]): void`
+
+Adds or updates multiple key-value pairs from an array of entries.
+
+### `size: number` (getter)
+
+Returns the current number of items in the cache.
+
+### `capacity: number` (getter)
+
+Returns the maximum number of items the cache can hold.
+
+### `getStats(): CacheStats`
+
+Returns an object with cache statistics:
+
+```typescript
+{
+  hits: number;
+  misses: number;
+  hitRate: number; // A value between 0 and 1
+  size: number;
+  capacity: number;
+  expired?: number; // Only for TTL caches
+}
+```
+
+### `cleanup(): number` (For `FastCacheWithTTL` only)
+
+Manually triggers the cleanup of expired items. Returns the number of items that were removed.
+
+### `destroy(): void` (For `FastCacheWithTTL` only)
+
+Clears the automatic cleanup timer if `autoCleanup` was enabled. **Crucial for graceful shutdown in Node.js.**
+
+## 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.
+
+## Contributing
+
+Contributions are welcome! Please see the [Contributing Guide](CONTRIBUTING.md) for details on how to get started.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/README_zh-CN.md

@@ -0,0 +1,175 @@
+[简体中文](README_zh-CN.md) | [English](README.md)
+
+# Fast Map Cache
+
+[![NPM Version](https://img.shields.io/npm/v/fast-map-cache.svg?style=flat)](https://www.npmjs.com/package/fast-map-cache)
+[![NPM Downloads](https://img.shields.io/npm/dm/fast-map-cache.svg?style=flat)](https://www.npmjs.com/package/fast-map-cache)
+[![License](https://img.shields.io/npm/l/fast-map-cache.svg?style=flat)](https://github.com/crper/fast-map-cache/blob/main/LICENSE)
+[![Tests](https://img.shields.io/github/actions/workflow/status/crper/fast-map-cache/test.yml?branch=main&label=tests&style=flat)](https://github.com/crper/fast-map-cache/actions/workflows/test.yml)
+
+一个为 Node.js 和浏览器设计的高性能内存 LRU 缓存库。通过 `Map` 和双向链表实现，所有核心操作的时间复杂度均为 **O(1)**。
+
+## ✨ 性能亮点
+
+在真实业务场景中，`fast-map-cache` 通过有效避免高成本操作，展现出显著的性能优势：
+
+- **🚀 可靠性能**: 在真实的 I/O 和 CPU 密集型场景中，通过避免高成本操作，带来 **2-3 倍** 的性能提升。
+
+详细分析请参阅完整的 [**性能报告**](./docs/performance-report.md)。
+
+## 功能特性
+
+- **🚀 高性能**: `get`, `set`, `delete` 等核心操作的时间复杂度均为 O(1)。
+- **🛡️ LRU 策略**: 缓存满时，自动淘汰最久未被使用的数据。
+- **⏱️ TTL 支持**: `FastCacheWithTTL` 类提供了对缓存项生命周期 (TTL) 的支持。
+- **💪 类型安全**: 完全使用 TypeScript 编写，零外部依赖。
+- **🌐 环境通用**: 同时支持 Node.js 和浏览器环境。
+- **📊 状态追踪**: 内置命中、未命中和命中率的统计功能。
+
+## 安装
+
+```bash
+# pnpm (推荐)
+pnpm add fast-map-cache
+
+# npm
+npm install fast-map-cache
+
+# yarn
+yarn add fast-map-cache
+```
+
+## 快速上手
+
+```typescript
+import { createCache } from 'fast-map-cache'
+
+// 创建一个最大容量为 2 的缓存实例
+const cache = createCache<string, number>(2)
+
+cache.set('a', 1)
+cache.set('b', 2)
+
+console.log(cache.get('a')) // 输出: 1
+
+// 添加 'c' 会淘汰最久未使用的 'b'
+cache.set('c', 3)
+
+console.log(cache.get('b')) // 输出: undefined
+console.log(cache.size) // 输出: 2
+```
+
+关于更高级的用法（例如批量操作和预设配置），请参阅完整的示例文件：[`examples/01-basic-example.ts`](./examples/01-basic-example.ts)。您可以直接通过 `pnpm run:example` 命令运行它。
+
+### 带 TTL 的用法
+
+如果缓存项需要在一定时间后过期，请使用 `createCacheWithTTL`。
+
+```typescript
+import { createCacheWithTTL } from 'fast-map-cache'
+
+const cache = createCacheWithTTL<string, string>({
+  maxSize: 100,
+  ttl: 5000, // 5 秒
+})
+
+cache.set('key', 'value')
+
+setTimeout(() => {
+  console.log(cache.get('key')) // 输出: undefined
+}, 6000)
+```
+
+### ❗ Node.js 用户重要提示
+
+在 Node.js 环境下使用 `FastCacheWithTTL` 并开启 `autoCleanup: true` 选项时，系统会使用 `setInterval` 定时清理过期缓存。这个定时器会阻止 Node.js 进程正常退出。
+
+**您必须在程序退出前手动调用 `destroy()` 方法来清除该定时器。**
+
+```typescript
+const cache = createCacheWithTTL({ maxSize: 100, autoCleanup: true, ttl: 60000 })
+
+// ... 你的应用逻辑 ...
+
+// 在应用关闭前:
+cache.destroy()
+```
+
+## API 参考
+
+由 `createCache` 或 `createCacheWithTTL` 创建的缓存实例均实现了 `IFastCache` 接口。
+
+### `get(key: K): V | undefined`
+
+根据键获取值。如果键不存在或已过期，则返回 `undefined`。此操作会将访问项标记为最近使用。
+
+### `set(key: K, value: V): void`
+
+添加或更新一个键值对。如果键已存在，则更新其值并将其标记为最近使用。如果缓存已满，则淘汰最久未使用的项。
+
+> **注意**：虽然 JavaScript 的 `Map` 允许任何类型作为键，但为了获得最佳的性能和可预测性，推荐使用原始类型 (`string`, `number`, `symbol`, `bigint`)。
+
+### `delete(key: K): boolean`
+
+删除一个键值对。如果键存在且被成功删除，返回 `true`，否则返回 `false`。
+
+### `has(key: K): boolean`
+
+检查一个键是否存在于缓存中，此操作**不会**更新其"最近使用"状态。注意：对于带 TTL 的缓存，如果发现该项已过期，会懒惰地删除它，然后返回 `false`。
+
+### `clear(): void`
+
+清空缓存中的所有项目。
+
+### `getMany(keys: K[]): Map<K, V>`
+
+根据键数组批量获取值。返回一个包含已找到的键值对的 `Map`。
+
+### `setMany(entries: [K, V][]): void`
+
+通过一个条目数组批量添加或更新键值对。
+
+### `size: number` (getter)
+
+返回缓存中当前的项目数量。
+
+### `capacity: number` (getter)
+
+返回缓存的最大容量。
+
+### `getStats(): CacheStats`
+
+返回一个包含缓存统计信息的对象：
+
+```typescript
+{
+  hits: number;      // 命中次数
+  misses: number;    // 未命中次数
+  hitRate: number;   // 命中率 (0 到 1 之间)
+  size: number;      // 当前大小
+  capacity: number;  // 最大容量
+  expired?: number; // 已过期数量 (仅限 TTL 缓存)
+}
+```
+
+### `cleanup(): number` (仅 `FastCacheWithTTL` 可用)
+
+手动触发过期项目的清理。返回被移除的项目数量。
+
+### `destroy(): void` (仅 `FastCacheWithTTL` 可用)
+
+如果开启了 `autoCleanup`，此方法用于清除自动清理定时器。**这对于在 Node.js 中实现优雅停机至关重要。**
+
+## 性能基准
+
+本库为真实场景下的高性能而设计。缓存的核心价值不仅在于 `get`/`set` 操作的原始速度，更在于它能够有效避免昂贵的计算或网络请求。
+
+我们的基准测试显示，在模拟真实世界的 I/O 密集和 CPU 密集场景下，`fast-map-cache` 平均能带来 **2 到 3 倍的性能提升**。实际提升效果取决于被缓存操作的成本。
+
+## 贡献
+
+欢迎任何形式的贡献！请参阅 [贡献指南](CONTRIBUTING.md) 以了解如何开始。
+
+## 许可证
+
+本项目采用 [MIT 许可证](LICENSE)。

package/dist/main.d.mts

@@ -0,0 +1,122 @@
+//#region src/types.d.ts
+/**
+ * 基础类型定义
+ */
+type CacheKey = string | number | symbol | bigint;
+interface CacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+  capacity: number;
+  expired?: number;
+}
+interface CacheOptions {
+  maxSize: number;
+  ttl?: number;
+  autoCleanup?: boolean;
+  cleanupInterval?: number;
+}
+interface IFastCache<K extends CacheKey, V> {
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  delete(key: K): boolean;
+  clear(): void;
+  has(key: K): boolean;
+  readonly size: number;
+  readonly capacity: number;
+  setMany(entries: [K, V][]): void;
+  getMany(keys: K[]): Map<K, V>;
+  getStats(): CacheStats;
+  cleanup?(): number;
+}
+interface CacheNode<K extends CacheKey, V> {
+  key: K;
+  value: V;
+  prev: CacheNode<K, V> | null;
+  next: CacheNode<K, V> | null;
+  timestamp?: number;
+  timePrev?: CacheNode<K, V> | null;
+  timeNext?: CacheNode<K, V> | null;
+}
+//#endregion
+//#region src/fast-cache.d.ts
+/**
+ * 高性能 LRU 缓存实现
+ * 使用 Map + 双向链表实现 O(1) 复杂度的所有操作
+ */
+declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
+  protected readonly cache: Map<K, CacheNode<K, V>>;
+  protected readonly head: CacheNode<K, V>;
+  protected readonly tail: CacheNode<K, V>;
+  protected readonly maxSize: number;
+  protected hits: number;
+  protected misses: number;
+  constructor(maxSize: number);
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  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;
+  protected addToHead(node: CacheNode<K, V>): void;
+  protected removeNode(node: CacheNode<K, V>): void;
+  protected moveToHead(node: CacheNode<K, V>): void;
+  protected removeTail(): void;
+}
+//#endregion
+//#region src/fast-cache-ttl.d.ts
+/**
+ * 带 TTL (Time To Live) 支持的高性能缓存实现。
+ * 继承自 FastCache，并增加了一个按时间排序的独立链表，
+ * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
+ *
+ * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
+ * 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
+ * 否则定时器会阻止 Node.js 进程正常退出。
+ */
+declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
+  private readonly ttl;
+  private readonly autoCleanup;
+  private cleanupTimer;
+  private readonly timeHead;
+  private readonly timeTail;
+  private expired;
+  constructor(options: CacheOptions);
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  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;
+  private isExpired;
+  private _addToTimeListTail;
+  private _removeFromTimeList;
+  private _moveToTimeListTail;
+}
+//#endregion
+//#region src/index.d.ts
+declare function createCache<K extends CacheKey, V>(maxSize: number): FastCache<K, V>;
+declare function createCacheWithTTL<K extends CacheKey, V>(options: CacheOptions): FastCacheWithTTL<K, V>;
+declare const CachePresets: {
+  readonly apiCache: <T>(maxSize?: number) => FastCache<string, T>;
+  readonly computeCache: <T>(maxSize?: number) => FastCache<string, T>;
+  readonly sessionCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
+  readonly tempCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
+};
+//#endregion
+export { CacheKey, CacheNode, CacheOptions, CachePresets, CacheStats, FastCache, FastCacheWithTTL, IFastCache, createCache, createCacheWithTTL };

package/dist/main.d.ts

@@ -0,0 +1,122 @@
+//#region src/types.d.ts
+/**
+ * 基础类型定义
+ */
+type CacheKey = string | number | symbol | bigint;
+interface CacheStats {
+  hits: number;
+  misses: number;
+  hitRate: number;
+  size: number;
+  capacity: number;
+  expired?: number;
+}
+interface CacheOptions {
+  maxSize: number;
+  ttl?: number;
+  autoCleanup?: boolean;
+  cleanupInterval?: number;
+}
+interface IFastCache<K extends CacheKey, V> {
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  delete(key: K): boolean;
+  clear(): void;
+  has(key: K): boolean;
+  readonly size: number;
+  readonly capacity: number;
+  setMany(entries: [K, V][]): void;
+  getMany(keys: K[]): Map<K, V>;
+  getStats(): CacheStats;
+  cleanup?(): number;
+}
+interface CacheNode<K extends CacheKey, V> {
+  key: K;
+  value: V;
+  prev: CacheNode<K, V> | null;
+  next: CacheNode<K, V> | null;
+  timestamp?: number;
+  timePrev?: CacheNode<K, V> | null;
+  timeNext?: CacheNode<K, V> | null;
+}
+//#endregion
+//#region src/fast-cache.d.ts
+/**
+ * 高性能 LRU 缓存实现
+ * 使用 Map + 双向链表实现 O(1) 复杂度的所有操作
+ */
+declare class FastCache<K extends CacheKey, V> implements IFastCache<K, V> {
+  protected readonly cache: Map<K, CacheNode<K, V>>;
+  protected readonly head: CacheNode<K, V>;
+  protected readonly tail: CacheNode<K, V>;
+  protected readonly maxSize: number;
+  protected hits: number;
+  protected misses: number;
+  constructor(maxSize: number);
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  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;
+  protected addToHead(node: CacheNode<K, V>): void;
+  protected removeNode(node: CacheNode<K, V>): void;
+  protected moveToHead(node: CacheNode<K, V>): void;
+  protected removeTail(): void;
+}
+//#endregion
+//#region src/fast-cache-ttl.d.ts
+/**
+ * 带 TTL (Time To Live) 支持的高性能缓存实现。
+ * 继承自 FastCache，并增加了一个按时间排序的独立链表，
+ * 以实现 O(M) 复杂度的过期项目清理（M 为过期数量）。
+ *
+ * @important 在 Node.js 环境下使用 `autoCleanup: true` 时，
+ * 必须在程序退出前手动调用 `destroy()` 方法来清理定时器，
+ * 否则定时器会阻止 Node.js 进程正常退出。
+ */
+declare class FastCacheWithTTL<K extends CacheKey, V> extends FastCache<K, V> {
+  private readonly ttl;
+  private readonly autoCleanup;
+  private cleanupTimer;
+  private readonly timeHead;
+  private readonly timeTail;
+  private expired;
+  constructor(options: CacheOptions);
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  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;
+  private isExpired;
+  private _addToTimeListTail;
+  private _removeFromTimeList;
+  private _moveToTimeListTail;
+}
+//#endregion
+//#region src/index.d.ts
+declare function createCache<K extends CacheKey, V>(maxSize: number): FastCache<K, V>;
+declare function createCacheWithTTL<K extends CacheKey, V>(options: CacheOptions): FastCacheWithTTL<K, V>;
+declare const CachePresets: {
+  readonly apiCache: <T>(maxSize?: number) => FastCache<string, T>;
+  readonly computeCache: <T>(maxSize?: number) => FastCache<string, T>;
+  readonly sessionCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
+  readonly tempCache: <T>(maxSize?: number, ttl?: number) => FastCacheWithTTL<string, T>;
+};
+//#endregion
+export { CacheKey, CacheNode, CacheOptions, CachePresets, CacheStats, FastCache, FastCacheWithTTL, IFastCache, createCache, createCacheWithTTL };