@zajno/common 2.7.6 → 2.8.0

package/types/math/object/helpers.d.ts

@@ -1,7 +1,8 @@
 import type { DeepReadonly, DeepReadonlyPartial } from '../../types/deep.js';
+import type { Nullable } from '../../types/misc.js';
 import type { BasePair, IObjectOps, NumKey } from './types.js';
-export declare function _getValue<T extends object, TKey extends NumKey<T> = NumKey<T>>(o: DeepReadonlyPartial<T>, key: TKey): T[TKey] | null;
-export declare function _getInnerValue<T extends object, TKey extends string & keyof T>(o: DeepReadonly<T>, key: TKey): DeepReadonly<T[TKey]>;
-export declare function _getInnerValue<T extends object, TKey extends string & keyof T>(o: DeepReadonly<T> | number, key: TKey): DeepReadonly<T[TKey]> | number;
+export declare function _getValue<T extends object, TKey extends NumKey<T> = NumKey<T>>(o: Nullable<DeepReadonlyPartial<T>>, key: TKey): T[TKey] | undefined;
+export declare function _getInnerValue<T extends object, TKey extends string & keyof T>(o: Nullable<DeepReadonly<T>>, key: TKey): DeepReadonly<T[TKey]>;
+export declare function _getInnerValue<T extends object, TKey extends string & keyof T>(o: Nullable<DeepReadonly<T> | number>, key: TKey): DeepReadonly<T[TKey]> | number;
 /** this helpers hides some cumbersome type transformations */
-export declare function doOps<T extends object, TOps extends IObjectOps<any>>(this: void, ops: BasePair<T, string & keyof T, TOps>[], o: DeepReadonly<T>, processor?: (ops: TOps, value: DeepReadonly<T[string & keyof T]>, key: string & keyof T) => T[keyof T] | null): T;
+export declare function doOps<T extends object, TOps extends IObjectOps<any>>(this: void, ops: BasePair<T, string & keyof T, TOps>[], o: Nullable<DeepReadonly<T>>, processor?: (ops: TOps, value: DeepReadonly<T[string & keyof T]>, key: string & keyof T) => T[keyof T] | null): T;

package/types/math/object/math.composite.d.ts

@@ -1,16 +1,16 @@
-import type { AnyObject } from '../../types/index.js';
+import type { AnyObject, Nullable } from '../../types/index.js';
 import type { DeepReadonly } from '../../types/deep.js';
 import { CompositeObjectOps } from './ops.composite.js';
 import type { AbsOptions, IObjectMath, MathPairsMap, RoundOptions } from './types.js';
 export declare class CompositeObjectMath<T extends AnyObject> extends CompositeObjectOps<T> implements IObjectMath<T> {
     private readonly _math;
     constructor(innerMath: MathPairsMap<T>);
-    contains(base: DeepReadonly<T>, target: DeepReadonly<T>): boolean;
-    inverse(o: DeepReadonly<T>): T;
-    abs(o: DeepReadonly<T>, options?: AbsOptions): T | null;
-    round(o: DeepReadonly<T>, options?: RoundOptions): T;
-    add(o1: DeepReadonly<T>, o2: DeepReadonly<T>): T;
-    subtract(base: DeepReadonly<T>, amount: number | DeepReadonly<T>): T;
-    multiply(o1: DeepReadonly<T>, o2: number | DeepReadonly<T>): T;
-    div(o1: DeepReadonly<T>, o2: number | DeepReadonly<T>): number;
+    contains(base: Nullable<DeepReadonly<T>>, target: Nullable<DeepReadonly<T>>): boolean;
+    inverse(o: Nullable<DeepReadonly<T>>): T;
+    abs(o: Nullable<DeepReadonly<T>>, options?: AbsOptions): T | null;
+    round(o: Nullable<DeepReadonly<T>>, options?: RoundOptions): T;
+    add(o1: Nullable<DeepReadonly<T>>, o2: Nullable<DeepReadonly<T>>): T;
+    subtract(base: Nullable<DeepReadonly<T>>, amount: number | Nullable<DeepReadonly<T>>): T;
+    multiply(o1: Nullable<DeepReadonly<T>>, o2: number | Nullable<DeepReadonly<T>>): T;
+    div(o1: Nullable<DeepReadonly<T>>, o2: Nullable<number | DeepReadonly<T>>): number;
 }

package/types/math/object/math.d.ts

