@zajno/common 2.8.7 → 2.8.8

package/esm/structures/promiseCache/cache.js

@@ -0,0 +1,282 @@
+import { DebounceProcessor } from '../../functions/debounce.js';
+import { PromiseCacheCore } from './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.
+*/
+export class PromiseCache extends 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 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 = null;
+            }
+            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);
+                res = this.prepareResult(res);
+                if (!fetchFailed) {
+                    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;
+            }
+        }
+    }
+}
+//# sourceMappingURL=cache.js.map

package/esm/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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"}

package/esm/structures/promiseCache/core.js

@@ -0,0 +1,297 @@
+import { Loggable } from '../../logger/loggable.js';
+import { Model } from '../../models/Model.js';
+/**
+ * Core base class for PromiseCache. Provides basic cache operations, hooks, and `pure_create*` methods.
+ *
+ * This class handles:
+ *  - item storage and retrieval
+ *  - loading state tracking
+ *  - promise caching
+ *  - error storage
+ *  - timestamps for cached items
+ *  - direct cache manipulation (invalidate, updateValueDirectly, clear)
+ *  - keys iteration
+ *
+ * Subclasses are expected to implement fetching logic, invalidation policies, etc.
+ */
+export class PromiseCacheCore extends Loggable {
+    keyAdapter;
+    keyParser;
+    /** Stores resolved items in map by id. */
+    _itemsCache;
+    /** Stores items loading state (loading or not) in map by id. */
+    _itemsStatus;
+    /** Stores items loading count. */
+    _loadingCount;
+    /** Stores items Promises state (if still loading) in map by id. */
+    _fetchCache;
+    /** Stores last errors by key. Observable-friendly via IMapModel. */
+    _errorsMap;
+    /** Stores items resolve timestamps (for expiration) in map by id. */
+    _timestamps = new Map();
+    _version = 0;
+    constructor(keyAdapter, keyParser) {
+        super();
+        this.keyAdapter = keyAdapter;
+        this.keyParser = keyParser;
+        this._loadingCount = this.pure_createLoadingCount();
+        this._itemsCache = this.pure_createItemsCache();
+        this._itemsStatus = this.pure_createItemsStatus();
+        this._fetchCache = this.pure_createFetchCache();
+        this._errorsMap = this.pure_createErrorsMap();
+    }
+    // ─── Counts ──────────────────────────────────────────────────────────
+    /** Returns the number of items currently being fetched. */
+    get loadingCount() { return this._loadingCount.value; }
+    /** Returns the number of cached items (resolved values). */
+    get cachedCount() { return this._itemsCache.size; }
+    /** Returns the number of in-flight promises (items currently being fetched). */
+    get promisesCount() { return this._fetchCache.size; }
+    /** Returns the number of cached items that are currently invalid (expired). */
+    get invalidCount() {
+        let count = 0;
+        for (const key of this._itemsCache.keys()) {
+            if (this.getIsInvalidated(key)) {
+                count++;
+            }
+        }
+        return count;
+    }
+    // ─── Pure factory methods (override for observability) ───────────────
+    /**
+     * @pure @const
+     * Creates a model for tracking the loading state. Override to inject own instance, e.g. for observability.
+     *
+     * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
+     */
+    pure_createLoadingCount() {
+        return new Model(0);
+    }
+    /**
+     * @pure @const
+     * Creates a map for caching resolved items by id. Override to inject own instance, e.g. for observability.
+     *
+     * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
+     */
+    pure_createItemsCache() {
+        return new Map();
+    }
+    /**
+     * @pure @const
+     * Creates a map for tracking the loading state of items by id. Override to inject own instance, e.g. for observability.
+     *
+     * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
+     */
+    pure_createItemsStatus() {
+        return new Map();
+    }
+    /**
+     * @pure @const
+     * Creates a map for caching promises of items by id. Override to inject own instance, e.g. for observability.
+     *
+     * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
+     */
+    pure_createFetchCache() {
+        return new Map();
+    }
+    /**
+     * @pure @const
+     * Creates a map for storing last errors by key. Override to inject own instance, e.g. for observability.
+     *
+     * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
+     */
+    pure_createErrorsMap() {
+        return new Map();
+    }
+    // ─── Key handling ────────────────────────────────────────────────────
+    _pk(k) {
+        if (k == null) {
+            throw new Error('PromiseCache: null keys are not supported');
+        }
+        if (typeof k === 'string') {
+            return k;
+        }
+        if (!this.keyAdapter) {
+            throw new Error('Provide key adapter for non-string keys');
+        }
+        return this.keyAdapter(k);
+    }
+    getLoggerName(name) {
+        return `[PromiseCache:${name || '?'}]`;
+    }
+    // ─── Public API: reading ─────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    getDeferred(key) {
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const self = this;
+        return {
+            get current() { return self.getCurrent(key); },
+            get promise() { return self.get(key); },
+            get isLoading() { return self.getIsLoading(key); },
+            get error() { return self.getLastError(key); },
+        };
+    }
+    /**
+     * Returns the loading state of an item.
+     *
+     * @returns true if loading, false if loading completed, undefined if loading was not started yet.
+     */
+    getIsLoading(id) {
+        const key = this._pk(id);
+        const res = this._itemsStatus.get(key);
+        if (res) {
+            return res;
+        }
+        const isInvalid = this.getIsInvalidated(key);
+        return isInvalid ? undefined : res;
+    }
+    /**
+     * Returns whether the cached item for the specified key is valid (not expired and not invalidated by callback).
+     *
+     * @returns `true` if the item is cached and valid, `false` if the item is invalidated or not cached.
+     */
+    getIsValid(id) {
+        const key = this._pk(id);
+        if (!this._itemsCache.has(key)) {
+            return false;
+        }
+        return !this.getIsInvalidated(key);
+    }
+    /**
+     * Returns the last error that occurred during fetching for the specified key.
+     *
+     * @returns The raw error, or null if no error.
+     */
+    getLastError(id) {
+        const key = this._pk(id);
+        return this._errorsMap.get(key) ?? null;
+    }
+    /** Returns the current cached value, optionally triggering a fetch. */
+    getCurrent(id, initiateFetch = true) {
+        const { item, key } = this._getCurrent(id);
+        if (initiateFetch) {
+            this.get(id);
+        }
+        this.logger.log(key, 'getCurrent: returns', item);
+        return item;
+    }
+    /** Returns true if the item is cached or fetching was initiated. Does not initiate fetching. */
+    hasKey(id) {
+        const key = this._pk(id);
+        return this._itemsCache.get(key) !== undefined || this._itemsStatus.get(key) !== undefined;
+    }
+    keys(iterate = false) {
+        const iterator = this._itemsCache.keys();
+        return iterate
+            ? iterator
+            : Array.from(iterator);
+    }
+    keysParsed(iterate = false) {
+        const kp = this.keyParser;
+        if (!kp) {
+            return null;
+        }
+        const keysIterator = this.keys(true);
+        if (!iterate) {
+            return Array.from(keysIterator, key => kp(key));
+        }
+        return (function* () {
+            for (const key of keysIterator) {
+                yield kp(key);
+            }
+        })();
+    }
+    // ─── Public API: mutation ────────────────────────────────────────────
+    /** Instantly invalidates the cached item for the specified id, like it was never fetched/accessed. */
+    invalidate(id) {
+        const key = this._pk(id);
+        this._set(key, undefined, undefined, undefined);
+        this._errorsMap.delete(key);
+        this._timestamps.delete(key);
+    }
+    /** Updates the cached value for the specified id directly, like it was fetched already. */
+    updateValueDirectly(id, value) {
+        const key = this._pk(id);
+        this._set(key, value, undefined, undefined);
+    }
+    /**
+     * Iterates over all cached items and removes those that are invalid (expired).
+     *
+     * @returns The number of items that were removed.
+     */
+    sanitize() {
+        let removed = 0;
+        const keysToRemove = [];
+        for (const key of this._itemsCache.keys()) {
+            if (this.getIsInvalidated(key)) {
+                keysToRemove.push(key);
+            }
+        }
+        for (const key of keysToRemove) {
+            this._set(key, undefined, undefined, undefined);
+            this._errorsMap.delete(key);
+            this._timestamps.delete(key);
+            removed++;
+        }
+        return removed;
+    }
+    /** Clears the cache and resets the loading state. */
+    clear() {
+        ++this._version;
+        this._loadingCount.value = 0;
+        this._itemsCache.clear();
+        this._itemsStatus.clear();
+        this._fetchCache.clear();
+        this._errorsMap.clear();
+        this._timestamps.clear();
+    }
+    /** @internal updates all caches states at once. */
+    _set(key, item, promise, isLoading) {
+        PromiseCacheCore._setMapX(key, this._fetchCache, promise);
+        PromiseCacheCore._setMapX(key, this._itemsStatus, isLoading);
+        PromiseCacheCore._setMapX(key, this._itemsCache, item);
+    }
+    /** Updates the loading status for the specified key. Override to add a hook. */
+    setStatus(key, status) {
+        this.logger.log(key, 'status update:', status);
+        this._itemsStatus.set(key, status);
+    }
+    /** Updates the promise for the specified key. Override to add a hook. */
+    setPromise(key, promise) {
+        this._fetchCache.set(key, promise);
+    }
+    /** Stores the result for the specified key. Override to add a hook. */
+    storeResult(key, res) {
+        this._itemsCache.set(key, res);
+        this._timestamps.set(key, Date.now());
+        this._errorsMap.delete(key);
+    }
+    /** Hooks into the fetch process before it starts. */
+    onBeforeFetch(_key) {
+        this._loadingCount.value = this._loadingCount.value + 1;
+    }
+    /** Hooks into the fetch process after it completes. */
+    onFetchComplete(key) {
+        this._loadingCount.value = this._loadingCount.value - 1;
+        this._fetchCache.delete(key);
+        this._itemsStatus.set(key, false);
+    }
+    /** Hooks into the result preparation process, before it's stored into the cache. */
+    prepareResult(res) {
+        return res;
+    }
+    /** @internal Helper to set or delete a value in a map. */
+    static _setMapX(key, map, val) {
+        if (val === undefined) {
+            map.delete(key);
+        }
+        else {
+            map.set(key, val);
+        }
+    }
+}
+//# sourceMappingURL=core.js.map

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

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

