Registry / storage / caching-map

caching-map

JSON →
library1.0.2jsnpmunverified

caching-map v1.0.2 is an in-memory LRU cache with an ES6 Map-like API. It supports configurable cache limits, per-key cost for memory-aware eviction, per-key TTL expiration, and a materialize callback to avoid thundering herds for async resources. Unlike lru-cache, it offers easy enable/disable via zero/infinite limits and integrates with promises for async loading. Release cadence is low; no recent updates. Key differentiators include cost-based eviction, expired-key-first eviction, and full iteration order from most to least recently used.

storage
npm install caching-map
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · CACHING-MAP
C
caching-map
storagejavascriptv1.0.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.

caching-map (default export)
✓ const Cache = require('caching-map');
✗ import Cache from 'caching-map';
This package is CommonJS-only. ESM dynamic import works but is not the primary pattern.
Cache (instance methods)
✓ const cache = new Cache(100); cache.get('key'); cache.set('key', value); cache.delete('key'); cache.keys();
✗ Cache.get('key')
Methods are instance methods, not static.
materialize callback
✓ cache.materialize = async (key) => { return fetchData(key); };
✗ new Cache(10, { materialize: fn })
The materialize function is assigned directly to the cache instance, not passed in constructor options.

Shows basic usage: create cache, set materialize callback, get with async resolution, set with TTL and cost, iteration, and expiration.

const Cache = require('caching-map'); const cache = new Cache(10); cache.materialize = async (key) => { // Simulate async fetch with delay return new Promise(resolve => setTimeout(() => resolve(`Value for ${key}`), 100)); }; async function main() { // First call triggers materialize const val1 = await cache.get('a'); console.log(val1); // "Value for a" // Second call returns cached value const val2 = await cache.get('a'); console.log(val2); // "Value for a" (instant) // Check cache stats console.log(cache.size); // 1 console.log([...cache.keys()]); // ['a'] console.log('cost:', cache.cost); // 1 (default cost per key) // Set with custom TTL (100ms) and cost cache.set('b', 'short-lived', { ttl: 100, cost: 2 }); console.log(cache.size); // 2 await new Promise(r => setTimeout(r, 150)); console.log(cache.has('b')); // false (expired) console.log(cache.size); // 1 } main();
Debug
Known issues
gotchamaterialize must be a function that returns a value (not a Promise) or a Promise. In previous versions, the return value was used as-is; if you return a Promise, cache.get returns that Promise, not its resolved value. (Current behavior: returns the resolved value if materialize returns a Promise, cache.get resolves it. But be consistent.)
fix
Ensure materialize returns the desired value, or if it returns a Promise, cache.get will wait for it. For synchronous caches, do not return a Promise.
affects: >=1.0.0
gotchaChanging the cache limit at runtime does NOT automatically evict keys. Eviction only happens when a new key is set and the cache exceeds the limit. Setting limit to 0 does not clear the cache; subsequent gets will miss and trigger materialize.
fix
To clear the cache when changing limit, call cache.clear() explicitly.
affects: >=1.0.0
gotchaThe 'cost' option in set() is not the byte size but an arbitrary number. The default is 1, so limit acts as max key count. If you set cost > 1 for some keys, you may hit limit unexpectedly.
fix
Understand that 'limit' is a budget of total cost, not key count. Set appropriate costs consistent with your limit.
affects: >=1.0.0
gotchaExpired keys are only evicted when a new key is added and the cache is over limit. They do NOT expire automatically in the background. An expired key can still exist in the cache and be returned by get()? Actually get() checks TTL and returns undefined if expired. But the entry is still present in internal storage until eviction or explicit delete.
fix
If you need automatic cleanup, use lru-cache with 'ttlAutopurge' or implement periodic pruning.
affects: >=1.0.0
gettingThe constructor second argument can be a Map or another Cache to copy entries. This may cause unexpected behavior if the source has materialize callbacks or custom costs.
fix
If copying, costs are copied from the source only if the source is a Cache; Map entries get default cost (1). TTL is not copied from Map entries; they will have no TTL.
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: cache.materialize is not a function
The materialize property was not assigned or was assigned after attempting to get a missing key.
fix
Assign cache.materialize = async (key) => { ... } before calling cache.get(key).
Cache constructor does not accept an options object
Trying to pass materialize or other options via an object like new Cache({ limit: 10, materialize: fn }). The constructor only accepts (limit, [iterable]).
fix
Use new Cache(limit) and then assign properties like cache.materialize = fn.
Maximum call stack size exceeded
Recursive get inside materialize (materialize calls cache.get on the same key, causing infinite loop).
fix
Ensure materialize does not call cache.get(key) for the same key it's being called for.
Cannot read property 'get' of undefined
Forgot to instantiate the Cache; used Cache.get instead of instance.get.
fix
const cache = new Cache(10); then cache.get(key);
Upgrade
Version history
1.0.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
17 hits · last 30 days
node
16
Resources
githubhttps://github.com/broadly/caching-map ↗
packagecaching-map ↗
homepagehttps://github.com/broadly/caching-map#readme ↗
caching-map — npm install caching-map · libregistry