lru-cache - npm Package Compare versions

Comparing version 10.2.2 to 10.3.0

dist/commonjs/index.d.ts

@@ -60,4 +60,14 @@ /**
      * to the {@link Disposer} methods.
+     *
+     * - `evict`: The item was evicted because it is the least recently used,
+     *   and the cache is full.
+     * - `set`: A new value was set, overwriting the old value being disposed.
+     * - `delete`: The item was explicitly deleted, either by calling
+     *   {@link LRUCache#delete}, {@link LRUCache#clear}, or
+     *   {@link LRUCache#set} with an undefined value.
+     * - `expire`: The item was removed due to exceeding its TTL.
+     * - `fetch`: A {@link OptionsBase#fetchMethod} operation returned
+     *   `undefined` or was aborted, causing the item to be deleted.
      */
-    type DisposeReason = 'evict' | 'set' | 'delete';
+    type DisposeReason = 'evict' | 'set' | 'delete' | 'expire' | 'fetch';
     /**
@@ -88,4 +98,10 @@ * A method called upon item removal, passed as the
     /**
-     * Status object that may be passed to {@link LRUCache#fetch},
-     * {@link LRUCache#get}, {@link LRUCache#set}, and {@link LRUCache#has}.
+     * 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
+     * {@link LRUCache#fetch}, {@link LRUCache#get}, {@link LRUCache#set},
+     * {@link LRUCache#memo}, and {@link LRUCache#has} methods.
+     *
+     * The `status` option should be a plain JavaScript object. The following
+     * fields will be set on it appropriately, depending on the situation.
      */
@@ -150,3 +166,4 @@ interface Status<V> {
          * - inflight: there is another fetch() for this key which is in process
-         * - get: there is no fetchMethod, so {@link LRUCache#get} was called.
+         * - get: there is no {@link OptionsBase.fetchMethod}, so
+         *   {@link LRUCache#get} was called.
          * - miss: the item is not in cache, and will be fetched.
@@ -260,3 +277,64 @@ * - hit: the item is in the cache, and was resolved immediately.
     }
+    interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
+        /**
+         * Set to true to force a re-load of the existing data, even if it
+         * is not yet stale.
+         */
+        forceRefresh?: boolean;
+        /**
+         * Context provided to the {@link OptionsBase.memoMethod} as
+         * the {@link MemoizerOptions.context} param.
+         *
+         * If the FC type is specified as unknown (the default),
+         * undefined or void, then this is optional.  Otherwise, it will
+         * be required.
+         */
+        context?: FC;
+        status?: Status<V>;
+    }
     /**
+     * Options provided to {@link LRUCache#memo} when the FC type is something
+     * other than `unknown`, `undefined`, or `void`
+     */
+    interface MemoOptionsWithContext<K, V, FC> extends MemoOptions<K, V, FC> {
+        context: FC;
+    }
+    /**
+     * Options provided to {@link LRUCache#memo} when the FC type is
+     * `undefined` or `void`
+     */
+    interface MemoOptionsNoContext<K, V> extends MemoOptions<K, V, undefined> {
+        context?: undefined;
+    }
+    /**
+     * Options provided to the
+     * {@link OptionsBase.memoMethod} function.
+     */
+    interface MemoizerOptions<K, V, FC = unknown> {
+        options: MemoizerMemoOptions<K, V, FC>;
+        /**
+         * Object provided in the {@link MemoOptions.context} option to
+         * {@link LRUCache#memo}
+         */
+        context: FC;
+    }
+    /**
+     * options which override the options set in the LRUCache constructor
+     * when calling {@link LRUCache#memo}.
+     *
+     * This is the union of {@link GetOptions} and {@link SetOptions}, plus
+     * {@link MemoOptions.forceRefresh}, and
+     * {@link MemoerOptions.context}
+     *
+     * Any of these may be modified in the {@link OptionsBase.memoMethod}
+     * function, but the {@link GetOptions} fields will of course have no
+     * effect, as the {@link LRUCache#get} call already happened by the time
+     * the memoMethod is called.
+     */
+    interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {
+        status?: Status<V>;
+        size?: Size;
+        start?: Milliseconds;
+    }
+    /**
      * Options that may be passed to the {@link LRUCache#has} method.
@@ -304,2 +382,6 @@ */
     /**
+     * the type signature for the {@link OptionsBase.memoMethod} option.
+     */
+    type Memoizer<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: MemoizerOptions<K, V, FC>) => V;
+    /**
      * Options which may be passed to the {@link LRUCache} constructor.
@@ -318,2 +400,10 @@ *
      * unbounded storage.
+     *
+     * All options are also available on the {@link LRUCache} instance, making
+     * it safe to pass an LRUCache instance as the options argumemnt to
+     * make another empty cache of the same type.
+     *
+     * Some options are marked as read-only, because changing them after
+     * instantiation is not safe. Changing any of the other options will of
+     * course only have an effect on subsequent method calls.
      */