package/esm/structures/promiseCache/index.js

@@ -0,0 +1,4 @@
+export * from './core.js';
+export * from './types.js';
+export * from './cache.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/structures/promiseCache/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}

package/esm/structures/promiseCache/types.js

@@ -0,0 +1,12 @@
+export var DeferredGetter;
+(function (DeferredGetter) {
+    const _resolvedPromise = Promise.resolve(null);
+    /** Empty resolved value. */
+    DeferredGetter.Empty = {
+        get current() { return null; },
+        get promise() { return _resolvedPromise; },
+        get isLoading() { return false; },
+        get error() { return null; },
+    };
+})(DeferredGetter || (DeferredGetter = {}));
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zajno/common",
-  "version": "2.8.7",
+  "version": "2.8.8",
   "description": "Zajno's re-usable utilities for JS/TS projects",
   "private": false,
   "type": "module",
@@ -151,6 +151,12 @@
       "require": "./cjs/structures/path/utils/index.js",
       "default": "./cjs/structures/path/utils/index.js"
     },
+    "./structures/promiseCache": {
+      "types": "./types/structures/promiseCache/index.d.ts",
+      "import": "./esm/structures/promiseCache/index.js",
+      "require": "./cjs/structures/promiseCache/index.js",
+      "default": "./cjs/structures/promiseCache/index.js"
+    },
     "./types": {
       "types": "./types/types/index.d.ts",
       "import": "./esm/types/index.js",