weak-lru-cache

library1.2.2jsnpmunverified

A cache that combines LRU/LFU (LRFU) expiration with weak references, allowing garbage collection to reclaim unused cache entries. The cache retains strongly referenced data until it falls out of the LRU/LFU order, then uses weak references so the GC can free memory if needed. This package provides the WeakLRUCache class, which extends Map, and is suitable for Node.js (v14.10+) and Deno. Current version 1.2.2 is stable with a moderate release cadence. Compared to other LRU caches, weak-lru-cache's key differentiator is its use of weak references to avoid holding memory unnecessarily, making it ideal for large object caches where memory pressure is a concern.

storage

npm install weak-lru-cache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · WEAK-LRU-CACHE

weak-lru-cache

storagejavascriptv1.2.2

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.

WeakLRUCache

✓ import { WeakLRUCache } from 'weak-lru-cache'

✗ const WeakLRUCache = require('weak-lru-cache')

Package provides both ESM and CJS, but named export is preferred. CJS require returns the module object, not WeakLRUCache directly.

default export

✓ import WeakLRUCache from 'weak-lru-cache'

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

A default export is also available. In CJS, use require and access .default only if using the ESM default.

WeakLRUCache type

✓ import type { WeakLRUCache } from 'weak-lru-cache'

✗ import { WeakLRUCache } from 'weak-lru-cache' // used as type

TypeScript users can import type to avoid runtime overhead, but the class is also a value.

Imports WeakLRUCache, creates a cache instance, sets and gets a value; demonstrates basic usage with an object.

import { WeakLRUCache } from 'weak-lru-cache'; const cache = new WeakLRUCache(); cache.setValue('key1', { data: 'hello' }); const val = cache.getValue('key1'); console.log(val); // { data: 'hello' } // After GC and LRFU expiration, val may become undefined

Debug

Known issues

gotchaWeak references only work with objects; primitives (string, number, etc.) are stored strongly and removed immediately upon expiration, not garbage collected.

fix

Always use object values if you want weak reference behavior.

affects: >=1.0.0

gotchaThe cache extends Map, so Map methods like .get() and .set() are available, but they use strong references and do not have expiration logic. Use getValue() and setValue() for LRFU expiration.

fix

Use getValue() and setValue() instead of Map's get/set to get LRFU expiration and weak behavior.

affects: >=1.0.0

breakingNode.js v14.10+ is required for WeakRef and FinalizationRegistry support. Older versions throw errors unless --harmony-weak-ref flag is used (v13).

fix

Use Node.js v14.10 or later, or enable the harmony flag in v13.

affects: >=1.0.0

gotchaCache expirationPriority uses a sum of about 100,000 by default; larger values expire sooner. If you set very large priorities, cache size may be much smaller than expected.

fix

Adjust expirationPriority to match your memory budget; for a 100 MB limit, set priority = sizeOfObject >> 10.

affects: >=1.0.0

gotchaThe cache does not automatically clear finalized weak entries until explicitly accessed or iterated; memory for the key may persist until the cache is mutated.

fix

Periodically call .expire() or .delete() to clean up finalized entries if memory usage is a concern.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: WeakLRUCache is not a constructor

Using CJS require without destructuring or incorrectly importing the default.

fix

Use 'const { WeakLRUCache } = require('weak-lru-cache');' or 'import WeakLRUCache from 'weak-lru-cache';'

ReferenceError: WeakRef is not defined

Running on a Node.js version that does not support WeakRef (pre-v14.10) without the harmony flag.

fix

Upgrade Node.js to v14.10+ or run with '--harmony-weak-ref' flag.

TypeError: cache.setValue is not a function

Using Map's .set() method instead of .setValue() or incorrectly importing the module.

fix

Use 'cache.setValue(key, value)' or ensure you imported WeakLRUCache correctly.

Upgrade

Version history

1.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

38 hits · last 30 days

node

OpenAI (training)

Resources

githubssh://git@github.com/kriszyp/weak-lru-cache ↗

packageweak-lru-cache ↗

homepagehttps://github.com/kriszyp/weak-lru-cache#readme ↗