@nocobase/plugin-workflow 2.1.0-beta.15 → 2.1.0-beta.16

package/dist/node_modules/lru-cache/dist/{cjs → esm}/index.js

@@ -1,26 +1,31 @@
-"use strict";
 /**
  * @module LRUCache
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LRUCache = void 0;
-const perf = typeof performance === 'object' &&
+import { metrics, tracing } from './diagnostics-channel.js';
+const hasSubscribers = () => metrics.hasSubscribers || tracing.hasSubscribers;
+const defaultPerf = (typeof performance === 'object' &&
     performance &&
-    typeof performance.now === 'function'
-    ? performance
+    typeof performance.now === 'function') ?
+    performance
     : Date;
 const warned = new Set();
+/* c8 ignore start */
+const PROCESS = (typeof process === 'object' && !!process ?
+    process
+    : {});
+/* c8 ignore stop */
 const emitWarning = (msg, type, code, fn) => {
-    typeof process === 'object' &&
-        process &&
-        typeof process.emitWarning === 'function'
-        ? process.emitWarning(msg, type, code, fn)
-        : console.error(`[${code}] ${type}: ${msg}`);
+    if (typeof PROCESS.emitWarning === 'function') {
+        PROCESS.emitWarning(msg, type, code, fn);
+    }
+    else {
+        //oxlint-disable-next-line no-console
+        console.error(`[${code}] ${type}: ${msg}`);
+    }
 };
 const shouldWarn = (code) => !warned.has(code);
 const TYPE = Symbol('type');
-const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
-/* c8 ignore start */
+const isPosInt = (n) => !!n && n === Math.floor(n) && n > 0 && isFinite(n);
 // This is a little bit ridiculous, tbh.
 // The maximum array length is 2^32-1 or thereabouts on most JS impls.
 // And well before that point, you're caching the entire world, I mean,
@@ -29,16 +34,12 @@ const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
 // zeroes at init time is brutal when you get that big.
 // But why not be complete?
 // Maybe in the future, these limits will have expanded.