@@ -1,17 +1,18 @@
+import type { Nullable } from '../../types/index.js';
 import type { DeepReadonly, DeepReadonlyPartial } from '../../types/deep.js';
 import { ObjectOps } from './ops.js';
 import type { AbsOptions, DELETE_TYPE, IObjectMath, NumKey, RoundOptions } from './types.js';
 export declare class ObjectMath<T extends object> extends ObjectOps<T> implements IObjectMath<T> {
-    getTotal(o: DeepReadonlyPartial<T>): number;
-    contains(base: DeepReadonly<T>, target: DeepReadonly<T>): boolean;
-    inverse(o: DeepReadonly<T>): T;
-    div(o1: DeepReadonly<T>, o2: number): T;
-    div(o1: DeepReadonly<T>, o2: DeepReadonly<T>): number;
-    process(o: DeepReadonly<T>, processor: (val: number, key: NumKey<T>) => number | DELETE_TYPE): T | null;
-    abs(c: DeepReadonly<T>, stripNegatives?: AbsOptions): T | null;
-    round(c: DeepReadonly<T>, method?: RoundOptions): T | null;
-    calc(c1: DeepReadonly<T>, c2: DeepReadonly<T> | number, operator: (n: number, n2: number) => number): T;
-    add(c1: DeepReadonly<T>, c2: DeepReadonly<T> | number): T;
-    subtract(base: DeepReadonly<T>, amount: DeepReadonly<T> | number): T;
-    multiply(c1: DeepReadonly<T>, c2: DeepReadonly<T> | number): T;
+    getTotal(o: Nullable<DeepReadonlyPartial<T>>): number;
+    contains(base: Nullable<DeepReadonly<T>>, target: Nullable<DeepReadonly<T>>): boolean;
+    inverse(o: Nullable<DeepReadonly<T>>): T;
+    div(o1: Nullable<DeepReadonly<T>>, o2: Nullable<number>): T;
+    div(o1: Nullable<DeepReadonly<T>>, o2: Nullable<DeepReadonly<T>>): number;
+    process(o: Nullable<DeepReadonly<T>>, processor: (val: number, key: NumKey<T>) => number | DELETE_TYPE): T | null;
+    abs(c: Nullable<DeepReadonly<T>>, stripNegatives?: AbsOptions): T | null;
+    round(c: Nullable<DeepReadonly<T>>, method?: RoundOptions): T | null;
+    calc(c1: Nullable<DeepReadonly<T>>, c2: Nullable<DeepReadonly<T> | number>, operator: (n: number, n2: number) => number): T;
+    add(c1: Nullable<DeepReadonly<T>>, c2: Nullable<DeepReadonly<T> | number>): T;
+    subtract(base: Nullable<DeepReadonly<T>>, amount: Nullable<DeepReadonly<T> | number>): T;
+    multiply(c1: Nullable<DeepReadonly<T>>, c2: Nullable<DeepReadonly<T> | number>): T;
 }

package/types/math/object/ops.composite.d.ts

@@ -1,14 +1,14 @@
-import type { AnyObject } from '../../types/index.js';
+import type { AnyObject, Nullable } from '../../types/index.js';
 import type { DeepReadonly } from '../../types/deep.js';
 import type { IObjectOps, OpsPairsMap } from './types.js';
 export declare class CompositeObjectOps<T extends AnyObject> implements IObjectOps<T> {
     readonly Empty: Readonly<T>;
     private readonly _ops;
     constructor(innerOps: OpsPairsMap<T>);
-    isEmpty(o: DeepReadonly<T>): boolean;
+    isEmpty(o: Nullable<DeepReadonly<T>>): boolean;
     getEmpty(): T;
-    clone(o: DeepReadonly<T>): T;
-    isValid(o: DeepReadonly<T>): boolean;
-    isEquals(a: DeepReadonly<T>, b: DeepReadonly<T>): boolean;
-    assign(to: T, other: DeepReadonly<T>): void;
+    clone(o: Nullable<DeepReadonly<T>>): T;
+    isValid(o: Nullable<DeepReadonly<T>>): boolean;
+    isEquals(a: Nullable<DeepReadonly<T>>, b: Nullable<DeepReadonly<T>>): boolean;
+    assign(to: T, other: Nullable<DeepReadonly<T>>): void;
 }

package/types/math/object/ops.d.ts

@@ -1,5 +1,5 @@
 import { SkipCondition, SkipOptions } from '../../fields/skip.js';
