@tstdl/base 0.92.145 → 0.92.148

package/serializer/types.d.ts

@@ -1,4 +1,4 @@
-import type { AbstractConstructor, JsonPrimitive, Nested, Record } from '../types.js';
+import type { AbstractConstructor, JsonPrimitive, Nested, Record } from '../types/index.js';
 declare const serializedSymbol: unique symbol;
 declare const stringSerializedSymbol: unique symbol;
 declare const decycledSymbol: unique symbol;

package/templates/module.d.ts

@@ -1,4 +1,4 @@
-import type { Type } from '../types.js';
+import type { Type } from '../types/index.js';
 import { TemplateProvider } from './template.provider.js';
 import { TemplateRenderer } from './template.renderer.js';
 import { TemplateResolver } from './template.resolver.js';

package/templates/renderers/handlebars.template-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { ObjectLiteral, Record } from '../../types.js';
+import type { ObjectLiteral, Record } from '../../types/index.js';
 import type * as Handlebars from 'handlebars';
 import { TemplateResolverProvider } from '../template-resolver.provider.js';
 import type { TemplateField } from '../template.model.js';

package/templates/renderers/jsx.template-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { Record } from '../../types.js';
+import type { Record } from '../../types/index.js';
 import type { JsxTemplate } from '../resolvers/jsx.template-resolver.js';
 import type { TemplateRenderObject, TemplateRenderResult } from '../template.renderer.js';
 import { TemplateRenderer } from '../template.renderer.js';

package/templates/renderers/mjml.template-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { Record } from '../../types.js';
+import type { Record } from '../../types/index.js';
 import type { MJMLParsingOptions } from 'mjml-core';
 import { TemplateRendererProvider } from '../template-renderer.provider.js';
 import type { TemplateRenderObject, TemplateRenderResult } from '../template.renderer.js';

package/templates/renderers/string.template-renderer.d.ts

@@ -1,4 +1,4 @@
-import type { Record } from '../../types.js';
+import type { Record } from '../../types/index.js';
 import type { StringTemplate } from '../resolvers/string.template-resolver.js';
 import type { TemplateRenderObject, TemplateRenderResult } from '../template.renderer.js';
 import { TemplateRenderer } from '../template.renderer.js';

package/templates/resolvers/file.template-resolver.d.ts

@@ -1,5 +1,5 @@
 import { type Resolvable, resolveArgumentType } from '../../injector/interfaces.js';
-import type { TypedOmit } from '../../types.js';
+import type { TypedOmit } from '../../types/index.js';
 import { TemplateField } from '../template.model.js';
 import type { TemplateRenderer, TemplateRendererOptions, TemplateRendererString } from '../template.renderer.js';
 import { TemplateResolver } from '../template.resolver.js';

package/templates/resolvers/jsx.template-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { PartialProperty, Record, TypedOmit } from '../../types.js';
+import type { PartialProperty, Record, TypedOmit } from '../../types/index.js';
 import type { ComponentClass, FunctionComponent } from 'preact';
 import { type Template, TemplateField } from '../template.model.js';
 import type { TemplateRenderer, TemplateRendererOptions, TemplateRendererString } from '../template.renderer.js';

package/templates/resolvers/string.template-resolver.d.ts

@@ -1,4 +1,4 @@
-import type { Record, TypedOmit } from '../../types.js';
+import type { Record, TypedOmit } from '../../types/index.js';
 import { TemplateField } from '../template.model.js';
 import type { TemplateRenderer, TemplateRendererOptions, TemplateRendererString } from '../template.renderer.js';
 import { TemplateResolver } from '../template.resolver.js';

package/templates/template.model.d.ts

