tmp-cache
A least-recently-used cache in 35 lines of code~!
LRU caches operate on a first-in-first-out queue. This means that the first item is the oldest and will therefore be deleted once the max
limit has been reached.
When a maxAge
value is set, items are given an expiration date. This allows existing items to become stale over time which, depending on your stale
config, is equivalent to the item not existing at all!
In order to counteract this idle decay, all set()
and get()
operations on an item "refresh" its expiration date. By doing so, a new expires
value is issued & the item is moved to the end of the list β aka, it's the newest kid on the block!
Install
$ npm install --save tmp-cache
Usage
const Cache = require('tmp-cache');
let cache = new Cache(3); // sets "max" size
cache.set('a', 1); //~> ['a']
cache.set('b', 2); //~> ['a', 'b']
cache.set('c', 3); //~> ['a', 'b', 'c']
cache.get('a'); //~> ['b', 'c', 'a']
cache.set('d', 4); //~> ['c', 'a', 'd']
cache.peek('a'); //~> ['c', 'a', 'd']
cache.delete('d'); //~> ['c', 'a']
cache.has('d'); //=> false
cache.set('e', 5); //~> ['c', 'a', 'e']
cache.size; //=> 3
cache.clear(); //~> []
cache = new Cache({ maxAge:10 });
cache.set(123, 'hello'); //~> valid for 10ms
cache.get(123); //=> 'hello' -- resets 10ms counter
setTimeout(_ => cache.get(123), 25); //=> undefined
cache = new Cache({ maxAge:0, stale:true });
cache.set('foo', [123]); //~> already stale, 0ms lifespan
cache.get('foo'); //=> [123] -- because options.stale
cache.get('foo'); //=> undefined -- previous op flagged removal
API
Aside from the items & changes mentioned below, tmp-cache
extends the Map
class, so all properties and methods are inherited.
Cache(options)
Returns: Cache extends Map
options.max
Type: Number
Default: Infinity
The maximum number of items the cache will hold. Adding more entries will force the oldest, least-recently-used item to be purged.
Failure to include any max
restriction could potentially allow infinite unique entries! They will only be purged based on their expires
value (if set).
Note: If
options
is an integer, then it is used as theoptions.max
value.
options.maxAge
Type: Number
Default: -1
The maximum age (in ms) an item is considered valid; aka, its lifespan.
Items are not pro-actively pruned out as they age, but if you try to access an item that has expired, it will be purged and, by default, result in an undefined
response.
options.stale
Type: Boolean
Default: false
Allow an expired/stale item's value to be returned before deleting it.
Cache.set(key, value, maxAge?)
Persists the item and its value into the Cache. If a maxAge
value exists (via custom or cache-level options), an expiration date will also be stored.
When setting or updating an item that already exists, the original is removed. This allows the new item to be unique & the most recently used!
key
Type: String
The item's unique identifier.
value
Type: Mixed
The item's value to cache.
maxAge
Type: Number
Default: options.maxAge
Optionally override the options.maxAge
for this (single) operation.
Cache.get(key, mutate?)
Retrieve an item's value by its key name. By default, this operation will refresh/update the item's expiration date.
May also return undefined
if the item does not exist, or if it has expired & stale
is not set.
key
Type: String
The item's unique identifier.
mutate
Type: Boolean
Default: true
Refresh the item's expiration date, marking it as more recently used.
Cache.peek(key)
Return an item's value without updating its position or refreshing its expiration date.
May also return undefined
if the item does not exist, or if it has expired & stale
is not set.
key
Type: String
The item's unique identifier.
License
MIT Β© Luke Edwards