rapid_stack 1.0.0 → 1.0.1

data/lib/rapid_stack/generators/generator-rapid/node_modules/lru-cache/README.md

@@ -1,82 +1,28 @@
-# lru-cache
+# lru cache
 
 A cache object that deletes the least-recently-used items.
 
-Specify a max number of the most recently used items that you
-want to keep, and this cache will keep that many of the most
-recently accessed items.
+[![Build Status](https://travis-ci.org/isaacs/node-lru-cache.svg?branch=master)](https://travis-ci.org/isaacs/node-lru-cache) [![Coverage Status](https://coveralls.io/repos/isaacs/node-lru-cache/badge.svg?service=github)](https://coveralls.io/github/isaacs/node-lru-cache)
 
-This is not primarily a TTL cache, and does not make strong TTL
-guarantees. There is no preemptive pruning of expired items by
-default, but you _may_ set a TTL on the cache or on a single
-`set`. If you do so, it will treat expired items as missing, and
-delete them when fetched. If you are more interested in TTL
-caching than LRU caching, check out
-[@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
+## Installation:
 
-As of version 7, this is one of the most performant LRU
-implementations available in JavaScript, and supports a wide
-diversity of use cases. However, note that using some of the
-features will necessarily impact performance, by causing the
-cache to have to do more work. See the "Performance" section
-below.
-
-## Installation
-
-```bash
+```javascript
 npm install lru-cache --save
 ```
 
-## Usage
-
-```js
-// hybrid module, either works
-import LRUCache from 'lru-cache'
-// or:
-const LRUCache = require('lru-cache')
-
-// At least one of 'max', 'ttl', or 'maxSize' is required, to prevent
-// unsafe unbounded storage.
-//
-// In most cases, it's best to specify a max for performance, so all
-// the required memory allocation is done up-front.
-//
-// All the other options are optional, see the sections below for
-// documentation on what each one does.  Most of them can be
-// overridden for specific items in get()/set()
-const options = {
-  max: 500,
-
-  // for use with tracking overall storage size
-  maxSize: 5000,
-  sizeCalculation: (value, key) => {
-    return 1
-  },
-
-  // for use when you need to clean up something when objects
-  // are evicted from the cache
-  dispose: (value, key) => {
-    freeFromMemoryOrWhatever(value)
-  },
-
-  // how long to live in ms
-  ttl: 1000 * 60 * 5,
-
-  // return stale items before removing from cache?
-  allowStale: false,
+## Usage:
 
-  updateAgeOnGet: false,
-  updateAgeOnHas: false,
+```javascript
+var LRU = require("lru-cache")
+  , options = { max: 500
+              , length: function (n, key) { return n * 2 + key.length }
+              , dispose: function (key, n) { n.close() }
+              , maxAge: 1000 * 60 * 60 }
+  , cache = new LRU(options)
+  , otherCache = new LRU(50) // sets just the max size
 
-  // async method to use for cache.fetch(), for
-  // stale-while-revalidate type of behavior
-  fetchMethod: async (key, staleValue, { options, signal }) => {},
-}
-
-const cache = new LRUCache(options)
-
-cache.set('key', 'value')
-cache.get('key') // "value"
+cache.set("key", "value")
+cache.get("key") // "value"
 
 // non-string keys ARE fully supported
 // but note that it must be THE SAME object, not
@@ -90,1028 +36,131 @@ assert.equal(cache.get(someObject), 'a value')
 // because it's a different object identity
 assert.equal(cache.get({ a: 1 }), undefined)
 
-cache.clear() // empty the cache
+cache.reset()    // empty the cache
 ```
 
 If you put more stuff in it, then items will fall out.
 
-## Options
-
-### `max`
-
-The maximum number of items that remain in the cache (assuming no
-TTL pruning or explicit deletions). Note that fewer items may be
-stored if size calculation is used, and `maxSize` is exceeded.
-This must be a positive finite intger.
-
-At least one of `max`, `maxSize`, or `TTL` is required. This
-must be a positive integer if set.
-
-**It is strongly recommended to set a `max` to prevent unbounded
-growth of the cache.** See "Storage Bounds Safety" below.
-
-### `maxSize`
-
-Set to a positive integer to track the sizes of items added to
-the cache, and automatically evict items in order to stay below
-this size. Note that this may result in fewer than `max` items
-being stored.
-
-Attempting to add an item to the cache whose calculated size is
-greater that this amount will be a no-op. The item will not be
-cached, and no other items will be evicted.
-
-Optional, must be a positive integer if provided.
-
-Sets `maxEntrySize` to the same value, unless a different value
-is provided for `maxEntrySize`.
-
-At least one of `max`, `maxSize`, or `TTL` is required. This
-must be a positive integer if set.
-
-Even if size tracking is enabled, **it is strongly recommended to
-set a `max` to prevent unbounded growth of the cache.** See
-"Storage Bounds Safety" below.
-
-### `maxEntrySize`
-
-Set to a positive integer to track the sizes of items added to
-the cache, and prevent caching any item over a given size.
-Attempting to add an item whose calculated size is greater than
-this amount will be a no-op. The item will not be cached, and no
-other items will be evicted.
-
-Optional, must be a positive integer if provided. Defaults to
-the value of `maxSize` if provided.
-
-### `sizeCalculation`
-
-Function used to calculate the size of stored items. If you're
-storing strings or buffers, then you probably want to do
-something like `n => n.length`. The item is passed as the first
-argument, and the key is passed as the second argument.
-
-This may be overridden by passing an options object to
-`cache.set()`.
-
-Requires `maxSize` to be set.
-
-If the `size` (or return value of `sizeCalculation`) for a given
-entry is greater than `maxEntrySize`, then the item will not be
-added to the cache.
-
-Deprecated alias: `length`
-
-### `fetchMethod`
-
-Function that is used to make background asynchronous fetches.
-Called with `fetchMethod(key, staleValue, { signal, options,
-context })`. May return a Promise.
-
-If `fetchMethod` is not provided, then `cache.fetch(key)` is
-equivalent to `Promise.resolve(cache.get(key))`.
-
-The `signal` object is an `AbortSignal` if that's available in
-the global object, otherwise it's a pretty close polyfill.
-
-If at any time, `signal.aborted` is set to `true`, or if the
-`signal.onabort` method is called, or if it emits an `'abort'`
-event which you can listen to with `addEventListener`, then that
-means that the fetch should be abandoned. This may be passed
-along to async functions aware of AbortController/AbortSignal
-behavior.
-
-The `fetchMethod` should **only** return `undefined` or a Promise
-resolving to `undefined` if the AbortController signaled an
-`abort` event. In all other cases, it should return or resolve
-to a value suitable for adding to the cache.
-
-The `options` object is a union of the options that may be
-provided to `set()` and `get()`. If they are modified, then that
-will result in modifying the settings to `cache.set()` when the
-value is resolved, and in the case of `noDeleteOnFetchRejection`
-and `allowStaleOnFetchRejection`, the handling of `fetchMethod`
-failures.
-
-For example, a DNS cache may update the TTL based on the value
-returned from a remote DNS server by changing `options.ttl` in
-the `fetchMethod`.
-
-### `fetchContext`
-
-Arbitrary data that can be passed to the `fetchMethod` as the
-`context` option.
-
-Note that this will only be relevant when the `cache.fetch()`
-call needs to call `fetchMethod()`. Thus, any data which will
-meaningfully vary the fetch response needs to be present in the
-key. This is primarily intended for including `x-request-id`
-headers and the like for debugging purposes, which do not affect
-the `fetchMethod()` response.
-
-### `noDeleteOnFetchRejection`
-
-If a `fetchMethod` throws an error or returns a rejected promise,
-then by default, any existing stale value will be removed from
-the cache.
-
-If `noDeleteOnFetchRejection` is set to `true`, then this
-behavior is suppressed, and the stale value remains in the cache
-in the case of a rejected `fetchMethod`.
-
-This is important in cases where a `fetchMethod` is _only_ called
-as a background update while the stale value is returned, when
-`allowStale` is used.
-
-This is implicitly in effect when `allowStaleOnFetchRejection` is
-set.
-
-This may be set in calls to `fetch()`, or defaulted on the
-constructor, or overridden by modifying the options object in the
-`fetchMethod`.
-
-### `allowStaleOnFetchRejection`
-
-Set to true to return a stale value from the cache when a
-`fetchMethod` throws an error or returns a rejected Promise.
-
-If a `fetchMethod` fails, and there is no stale value available,
-the `fetch()` will resolve to `undefined`. Ie, all `fetchMethod`
-errors are suppressed.
-
-Implies `noDeleteOnFetchRejection`.
-
-This may be set in calls to `fetch()`, or defaulted on the
-constructor, or overridden by modifying the options object in the
-`fetchMethod`.
-
-### `allowStaleOnFetchAbort`
-
-Set to true to return a stale value from the cache when the
-`AbortSignal` passed to the `fetchMethod` dispatches an `'abort'`
-event, whether user-triggered, or due to internal cache behavior.
-
-Unless `ignoreFetchAbort` is also set, the underlying
-`fetchMethod` will still be considered canceled, and its return
-value will be ignored and not cached.
-
-### `ignoreFetchAbort`
-
-Set to true to ignore the `abort` event emitted by the
-`AbortSignal` object passed to `fetchMethod`, and still cache the
-resulting resolution value, as long as it is not `undefined`.
-
-When used on its own, this means aborted `fetch()` calls are not
-immediately resolved or rejected when they are aborted, and
-instead take the full time to await.
-
-When used with `allowStaleOnFetchAbort`, aborted `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.
-
-For example:
-
-```js
-const c = new LRUCache({
-  ttl: 100,
-  ignoreFetchAbort: true,
-  allowStaleOnFetchAbort: true,
-  fetchMethod: async (key, oldValue, { signal }) => {
-    // note: do NOT pass the signal to fetch()!
-    // let's say this fetch can take a long time.
-    const res = await fetch(`https://slow-backend-server/${key}`)
-    return await res.json()
-  },
-})
-
-// this will return the stale value after 100ms, while still
-// updating in the background for next time.
-const val = await c.fetch('key', { signal: AbortSignal.timeout(100) })
-```
-
-**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 on the `fetch()` call or in the
-`fetchMethod` itself.
-
-### `dispose`
-
-Function that is called on items when they are dropped from the
-cache, as `this.dispose(value, key, reason)`.
-
-This can be handy if you want to close file descriptors or do
-other cleanup tasks when items are no longer stored in the cache.
-
-**NOTE**: It is called _before_ the item has been fully removed
-from the cache, so if you want to put it right back in, you need
-to wait until the next tick. If you try to add it back in during
-the `dispose()` function call, it will break things in subtle and
-weird ways.
-
-Unlike several other options, this may _not_ be overridden by
-passing an option to `set()`, for performance reasons. If
-disposal functions may vary between cache entries, then the
-entire list must be scanned on every cache swap, even if no
-disposal function is in use.
-
-The `reason` will be one of the following strings, corresponding
-to the reason for the item's deletion:
-
-- `evict` Item was evicted to make space for a new addition
-- `set` Item was overwritten by a new value
-- `delete` Item was removed by explicit `cache.delete(key)` or by
-  calling `cache.clear()`, which deletes everything.
-
-The `dispose()` method is _not_ called for canceled calls to
-`fetchMethod()`. If you wish to handle evictions, overwrites,
-and deletes of in-flight asynchronous fetches, you must use the
-`AbortSignal` provided.
-
-Optional, must be a function.
-
-### `disposeAfter`
-
-The same as `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 in this way.
-
-The `disposeAfter()` method is _not_ called for canceled calls to
-`fetchMethod()`. If you wish to handle evictions, overwrites,
-and deletes of in-flight asynchronous fetches, you must use the
-`AbortSignal` provided.
-
-### `noDisposeOnSet`
-
-Set to `true` to suppress calling the `dispose()` function if the
-entry key is still accessible within the cache.
-
-This may be overridden by passing an options object to
-`cache.set()`.
-
-Boolean, default `false`. Only relevant if `dispose` or
-`disposeAfter` options are set.
-
-### `ttl`
-
-Max time to live for items before they are considered stale.
-Note that stale items are NOT preemptively removed by default,
-and MAY live in the cache, contributing to its LRU max, long
-after they have expired.
-
-Also, as this cache is optimized for LRU/MRU operations, some of
-the staleness/TTL checks will reduce performance.
-
-This is not primarily a TTL cache, and does not make strong TTL
-guarantees. There is no pre-emptive pruning of expired items,
-but you _may_ set a TTL on the cache, and it will treat expired
-items as missing when they are fetched, and delete them.
-
-Optional, but must be a positive integer in ms if specified.
-
-This may be overridden by passing an options object to
-`cache.set()`.
-
-At least one of `max`, `maxSize`, or `TTL` is required. This
-must be a positive integer if set.
-
-Even if ttl tracking is enabled, **it is strongly recommended to
-set a `max` to prevent unbounded growth of the cache.** See
-"Storage Bounds Safety" below.
-
-If ttl tracking is enabled, and `max` and `maxSize` are not set,
-and `ttlAutopurge` is not set, then a warning will be emitted
-cautioning about the potential for unbounded memory consumption.
-
-Deprecated alias: `maxAge`
-
-### `noUpdateTTL`
-
-Boolean 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.
-
-This may be passed as an option to `cache.set()`.
-
-Boolean, default false.
-
-### `ttlResolution`
-
-Minimum 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.
-
-Note that 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 intended.
-
-### `ttlAutopurge`
-
-Preemptively 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 `allowStale` is a bit pointless, as
-stale items will be deleted almost as soon as they expire.
-
-Use with caution!
-
-Boolean, default `false`
-
-### `allowStale`
-
-By default, if you set `ttl`, it'll only delete stale items from
-the cache when you `get(key)`. That is, it's not preemptively
-pruning items.
-
-If you set `allowStale:true`, it'll return the stale value as
-well as deleting it. If you don't set this, then it'll return
-`undefined` when you try to get a stale entry.
-
-Note that when a stale entry is fetched, _even if it is returned
-due to `allowStale` being set_, it is removed from the cache
-immediately. You can immediately put it back in the cache if you
-wish, thus resetting the TTL.
-
-This may be overridden by passing an options object to
-`cache.get()`. The `cache.has()` method will always return
-`false` for stale items.
-
-Boolean, default false, only relevant if `ttl` is set.
-
-Deprecated alias: `stale`
-
-### `noDeleteOnStaleGet`
-
-When using time-expiring entries with `ttl`, by default stale
-items will be removed from the cache when the key is accessed
-with `cache.get()`.
-
-Setting `noDeleteOnStaleGet` to `true` will cause stale items to
-remain in the cache, until they are explicitly deleted with
-`cache.delete(key)`, or retrieved with `noDeleteOnStaleGet` set
-to `false`.
-
-This may be overridden by passing an options object to
-`cache.get()`.
-
-Boolean, default false, only relevant if `ttl` is set.
-
-### `updateAgeOnGet`
+If you try to put an oversized thing in it, then it'll fall out right
+away.
 
-When using time-expiring entries with `ttl`, setting this to
-`true` will make each item's age reset to 0 whenever it is
-retrieved from cache with `get()`, causing it to not expire. (It
-can still fall out of cache based on recency of use, of course.)
-
-This may be overridden by passing an options object to
-`cache.get()`.
-
-Boolean, default false, only relevant if `ttl` is set.
-
-### `updateAgeOnHas`
-
-When using time-expiring entries with `ttl`, setting this to
-`true` will make each item's age reset to 0 whenever its presence
-in the cache is checked with `has()`, causing it to not expire.
-(It can still fall out of cache based on recency of use, of
-course.)
-
-This may be overridden by passing an options object to
-`cache.has()`.
+## Options
 
-Boolean, default false, only relevant if `ttl` is set.
+* `max` The maximum size of the cache, checked by applying the length
+  function to all values in the cache.  Not setting this is kind of
+  silly, since that's the whole purpose of this lib, but it defaults
+  to `Infinity`.  Setting it to a non-number or negative number will
+  throw a `TypeError`.  Setting it to 0 makes it be `Infinity`.
+* `maxAge` Maximum age in ms.  Items are not pro-actively pruned out
+  as they age, but if you try to get an item that is too old, it'll
+  drop it and return undefined instead of giving it to you.
+  Setting this to a negative value will make everything seem old!
+  Setting it to a non-number will throw a `TypeError`.
+* `length` Function that is used to calculate the length of stored
+  items.  If you're storing strings or buffers, then you probably want
+  to do something like `function(n, key){return n.length}`.  The default is
+  `function(){return 1}`, which is fine if you want to store `max`
+  like-sized things.  The item is passed as the first argument, and
+  the key is passed as the second argumnet.
+* `dispose` Function 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 if you want
+  to immediately put it back in, you'll have to do that in a
+  `nextTick` or `setTimeout` callback or it won't do anything.
+* `stale` By default, if you set a `maxAge`, it'll only actually pull
+  stale items out of the cache when you `get(key)`.  (That is, it's
+  not pre-emptively doing a `setTimeout` or anything.)  If you set
+  `stale:true`, it'll return the stale value before deleting it.  If
+  you don't set this, then it'll return `undefined` when you try to
+  get a stale entry, as if it had already been deleted.
+* `noDisposeOnSet` By default, if you set a `dispose()` method, then
+  it'll be called whenever a `set()` operation overwrites an existing
+  key.  If you set this option, `dispose()` will only be called when a
+  key falls out of the cache, not when it is overwritten.
+* `updateAgeOnGet` When using time-expiring entries with `maxAge`,
+  setting this to `true` will make each item's effective time update
+  to the current time whenever it is retrieved from cache, causing it
+  to not expire.  (It can still fall out of cache based on recency of
+  use, of course.)
 
 ## API
 
-### `new LRUCache(options)`
-
-Create a new LRUCache. All options are documented above, and are
-on the cache as public members.
-
-### `cache.max`, `cache.maxSize`, `cache.allowStale`,
-
-`cache.noDisposeOnSet`, `cache.sizeCalculation`, `cache.dispose`,
-`cache.maxSize`, `cache.ttl`, `cache.updateAgeOnGet`,
-`cache.updateAgeOnHas`
-
-All option names are exposed as public members on the cache
-object.
-
-These are intended for read access only. Changing them during
-program operation can cause undefined behavior.
-
-### `cache.size`
-
-The total number of items held in the cache at the current
-moment.
-
-### `cache.calculatedSize`
-
-The total size of items in cache when using size tracking.
-
-### `set(key, value, [{ size, sizeCalculation, ttl, noDisposeOnSet, start, status }])`
-
-Add a value to the cache.
-
-Optional options object may contain `ttl` and `sizeCalculation`
-as described above, which default to the settings on the cache
-object.
-
-If `start` is provided, then that will set the effective start
-time for the TTL calculation. Note that this must be a previous
-value of `performance.now()` if supported, or a previous value of
-`Date.now()` if not.
-
-Options object may also include `size`, which will prevent
-calling the `sizeCalculation` function and just use the specified
-number if it is a positive integer, and `noDisposeOnSet` which
-will prevent calling a `dispose` function in the case of
-overwrites.
-
-If the `size` (or return value of `sizeCalculation`) for a given
-entry is greater than `maxEntrySize`, then the item will not be
-added to the cache.
-
-Will update the recency of the entry.
-
-Returns the cache object.
-
-For the usage of the `status` option, see **Status Tracking**
-below.
-
-### `get(key, { updateAgeOnGet, allowStale, status } = {}) => value`
-
-Return a value from the cache.
-
-Will update the recency of the cache entry found.
-
-If the key is not found, `get()` will return `undefined`. This
-can be confusing when setting values specifically to `undefined`,
-as in `cache.set(key, undefined)`. Use `cache.has()` to
-determine whether a key is present in the cache at all.
-
-For the usage of the `status` option, see **Status Tracking**
-below.
-
-### `async fetch(key, options = {}) => Promise`
-
-The following options are supported:
-
-- `updateAgeOnGet`
-- `allowStale`
-- `size`
-- `sizeCalculation`
-- `ttl`
-- `noDisposeOnSet`
-- `forceRefresh`
-- `status` - See **Status Tracking** below.
-- `signal` - AbortSignal can be used to cancel the `fetch()`.
-  Note that the `signal` option provided to the `fetchMethod` is
-  a different object, because it must also respond to internal
-  cache state changes, but aborting this signal will abort the
-  one passed to `fetchMethod` as well.
-- `fetchContext` - sets the `context` option passed to the
-  underlying `fetchMethod`.
-
-If the value is in the cache and not stale, then the returned
-Promise resolves to the value.
-
-If not in the cache, or beyond its TTL staleness, then
-`fetchMethod(key, staleValue, { options, signal, context })` is
-called, and the value returned will be added to the cache once
-resolved.
-
-If called with `allowStale`, and an asynchronous fetch is
-currently in progress to reload a stale value, then the former
-stale value will be returned.
-
-If called with `forceRefresh`, then the cached item will be
-re-fetched, even if it is not stale. However, if `allowStale` is
-set, then the old value will still be returned. This is useful
-in cases where you want to force a reload of a cached value. If
-a background fetch is already in progress, then `forceRefresh`
-has no effect.
-
-Multiple fetches for the same `key` will only call `fetchMethod`
-a single time, and all will be resolved when the value is
-resolved, even if different options are used.
-
-If `fetchMethod` is not specified, then this is effectively an
-alias for `Promise.resolve(cache.get(key))`.
-
-When the fetch method resolves to a value, if the fetch has not
-been aborted due to deletion, eviction, or being overwritten,
-then it is added to the cache using the options provided.
-
-If the key is evicted or deleted before the `fetchMethod`
-resolves, then the AbortSignal passed to the `fetchMethod` will
-receive an `abort` event, and the promise returned by `fetch()`
-will reject with the reason for the abort.
-
-If a `signal` is passed to the `fetch()` call, then aborting the
-signal will abort the fetch and cause the `fetch()` promise to
-reject with the reason provided.
-
-### `peek(key, { allowStale } = {}) => value`
-
-Like `get()` but doesn't update recency or delete stale items.
-
-Returns `undefined` if the item is stale, unless `allowStale` is
-set either on the cache or in the options object.
-
-### `has(key, { updateAgeOnHas, status } = {}) => Boolean`
-
-Check if a key is in the cache, without updating the recency of
-use. Age is updated if `updateAgeOnHas` is set to `true` in
-either the options or the constructor.
-
-Will return `false` if the item is stale, even though it is
-technically in the cache.  The difference can be determined (if
-it matters) by using a `status` argument, and inspecting the
-`has` field.
-
-For the usage of the `status` option, see **Status Tracking**
-below.
-
-### `delete(key)`
-
-Deletes a key out of the cache.
-
-Returns `true` if the key was deleted, `false` otherwise.
-
-### `clear()`
-
-Clear the cache entirely, throwing away all values.
-
-Deprecated alias: `reset()`
-
-### `keys()`
-
-Return a generator yielding the keys in the cache, in order from
-most recently used to least recently used.
-
-### `rkeys()`
-
-Return a generator yielding the keys in the cache, in order from
-least recently used to most recently used.
-
-### `values()`
-
-Return a generator yielding the values in the cache, in order
-from most recently used to least recently used.
+* `set(key, value, maxAge)`
+* `get(key) => value`
 
-### `rvalues()`
+    Both of these will update the "recently used"-ness of the key.
+    They do what you think. `maxAge` is optional and overrides the
+    cache `maxAge` option if provided.
 
-Return a generator yielding the values in the cache, in order
-from least recently used to most recently used.
+    If the key is not found, `get()` will return `undefined`.
 
-### `entries()`
+    The key and val can be any value.
 
-Return a generator yielding `[key, value]` pairs, in order from
-most recently used to least recently used.
+* `peek(key)`
 
-### `rentries()`
+    Returns the key value (or `undefined` if not found) without
+    updating the "recently used"-ness of the key.
 
-Return a generator yielding `[key, value]` pairs, in order from
-least recently used to most recently used.
+    (If you find yourself using this a lot, you *might* be using the
+    wrong sort of data structure, but there are some use cases where
+    it's handy.)
 
-### `find(fn, [getOptions])`
+* `del(key)`
 
-Find a value for which the supplied `fn` method returns a truthy
-value, similar to `Array.find()`.
+    Deletes a key out of the cache.
 
-`fn` is called as `fn(value, key, cache)`.
+* `reset()`
 
-The optional `getOptions` are applied to the resulting `get()` of
-the item found.
+    Clear the cache entirely, throwing away all values.
 
-### `dump()`
+* `has(key)`
 
-Return an array of `[key, entry]` objects which can be passed to
-`cache.load()`
+    Check if a key is in the cache, without updating the recent-ness
+    or deleting it for being stale.
 
-The `start` fields are calculated relative to a portable
-`Date.now()` timestamp, even if `performance.now()` is available.
+* `forEach(function(value,key,cache), [thisp])`
 
-Stale entries are always included in the `dump`, even if
-`allowStale` is false.
+    Just like `Array.prototype.forEach`.  Iterates over all the keys
+    in the cache, in order of recent-ness.  (Ie, more recently used
+    items are iterated over first.)
 
-Note: this returns an actual array, not a generator, so it can be
-more easily passed around.
+* `rforEach(function(value,key,cache), [thisp])`
 
-### `load(entries)`
+    The same as `cache.forEach(...)` but items are iterated over in
+    reverse order.  (ie, less recently used items are iterated over
+    first.)
 
-Reset the cache and load in the items in `entries` in the order
-listed. Note that the shape of the resulting cache may be
-different if the same options are not used in both caches.
+* `keys()`
 
-The `start` fields are assumed to be calculated relative to a
-portable `Date.now()` timestamp, even if `performance.now()` is
-available.
+    Return an array of the keys in the cache.
 
-### `purgeStale()`
+* `values()`
 
-Delete any stale entries. Returns `true` if anything was
-removed, `false` otherwise.
+    Return an array of the values in the cache.
 
-Deprecated alias: `prune`
-
-### `getRemainingTTL(key)`
-
-Return the number of ms left in the item's TTL. If item is not
-in cache, returns `0`. Returns `Infinity` if item is in cache
-without a defined TTL.
-
-### `forEach(fn, [thisp])`
-
-Call the `fn` function with each set of `fn(value, key, cache)`
-in the LRU cache, from most recent to least recently used.
-
-Does not affect recency of use.
-
-If `thisp` is provided, function will be called in the
-`this`-context of the provided object.
-
-### `rforEach(fn, [thisp])`
-
-Same as `cache.forEach(fn, thisp)`, but in order from least
-recently used to most recently used.
-
-### `pop()`
-
-Evict the least recently used item, returning its value.
-
-Returns `undefined` if cache is empty.
-
-### Internal Methods and Properties
-
-In order to optimize performance as much as possible, "private"
-members and methods are exposed on the object as normal
-properties, rather than being accessed via Symbols, private
-members, or closure variables.
-
-**Do not use or rely on these.** They will change or be removed
-without notice. They will cause undefined behavior if used
-inappropriately. There is no need or reason to ever call them
-directly.
-
-This documentation is here so that it is especially clear that
-this not "undocumented" because someone forgot; it _is_
-documented, and the documentation is telling you not to do it.
-
-**Do not report bugs that stem from using these properties.**
-They will be ignored.
-
-- `initializeTTLTracking()` Set up the cache for tracking TTLs
-- `updateItemAge(index)` Called when an item age is updated, by
-  internal ID
-- `setItemTTL(index)` Called when an item ttl is updated, by
-  internal ID
-- `isStale(index)` Called to check an item's staleness, by
-  internal ID
-- `initializeSizeTracking()` Set up the cache for tracking item
-  size. Called automatically when a size is specified.
-- `removeItemSize(index)` Updates the internal size calculation
-  when an item is removed or modified, by internal ID
-- `addItemSize(index)` Updates the internal size calculation when
-  an item is added or modified, by internal ID
-- `indexes()` An iterator over the non-stale internal IDs, from
-  most recently to least recently used.
-- `rindexes()` An iterator over the non-stale internal IDs, from
-  least recently to most recently used.
-- `newIndex()` Create a new internal ID, either reusing a deleted
-  ID, evicting the least recently used ID, or walking to the end
-  of the allotted space.
-- `evict()` Evict the least recently used internal ID, returning
-  its ID. Does not do any bounds checking.
-- `connect(p, n)` Connect the `p` and `n` internal IDs in the
-  linked list.
-- `moveToTail(index)` Move the specified internal ID to the most
-  recently used position.
-- `keyMap` Map of keys to internal IDs
-- `keyList` List of keys by internal ID
-- `valList` List of values by internal ID
-- `sizes` List of calculated sizes by internal ID
-- `ttls` List of TTL values by internal ID
-- `starts` List of start time values by internal ID
-- `next` Array of "next" pointers by internal ID
-- `prev` Array of "previous" pointers by internal ID
-- `head` Internal ID of least recently used item
-- `tail` Internal ID of most recently used item
-- `free` Stack of deleted internal IDs
-
-## Status Tracking
-
-Occasionally, it may be useful to track the internal behavior of
-the cache, particularly for logging, debugging, or for behavior
-within the `fetchMethod`.  To do this, you can pass a `status`
-object to the `get()`, `set()`, `has()`, and `fetch()` methods.
-
-The `status` option should be a plain JavaScript object.
-
-The following fields will be set appropriately:
-
-```ts
-interface Status<V> {
-  /**
-   * The status of a set() operation.
-   *
-   * - add: the item was not found in the cache, and was added
-   * - update: the item was in the cache, with the same value provided
-   * - replace: the item was in the cache, and replaced
-   * - miss: the item was not added to the cache for some reason
-   */
-  set?: 'add' | 'update' | 'replace' | 'miss'
-
-  /**
-   * the ttl stored for the item, or undefined if ttls are not used.
-   */
-  ttl?: LRUMilliseconds
-
-  /**
-   * the start time for the item, or undefined if ttls are not used.
-   */
-  start?: LRUMilliseconds
-
-  /**
-   * The timestamp used for TTL calculation
-   */
-  now?: LRUMilliseconds
-
-  /**
-   * the remaining ttl for the item, or undefined if ttls are not used.
-   */
-  remainingTTL?: LRUMilliseconds
-
-  /**
-   * The calculated size for the item, if sizes are used.
-   */
-  size?: LRUSize
-
-  /**
-   * A flag indicating that the item was not stored, due to exceeding the
-   * {@link maxEntrySize}
-   */
-  maxEntrySizeExceeded?: true
-
-  /**
-   * The old value, specified in the case of `set:'update'` or
-   * `set:'replace'`
-   */
-  oldValue?: V
-
-  /**
-   * The results of a {@link has} operation
-   *
-   * - hit: the item was found in the cache
-   * - stale: the item was found in the cache, but is stale
-   * - miss: the item was not found in the cache
-   */
-  has?: 'hit' | 'stale' | 'miss'
-
-  /**
-   * The status of a {@link fetch} operation.
-   * Note that this can change as the underlying fetch() moves through
-   * various states.
-   *
-   * - inflight: there is another fetch() for this key which is in process
-   * - get: there is no fetchMethod, so {@link get} was called.
-   * - miss: the item is not in cache, and will be fetched.
-   * - hit: the item is in the cache, and was resolved immediately.
-   * - stale: the item is in the cache, but stale.
-   * - refresh: the item is in the cache, and not stale, but
-   *   {@link forceRefresh} was specified.
-   */
-  fetch?: 'get' | 'inflight' | 'miss' | 'hit' | 'stale' | 'refresh'
-
-  /**
-   * The {@link fetchMethod} was called
-   */
-  fetchDispatched?: true
-
-  /**
-   * The cached value was updated after a successful call to fetchMethod
-   */
-  fetchUpdated?: true
-
-  /**
-   * The reason for a fetch() rejection.  Either the error raised by the
-   * {@link fetchMethod}, or the reason for an AbortSignal.
-   */
-  fetchError?: Error
-
-  /**
-   * The fetch received an abort signal
-   */
-  fetchAborted?: true
-
-  /**
-   * The abort signal received was ignored, and the fetch was allowed to
-   * continue.
-   */
-  fetchAbortIgnored?: true
-
-  /**
-   * The fetchMethod promise resolved successfully
-   */
-  fetchResolved?: true
-
-  /**
-   * The results of the fetchMethod promise were stored in the cache
-   */
-  fetchUpdated?: true
-
-  /**
-   * The fetchMethod promise was rejected
-   */
-  fetchRejected?: true
-
-  /**
-   * The status of a {@link get} operation.
-   *
-   * - fetching: The item is currently being fetched.  If a previous value is
-   *   present and allowed, that will be returned.
-   * - stale: The item is in the cache, and is stale.
-   * - hit: the item is in the cache
-   * - miss: the item is not in the cache
-   */
-  get?: 'stale' | 'hit' | 'miss'
-
-  /**
-   * A fetch or get operation returned a stale value.
-   */
-  returnedStale?: true
-}
-```
-
-## Storage Bounds Safety
-
-This implementation aims to be as flexible as possible, within
-the limits of safe memory consumption and optimal performance.
-
-At initial object creation, storage is allocated for `max` items.
-If `max` is set to zero, then some performance is lost, and item
-count is unbounded. Either `maxSize` or `ttl` _must_ be set if
-`max` is not specified.
-
-If `maxSize` is set, then this creates a safe limit on the
-maximum storage consumed, but without the performance benefits of
-pre-allocation. When `maxSize` is set, every item _must_ provide
-a size, either via the `sizeCalculation` method provided to the
-constructor, or via a `size` or `sizeCalculation` option provided
-to `cache.set()`. The size of every item _must_ be a positive
-integer.
-
-If neither `max` nor `maxSize` are set, then `ttl` tracking must
-be enabled. Note that, even when tracking item `ttl`, items are
-_not_ preemptively deleted when they become stale, unless
-`ttlAutopurge` is enabled. Instead, they are only purged the
-next time the key is requested. Thus, if `ttlAutopurge`, `max`,
-and `maxSize` are all not set, then the cache will potentially
-grow unbounded.
-
-In this case, a warning is printed to standard error. Future
-versions may require the use of `ttlAutopurge` if `max` and
-`maxSize` are not specified.
-
-If you truly wish to use a cache that is bound _only_ by TTL
-expiration, consider using a `Map` object, and calling
-`setTimeout` to delete entries when they expire. It will perform
-much better than an LRU cache.
-
-Here is an implementation you may use, under the same
-[license](./LICENSE) as this package:
-
-```js
-// a storage-unbounded ttl cache that is not an lru-cache
-const cache = {
-  data: new Map(),
-  timers: new Map(),
-  set: (k, v, ttl) => {
-    if (cache.timers.has(k)) {
-      clearTimeout(cache.timers.get(k))
-    }
-    cache.timers.set(
-      k,
-      setTimeout(() => cache.delete(k), ttl)
-    )
-    cache.data.set(k, v)
-  },
-  get: k => cache.data.get(k),
-  has: k => cache.data.has(k),
-  delete: k => {
-    if (cache.timers.has(k)) {
-      clearTimeout(cache.timers.get(k))
-    }
-    cache.timers.delete(k)
-    return cache.data.delete(k)
-  },
-  clear: () => {
-    cache.data.clear()
-    for (const v of cache.timers.values()) {
-      clearTimeout(v)
-    }
-    cache.timers.clear()
-  },
-}
-```
-
-If that isn't to your liking, check out
-[@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
-
-## Performance
-
-As of January 2022, version 7 of this library is one of the most
-performant LRU cache implementations in JavaScript.
-
-Benchmarks can be extremely difficult to get right. In
-particular, the performance of set/get/delete operations on
-objects will vary _wildly_ depending on the type of key used. V8
-is highly optimized for objects with keys that are short strings,
-especially integer numeric strings. Thus any benchmark which
-tests _solely_ using numbers as keys will tend to find that an
-object-based approach performs the best.
-
-Note that coercing _anything_ to strings to use as object keys is
-unsafe, unless you can be 100% certain that no other type of
-value will be used. For example:
-
-```js
-const myCache = {}
-const set = (k, v) => (myCache[k] = v)
-const get = k => myCache[k]
-
-set({}, 'please hang onto this for me')
-set('[object Object]', 'oopsie')
-```
+* `length`
 
-Also beware of "Just So" stories regarding performance. Garbage
-collection of large (especially: deep) object graphs can be
-incredibly costly, with several "tipping points" where it
-increases exponentially. As a result, putting that off until
-later can make it much worse, and less predictable. If a library
-performs well, but only in a scenario where the object graph is
-kept shallow, then that won't help you if you are using large
-objects as keys.
+    Return total length of objects in cache taking into account
+    `length` options function.
 
-In general, when attempting to use a library to improve
-performance (such as a cache like this one), it's best to choose
-an option that will perform well in the sorts of scenarios where
-you'll actually use it.
+* `itemCount`
 
-This library is optimized for repeated gets and minimizing
-eviction time, since that is the expected need of a LRU. Set
-operations are somewhat slower on average than a few other
-options, in part because of that optimization. It is assumed
-that you'll be caching some costly operation, ideally as rarely
-as possible, so optimizing set over get would be unwise.
+    Return total quantity of objects currently in cache. Note, that
+    `stale` (see options) items are returned as part of this item
+    count.
 
-If performance matters to you:
+* `dump()`
 
-1. If it's at all possible to use small integer values as keys,
-   and you can guarantee that no other types of values will be
-   used as keys, then do that, and use a cache such as
-   [lru-fast](https://npmjs.com/package/lru-fast), or
-   [mnemonist's
-   LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache)
-   which uses an Object as its data store.
-2. Failing that, if at all possible, use short non-numeric
-   strings (ie, less than 256 characters) as your keys, and use
-   [mnemonist's
-   LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache).
-3. If the types of your keys will be long strings, strings that
-   look like floats, `null`, objects, or some mix of types, or if
-   you aren't sure, then this library will work well for you.
-4. Do not use a `dispose` function, size tracking, or especially
-   ttl behavior, unless absolutely needed. These features are
-   convenient, and necessary in some use cases, and every attempt
-   has been made to make the performance impact minimal, but it
-   isn't nothing.
+    Return an array of the cache entries ready for serialization and usage
+    with 'destinationCache.load(arr)`.
 
-## Breaking Changes in Version 7
+* `load(cacheEntriesArray)`
 
-This library changed to a different algorithm and internal data
-structure in version 7, yielding significantly better
-performance, albeit with some subtle changes as a result.
+    Loads another cache entries array, obtained with `sourceCache.dump()`,
+    into the cache. The destination cache is reset before loading new entries
 
-If you were relying on the internals of LRUCache in version 6 or
-before, it probably will not work in version 7 and above.
+* `prune()`
 
-For more info, see the [change log](CHANGELOG.md).
+    Manually iterates over the entire cache proactively pruning old entries