@automattic/vip 4.1.2 → 4.1.4

package/node_modules/{lando/node_modules/lru-cache/dist/commonjs → path-scurry/node_modules/lru-cache/dist/esm}/index.js

@@ -1,78 +1,27 @@
-"use strict";
 /**
  * @module LRUCache
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LRUCache = void 0;
-const defaultPerf = (typeof performance === 'object' &&
-    performance &&
-    typeof performance.now === 'function') ?
-    performance
-    : Date;
+import { metrics, tracing } from './diagnostics-channel.js';
+import { defaultPerf } from './perf.js';
+const hasSubscribers = () => metrics.hasSubscribers || tracing.hasSubscribers;
 const warned = new Set();
 /* c8 ignore start */
 const PROCESS = (typeof process === 'object' && !!process ?
     process
     : {});
-/* c8 ignore start */
+/* c8 ignore stop */
 const emitWarning = (msg, type, code, fn) => {
-    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}`);
+    }
 };
-let AC = globalThis.AbortController;
-let AS = globalThis.AbortSignal;
-/* c8 ignore start */
-if (typeof AC === 'undefined') {
-    //@ts-ignore
-    AS = class AbortSignal {
-        onabort;
-        _onabort = [];
-        reason;
-        aborted = false;
-        addEventListener(_, fn) {
-            this._onabort.push(fn);
-        }
-    };
-    //@ts-ignore
-    AC = class AbortController {
-        constructor() {
-            warnACPolyfill();
-        }
-        signal = new AS();
-        abort(reason) {
-            if (this.signal.aborted)
-                return;
-            //@ts-ignore
-            this.signal.reason = reason;
-            //@ts-ignore
-            this.signal.aborted = true;
-            //@ts-ignore
-            for (const fn of this.signal._onabort) {
-                fn(reason);
-            }
-            this.signal.onabort?.(reason);
-        }
-    };
-    let printACPolyfillWarning = PROCESS.env?.LRU_CACHE_IGNORE_AC_WARNING !== '1';
-    const warnACPolyfill = () => {
-        if (!printACPolyfillWarning)
-            return;
-        printACPolyfillWarning = false;
-        emitWarning('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', warnACPolyfill);
-    };
-}
-/* c8 ignore stop */
 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,
@@ -81,6 +30,7 @@ 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.
+/* c8 ignore start */
 const getUintArray = (max) => !isPosInt(max) ? null
     : max <= Math.pow(2, 8) ? Uint8Array
         : max <= Math.pow(2, 16) ? Uint16Array
@@ -95,7 +45,9 @@ class ZeroArray extends Array {
     }
 }
 class Stack {
+    /* c8 ignore start - not sure why this is showing up uncovered?? */
     heap;
+    /* c8 ignore stop */
     length;
     // private constructor
     static #constructing = false;
@@ -139,7 +91,7 @@ class Stack {
  *
  * Changing any of these will alter the defaults for subsequent method calls.
  */
-class LRUCache {
+export class LRUCache {
     // options that cannot be changed without disaster
     #max;
     #maxSize;
@@ -215,6 +167,8 @@ class LRUCache {
      * {@link LRUCache.OptionsBase.ignoreFetchAbort}
      */
     ignoreFetchAbort;
+    /** {@link LRUCache.OptionsBase.backgroundFetchSize} */
+    backgroundFetchSize;
     // computed properties
     #size;
     #calculatedSize;
@@ -325,7 +279,8 @@ class LRUCache {
         return this.#disposeAfter;
     }
     constructor(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;
+        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, backgroundFetchSize = 1, perf, } = options;
+        this.backgroundFetchSize = backgroundFetchSize;
         if (perf !== undefined) {
             if (typeof perf?.now !== 'function') {
                 throw new TypeError('perf option must have a now() method if specified');
@@ -361,8 +316,8 @@ class LRUCache {
         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;
@@ -446,23 +401,25 @@ class LRUCache {
         this.#ttls = ttls;
         this.#starts = starts;
         const purgeTimers = this.ttlAutopurge ?
-            new Array(this.#max)
+            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;
-            setPurgetTimer(index, ttl);
+            setPurgeTimer(index, ttl);
         };
         this.#updateItemAge = index => {
             starts[index] = ttls[index] !== 0 ? this.#perf.now() : 0;
-            setPurgetTimer(index, ttls[index]);
+            setPurgeTimer(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 ?
+        const setPurgeTimer = !this.ttlAutopurge ?
             () => { }
             : (index, ttl) => {
                 if (purgeTimers?.[index]) {
@@ -473,6 +430,10 @@ class LRUCache {
                     const t = setTimeout(() => {
                         if (this.#isStale(index)) {
                             this.#delete(this.#keyList[index], 'expire');
+                            purgeTimers[index] = undefined;
+                        }
+                        else {
+                            setPurgeTimer(index, getRemainingTTL(index));
                         }
                     }, ttl + 1);
                     // unref() not supported on all platforms
@@ -488,9 +449,11 @@ class LRUCache {
             if (ttls[index]) {
                 const ttl = ttls[index];
                 const start = starts[index];
-                /* c8 ignore next */
-                if (!ttl || !start)
+                /* c8 ignore start */
+                if (!ttl || !start) {
                     return;
+                }
+                /* c8 ignore stop */
                 status.ttl = ttl;
                 status.start = start;
                 status.now = cachedNow || getNow();
@@ -520,6 +483,9 @@ class LRUCache {
             if (index === undefined) {
                 return 0;
             }
+            return getRemainingTTL(index);
+        };
+        const getRemainingTTL = (index) => {
             const ttl = ttls[index];
             const start = starts[index];
             if (!ttl || !start) {
@@ -549,12 +515,15 @@ class LRUCache {
             sizes[index] = 0;
         };
         this.#requireSize = (k, v, size, sizeCalculation) => {
-            // provisionally accept background fetches.
-            // actual value size will be checked when they return.
-            if (this.#isBackgroundFetch(v)) {
-                return 0;
-            }
             if (!isPosInt(size)) {
+                // provisionally accept background fetches.
+                // actual value size will be checked when they return.
+                if (this.#isBackgroundFetch(v)) {
+                    // NB: this cannot occur if v.__staleWhileFetching is set,
+                    // because in that case, it would take on the size of the
+                    // existing entry that it temporarily replaces.
+                    return this.backgroundFetchSize;
+                }
                 if (sizeCalculation) {
                     if (typeof sizeCalculation !== 'function') {
                         throw new TypeError('sizeCalculation must be a function');
@@ -597,10 +566,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;
                 }
@@ -615,10 +581,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;
                 }
@@ -739,7 +702,7 @@ class LRUCache {
             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);
             }
         }
     }
@@ -812,7 +775,7 @@ class LRUCache {
         const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
         if (value === undefined)
             return undefined;
-        /* c8 ignore end */
+        /* c8 ignore stop */
         const entry = { value };
         if (this.#ttls && this.#starts) {
             const ttl = this.#ttls[i];
@@ -886,7 +849,7 @@ class LRUCache {
                 const age = Date.now() - entry.start;
                 entry.start = this.#perf.now() - age;
             }
-            this.set(key, entry.value, entry);
+            this.#set(key, entry.value, entry);
         }
     }
     /**
@@ -920,22 +883,43 @@ class LRUCache {
      * `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;
