Registry / storage / cache-lru

cache-lru

JSON →
library1.2.0jsnpmunverified

Cache-LRU is a minimal JavaScript library that provides an in-memory key-indexed cache with Least-Recently-Used (LRU) purging strategy. Current stable version is 1.2.0, released on 2025-01-27. Unlike many LRU caches (e.g., lru-cache, node-lru-cache), Cache-LRU guarantees strict O(1) time complexity for all main operations (get, set, has, del, touch, peek) including internal LRU reordering, making it suitable for performance-critical applications. It supports optional per-item expiration and a disposal callback. The library is small (≈300 lines), has zero dependencies, and works in both Node.js and browser environments. It exports a single class via CommonJS. No TypeScript types are bundled.

storage
npm install cache-lru
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · CACHE-LRU
C
cache-lru
storagejavascriptv1.2.0
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.

CacheLRU
✓ const CacheLRU = require('cache-lru');
✗ import CacheLRU from 'cache-lru';
Cache-LRU is a CommonJS package; ESM import will not work unless using a bundler that handles CJS interop.
CacheLRU (ESM)
✓ import CacheLRU from 'cache-lru';
If using Node.js with --experimental-require-module or a bundler, ESM default import may work. But the package itself is CJS.
CacheLRU (types)
✓ // @ts-ignore const CacheLRU = require('cache-lru');
✗ import CacheLRU from 'cache-lru';
No TypeScript declarations are provided; you may need to write your own or use a .d.ts stub.

Creates a cache with a limit, stores and retrieves items, demonstrates O(1) operations including touch, peek, has, and disposal callback.

const CacheLRU = require('cache-lru'); const cache = new CacheLRU(); cache.limit(100); // max 100 items cache.set('key1', { data: 42 }, 5000); // expires after 5 seconds cache.set('key2', 'hello'); const val = cache.get('key1'); promotes to MRU console.log(val); // { data: 42 } const exists = cache.has('key3'); console.log(exists); // false cache.peek('key2'); // get without promoting cache.touch('key2'); // explicitly promote cache.dispose((key, value, operation) => { console.log(`Disposed ${key} due to ${operation}`); }); cache.del('key1'); // triggers dispose callback cache.clear(); // remove all
Debug
Known issues
gotcha`del()` throws an exception if the key does not exist, unlike many other caches that silently return.
fix
Use `if (cache.has(key)) cache.del(key);` or wrap in try-catch.
affects: >=1.0.0
gotcha`touch()` throws an exception if the key does not exist.
fix
Always call `has()` before `touch()` or use try-catch.
affects: >=1.0.0
gotcha`limit()` with no arguments returns current limit, but it's documented as returning a Number. However, the signature is `limit(max?: Number): Number`.
fix
`const max = cache.limit();` works; but note that passing `undefined` does NOT change the limit.
affects: >=1.0.0
gotchaThe `expires` parameter in `set()` expects milliseconds, but many users mistakenly pass seconds or Date.now()+ms.
fix
Use `cache.set('key', value, 5000);` for 5 seconds.
affects: >=1.0.0
gotchaNo automatic cleanup for expired items; expired items are only removed on access (`get`, `has`, `peek`, `touch`) or when they become LRU and are purged. Timers are not used.
fix
Manually call `cache.get(key)` to trigger expiration, or use a separate periodic sweep.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: CacheLRU is not a constructor
Using ESM import (import CacheLRU from 'cache-lru') in Node.js without bundler.
fix
Use CommonJS require: `const CacheLRU = require('cache-lru');`.
Error: key "..." not found
Calling `del()` or `touch()` on a non-existent key.
fix
Check existence first with `has()` or wrap in try-catch.
Cannot find module 'cache-lru'
Package not installed or required incorrectly in browser.
fix
Run `npm install cache-lru`. For browser, use a bundler like webpack or browserify, or include dist/cache-lru.js via <script> tag.
Upgrade
Version history
1.2.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
30 hits · last 30 days
node
28
Resources
githubhttps://github.com/rse/cache-lru ↗
packagecache-lru ↗
homepagehttps://github.com/rse/cache-lru ↗
cache-lru — npm install cache-lru · libregistry