rache

library1.0.0jsnpmunverified

A random-eviction cache library for Node.js that imposes a global size limit across all derived sub-caches. v1.0.0 is stable, with constant-time get, set, delete, and eviction. Unlike typical per-cache limit caches, Rache shares a memory budget among multiple caches via a simple global counter, making it ideal for scenarios with many small caches. No external dependencies, no runtime dependencies. Uses CommonJS, no TypeScript types provided.

storage

npm install rache

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · RACHE

rache

storagejavascriptv1.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.

Rache

✓ const Rache = require('rache')

✗ import Rache from 'rache'

Package uses CommonJS; ESM import not available. Use require() in Node.js.

new Rache({ maxSize })

✓ const cache = new Rache({ maxSize: 100 })

✗ const cache = new Rache(100)

Constructor expects an options object, not a number directly.

cache.sub()

✓ const sub = cache.sub()

✗ const sub = new Rache({ maxSize: someSize })

To share global limit, use .sub() or Rache.from(cache). Creating a new Rache() with options creates an independent cache.

Creates a global-limited cache, adds entries, observes eviction, deletes, iterates keys, clears, and destroys a sub-cache.

const Rache = require('rache') const cache = new Rache({ maxSize: 3 }) const subCache = cache.sub() cache.set('a', 1) subCache.set('b', 2) console.log(cache.get('a')) // 1 console.log(subCache.get('b')) // 2 console.log(cache.globalSize) // 2 console.log(cache.maxSize) // 3 cache.set('c', 3) subCache.set('d', 4) // evicts one console.log(cache.globalSize) // 3 (one evicted) cache.delete('a') console.log(cache.globalSize) // 2 for (const key of cache.keys()) { console.log(key) // 'b', 'c', or 'd' } cache.clear() console.log(cache.size) // 0 subCache.destroy()

Debug

Known issues

gotchaGlobal maxSize limit is shared across all sub-caches; eviction is random and global, not per sub-cache

fix

Design systems to expect entries from any sub-cache may be evicted when total entries exceed maxSize.

affects: >=1.0.0

gotchaNo time-based expiration or LRU eviction; only random eviction when global size exceeds maxSize

fix

If you need TTL or LRU, consider another library (e.g., lru-cache).

affects: >=1.0.0

gotchadestroy() must be called on sub-caches to avoid memory leaks; the cache is not garbage-collected if sub-caches still reference it

fix

Always call subCache.destroy() when you're done using a sub-cache.

affects: >=1.0.0

gotchakeys() and values() return iterators, not arrays; converting to array via [...cache.keys()] materializes all keys

fix

Use iterator methods directly (for...of) or spread into array only for small caches.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Rache is not a constructor

Using ESM import incorrectly or misspelled require

fix

Use const Rache = require('rache') (CommonJS only).

Error: maxSize must be a positive integer

Passing a non-number or negative number in options

fix

Use new Rache({ maxSize: 100 }) with a positive integer.

Cannot read properties of undefined (reading 'get')

Using a destroyed cache

fix

Do not call methods on a cache after destroy(). Call .destroy() only when done.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/holepunchto/rache ↗

packagerache ↗

homepagehttps://github.com/holepunchto/rache#readme ↗