简体中文 | English

Fast Map Cache

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:

• 🚀 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.

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

# pnpm (recommended)
pnpm add fast-map-cache

# npm
npm install fast-map-cache

# yarn
yarn add fast-map-cache

Quick Start

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.

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)

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 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.

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.

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. You can run it directly with pnpm run:example.

API Reference

The cache instance created by createCache implements IFastCache. FastCacheWithTTL additionally satisfies IFastTTLCache and exposes cleanup() and destroy().

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. 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. This is a convenience API, not a guaranteed performance optimization.

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:

{
  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. 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.

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

Contributions are welcome! Please see the Contributing Guide for details on how to get started.

License

This project is licensed under the MIT License.