@@ -332,2 +422,5 @@ interface OptionsBase<K, V, FC> {
          * set.
+         *
+         * **It is strongly recommended to set a `max` to prevent unbounded growth
+         * of the cache.**
          */
@@ -337,5 +430,10 @@ max?: Count;
          * Max 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.
+         * 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, unless {@link OptionsBase.ttlAutopurge} is
+         * set.
          *
+         * If set to `0` (the default value), then that means "do not track
+         * TTL", not "expire immediately".
+         *
          * Also, as this cache is optimized for LRU/MRU operations, some of
@@ -345,5 +443,21 @@ * the staleness/TTL checks will reduce performance, as they will incur
          *
-         * Must be an integer number of ms. If set to 0, this indicates "no TTL"
+         * 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.
          *
-         * @default 0
+         * Optional, but must be a non-negative 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.**
+         *
+         * 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.
+         * (The TypeScript definitions will also discourage this.)
          */
@@ -368,7 +482,8 @@ ttl?: Milliseconds;
          * 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 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 {@link OptionsBase.allowStale} is a bit
@@ -378,19 +493,23 @@ * pointless, as stale items will be deleted almost as soon as they
          *
-         * @default false
+         * Use with caution!
          */
         ttlAutopurge?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#get}, renewing their TTL
+         * 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
+         * {@link LRUCache#get}, causing it to not expire. (It can still fall out
+         * of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
          *
-         * @default false
+         * This may be overridden by passing an options object to `cache.get()`.
          */
         updateAgeOnGet?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#has}, renewing their TTL
+         * 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 {@link LRUCache#has}, causing it to not expire. (It can
+         * still fall out of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
-         *
-         * @default false
          */
@@ -401,14 +520,49 @@ updateAgeOnHas?: boolean;
          * stale data, if available.
+         *
+         * By default, if you set `ttl`, stale items will only be deleted from the
+         * cache when you `get(key)`. That is, it's not preemptively pruning items,
+         * unless {@link OptionsBase.ttlAutopurge} is set.
+         *
+         * 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 suppress this behavior by setting
+         * {@link OptionsBase.noDeleteOnStaleGet}, either in the constructor, or in
+         * the options provided to {@link LRUCache#get}.
+         *
+         * This may be overridden by passing an options object to `cache.get()`.
+         * The `cache.has()` method will always return `false` for stale items.
+         *
+         * Only relevant if a ttl is set.
          */
         allowStale?: boolean;
         /**
-         * 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 it is *NOT* safe to re-add them.
+         * Function that is called on items when they are dropped from the
+         * cache, as `dispose(value, key, reason)`.
          *
-         * Use {@link 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.
+         * 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.
+         *
+         * 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
+         * - `expire` Item expired its TTL
+         * - `fetch` Item was deleted due to a failed or aborted fetch, or a
+         *   fetchMethod returning `undefined.
+         * - `delete` Item was removed by explicit `cache.delete(key)`,
+         *   `cache.clear()`, or `cache.set(key, undefined)`.
          */
@@ -419,2 +573,3 @@ dispose?: Disposer<K, V>;
          * 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.
@@ -429,23 +584,40 @@ * However, note that it is *very* easy to inadvertently create infinite
          * still accessible within the cache.
+         *
          * This may be overridden by passing an options object to
          * {@link LRUCache#set}.
+         *
+         * Only relevant if `dispose` or `disposeAfter` are set.
          */
         noDisposeOnSet?: boolean;
         /**
-         * 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.
+         * 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.
          *
          * Has no effect if a {@link OptionsBase.ttl} is not set.
+         *
+         * May be passed as an option to {@link LRUCache#set}.
          */
         noUpdateTTL?: boolean;
         /**
-         * If 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!
+         * 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.**
+         *
          * Note also that size tracking can negatively impact performance,
@@ -459,4 +631,11 @@ * though for most cases, only minimally.
          * If a larger item is passed to {@link LRUCache#set} or returned by a
-         * {@link OptionsBase.fetchMethod}, then it will not be stored in the
-         * cache.
+         * {@link OptionsBase.fetchMethod} or {@link OptionsBase.memoMethod}, then
+         * it will not be stored in the cache.
+         *
+         * Attempting to add an item whose calculated size is greater than
+         * this amount will not cache the item or evict any old items, but
+         * WILL delete an existing value if one is already present.
+         *
+         * Optional, must be a positive integer if provided. Defaults to
+         * the value of `maxSize` if provided.
          */
@@ -467,2 +646,4 @@ maxEntrySize?: Size;
          *
+         * Requires {@link OptionsBase.maxSize} to be set.
+         *
          * If not provided, and {@link OptionsBase.maxSize} or
@@ -476,5 +657,38 @@ * {@link OptionsBase.maxEntrySize} are set, then all
          * Method that provides the implementation for {@link LRUCache#fetch}
+         *
+         * ```ts
+         * fetchMethod(key, staleValue, { signal, options, context })
+         * ```
+         *
+         * If `fetchMethod` is not provided, then `cache.fetch(key)` is equivalent
+         * to `Promise.resolve(cache.get(key))`.
+         *
+         * 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
+         * {@link OptionsBase.noDeleteOnFetchRejection} and
+         * {@link OptionsBase.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`.
          */
         fetchMethod?: Fetcher<K, V, FC>;
         /**
+         * Method that provides the implementation for {@link LRUCache#memo}
+         */
+        memoMethod?: Memoizer<K, V, FC>;
+        /**
          * Set to true to suppress the deletion of stale data when a
@@ -490,2 +704,14 @@ * {@link OptionsBase.fetchMethod} returns a rejected promise.
          * unless {@link OptionsBase.allowStale} is true.
+         *
+         * 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 this option 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()`.
+         *
+         * Only relevant if a ttl is used.
          */
@@ -499,4 +725,13 @@ noDeleteOnStaleGet?: boolean;
          * This differs from using {@link OptionsBase.allowStale} in that stale
-         * data will ONLY be returned in the case that the
-         * {@link LRUCache#fetch} fails, not any other times.
+         * data will ONLY be returned in the case that the {@link LRUCache#fetch}
+         * fails, not any other times.
+         *
+         * 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`.
          */
@@ -506,4 +741,5 @@ allowStaleOnFetchRejection?: boolean;
          * Set to true to return a stale value from the cache when the
-         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches an `'abort'`
-         * event, whether user-triggered, or due to internal cache behavior.
+         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches
+         * an `'abort'` event, whether user-triggered, or due to internal cache
+         * behavior.
          *
@@ -544,5 +780,5 @@ * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying
          *
-         * When used on its own, this means aborted {@link LRUCache#fetch} calls are not
-         * immediately resolved or rejected when they are aborted, and instead
-         * take the full time to await.
+         * When used on its own, this means aborted {@link LRUCache#fetch} calls
+         * are not immediately resolved or rejected when they are aborted, and
+         * instead take the full time to await.
          *
@@ -556,2 +792,22 @@ * When used with {@link OptionsBase.allowStaleOnFetchAbort}, aborted
          *
+         * For example:
+         *
+         * ```ts
+         * 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
@@ -594,7 +850,13 @@ * emitted on the `AbortSignal` object_, so may result in invalid results
  *
- * All properties from the options object (with the exception of
- * {@link OptionsBase.max} and {@link OptionsBase.maxSize}) are added as
- * normal public members. (`max` and `maxBase` are read-only getters.)
- * Changing any of these will alter the defaults for subsequent method calls,
- * but is otherwise safe.
+ * The `K` and `V` types define the key and value types, respectively. The
+ * optional `FC` type defines the type of the `context` object passed to
+ * `cache.fetch()` and `cache.memo()`.
+ *
+ * Keys and values **must not** be `null` or `undefined`.
+ *
+ * All properties from the options object (with the exception of `max`,
+ * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are
+ * added as normal public members. (The listed options are read-only getters.)
+ *
+ * Changing any of these will alter the defaults for subsequent method calls.
  */
@@ -715,2 +977,3 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<K, V> {
     get fetchMethod(): LRUCache.Fetcher<K, V, FC> | undefined;
+    get memoMethod(): LRUCache.Memoizer<K, V, FC> | undefined;
     /**
@@ -726,3 +989,4 @@ * {@link LRUCache.OptionsBase.dispose} (read-only)
     /**
-     * Return the remaining TTL time for a given entry 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.
      */
@@ -772,4 +1036,5 @@ getRemainingTTL(key: K): number;
     /**
-     * A String value that is used in the creation of the default string description of an object.
-     * Called by the built-in method Object.prototype.toString.
+     * A String value that is used in the creation of the default string
+     * description of an object. Called by the built-in method
+     * `Object.prototype.toString`.
      */
@@ -779,10 +1044,15 @@ [Symbol.toStringTag]: string;
      * Find a value for which the supplied fn method returns a truthy value,
-     * similar to Array.find().  fn is called as fn(value, key, cache).
+     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.
      */
     find(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => boolean, getOptions?: LRUCache.GetOptions<K, V, FC>): V | undefined;
     /**
-     * Call the supplied function on each item in the cache, in order from
-     * most recently used to least recently used.  fn is called as
-     * fn(value, key, cache).  Does not update age or recenty of use.
-     * Does not iterate over stale values.
+     * Call the supplied function on each item in the cache, in order from most
+     * recently used to least recently used.
+     *
+     * `fn` is called as `fn(value, key, cache)`.
+     *
+     * If `thisp` is provided, function will be called in the `this`-context of
+     * the provided object, or the cache if no `thisp` object is provided.
+     *
+     * Does not update age or recenty of use, or iterate over stale values.
      */
@@ -802,5 +1072,11 @@ forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
      * Get the extended info about a given entry, to get its value, size, and
-     * TTL info simultaneously. Like {@link LRUCache#dump}, but just for a
-     * single key. Always returns stale values, if their info is found in the
-     * cache, so be sure to check for expired TTLs if relevant.
+     * TTL info simultaneously. Returns `undefined` if the key is not present.
+     *
+     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive
+     * serialization, the `start` value is always the current timestamp, and the
+     * `ttl` is a calculated remaining time to live (negative if expired).
+     *
+     * Always returns stale values, if their info is found in the cache, so be
+     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})
+     * if relevant.
      */
@@ -810,3 +1086,12 @@ info(key: K): LRUCache.Entry<V> | undefined;
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRLUCache#load}.
+     *
+     * The `start` fields are calculated relative to a portable `Date.now()`
+     * timestamp, even if `performance.now()` is available.
+     *
+     * Stale entries are always included in the `dump`, even if
+     * {@link LRUCache.OptionsBase.allowStale} is false.
+     *
+     * Note: this returns an actual array, not a generator, so it can be more
+     * easily passed around.
      */
@@ -816,4 +1101,8 @@ dump(): [K, LRUCache.Entry<V>][];
      * 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.
+     *
+     * The shape of the resulting cache may be different if the same options are
+     * not used in both caches.
+     *
+     * The `start` fields are assumed to be calculated relative to a portable
+     * `Date.now()` timestamp, even if `performance.now()` is available.
      */
@@ -826,2 +1115,26 @@ load(arr: [K, LRUCache.Entry<V>][]): void;
      * {@link LRUCache#delete}
+     *
+     * Fields on the {@link LRUCache.SetOptions} options param will override
+     * their corresponding values in the constructor options for the scope
+     * of this single `set()` operation.
+     *
+     * 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.
+     *
+     * If the value is `undefined`, then this is an alias for
+     * `cache.delete(key)`. `undefined` is never stored in the cache.
      */
@@ -839,2 +1152,10 @@ set(k: K, v: V | BackgroundFetch<V> | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
      *
+     * Check if a key is in the cache, without updating the recency of
+     * use. Age is updated if {@link LRUCache.OptionsBase.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.
+     *
      * Will not update item age unless
@@ -856,2 +1177,21 @@ * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
      *
+     * 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 also
+     * 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.
+     *
      * If multiple fetches for the same key are issued, then they will all be
@@ -869,2 +1209,51 @@ * coalesced into a single call to fetchMethod.
      * may not be worth the costs for this edge case.
+     *
+     * If {@link LRUCache.OptionsBase.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.
+     *
+     * **Setting `context`**
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the {@link LRUCache} constructor, then all
+     * calls to `cache.fetch()` _must_ provide a `context` option. If
+     * set to `undefined` or `void`, then calls to fetch _must not_
+     * provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that
+     * might be relevant in the course of fetching the data. It is only
+     * relevant for the course of a single `fetch()` operation, and
+     * discarded afterwards.
+     *
+     * **Note: `fetch()` calls are inflight-unique**
+     *
+     * If you call `fetch()` multiple times with the same key value,
+     * then every call after the first will resolve on the same
+     * promise<sup>1</sup>,
+     * _even if they have different settings that would otherwise change
+     * the behavior of the fetch_, such as `noDeleteOnFetchRejection`
+     * or `ignoreFetchAbort`.
+     *
+     * In most cases, this is not a problem (in fact, only fetching
+     * something once is what you probably want, if you're caching in
+     * the first place). If you are changing the fetch() options
+     * dramatically between runs, there's a good chance that you might
+     * be trying to fit divergent semantics into a single object, and
+     * would be better off with multiple cache instances.
+     *
+     * **1**: Ie, they're not the "same Promise", but they resolve at
+     * the same time, because they're both waiting on the same
+     * underlying fetchMethod response.
      */
@@ -874,2 +1263,33 @@ fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<undefined | V>;
     /**
+     * In some cases, `cache.fetch()` may resolve to `undefined`, either because
+     * a {@link LRUCache.OptionsBase#fetchMethod} was not provided (turning
+     * `cache.fetch(k)` into just an async wrapper around `cache.get(k)`) or
+     * because `ignoreFetchAbort` was specified (either to the constructor or
+     * in the {@link LRUCache.FetchOptions}). Also, the
+     * {@link OptionsBase.fetchMethod} may return `undefined` or `void`, making
+     * the test even more complicated.
+     *
+     * Because inferring the cases where `undefined` might be returned are so
+     * cumbersome, but testing for `undefined` can also be annoying, this method
+     * can be used, which will reject if `this.fetch()` resolves to undefined.
+     */
+    forceFetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<V>;
+    forceFetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<V>;
+    /**
+     * If the key is found in the cache, then this is equivalent to
+     * {@link LRUCache#get}. If not, in the cache, then calculate the value using
+     * the {@link LRUCache.OptionsBase.memoMethod}, and add it to the cache.
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the LRUCache constructor, then all calls to `cache.memo()`
+     * _must_ provide a `context` option. If set to `undefined` or `void`, then
+     * calls to memo _must not_ provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that might be
+     * relevant in the course of fetching the data. It is only relevant for the
+     * course of a single `memo()` operation, and discarded afterwards.
+     */
+    memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
+    memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : never): V;
+    /**
      * Return a value from the cache. Will update the recency of the cache
@@ -883,2 +1303,3 @@ * entry found.
      * Deletes a key out of the cache.
+     *
      * Returns true if the key was deleted, false otherwise.
@@ -885,0 +1306,0 @@ */

dist/commonjs/index.js

@@ -133,12 +133,16 @@ "use strict";
  *
- * All properties from the options object (with the exception of
- * {@link OptionsBase.max} and {@link OptionsBase.maxSize}) are added as
- * normal public members. (`max` and `maxBase` are read-only getters.)
- * Changing any of these will alter the defaults for subsequent method calls,
- * but is otherwise safe.
+ * The `K` and `V` types define the key and value types, respectively. The
+ * optional `FC` type defines the type of the `context` object passed to
+ * `cache.fetch()` and `cache.memo()`.
+ *
+ * Keys and values **must not** be `null` or `undefined`.
+ *
+ * All properties from the options object (with the exception of `max`,
+ * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are
+ * added as normal public members. (The listed options are read-only getters.)
+ *
+ * Changing any of these will alter the defaults for subsequent method calls.
  */
 class LRUCache {
-    // properties coming in from the options of these, only max and maxSize
-    // really *need* to be protected. The rest can be modified, as they just
-    // set defaults for various methods.
+    // options that cannot be changed without disaster
     #max;
@@ -149,2 +153,3 @@ #maxSize;
     #fetchMethod;
+    #memoMethod;
     /**
@@ -295,2 +300,5 @@ * {@link LRUCache.OptionsBase.ttl}
     }
+    get memoMethod() {
+        return this.#memoMethod;
+    }
     /**
@@ -309,3 +317,3 @@ * {@link LRUCache.OptionsBase.dispose} (read-only)
     constructor(options) {
-        const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, } = options;
+        const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, } = options;
         if (max !== 0 && !isPosInt(max)) {
@@ -330,2 +338,7 @@ throw new TypeError('max option must be a nonnegative integer');
         }
+        if (memoMethod !== undefined &&
+            typeof memoMethod !== 'function') {
+            throw new TypeError('memoMethod must be a function if defined');
+        }
+        this.#memoMethod = memoMethod;
         if (fetchMethod !== undefined &&
@@ -409,3 +422,4 @@ typeof fetchMethod !== 'function') {
     /**
-     * Return the remaining TTL time for a given entry 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.
      */
@@ -426,3 +440,3 @@ getRemainingTTL(key) {
                     if (this.#isStale(index)) {
-                        this.delete(this.#keyList[index]);
+                        this.#delete(this.#keyList[index], 'expire');
                     }
@@ -684,4 +698,5 @@ }, ttl + 1);
     /**
-     * A String value that is used in the creation of the default string description of an object.
-     * Called by the built-in method Object.prototype.toString.
+     * A String value that is used in the creation of the default string
+     * description of an object. Called by the built-in method
+     * `Object.prototype.toString`.
      */
@@ -691,3 +706,3 @@ [Symbol.toStringTag] = 'LRUCache';
      * Find a value for which the supplied fn method returns a truthy value,
-     * similar to Array.find().  fn is called as fn(value, key, cache).
+     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.
      */
@@ -708,6 +723,11 @@ find(fn, getOptions = {}) {
     /**
-     * Call the supplied function on each item in the cache, in order from
-     * most recently used to least recently used.  fn is called as
-     * fn(value, key, cache).  Does not update age or recenty of use.
-     * Does not iterate over stale values.
+     * Call the supplied function on each item in the cache, in order from most
+     * recently used to least recently used.
+     *
+     * `fn` is called as `fn(value, key, cache)`.
+     *
+     * If `thisp` is provided, function will be called in the `this`-context of
+     * the provided object, or the cache if no `thisp` object is provided.
+     *
+     * Does not update age or recenty of use, or iterate over stale values.
      */
@@ -748,3 +768,3 @@ forEach(fn, thisp = this) {
             if (this.#isStale(i)) {
-                this.delete(this.#keyList[i]);
+                this.#delete(this.#keyList[i], 'expire');
                 deleted = true;
@@ -757,5 +777,11 @@ }
      * Get the extended info about a given entry, to get its value, size, and
-     * TTL info simultaneously. Like {@link LRUCache#dump}, but just for a
-     * single key. Always returns stale values, if their info is found in the
-     * cache, so be sure to check for expired TTLs if relevant.
+     * TTL info simultaneously. Returns `undefined` if the key is not present.
+     *
+     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive
+     * serialization, the `start` value is always the current timestamp, and the
+     * `ttl` is a calculated remaining time to live (negative if expired).
+     *
+     * Always returns stale values, if their info is found in the cache, so be
+     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})
+     * if relevant.
      */
@@ -789,3 +815,12 @@ info(key) {
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRLUCache#load}.
+     *
+     * The `start` fields are calculated relative to a portable `Date.now()`
+     * timestamp, even if `performance.now()` is available.
+     *
+     * Stale entries are always included in the `dump`, even if
+     * {@link LRUCache.OptionsBase.allowStale} is false.
+     *
+     * Note: this returns an actual array, not a generator, so it can be more
+     * easily passed around.
      */
@@ -819,4 +854,8 @@ dump() {
      * 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.
+     *
+     * The shape of the resulting cache may be different if the same options are
+     * not used in both caches.
+     *
+     * The `start` fields are assumed to be calculated relative to a portable
+     * `Date.now()` timestamp, even if `performance.now()` is available.
      */
@@ -844,2 +883,26 @@ load(arr) {
      * {@link LRUCache#delete}
+     *
+     * Fields on the {@link LRUCache.SetOptions} options param will override
+     * their corresponding values in the constructor options for the scope
+     * of this single `set()` operation.
+     *
+     * 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.
+     *
+     * If the value is `undefined`, then this is an alias for
+     * `cache.delete(key)`. `undefined` is never stored in the cache.
      */
@@ -862,3 +925,3 @@ set(k, v, setOptions = {}) {
             // have to delete, in case something is there already.
-            this.delete(k);
+            this.#delete(k, 'set');
             return this;
@@ -1015,2 +1078,10 @@ }
      *
+     * Check if a key is in the cache, without updating the recency of
+     * use. Age is updated if {@link LRUCache.OptionsBase.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.
+     *
      * Will not update item age unless
@@ -1107,3 +1178,3 @@ * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
                     else {
-                        this.delete(k);
+                        this.#delete(k, 'fetch');
                     }
@@ -1137,3 +1208,3 @@ }
                 if (del) {
-                    this.delete(k);
+                    this.#delete(k, 'fetch');
                 }
@@ -1284,2 +1355,24 @@ else if (!allowStaleAborted) {
     }
+    async forceFetch(k, fetchOptions = {}) {
+        const v = await this.fetch(k, fetchOptions);
+        if (v === undefined)
+            throw new Error('fetch() returned undefined');
+        return v;
+    }
+    memo(k, memoOptions = {}) {
+        const memoMethod = this.#memoMethod;
+        if (!memoMethod) {
+            throw new Error('no memoMethod provided to constructor');
+        }
+        const { context, forceRefresh, ...options } = memoOptions;
+        const v = this.get(k, options);
+        if (!forceRefresh && v !== undefined)
+            return v;
+        const vv = memoMethod(k, v, {
+            options,
+            context,
+        });
+        this.set(k, vv, options);
+        return vv;
+    }
     /**
@@ -1305,3 +1398,3 @@ * Return a value from the cache. Will update the recency of the cache
                     if (!noDeleteOnStaleGet) {
-                        this.delete(k);
+                        this.#delete(k, 'expire');
                     }
@@ -1369,5 +1462,9 @@ if (status && allowStale)
      * Deletes a key out of the cache.
+     *
      * Returns true if the key was deleted, false otherwise.
      */
     delete(k) {
+        return this.#delete(k, 'delete');
+    }
+    #delete(k, reason) {
         let deleted = false;
@@ -1379,3 +1476,3 @@ if (this.#size !== 0) {
                 if (this.#size === 1) {
-                    this.clear();
+                    this.#clear(reason);
                 }
@@ -1390,6 +1487,6 @@ else {
                         if (this.#hasDispose) {
-                            this.#dispose?.(v, k, 'delete');
+                            this.#dispose?.(v, k, reason);
                         }
                         if (this.#hasDisposeAfter) {
-                            this.#disposed?.push([v, k, 'delete']);
+                            this.#disposed?.push([v, k, reason]);
                         }
@@ -1430,2 +1527,5 @@ }
     clear() {
+        return this.#clear('delete');
+    }
+    #clear(reason) {
         for (const index of this.#rindexes({ allowStale: true })) {
@@ -1439,6 +1539,6 @@ const v = this.#valList[index];
                 if (this.#hasDispose) {
-                    this.#dispose?.(v, k, 'delete');
+                    this.#dispose?.(v, k, reason);
                 }
                 if (this.#hasDisposeAfter) {
-                    this.#disposed?.push([v, k, 'delete']);
+                    this.#disposed?.push([v, k, reason]);
                 }
@@ -1445,0 +1545,0 @@ }

dist/commonjs/index.min.js

@@ -1,2 +0,2 @@
-"use strict";var G=(o,t,e)=>{if(!t.has(o))throw TypeError("Cannot "+e)};var j=(o,t,e)=>(G(o,t,"read from private field"),e?e.call(o):t.get(o)),I=(o,t,e)=>{if(t.has(o))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(o):t.set(o,e)},D=(o,t,e,i)=>(G(o,t,"write to private field"),i?i.call(o,e):t.set(o,e),e);Object.defineProperty(exports,"__esModule",{value:!0});exports.LRUCache=void 0;var T=typeof performance=="object"&&performance&&typeof performance.now=="function"?performance:Date,N=new Set,L=typeof process=="object"&&process?process:{},P=(o,t,e,i)=>{typeof L.emitWarning=="function"?L.emitWarning(o,t,e,i):console.error(`[${e}] ${t}: ${o}`)},W=globalThis.AbortController,M=globalThis.AbortSignal;if(typeof W>"u"){M=class{onabort;_onabort=[];reason;aborted=!1;addEventListener(i,s){this._onabort.push(s)}},W=class{constructor(){t()}signal=new M;abort(i){if(!this.signal.aborted){this.signal.reason=i,this.signal.aborted=!0;for(let s of this.signal._onabort)s(i);this.signal.onabort?.(i)}}};let o=L.env?.LRU_CACHE_IGNORE_AC_WARNING!=="1",t=()=>{o&&(o=!1,P("AbortController is not defined. If using lru-cache in node 14, load an AbortController polyfill from the `node-abort-controller` package. A minimal polyfill is provided for use by LRUCache.fetch(), but it should not be relied upon in other contexts (eg, passing it to other APIs that use AbortController/AbortSignal might have undesirable effects). You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.","NO_ABORT_CONTROLLER","ENOTSUP",t))}}var V=o=>!N.has(o),Y=Symbol("type"),A=o=>o&&o===Math.floor(o)&&o>0&&isFinite(o),H=o=>A(o)?o<=Math.pow(2,8)?Uint8Array:o<=Math.pow(2,16)?Uint16Array:o<=Math.pow(2,32)?Uint32Array:o<=Number.MAX_SAFE_INTEGER?E:null:null,E=class extends Array{constructor(t){super(t),this.fill(0)}},v,z=class{heap;length;static create(t){let e=H(t);if(!e)return[];D(z,v,!0);let i=new z(t,e);return D(z,v,!1),i}constructor(t,e){if(!j(z,v))throw new TypeError("instantiate Stack using Stack.create(n)");this.heap=new e(t),this.length=0}push(t){this.heap[this.length++]=t}pop(){return this.heap[--this.length]}},R=z;v=new WeakMap,I(R,v,!1);var C=class{#g;#f;#p;#w;#C;ttl;ttlResolution;ttlAutopurge;updateAgeOnGet;updateAgeOnHas;allowStale;noDisposeOnSet;noUpdateTTL;maxEntrySize;sizeCalculation;noDeleteOnFetchRejection;noDeleteOnStaleGet;allowStaleOnFetchAbort;allowStaleOnFetchRejection;ignoreFetchAbort;#n;#S;#s;#i;#t;#l;#c;#o;#h;#_;#r;#b;#y;#u;#m;#T;#a;static unsafeExposeInternals(t){return{starts:t.#y,ttls:t.#u,sizes:t.#b,keyMap:t.#s,keyList:t.#i,valList:t.#t,next:t.#l,prev:t.#c,get head(){return t.#o},get tail(){return t.#h},free:t.#_,isBackgroundFetch:e=>t.#e(e),backgroundFetch:(e,i,s,n)=>t.#D(e,i,s,n),moveToTail:e=>t.#v(e),indexes:e=>t.#A(e),rindexes:e=>t.#F(e),isStale:e=>t.#d(e)}}get max(){return this.#g}get maxSize(){return this.#f}get calculatedSize(){return this.#S}get size(){return this.#n}get fetchMethod(){return this.#C}get dispose(){return this.#p}get disposeAfter(){return this.#w}constructor(t){let{max:e=0,ttl:i,ttlResolution:s=1,ttlAutopurge:n,updateAgeOnGet:h,updateAgeOnHas:l,allowStale:r,dispose:g,disposeAfter:b,noDisposeOnSet:f,noUpdateTTL:u,maxSize:c=0,maxEntrySize:F=0,sizeCalculation:d,fetchMethod:S,noDeleteOnFetchRejection:a,noDeleteOnStaleGet:w,allowStaleOnFetchRejection:y,allowStaleOnFetchAbort:p,ignoreFetchAbort:_}=t;if(e!==0&&!A(e))throw new TypeError("max option must be a nonnegative integer");let O=e?H(e):Array;if(!O)throw new Error("invalid max value: "+e);if(this.#g=e,this.#f=c,this.maxEntrySize=F||this.#f,this.sizeCalculation=d,this.sizeCalculation){if(!this.#f&&!this.maxEntrySize)throw new TypeError("cannot set sizeCalculation without setting maxSize or maxEntrySize");if(typeof this.sizeCalculation!="function")throw new TypeError("sizeCalculation set to non-function")}if(S!==void 0&&typeof S!="function")throw new TypeError("fetchMethod must be a function if specified");if(this.#C=S,this.#T=!!S,this.#s=new Map,this.#i=new Array(e).fill(void 0),this.#t=new Array(e).fill(void 0),this.#l=new O(e),this.#c=new O(e),this.#o=0,this.#h=0,this.#_=R.create(e),this.#n=0,this.#S=0,typeof g=="function"&&(this.#p=g),typeof b=="function"?(this.#w=b,this.#r=[]):(this.#w=void 0,this.#r=void 0),this.#m=!!this.#p,this.#a=!!this.#w,this.noDisposeOnSet=!!f,this.noUpdateTTL=!!u,this.noDeleteOnFetchRejection=!!a,this.allowStaleOnFetchRejection=!!y,this.allowStaleOnFetchAbort=!!p,this.ignoreFetchAbort=!!_,this.maxEntrySize!==0){if(this.#f!==0&&!A(this.#f))throw new TypeError("maxSize must be a positive integer if specified");if(!A(this.maxEntrySize))throw new TypeError("maxEntrySize must be a positive integer if specified");this.#I()}if(this.allowStale=!!r,this.noDeleteOnStaleGet=!!w,this.updateAgeOnGet=!!h,this.updateAgeOnHas=!!l,this.ttlResolution=A(s)||s===0?s:1,this.ttlAutopurge=!!n,this.ttl=i||0,this.ttl){if(!A(this.ttl))throw new TypeError("ttl must be a positive integer if specified");this.#L()}if(this.#g===0&&this.ttl===0&&this.#f===0)throw new TypeError("At least one of max, maxSize, or ttl is required");if(!this.ttlAutopurge&&!this.#g&&!this.#f){let m="LRU_CACHE_UNBOUNDED";V(m)&&(N.add(m),P("TTL caching without ttlAutopurge, max, or maxSize can result in unbounded memory consumption.","UnboundedCacheWarning",m,C))}}getRemainingTTL(t){return this.#s.has(t)?1/0:0}#L(){let t=new E(this.#g),e=new E(this.#g);this.#u=t,this.#y=e,this.#U=(n,h,l=T.now())=>{if(e[n]=h!==0?l:0,t[n]=h,h!==0&&this.ttlAutopurge){let r=setTimeout(()=>{this.#d(n)&&this.delete(this.#i[n])},h+1);r.unref&&r.unref()}},this.#z=n=>{e[n]=t[n]!==0?T.now():0},this.#O=(n,h)=>{if(t[h]){let l=t[h],r=e[h];if(!l||!r)return;n.ttl=l,n.start=r,n.now=i||s();let g=n.now-r;n.remainingTTL=l-g}};let i=0,s=()=>{let n=T.now();if(this.ttlResolution>0){i=n;let h=setTimeout(()=>i=0,this.ttlResolution);h.unref&&h.unref()}return n};this.getRemainingTTL=n=>{let h=this.#s.get(n);if(h===void 0)return 0;let l=t[h],r=e[h];if(!l||!r)return 1/0;let g=(i||s())-r;return l-g},this.#d=n=>{let h=e[n],l=t[n];return!!l&&!!h&&(i||s())-h>l}}#z=()=>{};#O=()=>{};#U=()=>{};#d=()=>!1;#I(){let t=new E(this.#g);this.#S=0,this.#b=t,this.#E=e=>{this.#S-=t[e],t[e]=0},this.#x=(e,i,s,n)=>{if(this.#e(i))return 0;if(!A(s))if(n){if(typeof n!="function")throw new TypeError("sizeCalculation must be a function");if(s=n(i,e),!A(s))throw new TypeError("sizeCalculation return invalid (expect positive integer)")}else throw new TypeError("invalid size value (must be positive integer). When maxSize or maxEntrySize is used, sizeCalculation or size must be set.");return s},this.#R=(e,i,s)=>{if(t[e]=i,this.#f){let n=this.#f-t[e];for(;this.#S>n;)this.#W(!0)}this.#S+=t[e],s&&(s.entrySize=i,s.totalCalculatedSize=this.#S)}}#E=t=>{};#R=(t,e,i)=>{};#x=(t,e,i,s)=>{if(i||s)throw new TypeError("cannot set size without setting maxSize or maxEntrySize on cache");return 0};*#A({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#h;!(!this.#G(e)||((t||!this.#d(e))&&(yield e),e===this.#o));)e=this.#c[e]}*#F({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#o;!(!this.#G(e)||((t||!this.#d(e))&&(yield e),e===this.#h));)e=this.#l[e]}#G(t){return t!==void 0&&this.#s.get(this.#i[t])===t}*entries(){for(let t of this.#A())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*rentries(){for(let t of this.#F())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*keys(){for(let t of this.#A()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*rkeys(){for(let t of this.#F()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*values(){for(let t of this.#A())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}*rvalues(){for(let t of this.#F())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}[Symbol.iterator](){return this.entries()}[Symbol.toStringTag]="LRUCache";find(t,e={}){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;if(n!==void 0&&t(n,this.#i[i],this))return this.get(this.#i[i],e)}}forEach(t,e=this){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}rforEach(t,e=this){for(let i of this.#F()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}purgeStale(){let t=!1;for(let e of this.#F({allowStale:!0}))this.#d(e)&&(this.delete(this.#i[e]),t=!0);return t}info(t){let e=this.#s.get(t);if(e===void 0)return;let i=this.#t[e],s=this.#e(i)?i.__staleWhileFetching:i;if(s===void 0)return;let n={value:s};if(this.#u&&this.#y){let h=this.#u[e],l=this.#y[e];if(h&&l){let r=h-(T.now()-l);n.ttl=r,n.start=Date.now()}}return this.#b&&(n.size=this.#b[e]),n}dump(){let t=[];for(let e of this.#A({allowStale:!0})){let i=this.#i[e],s=this.#t[e],n=this.#e(s)?s.__staleWhileFetching:s;if(n===void 0||i===void 0)continue;let h={value:n};if(this.#u&&this.#y){h.ttl=this.#u[e];let l=T.now()-this.#y[e];h.start=Math.floor(Date.now()-l)}this.#b&&(h.size=this.#b[e]),t.unshift([i,h])}return t}load(t){this.clear();for(let[e,i]of t){if(i.start){let s=Date.now()-i.start;i.start=T.now()-s}this.set(e,i.value,i)}}set(t,e,i={}){if(e===void 0)return this.delete(t),this;let{ttl:s=this.ttl,start:n,noDisposeOnSet:h=this.noDisposeOnSet,sizeCalculation:l=this.sizeCalculation,status:r}=i,{noUpdateTTL:g=this.noUpdateTTL}=i,b=this.#x(t,e,i.size||0,l);if(this.maxEntrySize&&b>this.maxEntrySize)return r&&(r.set="miss",r.maxEntrySizeExceeded=!0),this.delete(t),this;let f=this.#n===0?void 0:this.#s.get(t);if(f===void 0)f=this.#n===0?this.#h:this.#_.length!==0?this.#_.pop():this.#n===this.#g?this.#W(!1):this.#n,this.#i[f]=t,this.#t[f]=e,this.#s.set(t,f),this.#l[this.#h]=f,this.#c[f]=this.#h,this.#h=f,this.#n++,this.#R(f,b,r),r&&(r.set="add"),g=!1;else{this.#v(f);let u=this.#t[f];if(e!==u){if(this.#T&&this.#e(u)){u.__abortController.abort(new Error("replaced"));let{__staleWhileFetching:c}=u;c!==void 0&&!h&&(this.#m&&this.#p?.(c,t,"set"),this.#a&&this.#r?.push([c,t,"set"]))}else h||(this.#m&&this.#p?.(u,t,"set"),this.#a&&this.#r?.push([u,t,"set"]));if(this.#E(f),this.#R(f,b,r),this.#t[f]=e,r){r.set="replace";let c=u&&this.#e(u)?u.__staleWhileFetching:u;c!==void 0&&(r.oldValue=c)}}else r&&(r.set="update")}if(s!==0&&!this.#u&&this.#L(),this.#u&&(g||this.#U(f,s,n),r&&this.#O(r,f)),!h&&this.#a&&this.#r){let u=this.#r,c;for(;c=u?.shift();)this.#w?.(...c)}return this}pop(){try{for(;this.#n;){let t=this.#t[this.#o];if(this.#W(!0),this.#e(t)){if(t.__staleWhileFetching)return t.__staleWhileFetching}else if(t!==void 0)return t}}finally{if(this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}}#W(t){let e=this.#o,i=this.#i[e],s=this.#t[e];return this.#T&&this.#e(s)?s.__abortController.abort(new Error("evicted")):(this.#m||this.#a)&&(this.#m&&this.#p?.(s,i,"evict"),this.#a&&this.#r?.push([s,i,"evict"])),this.#E(e),t&&(this.#i[e]=void 0,this.#t[e]=void 0,this.#_.push(e)),this.#n===1?(this.#o=this.#h=0,this.#_.length=0):this.#o=this.#l[e],this.#s.delete(i),this.#n--,e}has(t,e={}){let{updateAgeOnHas:i=this.updateAgeOnHas,status:s}=e,n=this.#s.get(t);if(n!==void 0){let h=this.#t[n];if(this.#e(h)&&h.__staleWhileFetching===void 0)return!1;if(this.#d(n))s&&(s.has="stale",this.#O(s,n));else return i&&this.#z(n),s&&(s.has="hit",this.#O(s,n)),!0}else s&&(s.has="miss");return!1}peek(t,e={}){let{allowStale:i=this.allowStale}=e,s=this.#s.get(t);if(s===void 0||!i&&this.#d(s))return;let n=this.#t[s];return this.#e(n)?n.__staleWhileFetching:n}#D(t,e,i,s){let n=e===void 0?void 0:this.#t[e];if(this.#e(n))return n;let h=new W,{signal:l}=i;l?.addEventListener("abort",()=>h.abort(l.reason),{signal:h.signal});let r={signal:h.signal,options:i,context:s},g=(d,S=!1)=>{let{aborted:a}=h.signal,w=i.ignoreFetchAbort&&d!==void 0;if(i.status&&(a&&!S?(i.status.fetchAborted=!0,i.status.fetchError=h.signal.reason,w&&(i.status.fetchAbortIgnored=!0)):i.status.fetchResolved=!0),a&&!w&&!S)return f(h.signal.reason);let y=c;return this.#t[e]===c&&(d===void 0?y.__staleWhileFetching?this.#t[e]=y.__staleWhileFetching:this.delete(t):(i.status&&(i.status.fetchUpdated=!0),this.set(t,d,r.options))),d},b=d=>(i.status&&(i.status.fetchRejected=!0,i.status.fetchError=d),f(d)),f=d=>{let{aborted:S}=h.signal,a=S&&i.allowStaleOnFetchAbort,w=a||i.allowStaleOnFetchRejection,y=w||i.noDeleteOnFetchRejection,p=c;if(this.#t[e]===c&&(!y||p.__staleWhileFetching===void 0?this.delete(t):a||(this.#t[e]=p.__staleWhileFetching)),w)return i.status&&p.__staleWhileFetching!==void 0&&(i.status.returnedStale=!0),p.__staleWhileFetching;if(p.__returned===p)throw d},u=(d,S)=>{let a=this.#C?.(t,n,r);a&&a instanceof Promise&&a.then(w=>d(w===void 0?void 0:w),S),h.signal.addEventListener("abort",()=>{(!i.ignoreFetchAbort||i.allowStaleOnFetchAbort)&&(d(void 0),i.allowStaleOnFetchAbort&&(d=w=>g(w,!0)))})};i.status&&(i.status.fetchDispatched=!0);let c=new Promise(u).then(g,b),F=Object.assign(c,{__abortController:h,__staleWhileFetching:n,__returned:void 0});return e===void 0?(this.set(t,F,{...r.options,status:void 0}),e=this.#s.get(t)):this.#t[e]=F,F}#e(t){if(!this.#T)return!1;let e=t;return!!e&&e instanceof Promise&&e.hasOwnProperty("__staleWhileFetching")&&e.__abortController instanceof W}async fetch(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,ttl:h=this.ttl,noDisposeOnSet:l=this.noDisposeOnSet,size:r=0,sizeCalculation:g=this.sizeCalculation,noUpdateTTL:b=this.noUpdateTTL,noDeleteOnFetchRejection:f=this.noDeleteOnFetchRejection,allowStaleOnFetchRejection:u=this.allowStaleOnFetchRejection,ignoreFetchAbort:c=this.ignoreFetchAbort,allowStaleOnFetchAbort:F=this.allowStaleOnFetchAbort,context:d,forceRefresh:S=!1,status:a,signal:w}=e;if(!this.#T)return a&&(a.fetch="get"),this.get(t,{allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,status:a});let y={allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,ttl:h,noDisposeOnSet:l,size:r,sizeCalculation:g,noUpdateTTL:b,noDeleteOnFetchRejection:f,allowStaleOnFetchRejection:u,allowStaleOnFetchAbort:F,ignoreFetchAbort:c,status:a,signal:w},p=this.#s.get(t);if(p===void 0){a&&(a.fetch="miss");let _=this.#D(t,p,y,d);return _.__returned=_}else{let _=this.#t[p];if(this.#e(_)){let x=i&&_.__staleWhileFetching!==void 0;return a&&(a.fetch="inflight",x&&(a.returnedStale=!0)),x?_.__staleWhileFetching:_.__returned=_}let O=this.#d(p);if(!S&&!O)return a&&(a.fetch="hit"),this.#v(p),s&&this.#z(p),a&&this.#O(a,p),_;let m=this.#D(t,p,y,d),U=m.__staleWhileFetching!==void 0&&i;return a&&(a.fetch=O?"stale":"refresh",U&&O&&(a.returnedStale=!0)),U?m.__staleWhileFetching:m.__returned=m}}get(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,status:h}=e,l=this.#s.get(t);if(l!==void 0){let r=this.#t[l],g=this.#e(r);return h&&this.#O(h,l),this.#d(l)?(h&&(h.get="stale"),g?(h&&i&&r.__staleWhileFetching!==void 0&&(h.returnedStale=!0),i?r.__staleWhileFetching:void 0):(n||this.delete(t),h&&i&&(h.returnedStale=!0),i?r:void 0)):(h&&(h.get="hit"),g?r.__staleWhileFetching:(this.#v(l),s&&this.#z(l),r))}else h&&(h.get="miss")}#j(t,e){this.#c[e]=t,this.#l[t]=e}#v(t){t!==this.#h&&(t===this.#o?this.#o=this.#l[t]:this.#j(this.#c[t],this.#l[t]),this.#j(this.#h,t),this.#h=t)}delete(t){let e=!1;if(this.#n!==0){let i=this.#s.get(t);if(i!==void 0)if(e=!0,this.#n===1)this.clear();else{this.#E(i);let s=this.#t[i];if(this.#e(s)?s.__abortController.abort(new Error("deleted")):(this.#m||this.#a)&&(this.#m&&this.#p?.(s,t,"delete"),this.#a&&this.#r?.push([s,t,"delete"])),this.#s.delete(t),this.#i[i]=void 0,this.#t[i]=void 0,i===this.#h)this.#h=this.#c[i];else if(i===this.#o)this.#o=this.#l[i];else{let n=this.#c[i];this.#l[n]=this.#l[i];let h=this.#l[i];this.#c[h]=this.#c[i]}this.#n--,this.#_.push(i)}}if(this.#a&&this.#r?.length){let i=this.#r,s;for(;s=i?.shift();)this.#w?.(...s)}return e}clear(){for(let t of this.#F({allowStale:!0})){let e=this.#t[t];if(this.#e(e))e.__abortController.abort(new Error("deleted"));else{let i=this.#i[t];this.#m&&this.#p?.(e,i,"delete"),this.#a&&this.#r?.push([e,i,"delete"])}}if(this.#s.clear(),this.#t.fill(void 0),this.#i.fill(void 0),this.#u&&this.#y&&(this.#u.fill(0),this.#y.fill(0)),this.#b&&this.#b.fill(0),this.#o=0,this.#h=0,this.#_.length=0,this.#S=0,this.#n=0,this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}};exports.LRUCache=C;
+"use strict";var G=(l,t,e)=>{if(!t.has(l))throw TypeError("Cannot "+e)};var j=(l,t,e)=>(G(l,t,"read from private field"),e?e.call(l):t.get(l)),I=(l,t,e)=>{if(t.has(l))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(l):t.set(l,e)},x=(l,t,e,i)=>(G(l,t,"write to private field"),i?i.call(l,e):t.set(l,e),e);Object.defineProperty(exports,"__esModule",{value:!0});exports.LRUCache=void 0;var T=typeof performance=="object"&&performance&&typeof performance.now=="function"?performance:Date,P=new Set,U=typeof process=="object"&&process?process:{},H=(l,t,e,i)=>{typeof U.emitWarning=="function"?U.emitWarning(l,t,e,i):console.error(`[${e}] ${t}: ${l}`)},D=globalThis.AbortController,N=globalThis.AbortSignal;if(typeof D>"u"){N=class{onabort;_onabort=[];reason;aborted=!1;addEventListener(i,s){this._onabort.push(s)}},D=class{constructor(){t()}signal=new N;abort(i){if(!this.signal.aborted){this.signal.reason=i,this.signal.aborted=!0;for(let s of this.signal._onabort)s(i);this.signal.onabort?.(i)}}};let l=U.env?.LRU_CACHE_IGNORE_AC_WARNING!=="1",t=()=>{l&&(l=!1,H("AbortController is not defined. If using lru-cache in node 14, load an AbortController polyfill from the `node-abort-controller` package. A minimal polyfill is provided for use by LRUCache.fetch(), but it should not be relied upon in other contexts (eg, passing it to other APIs that use AbortController/AbortSignal might have undesirable effects). You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.","NO_ABORT_CONTROLLER","ENOTSUP",t))}}var V=l=>!P.has(l),Y=Symbol("type"),A=l=>l&&l===Math.floor(l)&&l>0&&isFinite(l),k=l=>A(l)?l<=Math.pow(2,8)?Uint8Array:l<=Math.pow(2,16)?Uint16Array:l<=Math.pow(2,32)?Uint32Array:l<=Number.MAX_SAFE_INTEGER?E:null:null,E=class extends Array{constructor(t){super(t),this.fill(0)}},v,O=class{heap;length;static create(t){let e=k(t);if(!e)return[];x(O,v,!0);let i=new O(t,e);return x(O,v,!1),i}constructor(t,e){if(!j(O,v))throw new TypeError("instantiate Stack using Stack.create(n)");this.heap=new e(t),this.length=0}push(t){this.heap[this.length++]=t}pop(){return this.heap[--this.length]}},W=O;v=new WeakMap,I(W,v,!1);var C=class{#g;#f;#p;#w;#R;#W;ttl;ttlResolution;ttlAutopurge;updateAgeOnGet;updateAgeOnHas;allowStale;noDisposeOnSet;noUpdateTTL;maxEntrySize;sizeCalculation;noDeleteOnFetchRejection;noDeleteOnStaleGet;allowStaleOnFetchAbort;allowStaleOnFetchRejection;ignoreFetchAbort;#n;#S;#s;#i;#t;#l;#c;#o;#h;#_;#r;#b;#m;#u;#y;#E;#a;static unsafeExposeInternals(t){return{starts:t.#m,ttls:t.#u,sizes:t.#b,keyMap:t.#s,keyList:t.#i,valList:t.#t,next:t.#l,prev:t.#c,get head(){return t.#o},get tail(){return t.#h},free:t.#_,isBackgroundFetch:e=>t.#e(e),backgroundFetch:(e,i,s,n)=>t.#x(e,i,s,n),moveToTail:e=>t.#C(e),indexes:e=>t.#A(e),rindexes:e=>t.#F(e),isStale:e=>t.#d(e)}}get max(){return this.#g}get maxSize(){return this.#f}get calculatedSize(){return this.#S}get size(){return this.#n}get fetchMethod(){return this.#R}get memoMethod(){return this.#W}get dispose(){return this.#p}get disposeAfter(){return this.#w}constructor(t){let{max:e=0,ttl:i,ttlResolution:s=1,ttlAutopurge:n,updateAgeOnGet:h,updateAgeOnHas:o,allowStale:r,dispose:g,disposeAfter:b,noDisposeOnSet:f,noUpdateTTL:u,maxSize:c=0,maxEntrySize:F=0,sizeCalculation:d,fetchMethod:S,memoMethod:a,noDeleteOnFetchRejection:w,noDeleteOnStaleGet:m,allowStaleOnFetchRejection:p,allowStaleOnFetchAbort:_,ignoreFetchAbort:z}=t;if(e!==0&&!A(e))throw new TypeError("max option must be a nonnegative integer");let y=e?k(e):Array;if(!y)throw new Error("invalid max value: "+e);if(this.#g=e,this.#f=c,this.maxEntrySize=F||this.#f,this.sizeCalculation=d,this.sizeCalculation){if(!this.#f&&!this.maxEntrySize)throw new TypeError("cannot set sizeCalculation without setting maxSize or maxEntrySize");if(typeof this.sizeCalculation!="function")throw new TypeError("sizeCalculation set to non-function")}if(a!==void 0&&typeof a!="function")throw new TypeError("memoMethod must be a function if defined");if(this.#W=a,S!==void 0&&typeof S!="function")throw new TypeError("fetchMethod must be a function if specified");if(this.#R=S,this.#E=!!S,this.#s=new Map,this.#i=new Array(e).fill(void 0),this.#t=new Array(e).fill(void 0),this.#l=new y(e),this.#c=new y(e),this.#o=0,this.#h=0,this.#_=W.create(e),this.#n=0,this.#S=0,typeof g=="function"&&(this.#p=g),typeof b=="function"?(this.#w=b,this.#r=[]):(this.#w=void 0,this.#r=void 0),this.#y=!!this.#p,this.#a=!!this.#w,this.noDisposeOnSet=!!f,this.noUpdateTTL=!!u,this.noDeleteOnFetchRejection=!!w,this.allowStaleOnFetchRejection=!!p,this.allowStaleOnFetchAbort=!!_,this.ignoreFetchAbort=!!z,this.maxEntrySize!==0){if(this.#f!==0&&!A(this.#f))throw new TypeError("maxSize must be a positive integer if specified");if(!A(this.maxEntrySize))throw new TypeError("maxEntrySize must be a positive integer if specified");this.#P()}if(this.allowStale=!!r,this.noDeleteOnStaleGet=!!m,this.updateAgeOnGet=!!h,this.updateAgeOnHas=!!o,this.ttlResolution=A(s)||s===0?s:1,this.ttlAutopurge=!!n,this.ttl=i||0,this.ttl){if(!A(this.ttl))throw new TypeError("ttl must be a positive integer if specified");this.#U()}if(this.#g===0&&this.ttl===0&&this.#f===0)throw new TypeError("At least one of max, maxSize, or ttl is required");if(!this.ttlAutopurge&&!this.#g&&!this.#f){let R="LRU_CACHE_UNBOUNDED";V(R)&&(P.add(R),H("TTL caching without ttlAutopurge, max, or maxSize can result in unbounded memory consumption.","UnboundedCacheWarning",R,C))}}getRemainingTTL(t){return this.#s.has(t)?1/0:0}#U(){let t=new E(this.#g),e=new E(this.#g);this.#u=t,this.#m=e,this.#M=(n,h,o=T.now())=>{if(e[n]=h!==0?o:0,t[n]=h,h!==0&&this.ttlAutopurge){let r=setTimeout(()=>{this.#d(n)&&this.#T(this.#i[n],"expire")},h+1);r.unref&&r.unref()}},this.#v=n=>{e[n]=t[n]!==0?T.now():0},this.#O=(n,h)=>{if(t[h]){let o=t[h],r=e[h];if(!o||!r)return;n.ttl=o,n.start=r,n.now=i||s();let g=n.now-r;n.remainingTTL=o-g}};let i=0,s=()=>{let n=T.now();if(this.ttlResolution>0){i=n;let h=setTimeout(()=>i=0,this.ttlResolution);h.unref&&h.unref()}return n};this.getRemainingTTL=n=>{let h=this.#s.get(n);if(h===void 0)return 0;let o=t[h],r=e[h];if(!o||!r)return 1/0;let g=(i||s())-r;return o-g},this.#d=n=>{let h=e[n],o=t[n];return!!o&&!!h&&(i||s())-h>o}}#v=()=>{};#O=()=>{};#M=()=>{};#d=()=>!1;#P(){let t=new E(this.#g);this.#S=0,this.#b=t,this.#z=e=>{this.#S-=t[e],t[e]=0},this.#G=(e,i,s,n)=>{if(this.#e(i))return 0;if(!A(s))if(n){if(typeof n!="function")throw new TypeError("sizeCalculation must be a function");if(s=n(i,e),!A(s))throw new TypeError("sizeCalculation return invalid (expect positive integer)")}else throw new TypeError("invalid size value (must be positive integer). When maxSize or maxEntrySize is used, sizeCalculation or size must be set.");return s},this.#D=(e,i,s)=>{if(t[e]=i,this.#f){let n=this.#f-t[e];for(;this.#S>n;)this.#L(!0)}this.#S+=t[e],s&&(s.entrySize=i,s.totalCalculatedSize=this.#S)}}#z=t=>{};#D=(t,e,i)=>{};#G=(t,e,i,s)=>{if(i||s)throw new TypeError("cannot set size without setting maxSize or maxEntrySize on cache");return 0};*#A({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#h;!(!this.#j(e)||((t||!this.#d(e))&&(yield e),e===this.#o));)e=this.#c[e]}*#F({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#o;!(!this.#j(e)||((t||!this.#d(e))&&(yield e),e===this.#h));)e=this.#l[e]}#j(t){return t!==void 0&&this.#s.get(this.#i[t])===t}*entries(){for(let t of this.#A())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*rentries(){for(let t of this.#F())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*keys(){for(let t of this.#A()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*rkeys(){for(let t of this.#F()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*values(){for(let t of this.#A())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}*rvalues(){for(let t of this.#F())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}[Symbol.iterator](){return this.entries()}[Symbol.toStringTag]="LRUCache";find(t,e={}){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;if(n!==void 0&&t(n,this.#i[i],this))return this.get(this.#i[i],e)}}forEach(t,e=this){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}rforEach(t,e=this){for(let i of this.#F()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}purgeStale(){let t=!1;for(let e of this.#F({allowStale:!0}))this.#d(e)&&(this.#T(this.#i[e],"expire"),t=!0);return t}info(t){let e=this.#s.get(t);if(e===void 0)return;let i=this.#t[e],s=this.#e(i)?i.__staleWhileFetching:i;if(s===void 0)return;let n={value:s};if(this.#u&&this.#m){let h=this.#u[e],o=this.#m[e];if(h&&o){let r=h-(T.now()-o);n.ttl=r,n.start=Date.now()}}return this.#b&&(n.size=this.#b[e]),n}dump(){let t=[];for(let e of this.#A({allowStale:!0})){let i=this.#i[e],s=this.#t[e],n=this.#e(s)?s.__staleWhileFetching:s;if(n===void 0||i===void 0)continue;let h={value:n};if(this.#u&&this.#m){h.ttl=this.#u[e];let o=T.now()-this.#m[e];h.start=Math.floor(Date.now()-o)}this.#b&&(h.size=this.#b[e]),t.unshift([i,h])}return t}load(t){this.clear();for(let[e,i]of t){if(i.start){let s=Date.now()-i.start;i.start=T.now()-s}this.set(e,i.value,i)}}set(t,e,i={}){if(e===void 0)return this.delete(t),this;let{ttl:s=this.ttl,start:n,noDisposeOnSet:h=this.noDisposeOnSet,sizeCalculation:o=this.sizeCalculation,status:r}=i,{noUpdateTTL:g=this.noUpdateTTL}=i,b=this.#G(t,e,i.size||0,o);if(this.maxEntrySize&&b>this.maxEntrySize)return r&&(r.set="miss",r.maxEntrySizeExceeded=!0),this.#T(t,"set"),this;let f=this.#n===0?void 0:this.#s.get(t);if(f===void 0)f=this.#n===0?this.#h:this.#_.length!==0?this.#_.pop():this.#n===this.#g?this.#L(!1):this.#n,this.#i[f]=t,this.#t[f]=e,this.#s.set(t,f),this.#l[this.#h]=f,this.#c[f]=this.#h,this.#h=f,this.#n++,this.#D(f,b,r),r&&(r.set="add"),g=!1;else{this.#C(f);let u=this.#t[f];if(e!==u){if(this.#E&&this.#e(u)){u.__abortController.abort(new Error("replaced"));let{__staleWhileFetching:c}=u;c!==void 0&&!h&&(this.#y&&this.#p?.(c,t,"set"),this.#a&&this.#r?.push([c,t,"set"]))}else h||(this.#y&&this.#p?.(u,t,"set"),this.#a&&this.#r?.push([u,t,"set"]));if(this.#z(f),this.#D(f,b,r),this.#t[f]=e,r){r.set="replace";let c=u&&this.#e(u)?u.__staleWhileFetching:u;c!==void 0&&(r.oldValue=c)}}else r&&(r.set="update")}if(s!==0&&!this.#u&&this.#U(),this.#u&&(g||this.#M(f,s,n),r&&this.#O(r,f)),!h&&this.#a&&this.#r){let u=this.#r,c;for(;c=u?.shift();)this.#w?.(...c)}return this}pop(){try{for(;this.#n;){let t=this.#t[this.#o];if(this.#L(!0),this.#e(t)){if(t.__staleWhileFetching)return t.__staleWhileFetching}else if(t!==void 0)return t}}finally{if(this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}}#L(t){let e=this.#o,i=this.#i[e],s=this.#t[e];return this.#E&&this.#e(s)?s.__abortController.abort(new Error("evicted")):(this.#y||this.#a)&&(this.#y&&this.#p?.(s,i,"evict"),this.#a&&this.#r?.push([s,i,"evict"])),this.#z(e),t&&(this.#i[e]=void 0,this.#t[e]=void 0,this.#_.push(e)),this.#n===1?(this.#o=this.#h=0,this.#_.length=0):this.#o=this.#l[e],this.#s.delete(i),this.#n--,e}has(t,e={}){let{updateAgeOnHas:i=this.updateAgeOnHas,status:s}=e,n=this.#s.get(t);if(n!==void 0){let h=this.#t[n];if(this.#e(h)&&h.__staleWhileFetching===void 0)return!1;if(this.#d(n))s&&(s.has="stale",this.#O(s,n));else return i&&this.#v(n),s&&(s.has="hit",this.#O(s,n)),!0}else s&&(s.has="miss");return!1}peek(t,e={}){let{allowStale:i=this.allowStale}=e,s=this.#s.get(t);if(s===void 0||!i&&this.#d(s))return;let n=this.#t[s];return this.#e(n)?n.__staleWhileFetching:n}#x(t,e,i,s){let n=e===void 0?void 0:this.#t[e];if(this.#e(n))return n;let h=new D,{signal:o}=i;o?.addEventListener("abort",()=>h.abort(o.reason),{signal:h.signal});let r={signal:h.signal,options:i,context:s},g=(d,S=!1)=>{let{aborted:a}=h.signal,w=i.ignoreFetchAbort&&d!==void 0;if(i.status&&(a&&!S?(i.status.fetchAborted=!0,i.status.fetchError=h.signal.reason,w&&(i.status.fetchAbortIgnored=!0)):i.status.fetchResolved=!0),a&&!w&&!S)return f(h.signal.reason);let m=c;return this.#t[e]===c&&(d===void 0?m.__staleWhileFetching?this.#t[e]=m.__staleWhileFetching:this.#T(t,"fetch"):(i.status&&(i.status.fetchUpdated=!0),this.set(t,d,r.options))),d},b=d=>(i.status&&(i.status.fetchRejected=!0,i.status.fetchError=d),f(d)),f=d=>{let{aborted:S}=h.signal,a=S&&i.allowStaleOnFetchAbort,w=a||i.allowStaleOnFetchRejection,m=w||i.noDeleteOnFetchRejection,p=c;if(this.#t[e]===c&&(!m||p.__staleWhileFetching===void 0?this.#T(t,"fetch"):a||(this.#t[e]=p.__staleWhileFetching)),w)return i.status&&p.__staleWhileFetching!==void 0&&(i.status.returnedStale=!0),p.__staleWhileFetching;if(p.__returned===p)throw d},u=(d,S)=>{let a=this.#R?.(t,n,r);a&&a instanceof Promise&&a.then(w=>d(w===void 0?void 0:w),S),h.signal.addEventListener("abort",()=>{(!i.ignoreFetchAbort||i.allowStaleOnFetchAbort)&&(d(void 0),i.allowStaleOnFetchAbort&&(d=w=>g(w,!0)))})};i.status&&(i.status.fetchDispatched=!0);let c=new Promise(u).then(g,b),F=Object.assign(c,{__abortController:h,__staleWhileFetching:n,__returned:void 0});return e===void 0?(this.set(t,F,{...r.options,status:void 0}),e=this.#s.get(t)):this.#t[e]=F,F}#e(t){if(!this.#E)return!1;let e=t;return!!e&&e instanceof Promise&&e.hasOwnProperty("__staleWhileFetching")&&e.__abortController instanceof D}async fetch(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,ttl:h=this.ttl,noDisposeOnSet:o=this.noDisposeOnSet,size:r=0,sizeCalculation:g=this.sizeCalculation,noUpdateTTL:b=this.noUpdateTTL,noDeleteOnFetchRejection:f=this.noDeleteOnFetchRejection,allowStaleOnFetchRejection:u=this.allowStaleOnFetchRejection,ignoreFetchAbort:c=this.ignoreFetchAbort,allowStaleOnFetchAbort:F=this.allowStaleOnFetchAbort,context:d,forceRefresh:S=!1,status:a,signal:w}=e;if(!this.#E)return a&&(a.fetch="get"),this.get(t,{allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,status:a});let m={allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,ttl:h,noDisposeOnSet:o,size:r,sizeCalculation:g,noUpdateTTL:b,noDeleteOnFetchRejection:f,allowStaleOnFetchRejection:u,allowStaleOnFetchAbort:F,ignoreFetchAbort:c,status:a,signal:w},p=this.#s.get(t);if(p===void 0){a&&(a.fetch="miss");let _=this.#x(t,p,m,d);return _.__returned=_}else{let _=this.#t[p];if(this.#e(_)){let M=i&&_.__staleWhileFetching!==void 0;return a&&(a.fetch="inflight",M&&(a.returnedStale=!0)),M?_.__staleWhileFetching:_.__returned=_}let z=this.#d(p);if(!S&&!z)return a&&(a.fetch="hit"),this.#C(p),s&&this.#v(p),a&&this.#O(a,p),_;let y=this.#x(t,p,m,d),L=y.__staleWhileFetching!==void 0&&i;return a&&(a.fetch=z?"stale":"refresh",L&&z&&(a.returnedStale=!0)),L?y.__staleWhileFetching:y.__returned=y}}async forceFetch(t,e={}){let i=await this.fetch(t,e);if(i===void 0)throw new Error("fetch() returned undefined");return i}memo(t,e={}){let i=this.#W;if(!i)throw new Error("no memoMethod provided to constructor");let{context:s,forceRefresh:n,...h}=e,o=this.get(t,h);if(!n&&o!==void 0)return o;let r=i(t,o,{options:h,context:s});return this.set(t,r,h),r}get(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,status:h}=e,o=this.#s.get(t);if(o!==void 0){let r=this.#t[o],g=this.#e(r);return h&&this.#O(h,o),this.#d(o)?(h&&(h.get="stale"),g?(h&&i&&r.__staleWhileFetching!==void 0&&(h.returnedStale=!0),i?r.__staleWhileFetching:void 0):(n||this.#T(t,"expire"),h&&i&&(h.returnedStale=!0),i?r:void 0)):(h&&(h.get="hit"),g?r.__staleWhileFetching:(this.#C(o),s&&this.#v(o),r))}else h&&(h.get="miss")}#I(t,e){this.#c[e]=t,this.#l[t]=e}#C(t){t!==this.#h&&(t===this.#o?this.#o=this.#l[t]:this.#I(this.#c[t],this.#l[t]),this.#I(this.#h,t),this.#h=t)}delete(t){return this.#T(t,"delete")}#T(t,e){let i=!1;if(this.#n!==0){let s=this.#s.get(t);if(s!==void 0)if(i=!0,this.#n===1)this.#N(e);else{this.#z(s);let n=this.#t[s];if(this.#e(n)?n.__abortController.abort(new Error("deleted")):(this.#y||this.#a)&&(this.#y&&this.#p?.(n,t,e),this.#a&&this.#r?.push([n,t,e])),this.#s.delete(t),this.#i[s]=void 0,this.#t[s]=void 0,s===this.#h)this.#h=this.#c[s];else if(s===this.#o)this.#o=this.#l[s];else{let h=this.#c[s];this.#l[h]=this.#l[s];let o=this.#l[s];this.#c[o]=this.#c[s]}this.#n--,this.#_.push(s)}}if(this.#a&&this.#r?.length){let s=this.#r,n;for(;n=s?.shift();)this.#w?.(...n)}return i}clear(){return this.#N("delete")}#N(t){for(let e of this.#F({allowStale:!0})){let i=this.#t[e];if(this.#e(i))i.__abortController.abort(new Error("deleted"));else{let s=this.#i[e];this.#y&&this.#p?.(i,s,t),this.#a&&this.#r?.push([i,s,t])}}if(this.#s.clear(),this.#t.fill(void 0),this.#i.fill(void 0),this.#u&&this.#m&&(this.#u.fill(0),this.#m.fill(0)),this.#b&&this.#b.fill(0),this.#o=0,this.#h=0,this.#_.length=0,this.#S=0,this.#n=0,this.#a&&this.#r){let e=this.#r,i;for(;i=e?.shift();)this.#w?.(...i)}}};exports.LRUCache=C;
 //# sourceMappingURL=index.min.js.map

dist/esm/index.d.ts

@@ -60,4 +60,14 @@ /**
      * to the {@link Disposer} methods.
+     *
+     * - `evict`: The item was evicted because it is the least recently used,
+     *   and the cache is full.
+     * - `set`: A new value was set, overwriting the old value being disposed.
+     * - `delete`: The item was explicitly deleted, either by calling
+     *   {@link LRUCache#delete}, {@link LRUCache#clear}, or
+     *   {@link LRUCache#set} with an undefined value.
+     * - `expire`: The item was removed due to exceeding its TTL.
+     * - `fetch`: A {@link OptionsBase#fetchMethod} operation returned
+     *   `undefined` or was aborted, causing the item to be deleted.
      */
-    type DisposeReason = 'evict' | 'set' | 'delete';
+    type DisposeReason = 'evict' | 'set' | 'delete' | 'expire' | 'fetch';
     /**
@@ -88,4 +98,10 @@ * A method called upon item removal, passed as the
     /**
-     * Status object that may be passed to {@link LRUCache#fetch},
-     * {@link LRUCache#get}, {@link LRUCache#set}, and {@link LRUCache#has}.
+     * 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
+     * {@link LRUCache#fetch}, {@link LRUCache#get}, {@link LRUCache#set},
+     * {@link LRUCache#memo}, and {@link LRUCache#has} methods.
+     *
+     * The `status` option should be a plain JavaScript object. The following
+     * fields will be set on it appropriately, depending on the situation.
      */
@@ -150,3 +166,4 @@ interface Status<V> {
          * - inflight: there is another fetch() for this key which is in process
-         * - get: there is no fetchMethod, so {@link LRUCache#get} was called.
+         * - get: there is no {@link OptionsBase.fetchMethod}, so
+         *   {@link LRUCache#get} was called.
          * - miss: the item is not in cache, and will be fetched.
@@ -260,3 +277,64 @@ * - hit: the item is in the cache, and was resolved immediately.
     }
+    interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
+        /**
+         * Set to true to force a re-load of the existing data, even if it
+         * is not yet stale.
+         */
+        forceRefresh?: boolean;
+        /**
+         * Context provided to the {@link OptionsBase.memoMethod} as
+         * the {@link MemoizerOptions.context} param.
+         *
+         * If the FC type is specified as unknown (the default),
+         * undefined or void, then this is optional.  Otherwise, it will
+         * be required.
+         */
+        context?: FC;
+        status?: Status<V>;
+    }
     /**
+     * Options provided to {@link LRUCache#memo} when the FC type is something
+     * other than `unknown`, `undefined`, or `void`
+     */
+    interface MemoOptionsWithContext<K, V, FC> extends MemoOptions<K, V, FC> {
+        context: FC;
+    }
+    /**
+     * Options provided to {@link LRUCache#memo} when the FC type is
+     * `undefined` or `void`
+     */
+    interface MemoOptionsNoContext<K, V> extends MemoOptions<K, V, undefined> {
+        context?: undefined;
+    }
+    /**
+     * Options provided to the
+     * {@link OptionsBase.memoMethod} function.
+     */
+    interface MemoizerOptions<K, V, FC = unknown> {
+        options: MemoizerMemoOptions<K, V, FC>;
+        /**
+         * Object provided in the {@link MemoOptions.context} option to
+         * {@link LRUCache#memo}
+         */
+        context: FC;
+    }
+    /**
+     * options which override the options set in the LRUCache constructor
+     * when calling {@link LRUCache#memo}.
+     *
+     * This is the union of {@link GetOptions} and {@link SetOptions}, plus
+     * {@link MemoOptions.forceRefresh}, and
+     * {@link MemoerOptions.context}
+     *
+     * Any of these may be modified in the {@link OptionsBase.memoMethod}
+     * function, but the {@link GetOptions} fields will of course have no
+     * effect, as the {@link LRUCache#get} call already happened by the time
+     * the memoMethod is called.
+     */
+    interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {
+        status?: Status<V>;
+        size?: Size;
+        start?: Milliseconds;
+    }
+    /**
      * Options that may be passed to the {@link LRUCache#has} method.
@@ -304,2 +382,6 @@ */
     /**
+     * the type signature for the {@link OptionsBase.memoMethod} option.
+     */
+    type Memoizer<K, V, FC = unknown> = (key: K, staleValue: V | undefined, options: MemoizerOptions<K, V, FC>) => V;
+    /**
      * Options which may be passed to the {@link LRUCache} constructor.
@@ -318,2 +400,10 @@ *
      * unbounded storage.
+     *
+     * All options are also available on the {@link LRUCache} instance, making
+     * it safe to pass an LRUCache instance as the options argumemnt to
+     * make another empty cache of the same type.
+     *
+     * Some options are marked as read-only, because changing them after
+     * instantiation is not safe. Changing any of the other options will of
+     * course only have an effect on subsequent method calls.
      */
@@ -332,2 +422,5 @@ interface OptionsBase<K, V, FC> {
          * set.
+         *
+         * **It is strongly recommended to set a `max` to prevent unbounded growth
+         * of the cache.**
          */
@@ -337,5 +430,10 @@ max?: Count;
          * Max 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.
+         * 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, unless {@link OptionsBase.ttlAutopurge} is
+         * set.
          *
+         * If set to `0` (the default value), then that means "do not track
+         * TTL", not "expire immediately".
+         *
          * Also, as this cache is optimized for LRU/MRU operations, some of
@@ -345,5 +443,21 @@ * the staleness/TTL checks will reduce performance, as they will incur
          *
-         * Must be an integer number of ms. If set to 0, this indicates "no TTL"
+         * 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.
          *
-         * @default 0
+         * Optional, but must be a non-negative 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.**
+         *
+         * 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.
+         * (The TypeScript definitions will also discourage this.)
          */
@@ -368,7 +482,8 @@ ttl?: Milliseconds;
          * 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 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 {@link OptionsBase.allowStale} is a bit
@@ -378,19 +493,23 @@ * pointless, as stale items will be deleted almost as soon as they
          *
-         * @default false
+         * Use with caution!
          */
         ttlAutopurge?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#get}, renewing their TTL
+         * 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
+         * {@link LRUCache#get}, causing it to not expire. (It can still fall out
+         * of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
          *
-         * @default false
+         * This may be overridden by passing an options object to `cache.get()`.
          */
         updateAgeOnGet?: boolean;
         /**
-         * Update the age of items on {@link LRUCache#has}, renewing their TTL
+         * 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 {@link LRUCache#has}, causing it to not expire. (It can
+         * still fall out of cache based on recency of use, of course.)
          *
          * Has no effect if {@link OptionsBase.ttl} is not set.
-         *
-         * @default false
          */
@@ -401,14 +520,49 @@ updateAgeOnHas?: boolean;
          * stale data, if available.
+         *
+         * By default, if you set `ttl`, stale items will only be deleted from the
+         * cache when you `get(key)`. That is, it's not preemptively pruning items,
+         * unless {@link OptionsBase.ttlAutopurge} is set.
+         *
+         * 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 suppress this behavior by setting
+         * {@link OptionsBase.noDeleteOnStaleGet}, either in the constructor, or in
+         * the options provided to {@link LRUCache#get}.
+         *
+         * This may be overridden by passing an options object to `cache.get()`.
+         * The `cache.has()` method will always return `false` for stale items.
+         *
+         * Only relevant if a ttl is set.
          */
         allowStale?: boolean;
         /**
-         * 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 it is *NOT* safe to re-add them.
+         * Function that is called on items when they are dropped from the
+         * cache, as `dispose(value, key, reason)`.
          *
-         * Use {@link 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.
+         * 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.
+         *
+         * 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
+         * - `expire` Item expired its TTL
+         * - `fetch` Item was deleted due to a failed or aborted fetch, or a
+         *   fetchMethod returning `undefined.
+         * - `delete` Item was removed by explicit `cache.delete(key)`,
+         *   `cache.clear()`, or `cache.set(key, undefined)`.
          */
@@ -419,2 +573,3 @@ dispose?: Disposer<K, V>;
          * 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.
@@ -429,23 +584,40 @@ * However, note that it is *very* easy to inadvertently create infinite
          * still accessible within the cache.
+         *
          * This may be overridden by passing an options object to
          * {@link LRUCache#set}.
+         *
+         * Only relevant if `dispose` or `disposeAfter` are set.
          */
         noDisposeOnSet?: boolean;
         /**
-         * 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.
+         * 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.
          *
          * Has no effect if a {@link OptionsBase.ttl} is not set.
+         *
+         * May be passed as an option to {@link LRUCache#set}.
          */
         noUpdateTTL?: boolean;
         /**
-         * If 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!
+         * 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.**
+         *
          * Note also that size tracking can negatively impact performance,
@@ -459,4 +631,11 @@ * though for most cases, only minimally.
          * If a larger item is passed to {@link LRUCache#set} or returned by a
-         * {@link OptionsBase.fetchMethod}, then it will not be stored in the
-         * cache.
+         * {@link OptionsBase.fetchMethod} or {@link OptionsBase.memoMethod}, then
+         * it will not be stored in the cache.
+         *
+         * Attempting to add an item whose calculated size is greater than
+         * this amount will not cache the item or evict any old items, but
+         * WILL delete an existing value if one is already present.
+         *
+         * Optional, must be a positive integer if provided. Defaults to
+         * the value of `maxSize` if provided.
          */
@@ -467,2 +646,4 @@ maxEntrySize?: Size;
          *
+         * Requires {@link OptionsBase.maxSize} to be set.
+         *
          * If not provided, and {@link OptionsBase.maxSize} or
@@ -476,5 +657,38 @@ * {@link OptionsBase.maxEntrySize} are set, then all
          * Method that provides the implementation for {@link LRUCache#fetch}
+         *
+         * ```ts
+         * fetchMethod(key, staleValue, { signal, options, context })
+         * ```
+         *
+         * If `fetchMethod` is not provided, then `cache.fetch(key)` is equivalent
+         * to `Promise.resolve(cache.get(key))`.
+         *
+         * 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
+         * {@link OptionsBase.noDeleteOnFetchRejection} and
+         * {@link OptionsBase.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`.
          */
         fetchMethod?: Fetcher<K, V, FC>;
         /**
+         * Method that provides the implementation for {@link LRUCache#memo}
+         */
+        memoMethod?: Memoizer<K, V, FC>;
+        /**
          * Set to true to suppress the deletion of stale data when a
@@ -490,2 +704,14 @@ * {@link OptionsBase.fetchMethod} returns a rejected promise.
          * unless {@link OptionsBase.allowStale} is true.
+         *
+         * 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 this option 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()`.
+         *
+         * Only relevant if a ttl is used.
          */
@@ -499,4 +725,13 @@ noDeleteOnStaleGet?: boolean;
          * This differs from using {@link OptionsBase.allowStale} in that stale
-         * data will ONLY be returned in the case that the
-         * {@link LRUCache#fetch} fails, not any other times.
+         * data will ONLY be returned in the case that the {@link LRUCache#fetch}
+         * fails, not any other times.
+         *
+         * 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`.
          */
@@ -506,4 +741,5 @@ allowStaleOnFetchRejection?: boolean;
          * Set to true to return a stale value from the cache when the
-         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches an `'abort'`
-         * event, whether user-triggered, or due to internal cache behavior.
+         * `AbortSignal` passed to the {@link OptionsBase.fetchMethod} dispatches
+         * an `'abort'` event, whether user-triggered, or due to internal cache
+         * behavior.
          *
@@ -544,5 +780,5 @@ * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying
          *
-         * When used on its own, this means aborted {@link LRUCache#fetch} calls are not
-         * immediately resolved or rejected when they are aborted, and instead
-         * take the full time to await.
+         * When used on its own, this means aborted {@link LRUCache#fetch} calls
+         * are not immediately resolved or rejected when they are aborted, and
+         * instead take the full time to await.
          *
@@ -556,2 +792,22 @@ * When used with {@link OptionsBase.allowStaleOnFetchAbort}, aborted
          *
+         * For example:
+         *
+         * ```ts
+         * 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
@@ -594,7 +850,13 @@ * emitted on the `AbortSignal` object_, so may result in invalid results
  *
- * All properties from the options object (with the exception of
- * {@link OptionsBase.max} and {@link OptionsBase.maxSize}) are added as
- * normal public members. (`max` and `maxBase` are read-only getters.)
- * Changing any of these will alter the defaults for subsequent method calls,
- * but is otherwise safe.
+ * The `K` and `V` types define the key and value types, respectively. The
+ * optional `FC` type defines the type of the `context` object passed to
+ * `cache.fetch()` and `cache.memo()`.
+ *
+ * Keys and values **must not** be `null` or `undefined`.
+ *
+ * All properties from the options object (with the exception of `max`,
+ * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are
+ * added as normal public members. (The listed options are read-only getters.)
+ *
+ * Changing any of these will alter the defaults for subsequent method calls.
  */
@@ -715,2 +977,3 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> implements Map<K, V> {
     get fetchMethod(): LRUCache.Fetcher<K, V, FC> | undefined;
+    get memoMethod(): LRUCache.Memoizer<K, V, FC> | undefined;
     /**
@@ -726,3 +989,4 @@ * {@link LRUCache.OptionsBase.dispose} (read-only)
     /**
-     * Return the remaining TTL time for a given entry 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.
      */
@@ -772,4 +1036,5 @@ getRemainingTTL(key: K): number;
     /**
-     * A String value that is used in the creation of the default string description of an object.
-     * Called by the built-in method Object.prototype.toString.
+     * A String value that is used in the creation of the default string
+     * description of an object. Called by the built-in method
+     * `Object.prototype.toString`.
      */
@@ -779,10 +1044,15 @@ [Symbol.toStringTag]: string;
      * Find a value for which the supplied fn method returns a truthy value,
-     * similar to Array.find().  fn is called as fn(value, key, cache).
+     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.
      */
     find(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => boolean, getOptions?: LRUCache.GetOptions<K, V, FC>): V | undefined;
     /**
-     * Call the supplied function on each item in the cache, in order from
-     * most recently used to least recently used.  fn is called as
-     * fn(value, key, cache).  Does not update age or recenty of use.
-     * Does not iterate over stale values.
+     * Call the supplied function on each item in the cache, in order from most
+     * recently used to least recently used.
+     *
+     * `fn` is called as `fn(value, key, cache)`.
+     *
+     * If `thisp` is provided, function will be called in the `this`-context of
+     * the provided object, or the cache if no `thisp` object is provided.
+     *
+     * Does not update age or recenty of use, or iterate over stale values.
      */
@@ -802,5 +1072,11 @@ forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
      * Get the extended info about a given entry, to get its value, size, and
-     * TTL info simultaneously. Like {@link LRUCache#dump}, but just for a
-     * single key. Always returns stale values, if their info is found in the
-     * cache, so be sure to check for expired TTLs if relevant.
+     * TTL info simultaneously. Returns `undefined` if the key is not present.
+     *
+     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive
+     * serialization, the `start` value is always the current timestamp, and the
+     * `ttl` is a calculated remaining time to live (negative if expired).
+     *
+     * Always returns stale values, if their info is found in the cache, so be
+     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})
+     * if relevant.
      */
@@ -810,3 +1086,12 @@ info(key: K): LRUCache.Entry<V> | undefined;
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRLUCache#load}.
+     *
+     * The `start` fields are calculated relative to a portable `Date.now()`
+     * timestamp, even if `performance.now()` is available.
+     *
+     * Stale entries are always included in the `dump`, even if
+     * {@link LRUCache.OptionsBase.allowStale} is false.
+     *
+     * Note: this returns an actual array, not a generator, so it can be more
+     * easily passed around.
      */
@@ -816,4 +1101,8 @@ dump(): [K, LRUCache.Entry<V>][];
      * 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.
+     *
+     * The shape of the resulting cache may be different if the same options are
+     * not used in both caches.
+     *
+     * The `start` fields are assumed to be calculated relative to a portable
+     * `Date.now()` timestamp, even if `performance.now()` is available.
      */
@@ -826,2 +1115,26 @@ load(arr: [K, LRUCache.Entry<V>][]): void;
      * {@link LRUCache#delete}
+     *
+     * Fields on the {@link LRUCache.SetOptions} options param will override
+     * their corresponding values in the constructor options for the scope
+     * of this single `set()` operation.
+     *
+     * 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.
+     *
+     * If the value is `undefined`, then this is an alias for
+     * `cache.delete(key)`. `undefined` is never stored in the cache.
      */
@@ -839,2 +1152,10 @@ set(k: K, v: V | BackgroundFetch<V> | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
      *
+     * Check if a key is in the cache, without updating the recency of
+     * use. Age is updated if {@link LRUCache.OptionsBase.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.
+     *
      * Will not update item age unless
@@ -856,2 +1177,21 @@ * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
      *
+     * 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 also
+     * 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.
+     *
      * If multiple fetches for the same key are issued, then they will all be
@@ -869,2 +1209,51 @@ * coalesced into a single call to fetchMethod.
      * may not be worth the costs for this edge case.
+     *
+     * If {@link LRUCache.OptionsBase.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.
+     *
+     * **Setting `context`**
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the {@link LRUCache} constructor, then all
+     * calls to `cache.fetch()` _must_ provide a `context` option. If
+     * set to `undefined` or `void`, then calls to fetch _must not_
+     * provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that
+     * might be relevant in the course of fetching the data. It is only
+     * relevant for the course of a single `fetch()` operation, and
+     * discarded afterwards.
+     *
+     * **Note: `fetch()` calls are inflight-unique**
+     *
+     * If you call `fetch()` multiple times with the same key value,
+     * then every call after the first will resolve on the same
+     * promise<sup>1</sup>,
+     * _even if they have different settings that would otherwise change
+     * the behavior of the fetch_, such as `noDeleteOnFetchRejection`
+     * or `ignoreFetchAbort`.
+     *
+     * In most cases, this is not a problem (in fact, only fetching
+     * something once is what you probably want, if you're caching in
+     * the first place). If you are changing the fetch() options
+     * dramatically between runs, there's a good chance that you might
+     * be trying to fit divergent semantics into a single object, and
+     * would be better off with multiple cache instances.
+     *
+     * **1**: Ie, they're not the "same Promise", but they resolve at
+     * the same time, because they're both waiting on the same
+     * underlying fetchMethod response.
      */
@@ -874,2 +1263,33 @@ fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<undefined | V>;
     /**
+     * In some cases, `cache.fetch()` may resolve to `undefined`, either because
+     * a {@link LRUCache.OptionsBase#fetchMethod} was not provided (turning
+     * `cache.fetch(k)` into just an async wrapper around `cache.get(k)`) or
+     * because `ignoreFetchAbort` was specified (either to the constructor or
+     * in the {@link LRUCache.FetchOptions}). Also, the
+     * {@link OptionsBase.fetchMethod} may return `undefined` or `void`, making
+     * the test even more complicated.
+     *
+     * Because inferring the cases where `undefined` might be returned are so
+     * cumbersome, but testing for `undefined` can also be annoying, this method
+     * can be used, which will reject if `this.fetch()` resolves to undefined.
+     */
+    forceFetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<V>;
+    forceFetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<V>;
+    /**
+     * If the key is found in the cache, then this is equivalent to
+     * {@link LRUCache#get}. If not, in the cache, then calculate the value using
+     * the {@link LRUCache.OptionsBase.memoMethod}, and add it to the cache.
+     *
+     * If an `FC` type is set to a type other than `unknown`, `void`, or
+     * `undefined` in the LRUCache constructor, then all calls to `cache.memo()`
+     * _must_ provide a `context` option. If set to `undefined` or `void`, then
+     * calls to memo _must not_ provide a `context` option.
+     *
+     * The `context` param allows you to provide arbitrary data that might be
+     * relevant in the course of fetching the data. It is only relevant for the
+     * course of a single `memo()` operation, and discarded afterwards.
+     */
+    memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
+    memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : never): V;
+    /**
      * Return a value from the cache. Will update the recency of the cache
@@ -883,2 +1303,3 @@ * entry found.
      * Deletes a key out of the cache.
+     *
      * Returns true if the key was deleted, false otherwise.
@@ -885,0 +1306,0 @@ */

dist/esm/index.js

@@ -130,12 +130,16 @@ /**
  *
- * All properties from the options object (with the exception of
- * {@link OptionsBase.max} and {@link OptionsBase.maxSize}) are added as
- * normal public members. (`max` and `maxBase` are read-only getters.)
- * Changing any of these will alter the defaults for subsequent method calls,
- * but is otherwise safe.
+ * The `K` and `V` types define the key and value types, respectively. The
+ * optional `FC` type defines the type of the `context` object passed to
+ * `cache.fetch()` and `cache.memo()`.
+ *
+ * Keys and values **must not** be `null` or `undefined`.
+ *
+ * All properties from the options object (with the exception of `max`,
+ * `maxSize`, `fetchMethod`, `memoMethod`, `dispose` and `disposeAfter`) are
+ * added as normal public members. (The listed options are read-only getters.)
+ *
+ * Changing any of these will alter the defaults for subsequent method calls.
  */
 export class LRUCache {
-    // properties coming in from the options of these, only max and maxSize
-    // really *need* to be protected. The rest can be modified, as they just
-    // set defaults for various methods.
+    // options that cannot be changed without disaster
     #max;
@@ -146,2 +150,3 @@ #maxSize;
     #fetchMethod;
+    #memoMethod;
     /**
@@ -292,2 +297,5 @@ * {@link LRUCache.OptionsBase.ttl}
     }
+    get memoMethod() {
+        return this.#memoMethod;
+    }
     /**
@@ -306,3 +314,3 @@ * {@link LRUCache.OptionsBase.dispose} (read-only)
     constructor(options) {
-        const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, } = options;
+        const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, } = options;
         if (max !== 0 && !isPosInt(max)) {
@@ -327,2 +335,7 @@ throw new TypeError('max option must be a nonnegative integer');
         }
+        if (memoMethod !== undefined &&
+            typeof memoMethod !== 'function') {
+            throw new TypeError('memoMethod must be a function if defined');
+        }
+        this.#memoMethod = memoMethod;
         if (fetchMethod !== undefined &&
@@ -406,3 +419,4 @@ typeof fetchMethod !== 'function') {
     /**
-     * Return the remaining TTL time for a given entry 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.
      */
@@ -423,3 +437,3 @@ getRemainingTTL(key) {
                     if (this.#isStale(index)) {
-                        this.delete(this.#keyList[index]);
+                        this.#delete(this.#keyList[index], 'expire');
                     }
@@ -681,4 +695,5 @@ }, ttl + 1);
     /**
-     * A String value that is used in the creation of the default string description of an object.
-     * Called by the built-in method Object.prototype.toString.
+     * A String value that is used in the creation of the default string
+     * description of an object. Called by the built-in method
+     * `Object.prototype.toString`.
      */
@@ -688,3 +703,3 @@ [Symbol.toStringTag] = 'LRUCache';
      * Find a value for which the supplied fn method returns a truthy value,
-     * similar to Array.find().  fn is called as fn(value, key, cache).
+     * similar to `Array.find()`. fn is called as `fn(value, key, cache)`.
      */
@@ -705,6 +720,11 @@ find(fn, getOptions = {}) {
     /**
-     * Call the supplied function on each item in the cache, in order from
-     * most recently used to least recently used.  fn is called as
-     * fn(value, key, cache).  Does not update age or recenty of use.
-     * Does not iterate over stale values.
+     * Call the supplied function on each item in the cache, in order from most
+     * recently used to least recently used.
+     *
+     * `fn` is called as `fn(value, key, cache)`.
+     *
+     * If `thisp` is provided, function will be called in the `this`-context of
+     * the provided object, or the cache if no `thisp` object is provided.
+     *
+     * Does not update age or recenty of use, or iterate over stale values.
      */
@@ -745,3 +765,3 @@ forEach(fn, thisp = this) {
             if (this.#isStale(i)) {
-                this.delete(this.#keyList[i]);
+                this.#delete(this.#keyList[i], 'expire');
                 deleted = true;
@@ -754,5 +774,11 @@ }
      * Get the extended info about a given entry, to get its value, size, and
-     * TTL info simultaneously. Like {@link LRUCache#dump}, but just for a
-     * single key. Always returns stale values, if their info is found in the
-     * cache, so be sure to check for expired TTLs if relevant.
+     * TTL info simultaneously. Returns `undefined` if the key is not present.
+     *
+     * Unlike {@link LRUCache#dump}, which is designed to be portable and survive
+     * serialization, the `start` value is always the current timestamp, and the
+     * `ttl` is a calculated remaining time to live (negative if expired).
+     *
+     * Always returns stale values, if their info is found in the cache, so be
+     * sure to check for expirations (ie, a negative {@link LRUCache.Entry#ttl})
+     * if relevant.
      */
@@ -786,3 +812,12 @@ info(key) {
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRLUCache#load}.
+     *
+     * The `start` fields are calculated relative to a portable `Date.now()`
+     * timestamp, even if `performance.now()` is available.
+     *
+     * Stale entries are always included in the `dump`, even if
+     * {@link LRUCache.OptionsBase.allowStale} is false.
+     *
+     * Note: this returns an actual array, not a generator, so it can be more
+     * easily passed around.
      */
@@ -816,4 +851,8 @@ dump() {
      * 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.
+     *
+     * The shape of the resulting cache may be different if the same options are
+     * not used in both caches.
+     *
+     * The `start` fields are assumed to be calculated relative to a portable
+     * `Date.now()` timestamp, even if `performance.now()` is available.
      */
@@ -841,2 +880,26 @@ load(arr) {
      * {@link LRUCache#delete}
+     *
+     * Fields on the {@link LRUCache.SetOptions} options param will override
+     * their corresponding values in the constructor options for the scope
+     * of this single `set()` operation.
+     *
+     * 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.
+     *
+     * If the value is `undefined`, then this is an alias for
+     * `cache.delete(key)`. `undefined` is never stored in the cache.
      */
@@ -859,3 +922,3 @@ set(k, v, setOptions = {}) {
             // have to delete, in case something is there already.
-            this.delete(k);
+            this.#delete(k, 'set');
             return this;
@@ -1012,2 +1075,10 @@ }
      *
+     * Check if a key is in the cache, without updating the recency of
+     * use. Age is updated if {@link LRUCache.OptionsBase.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.
+     *
      * Will not update item age unless
@@ -1104,3 +1175,3 @@ * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
                     else {
-                        this.delete(k);
+                        this.#delete(k, 'fetch');
                     }
@@ -1134,3 +1205,3 @@ }
                 if (del) {
-                    this.delete(k);
+                    this.#delete(k, 'fetch');
                 }
@@ -1281,2 +1352,24 @@ else if (!allowStaleAborted) {
     }
+    async forceFetch(k, fetchOptions = {}) {
+        const v = await this.fetch(k, fetchOptions);
+        if (v === undefined)
+            throw new Error('fetch() returned undefined');
+        return v;
+    }
+    memo(k, memoOptions = {}) {
+        const memoMethod = this.#memoMethod;
+        if (!memoMethod) {
+            throw new Error('no memoMethod provided to constructor');
+        }
+        const { context, forceRefresh, ...options } = memoOptions;
+        const v = this.get(k, options);
+        if (!forceRefresh && v !== undefined)
+            return v;
+        const vv = memoMethod(k, v, {
+            options,
+            context,
+        });
+        this.set(k, vv, options);
+        return vv;
+    }
     /**
@@ -1302,3 +1395,3 @@ * Return a value from the cache. Will update the recency of the cache
                     if (!noDeleteOnStaleGet) {
-                        this.delete(k);
+                        this.#delete(k, 'expire');
                     }
@@ -1366,5 +1459,9 @@ if (status && allowStale)
      * Deletes a key out of the cache.
+     *
      * Returns true if the key was deleted, false otherwise.
      */
     delete(k) {
+        return this.#delete(k, 'delete');
+    }
+    #delete(k, reason) {
         let deleted = false;
@@ -1376,3 +1473,3 @@ if (this.#size !== 0) {
                 if (this.#size === 1) {
-                    this.clear();
+                    this.#clear(reason);
                 }
@@ -1387,6 +1484,6 @@ else {
                         if (this.#hasDispose) {
-                            this.#dispose?.(v, k, 'delete');
+                            this.#dispose?.(v, k, reason);
                         }
                         if (this.#hasDisposeAfter) {
-                            this.#disposed?.push([v, k, 'delete']);
+                            this.#disposed?.push([v, k, reason]);
                         }
@@ -1427,2 +1524,5 @@ }
     clear() {
+        return this.#clear('delete');
+    }
+    #clear(reason) {
         for (const index of this.#rindexes({ allowStale: true })) {
@@ -1436,6 +1536,6 @@ const v = this.#valList[index];
                 if (this.#hasDispose) {
-                    this.#dispose?.(v, k, 'delete');
+                    this.#dispose?.(v, k, reason);
                 }
                 if (this.#hasDisposeAfter) {
-                    this.#disposed?.push([v, k, 'delete']);
+                    this.#disposed?.push([v, k, reason]);
                 }
@@ -1442,0 +1542,0 @@ }

dist/esm/index.min.js

@@ -1,2 +0,2 @@
-var G=(o,t,e)=>{if(!t.has(o))throw TypeError("Cannot "+e)};var I=(o,t,e)=>(G(o,t,"read from private field"),e?e.call(o):t.get(o)),j=(o,t,e)=>{if(t.has(o))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(o):t.set(o,e)},D=(o,t,e,i)=>(G(o,t,"write to private field"),i?i.call(o,e):t.set(o,e),e);var O=typeof performance=="object"&&performance&&typeof performance.now=="function"?performance:Date,M=new Set,L=typeof process=="object"&&process?process:{},P=(o,t,e,i)=>{typeof L.emitWarning=="function"?L.emitWarning(o,t,e,i):console.error(`[${e}] ${t}: ${o}`)},W=globalThis.AbortController,N=globalThis.AbortSignal;if(typeof W>"u"){N=class{onabort;_onabort=[];reason;aborted=!1;addEventListener(i,s){this._onabort.push(s)}},W=class{constructor(){t()}signal=new N;abort(i){if(!this.signal.aborted){this.signal.reason=i,this.signal.aborted=!0;for(let s of this.signal._onabort)s(i);this.signal.onabort?.(i)}}};let o=L.env?.LRU_CACHE_IGNORE_AC_WARNING!=="1",t=()=>{o&&(o=!1,P("AbortController is not defined. If using lru-cache in node 14, load an AbortController polyfill from the `node-abort-controller` package. A minimal polyfill is provided for use by LRUCache.fetch(), but it should not be relied upon in other contexts (eg, passing it to other APIs that use AbortController/AbortSignal might have undesirable effects). You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.","NO_ABORT_CONTROLLER","ENOTSUP",t))}}var V=o=>!M.has(o),Y=Symbol("type"),A=o=>o&&o===Math.floor(o)&&o>0&&isFinite(o),H=o=>A(o)?o<=Math.pow(2,8)?Uint8Array:o<=Math.pow(2,16)?Uint16Array:o<=Math.pow(2,32)?Uint32Array:o<=Number.MAX_SAFE_INTEGER?E:null:null,E=class extends Array{constructor(t){super(t),this.fill(0)}},v,z=class{heap;length;static create(t){let e=H(t);if(!e)return[];D(z,v,!0);let i=new z(t,e);return D(z,v,!1),i}constructor(t,e){if(!I(z,v))throw new TypeError("instantiate Stack using Stack.create(n)");this.heap=new e(t),this.length=0}push(t){this.heap[this.length++]=t}pop(){return this.heap[--this.length]}},C=z;v=new WeakMap,j(C,v,!1);var R=class{#g;#f;#p;#w;#C;ttl;ttlResolution;ttlAutopurge;updateAgeOnGet;updateAgeOnHas;allowStale;noDisposeOnSet;noUpdateTTL;maxEntrySize;sizeCalculation;noDeleteOnFetchRejection;noDeleteOnStaleGet;allowStaleOnFetchAbort;allowStaleOnFetchRejection;ignoreFetchAbort;#n;#S;#s;#i;#t;#l;#c;#o;#h;#_;#r;#b;#y;#u;#m;#O;#a;static unsafeExposeInternals(t){return{starts:t.#y,ttls:t.#u,sizes:t.#b,keyMap:t.#s,keyList:t.#i,valList:t.#t,next:t.#l,prev:t.#c,get head(){return t.#o},get tail(){return t.#h},free:t.#_,isBackgroundFetch:e=>t.#e(e),backgroundFetch:(e,i,s,n)=>t.#D(e,i,s,n),moveToTail:e=>t.#v(e),indexes:e=>t.#A(e),rindexes:e=>t.#F(e),isStale:e=>t.#d(e)}}get max(){return this.#g}get maxSize(){return this.#f}get calculatedSize(){return this.#S}get size(){return this.#n}get fetchMethod(){return this.#C}get dispose(){return this.#p}get disposeAfter(){return this.#w}constructor(t){let{max:e=0,ttl:i,ttlResolution:s=1,ttlAutopurge:n,updateAgeOnGet:h,updateAgeOnHas:l,allowStale:r,dispose:g,disposeAfter:b,noDisposeOnSet:f,noUpdateTTL:u,maxSize:c=0,maxEntrySize:F=0,sizeCalculation:d,fetchMethod:S,noDeleteOnFetchRejection:a,noDeleteOnStaleGet:w,allowStaleOnFetchRejection:y,allowStaleOnFetchAbort:p,ignoreFetchAbort:_}=t;if(e!==0&&!A(e))throw new TypeError("max option must be a nonnegative integer");let T=e?H(e):Array;if(!T)throw new Error("invalid max value: "+e);if(this.#g=e,this.#f=c,this.maxEntrySize=F||this.#f,this.sizeCalculation=d,this.sizeCalculation){if(!this.#f&&!this.maxEntrySize)throw new TypeError("cannot set sizeCalculation without setting maxSize or maxEntrySize");if(typeof this.sizeCalculation!="function")throw new TypeError("sizeCalculation set to non-function")}if(S!==void 0&&typeof S!="function")throw new TypeError("fetchMethod must be a function if specified");if(this.#C=S,this.#O=!!S,this.#s=new Map,this.#i=new Array(e).fill(void 0),this.#t=new Array(e).fill(void 0),this.#l=new T(e),this.#c=new T(e),this.#o=0,this.#h=0,this.#_=C.create(e),this.#n=0,this.#S=0,typeof g=="function"&&(this.#p=g),typeof b=="function"?(this.#w=b,this.#r=[]):(this.#w=void 0,this.#r=void 0),this.#m=!!this.#p,this.#a=!!this.#w,this.noDisposeOnSet=!!f,this.noUpdateTTL=!!u,this.noDeleteOnFetchRejection=!!a,this.allowStaleOnFetchRejection=!!y,this.allowStaleOnFetchAbort=!!p,this.ignoreFetchAbort=!!_,this.maxEntrySize!==0){if(this.#f!==0&&!A(this.#f))throw new TypeError("maxSize must be a positive integer if specified");if(!A(this.maxEntrySize))throw new TypeError("maxEntrySize must be a positive integer if specified");this.#j()}if(this.allowStale=!!r,this.noDeleteOnStaleGet=!!w,this.updateAgeOnGet=!!h,this.updateAgeOnHas=!!l,this.ttlResolution=A(s)||s===0?s:1,this.ttlAutopurge=!!n,this.ttl=i||0,this.ttl){if(!A(this.ttl))throw new TypeError("ttl must be a positive integer if specified");this.#L()}if(this.#g===0&&this.ttl===0&&this.#f===0)throw new TypeError("At least one of max, maxSize, or ttl is required");if(!this.ttlAutopurge&&!this.#g&&!this.#f){let m="LRU_CACHE_UNBOUNDED";V(m)&&(M.add(m),P("TTL caching without ttlAutopurge, max, or maxSize can result in unbounded memory consumption.","UnboundedCacheWarning",m,R))}}getRemainingTTL(t){return this.#s.has(t)?1/0:0}#L(){let t=new E(this.#g),e=new E(this.#g);this.#u=t,this.#y=e,this.#x=(n,h,l=O.now())=>{if(e[n]=h!==0?l:0,t[n]=h,h!==0&&this.ttlAutopurge){let r=setTimeout(()=>{this.#d(n)&&this.delete(this.#i[n])},h+1);r.unref&&r.unref()}},this.#z=n=>{e[n]=t[n]!==0?O.now():0},this.#T=(n,h)=>{if(t[h]){let l=t[h],r=e[h];if(!l||!r)return;n.ttl=l,n.start=r,n.now=i||s();let g=n.now-r;n.remainingTTL=l-g}};let i=0,s=()=>{let n=O.now();if(this.ttlResolution>0){i=n;let h=setTimeout(()=>i=0,this.ttlResolution);h.unref&&h.unref()}return n};this.getRemainingTTL=n=>{let h=this.#s.get(n);if(h===void 0)return 0;let l=t[h],r=e[h];if(!l||!r)return 1/0;let g=(i||s())-r;return l-g},this.#d=n=>{let h=e[n],l=t[n];return!!l&&!!h&&(i||s())-h>l}}#z=()=>{};#T=()=>{};#x=()=>{};#d=()=>!1;#j(){let t=new E(this.#g);this.#S=0,this.#b=t,this.#E=e=>{this.#S-=t[e],t[e]=0},this.#U=(e,i,s,n)=>{if(this.#e(i))return 0;if(!A(s))if(n){if(typeof n!="function")throw new TypeError("sizeCalculation must be a function");if(s=n(i,e),!A(s))throw new TypeError("sizeCalculation return invalid (expect positive integer)")}else throw new TypeError("invalid size value (must be positive integer). When maxSize or maxEntrySize is used, sizeCalculation or size must be set.");return s},this.#W=(e,i,s)=>{if(t[e]=i,this.#f){let n=this.#f-t[e];for(;this.#S>n;)this.#R(!0)}this.#S+=t[e],s&&(s.entrySize=i,s.totalCalculatedSize=this.#S)}}#E=t=>{};#W=(t,e,i)=>{};#U=(t,e,i,s)=>{if(i||s)throw new TypeError("cannot set size without setting maxSize or maxEntrySize on cache");return 0};*#A({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#h;!(!this.#G(e)||((t||!this.#d(e))&&(yield e),e===this.#o));)e=this.#c[e]}*#F({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#o;!(!this.#G(e)||((t||!this.#d(e))&&(yield e),e===this.#h));)e=this.#l[e]}#G(t){return t!==void 0&&this.#s.get(this.#i[t])===t}*entries(){for(let t of this.#A())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*rentries(){for(let t of this.#F())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*keys(){for(let t of this.#A()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*rkeys(){for(let t of this.#F()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*values(){for(let t of this.#A())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}*rvalues(){for(let t of this.#F())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}[Symbol.iterator](){return this.entries()}[Symbol.toStringTag]="LRUCache";find(t,e={}){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;if(n!==void 0&&t(n,this.#i[i],this))return this.get(this.#i[i],e)}}forEach(t,e=this){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}rforEach(t,e=this){for(let i of this.#F()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}purgeStale(){let t=!1;for(let e of this.#F({allowStale:!0}))this.#d(e)&&(this.delete(this.#i[e]),t=!0);return t}info(t){let e=this.#s.get(t);if(e===void 0)return;let i=this.#t[e],s=this.#e(i)?i.__staleWhileFetching:i;if(s===void 0)return;let n={value:s};if(this.#u&&this.#y){let h=this.#u[e],l=this.#y[e];if(h&&l){let r=h-(O.now()-l);n.ttl=r,n.start=Date.now()}}return this.#b&&(n.size=this.#b[e]),n}dump(){let t=[];for(let e of this.#A({allowStale:!0})){let i=this.#i[e],s=this.#t[e],n=this.#e(s)?s.__staleWhileFetching:s;if(n===void 0||i===void 0)continue;let h={value:n};if(this.#u&&this.#y){h.ttl=this.#u[e];let l=O.now()-this.#y[e];h.start=Math.floor(Date.now()-l)}this.#b&&(h.size=this.#b[e]),t.unshift([i,h])}return t}load(t){this.clear();for(let[e,i]of t){if(i.start){let s=Date.now()-i.start;i.start=O.now()-s}this.set(e,i.value,i)}}set(t,e,i={}){if(e===void 0)return this.delete(t),this;let{ttl:s=this.ttl,start:n,noDisposeOnSet:h=this.noDisposeOnSet,sizeCalculation:l=this.sizeCalculation,status:r}=i,{noUpdateTTL:g=this.noUpdateTTL}=i,b=this.#U(t,e,i.size||0,l);if(this.maxEntrySize&&b>this.maxEntrySize)return r&&(r.set="miss",r.maxEntrySizeExceeded=!0),this.delete(t),this;let f=this.#n===0?void 0:this.#s.get(t);if(f===void 0)f=this.#n===0?this.#h:this.#_.length!==0?this.#_.pop():this.#n===this.#g?this.#R(!1):this.#n,this.#i[f]=t,this.#t[f]=e,this.#s.set(t,f),this.#l[this.#h]=f,this.#c[f]=this.#h,this.#h=f,this.#n++,this.#W(f,b,r),r&&(r.set="add"),g=!1;else{this.#v(f);let u=this.#t[f];if(e!==u){if(this.#O&&this.#e(u)){u.__abortController.abort(new Error("replaced"));let{__staleWhileFetching:c}=u;c!==void 0&&!h&&(this.#m&&this.#p?.(c,t,"set"),this.#a&&this.#r?.push([c,t,"set"]))}else h||(this.#m&&this.#p?.(u,t,"set"),this.#a&&this.#r?.push([u,t,"set"]));if(this.#E(f),this.#W(f,b,r),this.#t[f]=e,r){r.set="replace";let c=u&&this.#e(u)?u.__staleWhileFetching:u;c!==void 0&&(r.oldValue=c)}}else r&&(r.set="update")}if(s!==0&&!this.#u&&this.#L(),this.#u&&(g||this.#x(f,s,n),r&&this.#T(r,f)),!h&&this.#a&&this.#r){let u=this.#r,c;for(;c=u?.shift();)this.#w?.(...c)}return this}pop(){try{for(;this.#n;){let t=this.#t[this.#o];if(this.#R(!0),this.#e(t)){if(t.__staleWhileFetching)return t.__staleWhileFetching}else if(t!==void 0)return t}}finally{if(this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}}#R(t){let e=this.#o,i=this.#i[e],s=this.#t[e];return this.#O&&this.#e(s)?s.__abortController.abort(new Error("evicted")):(this.#m||this.#a)&&(this.#m&&this.#p?.(s,i,"evict"),this.#a&&this.#r?.push([s,i,"evict"])),this.#E(e),t&&(this.#i[e]=void 0,this.#t[e]=void 0,this.#_.push(e)),this.#n===1?(this.#o=this.#h=0,this.#_.length=0):this.#o=this.#l[e],this.#s.delete(i),this.#n--,e}has(t,e={}){let{updateAgeOnHas:i=this.updateAgeOnHas,status:s}=e,n=this.#s.get(t);if(n!==void 0){let h=this.#t[n];if(this.#e(h)&&h.__staleWhileFetching===void 0)return!1;if(this.#d(n))s&&(s.has="stale",this.#T(s,n));else return i&&this.#z(n),s&&(s.has="hit",this.#T(s,n)),!0}else s&&(s.has="miss");return!1}peek(t,e={}){let{allowStale:i=this.allowStale}=e,s=this.#s.get(t);if(s===void 0||!i&&this.#d(s))return;let n=this.#t[s];return this.#e(n)?n.__staleWhileFetching:n}#D(t,e,i,s){let n=e===void 0?void 0:this.#t[e];if(this.#e(n))return n;let h=new W,{signal:l}=i;l?.addEventListener("abort",()=>h.abort(l.reason),{signal:h.signal});let r={signal:h.signal,options:i,context:s},g=(d,S=!1)=>{let{aborted:a}=h.signal,w=i.ignoreFetchAbort&&d!==void 0;if(i.status&&(a&&!S?(i.status.fetchAborted=!0,i.status.fetchError=h.signal.reason,w&&(i.status.fetchAbortIgnored=!0)):i.status.fetchResolved=!0),a&&!w&&!S)return f(h.signal.reason);let y=c;return this.#t[e]===c&&(d===void 0?y.__staleWhileFetching?this.#t[e]=y.__staleWhileFetching:this.delete(t):(i.status&&(i.status.fetchUpdated=!0),this.set(t,d,r.options))),d},b=d=>(i.status&&(i.status.fetchRejected=!0,i.status.fetchError=d),f(d)),f=d=>{let{aborted:S}=h.signal,a=S&&i.allowStaleOnFetchAbort,w=a||i.allowStaleOnFetchRejection,y=w||i.noDeleteOnFetchRejection,p=c;if(this.#t[e]===c&&(!y||p.__staleWhileFetching===void 0?this.delete(t):a||(this.#t[e]=p.__staleWhileFetching)),w)return i.status&&p.__staleWhileFetching!==void 0&&(i.status.returnedStale=!0),p.__staleWhileFetching;if(p.__returned===p)throw d},u=(d,S)=>{let a=this.#C?.(t,n,r);a&&a instanceof Promise&&a.then(w=>d(w===void 0?void 0:w),S),h.signal.addEventListener("abort",()=>{(!i.ignoreFetchAbort||i.allowStaleOnFetchAbort)&&(d(void 0),i.allowStaleOnFetchAbort&&(d=w=>g(w,!0)))})};i.status&&(i.status.fetchDispatched=!0);let c=new Promise(u).then(g,b),F=Object.assign(c,{__abortController:h,__staleWhileFetching:n,__returned:void 0});return e===void 0?(this.set(t,F,{...r.options,status:void 0}),e=this.#s.get(t)):this.#t[e]=F,F}#e(t){if(!this.#O)return!1;let e=t;return!!e&&e instanceof Promise&&e.hasOwnProperty("__staleWhileFetching")&&e.__abortController instanceof W}async fetch(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,ttl:h=this.ttl,noDisposeOnSet:l=this.noDisposeOnSet,size:r=0,sizeCalculation:g=this.sizeCalculation,noUpdateTTL:b=this.noUpdateTTL,noDeleteOnFetchRejection:f=this.noDeleteOnFetchRejection,allowStaleOnFetchRejection:u=this.allowStaleOnFetchRejection,ignoreFetchAbort:c=this.ignoreFetchAbort,allowStaleOnFetchAbort:F=this.allowStaleOnFetchAbort,context:d,forceRefresh:S=!1,status:a,signal:w}=e;if(!this.#O)return a&&(a.fetch="get"),this.get(t,{allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,status:a});let y={allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,ttl:h,noDisposeOnSet:l,size:r,sizeCalculation:g,noUpdateTTL:b,noDeleteOnFetchRejection:f,allowStaleOnFetchRejection:u,allowStaleOnFetchAbort:F,ignoreFetchAbort:c,status:a,signal:w},p=this.#s.get(t);if(p===void 0){a&&(a.fetch="miss");let _=this.#D(t,p,y,d);return _.__returned=_}else{let _=this.#t[p];if(this.#e(_)){let U=i&&_.__staleWhileFetching!==void 0;return a&&(a.fetch="inflight",U&&(a.returnedStale=!0)),U?_.__staleWhileFetching:_.__returned=_}let T=this.#d(p);if(!S&&!T)return a&&(a.fetch="hit"),this.#v(p),s&&this.#z(p),a&&this.#T(a,p),_;let m=this.#D(t,p,y,d),x=m.__staleWhileFetching!==void 0&&i;return a&&(a.fetch=T?"stale":"refresh",x&&T&&(a.returnedStale=!0)),x?m.__staleWhileFetching:m.__returned=m}}get(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,status:h}=e,l=this.#s.get(t);if(l!==void 0){let r=this.#t[l],g=this.#e(r);return h&&this.#T(h,l),this.#d(l)?(h&&(h.get="stale"),g?(h&&i&&r.__staleWhileFetching!==void 0&&(h.returnedStale=!0),i?r.__staleWhileFetching:void 0):(n||this.delete(t),h&&i&&(h.returnedStale=!0),i?r:void 0)):(h&&(h.get="hit"),g?r.__staleWhileFetching:(this.#v(l),s&&this.#z(l),r))}else h&&(h.get="miss")}#I(t,e){this.#c[e]=t,this.#l[t]=e}#v(t){t!==this.#h&&(t===this.#o?this.#o=this.#l[t]:this.#I(this.#c[t],this.#l[t]),this.#I(this.#h,t),this.#h=t)}delete(t){let e=!1;if(this.#n!==0){let i=this.#s.get(t);if(i!==void 0)if(e=!0,this.#n===1)this.clear();else{this.#E(i);let s=this.#t[i];if(this.#e(s)?s.__abortController.abort(new Error("deleted")):(this.#m||this.#a)&&(this.#m&&this.#p?.(s,t,"delete"),this.#a&&this.#r?.push([s,t,"delete"])),this.#s.delete(t),this.#i[i]=void 0,this.#t[i]=void 0,i===this.#h)this.#h=this.#c[i];else if(i===this.#o)this.#o=this.#l[i];else{let n=this.#c[i];this.#l[n]=this.#l[i];let h=this.#l[i];this.#c[h]=this.#c[i]}this.#n--,this.#_.push(i)}}if(this.#a&&this.#r?.length){let i=this.#r,s;for(;s=i?.shift();)this.#w?.(...s)}return e}clear(){for(let t of this.#F({allowStale:!0})){let e=this.#t[t];if(this.#e(e))e.__abortController.abort(new Error("deleted"));else{let i=this.#i[t];this.#m&&this.#p?.(e,i,"delete"),this.#a&&this.#r?.push([e,i,"delete"])}}if(this.#s.clear(),this.#t.fill(void 0),this.#i.fill(void 0),this.#u&&this.#y&&(this.#u.fill(0),this.#y.fill(0)),this.#b&&this.#b.fill(0),this.#o=0,this.#h=0,this.#_.length=0,this.#S=0,this.#n=0,this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}};export{R as LRUCache};
+var G=(l,t,e)=>{if(!t.has(l))throw TypeError("Cannot "+e)};var I=(l,t,e)=>(G(l,t,"read from private field"),e?e.call(l):t.get(l)),j=(l,t,e)=>{if(t.has(l))throw TypeError("Cannot add the same private member more than once");t instanceof WeakSet?t.add(l):t.set(l,e)},x=(l,t,e,i)=>(G(l,t,"write to private field"),i?i.call(l,e):t.set(l,e),e);var T=typeof performance=="object"&&performance&&typeof performance.now=="function"?performance:Date,P=new Set,M=typeof process=="object"&&process?process:{},H=(l,t,e,i)=>{typeof M.emitWarning=="function"?M.emitWarning(l,t,e,i):console.error(`[${e}] ${t}: ${l}`)},W=globalThis.AbortController,N=globalThis.AbortSignal;if(typeof W>"u"){N=class{onabort;_onabort=[];reason;aborted=!1;addEventListener(i,s){this._onabort.push(s)}},W=class{constructor(){t()}signal=new N;abort(i){if(!this.signal.aborted){this.signal.reason=i,this.signal.aborted=!0;for(let s of this.signal._onabort)s(i);this.signal.onabort?.(i)}}};let l=M.env?.LRU_CACHE_IGNORE_AC_WARNING!=="1",t=()=>{l&&(l=!1,H("AbortController is not defined. If using lru-cache in node 14, load an AbortController polyfill from the `node-abort-controller` package. A minimal polyfill is provided for use by LRUCache.fetch(), but it should not be relied upon in other contexts (eg, passing it to other APIs that use AbortController/AbortSignal might have undesirable effects). You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.","NO_ABORT_CONTROLLER","ENOTSUP",t))}}var V=l=>!P.has(l),Y=Symbol("type"),A=l=>l&&l===Math.floor(l)&&l>0&&isFinite(l),k=l=>A(l)?l<=Math.pow(2,8)?Uint8Array:l<=Math.pow(2,16)?Uint16Array:l<=Math.pow(2,32)?Uint32Array:l<=Number.MAX_SAFE_INTEGER?O:null:null,O=class extends Array{constructor(t){super(t),this.fill(0)}},z,E=class{heap;length;static create(t){let e=k(t);if(!e)return[];x(E,z,!0);let i=new E(t,e);return x(E,z,!1),i}constructor(t,e){if(!I(E,z))throw new TypeError("instantiate Stack using Stack.create(n)");this.heap=new e(t),this.length=0}push(t){this.heap[this.length++]=t}pop(){return this.heap[--this.length]}},R=E;z=new WeakMap,j(R,z,!1);var D=class{#g;#f;#p;#w;#R;#W;ttl;ttlResolution;ttlAutopurge;updateAgeOnGet;updateAgeOnHas;allowStale;noDisposeOnSet;noUpdateTTL;maxEntrySize;sizeCalculation;noDeleteOnFetchRejection;noDeleteOnStaleGet;allowStaleOnFetchAbort;allowStaleOnFetchRejection;ignoreFetchAbort;#n;#S;#s;#i;#t;#l;#c;#o;#h;#_;#r;#m;#b;#u;#y;#O;#a;static unsafeExposeInternals(t){return{starts:t.#b,ttls:t.#u,sizes:t.#m,keyMap:t.#s,keyList:t.#i,valList:t.#t,next:t.#l,prev:t.#c,get head(){return t.#o},get tail(){return t.#h},free:t.#_,isBackgroundFetch:e=>t.#e(e),backgroundFetch:(e,i,s,n)=>t.#x(e,i,s,n),moveToTail:e=>t.#C(e),indexes:e=>t.#A(e),rindexes:e=>t.#F(e),isStale:e=>t.#d(e)}}get max(){return this.#g}get maxSize(){return this.#f}get calculatedSize(){return this.#S}get size(){return this.#n}get fetchMethod(){return this.#R}get memoMethod(){return this.#W}get dispose(){return this.#p}get disposeAfter(){return this.#w}constructor(t){let{max:e=0,ttl:i,ttlResolution:s=1,ttlAutopurge:n,updateAgeOnGet:h,updateAgeOnHas:o,allowStale:r,dispose:g,disposeAfter:m,noDisposeOnSet:f,noUpdateTTL:u,maxSize:c=0,maxEntrySize:F=0,sizeCalculation:d,fetchMethod:S,memoMethod:a,noDeleteOnFetchRejection:w,noDeleteOnStaleGet:b,allowStaleOnFetchRejection:p,allowStaleOnFetchAbort:_,ignoreFetchAbort:v}=t;if(e!==0&&!A(e))throw new TypeError("max option must be a nonnegative integer");let y=e?k(e):Array;if(!y)throw new Error("invalid max value: "+e);if(this.#g=e,this.#f=c,this.maxEntrySize=F||this.#f,this.sizeCalculation=d,this.sizeCalculation){if(!this.#f&&!this.maxEntrySize)throw new TypeError("cannot set sizeCalculation without setting maxSize or maxEntrySize");if(typeof this.sizeCalculation!="function")throw new TypeError("sizeCalculation set to non-function")}if(a!==void 0&&typeof a!="function")throw new TypeError("memoMethod must be a function if defined");if(this.#W=a,S!==void 0&&typeof S!="function")throw new TypeError("fetchMethod must be a function if specified");if(this.#R=S,this.#O=!!S,this.#s=new Map,this.#i=new Array(e).fill(void 0),this.#t=new Array(e).fill(void 0),this.#l=new y(e),this.#c=new y(e),this.#o=0,this.#h=0,this.#_=R.create(e),this.#n=0,this.#S=0,typeof g=="function"&&(this.#p=g),typeof m=="function"?(this.#w=m,this.#r=[]):(this.#w=void 0,this.#r=void 0),this.#y=!!this.#p,this.#a=!!this.#w,this.noDisposeOnSet=!!f,this.noUpdateTTL=!!u,this.noDeleteOnFetchRejection=!!w,this.allowStaleOnFetchRejection=!!p,this.allowStaleOnFetchAbort=!!_,this.ignoreFetchAbort=!!v,this.maxEntrySize!==0){if(this.#f!==0&&!A(this.#f))throw new TypeError("maxSize must be a positive integer if specified");if(!A(this.maxEntrySize))throw new TypeError("maxEntrySize must be a positive integer if specified");this.#P()}if(this.allowStale=!!r,this.noDeleteOnStaleGet=!!b,this.updateAgeOnGet=!!h,this.updateAgeOnHas=!!o,this.ttlResolution=A(s)||s===0?s:1,this.ttlAutopurge=!!n,this.ttl=i||0,this.ttl){if(!A(this.ttl))throw new TypeError("ttl must be a positive integer if specified");this.#M()}if(this.#g===0&&this.ttl===0&&this.#f===0)throw new TypeError("At least one of max, maxSize, or ttl is required");if(!this.ttlAutopurge&&!this.#g&&!this.#f){let C="LRU_CACHE_UNBOUNDED";V(C)&&(P.add(C),H("TTL caching without ttlAutopurge, max, or maxSize can result in unbounded memory consumption.","UnboundedCacheWarning",C,D))}}getRemainingTTL(t){return this.#s.has(t)?1/0:0}#M(){let t=new O(this.#g),e=new O(this.#g);this.#u=t,this.#b=e,this.#U=(n,h,o=T.now())=>{if(e[n]=h!==0?o:0,t[n]=h,h!==0&&this.ttlAutopurge){let r=setTimeout(()=>{this.#d(n)&&this.#T(this.#i[n],"expire")},h+1);r.unref&&r.unref()}},this.#z=n=>{e[n]=t[n]!==0?T.now():0},this.#E=(n,h)=>{if(t[h]){let o=t[h],r=e[h];if(!o||!r)return;n.ttl=o,n.start=r,n.now=i||s();let g=n.now-r;n.remainingTTL=o-g}};let i=0,s=()=>{let n=T.now();if(this.ttlResolution>0){i=n;let h=setTimeout(()=>i=0,this.ttlResolution);h.unref&&h.unref()}return n};this.getRemainingTTL=n=>{let h=this.#s.get(n);if(h===void 0)return 0;let o=t[h],r=e[h];if(!o||!r)return 1/0;let g=(i||s())-r;return o-g},this.#d=n=>{let h=e[n],o=t[n];return!!o&&!!h&&(i||s())-h>o}}#z=()=>{};#E=()=>{};#U=()=>{};#d=()=>!1;#P(){let t=new O(this.#g);this.#S=0,this.#m=t,this.#v=e=>{this.#S-=t[e],t[e]=0},this.#G=(e,i,s,n)=>{if(this.#e(i))return 0;if(!A(s))if(n){if(typeof n!="function")throw new TypeError("sizeCalculation must be a function");if(s=n(i,e),!A(s))throw new TypeError("sizeCalculation return invalid (expect positive integer)")}else throw new TypeError("invalid size value (must be positive integer). When maxSize or maxEntrySize is used, sizeCalculation or size must be set.");return s},this.#D=(e,i,s)=>{if(t[e]=i,this.#f){let n=this.#f-t[e];for(;this.#S>n;)this.#L(!0)}this.#S+=t[e],s&&(s.entrySize=i,s.totalCalculatedSize=this.#S)}}#v=t=>{};#D=(t,e,i)=>{};#G=(t,e,i,s)=>{if(i||s)throw new TypeError("cannot set size without setting maxSize or maxEntrySize on cache");return 0};*#A({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#h;!(!this.#I(e)||((t||!this.#d(e))&&(yield e),e===this.#o));)e=this.#c[e]}*#F({allowStale:t=this.allowStale}={}){if(this.#n)for(let e=this.#o;!(!this.#I(e)||((t||!this.#d(e))&&(yield e),e===this.#h));)e=this.#l[e]}#I(t){return t!==void 0&&this.#s.get(this.#i[t])===t}*entries(){for(let t of this.#A())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*rentries(){for(let t of this.#F())this.#t[t]!==void 0&&this.#i[t]!==void 0&&!this.#e(this.#t[t])&&(yield[this.#i[t],this.#t[t]])}*keys(){for(let t of this.#A()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*rkeys(){for(let t of this.#F()){let e=this.#i[t];e!==void 0&&!this.#e(this.#t[t])&&(yield e)}}*values(){for(let t of this.#A())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}*rvalues(){for(let t of this.#F())this.#t[t]!==void 0&&!this.#e(this.#t[t])&&(yield this.#t[t])}[Symbol.iterator](){return this.entries()}[Symbol.toStringTag]="LRUCache";find(t,e={}){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;if(n!==void 0&&t(n,this.#i[i],this))return this.get(this.#i[i],e)}}forEach(t,e=this){for(let i of this.#A()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}rforEach(t,e=this){for(let i of this.#F()){let s=this.#t[i],n=this.#e(s)?s.__staleWhileFetching:s;n!==void 0&&t.call(e,n,this.#i[i],this)}}purgeStale(){let t=!1;for(let e of this.#F({allowStale:!0}))this.#d(e)&&(this.#T(this.#i[e],"expire"),t=!0);return t}info(t){let e=this.#s.get(t);if(e===void 0)return;let i=this.#t[e],s=this.#e(i)?i.__staleWhileFetching:i;if(s===void 0)return;let n={value:s};if(this.#u&&this.#b){let h=this.#u[e],o=this.#b[e];if(h&&o){let r=h-(T.now()-o);n.ttl=r,n.start=Date.now()}}return this.#m&&(n.size=this.#m[e]),n}dump(){let t=[];for(let e of this.#A({allowStale:!0})){let i=this.#i[e],s=this.#t[e],n=this.#e(s)?s.__staleWhileFetching:s;if(n===void 0||i===void 0)continue;let h={value:n};if(this.#u&&this.#b){h.ttl=this.#u[e];let o=T.now()-this.#b[e];h.start=Math.floor(Date.now()-o)}this.#m&&(h.size=this.#m[e]),t.unshift([i,h])}return t}load(t){this.clear();for(let[e,i]of t){if(i.start){let s=Date.now()-i.start;i.start=T.now()-s}this.set(e,i.value,i)}}set(t,e,i={}){if(e===void 0)return this.delete(t),this;let{ttl:s=this.ttl,start:n,noDisposeOnSet:h=this.noDisposeOnSet,sizeCalculation:o=this.sizeCalculation,status:r}=i,{noUpdateTTL:g=this.noUpdateTTL}=i,m=this.#G(t,e,i.size||0,o);if(this.maxEntrySize&&m>this.maxEntrySize)return r&&(r.set="miss",r.maxEntrySizeExceeded=!0),this.#T(t,"set"),this;let f=this.#n===0?void 0:this.#s.get(t);if(f===void 0)f=this.#n===0?this.#h:this.#_.length!==0?this.#_.pop():this.#n===this.#g?this.#L(!1):this.#n,this.#i[f]=t,this.#t[f]=e,this.#s.set(t,f),this.#l[this.#h]=f,this.#c[f]=this.#h,this.#h=f,this.#n++,this.#D(f,m,r),r&&(r.set="add"),g=!1;else{this.#C(f);let u=this.#t[f];if(e!==u){if(this.#O&&this.#e(u)){u.__abortController.abort(new Error("replaced"));let{__staleWhileFetching:c}=u;c!==void 0&&!h&&(this.#y&&this.#p?.(c,t,"set"),this.#a&&this.#r?.push([c,t,"set"]))}else h||(this.#y&&this.#p?.(u,t,"set"),this.#a&&this.#r?.push([u,t,"set"]));if(this.#v(f),this.#D(f,m,r),this.#t[f]=e,r){r.set="replace";let c=u&&this.#e(u)?u.__staleWhileFetching:u;c!==void 0&&(r.oldValue=c)}}else r&&(r.set="update")}if(s!==0&&!this.#u&&this.#M(),this.#u&&(g||this.#U(f,s,n),r&&this.#E(r,f)),!h&&this.#a&&this.#r){let u=this.#r,c;for(;c=u?.shift();)this.#w?.(...c)}return this}pop(){try{for(;this.#n;){let t=this.#t[this.#o];if(this.#L(!0),this.#e(t)){if(t.__staleWhileFetching)return t.__staleWhileFetching}else if(t!==void 0)return t}}finally{if(this.#a&&this.#r){let t=this.#r,e;for(;e=t?.shift();)this.#w?.(...e)}}}#L(t){let e=this.#o,i=this.#i[e],s=this.#t[e];return this.#O&&this.#e(s)?s.__abortController.abort(new Error("evicted")):(this.#y||this.#a)&&(this.#y&&this.#p?.(s,i,"evict"),this.#a&&this.#r?.push([s,i,"evict"])),this.#v(e),t&&(this.#i[e]=void 0,this.#t[e]=void 0,this.#_.push(e)),this.#n===1?(this.#o=this.#h=0,this.#_.length=0):this.#o=this.#l[e],this.#s.delete(i),this.#n--,e}has(t,e={}){let{updateAgeOnHas:i=this.updateAgeOnHas,status:s}=e,n=this.#s.get(t);if(n!==void 0){let h=this.#t[n];if(this.#e(h)&&h.__staleWhileFetching===void 0)return!1;if(this.#d(n))s&&(s.has="stale",this.#E(s,n));else return i&&this.#z(n),s&&(s.has="hit",this.#E(s,n)),!0}else s&&(s.has="miss");return!1}peek(t,e={}){let{allowStale:i=this.allowStale}=e,s=this.#s.get(t);if(s===void 0||!i&&this.#d(s))return;let n=this.#t[s];return this.#e(n)?n.__staleWhileFetching:n}#x(t,e,i,s){let n=e===void 0?void 0:this.#t[e];if(this.#e(n))return n;let h=new W,{signal:o}=i;o?.addEventListener("abort",()=>h.abort(o.reason),{signal:h.signal});let r={signal:h.signal,options:i,context:s},g=(d,S=!1)=>{let{aborted:a}=h.signal,w=i.ignoreFetchAbort&&d!==void 0;if(i.status&&(a&&!S?(i.status.fetchAborted=!0,i.status.fetchError=h.signal.reason,w&&(i.status.fetchAbortIgnored=!0)):i.status.fetchResolved=!0),a&&!w&&!S)return f(h.signal.reason);let b=c;return this.#t[e]===c&&(d===void 0?b.__staleWhileFetching?this.#t[e]=b.__staleWhileFetching:this.#T(t,"fetch"):(i.status&&(i.status.fetchUpdated=!0),this.set(t,d,r.options))),d},m=d=>(i.status&&(i.status.fetchRejected=!0,i.status.fetchError=d),f(d)),f=d=>{let{aborted:S}=h.signal,a=S&&i.allowStaleOnFetchAbort,w=a||i.allowStaleOnFetchRejection,b=w||i.noDeleteOnFetchRejection,p=c;if(this.#t[e]===c&&(!b||p.__staleWhileFetching===void 0?this.#T(t,"fetch"):a||(this.#t[e]=p.__staleWhileFetching)),w)return i.status&&p.__staleWhileFetching!==void 0&&(i.status.returnedStale=!0),p.__staleWhileFetching;if(p.__returned===p)throw d},u=(d,S)=>{let a=this.#R?.(t,n,r);a&&a instanceof Promise&&a.then(w=>d(w===void 0?void 0:w),S),h.signal.addEventListener("abort",()=>{(!i.ignoreFetchAbort||i.allowStaleOnFetchAbort)&&(d(void 0),i.allowStaleOnFetchAbort&&(d=w=>g(w,!0)))})};i.status&&(i.status.fetchDispatched=!0);let c=new Promise(u).then(g,m),F=Object.assign(c,{__abortController:h,__staleWhileFetching:n,__returned:void 0});return e===void 0?(this.set(t,F,{...r.options,status:void 0}),e=this.#s.get(t)):this.#t[e]=F,F}#e(t){if(!this.#O)return!1;let e=t;return!!e&&e instanceof Promise&&e.hasOwnProperty("__staleWhileFetching")&&e.__abortController instanceof W}async fetch(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,ttl:h=this.ttl,noDisposeOnSet:o=this.noDisposeOnSet,size:r=0,sizeCalculation:g=this.sizeCalculation,noUpdateTTL:m=this.noUpdateTTL,noDeleteOnFetchRejection:f=this.noDeleteOnFetchRejection,allowStaleOnFetchRejection:u=this.allowStaleOnFetchRejection,ignoreFetchAbort:c=this.ignoreFetchAbort,allowStaleOnFetchAbort:F=this.allowStaleOnFetchAbort,context:d,forceRefresh:S=!1,status:a,signal:w}=e;if(!this.#O)return a&&(a.fetch="get"),this.get(t,{allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,status:a});let b={allowStale:i,updateAgeOnGet:s,noDeleteOnStaleGet:n,ttl:h,noDisposeOnSet:o,size:r,sizeCalculation:g,noUpdateTTL:m,noDeleteOnFetchRejection:f,allowStaleOnFetchRejection:u,allowStaleOnFetchAbort:F,ignoreFetchAbort:c,status:a,signal:w},p=this.#s.get(t);if(p===void 0){a&&(a.fetch="miss");let _=this.#x(t,p,b,d);return _.__returned=_}else{let _=this.#t[p];if(this.#e(_)){let U=i&&_.__staleWhileFetching!==void 0;return a&&(a.fetch="inflight",U&&(a.returnedStale=!0)),U?_.__staleWhileFetching:_.__returned=_}let v=this.#d(p);if(!S&&!v)return a&&(a.fetch="hit"),this.#C(p),s&&this.#z(p),a&&this.#E(a,p),_;let y=this.#x(t,p,b,d),L=y.__staleWhileFetching!==void 0&&i;return a&&(a.fetch=v?"stale":"refresh",L&&v&&(a.returnedStale=!0)),L?y.__staleWhileFetching:y.__returned=y}}async forceFetch(t,e={}){let i=await this.fetch(t,e);if(i===void 0)throw new Error("fetch() returned undefined");return i}memo(t,e={}){let i=this.#W;if(!i)throw new Error("no memoMethod provided to constructor");let{context:s,forceRefresh:n,...h}=e,o=this.get(t,h);if(!n&&o!==void 0)return o;let r=i(t,o,{options:h,context:s});return this.set(t,r,h),r}get(t,e={}){let{allowStale:i=this.allowStale,updateAgeOnGet:s=this.updateAgeOnGet,noDeleteOnStaleGet:n=this.noDeleteOnStaleGet,status:h}=e,o=this.#s.get(t);if(o!==void 0){let r=this.#t[o],g=this.#e(r);return h&&this.#E(h,o),this.#d(o)?(h&&(h.get="stale"),g?(h&&i&&r.__staleWhileFetching!==void 0&&(h.returnedStale=!0),i?r.__staleWhileFetching:void 0):(n||this.#T(t,"expire"),h&&i&&(h.returnedStale=!0),i?r:void 0)):(h&&(h.get="hit"),g?r.__staleWhileFetching:(this.#C(o),s&&this.#z(o),r))}else h&&(h.get="miss")}#j(t,e){this.#c[e]=t,this.#l[t]=e}#C(t){t!==this.#h&&(t===this.#o?this.#o=this.#l[t]:this.#j(this.#c[t],this.#l[t]),this.#j(this.#h,t),this.#h=t)}delete(t){return this.#T(t,"delete")}#T(t,e){let i=!1;if(this.#n!==0){let s=this.#s.get(t);if(s!==void 0)if(i=!0,this.#n===1)this.#N(e);else{this.#v(s);let n=this.#t[s];if(this.#e(n)?n.__abortController.abort(new Error("deleted")):(this.#y||this.#a)&&(this.#y&&this.#p?.(n,t,e),this.#a&&this.#r?.push([n,t,e])),this.#s.delete(t),this.#i[s]=void 0,this.#t[s]=void 0,s===this.#h)this.#h=this.#c[s];else if(s===this.#o)this.#o=this.#l[s];else{let h=this.#c[s];this.#l[h]=this.#l[s];let o=this.#l[s];this.#c[o]=this.#c[s]}this.#n--,this.#_.push(s)}}if(this.#a&&this.#r?.length){let s=this.#r,n;for(;n=s?.shift();)this.#w?.(...n)}return i}clear(){return this.#N("delete")}#N(t){for(let e of this.#F({allowStale:!0})){let i=this.#t[e];if(this.#e(i))i.__abortController.abort(new Error("deleted"));else{let s=this.#i[e];this.#y&&this.#p?.(i,s,t),this.#a&&this.#r?.push([i,s,t])}}if(this.#s.clear(),this.#t.fill(void 0),this.#i.fill(void 0),this.#u&&this.#b&&(this.#u.fill(0),this.#b.fill(0)),this.#m&&this.#m.fill(0),this.#o=0,this.#h=0,this.#_.length=0,this.#S=0,this.#n=0,this.#a&&this.#r){let e=this.#r,i;for(;i=e?.shift();)this.#w?.(...i)}}};export{D as LRUCache};
 //# sourceMappingURL=index.min.js.map

package.json

 {
   "name": "lru-cache",
   "description": "A cache object that deletes the least-recently-used items.",
-  "version": "10.2.2",
+  "version": "10.3.0",
   "author": "Isaac Z. Schlueter <[e-mail]>",
@@ -6,0 +6,0 @@ "keywords": [

README.md

@@ -105,885 +105,5 @@ # lru-cache
 
-## `class LRUCache<K, V, FC = unknown>(options)`
+For full description of the API and all options, please see [the
+LRUCache typedocs](https://isaacs.github.io/node-lru-cache/)
 
-Create a new `LRUCache` object.
-
-When using TypeScript, set the `K` and `V` types to the `key` and
-`value` types, respectively.
-
-The `FC` ("fetch context") generic type defaults to `unknown`.
-If set to a value other than `void` or `undefined`, then any
-calls to `cache.fetch()` _must_ provide a `context` option
-matching the `FC` type. If `FC` is set to `void` or `undefined`,
-then `cache.fetch()` _must not_ provide a `context` option. See
-the documentation on `async fetch()` below.
-
-## Options
-
-All options are available on the LRUCache instance, making it
-safe to pass an LRUCache instance as the options argument to make
-another empty cache of the same type.
-
-Some options are marked read-only because changing them after
-instantiation is not safe. Changing any of the other options
-will of course only have an effect on subsequent method calls.
-
-### `max` (read only)
-
-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` (read only)
-
-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.
-
-### `fetchMethod` (read only)
-
-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))`.
-
-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`.
-
-### `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 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:
-
-```ts
-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' }
-```
-
-### `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` (read only)
-
-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.
-
-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` (read only)
-
-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.
-(The TypeScript definitions will also discourage this.)
-
-### `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.
-
-### `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`
-
-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()`.
-
-Boolean, default false, only relevant if `ttl` is set.
-
-## API
-
-### `new LRUCache<K, V, FC = unknown>(options)`
-
-Create a new LRUCache. All options are documented above, and are
-on the cache as public members.
-
-The `K` and `V` types define the key and value types,
-respectively. The optional `FC` type defines the type of the
-`context` object passed to `cache.fetch()`.
-
-Keys and values **must not** be `null` or `undefined`.
-
-### `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.
-
-If the value is `undefined`, then this is an alias for
-`cache.delete(key)`. `undefined` is never stored in the cache.
-See **Storing Undefined Values** 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`.
-
-For the usage of the `status` option, see **Status Tracking**
-below.
-
-### `info(key) => Entry | undefined`
-
-Return an `Entry` object containing the currently cached value,
-as well as ttl and size information if available. Returns
-undefined if the key is not found in the cache.
-
-Unlike `dump()` (which is designed to be portable and survive
-serialization), the `start` value is always the current
-timestamp, and the `ttl` is a calculated remaining time to live
-(negative if expired).
-
-Note that stale values are always returned, rather than being
-pruned and treated as if they were not in the cache. If you wish
-to exclude stale entries, guard against a negative `ttl` value.
-
-### `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.
-- `context` - 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.
-
-#### Setting `context`
-
-If an `FC` type is set to a type other than `unknown`, `void`, or
-`undefined` in the LRUCache constructor, then all
-calls to `cache.fetch()` _must_ provide a `context` option. If
-set to `undefined` or `void`, then calls to fetch _must not_
-provide a `context` option.
-
-The `context` param allows you to provide arbitrary data that
-might be relevant in the course of fetching the data. It is only
-relevant for the course of a single `fetch()` operation, and
-discarded afterwards.
-
-#### Note: `fetch()` calls are inflight-unique
-
-If you call `fetch()` multiple times with the same key value,
-then every call after the first will resolve on the same
-promise<sup>1</sup>,
-_even if they have different settings that would otherwise change
-the behvavior of the fetch_, such as `noDeleteOnFetchRejection`
-or `ignoreFetchAbort`.
-
-In most cases, this is not a problem (in fact, only fetching
-something once is what you probably want, if you're caching in
-the first place). If you are changing the fetch() options
-dramatically between runs, there's a good chance that you might
-be trying to fit divergent semantics into a single object, and
-would be better off with multiple cache instances.
-
-**1**: Ie, they're not the "same Promise", but they resolve at
-the same time, because they're both waiting on the same
-underlying fetchMethod response.
-
-### `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.
-
-### `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.
-
-### `rvalues()`
-
-Return a generator yielding the values in the cache, in order
-from least recently used to most recently used.
-
-### `entries()`
-
-Return a generator yielding `[key, value]` pairs, in order from
-most recently used to least recently used.
-
-### `rentries()`
-
-Return a generator yielding `[key, value]` pairs, in order from
-least recently used to most recently used.
-
-### `find(fn, [getOptions])`
-
-Find a value for which the supplied `fn` method returns a truthy
-value, similar to `Array.find()`.
-
-`fn` is called as `fn(value, key, cache)`.
-
-The optional `getOptions` are applied to the resulting `get()` of
-the item found.
-
-### `dump()`
-
-Return an array of `[key, entry]` objects which can be passed to
-`cache.load()`
-
-The `start` fields are calculated relative to a portable
-`Date.now()` timestamp, even if `performance.now()` is available.
-
-Stale entries are always included in the `dump`, even if
-`allowStale` is false.
-
-Note: this returns an actual array, not a generator, so it can be
-more easily passed around.
-
-### `load(entries)`
-
-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.
-
-The `start` fields are assumed to be calculated relative to a
-portable `Date.now()` timestamp, even if `performance.now()` is
-available.
-
-### `purgeStale()`
-
-Delete any stale entries. Returns `true` if anything was
-removed, `false` otherwise.
-
-### `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.
-
-## 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
@@ -1070,3 +190,3 @@
 
-You may call `cache.set(key, undefined)`, but this is just an
+You may call `cache.set(key, undefined)`, but this is just
 an alias for `cache.delete(key)`. Note that this has the effect
@@ -1200,3 +320,3 @@ that `cache.has(key)` will return _false_ after setting it to
 
-## Changes in Version 9
+## Breaking Changes in Version 9
 
@@ -1207,2 +327,9 @@ - Named export only, no default export.
 
+## Breaking Changes in Version 10
+
+- `cache.fetch()` return type is now `Promise<V | undefined>`
+  instead of `Promise<V | void>`. This is an irrelevant change
+  practically speaking, but can require changes for TypeScript
+  users.
+
 For more info, see the [change log](CHANGELOG.md).

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

804323

increased by18.13%

Lines of code

5778

increased by22.16%

Worsened metrics

Number of lines in readme file

332

decreased by-72.45%

No dependency changes