@zajno/common 2.8.7 → 2.8.9

package/esm/structures/promiseCache.js

@@ -1,395 +0,0 @@
-import { DebounceProcessor } from '../functions/debounce.js';
-import { Loggable } from '../logger/loggable.js';
-import { Model } from '../models/Model.js';
-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; },
-    };
-})(DeferredGetter || (DeferredGetter = {}));
-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.
-*/
-export class PromiseCache extends Loggable {
-    fetcher;
-    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 items resolve timestamps (for expiration) in map by id. */
-    _timestamps = new Map();
-    _batch = null;
-    _invalidationTimeMs = null;
-    _keepInstanceDuringInvalidation = false;
-    _version = 0;
-    /**
-     * 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();
-        this.fetcher = fetcher;
-        this.keyAdapter = keyAdapter;
-        this.keyParser = keyParser;
-        this._loadingCount = this.pure_createBusyCount();
-        this._itemsCache = this.pure_createItemsCache();
-        this._itemsStatus = this.pure_createItemsStatus();
-        this._fetchCache = this.pure_createFetchCache();
-    }
-    get busyCount() { return this._loadingCount.value; }
-    /**
-     * @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`.
-     *
-     * @returns A value model for the loading count.
-     */
-    pure_createBusyCount() {
-        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`.
-     *
-     * @returns A map model for the items cache.
-     */
-    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`.
-     *
-     * @returns A map model for the items loading state.
-     */
-    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`.
-     *
-     * @returns A map model for the items promises cache.
-     */
-    pure_createFetchCache() {
-        return new Map();
-    }
-    _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);
-    }
-    /**
-     * Creates a logger name for this instance.
-     * @param name The name of the cache instance.
-     * @returns The logger name.
-     */
-    getLoggerName(name) {
-        return `[PromiseCache:${name || '?'}]`;
-    }
-    /**
-     * 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.
-     *
-     * @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 will be set to `undefined` instead. Defaults to false.
-    */
-    useInvalidationTime(ms, keepInstance = false) {
-        this._invalidationTimeMs = ms;
-        this._keepInstanceDuringInvalidation = keepInstance;
-        return this;
-    }
-    /**
-     * Returns a {@link DeferredGetter} object for a specfied key.
-     *
-     * This can be used to access the current value, promise, and loading state of the item.
-     *
-     * @param key The key 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.getIsBusy(key); },
-        };
-    }
-    /**
-     * Returns the loading state of an item.
-     *
-     * @param id The id of the item.
-     * @returns The loading state of the item: true if loading, false if loading completed, undefined if loading was not started yet for the specified key.
-     */
-    getIsBusy(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 the current cached value for the specified key, without triggering a fetch.
-     * @param id The id of the item.
-     * @returns The current cached value of the item.
-     */
-    _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);
-        if (isInvalid) {
-            this.logger.log(key, 'item is invalidated');
-        }
-        return {
-            item: (isInvalid && !this._keepInstanceDuringInvalidation) ? undefined : item,
-            key,
-            isInvalid,
-        };
-    }
-    /**
-     * Returns the current cached value for the specified key, optionally triggering a fetch.
-     * @param id The id of the item.
-     * @param initiateFetch If true, will initiate a fetch if the item is not cached.
-     * @returns The current cached value of the item.
-     */
-    getCurrent(id, initiateFetch = true) {
-        const { item, key } = this._getCurrent(id);
-        if (initiateFetch) {
-            // spin fetch
-            this.get(id);
-        }
-        this.logger.log(key, 'getCurrent: returns', item);
-        return item;
-    }
-    /**
-     * 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;
-    }
-    /**
-     * 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.
-     */
-    _doFetchAsync = async (id, key) => {
-        let isInSameVersion = true;
-        try {
-            this.onBeforeFetch(key);
-            const v = this._version;
-            let res = await this.tryFetchInBatch(id);
-            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);
-                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)');
-            }
-        }
-    };
-    /**
-     * Instantly invalidates the cached item for the specified id, like it was never fetched/accessed.
-     * @param id The id of the item.
-     */
-    invalidate(id) {
-        const key = this._pk(id);
-        this._set(key, undefined, undefined, undefined);
-    }
-    /**
-     * Updates the cached value for the specified id directly, like it was fetched already. Overrides existing value, if any.
-     * @param id The id of the item.
-     * @param value The new value to cache.
-     */
-    updateValueDirectly(id, value) {
-        const key = this._pk(id);
-        this._set(key, value, undefined, undefined);
-    }
-    /** Returns true if the item is cached or fetching was initiated. Does not initiates 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);
-            }
-        })();
-    }
-    /** Clears the cache and resets the loading state. */
-    clear() {
-        ++this._version;
-        this._loadingCount.value = 0;
-        this._batch?.clear();
-        this._itemsCache.clear();
-        this._itemsStatus.clear();
-        this._fetchCache.clear();
-    }
-    /** @internal updates all caches states at once. */
-    _set(key, item, promise, busy) {
-        _setX(key, this._fetchCache, promise);
-        _setX(key, this._itemsStatus, busy);
-        _setX(key, this._itemsCache, item);
-    }
-    /**
-     * Checks if the cached item for the specified key is invalidated (expired).
-     * @param key The cache key.
-     * @returns True if the item is invalidated, false otherwise.
-     */
-    getIsInvalidated(key) {
-        if (!this._invalidationTimeMs) {
-            return false;
-        }
-        const ts = this._timestamps.get(key);
-        return ts != null && Date.now() - ts > this._invalidationTimeMs;
-    }
-    /** 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());
-    }
-    /** 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 || null;
-    }
-    /** @pure Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. */
-    async tryFetchInBatch(id) {
-        const fetchWrap = () => this.fetcher(id).catch(err => {
-            this.logger.warn('fetcher failed', id, err);
-            return null;
-        });
-        if (!this._batch) {
-            return fetchWrap();
-        }
-        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) {
-            // If we got to batch call, should we fallback to the direct one?
-            return fetchWrap();
-        }
-        return res.result[res.index];
-    }
-}
-function _setX(key, map, val) {
-    if (val === undefined) {
-        map.delete(key);
-    }
-    else {
-        map.set(key, val);
-    }
-}
-//# sourceMappingURL=promiseCache.js.map

package/esm/structures/promiseCache.js.map

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

package/types/structures/promiseCache.d.ts

@@ -1,206 +0,0 @@
-import { Loggable } from '../logger/loggable.js';
-import type { IMapModel, IValueModel } from '../models/types.js';
-/** Represents a state of a cached item. Holds a references to an actual state. */
-export type DeferredGetter<T> = {
-    /** Get current resolved value, if any, or initiates fetching. */
-    readonly current: T | null | undefined;
-    /** Returns a promise that resolves to the current or fetching value. */
-    readonly promise: Promise<T | null>;
-    /** Returns true if the item is currently being fetched. Returns undefined if fetching has not started yet. */
-    readonly isLoading: boolean | undefined;
-};
-export declare namespace DeferredGetter {
-    /** Empty resolved value. */
-    const Empty: {
-        readonly current: null;
-        readonly promise: Promise<null>;
-        readonly isLoading: boolean;
-    };
-}
-/**
- * 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.
-*/
-export declare class PromiseCache<T, K = string> extends Loggable {
-    private readonly fetcher;
-    private readonly keyAdapter?;
-    private readonly keyParser?;
-    /** Stores resolved items in map by id. */
-    protected readonly _itemsCache: IMapModel<string, T | null | undefined>;
-    /** Stores items loading state (loading or not) in map by id. */
-    protected readonly _itemsStatus: IMapModel<string, boolean>;
-    /** Stores items loading count. */
-    protected readonly _loadingCount: IValueModel<number>;
-    /** Stores items Promises state (if still loading) in map by id. */
-    private readonly _fetchCache;
-    /** Stores items resolve timestamps (for expiration) in map by id. */
-    private readonly _timestamps;
-    private _batch;
-    private _invalidationTimeMs;
-    private _keepInstanceDuringInvalidation;
-    private _version;
-    /**
-     * 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: (id: K) => Promise<T>, keyAdapter?: (K extends string ? null : (k: K) => string) | undefined, keyParser?: (K extends string ? null : (id: string) => K) | undefined);
-    get busyCount(): number;
-    /**
-     * @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`.
-     *
-     * @returns A value model for the loading count.
-     */
-    protected pure_createBusyCount(): IValueModel<number>;
-    /**
-     * @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`.
-     *
-     * @returns A map model for the items cache.
-     */
-    protected pure_createItemsCache(): IMapModel<string, T | null | undefined>;
-    /**
-     * @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`.
-     *
-     * @returns A map model for the items loading state.
-     */
-    protected pure_createItemsStatus(): IMapModel<string, boolean>;
-    /**
-     * @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`.
-     *
-     * @returns A map model for the items promises cache.
-     */
-    protected pure_createFetchCache(): IMapModel<string, Promise<T | null>>;
-    private _pk;
-    /**
-     * Creates a logger name for this instance.
-     * @param name The name of the cache instance.
-     * @returns The logger name.
-     */
-    protected getLoggerName(name: string | undefined): string;
-    /**
-     * 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: (ids: K[]) => Promise<T[]>, delay?: number): this;
-    /**
-     * Enables auto-invalidation of cached items.
-     *
-     * @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 will be set to `undefined` instead. Defaults to false.
-    */
-    useInvalidationTime(ms: number | null, keepInstance?: boolean): this;
-    /**
-     * Returns a {@link DeferredGetter} object for a specfied key.
-     *
-     * This can be used to access the current value, promise, and loading state of the item.
-     *
-     * @param key The key of the item.
-     */
-    getDeferred(key: K): DeferredGetter<T>;
-    /**
-     * Returns the loading state of an item.
-     *
-     * @param id The id of the item.
-     * @returns The loading state of the item: true if loading, false if loading completed, undefined if loading was not started yet for the specified key.
-     */
-    getIsBusy(id: K): boolean | undefined;
-    /**
-     * Returns the current cached value for the specified key, without triggering a fetch.
-     * @param id The id of the item.
-     * @returns The current cached value of the item.
-     */
-    protected _getCurrent(id: K): {
-        item: T | null | undefined;
-        key: string;
-        isInvalid: boolean;
-    };
-    /**
-     * Returns the current cached value for the specified key, optionally triggering a fetch.
-     * @param id The id of the item.
-     * @param initiateFetch If true, will initiate a fetch if the item is not cached.
-     * @returns The current cached value of the item.
-     */
-    getCurrent(id: K, initiateFetch?: boolean): T | null | undefined;
-    /**
-     * 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: K): Promise<T | null>;
-    /**
-     * 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.
-     */
-    protected _doFetchAsync: (id: K, key: string) => Promise<T | null>;
-    /**
-     * Instantly invalidates the cached item for the specified id, like it was never fetched/accessed.
-     * @param id The id of the item.
-     */
-    invalidate(id: K): void;
-    /**
-     * Updates the cached value for the specified id directly, like it was fetched already. Overrides existing value, if any.
-     * @param id The id of the item.
-     * @param value The new value to cache.
-     */
-    updateValueDirectly(id: K, value: T | null): void;
-    /** Returns true if the item is cached or fetching was initiated. Does not initiates fetching. */
-    hasKey(id: K): boolean;
-    /** Returns an iterator over the keys of the cached items. */
-    keys(iterate: true): MapIterator<string>;
-    /** Returns an array of the keys of the cached items. */
-    keys(): string[];
-    /** Returns an iterator over the parsed keys of the cached items. */
-    keysParsed(iterate: true): Generator<K> | null;
-    /** Returns an array of the parsed keys of the cached items. */
-    keysParsed(): K[] | null;
-    /** Clears the cache and resets the loading state. */
-    clear(): void;
-    /** @internal updates all caches states at once. */
-    protected _set(key: string, item: T | null | undefined, promise: Promise<T> | undefined, busy: boolean | undefined): void;
-    /**
-     * Checks if the cached item for the specified key is invalidated (expired).
-     * @param key The cache key.
-     * @returns True if the item is invalidated, false otherwise.
-     */
-    protected getIsInvalidated(key: string): boolean;
-    /** Updates the loading status for the specified key. Override to add a hook. */
-    protected setStatus(key: string, status: boolean): void;
-    /** Updates the promise for the specified key. Override to add a hook. */
-    protected setPromise(key: string, promise: Promise<T | null>): void;
-    /** Stores the result for the specified key. Override to add a hook. */
-    protected storeResult(key: string, res: T | null): void;
-    /** Hooks into the fetch process before it starts. */
-    protected onBeforeFetch(_key: string): void;
-    /** Hooks into the fetch process after it completes. */
-    protected onFetchComplete(key: string): void;
-    /** Hooks into the result preparation process, before it's stored into the cache. */
-    protected prepareResult(res: T | null): NonNullable<T> | null;
-    /** @pure Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. */
-    protected tryFetchInBatch(id: K): Promise<T | null>;
-}