@zajno/common 2.6.3 → 2.6.5

package/types/api/extensions/validation.d.ts

@@ -1,12 +1,13 @@
+import { AnyObject } from '../../types/misc.js';
 import type { ApiEndpoint } from '../endpoint.js';
 import type { IEndpointInfo } from '../endpoint.types.js';
 export interface IEndpointInputValidation {
-    readonly validate?: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this>>;
+    readonly validate?: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this, AnyObject>>;
     withValidation(validator: IEndpointInputValidation.Validator<IEndpointInfo.ExtractIn<this>>): this;
 }
 export declare namespace IEndpointInputValidation {
     type Validator<TIn> = (input: TIn) => Promise<void> | void;
     const extender: ApiEndpoint.IBuilderExtender<IEndpointInputValidation>;
     function guard(api: IEndpointInfo): api is (IEndpointInfo & IEndpointInputValidation);
-    function tryValidate(api: IEndpointInfo, input: IEndpointInfo.ExtractIn<IEndpointInfo>): void | Promise<void>;
+    function tryValidate(api: IEndpointInfo, input: AnyObject): void | Promise<void>;
 }

package/types/api/helpers.d.ts

@@ -4,6 +4,6 @@ export declare const DefaultSettings: {
     basePrefix: string;
 };
 export declare function setDefaults(settings: Partial<typeof DefaultSettings>): void;
-export declare function getPath<T extends IEndpointInfo.IPath<K>, K extends readonly string[]>(endpoint: T, pathArgs: IEndpointInfo.ExtractPath<T>, prefix?: string | boolean): string;
+export declare function getPath<T extends IEndpointInfo.Base & IEndpointInfo.IPathAbstract>(endpoint: T, pathArgs: IEndpointInfo.ExtractPath<T>, prefix?: string | boolean): string;
 export declare function getTemplate<T extends IEndpointInfo>(endpoint: T, prefix?: string | boolean): string;
 export declare function getFormattedDisplayName(endpoint: IEndpointInfo): string;

package/types/async/arrays.d.ts

@@ -1,4 +1,4 @@
-export declare function someAsync<T>(target: ReadonlyArray<T>, condition: (v: T, index?: number, arr?: ReadonlyArray<T>) => Promise<boolean>): Promise<boolean>;
-export declare function everyAsync<T>(target: ReadonlyArray<T>, condition: (v: T, index?: number, arr?: ReadonlyArray<T>) => Promise<boolean>): Promise<boolean>;
-export declare function forEachAsync<T>(target: ReadonlyArray<T>, cb: (v: T, index?: number, arr?: ReadonlyArray<T>) => Promise<void>): Promise<void>;
-export declare function mapAsync<T, R>(target: ReadonlyArray<T>, cb: (v: T, index?: number, arr?: ReadonlyArray<T>) => Promise<R>): Promise<R[]>;
+export declare function someAsync<T>(target: ReadonlyArray<T>, condition: (v: T, index: number, arr: ReadonlyArray<T>) => Promise<boolean>): Promise<boolean>;
+export declare function everyAsync<T>(target: ReadonlyArray<T>, condition: (v: T, index: number, arr: ReadonlyArray<T>) => Promise<boolean>): Promise<boolean>;
+export declare function forEachAsync<T>(target: ReadonlyArray<T>, cb: (v: T, index: number, arr: ReadonlyArray<T>) => Promise<void>): Promise<void>;
+export declare function mapAsync<T, R>(target: ReadonlyArray<T>, cb: (v: T, index: number, arr: ReadonlyArray<T>) => Promise<R>): Promise<R[]>;

package/types/dates/tz.d.ts

@@ -1,7 +1,19 @@
-/** This is experimental stuff, so no tests provided, see comments in the code */
+/** Helpers for time zones, based on `Intl.DateTimeFormat` */
 export declare namespace Timezones {
     const Current: string;
     const CurrentOffset: number;
-    const getOffset: (timeZone: string) => number;
+    /**
+     * Get the offset in minutes for a given time zone and date. Uses Intl.DateTimeFormat
+     * to get the time zone name, then parses it to get the offset.
+     * @param timeZone time zone name, e.g. 'America/New_York', 'Europe/Kyiv', etc.
+     * @param date date to get the offset for. If not provided, uses the current date.
+     * @returns offset in minutes. Positive values are west of UTC, negative values are east of UTC.
+     */
+    function getOffset(timeZone: string, date?: Date | number): number;
+    /** Returns a new date with the specified timezone offset applied.
+     *
+     * Usage case can be imagined like this: if your local wall clock shows time X,
+     * what your clock will show when another local wall clock in the specified timezone will be showing time X.
+    */
     function shiftToTimeZone(date: Date, tz: string | number): Date;
 }

