@zajno/common 2.7.7 → 2.8.1

package/types/structures/promiseCache.d.ts

@@ -1,21 +1,28 @@
 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>;
-    readonly busy: boolean | undefined;
+    /** 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 busy: boolean;
+        readonly isLoading: boolean;
     };
 }
-/** Caches items by key which are resolve by a promise.
+/**
+ * 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.
 */
@@ -23,22 +30,70 @@ 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>;
-    protected readonly _busyCount: IValueModel<number>;
+    /** 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.
@@ -52,40 +107,100 @@ export declare class PromiseCache<T, K = string> extends Loggable {
      * 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;
-    /** @override */
+    /** Updates the loading status for the specified key. Override to add a hook. */
     protected setStatus(key: string, status: boolean): void;
-    /** @override */
+    /** Updates the promise for the specified key. Override to add a hook. */
     protected setPromise(key: string, promise: Promise<T | null>): void;
-    /** @override */
+    /** Stores the result for the specified key. Override to add a hook. */
     protected storeResult(key: string, res: T | null): void;
-    /** @override */
+    /** Hooks into the fetch process before it starts. */
     protected onBeforeFetch(_key: string): void;
-    /** @override */
-    protected prepareResult(res: T | null): NonNullable<T> | null;
-    /** @override */
+    /** Hooks into the fetch process after it completes. */
     protected onFetchComplete(key: string): void;
-    /** @pure */
+    /** 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>;
 }

package/types/structures/promiseProxy.d.ts

@@ -11,18 +11,22 @@ type ForbiddenKeys = typeof PromiseGetter;
 type NoForbiddenKeys<T> = {
     [K in keyof T]: K extends ForbiddenKeys ? never : T[K];
 };
-type Options<T, TFnKeys, TWrap, TLazy> = {
+interface LazyPromiseCtor<K> {
+    new (loader: () => Promise<K>): LazyPromise<K>;
+}
+type Options<T, TFnKeys, TWrap, TLazy extends LazyPromiseCtor<T>> = {
+    /** Function returning a promise that resolves to a proxied object */
     loader: () => Promise<T>;
+    /** An array of keys that should be treated as functions so that they can be called before the object is resolved */
     fnKeys?: TFnKeys[];
+    /** An object that will be used as a wrapper for the proxied object. Can contain any fields that will be copied to the resolved object */
     wrap?: TWrap;
+    /** A constructor that creates {@link {LazyPromise}} instance for handling loader */
     lazy?: TLazy;
 };
 /**
- * Creates a proxy object that will be resolved to the object returned by the loader function. // Thanks CoPilot for this comment :)
- *
- * @param loader a function returning a promise that resolves to a proxied object
- * @param fnKeys an array of keys that should be treated as functions so that they can be called before the object is resolved
- * @param wrap an object that will be used as a wrapper for the proxied object. can contain any fields that will be copied to the resolved object
+ * Creates a proxy object that will be resolved to the object returned by the loader function.
+ * @param options - Options for creating the proxy, see {@link Options}
  * @returns a proxy object that will be resolved to the object returned by the loader function
  */
 export declare function createPromiseProxy<T extends NoForbiddenKeys<T>, TFnKeys extends AllowedFnKeys<T> = never, TWrap extends object = object>(options: Options<T, TFnKeys, TWrap, typeof LazyPromise>): PromiseProxy<T, StringKeys<T>, TFnKeys, TWrap>;

package/types/structures/tempoCache.d.ts

@@ -1,4 +1,5 @@
 import type { ILazy, ILazyPromise } from '../lazy/types.js';
+import type { IResettableModel } from '../models/types.js';
 import { ExpireTracker } from './expire.js';
 /**
  * Calls factory fn to fetch and store some value for a limited time.
@@ -19,11 +20,11 @@ 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 createFromLazy<T>(lazy: ILazy<T>, lifetimeMs: number): TempoCache<T>;
+    function createFromLazy<T>(lazy: ILazy<T> & IResettableModel, lifetimeMs: number): TempoCache<T>;
     /**
      * Creates a TempoCache instance which caches `ILazyPromise.promise` for a specified time.
      *
      * 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>, lifetimeMs: number): TempoCache<Promise<T>>;
+    function createFromLazyPromise<T>(lazy: ILazyPromise<T> & IResettableModel, lifetimeMs: number): TempoCache<Promise<T>>;
 }