@@ -1,4 +1,4 @@
-import type { PickBy, Record, SimplifyObject } from '../types.js';
+import type { PickBy, Record, SimplifyObject } from '../types/index.js';
 export type TemplateContext<T extends Template> = Parameters<NonNullable<T[typeof templateContext]>>[0];
 declare const templateContext: unique symbol;
 export declare class TemplateField<Resolver extends string = string, Renderer extends string = string, Options = any, Context extends Record = any> {

package/templates/template.renderer.d.ts

@@ -1,5 +1,5 @@
 import type { SchemaTestable } from '../schema/index.js';
-import type { Record } from '../types.js';
+import type { Record } from '../types/index.js';
 export type TemplateRenderResult = string;
 export type TemplateRenderObject<Renderer extends string = string, Options = any, V = unknown> = {
     renderer: Renderer;

package/templates/template.service.d.ts

@@ -1,4 +1,4 @@
-import type { Record } from '../types.js';
+import type { Record } from '../types/index.js';
 import { TemplateRendererProvider } from './template-renderer.provider.js';
 import { TemplateResolverProvider } from './template-resolver.provider.js';
 import type { Template, TemplateContext } from './template.model.js';

package/text/dynamic-text.model.d.ts

@@ -1,6 +1,6 @@
 import { type Observable } from 'rxjs';
 import { type Signal } from '../signals/api.js';
-import type { PickBy, ReactiveValue, ReplaceKey } from '../types.js';
+import type { PickBy, ReactiveValue, ReplaceKey } from '../types/index.js';
 import type { LocalizableText } from './localizable-text.model.js';
 import { LocalizationService } from './localization.service.js';
 export type DynamicText = ReactiveValue<LocalizableText>;

package/text/localization.service.d.ts

@@ -1,7 +1,7 @@
 import type { Observable } from 'rxjs';
 import { Logger } from '../logger/index.js';
 import type { Signal } from '../signals/api.js';
-import type { Enumeration, EnumerationValue, Record } from '../types.js';
+import type { Enumeration, EnumerationValue, Record } from '../types/index.js';
 import type { PropertyName } from '../utils/object/property-name.js';
 export type Language = {
     code: string;

package/types/geo-json.d.ts

@@ -1,4 +1,4 @@
-import type { JsonObject } from '../types.js';
+import type { JsonObject } from './types.js';
 export type Position = [longitude: number, latitude: number, elevation?: number];
 export type GeoJsonObject<Type extends string> = {
     type: Type;

package/types/index.d.ts

@@ -1,2 +1,4 @@
 export type * from './geo-json.js';
 export type * from './tagged.js';
+export type * from './types.js';
+export type * from './web-types.js';

package/types/tagged.d.ts

@@ -1,4 +1,4 @@
-import type { Record } from '../types.js';
+import type { Record } from './types.js';
 export declare const tag: unique symbol;
 export declare const type: unique symbol;
 export type TagContainer<Type, Token> = {

package/{types.d.ts → types/types.d.ts}

@@ -1,6 +1,6 @@
 import type { Observable } from 'rxjs';
 import type { CamelCase, Except, IsEqual, LiteralUnion } from 'type-fest';
-import type { Signal } from './signals/api.js';
+import type { Signal } from '../signals/api.js';
 export type ObjectLiteral = {};
 export type Function<P extends any[] = any[], R = any> = (...params: P) => R;
 export type PrimitiveTypeMap = {
@@ -149,6 +149,7 @@ export type PickBy<T, V> = Pick<T, {
 export type NonNullable<T> = T extends null ? never : T;
 export type NonUndefinable<T> = T extends undefined ? never : T;
 export type NonNullOrUndefinable<T> = T extends null | undefined ? never : T;
+export type NoUnion<T> = [T] extends [boolean] ? boolean : [T] extends [UnionToIntersection<T>] ? T : never;
 /**
  * Makes optional properties required and removes null and undefined
  */

package/utils/async-hook/async-hook.d.ts

@@ -1,9 +1,118 @@
+/**
+ * Represents the public interface for an asynchronous hook.
+ *
+ * @template T The type of the value that the hook is triggered with.
+ * @template C The type of the optional context object passed to the hook's trigger and handlers. Defaults to `never`.
+ * @template R The return type of an individual handler. Defaults to `unknown`.
+ */
 export type AsyncHook<T, C = never, R = unknown> = {
+    /**
+     * Registers a handler function to be called when the hook is triggered.
+     * @param handler The async handler function to register.
+     * @returns A registration object with an `unregister` method to remove the handler.
+     */
     register: (handler: AsyncHookHandler<T, C, R>) => AsyncHookHandlerRegistration;
+    /**
+     * Triggers the hook, executing all registered handlers in sequence.
+     *
+     * The signature of this function is conditional:
+     * - If the context type `C` is `never` (the default), it accepts only the `value` argument.
+     * - If `C` is any other type, it requires both `value` and `context` arguments.
+     *
+     * @param value The value to pass to all handlers.
+     * @param context The context object to pass to all handlers (only required if `C` is not `never`).
+     * @returns A promise that resolves to an array of results from all handlers.
+     */
     trigger: [C] extends [never] ? ((value: T) => Promise<R[]>) : ((value: T, context: C) => Promise<R[]>);
 };
+/**
+ * Defines the signature for a handler function that can be registered with an `AsyncHook`.
+ * The function can be synchronous (returning `R`) or asynchronous (returning `Promise<R>`).
+ *
+ * The signature is conditional based on the context type `C`:
+ * - If `C` is `never`, the handler receives only the `value` argument.
+ * - If `C` is any other type, the handler receives both `value` and `context`.
+ *
+ * @template T The type of the value passed to the handler.
+ * @template C The type of the optional context object.
+ * @template R The expected return type of the handler.
+ */
 export type AsyncHookHandler<T, C, R> = [C] extends [never] ? ((value: T) => R | Promise<R>) : ((value: T, context: C) => R | Promise<R>);
+/**
+ * Represents the object returned when a handler is registered,
+ * allowing for its subsequent unregistration.
+ */
 export type AsyncHookHandlerRegistration = {
+    /**
+     * Unregisters the handler, preventing it from being called in future triggers.
+     */
     unregister: () => void;
 };
+/**
+ * Creates a new asynchronous hook.
+ *
+ * An async hook is a system that allows you to register multiple "handler" functions
+ * that will be executed in sequence when a "trigger" event occurs. This is useful
+ * for creating extensible, plugin-like architectures. Handlers can be synchronous
+ * or asynchronous.
+ *
+ * @template T The type of the primary value that the hook is triggered with.
+ * @template C The type of the optional context object passed to the hook's trigger and handlers. Defaults to `never`.
+ * @template R The return type of an individual handler. The `trigger` method will resolve with an array of these values (`R[]`). Defaults to `unknown`.
+ * @returns {AsyncHook<T, C, R>} An object with `register` and `trigger` methods.
+ *
+ * @example
+ * ```ts
+ * // Simple hook without context
+ * async function runSimpleExample() {
+ *   const onTaskStart = asyncHook<string>();
+ *
+ *   onTaskStart.register(taskName => {
+ *     console.log(`[Logger] Task started: ${taskName}`);
+ *   });
+ *
+ *   const registration = onTaskStart.register(async taskName => {
+ *     await new Promise(resolve => setTimeout(resolve, 50));
+ *     console.log(`[Notifier] Notifying that task started: ${taskName}`);
+ *   });
+ *
+ *   await onTaskStart.trigger('Process Data');
+ *   // [Logger] Task started: Process Data
+ *   // [Notifier] Notifying that task started: Process Data
+ *
+ *   registration.unregister();
+ *   console.log('Notifier unregistered.');
+ *
+ *   await onTaskStart.trigger('Finalize Report');
+ *   // [Logger] Task started: Finalize Report
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hook with a context object
+ * async function runContextExample() {
+ *   type TaskContext = { userId: number; transactionId: string };
+ *
+ *   const onTaskComplete = asyncHook<string, TaskContext, boolean>();
+ *
+ *   onTaskComplete.register((taskName, context) => {
+ *     console.log(`[Audit] Task '${taskName}' completed by user ${context.userId}.`);
+ *     return true; // Audit successful
+ *   });
+ *
+ *   onTaskComplete.register(async (taskName, context) => {
+ *     console.log(`[DB] Logging completion of '${taskName}' for transaction ${context.transactionId}.`);
+ *     return true; // DB update successful
+ *   });
+ *
+ *   const results = await onTaskComplete.trigger(
+ *     'SubmitOrder',
+ *     { userId: 123, transactionId: 'abc-456' }
+ *   );
+ *
+ *   console.log('Handler results:', results); // [true, true]
+ * }
+ * ```
+ */
 export declare function asyncHook<T, C = never, R = unknown>(): AsyncHook<T, C, R>;

package/utils/async-hook/async-hook.js

@@ -1,3 +1,70 @@
+/**
+ * Creates a new asynchronous hook.
+ *
+ * An async hook is a system that allows you to register multiple "handler" functions
+ * that will be executed in sequence when a "trigger" event occurs. This is useful
+ * for creating extensible, plugin-like architectures. Handlers can be synchronous
+ * or asynchronous.
+ *
+ * @template T The type of the primary value that the hook is triggered with.
+ * @template C The type of the optional context object passed to the hook's trigger and handlers. Defaults to `never`.
+ * @template R The return type of an individual handler. The `trigger` method will resolve with an array of these values (`R[]`). Defaults to `unknown`.
+ * @returns {AsyncHook<T, C, R>} An object with `register` and `trigger` methods.
+ *
+ * @example
+ * ```ts
+ * // Simple hook without context
+ * async function runSimpleExample() {
+ *   const onTaskStart = asyncHook<string>();
+ *
+ *   onTaskStart.register(taskName => {
+ *     console.log(`[Logger] Task started: ${taskName}`);
+ *   });
+ *
+ *   const registration = onTaskStart.register(async taskName => {
+ *     await new Promise(resolve => setTimeout(resolve, 50));
+ *     console.log(`[Notifier] Notifying that task started: ${taskName}`);
+ *   });
+ *
+ *   await onTaskStart.trigger('Process Data');
+ *   // [Logger] Task started: Process Data
+ *   // [Notifier] Notifying that task started: Process Data
+ *
+ *   registration.unregister();
+ *   console.log('Notifier unregistered.');
+ *
+ *   await onTaskStart.trigger('Finalize Report');
+ *   // [Logger] Task started: Finalize Report
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Hook with a context object
+ * async function runContextExample() {
+ *   type TaskContext = { userId: number; transactionId: string };
+ *
+ *   const onTaskComplete = asyncHook<string, TaskContext, boolean>();
+ *
+ *   onTaskComplete.register((taskName, context) => {
+ *     console.log(`[Audit] Task '${taskName}' completed by user ${context.userId}.`);
+ *     return true; // Audit successful
+ *   });
+ *
+ *   onTaskComplete.register(async (taskName, context) => {
+ *     console.log(`[DB] Logging completion of '${taskName}' for transaction ${context.transactionId}.`);
+ *     return true; // DB update successful
+ *   });
+ *
+ *   const results = await onTaskComplete.trigger(
+ *     'SubmitOrder',
+ *     { userId: 123, transactionId: 'abc-456' }
+ *   );
+ *
+ *   console.log('Handler results:', results); // [true, true]
+ * }
+ * ```
+ */
 export function asyncHook() {
     const handlers = [];
     return {
@@ -5,13 +72,20 @@ export function asyncHook() {
             handlers.push(handler);
             return {
                 unregister() {
-                    handlers.splice(handlers.indexOf(handler));
+                    const index = handlers.indexOf(handler);
+                    if (index > -1) {
+                        handlers.splice(index, 1);
+                    }
                 },
             };
         },
+        // The implementation uses a single function body, but the public type signature
+        // is conditional, ensuring type safety for callers.
         trigger: async (value, context) => {
-            let returnValues = [];
-            for (const handler of handlers) {
+            const returnValues = [];
+            // Create a snapshot of handlers in case one of them unregisters another during its execution.
+            for (const handler of [...handlers]) {
+                // The non-null assertion `context!` is safe due to the conditional public type of `trigger`.
                 const returnValue = await handler(value, context);
                 returnValues.push(returnValue);
             }

package/utils/backoff.d.ts

@@ -1,77 +1,159 @@
 import type { CancellationSignal } from '../cancellation/token.js';
-import { CancellationToken } from '../cancellation/token.js';
 export type BackoffStrategy = 'linear' | 'exponential';
+/**
+ * Configuration for the backoff behavior.
+ */
 export type BackoffOptions = {
     /**
-     * how to increase delay
+     * The strategy to use for increasing the delay.
+     * - `linear`: Adds the `increase` value to the delay in each step.
+     * - `exponential`: Multiplies the delay by the `increase` value in each step.
+     * @default 'exponential'
      */
-    strategy: BackoffStrategy;
+    strategy?: BackoffStrategy;
     /**
-     * delay to start with
+     * The initial delay in milliseconds. Must be non-negative.
+     * @default 1000
      */
-    initialDelay: number;
+    initialDelay?: number;
     /**
-     * amount to increase/multiply delay by/with
+     * The value to increase the delay with.
+     * - For `linear` strategy, this is the number of milliseconds to add.
+     * - For `exponential` strategy, this is the multiplication factor.
+     * Must be non-negative. For exponential, should be > 1 to ensure growth.
+     * @default 2
      */
-    increase: number;
+    increase?: number;
     /**
-     * miaxmum time to back off
+     * The maximum delay in milliseconds. The backoff delay will not exceed this value.
+     * @default 30000
      */
     maximumDelay?: number;
+    /**
+     * A factor to randomize the delay, e.g., 0.1 for 10% jitter.
+     * This helps prevent the "thundering herd" problem in distributed systems.
+     * The actual delay will be `delay ± delay * jitter`.
+     * Must be a value between 0 and 1.
+     * @default 0.15
+     */
+    jitter?: number;
+};
+export type AutoBackoffLoopOptions = BackoffOptions & {
+    cancellationSignal?: CancellationSignal;
+    errorHandler?: (error: Error) => void;
+};
+export type BackoffLoopOptions = BackoffOptions & {
+    cancellationSignal?: CancellationSignal;
+};
+export type BackoffGeneratorOptions = BackoffOptions & {
+    /**
+     * An optional signal to terminate the generator.
+     * The generator can also be terminated by breaking the `for-await-of` loop.
+     */
+    cancellationSignal?: CancellationSignal;
 };
+/**
+ * Provides controls for the `backoffLoop`.
+ */
 export type BackoffLoopController = {
     /**
-     * backoff before next iteration
+     * Schedules a backoff delay before the next iteration of the loop.
+     * If this is not called, the backoff delay is reset for the next attempt.
      */
     backoff: () => void;
     /**
-     * break out of loop
+     * Immediately breaks out of the loop.
      */
     break: () => void;
 };
-export type BackoffLoopFunction = (controller: BackoffLoopController) => void | Promise<void>;
+export type BackoffLoopFunction = (controller: BackoffLoopController, cancellationSignal: CancellationSignal) => unknown;
+/**
+ * A function yielded by `backoffGenerator` to control the next iteration.
+ */
+export type BackoffGeneratorCallback = (options?: {
+    /**
+     * An optional signal that, when set, cancels the current backoff delay and proceeds
+     * to the next iteration immediately. This is useful for "continue early" scenarios.
+     */
+    continueToken?: CancellationSignal;
+}) => void;
+/**
+ * Default options for a robust backoff strategy.
+ */
+export declare const DEFAULT_BACKOFF_OPTIONS: {
+    readonly strategy: "exponential";
+    readonly initialDelay: 1000;
+    readonly increase: 2;
+    readonly maximumDelay: 30000;
+    readonly jitter: 0.15;
+};
 /**
- * @param continueToken token to continue loop immediately
+ * A helper class to manage the state of a backoff strategy.
  */
-export type BackoffGeneratorYield = (continueToken?: CancellationToken) => void;
 export declare class BackoffHelper {
-    private readonly strategy;
-    private readonly initialDelay;
-    private readonly increase;
-    private readonly maximumDelay;
-    private delay;
-    constructor({ strategy, initialDelay, increase, maximumDelay }: BackoffOptions);
+    private readonly options;
+    private currentDelay;
+    /**
+     * Creates a new BackoffHelper.
+     * @param options Partial backoff options, which will be merged with sane defaults.
+     */
+    constructor(options?: BackoffOptions);
+    /**
+     * Resets the current delay to the initial delay.
+     */
     reset(): void;
-    backoff(): number;
+    /**
+     * Calculates and returns the next backoff delay based on the configured strategy.
+     * This also updates the internal state for the subsequent call.
+     * @returns The next delay in milliseconds.
+     */
+    getNextDelay(): number;
 }
 /**
- * runs a function until token is set or controller returns and automatically backsoff if function throws. Warning: swallows errors
- * @param options backoff options
- * @param cancellationToken token to cancel loop
- * @param loopFunction function to call
+ * Runs a function in a loop, automatically backing off on errors.
+ *
+ * This function is a convenient wrapper that catches any errors from `loopFunction`,
+ * triggers a backoff, and continues the loop.
+ *
+ * @param loopFunction The asynchronous function to execute in each iteration.
+ * @param options Additional options for backoff configuration, cancellation, and error handling.
  */
-export declare function autoBackoffLoop(options: BackoffOptions, loopFunction: BackoffLoopFunction, extras?: {
-    cancellationSignal?: CancellationSignal;
-    errorHandler?: (error: Error) => void;
-}): Promise<void>;
+export declare function autoBackoffLoop(loopFunction: BackoffLoopFunction, options?: AutoBackoffLoopOptions): Promise<void>;
 /**
- * runs a function until token is set or controller returns.
- * @param options backoff options
- * @param cancellationToken signal to cancel loop
- * @param loopFunction function to call
+ * Runs a function in a loop, allowing manual control over backoff and breaking.
+ * The loop continues until it is explicitly broken via the controller or the cancellation signal is set.
+ * If `controller.backoff()` is not called in an iteration, the delay is reset for the next backoff.
+ *
+ * @param loopFunction The function to execute, receiving a controller to manage the loop.
+ * @param options Additional options for backoff configuration and cancellation.
  */
-export declare function backoffLoop(options: BackoffOptions, loopFunction: BackoffLoopFunction, extras?: {
-    cancellationSignal?: CancellationSignal;
-}): Promise<void>;
+export declare function backoffLoop(loopFunction: BackoffLoopFunction, options?: BackoffLoopOptions): Promise<void>;
 /**
- * generates endless function which, when called, backs off next iteration
- * @param options backoff options
- * @param cancellationSignal signal to cancel loop
+ * Creates an async generator that yields a callback to trigger a backoff.
+ * This is useful for `for-await-of` loops where you need fine-grained control.
+ * The generator terminates when the `cancellationSignal` is set or the loop is terminated by break.
+ *
+ * @param options Options for backoff configuration and an optional cancellation signal.
  * @example
- * for await (const backoff of backoffGenerator(options, token)) {
- *  if (iWantToBackoff) {
- *    backoff();
- *  }
+ * ```ts
+ * const token = new CancellationToken();
+ *
+ * // with a cancellation signal
+ * for await (const backoff of backoffGenerator({ cancellationSignal: token.signal })) {
+ *   const success = await doSomeWork();
+ *   if (!success) {
+ *     backoff(); // Schedule a backoff before the next iteration.
+ *   }
+ * }
+ *
+ * // without a cancellation signal (loop is broken manually)
+ * for await (const backoff of backoffGenerator()) {
+ *   const success = await doSomeWork();
+ *   if (success) {
+ *     break; // Exit the loop
+ *   }
+ *   backoff();
  * }
+ * ```
  */
-export declare function backoffGenerator(options: BackoffOptions, cancellationSignal: CancellationSignal): AsyncIterableIterator<BackoffGeneratorYield>;
+export declare function backoffGenerator(options?: BackoffGeneratorOptions): AsyncIterableIterator<BackoffGeneratorCallback>;