@zajno/common 2.8.9 → 2.8.11

package/types/lazy/promise.d.ts

@@ -1,7 +1,7 @@
 import { type IDisposable } from '../functions/disposer.js';
 import type { IResettableModel } from '../models/types.js';
 import type { IExpireTracker } from '../structures/expire.js';
-import type { IControllableLazyPromise, ILazyPromiseExtension, LazyFactory } from './types.js';
+import type { IControllableLazyPromise, ILazyPromiseExtension, IResolvedLazyPromise, LazyFactory } from './types.js';
 /**
  * Asynchronous lazy-loading container that initializes via a promise-based factory.
  * Handles concurrent operations with "latest wins" semantics: multiple refreshes are automatically
@@ -22,11 +22,14 @@ export declare class LazyPromise<T, TInitial extends T | undefined = undefined>
     constructor(factory: LazyFactory<T>, initial?: TInitial);
     /** Current loading state: true = loading, false = loaded, null = not started */
     get isLoading(): boolean | null;
+    /** Returns true if a value of type `T` has been successfully loaded (no error). */
     get hasValue(): boolean;
     get error(): unknown;
+    /** @inheritdoc */
+    hasResolvedValue(): this is LazyPromise<T, TInitial> & IResolvedLazyPromise<T, TInitial>;
     /** @deprecated Use {@link error} instead. */
     get errorMessage(): string | null;
-    get promise(): Promise<T>;
+    get promise(): Promise<T | TInitial>;
     get value(): T | TInitial;
     /** Returns current value without triggering loading. */
     get currentValue(): T | TInitial;
@@ -79,7 +82,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;

package/types/lazy/types.d.ts

@@ -3,7 +3,14 @@ import type { IResettableModel } from '../models/types.js';
 export interface ILazy<T> {
     /** Returns current value, triggering loading if not yet loaded. */
     readonly value: T;
-    /** Returns true if value has been loaded. Does not trigger loading. */
+    /**
+     * Returns true if a value of type `T` has been successfully loaded (no error).
+     *
+     * When `true`, `value` is guaranteed to be `T` (not `TInitial` or an error fallback).
+     * When `false`, `value` may be `TInitial`, `undefined`, or a stale value from a previous successful load.
+     *
+     * Does not trigger loading.
+     */
     readonly hasValue: boolean;
     /** Returns current value or undefined if not loaded. Does not trigger loading. */
     readonly currentValue: T | undefined;
@@ -23,12 +30,18 @@ export interface ILazyPromise<T, TInitial extends T | undefined = undefined> ext
      * Does not trigger loading.
      */
     readonly isLoading: boolean | null | undefined;
-    /** Returns the promise for the value, triggering loading if not started. */
-    readonly promise: Promise<T>;
+    /**
+     * Returns the promise for the value, triggering loading if not started.
+     *
+     * On error, resolves to the current value (stale or initial) instead of rejecting.
+     */
+    readonly promise: Promise<T | TInitial>;
     /**
      * Re-executes the factory to get fresh data. If concurrent refreshes occur, the latest wins.
      * All awaiting promises will resolve to the final refreshed value.
      *
+     * On error, resolves to the current value (stale or initial) instead of rejecting.
+     *
      * **⚠️ Use sparingly:** Only refresh when explicitly needed for fresh data.
      * Over-use defeats lazy loading and caching benefits.
      *
@@ -43,9 +56,32 @@ export interface ILazyPromise<T, TInitial extends T | undefined = undefined> ext
      * - Using instead of cache expiration (use `withExpire`)
      * - Calling in loops or high-frequency events without debouncing
      *
-     * @returns Promise resolving to the refreshed value
+     * @returns Promise resolving to the refreshed value, or the current value on error
      */
-    refresh(): Promise<T>;
+    refresh(): Promise<T | TInitial>;
+    /**
+     * Type-narrowing check: returns `true` if the value has been successfully resolved to `T`.
+     *
+     * When this returns `true`, `value` and `currentValue` are narrowed to `T` (not `TInitial`).
+     *
+     * @example
+     * ```typescript
+     * const lazy: ILazyPromise<User> = cache.getLazy('user-1');
+     * if (lazy.hasResolvedValue()) {
+     *     // lazy.value is `User` here, not `User | undefined`
+     *     console.log(lazy.value.name);
+     * }
+     * ```
+     */
+    hasResolvedValue(): this is IResolvedLazyPromise<T, TInitial>;
+}
+/** Narrowed state of ILazyPromise after successful resolution. */
+export interface IResolvedLazyPromise<T, TInitial extends T | undefined = undefined> extends ILazyPromise<T, TInitial> {
+    readonly value: T;
+    readonly currentValue: T;
+    readonly hasValue: true;
+    readonly isLoading: false;
+    readonly error: null;
 }
 /**
  * Controllable lazy promise with manual state management.

package/types/structures/promiseCache/cache.d.ts

@@ -1,5 +1,5 @@
 import { PromiseCacheCore } from './core.js';
-import type { ErrorCallback, InvalidationConfig } from './types.js';
+import type { ErrorCallback, InvalidationConfig, PromiseCacheFetcher, PromiseCacheKeyAdapter, PromiseCacheKeyParser } from './types.js';
 /**
  * Caches items by a key (string or another type) which are resolved by an async fetcher (`Promise`).
  *
@@ -10,18 +10,19 @@ import type { ErrorCallback, InvalidationConfig } from './types.js';
  *  - auto-invalidation of cached items (time-based, callback-based, max items).
  *  - error tracking per key.
 */
