A least-recently-used cache in 35 lines of code
npm install 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!
``
$ npm install --save tmp-cache
`js
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
`
Aside from the items & changes mentioned below, tmp-cache extends the Map class, so all properties and methods are inherited.
Returns: Cache extends Map
#### options.max
Type: Number
Default:
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 the options.max value.
#### options.maxAge
Type: Number
Default:
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:
Allow an expired/stale item's value to be returned before deleting it.
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:
Optionally override the options.maxAge for this (single) operation.
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:
Refresh the item's expiration date, marking it as _more_ recently used.
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.
MIT © Luke Edwards