-const getUintArray = (max) => !isPosInt(max)
-    ? null
-    : max <= Math.pow(2, 8)
-        ? Uint8Array
-        : max <= Math.pow(2, 16)
-            ? Uint16Array
-            : max <= Math.pow(2, 32)
-                ? Uint32Array
-                : max <= Number.MAX_SAFE_INTEGER
-                    ? ZeroArray
+/* c8 ignore start */
+const getUintArray = (max) => !isPosInt(max) ? null
+    : max <= Math.pow(2, 8) ? Uint8Array
+        : max <= Math.pow(2, 16) ? Uint16Array
+            : max <= Math.pow(2, 32) ? Uint32Array
+                : max <= Number.MAX_SAFE_INTEGER ? ZeroArray
                     : null;
 /* c8 ignore stop */
 class ZeroArray extends Array {
@@ -80,21 +81,34 @@ class Stack {
 /**
  * Default export, the thing you're using this module to get.
  *
- * 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.
+export class LRUCache {
+    // options that cannot be changed without disaster
     #max;
     #maxSize;
     #dispose;
+    #onInsert;
     #disposeAfter;
     #fetchMethod;
+    #memoMethod;
+    #perf;
+    /**
+     * {@link LRUCache.OptionsBase.perf}
+     */
+    get perf() {
+        return this.#perf;
+    }
     /**
      * {@link LRUCache.OptionsBase.ttl}
      */
@@ -170,9 +184,11 @@ class LRUCache {
     #sizes;
     #starts;
     #ttls;
+    #autopurgeTimers;
     #hasDispose;
     #hasFetchMethod;
     #hasDisposeAfter;
+    #hasOnInsert;
     /**
      * Do not call this method unless you need to inspect the
      * inner workings of the cache.  If anything returned by this
@@ -187,6 +203,7 @@ class LRUCache {
             // properties
             starts: c.#starts,
             ttls: c.#ttls,
+            autopurgeTimers: c.#autopurgeTimers,
             sizes: c.#sizes,
             keyMap: c.#keyMap,
             keyList: c.#keyList,
@@ -240,12 +257,21 @@ class LRUCache {
     get fetchMethod() {
         return this.#fetchMethod;
     }
+    get memoMethod() {
+        return this.#memoMethod;
+    }
     /**
      * {@link LRUCache.OptionsBase.dispose} (read-only)
      */
     get dispose() {
         return this.#dispose;
     }
+    /**
+     * {@link LRUCache.OptionsBase.onInsert} (read-only)
+     */
+    get onInsert() {
+        return this.#onInsert;
+    }
     /**
      * {@link LRUCache.OptionsBase.disposeAfter} (read-only)
      */
@@ -253,7 +279,13 @@ class LRUCache {
         return this.#disposeAfter;
     }
     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, onInsert, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, perf, } = options;
+        if (perf !== undefined) {
+            if (typeof perf?.now !== 'function') {
+                throw new TypeError('perf option must have a now() method if specified');
+            }
+        }
+        this.#perf = perf ?? defaultPerf;
         if (max !== 0 && !isPosInt(max)) {
             throw new TypeError('max option must be a nonnegative integer');
         }
@@ -273,15 +305,18 @@ class LRUCache {
                 throw new TypeError('sizeCalculation set to non-function');
             }
         }
-        if (fetchMethod !== undefined &&
-            typeof fetchMethod !== 'function') {
+        if (memoMethod !== undefined && typeof memoMethod !== 'function') {
+            throw new TypeError('memoMethod must be a function if defined');
+        }
+        this.#memoMethod = memoMethod;
+        if (fetchMethod !== undefined && typeof fetchMethod !== 'function') {
             throw new TypeError('fetchMethod must be a function if specified');
         }
         this.#fetchMethod = fetchMethod;
         this.#hasFetchMethod = !!fetchMethod;
         this.#keyMap = new Map();
-        this.#keyList = new Array(max).fill(undefined);
-        this.#valList = new Array(max).fill(undefined);
+        this.#keyList = Array.from({ length: max }).fill(undefined);
+        this.#valList = Array.from({ length: max }).fill(undefined);
         this.#next = new UintArray(max);
         this.#prev = new UintArray(max);
         this.#head = 0;
@@ -292,6 +327,9 @@ class LRUCache {
         if (typeof dispose === 'function') {
             this.#dispose = dispose;
         }
+        if (typeof onInsert === 'function') {
+            this.#onInsert = onInsert;
+        }
         if (typeof disposeAfter === 'function') {
             this.#disposeAfter = disposeAfter;
             this.#disposed = [];
@@ -301,6 +339,7 @@ class LRUCache {
             this.#disposed = undefined;
         }
         this.#hasDispose = !!this.#dispose;
+        this.#hasOnInsert = !!this.#onInsert;
         this.#hasDisposeAfter = !!this.#disposeAfter;
         this.noDisposeOnSet = !!noDisposeOnSet;
         this.noUpdateTTL = !!noUpdateTTL;
@@ -325,9 +364,7 @@ class LRUCache {
         this.updateAgeOnGet = !!updateAgeOnGet;
         this.updateAgeOnHas = !!updateAgeOnHas;
         this.ttlResolution =
-            isPosInt(ttlResolution) || ttlResolution === 0
-                ? ttlResolution
-                : 1;
+            isPosInt(ttlResolution) || ttlResolution === 0 ? ttlResolution : 1;
         this.ttlAutopurge = !!ttlAutopurge;
         this.ttl = ttl || 0;
         if (this.ttl) {
@@ -351,7 +388,8 @@ class LRUCache {
         }
     }
     /**
-     * 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.
      */
     getRemainingTTL(key) {
         return this.#keyMap.has(key) ? Infinity : 0;
@@ -361,41 +399,68 @@ class LRUCache {
         const starts = new ZeroArray(this.#max);
         this.#ttls = ttls;
         this.#starts = starts;
-        this.#setItemTTL = (index, ttl, start = perf.now()) => {
+        const purgeTimers = this.ttlAutopurge ?
+            Array.from({
+                length: this.#max,
+            })
+            : undefined;
+        this.#autopurgeTimers = purgeTimers;
+        this.#setItemTTL = (index, ttl, start = this.#perf.now()) => {
             starts[index] = ttl !== 0 ? start : 0;
             ttls[index] = ttl;
-            if (ttl !== 0 && this.ttlAutopurge) {
-                const t = setTimeout(() => {
-                    if (this.#isStale(index)) {
-                        this.delete(this.#keyList[index]);
-                    }
-                }, ttl + 1);
-                // unref() not supported on all platforms
-                /* c8 ignore start */
-                if (t.unref) {
-                    t.unref();
-                }
-                /* c8 ignore stop */
-            }
+            setPurgetTimer(index, ttl);
         };
         this.#updateItemAge = index => {
-            starts[index] = ttls[index] !== 0 ? perf.now() : 0;
+            starts[index] = ttls[index] !== 0 ? this.#perf.now() : 0;
+            setPurgetTimer(index, ttls[index]);
         };
+        // clear out the purge timer if we're setting TTL to 0, and
+        // previously had a ttl purge timer running, so it doesn't
+        // fire unnecessarily. Don't need to do this if we're not doing
+        // autopurge.
+        const setPurgetTimer = !this.ttlAutopurge ?
+            () => { }
+            : (index, ttl) => {
+                if (purgeTimers?.[index]) {
+                    clearTimeout(purgeTimers[index]);
+                    purgeTimers[index] = undefined;
+                }
+                if (ttl && ttl !== 0 && purgeTimers) {
+                    const t = setTimeout(() => {
+                        if (this.#isStale(index)) {
+                            this.#delete(this.#keyList[index], 'expire');
+                        }
+                    }, ttl + 1);
+                    // unref() not supported on all platforms
+                    /* c8 ignore start */
+                    if (t.unref) {
+                        t.unref();
+                    }
+                    /* c8 ignore stop */
+                    purgeTimers[index] = t;
+                }
+            };
         this.#statusTTL = (status, index) => {
             if (ttls[index]) {
                 const ttl = ttls[index];
                 const start = starts[index];
+                /* c8 ignore start */
+                if (!ttl || !start) {
+                    return;
+                }
+                /* c8 ignore stop */
                 status.ttl = ttl;
                 status.start = start;
                 status.now = cachedNow || getNow();
-                status.remainingTTL = status.now + ttl - start;
+                const age = status.now - start;
+                status.remainingTTL = ttl - age;
             }
         };
         // debounce calls to perf.now() to 1s so we're not hitting
         // that costly call repeatedly.
         let cachedNow = 0;
         const getNow = () => {
-            const n = perf.now();
+            const n = this.#perf.now();
             if (this.ttlResolution > 0) {
                 cachedNow = n;
                 const t = setTimeout(() => (cachedNow = 0), this.ttlResolution);
@@ -413,14 +478,18 @@ class LRUCache {
             if (index === undefined) {
                 return 0;
             }
-            return ttls[index] === 0 || starts[index] === 0
-                ? Infinity
-                : starts[index] + ttls[index] - (cachedNow || getNow());
+            const ttl = ttls[index];
+            const start = starts[index];
+            if (!ttl || !start) {
+                return Infinity;
+            }
+            const age = (cachedNow || getNow()) - start;
+            return ttl - age;
         };
         this.#isStale = index => {
-            return (ttls[index] !== 0 &&
-                starts[index] !== 0 &&
-                (cachedNow || getNow()) - starts[index] > ttls[index]);
+            const s = starts[index];
+            const t = ttls[index];
+            return !!t && !!s && (cachedNow || getNow()) - s > t;
         };
     }
     // conditionally set private methods related to TTL
@@ -486,10 +555,7 @@ class LRUCache {
     };
     *#indexes({ allowStale = this.allowStale } = {}) {
         if (this.#size) {
-            for (let i = this.#tail; true;) {
-                if (!this.#isValidIndex(i)) {
-                    break;
-                }
+            for (let i = this.#tail; this.#isValidIndex(i);) {
                 if (allowStale || !this.#isStale(i)) {
                     yield i;
                 }
@@ -504,10 +570,7 @@ class LRUCache {
     }
     *#rindexes({ allowStale = this.allowStale } = {}) {
         if (this.#size) {
-            for (let i = this.#head; true;) {
-                if (!this.#isValidIndex(i)) {
-                    break;
-                }
+            for (let i = this.#head; this.#isValidIndex(i);) {
                 if (allowStale || !this.#isStale(i)) {
                     yield i;
                 }
@@ -559,8 +622,7 @@ class LRUCache {
     *keys() {
         for (const i of this.#indexes()) {
             const k = this.#keyList[i];
-            if (k !== undefined &&
-                !this.#isBackgroundFetch(this.#valList[i])) {
+            if (k !== undefined && !this.#isBackgroundFetch(this.#valList[i])) {
                 yield k;
             }
         }
@@ -574,8 +636,7 @@ class LRUCache {
     *rkeys() {
         for (const i of this.#rindexes()) {
             const k = this.#keyList[i];
-            if (k !== undefined &&
-                !this.#isBackgroundFetch(this.#valList[i])) {
+            if (k !== undefined && !this.#isBackgroundFetch(this.#valList[i])) {
                 yield k;
             }
         }
@@ -587,8 +648,7 @@ class LRUCache {
     *values() {
         for (const i of this.#indexes()) {
             const v = this.#valList[i];
-            if (v !== undefined &&
-                !this.#isBackgroundFetch(this.#valList[i])) {
+            if (v !== undefined && !this.#isBackgroundFetch(this.#valList[i])) {
                 yield this.#valList[i];
             }
         }
@@ -602,8 +662,7 @@ class LRUCache {
     *rvalues() {
         for (const i of this.#rindexes()) {
             const v = this.#valList[i];
-            if (v !== undefined &&
-                !this.#isBackgroundFetch(this.#valList[i])) {
+            if (v !== undefined && !this.#isBackgroundFetch(this.#valList[i])) {
                 yield this.#valList[i];
             }
         }
@@ -615,35 +674,42 @@ class LRUCache {
     [Symbol.iterator]() {
         return this.entries();
     }
+    /**
+     * 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`.
+     */
+    [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)`.
      */
     find(fn, getOptions = {}) {
         for (const i of this.#indexes()) {
             const v = this.#valList[i];
-            const value = this.#isBackgroundFetch(v)
-                ? v.__staleWhileFetching
-                : v;
+            const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
             if (value === undefined)
                 continue;
             if (fn(value, this.#keyList[i], this)) {
-                return this.get(this.#keyList[i], getOptions);
+                return this.#get(this.#keyList[i], 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.
      */
     forEach(fn, thisp = this) {
         for (const i of this.#indexes()) {
             const v = this.#valList[i];
-            const value = this.#isBackgroundFetch(v)
-                ? v.__staleWhileFetching
-                : v;
+            const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
             if (value === undefined)
                 continue;
             fn.call(thisp, value, this.#keyList[i], this);
@@ -656,9 +722,7 @@ class LRUCache {
     rforEach(fn, thisp = this) {
         for (const i of this.#rindexes()) {
             const v = this.#valList[i];
-            const value = this.#isBackgroundFetch(v)
-                ? v.__staleWhileFetching
-                : v;
+            const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
             if (value === undefined)
                 continue;
             fn.call(thisp, value, this.#keyList[i], this);
@@ -672,24 +736,69 @@ class LRUCache {
         let deleted = false;
         for (const i of this.#rindexes({ allowStale: true })) {
             if (this.#isStale(i)) {
-                this.delete(this.#keyList[i]);
+                this.#delete(this.#keyList[i], 'expire');
                 deleted = true;
             }
         }
         return deleted;
     }
+    /**
+     * Get the extended info about a given entry, to get its value, size, and
+     * 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.
+     */
+    info(key) {
+        const i = this.#keyMap.get(key);
+        if (i === undefined)
+            return undefined;
+        const v = this.#valList[i];
+        /* c8 ignore start - this isn't tested for the info function,
+         * but it's the same logic as found in other places. */
+        const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
+        if (value === undefined)
+            return undefined;
+        /* c8 ignore stop */
+        const entry = { value };
+        if (this.#ttls && this.#starts) {
+            const ttl = this.#ttls[i];
+            const start = this.#starts[i];
+            if (ttl && start) {
+                const remain = ttl - (this.#perf.now() - start);
+                entry.ttl = remain;
+                entry.start = Date.now();
+            }
+        }
+        if (this.#sizes) {
+            entry.size = this.#sizes[i];
+        }
+        return entry;
+    }
     /**
      * Return an array of [key, {@link LRUCache.Entry}] tuples which can be
-     * passed to cache.load()
+     * passed to {@link LRUCache#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.
      */
     dump() {
         const arr = [];
         for (const i of this.#indexes({ allowStale: true })) {
             const key = this.#keyList[i];
             const v = this.#valList[i];
-            const value = this.#isBackgroundFetch(v)
-                ? v.__staleWhileFetching
-                : v;
+            const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
             if (value === undefined || key === undefined)
                 continue;
             const entry = { value };
@@ -697,7 +806,7 @@ class LRUCache {
                 entry.ttl = this.#ttls[i];
                 // always dump the start relative to a portable timestamp
                 // it's ok for this to be a bit slow, it's a rare operation.
-                const age = perf.now() - this.#starts[i];
+                const age = this.#perf.now() - this.#starts[i];
                 entry.start = Math.floor(Date.now() - age);
             }
             if (this.#sizes) {
@@ -709,8 +818,12 @@ class LRUCache {
     }
     /**
      * 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.
      */
     load(arr) {
         this.clear();
@@ -723,38 +836,85 @@ class LRUCache {
                 //
                 // it's ok for this to be a bit slow, it's a rare operation.
                 const age = Date.now() - entry.start;
-                entry.start = perf.now() - age;
+                entry.start = this.#perf.now() - age;
             }
-            this.set(key, entry.value, entry);
+            this.#set(key, entry.value, entry);
         }
     }
     /**
      * Add a value to the cache.
+     *
+     * Note: if `undefined` is specified as a value, this is an alias for
+     * {@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.
      */
     set(k, v, setOptions = {}) {
+        const { status = metrics.hasSubscribers ? {} : undefined } = setOptions;
+        setOptions.status = status;
+        if (status) {
+            status.op = 'set';
+            status.key = k;
+            if (v !== undefined)
+                status.value = v;
+        }
+        const result = this.#set(k, v, setOptions);
+        if (status && metrics.hasSubscribers) {
+            metrics.publish(status);
+        }
+        return result;
+    }
+    #set(k, v, setOptions = {}) {
         const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
+        if (v === undefined) {
+            if (status)
+                status.set = 'deleted';
+            this.delete(k);
+            return this;
+        }
         let { noUpdateTTL = this.noUpdateTTL } = setOptions;
-        const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation);
+        if (status && !this.#isBackgroundFetch(v))
+            status.value = v;
+        const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation, status);
         // if the item doesn't fit, don't do anything
         // NB: maxEntrySize set to maxSize by default
         if (this.maxEntrySize && size > this.maxEntrySize) {
+            // have to delete, in case something is there already.
+            this.#delete(k, 'set');
             if (status) {
                 status.set = 'miss';
                 status.maxEntrySizeExceeded = true;
             }
-            // have to delete, in case something is there already.
-            this.delete(k);
             return this;
         }
         let index = this.#size === 0 ? undefined : this.#keyMap.get(k);
         if (index === undefined) {
             // addition
-            index = (this.#size === 0
-                ? this.#tail
-                : this.#free.length !== 0
-                    ? this.#free.pop()
-                    : this.#size === this.#max
-                        ? this.#evict(false)
+            index = (this.#size === 0 ? this.#tail
+                : this.#free.length !== 0 ? this.#free.pop()
+                    : this.#size === this.#max ? this.#evict(false)
                         : this.#size);
             this.#keyList[index] = k;
             this.#valList[index] = v;
@@ -767,6 +927,9 @@ class LRUCache {
             if (status)
                 status.set = 'add';
             noUpdateTTL = false;
+            if (this.#hasOnInsert) {
+                this.#onInsert?.(v, k, 'add');
+            }
         }
         else {
             // update
@@ -775,6 +938,15 @@ class LRUCache {
             if (v !== oldVal) {
                 if (this.#hasFetchMethod && this.#isBackgroundFetch(oldVal)) {
                     oldVal.__abortController.abort(new Error('replaced'));
+                    const { __staleWhileFetching: s } = oldVal;
+                    if (s !== undefined && !noDisposeOnSet) {
+                        if (this.#hasDispose) {
+                            this.#dispose?.(s, k, 'set');
+                        }
+                        if (this.#hasDisposeAfter) {
+                            this.#disposed?.push([s, k, 'set']);
+                        }
+                    }
                 }
                 else if (!noDisposeOnSet) {
                     if (this.#hasDispose) {
@@ -789,8 +961,8 @@ class LRUCache {
                 this.#valList[index] = v;
                 if (status) {
                     status.set = 'replace';
-                    const oldValue = oldVal && this.#isBackgroundFetch(oldVal)
-                        ? oldVal.__staleWhileFetching
+                    const oldValue = oldVal && this.#isBackgroundFetch(oldVal) ?
+                        oldVal.__staleWhileFetching
                         : oldVal;
                     if (oldValue !== undefined)
                         status.oldValue = oldValue;
@@ -799,6 +971,9 @@ class LRUCache {
             else if (status) {
                 status.set = 'update';
             }
+            if (this.#hasOnInsert) {
+                this.onInsert?.(v, k, v === oldVal ? 'update' : 'replace');
+            }
         }
         if (ttl !== 0 && !this.#ttls) {
             this.#initializeTTLTracking();
@@ -864,6 +1039,10 @@ class LRUCache {
             }
         }
         this.#removeItemSize(head);
+        if (this.#autopurgeTimers?.[head]) {
+            clearTimeout(this.#autopurgeTimers[head]);
+            this.#autopurgeTimers[head] = undefined;
+        }
         // if we aren't about to use the index, then null these out
         if (free) {
             this.#keyList[head] = undefined;
@@ -886,10 +1065,30 @@ class LRUCache {
      * Will return false if the item is stale, even though it is technically
      * in the cache.
      *
+     * 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
      * {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
      */
     has(k, hasOptions = {}) {
+        const { status = metrics.hasSubscribers ? {} : undefined } = hasOptions;
+        hasOptions.status = status;
+        if (status) {
+            status.op = 'has';
+            status.key = k;
+        }
+        const result = this.#has(k, hasOptions);
+        if (metrics.hasSubscribers)
+            metrics.publish(status);
+        return result;
+    }
+    #has(k, hasOptions = {}) {
         const { updateAgeOnHas = this.updateAgeOnHas, status } = hasOptions;
         const index = this.#keyMap.get(k);
         if (index !== undefined) {
@@ -926,14 +1125,38 @@ class LRUCache {
      * {@link LRUCache.OptionsBase.allowStale} is set.
      */
     peek(k, peekOptions = {}) {
-        const { allowStale = this.allowStale } = peekOptions;
+        const { status = hasSubscribers() ? {} : undefined } = peekOptions;
+        if (status) {
+            status.op = 'peek';
+            status.key = k;
+        }
+        peekOptions.status = status;
+        const result = this.#peek(k, peekOptions);
+        if (metrics.hasSubscribers) {
+            metrics.publish(status);
+        }
+        return result;
+    }
+    #peek(k, peekOptions) {
+        const { status, allowStale = this.allowStale } = peekOptions;
         const index = this.#keyMap.get(k);
-        if (index !== undefined &&
-            (allowStale || !this.#isStale(index))) {
-            const v = this.#valList[index];
-            // either stale and allowed, or forcing a refresh of non-stale value
-            return this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
+        if (index === undefined || (!allowStale && this.#isStale(index))) {
+            if (status)
+                status.peek = index === undefined ? 'miss' : 'stale';
+            return undefined;
+        }
+        const v = this.#valList[index];
+        const val = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
+        if (status) {
+            if (val !== undefined) {
+                status.peek = 'hit';
+                status.value = val;
+            }
+            else {
+                status.peek = 'miss';
+            }
         }
+        return val;
     }
     #backgroundFetch(k, index, options, context) {
         const v = index === undefined ? undefined : this.#valList[index];
@@ -954,6 +1177,8 @@ class LRUCache {
         const cb = (v, updateCache = false) => {
             const { aborted } = ac.signal;
             const ignoreAbort = options.ignoreFetchAbort && v !== undefined;
+            const proceed = options.ignoreFetchAbort ||
+                !!(options.allowStaleOnFetchAbort && v !== undefined);
             if (options.status) {
                 if (aborted && !updateCache) {
                     options.status.fetchAborted = true;
@@ -966,23 +1191,27 @@ class LRUCache {
                 }
             }
             if (aborted && !ignoreAbort && !updateCache) {
-                return fetchFail(ac.signal.reason);
+                return fetchFail(ac.signal.reason, proceed);
             }
             // either we didn't abort, and are still here, or we did, and ignored
             const bf = p;
-            if (this.#valList[index] === p) {
+            // if nothing else has been written there but we're set to update the
+            // cache and ignore the abort, or if it's still pending on this specific
+            // background request, then write it to the cache.
+            const vl = this.#valList[index];
+            if (vl === p || (vl === undefined && ignoreAbort && updateCache)) {
                 if (v === undefined) {
-                    if (bf.__staleWhileFetching) {
+                    if (bf.__staleWhileFetching !== undefined) {
                         this.#valList[index] = bf.__staleWhileFetching;
                     }
                     else {
-                        this.delete(k);
+                        this.#delete(k, 'fetch');
                     }
                 }
                 else {
                     if (options.status)
                         options.status.fetchUpdated = true;
-                    this.set(k, v, fetchOpts.options);
+                    this.#set(k, v, fetchOpts.options);
                 }
             }
             return v;
@@ -992,9 +1221,10 @@ class LRUCache {
                 options.status.fetchRejected = true;
                 options.status.fetchError = er;
             }
-            return fetchFail(er);
+            // do not pass go, do not collect $200
+            return fetchFail(er, false);
         };
-        const fetchFail = (er) => {
+        const fetchFail = (er, proceed) => {
             const { aborted } = ac.signal;
             const allowStaleAborted = aborted && options.allowStaleOnFetchAbort;
             const allowStale = allowStaleAborted || options.allowStaleOnFetchRejection;
@@ -1003,9 +1233,9 @@ class LRUCache {
             if (this.#valList[index] === p) {
                 // if we allow stale on fetch rejections, then we need to ensure that
                 // the stale value is not removed from the cache when the fetch fails.
-                const del = !noDelete || bf.__staleWhileFetching === undefined;
+                const del = !noDelete || (!proceed && bf.__staleWhileFetching === undefined);
                 if (del) {
-                    this.delete(k);
+                    this.#delete(k, 'fetch');
                 }
                 else if (!allowStaleAborted) {
                     // still replace the *promise* with the stale value,
@@ -1028,15 +1258,14 @@ class LRUCache {
         const pcall = (res, rej) => {
             const fmp = this.#fetchMethod?.(k, v, fetchOpts);
             if (fmp && fmp instanceof Promise) {
-                fmp.then(v => res(v), rej);
+                fmp.then(v => res(v === undefined ? undefined : v), rej);
             }
             // ignored, we go until we finish, regardless.
             // defer check until we are actually aborting,
             // so fetchMethod can override.
             ac.signal.addEventListener('abort', () => {
-                if (!options.ignoreFetchAbort ||
-                    options.allowStaleOnFetchAbort) {
-                    res();
+                if (!options.ignoreFetchAbort || options.allowStaleOnFetchAbort) {
+                    res(undefined);
                     // when it eventually resolves, update the cache.
                     if (options.allowStaleOnFetchAbort) {
                         res = v => cb(v, true);
@@ -1054,7 +1283,7 @@ class LRUCache {
         });
         if (index === undefined) {
             // internal, don't expose status.
-            this.set(k, bf, { ...fetchOpts.options, status: undefined });
+            this.#set(k, bf, { ...fetchOpts.options, status: undefined });
             index = this.#keyMap.get(k);
         }
         else {
@@ -1071,7 +1300,23 @@ class LRUCache {
             b.hasOwnProperty('__staleWhileFetching') &&
             b.__abortController instanceof AbortController);
     }
-    async fetch(k, fetchOptions = {}) {
+    fetch(k, fetchOptions = {}) {
+        const ths = tracing.hasSubscribers;
+        const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
+        fetchOptions.status = status;
+        if (status && fetchOptions.context) {
+            status.context = fetchOptions.context;
+        }
+        const p = this.#fetch(k, fetchOptions);
+        if (status && hasSubscribers()) {
+            if (ths) {
+                status.trace = true;
+                tracing.tracePromise(() => p, status).catch(() => { });
+            }
+        }
+        return p;
+    }
+    async #fetch(k, fetchOptions = {}) {
         const { 
         // get options
         allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet, 
@@ -1079,10 +1324,16 @@ class LRUCache {
         ttl = this.ttl, noDisposeOnSet = this.noDisposeOnSet, size = 0, sizeCalculation = this.sizeCalculation, noUpdateTTL = this.noUpdateTTL, 
         // fetch exclusive options
         noDeleteOnFetchRejection = this.noDeleteOnFetchRejection, allowStaleOnFetchRejection = this.allowStaleOnFetchRejection, ignoreFetchAbort = this.ignoreFetchAbort, allowStaleOnFetchAbort = this.allowStaleOnFetchAbort, context, forceRefresh = false, status, signal, } = fetchOptions;
+        if (status) {
+            status.op = 'fetch';
+            status.key = k;
+            if (forceRefresh)
+                status.forceRefresh = true;
+        }
         if (!this.#hasFetchMethod) {
             if (status)
                 status.fetch = 'get';
-            return this.get(k, {
+            return this.#get(k, {
                 allowStale,
                 updateAgeOnGet,
                 noDeleteOnStaleGet,
@@ -1151,6 +1402,71 @@ class LRUCache {
             return staleVal ? p.__staleWhileFetching : (p.__returned = p);
         }
     }
+    forceFetch(k, fetchOptions = {}) {
+        const ths = tracing.hasSubscribers;
+        const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
+        fetchOptions.status = status;
+        if (status && fetchOptions.context) {
+            status.context = fetchOptions.context;
+        }
+        const p = this.#forceFetch(k, fetchOptions);
+        if (status && hasSubscribers()) {
+            if (ths) {
+                status.trace = true;
+                tracing.tracePromise(() => p, status).catch(() => { });
+            }
+        }
+        return p;
+    }
+    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 { status = metrics.hasSubscribers ? {} : undefined } = memoOptions;
+        memoOptions.status = status;
+        if (status) {
+            status.op = 'memo';
+            status.key = k;
+            if (memoOptions.context) {
+                status.context = memoOptions.context;
+            }
+        }
+        const result = this.#memo(k, memoOptions);
+        if (status)
+            status.value = result;
+        if (metrics.hasSubscribers)
+            metrics.publish(status);
+        return result;
+    }
+    #memo(k, memoOptions = {}) {
+        const memoMethod = this.#memoMethod;
+        if (!memoMethod) {
+            throw new Error('no memoMethod provided to constructor');
+        }
+        const { context, status, forceRefresh, ...options } = memoOptions;
+        if (status && forceRefresh)
+            status.forceRefresh = true;
+        const v = this.#get(k, options);
+        const refresh = forceRefresh || v === undefined;
+        if (status) {
+            status.memo = refresh ? 'miss' : 'hit';
+            if (!refresh)
+                status.value = v;
+        }
+        if (!refresh)
+            return v;
+        const vv = memoMethod(k, v, {
+            options,
+            context,
+        });
+        if (status)
+            status.value = vv;
+        this.#set(k, vv, options);
+        return vv;
+    }
     /**
      * Return a value from the cache. Will update the recency of the cache
      * entry found.
@@ -1158,55 +1474,70 @@ class LRUCache {
      * If the key is not found, get() will return `undefined`.
      */
     get(k, getOptions = {}) {
+        const { status = metrics.hasSubscribers ? {} : undefined } = getOptions;
+        getOptions.status = status;
+        if (status) {
+            status.op = 'get';
+            status.key = k;
+        }
+        const result = this.#get(k, getOptions);
+        if (status) {
+            if (result !== undefined)
+                status.value = result;
+            if (metrics.hasSubscribers)
+                metrics.publish(status);
+        }
+        return result;
+    }
+    #get(k, getOptions = {}) {
         const { allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet, status, } = getOptions;
         const index = this.#keyMap.get(k);
-        if (index !== undefined) {
-            const value = this.#valList[index];
-            const fetching = this.#isBackgroundFetch(value);
+        if (index === undefined) {
             if (status)
-                this.#statusTTL(status, index);
-            if (this.#isStale(index)) {
+                status.get = 'miss';
+            return undefined;
+        }
+        const value = this.#valList[index];
+        const fetching = this.#isBackgroundFetch(value);
+        if (status)
+            this.#statusTTL(status, index);
+        if (this.#isStale(index)) {
+            // delete only if not an in-flight background fetch
+            if (!fetching) {
+                if (!noDeleteOnStaleGet) {
+                    this.#delete(k, 'expire');
+                }
                 if (status)
                     status.get = 'stale';
-                // delete only if not an in-flight background fetch
-                if (!fetching) {
-                    if (!noDeleteOnStaleGet) {
-                        this.delete(k);
-                    }
-                    if (status && allowStale)
-                        status.returnedStale = true;
-                    return allowStale ? value : undefined;
-                }
-                else {
-                    if (status &&
-                        allowStale &&
-                        value.__staleWhileFetching !== undefined) {
+                if (allowStale) {
+                    if (status)
                         status.returnedStale = true;
-                    }
-                    return allowStale ? value.__staleWhileFetching : undefined;
+                    return value;
                 }
+                return undefined;
             }
-            else {
+            if (status)
+                status.get = 'stale-fetching';
+            if (allowStale && value.__staleWhileFetching !== undefined) {
                 if (status)
-                    status.get = 'hit';
-                // if we're currently fetching it, we don't actually have it yet
-                // it's not stale, which means this isn't a staleWhileRefetching.
-                // If it's not stale, and fetching, AND has a __staleWhileFetching
-                // value, then that means the user fetched with {forceRefresh:true},
-                // so it's safe to return that value.
-                if (fetching) {
-                    return value.__staleWhileFetching;
-                }
-                this.#moveToTail(index);
-                if (updateAgeOnGet) {
-                    this.#updateItemAge(index);
-                }
-                return value;
+                    status.returnedStale = true;
+                return value.__staleWhileFetching;
             }
+            return undefined;
         }
-        else if (status) {
-            status.get = 'miss';
+        // not stale
+        if (status)
+            status.get = fetching ? 'fetching' : 'hit';
+        // if we're currently fetching it, we don't actually have it yet
+        // it's not stale, which means this isn't a staleWhileRefetching.
+        // If it's not stale, and fetching, AND has a __staleWhileFetching
+        // value, then that means the user fetched with {forceRefresh:true},
+        // so it's safe to return that value.
+        this.#moveToTail(index);
+        if (updateAgeOnGet) {
+            this.#updateItemAge(index);
         }
+        return fetching ? value.__staleWhileFetching : value;
     }
     #connect(p, n) {
         this.#prev[n] = p;
@@ -1234,16 +1565,31 @@ class LRUCache {
     }
     /**
      * 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) {
+        if (metrics.hasSubscribers) {
+            metrics.publish({
+                op: 'delete',
+                delete: reason,
+                key: k,
+            });
+        }
         let deleted = false;
         if (this.#size !== 0) {
             const index = this.#keyMap.get(k);
             if (index !== undefined) {
+                if (this.#autopurgeTimers?.[index]) {
+                    clearTimeout(this.#autopurgeTimers?.[index]);
+                    this.#autopurgeTimers[index] = undefined;
+                }
                 deleted = true;
                 if (this.#size === 1) {
-                    this.clear();
+                    this.#clear(reason);
                 }
                 else {
                     this.#removeItemSize(index);
@@ -1253,10 +1599,10 @@ class LRUCache {
                     }
                     else if (this.#hasDispose || this.#hasDisposeAfter) {
                         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]);
                         }
                     }
                     this.#keyMap.delete(k);
@@ -1269,8 +1615,10 @@ class LRUCache {
                         this.#head = this.#next[index];
                     }
                     else {
-                        this.#next[this.#prev[index]] = this.#next[index];
-                        this.#prev[this.#next[index]] = this.#prev[index];
+                        const pi = this.#prev[index];
+                        this.#next[pi] = this.#next[index];
+                        const ni = this.#next[index];
+                        this.#prev[ni] = this.#prev[index];
                     }
                     this.#size--;
                     this.#free.push(index);
@@ -1290,6 +1638,9 @@ class LRUCache {
      * Clear the cache entirely, throwing away all values.
      */
     clear() {
+        return this.#clear('delete');
+    }
+    #clear(reason) {
         for (const index of this.#rindexes({ allowStale: true })) {
             const v = this.#valList[index];
             if (this.#isBackgroundFetch(v)) {
@@ -1298,10 +1649,10 @@ class LRUCache {
             else {
                 const k = this.#keyList[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]);
                 }
             }
         }
@@ -1311,6 +1662,11 @@ class LRUCache {
         if (this.#ttls && this.#starts) {
             this.#ttls.fill(0);
             this.#starts.fill(0);
+            for (const t of this.#autopurgeTimers ?? []) {
+                if (t !== undefined)
+                    clearTimeout(t);
+            }
+            this.#autopurgeTimers?.fill(undefined);
         }
         if (this.#sizes) {
             this.#sizes.fill(0);
@@ -1329,6 +1685,4 @@ class LRUCache {
         }
     }
 }
-exports.LRUCache = LRUCache;
-exports.default = LRUCache;
 //# sourceMappingURL=index.js.map