-export declare class PromiseCache<T, K = string> extends PromiseCacheCore<T, K> {
+export declare class PromiseCache<T, K = string, TInitial extends T | undefined = undefined> extends PromiseCacheCore<T, K, TInitial> {
     private readonly fetcher;
     private _batch;
     private _invalidationConfig;
     private _onError;
+    private _initialValueFactory;
     /**
      * 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, keyParser?: K extends string ? null : (id: string) => K);
+    constructor(fetcher: PromiseCacheFetcher<T, K>, keyAdapter?: PromiseCacheKeyAdapter<K>, keyParser?: PromiseCacheKeyParser<K>);
     /**
      * 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.
      *
@@ -36,9 +37,11 @@ export declare class PromiseCache<T, K = string> extends PromiseCacheCore<T, K>
      * 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: number | null, keepInstance?: boolean): this;
+    useInvalidationTime(ms: number | null, _keepInstance?: boolean): this;
     /**
      * Configures advanced invalidation policy.
      *
@@ -54,6 +57,19 @@ export declare class PromiseCache<T, K = string> extends PromiseCacheCore<T, K>
      * @param callback The callback to call on error. Receives the original key and the raw error.
      */
     useOnError(callback: ErrorCallback<K> | null): 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<TNewInitial extends T | undefined>(initial: TNewInitial | ((key: K) => TNewInitial)): PromiseCache<T, K, TNewInitial>;
     /**
      * 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.
      *
@@ -62,33 +78,52 @@ export declare class PromiseCache<T, K = string> extends PromiseCacheCore<T, K>
      * @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 | undefined>;
+    get(id: K): Promise<T | TInitial>;
+    /**
+     * 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: K): Promise<T | TInitial>;
     /** Clears the cache and resets the loading state. */
     clear(): void;
-    protected _getCurrent(id: K): {
-        item: T | undefined;
-        key: string;
-        isInvalid: boolean;
-    };
+    protected _getInitialValue(id: K): TInitial;
     protected getIsInvalidated(key: string): boolean;
     /** @override Stores the result for the specified key, enforcing max items. */
     protected storeResult(key: string, res: T): void;
     /**
-     * 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.
      */
-    protected _doFetchAsync(id: K, key: string): Promise<T | undefined>;
+    protected _doFetchAsync(id: K, key: string, refreshing: boolean): Promise<T | TInitial>;
     /** Performs a fetch operation in batch mode if available, otherwise uses the regular fetch. Throws on error. */
-    protected tryFetchInBatch(id: K): Promise<T>;
+    protected tryFetchInBatch(id: K, refreshing?: boolean): Promise<T>;
     /** Handles a fetch error: stores it, logs it, and calls the onError callback. */
-    private _handleError;
+    protected _handleError(id: K, err: unknown): void;
     /**
      * 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).
      */
     private _enforceMaxItems;

package/types/structures/promiseCache/core.d.ts

@@ -11,29 +11,41 @@ import type { DeferredGetter } from './types.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.
  */
-export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
+export declare abstract class PromiseCacheCore<T, K = string, TInitial extends T | undefined = undefined> extends Loggable {
     protected readonly keyAdapter?: ((k: K) => string) | null | undefined;
     protected readonly keyParser?: ((id: string) => K) | null | undefined;
     /** Stores resolved items in map by id. */
-    protected readonly _itemsCache: IMapModel<string, T | undefined>;
+    protected readonly _itemsCache: IMapModel<string, T>;
     /** 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. */
-    protected readonly _fetchCache: IMapModel<string, Promise<T | undefined>>;
+    protected readonly _fetchCache: IMapModel<string, Promise<T | TInitial>>;
     /** Stores last errors by key. Observable-friendly via IMapModel. */
     protected readonly _errorsMap: IMapModel<string, unknown>;
     /** Stores items resolve timestamps (for expiration) in map by id. */
     protected readonly _timestamps: Map<string, number>;
+    /**
+     * 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).
+     */
+    protected readonly _activeFetchPromises: Map<string, Promise<T | TInitial>>;
     protected _version: number;
     constructor(keyAdapter?: ((k: K) => string) | null | undefined, keyParser?: ((id: string) => K) | null | undefined);
-    /** 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(): number;
     /** Returns the number of cached items (resolved values). */
     get cachedCount(): number;
@@ -54,7 +66,7 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
      *
      * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
      */
-    protected pure_createItemsCache(): IMapModel<string, T | undefined>;
+    protected pure_createItemsCache(): IMapModel<string, T>;
     /**
      * @pure @const
      * Creates a map for tracking the loading state of items by id. Override to inject own instance, e.g. for observability.
@@ -68,7 +80,7 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
      *
      * Warning: as name indicates, this should be "pure"/"const" function, i.e. should not reference `this`/`super`.
      */
-    protected pure_createFetchCache(): IMapModel<string, Promise<T | undefined>>;
+    protected pure_createFetchCache(): IMapModel<string, Promise<T | TInitial>>;
     /**
      * @pure @const
      * Creates a map for storing last errors by key. Override to inject own instance, e.g. for observability.
@@ -87,9 +99,9 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
      *
      * - `value` / `promise` trigger a fetch if not started.
      * - `currentValue` reads without triggering.
-     * - `refresh()` invalidates and re-fetches.
+     * - `refresh()` re-fetches while keeping the stale value available.
      */
-    getLazy(key: K): ILazyPromise<T>;
+    getLazy(key: K): ILazyPromise<T, TInitial>;
     /**
      * Returns a {@link DeferredGetter} object for a specified key.
      *
@@ -102,7 +114,11 @@ export declare abstract class PromiseCacheCore<T, K = string> 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: K): boolean | undefined;
     /**
@@ -117,10 +133,23 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
      * @returns The raw error, or null if no error.
      */
     getLastError(id: K): unknown;
-    /** Returns the current cached value, optionally triggering a fetch. */
-    getCurrent(id: K, initiateFetch?: boolean): T | undefined;
+    /** Returns the current cached value, optionally triggering a fetch. Falls back to the initial value if configured. */
+    getCurrent(id: K, initiateFetch?: boolean): T | TInitial;
     /** Returns a promise that resolves to the cached or freshly fetched value. */
-    abstract get(id: K): Promise<T | undefined>;
+    abstract get(id: K): Promise<T | TInitial>;
+    /**
+     * Re-fetches the value for the specified key while keeping the stale cached value available.
+     *
+     * Implements stale-while-revalidate semantics:
+     * - The current cached value remains accessible via `getCurrent()` / `getLazy().value` during the refresh.
+     * - On success, the cached value is updated.
+     * - On error, the stale value is preserved and the error is stored.
+     * - Multiple concurrent refreshes use "latest wins" semantics.
+     *
+     * @param id The key of the item to refresh.
+     * @returns A promise resolving to the refreshed value, or the stale value on error.
+     */
+    abstract refresh(id: K): Promise<T | TInitial>;
     /** Returns true if the item is cached or fetching was initiated. Does not initiate fetching. */
     hasKey(id: K): boolean;
     /** Returns an iterator over the keys of the cached items. */
@@ -133,7 +162,11 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
     keysParsed(): K[] | null;
     /** Instantly invalidates the cached item for the specified id, like it was never fetched/accessed. */
     invalidate(id: K): void;
-    /** Updates the cached value for the specified id directly, like it was fetched already. */
+    /** 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: K, value: T): void;
+    /**
+     * @deprecated Use {@link set} instead.
+     */
     updateValueDirectly(id: K, value: T): void;
     /**
      * Iterates over all cached items and removes those that are invalid (expired).
@@ -143,31 +176,29 @@ export declare abstract class PromiseCacheCore<T, K = string> extends Loggable {
     sanitize(): number;
     /** Clears the cache and resets the loading state. */
     clear(): void;
-    /** Returns the current cached value for the specified key, without triggering a fetch. */
-    protected abstract _getCurrent(id: K): {
-        item: T | undefined;
-        key: string;
-        isInvalid: boolean;
-    };
+    /** Returns the cached value if present, otherwise the initial value for the key. */
+    protected _getCachedOrInitial(key: string, id: K): T | TInitial;
     /**
      * Checks if the cached item for the specified key is invalidated (expired).
      * Override to implement custom invalidation logic.
      */
     protected abstract getIsInvalidated(key: string): boolean;
-    /** @internal updates all caches states at once. */
-    protected _set(key: string, item: T | undefined, promise: Promise<T> | undefined, isLoading: boolean | undefined): void;
+    /** Returns the initial/default value for a key. Used as fallback when no cached value exists. */
+    protected abstract _getInitialValue(id: K): TInitial;
+    /** @internal Deletes all cache entries for a key (item, promise, status). */
+    protected _deleteKey(key: string): void;
     /** 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 | undefined>): void;
+    protected setPromise(key: string, promise: Promise<T | TInitial>): void;
     /** Stores the result for the specified key. Override to add a hook. */
     protected storeResult(key: string, res: T): 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 superseded fetch cleanup. Only decrements loading count — does not touch fetch cache or status. */
+    protected onFetchSuperseded(_key: string): void;
     /** Hooks into the result preparation process, before it's stored into the cache. */
     protected prepareResult(res: T): T;
-    /** @internal Helper to set or delete a value in a map. */
-    protected static _setMapX<T>(key: string, map: IMapModel<string, T>, val: T): void;
 }

package/types/structures/promiseCache/types.d.ts

@@ -32,6 +32,17 @@ export declare namespace DeferredGetter {
 export type InvalidationCallback<T> = (key: string, value: T | undefined, cachedAt: number) => boolean;
 /** Callback for handling errors during fetching. */
 export type ErrorCallback<K> = (key: K, error: unknown) => void;
+/**
+ * Fetcher function signature for PromiseCache.
+ *
+ * @param id The key of the item to fetch.
+ * @param refreshing `true` when called via `refresh()`, `false` on initial `get()`.
+ */
+export type PromiseCacheFetcher<T, K = string> = (id: K, refreshing?: boolean) => Promise<T>;
+/** Converts a non-string key to a string for internal cache storage. Resolves to `undefined` when `K` is `string`. */
+export type PromiseCacheKeyAdapter<K> = K extends string ? undefined : (k: K) => string;
+/** Parses a string key back to the original key type. Resolves to `undefined` when `K` is `string`. */
+export type PromiseCacheKeyParser<K> = K extends string ? undefined : (id: string) => K;
 /**
  * Configuration for cache invalidation policy.
  *
@@ -51,8 +62,13 @@ export interface InvalidationConfig<T> {
      * then oldest valid items are removed to make room.
      *
      * Note: items currently being fetched (in-flight) are not evicted.
+     *
+     * Performance: eviction scans all cached timestamps linearly. Suitable for caches up to ~1000 items.
      */
     readonly maxItems?: number | null;
-    /** If true, the cached item will not be removed during invalidation, but the old instance is kept. */
+    /**
+     * @deprecated This option is now ignored — stale values are always kept during invalidation (stale-while-revalidate).
+     * Use `invalidate()` followed by `get()` if you need to clear the stale value before re-fetching.
+     */
     readonly keepInstance?: boolean;
 }

package/types/structures/tempoCache.d.ts

@@ -26,5 +26,5 @@ export declare namespace TempoCache {
      *
      * Note a limitation: calling `reset` (or changing the stored value directly in other way) on `lazy` will not affect the value cached by `TempoCache` instance.
     */
-    function createFromLazyPromise<T>(lazy: ILazyPromise<T> & IResettableModel, lifetimeMs: number): TempoCache<Promise<T>>;
+    function createFromLazyPromise<T>(lazy: ILazyPromise<T> & IResettableModel, lifetimeMs: number): TempoCache<Promise<T | undefined>>;
 }