Rache

A random-eviction cache which imposes a global cache-size limit on all the caches derived from it.

Useful when you have many caches and want to limit their memory usage as a whole, instead of per cache.

The get and set operations as well as delete (and cache eviction) take constant time.

Install

npm i rache

Usage

const Rache = require('rache')

const cache = new Rache({ maxSize: 3 })
const cache2 = cache.sub()
const cache3 = cache.sub()

cache.set('key', 'value')
cache2.set('key', 'otherValue')
cache3.set('some', 'thing')

// cache 1 is a separate cache from cache2 and cache3
console.log('cached:', cache.get('key')) // 'value'

// But they share the same global size
console.log(cache.globalSize, 'of', cache.maxSize) // 3 of 3

cache.set('key2', 'another value')
// The cache was full, so one of the existing 3 entries got evicted

console.log(cache.globalSize, 'of', cache.maxSize) // 3 of 3

API

const cache = new Rache({ maxSize=65536 })

Create a new cache.

maxSize is the maximum amount of entries globally, across this cache and all derived caches (derived with cache.sub() or Rache.from(cache)).

const subCache = cache.sub()

Create a new cache which shares the global memory limit with the original cache.

const aCache = Rache.from(cache?)

Create a new rache instance.

If an existing cache is passed in, it will create a sub-cache (equivalent to aCache = cache.sub()).

Otherwise (if no cache or a falsy value is passed in), it will create a new cache (equivalent to aCache = new Rache()).

cache.globalSize

The current amount of entries across all caches.

cache.maxSize

The maximum amount of entries across all caches.

cache.size

The amount of entries in this specific cache.

cache.set(key, value)

Set the key to the given value.

If the global cache size was at the limit, a random old entry is evicted from the cache.

cache.delete(key)

Delete the entry corresponding to key, if any.

Returns true if an entry was deleted, false otherwise.

cache.get(key)

Returns the value corresponding to the given key, or undefined if there is none.

cache.keys()

Returns an iterator over the keys of this particular cache.

cache.values()

Returns an iterator over the values of this particular cache.

cache.clear()

Clear all entries from this particular cache.

After clearing, new entries can again be added to the cache.

cache.destroy()

Destroys the cache. The cache should no longer be used after it has been destroyed.