-import type { AnyObject, DeepPartial, DeepReadonly, Predicate } from '../../types/index.js';
+import type { AnyObject, DeepPartial, DeepReadonly, Nullable, Predicate } from '../../types/index.js';
 import type { IObjectOps, NumKey } from './types.js';
 type Keys<T extends AnyObject> = NumKey<T>[];
 export declare class ObjectOps<T extends AnyObject> implements IObjectOps<T> {
@@ -9,12 +9,12 @@ export declare class ObjectOps<T extends AnyObject> implements IObjectOps<T> {
     constructor(keys: Keys<T>);
     addValidator(validator: Predicate<DeepReadonly<T>>): this;
     getEmpty(): T;
-    clone(o: DeepReadonly<T>): T;
-    isEmpty(o: DeepReadonly<T>): boolean;
-    isValid(o: DeepReadonly<T>): boolean;
-    isEquals(a: DeepReadonly<T>, b: DeepReadonly<T>): boolean;
-    strip(v: DeepReadonly<T>, condition?: SkipCondition<T, NumKey<T>>): DeepPartial<T>;
-    toStringData(v: DeepReadonly<T>, labels: Readonly<Record<Keys<T>[number], string>>, strip?: SkipOptions): [number, string][];
-    assign(to: T, other: DeepReadonly<T>): void;
+    clone(o: Nullable<DeepReadonly<T>>): T;
+    isEmpty(o: Nullable<DeepReadonly<T>>): boolean;
+    isValid(o: Nullable<DeepReadonly<T>>): boolean;
+    isEquals(a: Nullable<DeepReadonly<T>>, b: Nullable<DeepReadonly<T>>): boolean;
+    strip(v: Nullable<DeepReadonly<T>>, condition?: SkipCondition<T, NumKey<T>>): DeepPartial<T>;
+    toStringData(v: Nullable<DeepReadonly<T>>, labels: Readonly<Record<Keys<T>[number], string>>, strip?: SkipOptions): [number, string][];
+    assign(to: T, other: Nullable<DeepReadonly<T>>): T;
 }
 export {};

package/types/math/object/types.d.ts

@@ -1,26 +1,26 @@
-import type { AnyObject, DeepReadonly, TypedKeys } from '../../types/index.js';
+import type { AnyObject, DeepReadonly, Nullable, TypedKeys } from '../../types/index.js';
 export type NumKey<T extends AnyObject> = TypedKeys<T, number>;
 export type AbsOptions = false | 'remove' | 'zero';
 export type RoundOptions = 'floor' | 'ceil' | 'round';
 export type DELETE_TYPE = 'delete';
 export interface IObjectOps<T extends AnyObject> {
     readonly Empty: Readonly<T>;
-    isEmpty(o: DeepReadonly<T>): boolean;
+    isEmpty(o: Nullable<DeepReadonly<T>>): boolean;
     getEmpty(): T;
-    clone(o: DeepReadonly<T>): T;
-    isValid(o: DeepReadonly<T>): boolean;
-    isEquals(a: DeepReadonly<T>, b: DeepReadonly<T>): boolean;
-    assign(to: T, other: DeepReadonly<T>): void;
+    clone(o: Nullable<DeepReadonly<T>>): T;
+    isValid(o: Nullable<DeepReadonly<T>>): boolean;
+    isEquals(a: Nullable<DeepReadonly<T>>, b: Nullable<DeepReadonly<T>>): boolean;
+    assign(to: T, other: Nullable<DeepReadonly<T>>): void;
 }
 export interface IObjectMath<T extends AnyObject> extends IObjectOps<T> {
-    contains(base: DeepReadonly<T>, target: DeepReadonly<T>): boolean;
-    inverse(o: DeepReadonly<T>): T;
-    abs(o: DeepReadonly<T>, options?: AbsOptions): T | null;
-    round(o: DeepReadonly<T>, options?: RoundOptions): T | null;
-    add(o1: DeepReadonly<T>, o2: DeepReadonly<T>): T;
-    subtract(base: DeepReadonly<T>, amount: DeepReadonly<T> | number): T;
-    multiply(o1: DeepReadonly<T>, o2: DeepReadonly<T> | number): T;
-    div(o1: DeepReadonly<T>, o2: DeepReadonly<T> | number): number;
+    contains(base: Nullable<DeepReadonly<T>>, target: Nullable<DeepReadonly<T>>): boolean;
+    inverse(o: Nullable<DeepReadonly<T>>): T;
+    abs(o: Nullable<DeepReadonly<T>>, options?: AbsOptions): T | null;
+    round(o: Nullable<DeepReadonly<T>>, options?: RoundOptions): T | null;
+    add(o1: Nullable<DeepReadonly<T>>, o2: Nullable<DeepReadonly<T>>): T;
+    subtract(base: Nullable<DeepReadonly<T>>, amount: Nullable<DeepReadonly<T> | number>): T;
+    multiply(o1: Nullable<DeepReadonly<T>>, o2: Nullable<DeepReadonly<T> | number>): T;
+    div(o1: Nullable<DeepReadonly<T>>, o2: Nullable<DeepReadonly<T> | number>): number;
 }
 export type BasePair<T extends AnyObject, TKey extends string & keyof T = string & keyof T, TOps extends IObjectOps<T[TKey]> = IObjectOps<T[TKey]>> = {
     key: TKey;

package/types/models/Loading.d.ts

@@ -1,4 +1,4 @@
-import type { IResetableModel, IValueModel } from './types.js';
+import type { IResettableModel, IValueModel } from './types.js';
 export type LoadingWorker<T> = () => (T | Promise<T>);
 export type LoadingResult<T = unknown> = {
     aborted: true;
@@ -7,8 +7,8 @@ export type LoadingResult<T = unknown> = {
     result: T;
 };
 export declare function withLoading<T>(this: void, model: IValueModel<boolean>, cb: LoadingWorker<T>, exclusive?: boolean | 'throw'): Promise<LoadingResult<T>>;
-export declare class LoadingModel implements IValueModel<boolean>, IResetableModel {
-    protected readonly _number: IValueModel<number> & IResetableModel;
+export declare class LoadingModel implements IValueModel<boolean>, IResettableModel {
+    protected readonly _number: IValueModel<number> & IResettableModel;
     protected _firstInit: boolean;
     /**
      * @param useFirstInit - if true, then `isLoading` will be returning 'true' until first `useLoading` call. Defaults to false.
@@ -27,7 +27,7 @@ export declare class LoadingModel implements IValueModel<boolean>, IResetableMod
     /** override me
      *
      * Called in the ctor. Should be pure and should NOT access `this`. */
-    protected pureConstructNumberModel(): IValueModel<number> & IResetableModel;
+    protected pureConstructNumberModel(): IValueModel<number> & IResettableModel;
 }
 export declare class ExclusiveLoadingError extends Error {
     readonly actionName?: string | undefined;

package/types/models/LogicModel.d.ts

@@ -5,7 +5,7 @@ import { Loggable } from '../logger/loggable.js';
 export type ActionRunOptions = {
     /** Action name, required for logging and joining. */
     name?: string;
-    /** If set to truthy, will not start an action if another is still in progress.
+    /** If set to truthy, will not start this action if another is still in progress.
      * Additionally, if set to 'throw', will throw an error. Otherwise, will return undefined.
      *
      * Note: if a current action runs in an exclusive mode, but the next one is not, the next one will still be allowed.

package/types/models/Model.d.ts

@@ -1,7 +1,7 @@
-import type { IResetableModel, IValueModel } from './types.js';
+import type { IResettableModel, IValueModel } from './types.js';
 import { Getter } from '../types/getter.js';
 import type { Nullable } from '../types/misc.js';
-export declare class Model<T> implements IValueModel<Nullable<T>>, IResetableModel {
+export declare class Model<T> implements IValueModel<Nullable<T>>, IResettableModel {
     private _value;
     private readonly _defaultValue;
     constructor(v?: Getter<Nullable<T>>);

package/types/models/types.d.ts

@@ -7,7 +7,7 @@ export interface IValueModel<TValue> extends IValueModelReadonly<TValue> {
 export interface ILabel<T> {
     readonly label: T;
 }
-export interface IResetableModel {
+export interface IResettableModel {
     readonly reset: () => void;
     readonly isDefault?: boolean;
 }

package/types/structures/path/index.d.ts

@@ -1,2 +1,2 @@
-export * from './utils.js';
+export * from './utils/index.js';
 export * as Path from './builder.js';

package/types/structures/path/types.d.ts

@@ -1,6 +1,6 @@
 import type { EmptyObject, Expand, IsNever, LengthArray, Nullable } from '../../types/misc.js';
 import type { ArgValue, IsOptional, ReadonlyArrayNormalized, TemplateTransform, ToOptionalArray, ToRequired, ToRequiredArray, TransformMap } from './types.helpers.js';
-import type { CombineOptions } from './utils.js';
+import type { CombineOptions } from './utils/combineUrls.js';
 export type ObjectBuilderArgs<TArgs extends string, TFallback = EmptyObject> = string extends TArgs ? TFallback : ArgRecord<TArgs>;
 export type BuilderArgs<TArgs extends string, L extends number = number> = LengthArray<ArgValue | null, L> | ArgRecord<TArgs>;
 export type ArgRecord<T extends string> = Expand<{

package/types/structures/path/{utils.d.ts → utils/combineUrls.d.ts}

@@ -1,5 +1,4 @@
-import type { Nullable } from '../../types/misc.js';
-export declare function indexTrim(str: string | null | undefined, ch: string): string;
+import type { Nullable } from '../../../types/misc.js';
 export type CombineOptions = {
     noTrim?: boolean;
     addTrail?: boolean | string;

package/types/structures/path/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './indexTrim.js';
+export * from './combineUrls.js';
+export * from './optionals.js';

package/types/structures/path/utils/indexTrim.d.ts

@@ -0,0 +1,2 @@
+export type TrimChar<T extends string, C extends string> = [T] extends undefined ? '' : T extends `${C}${infer R}` ? TrimChar<R, C> : T extends `${infer R}${C}` ? TrimChar<R, C> : T;
+export declare function indexTrim<T extends string, C extends string>(str: T | null | undefined, ch: C): TrimChar<T, C>;

package/types/structures/path/utils/optionals.d.ts

@@ -0,0 +1,2 @@
+/** Reformats path from format `'/foo/bar?'` to `'/foo{/bar}'`, according to the latest `path-to-regex` lib rules */
+export declare function replaceOptionalParts(pathname: string): string;

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>>;
 }

package/types/types/misc.d.ts

@@ -1,11 +1,11 @@
 export type Predicate<T> = (value: T) => boolean;
 /** Type for extracting only string keys from T (skips number & symbol keys) */
-export type StringKeys<T extends AnyObject> = {
+export type StringKeys<T extends AnyObject> = Exclude<{
     [K in keyof T]: K extends string ? K : never;
-}[keyof T];
+}[keyof T], undefined | null>;
 /** Type for extracting string keys of type `T` values of each are of certain type `K` */
 export type TypedKeys<T extends AnyObject, K> = {
-    [P in StringKeys<T>]: T[P] extends K ? P : never;
+    [P in StringKeys<T>]: T[P] extends (K | undefined) ? P : never;
 }[StringKeys<T>];
 /** Type for extraction only keys, values of which are functions with certain args and return result */
 export type FunctionKeys<T extends AnyObject, TArgs extends any[] = any[], TRes = any> = TypedKeys<T, (...args: TArgs) => TRes>;

package/cjs/structures/path/utils.js.map

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

package/esm/structures/path/utils.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../../src/structures/path/utils.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,SAAS,CAAC,GAA8B,EAAE,EAAU;IAChE,IAAI,CAAC,GAAG,IAAI,GAAG,KAAK,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;QAC5B,OAAO,EAAE,CAAC;IACd,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;IAEhC,OAAO,KAAK,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE;QACnC,EAAE,KAAK,CAAC;IAEZ,OAAO,GAAG,GAAG,KAAK,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE;QACrC,EAAE,GAAG,CAAC;IAEV,OAAO,CAAC,KAAK,GAAG,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC;QAClC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC;QAC3B,CAAC,CAAC,GAAG,CAAC;AACd,CAAC;AAWD,MAAM,KAAW,cAAc,CAI9B;AAJD,WAAiB,cAAc;IAC3B,SAAgB,KAAK,CAAC,GAAG,OAAmC;QACxD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;IACzC,CAAC;IAFe,oBAAK,QAEpB,CAAA;AACL,CAAC,EAJgB,cAAc,KAAd,cAAc,QAI9B;AAKD,MAAM,UAAU,WAAW,CAAC,GAAG,KAA0C;IACrE,MAAM,OAAO,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;QACxC,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,KAAK,CAAC,CAAC,CAA6B,CAAC;IAE3C,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,GAAG,CAAC;IAC5C,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,GAAG,CAAC;IAE9C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;IACxC,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACpB,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;YACxB,SAAS;QACb,CAAC;QAED,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,IAAI,GAAG,SAAS,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC;QACpC,CAAC;QAED,IAAI,IAAI,EAAE,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;IACL,CAAC;IAED,IAAI,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEpC,oFAAoF;IACpF,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,IAAI,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC,EAAE,CAAC;QACxE,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;YAC7C,CAAC,CAAC,OAAO,CAAC,QAAQ;YAClB,CAAC,CAAC,SAAS,CAAC;QAChB,MAAM,IAAI,IAAI,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;QACpB,MAAM,IAAI,GAAG,OAAO,OAAO,CAAC,QAAQ,KAAK,QAAQ;YAC7C,CAAC,CAAC,OAAO,CAAC,QAAQ;YAClB,CAAC,CAAC,SAAS,CAAC;QAChB,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;IAC3B,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC"}