lru-cache

library11.5.1jsnpmunverified

A high-performance LRU (Least Recently Used) cache for JavaScript. Current stable version is 11.5.1, with active development and frequent releases. Key differentiators: one of the most performant LRU implementations in JavaScript, supports both CommonJS and ES modules, TypeScript types included, and offers flexible options like max size with size calculation, TTL, dispose callbacks, fetch-method for stale-while-revalidate patterns. Notably requires at least one of max, ttl, or maxSize to prevent unbounded storage. Version 7+ saw major internal rewrites for performance; from v10, `fetch()` changed signature (removed stale boolean).

storage

npm install lru-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LRU-CACHE

lru-cache

storagejavascriptv11.5.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LRUCache

✓ import { LRUCache } from 'lru-cache'

✗ const LRUCache = require('lru-cache')

ESM import is preferred; CommonJS works in Node.js but `require` returns an object with LRUCache property.

LRUCache

✓ const { LRUCache } = require('lru-cache')

✗ const LRUCache = require('lru-cache').default

No default export; must destructure. This is correct for CommonJS.

LRUCache

✓ import { type LRUCacheOptions } from 'lru-cache'

✗ import LRUCacheOptions from 'lru-cache'

Type imports should use `type` prefix; options type is exported for TypeScript users.

Creates an LRU cache with max 500 items and 5-minute TTL, then sets and gets a string key-value pair.

import { LRUCache } from 'lru-cache' const cache = new LRUCache<string, string>({ max: 500, ttl: 1000 * 60 * 5 }) cache.set('key', 'value') console.log(cache.get('key')) // 'value' cache.clear()

Debug

Known issues

breakingLRUCache.fetch() signature changed in v10: removed the 'stale' boolean option; stale behavior is now controlled by the allowStale option on the cache.

fix

Use allowStale: true in cache options instead of passing stale as a fetch() parameter.

affects: >=10.0.0

breakingVersion 7 completely rewrote internals; constructor options and dispose signature changed (no longer supports async dispose).

fix

If upgrading from v6, see migration guide: dispose must be synchronous; use disposeAfter for async cleanup.

affects: >=7.0.0 <8.0.0

deprecatedUsing max: 0 without ttl or maxSize is allowed but deprecated; it causes unbounded growth and poor performance.

fix

Always set a max, ttl, or maxSize to prevent unbounded memory usage.

affects: >=7.0.0

gotchaNon-string keys must be object references, not equal objects. Two separate objects with same properties are different keys.

fix

Ensure you use the same object reference for get() and set(). Use Map for value equality.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: LRUCache is not a constructor

Importing the module incorrectly; expecting a default export.

fix

Use named import: const { LRUCache } = require('lru-cache') or import { LRUCache } from 'lru-cache'

ERR_INVALID_ARG_TYPE: The 'max' option must be a non-negative integer or Infinity

Passing a string or non-integer number to max option.

fix

Set max to a positive integer (e.g., max: 500) or undefined.

TypeError: invalid argument: 'sizeCalculation' must be a function or undefined

Setting sizeCalculation to something other than a function when maxSize is set.

fix

Provide a function: sizeCalculation: (value, key) => { return 1 }

Upgrade

Version history

11.5.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

19 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubssh://git@github.com/isaacs/node-lru-cache ↗

packagelru-cache ↗

homepagehttps://github.com/isaacs/node-lru-cache#readme ↗