@digital-alchemy/core 26.2.17 → 26.5.1

package/dist/helpers/events.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"events.mjs","sourceRoot":"","sources":["../../src/helpers/events.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAElC,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAAmC,CAAC;AACrF,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAAmC,CAAC;AACrF,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,OAAgB,EAAE,EAAE,CAChE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,iCAAiC,OAAO,EAAE,CAAC"}
+{"version":3,"file":"events.mjs","sourceRoot":"","sources":["../../src/helpers/events.mts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAElC;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAAmC,CAAC;AAErF;;GAEG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,mCAAmC,CAAC;AAErF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,OAAgB,EAAE,EAAE,CAChE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,iCAAiC,OAAO,EAAE,CAAC"}

package/dist/helpers/extend.d.mts

@@ -1,4 +1,54 @@
+/**
+ * Deep object merging and cloning utilities — recursive extend and array clone
+ * functions that preserve Date and RegExp instances.
+ *
+ * @remarks
+ * These utilities support the configuration system by enabling deep merging of
+ * config objects from multiple sources while preserving special value types.
+ * `deepExtend` mutates the target in place and returns it; `deepCloneArray`
+ * creates a new array with recursively cloned items.
+ */
+/**
+ * Clone a Date or RegExp instance.
+ *
+ * @remarks
+ * Creates a new Date or RegExp with the same value as the input. Throws
+ * TypeError if the input is neither a Date nor a RegExp.
+ *
+ * @throws {TypeError} when the value is not a Date or RegExp.
+ *
+ * @internal
+ */
 export declare function cloneSpecificValue(value: unknown): RegExp | Date;
+/**
+ * Recursively clone an array, preserving nested objects, arrays, Dates, and RegExps.
+ *
+ * @remarks
+ * Walks the array and clones each item: arrays are cloned recursively, Dates and
+ * RegExps are cloned using `cloneSpecificValue`, plain objects are merged with
+ * an empty target using `deepExtend`, and primitives are returned as-is.
+ */
 export declare function deepCloneArray<TYPE = unknown>(array: Array<TYPE>): Array<TYPE>;
+/**
+ * Safely read a property from an object, blocking access to `__proto__`.
+ *
+ * @remarks
+ * Returns `undefined` if the key is `__proto__`, otherwise returns the value at
+ * `object[key]`. This prevents prototype pollution vulnerabilities during deep
+ * merges.
+ *
+ * @internal
+ */
 export declare function safeGetProperty(object: unknown, key: string): unknown;
+/**
+ * Merge all own properties from `object` into `target`, recursively.
+ *
+ * @remarks
+ * Mutates `target` in place and returns the merged result. Primitive values
+ * overwrite target properties outright. Arrays from `object` are cloned into
+ * the target. Objects are recursively merged if both target and source values
+ * are plain objects; otherwise, a new deep clone is created. Dates and RegExps
+ * are cloned. Circular references (where `value === target`) are skipped to
+ * prevent infinite recursion.
+ */
 export declare function deepExtend<A, B>(target: A, object: B): A & B;

package/dist/helpers/extend.mjs

@@ -1,7 +1,33 @@
+/**
+ * Deep object merging and cloning utilities — recursive extend and array clone
+ * functions that preserve Date and RegExp instances.
+ *
+ * @remarks
+ * These utilities support the configuration system by enabling deep merging of
+ * config objects from multiple sources while preserving special value types.
+ * `deepExtend` mutates the target in place and returns it; `deepCloneArray`
+ * creates a new array with recursively cloned items.
+ */
 import { is } from "../index.mjs";
+/**
+ * Check whether a value is a Date or RegExp instance.
+ *
+ * @internal
+ */
 function isSpecificValue(value) {
     return value instanceof Date || value instanceof RegExp;
 }
+/**
+ * Clone a Date or RegExp instance.
+ *
+ * @remarks
+ * Creates a new Date or RegExp with the same value as the input. Throws
+ * TypeError if the input is neither a Date nor a RegExp.
+ *
+ * @throws {TypeError} when the value is not a Date or RegExp.
+ *
+ * @internal
+ */
 export function cloneSpecificValue(value) {
     if (value instanceof Date) {
         return new Date(value.getTime());
@@ -11,6 +37,14 @@ export function cloneSpecificValue(value) {
     }
     throw new TypeError("Unexpected situation");
 }
+/**
+ * Recursively clone an array, preserving nested objects, arrays, Dates, and RegExps.
+ *
+ * @remarks
+ * Walks the array and clones each item: arrays are cloned recursively, Dates and
+ * RegExps are cloned using `cloneSpecificValue`, plain objects are merged with
+ * an empty target using `deepExtend`, and primitives are returned as-is.
+ */
 export function deepCloneArray(array) {
     // eslint-disable-next-line sonarjs/function-return-type
     return array.map(item => {
@@ -26,35 +60,64 @@ export function deepCloneArray(array) {
         return item;
     });
 }
+/**
+ * Safely read a property from an object, blocking access to `__proto__`.
+ *
+ * @remarks
+ * Returns `undefined` if the key is `__proto__`, otherwise returns the value at
+ * `object[key]`. This prevents prototype pollution vulnerabilities during deep
+ * merges.
+ *
+ * @internal
+ */
 export function safeGetProperty(object, key) {
+    // guard against prototype pollution
     return key === "__proto__" ? undefined : object[key];
 }
+/**
+ * Merge all own properties from `object` into `target`, recursively.
+ *
+ * @remarks
+ * Mutates `target` in place and returns the merged result. Primitive values
+ * overwrite target properties outright. Arrays from `object` are cloned into
+ * the target. Objects are recursively merged if both target and source values
+ * are plain objects; otherwise, a new deep clone is created. Dates and RegExps
+ * are cloned. Circular references (where `value === target`) are skipped to
+ * prevent infinite recursion.
+ */
 export function deepExtend(target, object) {
+    // early exit if not merging an object
     if (!is.object(object)) {
         return target;
     }
     Object.keys(object).forEach(key => {
         const source = safeGetProperty(target, key);
         const value = safeGetProperty(object, key);
+        // skip circular references
         if (value === target) {
             return;
         }
+        // scalars and nulls overwrite directly
         if (typeof value !== "object" || value === null) {
             target[key] = value;
             return;
         }
+        // arrays are cloned into the target
         if (is.array(value)) {
             target[key] = deepCloneArray(value);
             return;
         }
+        // special values (Date, RegExp) are cloned
         if (isSpecificValue(value)) {
             target[key] = cloneSpecificValue(value);
             return;
         }
+        // if source is not an object or is an array, create a new clone of value
         if (typeof source !== "object" || source === null || is.array(source)) {
             target[key] = deepExtend({}, value);
             return;
         }
+        // both are plain objects — recurse
         target[key] = deepExtend(source, value);
     });
     return target;

package/dist/helpers/extend.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"extend.mjs","sourceRoot":"","sources":["../../src/helpers/extend.mts"],"names":[],"mappings":"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"}
+{"version":3,"file":"extend.mjs","sourceRoot":"","sources":["../../src/helpers/extend.mts"],"names":[],"mappings":"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"}

package/dist/helpers/index.d.mts

@@ -1,3 +1,12 @@
+/**
+ * Public helpers — pure-function modules and type definitions.
+ *
+ * @remarks
+ * This module re-exports all helper modules (async utilities, config loaders,
+ * lifecycle types, logging interfaces, cron schedules, etc.). Helpers are
+ * side-effect-free and differ from services in that they do not receive
+ * `TServiceParams` or participate in the DI graph.
+ */
 export * from "./async.mts";
 export * from "./config.mts";
 export * from "./config-environment-loader.mts";

package/dist/helpers/index.mjs

@@ -1,3 +1,12 @@
+/**
+ * Public helpers — pure-function modules and type definitions.
+ *
+ * @remarks
+ * This module re-exports all helper modules (async utilities, config loaders,
+ * lifecycle types, logging interfaces, cron schedules, etc.). Helpers are
+ * side-effect-free and differ from services in that they do not receive
+ * `TServiceParams` or participate in the DI graph.
+ */
 export * from "./async.mjs";
 export * from "./config.mjs";
 export * from "./config-environment-loader.mjs";

package/dist/helpers/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/helpers/index.mts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/helpers/index.mts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,iCAAiC,CAAC;AAChD,cAAc,0BAA0B,CAAC;AACzC,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC"}

package/dist/helpers/lifecycle.d.mts

@@ -1,54 +1,140 @@
+/**
+ * Lifecycle types and stage definitions — the ordered callback hooks that
+ * frame application startup and shutdown.
+ *
+ * @remarks
+ * Services register callbacks at specific lifecycle stages; the wiring engine
+ * executes them in strict order. Callbacks can be prioritized (positive = early,
+ * negative = late, unspecified = parallel). Each stage represents a well-defined
+ * point where certain actions are safe: `onPreInit` before config,
+ * `onPostConfig` after, `onBootstrap` after all modules are wired, `onReady`
+ * when the app is running, and three shutdown stages for graceful termination.
+ */
 import type { TBlackHole } from "./utilities.mts";
+/**
+ * Function signature for a lifecycle callback — takes no arguments, returns nothing.
+ */
 export type LifecycleCallback = () => TBlackHole;
+/**
+ * Prioritized callback — a tuple of callback function and numeric priority.
+ *
+ * @remarks
+ * Used internally by the lifecycle engine to sort callbacks before execution.
+ * Higher priorities run first; unspecified (default) callbacks run in parallel;
+ * negative priorities run last.
+ *
+ * @internal
+ */
 export type LifecyclePrioritizedCallback = [callback: LifecycleCallback, priority: number];
+/**
+ * Ordered collection of prioritized callbacks.
+ *
+ * @internal
+ */
 export type CallbackList = LifecyclePrioritizedCallback[];
+/**
+ * Function signature for registering a lifecycle callback.
+ *
+ * @remarks
+ * Services call these methods to attach callbacks at specific lifecycle stages.
+ * The optional `priority` argument controls execution order:
+ * positive = early (high to low), undefined = parallel, negative = late.
+ */
 export type TLifeCycleRegister = (callback: LifecycleCallback, priority?: number) => void;
+/**
+ * Core lifecycle interface — seven stages with callback registration methods.
+ *
+ * @remarks
+ * Each method (`onPreInit`, `onPostConfig`, etc.) accepts a callback and optional
+ * priority. Callbacks are invoked by the bootstrap engine in strict stage order,
+ * with priorities controlling execution within each stage.
+ */
 export type TLifecycleBase = {
     /**
-     * Registers a callback for the bootstrap phase, executed during the initial startup process.
+     * Registers a callback for the pre-initialization phase, executed before config is loaded.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * @remarks
+     * Safe for basic state setup; do not read config values at this stage.
+     *
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
-    onBootstrap: TLifeCycleRegister;
+    onPreInit: TLifeCycleRegister;
     /**
-     * Registers a callback for immediately after the configuration phase, allowing post-configuration adjustments.
+     * Registers a callback for the post-configuration phase, executed after config is ready.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * @remarks
+     * Safe to read and validate config values; all modules are not yet wired.
+     *
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
     onPostConfig: TLifeCycleRegister;
     /**
-     * Registers a callback for the pre-initialization phase, executed before the main initialization starts.
+     * Registers a callback for the bootstrap phase, executed when all modules are wired.
+     *
+     * @remarks
+     * Safe to call other services and set up inter-service dependencies.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
-    onPreInit: TLifeCycleRegister;
+    onBootstrap: TLifeCycleRegister;
     /**
-     * Registers a callback for when the system is fully initialized and ready.
+     * Registers a callback for the ready phase, executed when the app is fully running.
+     *
+     * @remarks
+     * Safe to start schedulers, timers, and external integrations.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
     onReady: TLifeCycleRegister;
     /**
-     * Notification that the application intends to shut down.
+     * Registers a callback for the pre-shutdown phase, notification of intended shutdown.
+     *
+     * @remarks
+     * First shutdown hook; used for graceful degradation or cleanup signaling.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
     onPreShutdown: TLifeCycleRegister;
     /**
-     * Begins the shutdown process, typically invoked when the system is about to shut down.
+     * Registers a callback for the shutdown-start phase, begins active teardown.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * @remarks
+     * Close connections, stop schedulers, and drain in-flight operations.
+     *
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
     onShutdownStart: TLifeCycleRegister;
     /**
-     * Completes the shutdown process, executed after all shutdown procedures are complete.
+     * Registers a callback for the shutdown-complete phase, final cleanup.
+     *
+     * @remarks
+     * Last-resort cleanup after all other teardown is done.
      *
-     * Optional priority arg: negative values -> no value -> positive value
+     * Priority: positive = early, undefined = parallel, negative = late.
      */
     onShutdownComplete: TLifeCycleRegister;
 };
+/**
+ * Extended lifecycle interface with child lifecycle factory.
+ *
+ * @remarks
+ * Used by scoped contexts (e.g., per-request) to create child lifecycle instances
+ * that fire callbacks within their own scope.
+ *
+ * @internal
+ */
 export type TParentLifecycle = TLifecycleBase & {
     child: () => TLifecycleBase;
 };
+/**
+ * Ordered lifecycle stages — the canonical sequence of bootstrap and shutdown phases.
+ *
+ * @remarks
+ * This array defines the execution order. Do not change the order; it is relied
+ * upon by the wiring engine to route callbacks and ensure safe state transitions.
+ */
 export declare const LIFECYCLE_STAGES: readonly ["PreInit", "PostConfig", "Bootstrap", "Ready", "PreShutdown", "ShutdownStart", "ShutdownComplete"];
+/**
+ * Union type of all lifecycle stage names.
+ */
 export type LifecycleStages = (typeof LIFECYCLE_STAGES)[number];

package/dist/helpers/lifecycle.mjs

@@ -1,4 +1,22 @@
-// ! This is a sorted array! Don't change the order
+/**
+ * Lifecycle types and stage definitions — the ordered callback hooks that
+ * frame application startup and shutdown.
+ *
+ * @remarks
+ * Services register callbacks at specific lifecycle stages; the wiring engine
+ * executes them in strict order. Callbacks can be prioritized (positive = early,
+ * negative = late, unspecified = parallel). Each stage represents a well-defined
+ * point where certain actions are safe: `onPreInit` before config,
+ * `onPostConfig` after, `onBootstrap` after all modules are wired, `onReady`
+ * when the app is running, and three shutdown stages for graceful termination.
+ */
+/**
+ * Ordered lifecycle stages — the canonical sequence of bootstrap and shutdown phases.
+ *
+ * @remarks
+ * This array defines the execution order. Do not change the order; it is relied
+ * upon by the wiring engine to route callbacks and ensure safe state transitions.
+ */
 export const LIFECYCLE_STAGES = [
     "PreInit",
     "PostConfig",

package/dist/helpers/lifecycle.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.mjs","sourceRoot":"","sources":["../../src/helpers/lifecycle.mts"],"names":[],"mappings":"AA+DA,mDAAmD;AACnD,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,YAAY;IACZ,WAAW;IACX,OAAO;IACP,aAAa;IACb,eAAe;IACf,kBAAkB;CACV,CAAC"}
+{"version":3,"file":"lifecycle.mjs","sourceRoot":"","sources":["../../src/helpers/lifecycle.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAmIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,SAAS;IACT,YAAY;IACZ,WAAW;IACX,OAAO;IACP,aAAa;IACb,eAAe;IACf,kBAAkB;CACV,CAAC"}

package/dist/helpers/logger.d.mts

@@ -1,67 +1,228 @@
+/**
+ * Logger interface and configuration — dual-arity log methods, color schemes,
+ * and a last-resort stderr writer.
+ *
+ * @remarks
+ * The logger supports six severity levels (trace, debug, info, warn, error, fatal)
+ * and dual-arity calls: `logger.info("message")` or `logger.info({ context, id }, "message")`.
+ * The logger service wraps this interface with chalk/stdout formatting, ALS
+ * integration, and LOG_LEVEL filtering. `fatalLog` is the last-resort writer for
+ * fatal conditions that cannot use the logger (e.g., during bootstrap failure).
+ */
 import type { Get } from "type-fest";
 import type { TContext } from "./context.mts";
 import type { TBlackHole } from "./utilities.mts";
+/**
+ * Extension hook for logger replacement via declaration merging.
+ *
+ * @remarks
+ * Downstream libraries can extend this interface to substitute their own logger
+ * type into `GetLogger`, allowing alternative logging implementations.
+ *
+ * @internal
+ */
 export interface ReplacementLogger {
 }
+/**
+ * Resolved logger type — either a merged replacement logger or the default `ILogger`.
+ *
+ * @remarks
+ * When `ReplacementLogger` is extended with a `logger` property, that type is
+ * used; otherwise, `ILogger` is the default.
+ */
 export type GetLogger = Get<ReplacementLogger, "logger"> extends object ? Get<ReplacementLogger, "logger"> : ILogger;
+/**
+ * Streaming log target — a function that receives formatted message and context data.
+ *
+ * @remarks
+ * Implementing libraries can add custom targets to send logs to external services
+ * (e.g., Datadog, CloudWatch) via the `logger.addTarget(...)` method.
+ */
 export type LogStreamTarget = (message: string, data: object) => TBlackHole;
+/**
+ * Logger service interface — methods to emit logs, create scoped loggers, and
+ * configure targets and output formatting.
+ *
+ * @remarks
+ * Each method operates on a base logger (which can be replaced for testing or
+ * integration) and filters based on the current LOG_LEVEL configuration.
+ * The `systemLogger` is a pre-created instance for use in bootstrap and
+ * low-level operations.
+ */
 export type DigitalAlchemyLogger = {
+    /**
+     * Register an additional log target.
+     *
+     * @remarks
+     * Targets receive all logged messages and context data after filtering.
+     * Can be a logger instance (like `ILogger`) or a stream function that writes
+     * directly to an external service.
+     */
     addTarget: (logger: GetLogger | LogStreamTarget) => void;
     /**
-     * Create a new logger instance for a given context
+     * Create a new logger instance scoped to a specific context.
+     *
+     * @remarks
+     * Returns an `ILogger` where all calls are implicitly tagged with the given context,
+     * enabling per-request log correlation and filtering.
      */
     context: (context: string | TContext) => ILogger;
     /**
-     * Retrieve a reference to the base logger used to emit from
+     * Retrieve the underlying base logger implementation.
+     *
+     * @remarks
+     * Exposed for testing and low-level integrations; most code should use the logger
+     * returned by the injection, not this method.
+     *
+     * @internal
      */
     getBaseLogger: () => Record<keyof GetLogger, (context: TContext, ...data: Parameters<TLoggerFunction>) => void>;
+    /**
+     * Check whether pretty formatting is enabled.
+     *
+     * @remarks
+     * Exposed for testing.
+     *
+     * @internal
+     */
     getPrettyFormat: () => boolean;
     /**
-     * exposed for testing
+     * Format a message string for display.
+     *
+     * @remarks
+     * Applies syntax highlighting or other transformations based on the current
+     * pretty-format setting. Exposed for testing.
+     *
+     * @internal
      */
     prettyFormatMessage: (message: string) => string;
     /**
-     * Modify the base logger
+     * Replace the base logger implementation.
      *
-     * Note: Extension still handles LOG_LEVEL logic
+     * @remarks
+     * Allows testing and framework integration by substituting a mock or wrapper logger.
+     * The service still enforces LOG_LEVEL filtering on top of the replacement.
      */
     setBaseLogger: (base: GetLogger) => GetLogger;
     /**
-     * Set the enabled/disabled state of the message pretty formatting logic
+     * Enable or disable pretty formatting of log messages.
+     *
+     * @remarks
+     * When disabled, output is minimal (no colors, no extra formatting).
+     * Returns the new state.
      */
     setPrettyFormat: (state: boolean) => boolean;
     /**
-     * Logger instance of last resort
+     * System logger instance — ready-to-use logger for bootstrap and low-level code.
+     *
+     * @remarks
+     * Pre-created for convenience in places where context is unavailable or
+     * not yet initialized.
      */
     systemLogger: GetLogger;
     /**
-     * exposed for testing
+     * Recompute log filtering based on current LOG_LEVEL config.
+     *
+     * @remarks
+     * Call after changing the LOG_LEVEL configuration to update filter state.
+     * Exposed for testing.
+     *
+     * @internal
      */
     updateShouldLog: () => void;
 };
+/**
+ * Dual-arity logger function signature — message-only or object+message forms.
+ *
+ * @remarks
+ * Enables flexible calling styles:
+ * - `logger.info("message")`
+ * - `logger.info({data}, "message")`
+ * The logger extracts `name` from objects for call-site identification.
+ */
 export type TLoggerFunction = ((message: string, ...arguments_: unknown[]) => void) | ((object: object, message?: string, ...arguments_: unknown[]) => void);
+/**
+ * Logger interface — six severity levels with dual-arity overloads.
+ *
+ * @remarks
+ * Each level (`trace`, `debug`, `info`, `warn`, `error`, `fatal`) accepts either
+ * a message string or an object with metadata plus an optional message. The
+ * object form typically includes a `name` field (function reference) for
+ * call-site identification.
+ */
 export interface ILogger {
+    /**
+     * Log at TRACE level — lowest severity, highest volume; decision points, entry/exit.
+     */
+    trace(...arguments_: Parameters<TLoggerFunction>): void;
+    trace(message: string, ...arguments_: unknown[]): void;
+    trace(object: object, message?: string, ...arguments_: unknown[]): void;
+    /**
+     * Log at DEBUG level — low severity; detailed operation flow.
+     */
     debug(...arguments_: Parameters<TLoggerFunction>): void;
     debug(message: string, ...arguments_: unknown[]): void;
     debug(object: object, message?: string, ...arguments_: unknown[]): void;
-    error(...arguments_: Parameters<TLoggerFunction>): void;
-    error(message: string, ...arguments_: unknown[]): void;
-    error(object: object, message?: string, ...arguments_: unknown[]): void;
-    fatal(...arguments_: Parameters<TLoggerFunction>): void;
-    fatal(message: string, ...arguments_: unknown[]): void;
-    fatal(object: object, message?: string, ...arguments_: unknown[]): void;
+    /**
+     * Log at INFO level — notable events; startup, shutdown, config changes.
+     */
     info(...arguments_: Parameters<TLoggerFunction>): void;
     info(message: string, ...arguments_: unknown[]): void;
     info(object: object, message?: string, ...arguments_: unknown[]): void;
-    trace(...arguments_: Parameters<TLoggerFunction>): void;
-    trace(message: string, ...arguments_: unknown[]): void;
-    trace(object: object, message?: string, ...arguments_: unknown[]): void;
+    /**
+     * Log at WARN level — unexpected but non-fatal; potential issues worth investigating.
+     */
     warn(...arguments_: Parameters<TLoggerFunction>): void;
     warn(message: string, ...arguments_: unknown[]): void;
     warn(object: object, message?: string, ...arguments_: unknown[]): void;
+    /**
+     * Log at ERROR level — error conditions; failed operations, exceptions.
+     */
+    error(...arguments_: Parameters<TLoggerFunction>): void;
+    error(message: string, ...arguments_: unknown[]): void;
+    error(object: object, message?: string, ...arguments_: unknown[]): void;
+    /**
+     * Log at FATAL level — unrecoverable errors; application must shut down.
+     */
+    fatal(...arguments_: Parameters<TLoggerFunction>): void;
+    fatal(message: string, ...arguments_: unknown[]): void;
+    fatal(object: object, message?: string, ...arguments_: unknown[]): void;
 }
+/**
+ * Configuration value type — log level or the special "silent" value.
+ */
 export type TConfigLogLevel = keyof ILogger | "silent";
+/**
+ * Mapping from log level to console color for pretty-printed output.
+ */
 export declare const METHOD_COLORS: Map<keyof ILogger, CONTEXT_COLORS>;
+/**
+ * Supported console color names for log output.
+ */
 export type CONTEXT_COLORS = "grey" | "blue" | "yellow" | "red" | "green" | "magenta";
+/**
+ * Event name for log level configuration updates.
+ *
+ * @internal
+ */
 export declare const EVENT_UPDATE_LOG_LEVELS = "EVENT_UPDATE_LOG_LEVELS";
+/**
+ * Last-resort logger for fatal conditions that cannot use the normal logger.
+ *
+ * @remarks
+ * Writes directly to `stderr` bypassing the logger service. Use only when the
+ * logger is not available (e.g., during bootstrap failure before services are
+ * wired). If `data` is an Error, extracts and formats `name`, `cause`, `message`,
+ * and stack trace; otherwise, JSON-stringifies it. Always adds a trailing newline.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await bootstrap();
+ * } catch (error) {
+ *   fatalLog("bootstrap failed", error);
+ *   process.exit(1);
+ * }
+ * ```
+ */
 export declare function fatalLog(message: string, data?: unknown): void;