package/types/observing/event.late.d.ts

@@ -1,4 +1,12 @@
 import { Event, EventHandler } from './event.js';
+/**
+ * One-time event that can be triggered only once, but listeners will be notified at the time of event or subscription, if it happens later.
+ *
+ * Useful for solving race conditions, when components initialization order is undetermined.
+ *
+ * Example usage: app initialization finished event, but some async components can subscribe later and be notified;
+ * So subscribers can be sure that the main initialization is finished.
+ */
 export declare class OneTimeLateEvent<T = any> extends Event<T> {
     private _triggeredWith;
     private _triggered;

package/types/observing/timeout.d.ts

@@ -0,0 +1,25 @@
+import type { IDisposable } from '../functions/disposer.js';
+import { type IEvent } from './event.js';
+export interface ITimeout extends IDisposable {
+    /** Fired when the timeout has elapsed. Passes actual elapsed milliseconds. */
+    readonly event: IEvent<number>;
+    /** Whether the timeout is running */
+    readonly isRunning: boolean;
+    /** Starts the timeout */
+    start(delay: number, callback?: () => void): Promise<number>;
+    /** Stops the timeout, event will not be triggered. */
+    stop(): void;
+}
+/**
+ * Simple one-off `setTimeout` wrapper/abstraction.
+ * Handle timeout via event, callback or Promise.
+ */
+export declare class Timeout implements ITimeout {
+    private _cancelCb;
+    private readonly _event;
+    get event(): IEvent<number>;
+    get isRunning(): boolean;
+    start(delay: number, callback?: () => void): Promise<number>;
+    stop(): void;
+    dispose(): void;
+}

package/types/observing/timer.d.ts

@@ -6,6 +6,11 @@ export type TimerState = {
     left: number;
     now: number;
 };
+/**
+ * A timer wraps `setInterval` and provides a more convenient API.
+ * It will fire an event every `interval` milliseconds.
+ * It also may have duration which means it will stop when elapsed time is greater than or equal to the duration.
+ */
 export declare class Timer implements IDisposable, IEvent<TimerState> {
     readonly interval: number;
     private readonly _event;

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

@@ -1,9 +1,13 @@
-import type { LengthArray, Nullable } from '../../types/misc.js';
+import type { EmptyObject, LengthArray, Nullable } from '../../types/misc.js';
 import type { CombineOptions } from './utils.js';
 export type ArgValue = string | number;
-export type ObjectBuilderArgs<TArgs extends string> = Record<TArgs, ArgValue>;
+export type ObjectBuilderArgs<TArgs extends string, TOptional = false, TFallback = EmptyObject> = string extends TArgs ? TFallback : true extends TOptional ? MakeOptional<Record<TArgs, ArgValue>> : Record<TArgs, ArgValue>;
 export type BuilderArgs<TArgs extends string, L extends number = number> = LengthArray<ArgValue, L> | Record<TArgs, ArgValue>;
 export type TemplatePrefixing = Nullable<string | ((key: string, index: number) => string)>;
+type MakeOptional<T> = {
+    [P in keyof T]?: Nullable<T[P]>;
+};
+/** Internal, Don't use it directly */
 interface BaseBuilder<A extends readonly string[], B, P = TemplatePrefixing> {
     /**
      * Builds the path using provided args.
@@ -45,17 +49,24 @@ export type TransformMap<A extends readonly string[]> = {
 };
 type EmptyBuilderArgs = [] | Record<PropertyKey, never>;
 type ReadonlyArr<TArr extends ReadonlyArray<any>> = TArr extends ReadonlyArray<infer T> ? ReadonlyArray<T> : never;
-export interface Builder<TArgs extends readonly string[]> extends BaseBuilder<ReadonlyArr<TArgs>, BuilderArgs<TArgs[number], TArgs['length']>> {
+export interface Builder<TArgs extends readonly string[], TOptional = false> extends BaseBuilder<ReadonlyArr<TArgs>, true extends TOptional ? MakeOptional<BuilderArgs<TArgs[number], TArgs['length']>> : BuilderArgs<TArgs[number], TArgs['length']>> {
+    /** Marks input type for `build` to be `Partial`, so any/all arguments can be omitted.
+     *
+     * **Limitation**: will convert to optional ALL parameters if >=2 Builders combined via CombineBuilders
+    */
+    asOptional(): Builder<TArgs, true>;
 }
 export interface StaticBuilder extends BaseBuilder<readonly [], EmptyBuilderArgs> {
 }
-export interface IBuilder extends BaseBuilder<readonly string[], BuilderArgs<string>> {
+export interface IBuilder extends BaseBuilder<readonly string[], any> {
 }
 export type StaticInput = string | readonly string[];
 export type BaseInput = StaticInput | BaseBuilder<any, any, any>;
-export type Output<TInput> = TInput extends StaticBuilder ? StaticBuilder : (TInput extends Builder<infer TArgs> ? Builder<TArgs> : StaticBuilder);
+export type Output<TInput> = TInput extends StaticBuilder ? StaticBuilder : (TInput extends Builder<infer TArgs, infer TOptional> ? Builder<TArgs, TOptional> : StaticBuilder);
 export type SwitchBuilder<TArg extends readonly string[]> = [TArg] extends [never] ? StaticBuilder : ([] extends TArg ? StaticBuilder : (readonly string[] extends TArg ? IBuilder : Builder<TArg>));
 export type ExtractArgs<T> = T extends Builder<infer TArgs> ? TArgs : readonly string[];
-type CombineTwo<T1 extends BaseInput, T2 extends BaseInput> = Output<T1> extends StaticBuilder ? Output<T2> : (Output<T2> extends StaticBuilder ? Output<T1> : (Output<T1> extends Builder<infer Arr1> ? (Output<T2> extends Builder<infer Arr2> ? Builder<[...Arr1, ...Arr2]> : never) : never));
-export type CombineBuilders<T extends BaseInput[]> = T extends [infer T1 extends BaseInput, infer T2 extends BaseInput, ...infer Rest] ? (CombineTwo<T1, T2> extends infer C extends BaseBuilder<any, any> & BaseInput ? (Rest extends BaseInput[] ? CombineBuilders<[C, ...Rest]> : never) : never) : (T extends [infer T1] ? Output<T1> : StaticBuilder);
+export type ExtractObjectArgs<T, F = EmptyObject> = T extends Builder<infer TArgs, infer O> ? ObjectBuilderArgs<TArgs[number], O, F> : F;
+type LogicalOr<O1, O2> = true extends O1 ? true : true extends O2 ? true : false;
+type CombineTwo<T1 extends BaseInput, T2 extends BaseInput> = Output<T1> extends StaticBuilder ? Output<T2> : (Output<T2> extends StaticBuilder ? Output<T1> : (Output<T1> extends Builder<infer Arr1, infer O1> ? (Output<T2> extends Builder<infer Arr2, infer O2> ? Builder<[...Arr1, ...Arr2], LogicalOr<O1, O2>> : never) : never));
+export type CombineBuilders<T extends readonly BaseInput[]> = T extends readonly [infer T1 extends BaseInput, infer T2 extends BaseInput, ...infer Rest] ? (CombineTwo<T1, T2> extends infer C extends BaseBuilder<any, any, any> & BaseInput ? (Rest extends readonly BaseInput[] ? CombineBuilders<readonly [C, ...Rest]> : never) : never) : (T extends readonly [infer T1] ? Output<T1> : StaticBuilder);
 export {};

package/types/types/misc.d.ts

@@ -34,4 +34,5 @@ export type PickNullable<T, K extends keyof T> = {
     [P in K]?: Nullable<T[P]>;
 };
 export type EmptyObjectNullable = (EmptyObject | null | undefined);
+export type IsNever<T, Y, N> = [T] extends [never] ? Y : N;
 export type Coalesce<T, TReplace = EmptyObjectNullable> = [T] extends [never] | [null] | [undefined] ? TReplace : T;