@zajno/common 2.8.7 → 2.8.9

package/cjs/functions/safe.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.catchPromise = catchPromise;
 exports.wrapAsync = wrapAsync;
+exports.formatError = formatError;
 function catchPromise(promise, errorCb) {
     Promise.resolve(promise).catch(err => errorCb?.(err));
 }
@@ -12,4 +13,19 @@ function wrapAsync(fn, errorCb) {
         }
     };
 }
+/**
+ * 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.).
+ */
+function formatError(err) {
+    if (typeof err === 'string') {
+        return err;
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err) || 'Unknown error';
+}
 //# sourceMappingURL=safe.js.map

package/cjs/functions/safe.js.map

@@ -1 +1 @@
-{"version":3,"file":"safe.js","sourceRoot":"","sources":["../../../src/functions/safe.ts"],"names":[],"mappings":";;AAIA,oCAEC;AAED,8BAMC;AAVD,SAAgB,YAAY,CAAC,OAAwB,EAAE,OAA4B;IAC/E,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,SAAgB,SAAS,CAAyB,EAA+C,EAAE,OAA4B;IAC3H,OAAO,CAAC,GAAG,IAAW,EAAE,EAAE;QACtB,IAAI,EAAE,EAAE,CAAC;YACL,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;IACL,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"safe.js","sourceRoot":"","sources":["../../../src/functions/safe.ts"],"names":[],"mappings":";;AAIA,oCAEC;AAED,8BAMC;AAQD,kCAQC;AA1BD,SAAgB,YAAY,CAAC,OAAwB,EAAE,OAA4B;IAC/E,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,CAAC;AAED,SAAgB,SAAS,CAAyB,EAA+C,EAAE,OAA4B;IAC3H,OAAO,CAAC,GAAG,IAAW,EAAE,EAAE;QACtB,IAAI,EAAE,EAAE,CAAC;YACL,YAAY,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QACvC,CAAC;IACL,CAAC,CAAC;AACN,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,GAAY;IACpC,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,GAAG,CAAC;IACf,CAAC;IACD,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,OAAO,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC;AAC1C,CAAC"}

package/cjs/lazy/lazy.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Lazy = void 0;
 const disposer_js_1 = require("../functions/disposer.js");
+const safe_js_1 = require("../functions/safe.js");
 /**
  * Synchronous lazy-loading container that initializes a value on first access.
  * The value is cached until reset or expired. Supports custom disposal and cache expiration.
@@ -22,6 +23,10 @@ class Lazy {
     }
     get currentValue() { return this._instance; }
     get error() { return this._error; }
+    /** @deprecated Use {@link error} instead. */
+    get errorMessage() {
+        return this._error != null ? (0, safe_js_1.formatError)(this._error) : null;
+    }
     /** Override me: additional way to make sure instance is valid */
     get isValid() {
         if (!this.hasValue) {
@@ -81,17 +86,8 @@ class Lazy {
             this.setInstance(res);
         }
         catch (e) {
-            this._error = this.parseError(e);
-        }
-    }
-    parseError(err) {
-        if (typeof err === 'string') {
-            return err;
-        }
-        if (err instanceof Error) {
-            return err.message;
+            this._error = e;
         }
-        return String(err) || 'Unknown error';
     }
 }
 exports.Lazy = Lazy;

package/cjs/lazy/lazy.js.map

@@ -1 +1 @@
-{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lazy.js","sourceRoot":"","sources":["../../../src/lazy/lazy.ts"],"names":[],"mappings":"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"}

package/cjs/lazy/light.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createLazy = createLazy;
+const safe_js_1 = require("../functions/safe.js");
 function createLazy(factory) {
     const _factory = factory;
     let _instance = undefined;
@@ -13,7 +14,7 @@ function createLazy(factory) {
                     _instance = _factory();
                 }
                 catch (e) {
-                    _error = e instanceof Error ? e.message : String(e);
+                    _error = e;
                     throw e;
                 }
             }
@@ -22,6 +23,8 @@ function createLazy(factory) {
         get currentValue() { return _instance; },
         get hasValue() { return _instance !== undefined; },
         get error() { return _error; },
+        /** @deprecated Use {@link error} instead. */
+        get errorMessage() { return _error != null ? (0, safe_js_1.formatError)(_error) : null; },
         reset: () => {
             _instance = undefined;
             _error = null;

package/cjs/lazy/light.js.map

@@ -1 +1 @@
-{"version":3,"file":"light.js","sourceRoot":"","sources":["../../../src/lazy/light.ts"],"names":[],"mappings":";;AAIA,gCA6BC;AA7BD,SAAgB,UAAU,CAAI,OAAgB;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC;IACzB,IAAI,SAAS,GAAkB,SAAS,CAAC;IACzC,IAAI,MAAM,GAAkB,IAAI,CAAC;IAEjC,MAAM,GAAG,GAA8C;QACnD,IAAI,KAAK;YACL,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,GAAG,IAAI,CAAC;gBACd,IAAI,CAAC;oBACD,SAAS,GAAG,QAAQ,EAAE,CAAC;gBAC3B,CAAC;gBAAC,OAAO,CAAU,EAAE,CAAC;oBAClB,MAAM,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;oBACpD,MAAM,CAAC,CAAC;gBACZ,CAAC;YACL,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,YAAY,KAAK,OAAO,SAAS,CAAC,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,MAAM,CAAC,CAAC,CAAC;QAC9B,KAAK,EAAE,GAAG,EAAE;YACR,SAAS,GAAG,SAAS,CAAC;YACtB,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;KAC7B,CAAC;IAEF,OAAO,GAAG,CAAC;AACf,CAAC"}
+{"version":3,"file":"light.js","sourceRoot":"","sources":["../../../src/lazy/light.ts"],"names":[],"mappings":";;AAKA,gCA+BC;AAnCD,kDAAmD;AAInD,SAAgB,UAAU,CAAI,OAAgB;IAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC;IACzB,IAAI,SAAS,GAAkB,SAAS,CAAC;IACzC,IAAI,MAAM,GAAY,IAAI,CAAC;IAE3B,MAAM,GAAG,GAA8C;QACnD,IAAI,KAAK;YACL,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,GAAG,IAAI,CAAC;gBACd,IAAI,CAAC;oBACD,SAAS,GAAG,QAAQ,EAAE,CAAC;gBAC3B,CAAC;gBAAC,OAAO,CAAU,EAAE,CAAC;oBAClB,MAAM,GAAG,CAAC,CAAC;oBACX,MAAM,CAAC,CAAC;gBACZ,CAAC;YACL,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,IAAI,YAAY,KAAK,OAAO,SAAS,CAAC,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC;QAClD,IAAI,KAAK,KAAK,OAAO,MAAM,CAAC,CAAC,CAAC;QAC9B,6CAA6C;QAC7C,IAAI,YAAY,KAAK,OAAO,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,IAAA,qBAAW,EAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,KAAK,EAAE,GAAG,EAAE;YACR,SAAS,GAAG,SAAS,CAAC;YACtB,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE;KAC7B,CAAC;IAEF,OAAO,GAAG,CAAC;AACf,CAAC"}

package/cjs/lazy/promise.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LazyPromise = void 0;
 const disposer_js_1 = require("../functions/disposer.js");
+const safe_js_1 = require("../functions/safe.js");
 /**
  * Asynchronous lazy-loading container that initializes via a promise-based factory.
  * Handles concurrent operations with "latest wins" semantics: multiple refreshes are automatically
@@ -29,6 +30,10 @@ class LazyPromise {
     get isLoading() { return this._state; }
     get hasValue() { return this._state === false; }
     get error() { return this._error; }
+    /** @deprecated Use {@link error} instead. */
+    get errorMessage() {
+        return this._error != null ? (0, safe_js_1.formatError)(this._error) : null;
+    }
     get promise() {
         this.ensureInstanceLoading();
         return this._promise;
@@ -224,20 +229,11 @@ class LazyPromise {
         this._state = isLoading;
     }
     setError(err) {
-        this._error = this.parseError(err);
+        this._error = err;
     }
     clearError() {
         this._error = null;
     }
-    parseError(err) {
-        if (typeof err === 'string') {
-            return err;
-        }
-        if (err instanceof Error) {
-            return err.message;
-        }
-        return String(err) || 'Unknown error';
-    }
 }
 exports.LazyPromise = LazyPromise;
 //# sourceMappingURL=promise.js.map

package/cjs/lazy/promise.js.map

@@ -1 +1 @@
-{"version":3,"file":"promise.js","sourceRoot":"","sources":["../../../src/lazy/promise.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"promise.js","sourceRoot":"","sources":["../../../src/lazy/promise.ts"],"names":[],"mappings":"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"}

package/cjs/structures/promiseCache/cache.js

@@ -0,0 +1,286 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseCache = void 0;
+const debounce_js_1 = require("../../functions/debounce.js");
+const core_js_1 = require("./core.js");
+const BATCHING_DELAY = 200;
+/**
+ * Caches items by a key (string or another type) which are resolved by an async fetcher (`Promise`).
+ *
+ * Supports:
+ *  - custom key adapter and parser for non-string keys.
+ *  - direct manual cache manipulation.
+ *  - batching of fetches.
+ *  - auto-invalidation of cached items (time-based, callback-based, max items).
+ *  - error tracking per key.
+*/
+class PromiseCache extends core_js_1.PromiseCacheCore {
+    fetcher;
+    _batch = null;
+    _invalidationConfig = null;
+    _onError = null;
+    /**
+     * Creates an instance of PromiseCache.
+     * @param fetcher Function to fetch data by key.
+     * @param keyAdapter Optional function to adapt non-string keys to strings.
+     * @param keyParser Optional function to parse string keys back to their original type.
+     */
+    constructor(fetcher, keyAdapter, keyParser) {
+        super(keyAdapter, keyParser);
+        this.fetcher = fetcher;
+    }
+    // ─── Configuration ───────────────────────────────────────────────────
+    /**
+     * Provide a fetcher function that takes multiple ids and returns multiple results at once. Will be called with a slight delay to allow multiple ids to be collected.
+     *
+     * Warning: resolved array should have the same order as the input array.
+     *
+     * When provided, effectively replaces the main fetcher; but in case of fail, fallbacks to the main fetcher.
+    */
+    useBatching(fetcher, delay = BATCHING_DELAY) {
+        this._batch = fetcher ? new debounce_js_1.DebounceProcessor(fetcher, delay) : null;
+        return this;
+    }
+    /**
+     * Enables auto-invalidation of cached items by time.
+     *
+     * 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.
+    */
+    useInvalidationTime(ms, keepInstance = false) {
+        return this.useInvalidation(ms != null ? { expirationMs: ms, keepInstance } : null);
+    }
+    /**
+     * Configures advanced invalidation policy.
+     *
+     * The config object is stored as-is (not destructured), so getter-based fields will be re-evaluated on each access.
+     * This allows consumers to provide dynamic invalidation policies.
+     *
+     * @param config The invalidation configuration. See {@link InvalidationConfig} for details.
+     */
+    useInvalidation(config) {
+        this._invalidationConfig = config;
+        return this;
+    }
+    /**
+     * Sets an error callback that is called when a fetcher fails.
+     *
+     * @param callback The callback to call on error. Receives the original key and the raw error.
+     */
+    useOnError(callback) {
+        this._onError = callback;
+        return this;
+    }
+    // ─── 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.
+     *
+     * Consequent calls will return the same promise until it resolves.
+     *
+     * @param id The id of the item.
+     * @returns A promise that resolves to the result, whether it's cached or freshly fetched.
+     */
+    get(id) {
+        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)' : '');
+            return Promise.resolve(item);
+        }
+        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);
+        this.setPromise(key, promise);
+        return promise;
+    }
+    /** Clears the cache and resets the loading state. */
+    clear() {
+        this._batch?.clear();
+        super.clear();
+    }
+    // ─── Protected overrides ─────────────────────────────────────────────
+    _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,
+            key,
+            isInvalid,
+        };
+    }
+    getIsInvalidated(key) {
+        const config = this._invalidationConfig;
+        if (!config) {
+            return false;
+        }
+        const ts = this._timestamps.get(key);
+        // Check time-based expiration
+        const expirationMs = config.expirationMs;
+        if (expirationMs != null && expirationMs > 0 && ts != null) {
+            if (Date.now() - ts > expirationMs) {
+                return true;
+            }
+        }
+        // Check callback-based invalidation
+        if (config.invalidationCheck) {
+            const value = this._itemsCache.get(key);
+            if (value !== undefined && config.invalidationCheck(key, value, ts ?? 0)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** @override Stores the result for the specified key, enforcing max items. */
+    storeResult(key, res) {
+        this._enforceMaxItems(key);
+        super.storeResult(key, res);
+    }
+    // ─── 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.
+     */
+    async _doFetchAsync(id, key) {
+        let isInSameVersion = true;
+        try {
+            this.onBeforeFetch(key);
+            const v = this._version;
+            let res;
+            let fetchFailed = false;
+            try {
+                res = await this.tryFetchInBatch(id);
+            }
+            catch (err) {
+                this._handleError(id, err);
+                fetchFailed = true;
+                res = undefined;
+            }
+            if (v !== this._version) {
+                isInSameVersion = false;
+                // resolve with actual result but don't store it
+                return res;
+            }
+            if (this._fetchCache.get(key) != null) {
+                this.logger.log(key, 'item\'s <promise> resolved to', res);
+                if (!fetchFailed && res !== undefined) {
+                    res = this.prepareResult(res);
+                    this.storeResult(key, res);
+                }
+            }
+            return res;
+        }
+        finally {
+            if (isInSameVersion) {
+                this.onFetchComplete(key);
+            }
+            else {
+                this.logger.log(key, 'skipping item\'s resolve due to version change ("clear()" has been called)');
+            }
+        }
+    }
+    /** Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. Throws on error. */
+    async tryFetchInBatch(id) {
+        if (!this._batch) {
+            return this.fetcher(id);
+        }
+        const res = await this._batch.push(id)
+            .catch(err => {
+            this.logger.warn('batch fetch failed', id, err);
+            return null;
+        });
+        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 res.result[res.index];
+    }
+    /** Handles a fetch error: stores it, logs it, and calls the onError callback. */
+    _handleError(id, err) {
+        const key = this._pk(id);
+        this._errorsMap.set(key, err);
+        this.logger.warn('fetcher failed', id, err);
+        if (this._onError) {
+            try {
+                this._onError(id, err);
+            }
+            catch {
+                // ignore errors in the callback
+            }
+        }
+    }
+    /**
+     * Enforces the max items limit by removing items to make room.
+     * Strategy: first removes invalid items, then oldest valid items.
+     * Items currently being fetched (in-flight) are not evicted.
+     *
+     * @param incomingKey The key of the item about to be stored (excluded from eviction).
+     */
+    _enforceMaxItems(incomingKey) {
+        const maxItems = this._invalidationConfig?.maxItems;
+        if (maxItems == null || maxItems <= 0) {
+            return;
+        }
+        // If we're under the limit, nothing to do
+        if (this._itemsCache.size < maxItems) {
+            return;
+        }
+        // Phase 1: Remove invalid items first (they're garbage anyway)
+        const invalidKeys = [];
+        for (const key of this._itemsCache.keys()) {
+            if (key === incomingKey)
+                continue;
+            if (this.getIsInvalidated(key)) {
+                invalidKeys.push(key);
+            }
+        }
+        for (const key of invalidKeys) {
+            this._set(key, undefined, undefined, undefined);
+            this._errorsMap.delete(key);
+            this._timestamps.delete(key);
+            if (this._itemsCache.size < maxItems) {
+                return;
+            }
+        }
+        // Phase 2: Remove oldest valid items (skip in-flight items)
+        while (this._itemsCache.size >= maxItems) {
+            let oldestKey = null;
+            let oldestTs = Infinity;
+            for (const [key, ts] of this._timestamps.entries()) {
+                // Don't evict the incoming key or items currently being fetched
+                if (key === incomingKey)
+                    continue;
+                if (this._fetchCache.has(key))
+                    continue;
+                if (ts < oldestTs) {
+                    oldestTs = ts;
+                    oldestKey = key;
+                }
+            }
+            if (oldestKey != null) {
+                this._set(oldestKey, undefined, undefined, undefined);
+                this._timestamps.delete(oldestKey);
+                this._errorsMap.delete(oldestKey);
+            }
+            else {
+                // No evictable items found (all are in-flight or incoming)
+                break;
+            }
+        }
+    }
+}
+exports.PromiseCache = PromiseCache;
+//# sourceMappingURL=cache.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/cache.ts"],"names":[],"mappings":"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"}