@nu-art/ts-common 0.401.0 → 0.401.2

package/consts/consts.d.ts

@@ -1 +1,2 @@
+/** Constant representing undefined (useful for type-safe undefined values) */
 export declare const _U: undefined;

package/consts/consts.js

@@ -15,4 +15,5 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+/** Constant representing undefined (useful for type-safe undefined values) */
 export const _U = undefined;

package/core/application.d.ts

@@ -1,5 +1,33 @@
 import { ModuleManager } from "./module-manager.js";
+/**
+ * Application class that extends ModuleManager with startup callback support.
+ *
+ * Provides a convenient way to execute code after all modules have been initialized.
+ * The `onStarted` callback is executed asynchronously and errors are caught and logged
+ * but don't prevent the application from continuing.
+ *
+ * @example
+ * ```typescript
+ * const app = new Application();
+ * app.addModulePack([ModuleA, ModuleB]);
+ * app.setConfig({ ... });
+ * app.build(async () => {
+ *   // This runs after all modules are initialized
+ *   await startServer();
+ * });
+ * ```
+ */
 export declare class Application extends ModuleManager {
     constructor();
+    /**
+     * Initializes all modules and optionally executes a startup callback.
+     *
+     * The callback is executed asynchronously (fire-and-forget). If the callback
+     * returns data, it will be logged. Errors in the callback are caught and logged
+     * but don't affect the application state.
+     *
+     * @param onStarted - Optional async callback to execute after initialization.
+     *                    The callback's return value (if any) will be logged.
+     */
     build(onStarted?: () => Promise<any>): void;
 }

package/core/application.js

@@ -16,10 +16,38 @@
  * limitations under the License.
  */
 import { ModuleManager } from "./module-manager.js";
