@zajno/common 2.8.8 → 2.8.10

package/esm/structures/promiseCache/cache.js

@@ -16,6 +16,7 @@ export class PromiseCache extends PromiseCacheCore {
     _batch = null;
     _invalidationConfig = null;
     _onError = null;
+    _initialValueFactory = null;
     /**
      * Creates an instance of PromiseCache.
      * @param fetcher Function to fetch data by key.
@@ -44,10 +45,12 @@ export class PromiseCache extends PromiseCacheCore {
      * This is a convenience wrapper around {@link useInvalidation}.
      *
      * @param ms Time in milliseconds after which the item will be considered invalid. If null, auto-invalidation is disabled.
-     * @param keepInstance If true, the cached item will not be removed during invalidation, but the old instance is kept. Defaults to false.
+     *
+     * @deprecated The `keepInstance` parameter is deprecated and ignored — stale values are now always kept during invalidation.
+     * Use `invalidate()` followed by `get()` if you need to clear the stale value before re-fetching.
     */
-    useInvalidationTime(ms, keepInstance = false) {
-        return this.useInvalidation(ms != null ? { expirationMs: ms, keepInstance } : null);
+    useInvalidationTime(ms, _keepInstance) {
+        return this.useInvalidation(ms != null ? { expirationMs: ms } : null);
     }
     /**
      * Configures advanced invalidation policy.
@@ -70,6 +73,25 @@ export class PromiseCache extends PromiseCacheCore {
         this._onError = callback;
         return this;
     }
+    /**
+     * Sets a default/initial value returned before the fetch completes or on error when no stale value exists.
+     *
+     * Accepts either a static value or a per-key factory function `(key: K) => TInitial`.
+     * The value is **not** stored in the cache — it's a synthetic default (same as `LazyPromise`'s initial value).
+     *
+     * **Note:** Functions are always interpreted as factories. If `T` is a function type,
+     * wrap it: `useInitialValue((key) => myFallbackFn)`.
+     *
+     * @param initial A value (non-function) or `(key: K) => TInitial` factory.
+     * @returns `this` for chaining.
+     */
+    useInitialValue(initial) {
+        const self = this;
+        self._initialValueFactory = typeof initial === 'function'
+            ? initial
+            : (_key) => initial;
+        return self;
+    }
     // ─── Core implementation ─────────────────────────────────────────────
     /**
      * Returns a promise that resolves to the cached value of the item if loaded already, otherwise starts fetching and the promise will be resolved to the final value.
@@ -83,16 +105,37 @@ export class PromiseCache extends PromiseCacheCore {
         const { item, key, isInvalid } = this._getCurrent(id);
         // return cached item if it's not invalidated
         if (item !== undefined && !isInvalid) {
-            this.logger.log(key, 'get: item resolved to', item, isInvalid ? '(invalidated)' : '');
+            this.logger.log(key, 'get: item resolved to', item);
             return Promise.resolve(item);
         }
+        // Join an existing in-flight fetch/refresh if one exists
         let promise = this._fetchCache.get(key);
         if (promise != null) {
             this.logger.log(key, 'get: item resolved to <promise>');
             return promise;
         }
         this.setStatus(key, true);
-        promise = this._doFetchAsync(id, key);
+        promise = this._doFetchAsync(id, key, false);
+        this.setPromise(key, promise);
+        return promise;
+    }
+    /**
+     * Re-fetches the value for the specified key while keeping the stale cached value available.
+     *
+     * Does not change the loading status — consumers reading `getCurrent()` / `getLazy().value`
+     * continue to see the stale value as if nothing happened.
+     *
+     * Implements "latest wins" concurrency: if multiple refreshes are called concurrently,
+     * all promises resolve to the value from the latest refresh.
+     *
+     * On error, the stale value is preserved and the error is stored.
+     *
+     * @param id The key of the item to refresh.
+     * @returns A promise resolving to the refreshed value, or the stale value on error.
+     */
+    refresh(id) {
+        const key = this._pk(id);
+        const promise = this._doFetchAsync(id, key, true);
         this.setPromise(key, promise);
         return promise;
     }
@@ -102,17 +145,21 @@ export class PromiseCache extends PromiseCacheCore {
         super.clear();
     }
     // ─── Protected overrides ─────────────────────────────────────────────
+    _getInitialValue(id) {
+        return this._initialValueFactory ? this._initialValueFactory(id) : undefined;
+    }
     _getCurrent(id) {
         const key = this._pk(id);
         const isInvalid = this.getIsInvalidated(key);
         // make sure current item is hooked here from the cache (required by observers)
         const item = this._itemsCache.get(key);
-        const keepInstance = !!this._invalidationConfig?.keepInstance;
         if (isInvalid) {
             this.logger.log(key, 'item is invalidated');
         }
         return {
-            item: (isInvalid && !keepInstance) ? undefined : item,
+            // Always keep the stale value visible — stale-while-revalidate by default.
+            // Use `invalidate()` + `get()` to clear the stale value before re-fetching.
+            item,
             key,
             isInvalid,
         };
@@ -146,53 +193,87 @@ export class PromiseCache extends PromiseCacheCore {
     }
     // ─── Private ─────────────────────────────────────────────────────────
     /**
-     * Fetches the item asynchronously.
-     * @param id The id of the item.
-     * @param key The cache key.
-     * @returns A promise that resolves to the fetched item.
+     * Unified fetch method with "latest wins" semantics.
+     *
+     * - Tracks the active factory promise per key via `_activeFetchPromises`.
+     * - If superseded by a newer fetch, delegates to the newer promise.
+     * - On error, preserves the stale cached value.
+     *
+     * @param id The original key.
+     * @param key The string cache key.
+     * @returns A promise resolving to the fetched/refreshed value, or the stale value on error.
      */
-    async _doFetchAsync(id, key) {
+    async _doFetchAsync(id, key, refreshing) {
         let isInSameVersion = true;
+        let isLatest = false;
         try {
             this.onBeforeFetch(key);
             const v = this._version;
+            // Create the factory promise and mark it as the active one for this key (latest wins)
+            const factoryPromise = this.tryFetchInBatch(id, refreshing);
+            this._activeFetchPromises.set(key, factoryPromise);
             let res;
             let fetchFailed = false;
             try {
-                res = await this.tryFetchInBatch(id);
+                res = await factoryPromise;
             }
             catch (err) {
                 this._handleError(id, err);
                 fetchFailed = true;
-                res = null;
+                res = undefined;
             }
             if (v !== this._version) {
                 isInSameVersion = false;
+                this._activeFetchPromises.delete(key);
                 // resolve with actual result but don't store it
-                return res;
+                return res ?? this._getInitialValue(id);
+            }
+            // Check if this is still the active (latest) fetch for this key
+            isLatest = this._activeFetchPromises.get(key) === factoryPromise;
+            if (!isLatest) {
+                // Superseded by a newer refresh/fetch — delegate to the latest public promise.
+                // This ensures anyone awaiting this old promise gets the fresh value,
+                // mirroring LazyPromise's "latest wins" behavior.
+                const newerPromise = this._fetchCache.get(key);
+                if (newerPromise) {
+                    // Catch errors from the newer promise — if it fails, fall back to stale/initial value.
+                    return newerPromise.catch(() => this._itemsCache.get(key) ?? this._getInitialValue(id));
+                }
+                // Fallback: return current cached value or initial
+                return this._itemsCache.get(key) ?? this._getInitialValue(id);
             }
-            if (this._fetchCache.get(key) != null) {
+            // We are the latest — clean up tracking
+            this._activeFetchPromises.delete(key);
+            if (!fetchFailed && res !== undefined) {
                 this.logger.log(key, 'item\'s <promise> resolved to', res);
                 res = this.prepareResult(res);
-                if (!fetchFailed) {
-                    this.storeResult(key, res);
-                }
+                this.storeResult(key, res);
             }
-            return res;
+            else if (fetchFailed) {
+                // Keep stale value — return whatever is in cache, or initial value
+                return this._itemsCache.get(key) ?? this._getInitialValue(id);
+            }
+            return res ?? this._getInitialValue(id);
         }
         finally {
-            if (isInSameVersion) {
+            if (!isInSameVersion) {
+                this.logger.log(key, 'skipping item\'s resolve due to version change ("clear()" has been called)');
+            }
+            else if (isLatest) {
+                // Only the latest fetch should clean up the fetch state.
+                // Superseded fetches delegate to the latest and should not
+                // prematurely clear the fetch cache or loading status.
                 this.onFetchComplete(key);
             }
             else {
-                this.logger.log(key, 'skipping item\'s resolve due to version change ("clear()" has been called)');
+                this.onFetchSuperseded(key);
             }
         }
     }
     /** Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. Throws on error. */
-    async tryFetchInBatch(id) {
+    async tryFetchInBatch(id, refreshing) {
         if (!this._batch) {
-            return this.fetcher(id);
+            return this.fetcher(id, refreshing);
         }
         const res = await this._batch.push(id)
             .catch(err => {
@@ -201,7 +282,7 @@ export class PromiseCache extends PromiseCacheCore {
         });
         if (!res || !res.result || res.result[res.index] === undefined) {
             // batch call failed or returned no result — fallback to the direct fetcher
-            return this.fetcher(id);
+            return this.fetcher(id, refreshing);
         }
         return res.result[res.index];
     }
@@ -221,9 +302,12 @@ export class PromiseCache extends PromiseCacheCore {
     }
     /**
      * Enforces the max items limit by removing items to make room.
-     * Strategy: first removes invalid items, then oldest valid items.
+     * Strategy: first removes invalid items, then oldest valid items by timestamp.
      * Items currently being fetched (in-flight) are not evicted.
      *
+     * Note: Phase 2 scans all timestamps linearly (O(n) per eviction).
+     * This is acceptable for typical `maxItems` values (up to ~1000).
+     *
      * @param incomingKey The key of the item about to be stored (excluded from eviction).
      */
     _enforceMaxItems(incomingKey) {
@@ -248,6 +332,7 @@ export class PromiseCache extends PromiseCacheCore {
             this._set(key, undefined, undefined, undefined);
             this._errorsMap.delete(key);
             this._timestamps.delete(key);
+            this._activeFetchPromises.delete(key);
             if (this._itemsCache.size < maxItems) {
                 return;
             }
@@ -271,6 +356,7 @@ export class PromiseCache extends PromiseCacheCore {
                 this._set(oldestKey, undefined, undefined, undefined);
                 this._timestamps.delete(oldestKey);
                 this._errorsMap.delete(oldestKey);
+                this._activeFetchPromises.delete(oldestKey);
             }
             else {
                 // No evictable items found (all are in-flight or incoming)

package/esm/structures/promiseCache/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/cache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAG7C,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B;;;;;;;;;EASE;AACF,MAAM,OAAO,YAA4B,SAAQ,gBAAsB;IAa9C;IAXb,MAAM,GAAqC,IAAI,CAAC;IAChD,mBAAmB,GAAiC,IAAI,CAAC;IACzD,QAAQ,GAA4B,IAAI,CAAC;IAEjD;;;;;OAKG;IACH,YACqB,OAA8B,EAC/C,UAAuD,EACvD,SAAuD;QAEvD,KAAK,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QAJZ,YAAO,GAAP,OAAO,CAAuB;IAKnD,CAAC;IAED,wEAAwE;IAExE;;;;;;MAME;IACF,WAAW,CAAC,OAAmC,EAAE,KAAK,GAAG,cAAc;QACnE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,iBAAiB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACrE,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;MAOE;IACF,mBAAmB,CAAC,EAAiB,EAAE,YAAY,GAAG,KAAK;QACvD,OAAO,IAAI,CAAC,eAAe,CAAC,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACxF,CAAC;IAED;;;;;;;OAOG;IACH,eAAe,CAAC,MAAoC;QAChD,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC;QAClC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,QAAiC;QACxC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,OAAO,IAAI,CAAC;IAChB,CAAC;IAED,wEAAwE;IAExE;;;;;;;OAOG;IACH,GAAG,CAAC,EAAK;QACL,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAEtD,6CAA6C;QAC7C,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,uBAAuB,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACtF,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,CAAC;QAED,IAAI,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,OAAO,IAAI,IAAI,EAAE,CAAC;YAClB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,iCAAiC,CAAC,CAAC;YACxD,OAAO,OAAO,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAE1B,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;QAEtC,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAE9B,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,qDAAqD;IAC5C,KAAK;QACV,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC;QACrB,KAAK,CAAC,KAAK,EAAE,CAAC;IAClB,CAAC;IAED,wEAAwE;IAE9D,WAAW,CAAC,EAAK;QACvB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC7C,+EAA+E;QAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,YAAY,GAAG,CAAC,CAAC,IAAI,CAAC,mBAAmB,EAAE,YAAY,CAAC;QAC9D,IAAI,SAAS,EAAE,CAAC;YACZ,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;QAChD,CAAC;QACD,OAAO;YACH,IAAI,EAAE,CAAC,SAAS,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI;YACrD,GAAG;YACH,SAAS;SACZ,CAAC;IACN,CAAC;IAES,gBAAgB,CAAC,GAAW;QAClC,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACxC,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACjB,CAAC;QAED,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAErC,8BAA8B;QAC9B,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACzC,IAAI,YAAY,IAAI,IAAI,IAAI,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI,EAAE,CAAC;YACzD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,YAAY,EAAE,CAAC;gBACjC,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QAED,oCAAoC;QACpC,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACxC,IAAI,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;gBACvE,OAAO,IAAI,CAAC;YAChB,CAAC;QACL,CAAC;QAED,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,8EAA8E;IAC3D,WAAW,CAAC,GAAW,EAAE,GAAa;QACrD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC3B,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,wEAAwE;IAExE;;;;;OAKG;IACO,KAAK,CAAC,aAAa,CAAC,EAAK,EAAE,GAAW;QAC5C,IAAI,eAAe,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC;YACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;YAExB,IAAI,GAAa,CAAC;YAClB,IAAI,WAAW,GAAG,KAAK,CAAC;YACxB,IAAI,CAAC;gBACD,GAAG,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;YACzC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,IAAI,CAAC,YAAY,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;gBAC3B,WAAW,GAAG,IAAI,CAAC;gBACnB,GAAG,GAAG,IAAI,CAAC;YACf,CAAC;YAED,IAAI,CAAC,KAAK,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACtB,eAAe,GAAG,KAAK,CAAC;gBACxB,gDAAgD;gBAChD,OAAO,GAAG,CAAC;YACf,CAAC;YAED,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;gBACpC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,+BAA+B,EAAE,GAAG,CAAC,CAAC;gBAC3D,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;gBAC9B,IAAI,CAAC,WAAW,EAAE,CAAC;oBACf,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC/B,CAAC;YACL,CAAC;YACD,OAAO,GAAG,CAAC;QACf,CAAC;gBAAS,CAAC;YACP,IAAI,eAAe,EAAE,CAAC;gBAClB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACJ,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,4EAA4E,CAAC,CAAC;YACvG,CAAC;QACL,CAAC;IACL,CAAC;IAED,gHAAgH;IACtG,KAAK,CAAC,eAAe,CAAC,EAAK;QACjC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACf,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;aACjC,KAAK,CAAC,GAAG,CAAC,EAAE;YACT,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC;QAChB,CAAC,CAAC,CAAC;QACP,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,SAAS,EAAE,CAAC;YAC7D,2EAA2E;YAC3E,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC;QAED,OAAO,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IAED,iFAAiF;IACzE,YAAY,CAAC,EAAK,EAAE,GAAY;QACpC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC;QAE5C,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChB,IAAI,CAAC;gBACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC3B,CAAC;YAAC,MAAM,CAAC;gBACL,gCAAgC;YACpC,CAAC;QACL,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACK,gBAAgB,CAAC,WAAmB;QACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC;QACpD,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;YACpC,OAAO;QACX,CAAC;QAED,0CAA0C;QAC1C,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;YACnC,OAAO;QACX,CAAC;QAED,+DAA+D;QAC/D,MAAM,WAAW,GAAa,EAAE,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,GAAG,KAAK,WAAW;gBAAE,SAAS;YAClC,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;QACL,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAE7B,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC;gBACnC,OAAO;YACX,CAAC;QACL,CAAC;QAED,4DAA4D;QAC5D,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,IAAI,QAAQ,EAAE,CAAC;YACvC,IAAI,SAAS,GAAkB,IAAI,CAAC;YACpC,IAAI,QAAQ,GAAG,QAAQ,CAAC;YAExB,KAAK,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC;gBACjD,gEAAgE;gBAChE,IAAI,GAAG,KAAK,WAAW;oBAAE,SAAS;gBAClC,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC;oBAAE,SAAS;gBAExC,IAAI,EAAE,GAAG,QAAQ,EAAE,CAAC;oBAChB,QAAQ,GAAG,EAAE,CAAC;oBACd,SAAS,GAAG,GAAG,CAAC;gBACpB,CAAC;YACL,CAAC;YAED,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;gBACpB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;gBACtD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;gBACnC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YACtC,CAAC;iBAAM,CAAC;gBACJ,2DAA2D;gBAC3D,MAAM;YACV,CAAC;QACL,CAAC;IACL,CAAC;CACJ"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/cache.ts"],"names":[],"mappings":"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"}

package/esm/structures/promiseCache/core.js

@@ -1,3 +1,4 @@
+import { formatError } from '../../functions/safe.js';
 import { Loggable } from '../../logger/loggable.js';
 import { Model } from '../../models/Model.js';
 /**
@@ -9,7 +10,7 @@ import { Model } from '../../models/Model.js';
  *  - promise caching
  *  - error storage
  *  - timestamps for cached items
- *  - direct cache manipulation (invalidate, updateValueDirectly, clear)
+ *  - direct cache manipulation (invalidate, set, clear)
  *  - keys iteration
  *
  * Subclasses are expected to implement fetching logic, invalidation policies, etc.
@@ -29,6 +30,11 @@ export class PromiseCacheCore extends Loggable {
     _errorsMap;
     /** Stores items resolve timestamps (for expiration) in map by id. */
     _timestamps = new Map();
+    /**
+     * Tracks the latest in-flight factory promise per key for "latest wins" refresh semantics.
+     * Separate from `_fetchCache` (which stores the public-facing promise returned to callers).
+     */
+    _activeFetchPromises = new Map();
     _version = 0;
     constructor(keyAdapter, keyParser) {
         super();
@@ -41,7 +47,14 @@ export class PromiseCacheCore extends Loggable {
         this._errorsMap = this.pure_createErrorsMap();
     }
     // ─── Counts ──────────────────────────────────────────────────────────
-    /** Returns the number of items currently being fetched. */
+    /**
+     * Returns the number of items currently being fetched (includes background refreshes).
+     *
+     * Note: `loadingCount` includes background refreshes started via `refresh()`,
+     * but `getIsLoading(key)` does **not** reflect background refreshes — it only
+     * tracks the per-key status set by `get()`. Use `loadingCount` for global
+     * "something is loading" indicators.
+     */
     get loadingCount() { return this._loadingCount.value; }
     /** Returns the number of cached items (resolved values). */
     get cachedCount() { return this._itemsCache.size; }
@@ -120,10 +133,50 @@ export class PromiseCacheCore extends Loggable {
         return `[PromiseCache:${name || '?'}]`;
     }
     // ─── Public API: reading ─────────────────────────────────────────────
+    /**
+     * Returns an {@link ILazyPromise} handle for a specified cache key.
+     *
+     * The returned object implements the same interface as a standalone `LazyPromise`,
+     * allowing consumers to use a single `ILazyPromise<T>` interface regardless of whether
+     * the data comes from a single lazy value or a keyed cache.
+     *
+     * - `value` / `promise` trigger a fetch if not started.
+     * - `currentValue` reads without triggering.
+     * - `refresh()` re-fetches while keeping the stale value available.
+     */
+    getLazy(key) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return {
+            get value() { return self.getCurrent(key); },
+            get currentValue() { return self.getCurrent(key, false); },
+            get hasValue() {
+                const k = self._pk(key);
+                return self._itemsCache.has(k);
+            },
+            get error() { return self.getLastError(key); },
+            /** @deprecated Use {@link error} instead. */
+            get errorMessage() {
+                const err = self.getLastError(key);
+                return err != null ? formatError(err) : null;
+            },
+            get isLoading() {
+                const v = self.getIsLoading(key);
+                return v === undefined ? null : v;
+            },
+            get promise() { return self.get(key); },
+            refresh() {
+                return self.refresh(key);
+            },
+        };
+    }
     /**
      * Returns a {@link DeferredGetter} object for a specified key.
      *
      * This can be used to access the current value, promise, loading state, and last error of the item.
+     *
+     * @deprecated Use {@link getLazy} instead — it returns an `ILazyPromise<T>` which is the standard
+     * interface shared with standalone `LazyPromise` instances.
      */
     getDeferred(key) {
         // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -138,7 +191,11 @@ export class PromiseCacheCore extends Loggable {
     /**
      * Returns the loading state of an item.
      *
-     * @returns true if loading, false if loading completed, undefined if loading was not started yet.
+     * Note: background refreshes via `refresh()` do **not** update per-key loading status.
+     * This method only reflects fetches initiated by `get()`. Use `loadingCount` for
+     * a global indicator that includes background refreshes.
+     *
+     * @returns true if loading, false if loading completed, undefined if loading was not started yet (or invalidated).
      */
     getIsLoading(id) {
         const key = this._pk(id);
@@ -170,14 +227,15 @@ export class PromiseCacheCore extends Loggable {
         const key = this._pk(id);
         return this._errorsMap.get(key) ?? null;
     }
-    /** Returns the current cached value, optionally triggering a fetch. */
+    /** Returns the current cached value, optionally triggering a fetch. Falls back to the initial value if configured. */
     getCurrent(id, initiateFetch = true) {
         const { item, key } = this._getCurrent(id);
         if (initiateFetch) {
             this.get(id);
         }
-        this.logger.log(key, 'getCurrent: returns', item);
-        return item;
+        const result = item ?? this._getInitialValue(id);
+        this.logger.log(key, 'getCurrent: returns', result);
+        return result;
     }
     /** Returns true if the item is cached or fetching was initiated. Does not initiate fetching. */
     hasKey(id) {
@@ -212,11 +270,21 @@ export class PromiseCacheCore extends Loggable {
         this._set(key, undefined, undefined, undefined);
         this._errorsMap.delete(key);
         this._timestamps.delete(key);
+        this._activeFetchPromises.delete(key);
     }
-    /** Updates the cached value for the specified id directly, like it was fetched already. */
-    updateValueDirectly(id, value) {
+    /** Injects a value into the cache for the specified key, as if it had been fetched. Sets the timestamp and clears any previous error. Cancels any in-flight fetch for this key. */
+    set(id, value) {
         const key = this._pk(id);
         this._set(key, value, undefined, undefined);
+        this._timestamps.set(key, Date.now());
+        this._errorsMap.delete(key);
+        this._activeFetchPromises.delete(key);
+    }
+    /**
+     * @deprecated Use {@link set} instead.
+     */
+    updateValueDirectly(id, value) {
+        return this.set(id, value);
     }
     /**
      * Iterates over all cached items and removes those that are invalid (expired).
@@ -235,6 +303,7 @@ export class PromiseCacheCore extends Loggable {
             this._set(key, undefined, undefined, undefined);
             this._errorsMap.delete(key);
             this._timestamps.delete(key);
+            this._activeFetchPromises.delete(key);
             removed++;
         }
         return removed;
@@ -248,6 +317,7 @@ export class PromiseCacheCore extends Loggable {
         this._fetchCache.clear();
         this._errorsMap.clear();
         this._timestamps.clear();
+        this._activeFetchPromises.clear();
     }
     /** @internal updates all caches states at once. */
     _set(key, item, promise, isLoading) {
@@ -280,6 +350,10 @@ export class PromiseCacheCore extends Loggable {
         this._fetchCache.delete(key);
         this._itemsStatus.set(key, false);
     }
+    /** Hooks into the superseded fetch cleanup. Only decrements loading count — does not touch fetch cache or status. */
+    onFetchSuperseded(_key) {
+        this._loadingCount.value = this._loadingCount.value - 1;
+    }
     /** Hooks into the result preparation process, before it's stored into the cache. */
     prepareResult(res) {
         return res;

package/esm/structures/promiseCache/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAI9C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,gBAAgC,SAAQ,QAAQ;IAuB3C;IACA;IAtBvB,0CAA0C;IACvB,WAAW,CAA0C;IAExE,gEAAgE;IAC7C,YAAY,CAA6B;IAE5D,kCAAkC;IACf,aAAa,CAAsB;IAEtD,mEAAmE;IAChD,WAAW,CAAuC;IAErE,oEAAoE;IACjD,UAAU,CAA6B;IAE1D,qEAAqE;IAClD,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAEjD,QAAQ,GAAG,CAAC,CAAC;IAEvB,YACuB,UAAsC,EACtC,SAAsC;QAEzD,KAAK,EAAE,CAAC;QAHW,eAAU,GAAV,UAAU,CAA4B;QACtC,cAAS,GAAT,SAAS,CAA6B;QAIzD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,uBAAuB,EAAE,CAAC;QACpD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAClD,CAAC;IAED,wEAAwE;IAExE,2DAA2D;IAC3D,IAAW,YAAY,KAAa,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtE,4DAA4D;IAC5D,IAAW,WAAW,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAElE,gFAAgF;IAChF,IAAW,aAAa,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAEpE,+EAA+E;IAC/E,IAAW,YAAY;QACnB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,KAAK,EAAE,CAAC;YACZ,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,wEAAwE;IAExE;;;;;OAKG;IACO,uBAAuB;QAC7B,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACO,qBAAqB;QAC3B,OAAO,IAAI,GAAG,EAAgC,CAAC;IACnD,CAAC;IAED;;;;;OAKG;IACO,sBAAsB;QAC5B,OAAO,IAAI,GAAG,EAAmB,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACO,qBAAqB;QAC3B,OAAO,IAAI,GAAG,EAA6B,CAAC;IAChD,CAAC;IAED;;;;;OAKG;IACO,oBAAoB;QAC1B,OAAO,IAAI,GAAG,EAAmB,CAAC;IACtC,CAAC;IAED,wEAAwE;IAE9D,GAAG,CAAC,CAAI;QACd,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,CAAC,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAES,aAAa,CAAC,IAAwB;QAC5C,OAAO,iBAAiB,IAAI,IAAI,GAAG,GAAG,CAAC;IAC3C,CAAC;IAED,wEAAwE;IAExE;;;;OAIG;IACH,WAAW,CAAC,GAAM;QACd,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,OAAO;YACH,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9C,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvC,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACjD,CAAC;IACN,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,EAAK;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,GAAG,EAAE,CAAC;YACN,OAAO,GAAG,CAAC;QACf,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC7C,OAAO,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,EAAK;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,EAAK;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED,uEAAuE;IACvE,UAAU,CAAC,EAAK,EAAE,aAAa,GAAG,IAAI;QAClC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,aAAa,EAAE,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,EAAE,IAAI,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC;IAChB,CAAC;IAKD,gGAAgG;IAChG,MAAM,CAAC,EAAK;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IAC/F,CAAC;IAQD,IAAI,CAAC,UAAmB,KAAK;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACzC,OAAO,OAAO;YACV,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAQD,UAAU,CAAC,UAAmB,KAAK;QAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,IAAI,CAAC,EAAE,EAAE,CAAC;YACN,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,CAAC,QAAQ,CAAC;YACb,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;gBAC7B,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;QACL,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAED,wEAAwE;IAExE,sGAAsG;IACtG,UAAU,CAAC,EAAK;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjC,CAAC;IAED,2FAA2F;IAC3F,mBAAmB,CAAC,EAAK,EAAE,KAAe;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;IAChD,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACJ,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACL,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,OAAO,EAAE,CAAC;QACd,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,qDAAqD;IACrD,KAAK;QACD,EAAE,IAAI,CAAC,QAAQ,CAAC;QAChB,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;QAE7B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAaD,mDAAmD;IACzC,IAAI,CAAC,GAAW,EAAE,IAA0B,EAAE,OAA+B,EAAE,SAA8B;QACnH,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1D,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAC7D,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,gFAAgF;IACtE,SAAS,CAAC,GAAW,EAAE,MAAe;QAC5C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,yEAAyE;IAC/D,UAAU,CAAC,GAAW,EAAE,OAA0B;QACxD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,uEAAuE;IAC7D,WAAW,CAAC,GAAW,EAAE,GAAa;QAC5C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,qDAAqD;IAC3C,aAAa,CAAC,IAAY;QAChC,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED,uDAAuD;IAC7C,eAAe,CAAC,GAAW;QACjC,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;QACxD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,oFAAoF;IAC1E,aAAa,CAAC,GAAa;QACjC,OAAO,GAAG,CAAC;IACf,CAAC;IAED,0DAA0D;IAChD,MAAM,CAAC,QAAQ,CAAI,GAAW,EAAE,GAAyB,EAAE,GAAM;QACvE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACJ,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;CACJ"}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/core.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAI9C;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAgB,gBAA4E,SAAQ,QAAQ;IA6BvF;IACA;IA5BvB,0CAA0C;IACvB,WAAW,CAAmC;IAEjE,gEAAgE;IAC7C,YAAY,CAA6B;IAE5D,kCAAkC;IACf,aAAa,CAAsB;IAEtD,mEAAmE;IAChD,WAAW,CAA2C;IAEzE,oEAAoE;IACjD,UAAU,CAA6B;IAE1D,qEAAqE;IAClD,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;IAE3D;;;OAGG;IACgB,oBAAoB,GAAG,IAAI,GAAG,EAAiC,CAAC;IAEzE,QAAQ,GAAG,CAAC,CAAC;IAEvB,YACuB,UAAsC,EACtC,SAAsC;QAEzD,KAAK,EAAE,CAAC;QAHW,eAAU,GAAV,UAAU,CAA4B;QACtC,cAAS,GAAT,SAAS,CAA6B;QAIzD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,uBAAuB,EAAE,CAAC;QACpD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChD,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,sBAAsB,EAAE,CAAC;QAClD,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChD,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,oBAAoB,EAAE,CAAC;IAClD,CAAC;IAED,wEAAwE;IAExE;;;;;;;OAOG;IACH,IAAW,YAAY,KAAa,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;IAEtE,4DAA4D;IAC5D,IAAW,WAAW,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAElE,gFAAgF;IAChF,IAAW,aAAa,KAAa,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC;IAEpE,+EAA+E;IAC/E,IAAW,YAAY;QACnB,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,KAAK,EAAE,CAAC;YACZ,CAAC;QACL,CAAC;QACD,OAAO,KAAK,CAAC;IACjB,CAAC;IAED,wEAAwE;IAExE;;;;;OAKG;IACO,uBAAuB;QAC7B,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,CAAC;IAED;;;;;OAKG;IACO,qBAAqB;QAC3B,OAAO,IAAI,GAAG,EAAyB,CAAC;IAC5C,CAAC;IAED;;;;;OAKG;IACO,sBAAsB;QAC5B,OAAO,IAAI,GAAG,EAAmB,CAAC;IACtC,CAAC;IAED;;;;;OAKG;IACO,qBAAqB;QAC3B,OAAO,IAAI,GAAG,EAAiC,CAAC;IACpD,CAAC;IAED;;;;;OAKG;IACO,oBAAoB;QAC1B,OAAO,IAAI,GAAG,EAAmB,CAAC;IACtC,CAAC;IAED,wEAAwE;IAE9D,GAAG,CAAC,CAAI;QACd,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACjE,CAAC;QAED,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACxB,OAAO,CAAC,CAAC;QACb,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QAC/D,CAAC;QAED,OAAO,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAC9B,CAAC;IAES,aAAa,CAAC,IAAwB;QAC5C,OAAO,iBAAiB,IAAI,IAAI,GAAG,GAAG,CAAC;IAC3C,CAAC;IAED,wEAAwE;IAExE;;;;;;;;;;OAUG;IACH,OAAO,CAAC,GAAM;QACV,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,OAAO;YACH,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,YAAY,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;YAC1D,IAAI,QAAQ;gBACR,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACxB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACnC,CAAC;YACD,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9C,6CAA6C;YAC7C,IAAI,YAAY;gBACZ,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;gBACnC,OAAO,GAAG,IAAI,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACjD,CAAC;YACD,IAAI,SAAS;gBACT,MAAM,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;gBACjC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YACtC,CAAC;YACD,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvC,OAAO;gBACH,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAC7B,CAAC;SACJ,CAAC;IACN,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,GAAM;QACd,4DAA4D;QAC5D,MAAM,IAAI,GAAG,IAAI,CAAC;QAClB,OAAO;YACH,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC9C,IAAI,OAAO,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACvC,IAAI,SAAS,KAAK,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACjD,CAAC;IACN,CAAC;IAED;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAK;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACvC,IAAI,GAAG,EAAE,CAAC;YACN,OAAO,GAAG,CAAC;QACf,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;QAC7C,OAAO,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,UAAU,CAAC,EAAK;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,OAAO,KAAK,CAAC;QACjB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,EAAK;QACd,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED,sHAAsH;IACtH,UAAU,CAAC,EAAK,EAAE,aAAa,GAAG,IAAI;QAClC,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC3C,IAAI,aAAa,EAAE,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QACD,MAAM,MAAM,GAAG,IAAI,IAAI,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,qBAAqB,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC;IAClB,CAAC;IAmBD,gGAAgG;IAChG,MAAM,CAAC,EAAK;QACR,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IAC/F,CAAC;IAQD,IAAI,CAAC,UAAmB,KAAK;QACzB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC;QACzC,OAAO,OAAO;YACV,CAAC,CAAC,QAAQ;YACV,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAQD,UAAU,CAAC,UAAmB,KAAK;QAC/B,MAAM,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,IAAI,CAAC,EAAE,EAAE,CAAC;YACN,OAAO,IAAI,CAAC;QAChB,CAAC;QAED,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO,KAAK,CAAC,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,CAAC,QAAQ,CAAC;YACb,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;gBAC7B,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC;YAClB,CAAC;QACL,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IAED,wEAAwE;IAExE,sGAAsG;IACtG,UAAU,CAAC,EAAK;QACZ,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED,mLAAmL;IACnL,GAAG,CAAC,EAAK,EAAE,KAAQ;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IAED;;OAEG;IACH,mBAAmB,CAAC,EAAK,EAAE,KAAQ;QAC/B,OAAO,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,QAAQ;QACJ,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;YACxC,IAAI,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC7B,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAC3B,CAAC;QACL,CAAC;QAED,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;YAC7B,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,CAAC,oBAAoB,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACtC,OAAO,EAAE,CAAC;QACd,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;IAED,qDAAqD;IACrD,KAAK;QACD,EAAE,IAAI,CAAC,QAAQ,CAAC;QAChB,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;QAE7B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC1B,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,oBAAoB,CAAC,KAAK,EAAE,CAAC;IACtC,CAAC;IAgBD,mDAAmD;IACzC,IAAI,CAAC,GAAW,EAAE,IAAmB,EAAE,OAA+B,EAAE,SAA8B;QAC5G,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1D,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;QAC7D,gBAAgB,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED,gFAAgF;IACtE,SAAS,CAAC,GAAW,EAAE,MAAe;QAC5C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,CAAC;QAC/C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAED,yEAAyE;IAC/D,UAAU,CAAC,GAAW,EAAE,OAA8B;QAC5D,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,uEAAuE;IAC7D,WAAW,CAAC,GAAW,EAAE,GAAM;QACrC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED,qDAAqD;IAC3C,aAAa,CAAC,IAAY;QAChC,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED,uDAAuD;IAC7C,eAAe,CAAC,GAAW;QACjC,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;QACxD,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACtC,CAAC;IAED,qHAAqH;IAC3G,iBAAiB,CAAC,IAAY;QACpC,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,GAAG,CAAC,CAAC;IAC5D,CAAC;IAED,oFAAoF;IAC1E,aAAa,CAAC,GAAM;QAC1B,OAAO,GAAG,CAAC;IACf,CAAC;IAED,0DAA0D;IAChD,MAAM,CAAC,QAAQ,CAAI,GAAW,EAAE,GAAyB,EAAE,GAAM;QACvE,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YACpB,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACpB,CAAC;aAAM,CAAC;YACJ,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;CACJ"}

package/esm/structures/promiseCache/types.js

@@ -1,9 +1,9 @@
 export var DeferredGetter;
 (function (DeferredGetter) {
-    const _resolvedPromise = Promise.resolve(null);
+    const _resolvedPromise = Promise.resolve(undefined);
     /** Empty resolved value. */
     DeferredGetter.Empty = {
-        get current() { return null; },
+        get current() { return undefined; },
         get promise() { return _resolvedPromise; },
         get isLoading() { return false; },
         get error() { return null; },

package/esm/structures/promiseCache/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/types.ts"],"names":[],"mappings":"AAgBA,MAAM,KAAW,cAAc,CAU9B;AAVD,WAAiB,cAAc;IAC3B,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAO,IAAI,CAAC,CAAC;IAErD,4BAA4B;IACf,oBAAK,GAAG;QACjB,IAAI,OAAO,KAAW,OAAO,IAAI,CAAC,CAAC,CAAC;QACpC,IAAI,OAAO,KAAoB,OAAO,gBAAgB,CAAC,CAAC,CAAC;QACzD,IAAI,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;KACA,CAAC;AACrC,CAAC,EAVgB,cAAc,KAAd,cAAc,QAU9B"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/types.ts"],"names":[],"mappings":"AAmBA,MAAM,KAAW,cAAc,CAU9B;AAVD,WAAiB,cAAc;IAC3B,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAY,SAAS,CAAC,CAAC;IAE/D,4BAA4B;IACf,oBAAK,GAAG;QACjB,IAAI,OAAO,KAAgB,OAAO,SAAS,CAAC,CAAC,CAAC;QAC9C,IAAI,OAAO,KAAyB,OAAO,gBAAgB,CAAC,CAAC,CAAC;QAC9D,IAAI,SAAS,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC;QACjC,IAAI,KAAK,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC;KACC,CAAC;AACtC,CAAC,EAVgB,cAAc,KAAd,cAAc,QAU9B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zajno/common",
-  "version": "2.8.8",
+  "version": "2.8.10",
   "description": "Zajno's re-usable utilities for JS/TS projects",
   "private": false,
   "type": "module",

package/types/functions/safe.d.ts

@@ -2,4 +2,11 @@ import type { Nullable } from '../types/index.js';
 type LaxPromise<T> = Promise<T> | T | void;
 export declare function catchPromise(promise: LaxPromise<any>, errorCb?: (err: any) => void): void;
 export declare function wrapAsync<T, TArgs extends any[]>(fn: Nullable<(...args: TArgs) => LaxPromise<T>>, errorCb?: (err: any) => void): (...args: TArgs) => void;
+/**
+ * Formats an unknown caught value into a human-readable string.
+ *
+ * Useful at presentation boundaries where a display string is needed.
+ * Prefer keeping the raw error for programmatic handling (instanceof checks, .cause, etc.).
+ */
+export declare function formatError(err: unknown): string;
 export {};

package/types/lazy/lazy.d.ts

@@ -16,7 +16,9 @@ export declare class Lazy<T> implements ILazy<T>, IDisposable, IResettableModel
     get hasValue(): boolean;
     get value(): T;
     get currentValue(): T | undefined;
-    get error(): string | null;
+    get error(): unknown;
+    /** @deprecated Use {@link error} instead. */
+    get errorMessage(): string | null;
     /** Override me: additional way to make sure instance is valid */
     protected get isValid(): boolean;
     /** Provides custom cleanup logic when the instance is reset or disposed. */
@@ -30,5 +32,4 @@ export declare class Lazy<T> implements ILazy<T>, IDisposable, IResettableModel
     reset(): void;
     dispose(): void;
     private ensureInstance;
-    protected parseError(err: unknown): string;
 }

package/types/lazy/promise.d.ts

@@ -23,8 +23,10 @@ export declare class LazyPromise<T, TInitial extends T | undefined = undefined>
     /** Current loading state: true = loading, false = loaded, null = not started */
     get isLoading(): boolean | null;
     get hasValue(): boolean;
-    get error(): string | null;
-    get promise(): Promise<T>;
+    get error(): unknown;
+    /** @deprecated Use {@link error} instead. */
+    get errorMessage(): string | null;
+    get promise(): Promise<T | TInitial>;
     get value(): T | TInitial;
     /** Returns current value without triggering loading. */
     get currentValue(): T | TInitial;
@@ -77,7 +79,7 @@ export declare class LazyPromise<T, TInitial extends T | undefined = undefined>
      *
      * @returns Promise resolving to the refreshed value
      */
-    refresh(): Promise<T>;
+    refresh(): Promise<T | TInitial>;
     reset(): void;
     dispose(): void;
     private ensureInstanceLoading;
@@ -86,5 +88,4 @@ export declare class LazyPromise<T, TInitial extends T | undefined = undefined>
     protected updateState(isLoading: boolean | null): void;
     protected setError(err: unknown): void;
     protected clearError(): void;
-    protected parseError(err: unknown): string;
 }