js-loading-cache 

A loading cache implementation with possibility to set a maximum size and timeout entries

Usage

``js
import LoadingCache from '@aftonbladet/loading-cache';
import request from 'co-request';

const cache = new LoadingCache(url => request(url), {
maxAge: 1000 60 5,
maxEntries: 1000
});

cache.get('http://example.com')
.then(result => {
});
`

API

$3

#### constructor([options])
Creates a new LoadingCache instance

* {object} options: A config object to configure how the cache behaves:
* {number} maxEntries: The maximum total amount of entries in the cache. See Eviction for how entries are removed from the cache.
* {number} maxAge: The maximum time (in milliseconds) an entry remains in the cache. If provided it should be a number larger than 0.
* {number} freshAge: The amount of time in milliseconds entries are considered to be fresh. See Serving stale entries for details.
* {Function} defaultLoader: This function is called with the key to populate if the value is not
found in the cache. The function must return a value synchronously, but it is ok to return a Promise if works needs to be done async.

$3


#### get(key, [loaderFn])
Fetches an item from the cache. If key is not already in the cache then loaderFn, provided in the constructor, is
invoked and the cache populated for that key.

Get always returns a Promise for a value, to allow the loader function to work asynchronously.

{} key: Any value that is a valid key for a Map works as a key in the LoadingCache.
* {Function} [loaderFn]: Optional if defaultLoader was specified when constructing the cache instance.
This function is called with the key to populate if the value is not
found in the cache. The function must return a value synchronously, but it is ok to return a Promise if works needs to be done async.

Returns: Promise{} - The value returned by loaderFn wrapped in a Promise.

#### has(key)
Checks if a key has an entry in the cache. Does _NOT_ invoke the loader function if the
key is not in th cache.

{} key: The key to check in the cache
* Returns: {boolean} - true if key is in the cache, false otherwise

#### clear()
Empties the cache

$3


#### {number} size
The current number of entries in the cache

#### {number|undefined} maxEntries
The maximum amount of entries allowed in the cache

#### {number|undefined} maxAge
The maximum amount of time entries are allowed to stay in the cache in milliseconds.

#### {number|undefined} freshAge
The amount of time in milliseconds entries are considered to be fresh. Entries that are older than freshAge will
continue to be served (as long as they are not evicted by maxAge), but the loaderFn will trigger an update in
the background.
Note maxAge need to be larger than freshAge for this to have any effect.

Cache eviction

The default cache eviction strategy is based upon an LRU-scheme. This means that "hot" items that are fetched often
have a higher chance to remain in the cache, while entries that are fetched only a few times will eventually be
evicted from the cache.

NOTE: You must provide a value for maxEntries for this to apply.

Additionally, entries can have a maxAge. Cache entries that have expired are evicted before items are evicted due
to a cache size exceeding maxEntries.

If you are not happy with the default eviction implementation, you can provide your own eviction strategy to the
constructor. The cache expects to receive an object (or constructor function) with the following interface:

Serving stale entries

If both the maxAge and freshAge properties are set, the cache will be able to serve stale entries in the time
period after freshAge but before maxAge. The stale content will be served during the loaderFn is busy updating
the cache entry or even if an error occurs in the loaderFn.

This can be used to make sure that you always return a cached entry quickly and let the update continue in the
background. It is also useful to be able to return stale content during a restart of a backing service or maybe
a network glitch or similar.

$3

#### constructor({maxEntries, maxAge, freshAge})
Constructs a new eviction strategy based upon the provided constructor function. You can either pass in the
constructor function, in which case you'll receive maxEntries, maxAge and freshAge as an config object argument,
or you can construct the eviction API yourself and provide that object to the constructor of the LoadingCache.

#### onLoad(key, val, entries)
Called after the cache received a value from the loaderFn. Note that entries has already been populated with
val at this point.

{} key: The key of val, which is the loaded value.
{Promise<>} val: A Promise for the eventual value of val.
* {Map} entries: All the entries in the cache, including val.

#### onGet(key, val, entries)
Called after key was found in the cache. Here you can perform management tasks such as keeping track of which
keys are fetched etc.

{} key: The key that was fetched
{Promise<>} val: A Promise for the eventual value of val corresponding to key.
* {Map} entries: All the entries in the cache.

#### isValid(key, val, entries)
Called when key has an entry in the cache, but before val is returned to the caller.

{} key: The key that was fetched
{Promise<>} val: A Promise for the eventual value of val corresponding to key.
* {Map} entries: All the entries in the cache.
* Returns: {boolean} - true if val is a valid entry for key, false otherwise.