Optional allowAllow LRUCache#get and LRUCache#fetch calls to return stale data, if available.
Optional allowSet to true to return a stale value from the cache when the
AbortSignal passed to the OptionsBase.fetchMethod dispatches an 'abort'
event, whether user-triggered, or due to internal cache behavior.
Unless OptionsBase.ignoreFetchAbort is also set, the underlying OptionsBase.fetchMethod will still be considered canceled, and any value it returns will be ignored and not cached.
Caveat: since fetches are aborted when a new value is explicitly
set in the cache, this can lead to fetch returning a stale value,
since that was the fallback value at the moment the fetch() was
initiated, even though the new updated value is now present in
the cache.
For example:
const cache = new LRUCache<string, any>({
ttl: 100,
fetchMethod: async (url, oldValue, { signal }) => {
const res = await fetch(url, { signal })
return await res.json()
}
})
cache.set('https://example.com/', { some: 'data' })
// 100ms go by...
const result = cache.fetch('https://example.com/')
cache.set('https://example.com/', { other: 'thing' })
console.log(await result) // { some: 'data' }
console.log(cache.get('https://example.com/')) // { other: 'thing' }
Optional allowSet to true to allow returning stale data when a OptionsBase.fetchMethod throws an error or returns a rejected promise.
This differs from using OptionsBase.allowStale in that stale data will ONLY be returned in the case that the LRUCache#fetch fails, not any other times.
Optional disposeFunction that is called on items when they are dropped from the cache.
This can be handy if you want to close file descriptors or do other
cleanup tasks when items are no longer accessible. Called with key, value. It's called before actually removing the item from the
internal cache, so it is NOT safe to re-add them.
Use OptionsBase.disposeAfter if you wish to dispose items after they have been full removed, when it is safe to add them back to the cache.
Optional disposeThe same as OptionsBase.dispose, but called after the entry is completely removed and the cache is once again in a clean state. It is safe to add an item right back into the cache at this point. However, note that it is very easy to inadvertently create infinite recursion this way.
Optional fetchMethod that provides the implementation for LRUCache#fetch
Optional ignoreSet to true to ignore the abort event emitted by the AbortSignal
object passed to OptionsBase.fetchMethod, and still cache the
resulting resolution value, as long as it is not undefined.
When used on its own, this means aborted LRUCache#fetch calls are not immediately resolved or rejected when they are aborted, and instead take the full time to await.
When used with OptionsBase.allowStaleOnFetchAbort, aborted
LRUCache#fetch calls will resolve immediately to their stale
cached value or undefined, and will continue to process and eventually
update the cache when they resolve, as long as the resulting value is
not undefined, thus supporting a "return stale on timeout while
refreshing" mechanism by passing AbortSignal.timeout(n) as the signal.
Note: regardless of this setting, an abort event is still
emitted on the AbortSignal object, so may result in invalid results
when passed to other underlying APIs that use AbortSignals.
This may be overridden in the OptionsBase.fetchMethod or the call to LRUCache#fetch.
Optional maxThe maximum number of items to store in the cache before evicting old entries. This is read-only on the LRUCache instance, and may not be overridden.
If set, then storage space will be pre-allocated at construction time, and the cache will perform significantly faster.
Note that significantly fewer items may be stored, if OptionsBase.maxSize and/or OptionsBase.ttl are also set.
Optional maxThe maximum allowed size for any single item in the cache.
If a larger item is passed to LRUCache#set or returned by a OptionsBase.fetchMethod, then it will not be stored in the cache.
Optional maxIf you wish to track item size, you must provide a maxSize note that we still will only keep up to max actual items, if max is set, so size tracking may cause fewer than max items to be stored. At the extreme, a single item of maxSize size will cause everything else in the cache to be dropped when it is added. Use with caution!
Note also that size tracking can negatively impact performance, though for most cases, only minimally.
Optional noSet to true to suppress the deletion of stale data when a OptionsBase.fetchMethod returns a rejected promise.
Optional noDo not delete stale items when they are retrieved with LRUCache#get.
Note that the get return value will still be undefined
unless OptionsBase.allowStale is true.
Optional noSet to true to suppress calling the OptionsBase.dispose function if the entry key is still accessible within the cache. This may be overridden by passing an options object to LRUCache#set.
Optional noBoolean flag to tell the cache to not update the TTL when setting a new value for an existing key (ie, when updating a value rather than inserting a new value). Note that the TTL value is always set (if provided) when adding a new entry into the cache.
Has no effect if a OptionsBase.ttl is not set.
Optional sizeA function that returns a number indicating the item's size.
If not provided, and OptionsBase.maxSize or OptionsBase.maxEntrySize are set, then all LRUCache#set calls must provide an explicit SetOptions.size or sizeCalculation param.
Optional ttlMax time in milliseconds for items to live in cache before they are considered stale. Note that stale items are NOT preemptively removed by default, and MAY live in the cache long after they have expired.
Also, as this cache is optimized for LRU/MRU operations, some of the staleness/TTL checks will reduce performance, as they will incur overhead by deleting items.
Must be an integer number of ms. If set to 0, this indicates "no TTL"
0
Optional ttlPreemptively remove stale items from the cache. Note that this may significantly degrade performance, especially if the cache is storing a large number of items. It is almost always best to just leave the stale items in the cache, and let them fall out as new items are added.
Note that this means that OptionsBase.allowStale is a bit pointless, as stale items will be deleted almost as soon as they expire.
false
Optional ttlMinimum amount of time in ms in which to check for staleness. Defaults to 1, which means that the current time is checked at most once per millisecond.
Set to 0 to check the current time every time staleness is tested. (This reduces performance, and is theoretically unnecessary.)
Setting this to a higher value will improve performance somewhat while using ttl tracking, albeit at the expense of keeping stale items around a bit longer than their TTLs would indicate.
1
Optional updateUpdate the age of items on LRUCache#get, renewing their TTL
Has no effect if OptionsBase.ttl is not set.
false
Optional updateUpdate the age of items on LRUCache#has, renewing their TTL
Has no effect if OptionsBase.ttl is not set.
false
Generated using TypeDoc
Options which may be passed to the LRUCache constructor.
Most of these may be overridden in the various options that use them.
Despite all being technically optional, the constructor requires that a cache is at minimum limited by one or more of OptionsBase.max, OptionsBase.ttl, or OptionsBase.maxSize.
If OptionsBase.ttl is used alone, then it is strongly advised (and in fact required by the type definitions here) that the cache also set OptionsBase.ttlAutopurge, to prevent potentially unbounded storage.