+            status.cache = this;
+        }
+        const result = this.#set(k, v, setOptions);
+        if (status && metrics.hasSubscribers) {
+            metrics.publish(status);
+        }
+        return result;
+    }
+    #set(k, v, setOptions, bf) {
+        const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
+        const isBF = this.#isBackgroundFetch(v);
         if (v === undefined) {
+            if (status)
+                status.set = 'deleted';
             this.delete(k);
             return this;
         }
-        const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
         let { noUpdateTTL = this.noUpdateTTL } = setOptions;
-        const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation);
+        if (status && !isBF)
+            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, 'set');
             return this;
         }
         let index = this.#size === 0 ? undefined : this.#keyMap.get(k);
@@ -956,52 +940,68 @@ class LRUCache {
             if (status)
                 status.set = 'add';
             noUpdateTTL = false;
-            if (this.#hasOnInsert) {
+            if (this.#hasOnInsert && !isBF) {
                 this.#onInsert?.(v, k, 'add');
             }
         }
         else {
             // update
+            // might be updating a background fetch!
             this.#moveToTail(index);
             const oldVal = this.#valList[index];
             if (v !== oldVal) {
-                if (this.#hasFetchMethod && this.#isBackgroundFetch(oldVal)) {
-                    oldVal.__abortController.abort(new Error('replaced'));
-                    const { __staleWhileFetching: s } = oldVal;
-                    if (s !== undefined && !noDisposeOnSet) {
+                if (!noDisposeOnSet) {
+                    if (this.#isBackgroundFetch(oldVal)) {
+                        if (oldVal !== bf) {
+                            // setting over a background fetch, not merely resolving it.
+                            oldVal.__abortController.abort(new Error('replaced'));
+                        }
+                        const { __staleWhileFetching: s } = oldVal;
+                        if (s !== undefined && s !== v) {
+                            if (this.#hasDispose) {
+                                this.#dispose?.(s, k, 'set');
+                            }
+                            if (this.#hasDisposeAfter) {
+                                this.#disposed?.push([s, k, 'set']);
+                            }
+                        }
+                    }
+                    else {
                         if (this.#hasDispose) {
-                            this.#dispose?.(s, k, 'set');
+                            this.#dispose?.(oldVal, k, 'set');
                         }
                         if (this.#hasDisposeAfter) {
-                            this.#disposed?.push([s, k, 'set']);
+                            this.#disposed?.push([oldVal, k, 'set']);
                         }
                     }
                 }
-                else if (!noDisposeOnSet) {
-                    if (this.#hasDispose) {
-                        this.#dispose?.(oldVal, k, 'set');
-                    }
-                    if (this.#hasDisposeAfter) {
-                        this.#disposed?.push([oldVal, k, 'set']);
-                    }
-                }
                 this.#removeItemSize(index);
                 this.#addItemSize(index, size, status);
                 this.#valList[index] = v;
-                if (status) {
-                    status.set = 'replace';
+                if (!isBF) {
                     const oldValue = oldVal && this.#isBackgroundFetch(oldVal) ?
                         oldVal.__staleWhileFetching
                         : oldVal;
-                    if (oldValue !== undefined)
-                        status.oldValue = oldValue;
+                    const setType = oldValue === undefined ? 'add'
+                        : v !== oldValue ? 'replace'
+                            : 'update';
+                    if (status) {
+                        status.set = setType;
+                        if (oldValue !== undefined)
+                            status.oldValue = oldValue;
+                    }
+                    if (this.#hasOnInsert) {
+                        this.onInsert?.(v, k, setType);
+                    }
                 }
             }
-            else if (status) {
-                status.set = 'update';
-            }
-            if (this.#hasOnInsert) {
-                this.onInsert?.(v, k, v === oldVal ? 'update' : 'replace');
+            else if (!isBF) {
+                if (status) {
+                    status.set = 'update';
+                }
+                if (this.#hasOnInsert) {
+                    this.onInsert?.(v, k, 'update');
+                }
             }
         }
         if (ttl !== 0 && !this.#ttls) {
@@ -1056,15 +1056,18 @@ class LRUCache {
         const head = this.#head;
         const k = this.#keyList[head];
         const v = this.#valList[head];
-        if (this.#hasFetchMethod && this.#isBackgroundFetch(v)) {
+        const isBF = this.#isBackgroundFetch(v);
+        if (isBF) {
             v.__abortController.abort(new Error('evicted'));
         }
-        else if (this.#hasDispose || this.#hasDisposeAfter) {
+        const oldValue = isBF ? v.__staleWhileFetching : v;
+        if ((this.#hasDispose || this.#hasDisposeAfter) &&
+            oldValue !== undefined) {
             if (this.#hasDispose) {
-                this.#dispose?.(v, k, 'evict');
+                this.#dispose?.(oldValue, k, 'evict');
             }
             if (this.#hasDisposeAfter) {
-                this.#disposed?.push([v, k, 'evict']);
+                this.#disposed?.push([oldValue, k, 'evict']);
             }
         }
         this.#removeItemSize(head);
@@ -1106,6 +1109,19 @@ class LRUCache {
      * {@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;
+            status.cache = this;
+        }
+        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) {
@@ -1142,21 +1158,46 @@ 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;
+            status.cache = this;
+        }
+        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))) {
-            return;
+            if (status)
+                status.peek = index === undefined ? 'miss' : 'stale';
+            return undefined;
         }
         const v = this.#valList[index];
-        // either stale and allowed, or forcing a refresh of non-stale value
-        return this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
+        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];
         if (this.#isBackgroundFetch(v)) {
             return v;
         }
-        const ac = new AC();
+        const ac = new AbortController();
         const { signal } = options;
         // when/if our AC signals, then stop listening to theirs.
         signal?.addEventListener('abort', () => ac.abort(signal.reason), {
@@ -1192,7 +1233,7 @@ class LRUCache {
             // 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 || (ignoreAbort && updateCache && vl === undefined)) {
+            if (vl === p || (vl === undefined && ignoreAbort && updateCache)) {
                 if (v === undefined) {
                     if (bf.__staleWhileFetching !== undefined) {
                         this.#valList[index] = bf.__staleWhileFetching;
@@ -1204,7 +1245,7 @@ class LRUCache {
                 else {
                     if (options.status)
                         options.status.fetchUpdated = true;
-                    this.set(k, v, fetchOpts.options);
+                    this.#set(k, v, fetchOpts.options, bf);
                 }
             }
             return v;
@@ -1250,9 +1291,6 @@ class LRUCache {
         };
         const pcall = (res, rej) => {
             const fmp = this.#fetchMethod?.(k, v, fetchOpts);
-            if (fmp && fmp instanceof Promise) {
-                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.
@@ -1265,6 +1303,12 @@ class LRUCache {
                     }
                 }
             });
+            if (fmp && fmp instanceof Promise) {
+                fmp.then(v => res(v === undefined ? undefined : v), rej);
+            }
+            else if (fmp !== undefined) {
+                res(fmp);
+            }
         };
         if (options.status)
             options.status.fetchDispatched = true;
@@ -1276,10 +1320,14 @@ 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 {
+            // do not call #set, because we do not want to adjust its place
+            // in the lru queue, as it has not yet been "used". Also, we don't
+            // need to worry about evicting for size, because a background fetch
+            // over a stale value is treated as the same size as its stale value.
             this.#valList[index] = bf;
         }
         return bf;
@@ -1291,9 +1339,23 @@ class LRUCache {
         return (!!b &&
             b instanceof Promise &&
             b.hasOwnProperty('__staleWhileFetching') &&
-            b.__abortController instanceof AC);
+            b.__abortController instanceof AbortController);
+    }
+    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 && ths) {
+            status.trace = true;
+            tracing.tracePromise(() => p, status).catch(() => { });
+        }
+        return p;
     }
-    async fetch(k, fetchOptions = {}) {
+    async #fetch(k, fetchOptions = {}) {
         const { 
         // get options
         allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet, 
@@ -1301,10 +1363,17 @@ 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;
+            status.cache = this;
+        }
         if (!this.#hasFetchMethod) {
             if (status)
                 status.fetch = 'get';
-            return this.get(k, {
+            return this.#get(k, {
                 allowStale,
                 updateAgeOnGet,
                 noDeleteOnStaleGet,
@@ -1373,26 +1442,68 @@ class LRUCache {
             return staleVal ? p.__staleWhileFetching : (p.__returned = p);
         }
     }
-    async forceFetch(k, fetchOptions = {}) {
-        const v = await this.fetch(k, fetchOptions);
+    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 && 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;
+            }
+            status.cache = this;
+        }
+        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, forceRefresh, ...options } = memoOptions;
-        const v = this.get(k, options);
-        if (!forceRefresh && v !== undefined)
+        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,
         });
-        this.set(k, vv, options);
+        if (status)
+            status.value = vv;
+        this.#set(k, vv, options);
         return vv;
     }
     /**
@@ -1402,55 +1513,71 @@ 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;
+            status.cache = this;
+        }
+        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, 'expire');
-                    }
-                    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;
@@ -1485,12 +1612,20 @@ class LRUCache {
         return this.#delete(k, 'delete');
     }
     #delete(k, reason) {
+        if (metrics.hasSubscribers) {
+            metrics.publish({
+                op: 'delete',
+                delete: reason,
+                key: k,
+                cache: this,
+            });
+        }
         let deleted = false;
         if (this.#size !== 0) {
             const index = this.#keyMap.get(k);
             if (index !== undefined) {
                 if (this.#autopurgeTimers?.[index]) {
-                    clearTimeout(this.#autopurgeTimers?.[index]);
+                    clearTimeout(this.#autopurgeTimers[index]);
                     this.#autopurgeTimers[index] = undefined;
                 }
                 deleted = true;
@@ -1563,7 +1698,7 @@ class LRUCache {
             }
         }
         this.#keyMap.clear();
-        this.#valList.fill(undefined);
+        void this.#valList.fill(undefined);
         this.#keyList.fill(undefined);
         if (this.#ttls && this.#starts) {
             this.#ttls.fill(0);
@@ -1591,5 +1726,4 @@ class LRUCache {
         }
     }
 }
-exports.LRUCache = LRUCache;
 //# sourceMappingURL=index.js.map