+/**
+ * Application class that extends ModuleManager with startup callback support.
+ *
+ * Provides a convenient way to execute code after all modules have been initialized.
+ * The `onStarted` callback is executed asynchronously and errors are caught and logged
+ * but don't prevent the application from continuing.
+ *
+ * @example
+ * ```typescript
+ * const app = new Application();
+ * app.addModulePack([ModuleA, ModuleB]);
+ * app.setConfig({ ... });
+ * app.build(async () => {
+ *   // This runs after all modules are initialized
+ *   await startServer();
+ * });
+ * ```
+ */
 export class Application extends ModuleManager {
     constructor() {
         super();
     }
+    /**
+     * Initializes all modules and optionally executes a startup callback.
+     *
+     * The callback is executed asynchronously (fire-and-forget). If the callback
+     * returns data, it will be logged. Errors in the callback are caught and logged
+     * but don't affect the application state.
+     *
+     * @param onStarted - Optional async callback to execute after initialization.
+     *                    The callback's return value (if any) will be logged.
+     */
     build(onStarted) {
         super.build();
         onStarted && onStarted()

package/core/dispatcher.d.ts

@@ -1,20 +1,159 @@
 import { FunctionKeys, ReturnPromiseType } from '../utils/types.js';
-import { Logger } from './logger/Logger.js';
+import { Logger } from './logger/index.js';
+/**
+ * Type helper that extracts parameter types from a method on type T.
+ *
+ * @template T - The type containing the method
+ * @template K - The method key
+ */
 export type ParamResolver<T, K extends keyof T> = T[K] extends (...args: any) => any ? Parameters<T[K]> : never;
+/**
+ * Type helper that extracts return type from a method on type T, unwrapping Promises.
+ *
+ * @template T - The type containing the method
+ * @template K - The method key
+ */
 export type ReturnTypeResolver<T, K extends keyof T> = T[K] extends (...args: any) => any ? ReturnPromiseType<T[K]> : never;
+/**
+ * Base processor class that filters and processes modules based on method presence.
+ *
+ * Processor finds all modules that have a specific method and allows processing
+ * them in various ways (sync, async parallel, async serial).
+ *
+ * The `modulesResolver` must be set by ModuleManager during initialization to
+ * provide access to all registered modules.
+ *
+ * @template T - The interface/type that modules should implement
+ * @template K - The method name to look for on modules
+ *
+ * @example
+ * ```typescript
+ * interface EventHandler {
+ *   onEvent(data: string): void;
+ * }
+ *
+ * const processor = new Processor<EventHandler, 'onEvent'>('onEvent');
+ * processor.processModules(module => {
+ *   module.onEvent('data');
+ * });
+ * ```
+ */
 export declare class Processor<T, K extends FunctionKeys<T>> extends Logger {
+    /** Function that returns all registered modules (set by ModuleManager) */
     static modulesResolver: () => any[];
+    /** The method name this processor is looking for */
     readonly method: K;
+    /** Filter function that checks if a module has the target method */
     protected readonly filter: (listener: any) => boolean;
+    /**
+     * Creates a new Processor for a specific method.
+     *
+     * @param method - The method name to look for on modules
+     */
     constructor(method: K);
+    /**
+     * Processes all matching modules synchronously.
+     *
+     * Filters modules that have the target method and applies the processor
+     * function to each, collecting results in an array.
+     *
+     * @param processor - Function to apply to each matching module
+     * @returns Array of results from processing each module
+     */
     processModules<R>(processor: (item: T) => R): R[];
+    /**
+     * Processes all matching modules asynchronously in parallel.
+     *
+     * All modules are processed concurrently using Promise.all. Use this
+     * when modules can be processed independently and order doesn't matter.
+     *
+     * @param processor - Async function to apply to each matching module
+     * @returns Promise that resolves to an array of results
+     */
     processModulesAsync<R>(processor: (item: T) => Promise<R>): Promise<R[]>;
+    /**
+     * Processes all matching modules asynchronously in serial (one after another).
+     *
+     * Modules are processed sequentially, waiting for each to complete before
+     * starting the next. Use this when order matters or when operations must
+     * not overlap.
+     *
+     * @param processor - Async function to apply to each matching module
+     * @returns Promise that resolves to an array of results in processing order
+     */
     processModulesAsyncSerial<R>(processor: (item: T) => Promise<R>): Promise<R[]>;
+    /**
+     * Filters all modules to those that have the target method.
+     *
+     * @returns Array of modules that implement the target method
+     */
     filterModules(): any[];
 }
+/**
+ * Event dispatcher that calls a specific method on all modules that implement it.
+ *
+ * Dispatcher extends Processor to provide a convenient way to invoke a method
+ * on all matching modules with proper type safety. It automatically:
+ * - Finds all modules that have the target method
+ * - Calls the method with the provided parameters
+ * - Collects and returns the results
+ *
+ * Supports three dispatch modes:
+ * - **Synchronous**: Calls all modules immediately, returns array of results
+ * - **Async Parallel**: Calls all modules concurrently, returns Promise of results
+ * - **Async Serial**: Calls modules one at a time, returns Promise of results in order
+ *
+ * @template T - The interface that modules should implement
+ * @template K - The method name to dispatch
+ * @template P - Parameter types for the method (inferred from T[K])
+ * @template R - Return type for the method (inferred from T[K], unwrapped from Promise)
+ *
+ * @example
+ * ```typescript
+ * interface ConfigValidator {
+ *   validateConfig(config: any): boolean;
+ * }
+ *
+ * const dispatcher = new Dispatcher<ConfigValidator, 'validateConfig'>('validateConfig');
+ * const results = dispatcher.dispatchModule(myConfig);
+ * // results is boolean[]
+ * ```
+ */
 export declare class Dispatcher<T, K extends FunctionKeys<T>, P extends ParamResolver<T, K> = ParamResolver<T, K>, R extends ReturnTypeResolver<T, K> = ReturnTypeResolver<T, K>> extends Processor<T, K> {
+    /**
+     * Creates a new Dispatcher for a specific method.
+     *
+     * @param method - The method name to dispatch to modules
+     */
     constructor(method: K);
+    /**
+     * Dispatches the method call to all matching modules synchronously.
+     *
+     * Calls the target method on each module that implements it, passing
+     * the provided parameters. Returns an array of all return values.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Array of return values from each module
+     */
     dispatchModule(...p: P): R[];
+    /**
+     * Dispatches the method call to all matching modules asynchronously in parallel.
+     *
+     * All modules are called concurrently. Use this when modules can process
+     * independently and order doesn't matter.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Promise that resolves to an array of return values
+     */
     dispatchModuleAsync(...p: P): Promise<R[]>;
+    /**
+     * Dispatches the method call to all matching modules asynchronously in serial.
+     *
+     * Modules are called one at a time, waiting for each to complete before
+     * calling the next. Use this when order matters or operations must not overlap.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Promise that resolves to an array of return values in call order
+     */
     dispatchModuleAsyncSerial(...p: P): Promise<R[]>;
 }

package/core/dispatcher.js

@@ -15,22 +15,82 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { Logger } from './logger/Logger.js';
+import { Logger } from './logger/index.js';
+/**
+ * Base processor class that filters and processes modules based on method presence.
+ *
+ * Processor finds all modules that have a specific method and allows processing
+ * them in various ways (sync, async parallel, async serial).
+ *
+ * The `modulesResolver` must be set by ModuleManager during initialization to
+ * provide access to all registered modules.
+ *
+ * @template T - The interface/type that modules should implement
+ * @template K - The method name to look for on modules
+ *
+ * @example
+ * ```typescript
+ * interface EventHandler {
+ *   onEvent(data: string): void;
+ * }
+ *
+ * const processor = new Processor<EventHandler, 'onEvent'>('onEvent');
+ * processor.processModules(module => {
+ *   module.onEvent('data');
+ * });
+ * ```
+ */
 export class Processor extends Logger {
+    /** Function that returns all registered modules (set by ModuleManager) */
     static modulesResolver;
+    /** The method name this processor is looking for */
     method;
+    /** Filter function that checks if a module has the target method */
     filter;
+    /**
+     * Creates a new Processor for a specific method.
+     *
+     * @param method - The method name to look for on modules
+     */
     constructor(method) {
         super(method);
         this.method = method;
         this.filter = (listener) => !!listener[this.method];
     }
+    /**
+     * Processes all matching modules synchronously.
+     *
+     * Filters modules that have the target method and applies the processor
+     * function to each, collecting results in an array.
+     *
+     * @param processor - Function to apply to each matching module
+     * @returns Array of results from processing each module
+     */
     processModules(processor) {
         return this.filterModules().filter(this.filter).map(processor);
     }
+    /**
+     * Processes all matching modules asynchronously in parallel.
+     *
+     * All modules are processed concurrently using Promise.all. Use this
+     * when modules can be processed independently and order doesn't matter.
+     *
+     * @param processor - Async function to apply to each matching module
+     * @returns Promise that resolves to an array of results
+     */
     async processModulesAsync(processor) {
         return Promise.all(this.filterModules().map(processor));
     }
+    /**
+     * Processes all matching modules asynchronously in serial (one after another).
+     *
+     * Modules are processed sequentially, waiting for each to complete before
+     * starting the next. Use this when order matters or when operations must
+     * not overlap.
+     *
+     * @param processor - Async function to apply to each matching module
+     * @returns Promise that resolves to an array of results in processing order
+     */
     async processModulesAsyncSerial(processor) {
         const modules = this.filterModules();
         const toRet = [];
@@ -39,21 +99,79 @@ export class Processor extends Logger {
         }
         return toRet;
     }
+    /**
+     * Filters all modules to those that have the target method.
+     *
+     * @returns Array of modules that implement the target method
+     */
     filterModules() {
         const listeners = Dispatcher.modulesResolver();
         return listeners.filter(this.filter);
     }
 }
+/**
+ * Event dispatcher that calls a specific method on all modules that implement it.
+ *
+ * Dispatcher extends Processor to provide a convenient way to invoke a method
+ * on all matching modules with proper type safety. It automatically:
+ * - Finds all modules that have the target method
+ * - Calls the method with the provided parameters
+ * - Collects and returns the results
+ *
+ * Supports three dispatch modes:
+ * - **Synchronous**: Calls all modules immediately, returns array of results
+ * - **Async Parallel**: Calls all modules concurrently, returns Promise of results
+ * - **Async Serial**: Calls modules one at a time, returns Promise of results in order
+ *
+ * @template T - The interface that modules should implement
+ * @template K - The method name to dispatch
+ * @template P - Parameter types for the method (inferred from T[K])
+ * @template R - Return type for the method (inferred from T[K], unwrapped from Promise)
+ *
+ * @example
+ * ```typescript
+ * interface ConfigValidator {
+ *   validateConfig(config: any): boolean;
+ * }
+ *
+ * const dispatcher = new Dispatcher<ConfigValidator, 'validateConfig'>('validateConfig');
+ * const results = dispatcher.dispatchModule(myConfig);
+ * // results is boolean[]
+ * ```
+ */
 export class Dispatcher extends Processor {
+    /**
+     * Creates a new Dispatcher for a specific method.
+     *
+     * @param method - The method name to dispatch to modules
+     */
     constructor(method) {
         super(method);
     }
+    /**
+     * Dispatches the method call to all matching modules synchronously.
+     *
+     * Calls the target method on each module that implements it, passing
+     * the provided parameters. Returns an array of all return values.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Array of return values from each module
+     */
     dispatchModule(...p) {
         return this.processModules((listener) => {
             // @ts-ignore
             return (listener[this.method])(...p);
         });
     }
+    /**
+     * Dispatches the method call to all matching modules asynchronously in parallel.
+     *
+     * All modules are called concurrently. Use this when modules can process
+     * independently and order doesn't matter.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Promise that resolves to an array of return values
+     */
     async dispatchModuleAsync(...p) {
         return this.processModulesAsync((listener) => {
             // const newVar = this.resolveListenerName(listener);
@@ -66,6 +184,15 @@ export class Dispatcher extends Processor {
     // 	return 'name' in listener ? listener.name :
     // 		'constructor' in listener ? listener['constructor']['name'] : '';
     // }
+    /**
+     * Dispatches the method call to all matching modules asynchronously in serial.
+     *
+     * Modules are called one at a time, waiting for each to complete before
+     * calling the next. Use this when order matters or operations must not overlap.
+     *
+     * @param p - Parameters to pass to the method (spread arguments)
+     * @returns Promise that resolves to an array of return values in call order
+     */
     async dispatchModuleAsyncSerial(...p) {
         return this.processModulesAsyncSerial((listener) => {
             // @ts-ignore

package/core/error-handling.d.ts

@@ -1,6 +1,9 @@
 import { Module } from './module.js';
 import { Dispatcher } from './dispatcher.js';
 import { CustomException } from './exceptions/exceptions.js';
+/**
+ * Severity levels for server errors, ordered from least to most severe.
+ */
 export declare enum ServerErrorSeverity {
     Debug = "Debug",
     Info = "Info",
@@ -8,16 +11,62 @@ export declare enum ServerErrorSeverity {
     Error = "Error",
     Critical = "Critical"
 }
+/**
+ * Array of error severities in ordinal order (least to most severe).
+ * Useful for comparisons and sorting.
+ */
 export declare const ServerErrorSeverity_Ordinal: ServerErrorSeverity[];
+/**
+ * Structure for error messages that may contain nested messages.
+ */
 export type ErrorMessage = {
+    /** Primary error message */
     message: string;
+    /** Optional array of nested/inner error messages */
     innerMessages?: string[];
 };
+/**
+ * Interface for modules that handle application notifications.
+ *
+ * Modules implementing this interface will receive notifications about
+ * application-level events (errors, warnings, etc.) via the dispatcher.
+ */
 export interface OnApplicationNotification {
+    /**
+     * Processes an application notification.
+     *
+     * @param errorLevel - Severity level of the notification
+     * @param module - The module that generated the notification
+     * @param message - Error message structure
+     */
     __processApplicationNotification(errorLevel: ServerErrorSeverity, module: Module, message: ErrorMessage): Promise<void>;
 }
+/**
+ * Dispatcher for application notifications.
+ *
+ * Use this to notify all modules that implement `OnApplicationNotification`
+ * about application-level events.
+ */
 export declare const dispatch_onApplicationNotification: Dispatcher<OnApplicationNotification, "__processApplicationNotification", [errorLevel: ServerErrorSeverity, module: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>, message: ErrorMessage], void>;
+/**
+ * Interface for modules that handle application exceptions.
+ *
+ * Modules implementing this interface will receive exceptions that occur
+ * at the application level via the dispatcher.
+ */
 export interface OnApplicationException {
+    /**
+     * Processes an application exception.
+     *
+     * @param e - The exception that occurred
+     * @param module - The module where the exception occurred
+     */
     __processApplicationException(e: CustomException, module: Module): Promise<void>;
 }
+/**
+ * Dispatcher for application exceptions.
+ *
+ * Use this to notify all modules that implement `OnApplicationException`
+ * about exceptions that occur at the application level.
+ */
 export declare const dispatch_onApplicationException: Dispatcher<OnApplicationException, "__processApplicationException", [e: CustomException, module: Module<any, any, import("../index.js").Validator<any> | import("../index.js").TypeValidator<any>>], void>;

package/core/error-handling.js

@@ -16,6 +16,9 @@
  * limitations under the License.
  */
 import { Dispatcher } from './dispatcher.js';
+/**
+ * Severity levels for server errors, ordered from least to most severe.
+ */
 export var ServerErrorSeverity;
 (function (ServerErrorSeverity) {
     ServerErrorSeverity["Debug"] = "Debug";
@@ -24,6 +27,10 @@ export var ServerErrorSeverity;
     ServerErrorSeverity["Error"] = "Error";
     ServerErrorSeverity["Critical"] = "Critical";
 })(ServerErrorSeverity || (ServerErrorSeverity = {}));
+/**
+ * Array of error severities in ordinal order (least to most severe).
+ * Useful for comparisons and sorting.
+ */
 export const ServerErrorSeverity_Ordinal = [
     ServerErrorSeverity.Debug,
     ServerErrorSeverity.Info,
@@ -31,5 +38,17 @@ export const ServerErrorSeverity_Ordinal = [
     ServerErrorSeverity.Error,
     ServerErrorSeverity.Critical
 ];
+/**
+ * Dispatcher for application notifications.
+ *
+ * Use this to notify all modules that implement `OnApplicationNotification`
+ * about application-level events.
+ */
 export const dispatch_onApplicationNotification = new Dispatcher('__processApplicationNotification');
+/**
+ * Dispatcher for application exceptions.
+ *
+ * Use this to notify all modules that implement `OnApplicationException`
+ * about exceptions that occur at the application level.
+ */
 export const dispatch_onApplicationException = new Dispatcher('__processApplicationException');