node-lfu-cache

library5.0.0jsnpmunverified

A least-frequently-used (LFU) cache for Node.js, directly ported from lru-cache but using an LFU eviction algorithm based on the paper by Dhruv Bird. Current version 5.0.0 provides a configurable cache with options for max size, item length calculation, maxAge, dispose callbacks, stale returns, and noDisposeOnSet. The API includes set, get, peek, del, reset, has, and forEach. Unlike LRU caches, which evict least-recently-used items, this cache evicts least-frequently-used items, making it suitable for workloads where access frequency matters more than recency.

storage

npm install node-lfu-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-LFU-CACHE

node-lfu-cache

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

default

✓ import LFU from 'node-lfu-cache'

✗ const LFU = require('node-lfu-cache')

ESM-only since v5.0.0; as of this version, CommonJS require() is no longer supported.

LFU

✓ import LFU from 'node-lfu-cache'

✗ import { LFU } from 'node-lfu-cache'

Default export; no named export exists.

type LFUOptions

✓ import type { LFUOptions } from 'node-lfu-cache'

✗ import { LFUOptions } from 'node-lfu-cache' (value import)

TypeScript users should use type-only import for options interface (available since v3.0.0).

Basic setup and usage of node-lfu-cache: constructor with options, set, get, del, and reset.

import LFU from 'node-lfu-cache'; const cache = new LFU({ max: 500, maxAge: 1000 * 60 * 60 }); cache.set('key', 'value'); console.log(cache.get('key')); // 'value' cache.set('obj', { foo: 'bar' }); console.log(cache.get('obj')); // { foo: 'bar' } cache.del('key'); cache.reset();

Debug

Known issues

breakingVersion 5.0.0 drops CommonJS support; only ESM imports work.

fix

Use import syntax: import LFU from 'node-lfu-cache'. If you need CJS, stay on 4.x.

affects: >=5.0.0

breakingConstructor must be called with new in v5.0.0; calling LFU(options) without new throws TypeError.

fix

Use new LFU(options) instead of LFU(options).

affects: >=5.0.0

deprecatedThe options.length function signature change: in v3+, length receives (value, key) instead of (key, value).

fix

Update your length function to (value, key) => ... . In v5, the order is (value, key) as well.

affects: >=3.0.0 <5.0.0

gotchaSetting an oversized item (length > max) will cause it to be immediately evicted; the dispose callback is NOT called for immediate evictions.

fix

Check item length before setting if you rely on dispose for cleanup.

affects: >=1.0.0

gotchaThe dispose callback is called synchronously before removal; if you try to re-set the same key inside dispose, it will not work unless wrapped in nextTick.

fix

Wrap any cache operations inside dispose with setImmediate or process.nextTick.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: LFU is not a constructor

Using import or require that does not match module system; likely mixing ESM and CJS or forgetting 'new' in v5.

fix

For v5: import LFU from 'node-lfu-cache'; new LFU(options). For older versions: const LFU = require('node-lfu-cache'); new LFU(options).

Module not found: Can't resolve 'node-lfu-cache'

Package not installed or incorrect import path in a bundler (e.g., webpack) that cannot resolve the package.

fix

Run npm install node-lfu-cache --save. If importing from a subpath, use import LFU from 'node-lfu-cache' (not 'node-lfu-cache/src').

ERR_REQUIRE_ESM: require() of ES Module node-lfu-cache not supported

Using require() with v5.0.0 which is ESM-only.

fix

Use import LFU from 'node-lfu-cache' or downgrade to v4.x with const LFU = require('node-lfu-cache').

TypeError: options.length is not a function

Passing options with length option that is not a function; or undefined/null.

fix

Ensure options.length is a function: length: (value, key) => value.length (or similar).

Upgrade

Version history

5.0.0latest on npm

Audit

Dependencies

lru-cacheoptionalPort of lru-cache (spiritual dependency for API design) but not a runtime dependency.

Agent activity

23 hits · last 30 days

node

Amazon

Resources

githubgit://github.com/calvinmetcalf/node-lfu-cache ↗

packagenode-lfu-cache ↗

homepagehttps://github.com/calvinmetcalf/node-lfu-cache#readme ↗