lru-cache

lru-cache is one of the most widely used caching primitives in the JavaScript ecosystem, providing a Map-like store that automatically evicts the least-recently-used entries once a configured bound is reached. It supports bounding by item count, total size, or TTL (individually or combined), and exposes a fetch() method for stale-while-revalidate style async caching with background refresh and abort-signal support.

Written in TypeScript and maintained by npm creator Isaac Z. Schlueter, the library ships as a dual ESM/CommonJS package with full type definitions, zero runtime dependencies, and diagnostics-channel instrumentation for production observability. It underpins caching in countless downstream packages, from build tools to HTTP clients to ORMs.

What You Get

• A LRUCache class with a Map-like API (get, set, has, delete, clear) plus LRU-specific extras (peek, pop, purgeStale, find)
• Bounding by max item count, maxSize with custom sizeCalculation, and/or ttl, enforced together or independently
• fetch() and forceFetch() for async stale-while-revalidate caching with in-flight de-duplication, AbortSignal support, and background refresh
• dispose/onInsert callbacks for lifecycle hooks (freeing resources, logging insertions)
• Full TypeScript types, dual ESM/CommonJS builds via tshy, and zero runtime dependencies
• Built-in node:diagnostics_channel metrics and tracing channels for production observability

Common Use Cases

• In-process memoization of expensive computations or database/API lookups behind a bounded cache
• HTTP response or resolved-module caching inside build tools, bundlers, and CLIs
• Bounding memory growth for per-request or per-session object caches in long-running Node.js services
• Stale-while-revalidate data fetching where a background refresh keeps a cache warm without blocking callers

Under The Hood

Architecture: The entire implementation lives in a single ~3,200-line src/index.ts module centered on the LRUCache<K, V, FC> class (defined at line 1211). Rather than a conventional node-per-object doubly-linked list, it pre-allocates parallel typed arrays (Uint8Array/Uint16Array/Uint32Array chosen by max size) to represent the next/prev links, keys, values, sizes, and TTL timestamps, indexed by integer position. This avoids per-entry object allocation and garbage-collection pressure, which is the source of its performance advantage over object-graph-based LRU implementations, at the cost of requiring a max, maxSize, or ttl bound to be specified up front so storage can be sized.

Tech Stack: Pure TypeScript with no runtime dependencies. The package is built with tshy to emit dual ESM/CommonJS output (with separate browser/node dialects) and ships hand-written .d.ts types. Tooling includes oxlint for linting, prettier for formatting, tap for the test runner, and typedoc for API documentation generation.

Code Quality: The test/ directory contains 30+ focused test files (basic.ts, ttl.ts, fetch.ts, dispose.ts, memo.ts, purge-stale-exhaustive.ts, etc.) covering eviction ordering, TTL edge cases, memory-leak avoidance, and map-like compatibility, run under tap. The single-file architecture is heavily commented and organized into clearly delimited sections (types, internal helpers, the class body), and strict TypeScript typing is used throughout including branded types (PosInt, Index) to prevent misuse of raw numbers as array indices.

API Design: The public API deliberately mirrors the built-in Map interface (get/set/has/delete/clear) so it’s a near drop-in replacement, while layering on cache-specific options (ttl, sizeCalculation, dispose, fetchMethod) that can be set globally or overridden per-call. The constructor requires at least one bounding option (max, maxSize, or ttl) which is an intentional API guardrail against unbounded memory growth. Extensive JSDoc comments and a published TypeDoc site cover every option.