{"id":46790,"library":"weak-lru-cache","title":"weak-lru-cache","description":"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.","status":"active","version":"1.2.2","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/kriszyp/weak-lru-cache","tags":["javascript","cache","weak","references","LRU","LRFU","typescript"],"install":[{"cmd":"npm install weak-lru-cache","lang":"bash","label":"npm"},{"cmd":"yarn add weak-lru-cache","lang":"bash","label":"yarn"},{"cmd":"pnpm add weak-lru-cache","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package provides both ESM and CJS, but named export is preferred. CJS require returns the module object, not WeakLRUCache directly.","wrong":"const WeakLRUCache = require('weak-lru-cache')","symbol":"WeakLRUCache","correct":"import { WeakLRUCache } from 'weak-lru-cache'"},{"note":"A default export is also available. In CJS, use require and access .default only if using the ESM default.","wrong":"const WeakLRUCache = require('weak-lru-cache').default","symbol":"default export","correct":"import WeakLRUCache from 'weak-lru-cache'"},{"note":"TypeScript users can import type to avoid runtime overhead, but the class is also a value.","wrong":"import { WeakLRUCache } from 'weak-lru-cache' // used as type","symbol":"WeakLRUCache type","correct":"import type { WeakLRUCache } from 'weak-lru-cache'"}],"quickstart":{"code":"import { WeakLRUCache } from 'weak-lru-cache';\n\nconst cache = new WeakLRUCache();\ncache.setValue('key1', { data: 'hello' });\nconst val = cache.getValue('key1');\nconsole.log(val); // { data: 'hello' }\n// After GC and LRFU expiration, val may become undefined","lang":"typescript","description":"Imports WeakLRUCache, creates a cache instance, sets and gets a value; demonstrates basic usage with an object."},"warnings":[{"fix":"Always use object values if you want weak reference behavior.","message":"Weak references only work with objects; primitives (string, number, etc.) are stored strongly and removed immediately upon expiration, not garbage collected.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use getValue() and setValue() instead of Map's get/set to get LRFU expiration and weak behavior.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use Node.js v14.10 or later, or enable the harmony flag in v13.","message":"Node.js v14.10+ is required for WeakRef and FinalizationRegistry support. Older versions throw errors unless --harmony-weak-ref flag is used (v13).","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Adjust expirationPriority to match your memory budget; for a 100 MB limit, set priority = sizeOfObject >> 10.","message":"Cache 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Periodically call .expire() or .delete() to clean up finalized entries if memory usage is a concern.","message":"The cache does not automatically clear finalized weak entries until explicitly accessed or iterated; memory for the key may persist until the cache is mutated.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.2.2':68 'allow':15 'avoid':95 'cach':4,6,21,24,80,84,105,113 'cadenc':75 'class':54 'collect':17 'combin':8 'compar':76 'concern':111 'current':66 'data':28 'deno':65 'differenti':87 'entri':22 'expir':11 'extend':56 'fall':31 'free':45 'garbag':16 'gc':43 'hold':96 'ideal':101 'javascript':112 'key':86 'larg':103 'lrfu':10,117 'lru':3,79,83,116 'lru/lfu':9,35 'make':99 'map':57 'memori':46,97,107 'moder':73 'need':48 'node.js':62 'object':104 'order':36 'packag':50 'pressur':108 'provid':51 'reclaim':19 'refer':14,40,93,115 'referenc':27 'releas':74 'retain':25 'stabl':70 'strong':26 'suitabl':60 'typescript':118 'unnecessarili':98 'unus':20 'use':38,90 'v14.10':63 'version':67 'weak':2,13,39,82,92,114 'weak-lru-cach':1,81 'weaklrucach':53","created_at":"2026-06-07T13:01:38.875156+00:00","updated_at":"2026-06-07T13:01:38.875156+00:00","problems":[{"fix":"Use 'const { WeakLRUCache } = require('weak-lru-cache');' or 'import WeakLRUCache from 'weak-lru-cache';'","cause":"Using CJS require without destructuring or incorrectly importing the default.","error":"TypeError: WeakLRUCache is not a constructor"},{"fix":"Upgrade Node.js to v14.10+ or run with '--harmony-weak-ref' flag.","cause":"Running on a Node.js version that does not support WeakRef (pre-v14.10) without the harmony flag.","error":"ReferenceError: WeakRef is not defined"},{"fix":"Use 'cache.setValue(key, value)' or ensure you imported WeakLRUCache correctly.","cause":"Using Map's .set() method instead of .setValue() or incorrectly importing the module.","error":"TypeError: cache.setValue is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/kriszyp/weak-lru-cache#readme","github":"ssh://git@github.com/kriszyp/weak-lru-cache","docs":null,"changelog":null,"pypi":null,"npm":"weak-lru-cache","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}