@zudojs/core 1.2.3 → 1.3.0

package/dist/logging/core/logLevel.level.js

@@ -55,4 +55,3 @@ export function shouldLog(level, minimumLevel) {
     const minimumPriority = LogLevelPriority[minimumLevel] ?? LogLevelPriority[DEFAULT_LOG_LEVEL];
     return levelPriority >= minimumPriority;
 }
-//# sourceMappingURL=logLevel.level.js.map

package/dist/logging/core/logRedaction.redaction.d.ts

@@ -35,4 +35,3 @@ export interface LogRedactorOptions {
  * redacted, "tokenizer" is not.
  */
 export declare function createLogRedactor(options?: LogRedactorOptions): LogRedactionHook;
-//# sourceMappingURL=logRedaction.redaction.d.ts.map

package/dist/logging/core/logRedaction.redaction.js

@@ -16,4 +16,3 @@ export function createLogRedactor(options = {}) {
     });
     return (value) => redactor.redactObject(sanitizeLogValue(value));
 }
-//# sourceMappingURL=logRedaction.redaction.js.map

package/dist/logging/core/logger.d.ts

@@ -29,10 +29,16 @@ export interface Logger {
     warn(message: string, context?: LogContext): void;
     /**
      * Logs an error.
+     *
+     * Argument order differs from `@zudojs/logger`, whose signature is
+     * `error(message, metadata)`. Both conventions work here: a plain
+     * object in the second position with no third argument is treated
+     * as context, not as the error. To log a plain object AS the error,
+     * pass a third argument (`{}` will do).
      */
     error(message: string, error?: unknown, context?: LogContext): void;
     /**
-     * Logs a fatal error.
+     * Logs a fatal error. Accepts the same two conventions as `error`.
      */
     fatal(message: string, error?: unknown, context?: LogContext): void;
     /**
@@ -80,4 +86,3 @@ export declare abstract class BaseLogger implements Logger {
      */
     protected abstract createChild(context: LogContext): Logger;
 }
-//# sourceMappingURL=logger.d.ts.map

package/dist/logging/core/logger.js

@@ -49,10 +49,12 @@ export class BaseLogger {
         this.write("warn", message, this.mergeCallContext(context));
     }
     error(message, error, context) {
-        this.write("error", message, this.mergeCallContext(context), error);
+        const [thrown, callContext] = splitErrorArguments(error, context);
+        this.write("error", message, this.mergeCallContext(callContext), thrown);
     }
     fatal(message, error, context) {
-        this.write("fatal", message, this.mergeCallContext(context), error);
+        const [thrown, callContext] = splitErrorArguments(error, context);
+        this.write("fatal", message, this.mergeCallContext(callContext), thrown);
     }
     child(context) {
         return this.createChild({
@@ -61,4 +63,21 @@ export class BaseLogger {
         });
     }
 }
-//# sourceMappingURL=logger.js.map
+/**
+ * Resolves the two `error()`/`fatal()` calling conventions: with no
+ * third argument, a plain object (not an Error, not a class instance)
+ * in the error position is the `@zudojs/logger`-style metadata.
+ */
+function splitErrorArguments(error, context) {
+    if (context === undefined && isPlainContext(error)) {
+        return [undefined, error];
+    }
+    return [error, context];
+}
+function isPlainContext(value) {
+    if (typeof value !== "object" || value === null || value instanceof Error) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}

package/dist/logging/core/loggerContext.context.d.ts

@@ -71,4 +71,3 @@ export declare function loggerContextFromExecution(context: ExecutionContext): L
  * with additional values.
  */
 export declare function createLoggerContext(base?: LoggerContext, additional?: LoggerContext): LoggerContext;
-//# sourceMappingURL=loggerContext.context.d.ts.map

package/dist/logging/core/loggerContext.context.js

@@ -35,4 +35,3 @@ export function createLoggerContext(base = {}, additional = {}) {
             : {}),
     };
 }
-//# sourceMappingURL=loggerContext.context.js.map

package/dist/logging/core/loggerOptions.options.d.ts

@@ -60,9 +60,13 @@ export interface LoggerOptions {
      * Redaction hook applied to structured log data (entry context
      * and error details) before it is written.
      *
-     * See createLogRedactor for a key-based implementation.
+     * Defaults to `createLogRedactor()`, which replaces values under
+     * sensitive-looking keys (`password`, `secret`, `token`, `apiKey`,
+     * `authorization`, ...) with `"[REDACTED]"`. Logging such keys in
+     * clear used to be the default. Pass `false` to disable redaction,
+     * or your own hook to replace it.
      */
-    readonly redact?: LogRedactionHook;
+    readonly redact?: LogRedactionHook | false;
     /**
      * ContextStorage consulted on every write. When an execution
      * context is active, its `executionId`, `correlationId`,
@@ -83,4 +87,3 @@ export type LogLevelOption = "trace" | "debug" | "info" | "warn" | "error" | "fa
  * Default logging configuration.
  */
 export declare const DEFAULT_LOGGER_OPTIONS: Required<Pick<LoggerOptions, "level" | "timestamps" | "structured" | "includeStackTrace">>;
-//# sourceMappingURL=loggerOptions.options.d.ts.map

package/dist/logging/core/loggerOptions.options.js

@@ -7,4 +7,3 @@ export const DEFAULT_LOGGER_OPTIONS = {
     structured: true,
     includeStackTrace: true,
 };
-//# sourceMappingURL=loggerOptions.options.js.map

package/dist/logging/index.d.ts

@@ -5,4 +5,3 @@
  */
 export * from "./core/index.js";
 export * from "./console/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/logging/index.js

@@ -5,4 +5,3 @@
  */
 export * from "./core/index.js";
 export * from "./console/index.js";
-//# sourceMappingURL=index.js.map

package/dist/modules/index.d.ts

@@ -16,4 +16,3 @@ export * from "./moduleRegistry/index.js";
 export * from "./moduleLoader/index.js";
 export * from "./moduleLifecycle/index.js";
 export * from "./moduleError/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/modules/index.js

@@ -43,4 +43,3 @@ export * from "./moduleLifecycle/index.js";
  * Module errors
  */
 export * from "./moduleError/index.js";
-//# sourceMappingURL=index.js.map

package/dist/modules/module.d.ts

@@ -174,4 +174,3 @@ export declare function isModule(value: unknown): value is Module;
  * Useful for modules that do not require a class.
  */
 export declare function createModule(definition: Module): Module;
-//# sourceMappingURL=module.d.ts.map

package/dist/modules/module.js

@@ -96,4 +96,3 @@ export function isModule(value) {
 export function createModule(definition) {
     return definition;
 }
-//# sourceMappingURL=module.js.map

package/dist/modules/moduleContext.context.d.ts

@@ -201,4 +201,3 @@ export declare function createModuleContext(options: CreateModuleContextOptions)
  * Type guard for ModuleContext.
  */
 export declare function isModuleContext(value: unknown): value is ModuleContext;
-//# sourceMappingURL=moduleContext.context.d.ts.map

package/dist/modules/moduleContext.context.js

@@ -102,4 +102,3 @@ export function isModuleContext(value) {
         typeof context.getConfig === "function" &&
         typeof context.requireConfig === "function");
 }
-//# sourceMappingURL=moduleContext.context.js.map

package/dist/modules/moduleDefinition.definition.d.ts

@@ -113,4 +113,3 @@ export declare function normalizeDependencies(dependencies?: readonly (ModuleId
  * Checks whether a value is a valid module definition.
  */
 export declare function isModuleDefinition(value: unknown): value is ModuleDefinition;
-//# sourceMappingURL=moduleDefinition.definition.d.ts.map

package/dist/modules/moduleDefinition.definition.js

@@ -131,4 +131,3 @@ function validateModuleDefinition(definition) {
         dependencyIds.add(id);
     }
 }
-//# sourceMappingURL=moduleDefinition.definition.js.map

package/dist/modules/moduleDependency/index.d.ts

@@ -7,4 +7,3 @@
 export { type ModuleDependency, type ModuleDependencies, type ModuleDependencyNode, type ModuleDependencyGraph, type ModuleDependencyInput, type ModuleDependencyNodeInput, } from "./moduleDependency.type.js";
 export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, satisfiesModuleVersionConstraint, } from "./moduleDependency.graph.js";
 export { findModuleDependencyCycle, hasModuleDependencyCycle, resolveModuleStartupOrder, resolveModuleShutdownOrder, } from "./moduleDependency.ordering.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleDependency/index.js

@@ -7,4 +7,3 @@
 export {} from "./moduleDependency.type.js";
 export { normalizeModuleDependency, normalizeModuleDependencies, validateModuleDependencies, validateModuleDependencyGraph, createModuleDependencyGraph, createModuleDependency, isOptionalModuleDependency, hasModuleVersionConstraint, satisfiesModuleVersionConstraint, } from "./moduleDependency.graph.js";
 export { findModuleDependencyCycle, hasModuleDependencyCycle, resolveModuleStartupOrder, resolveModuleShutdownOrder, } from "./moduleDependency.ordering.js";
-//# sourceMappingURL=index.js.map

package/dist/modules/moduleDependency/moduleDependency.graph.d.ts

@@ -57,4 +57,3 @@ export declare function hasModuleVersionConstraint(dependency: ModuleDependency)
  * the dependency module declares no version at all.
  */
 export declare function satisfiesModuleVersionConstraint(constraint: string, version: string | undefined): boolean;
-//# sourceMappingURL=moduleDependency.graph.d.ts.map

package/dist/modules/moduleDependency/moduleDependency.graph.js

@@ -286,4 +286,3 @@ export function satisfiesModuleVersionConstraint(constraint, version) {
             return false;
     }
 }
-//# sourceMappingURL=moduleDependency.graph.js.map

package/dist/modules/moduleDependency/moduleDependency.ordering.d.ts

@@ -43,4 +43,3 @@ export declare function resolveModuleStartupOrder(graph: ModuleDependencyGraph):
  * are stopped before the modules they depend on.
  */
 export declare function resolveModuleShutdownOrder(graph: ModuleDependencyGraph): readonly ModuleId[];
-//# sourceMappingURL=moduleDependency.ordering.d.ts.map

package/dist/modules/moduleDependency/moduleDependency.ordering.js

@@ -137,4 +137,3 @@ export function resolveModuleStartupOrder(graph) {
 export function resolveModuleShutdownOrder(graph) {
     return Object.freeze([...resolveModuleStartupOrder(graph)].reverse());
 }
-//# sourceMappingURL=moduleDependency.ordering.js.map

package/dist/modules/moduleDependency/moduleDependency.type.d.ts

@@ -90,4 +90,3 @@ export interface ModuleDependencyNodeInput {
      */
     readonly version?: string;
 }
-//# sourceMappingURL=moduleDependency.type.d.ts.map

package/dist/modules/moduleDependency/moduleDependency.type.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=moduleDependency.type.js.map

package/dist/modules/moduleError/index.d.ts

@@ -8,4 +8,3 @@ export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError
 export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleError/index.js

@@ -8,4 +8,3 @@ export { InvalidModuleDefinitionError, ModuleNotFoundError, DuplicateModuleError
 export { InvalidModuleDependencyError, MissingModuleDependencyError, CircularModuleDependencyError, ModuleVersionMismatchError, } from "./moduleError.dependency.js";
 export { getLifecycleErrorCode, ModuleInstantiationError, ModuleOperationError, InvalidModuleInstanceError, InvalidModuleStateError, ModuleOperationInProgressError, } from "./moduleError.lifecycle.js";
 export { isModuleError, hasModuleErrorCode, toModuleError, } from "./moduleError.helpers.js";
-//# sourceMappingURL=index.js.map

package/dist/modules/moduleError/moduleError.base.d.ts

@@ -116,4 +116,3 @@ export declare class ModuleError extends FrameworkError {
         errorMetadata: Readonly<Record<string, unknown>> | undefined;
     };
 }
-//# sourceMappingURL=moduleError.base.d.ts.map

package/dist/modules/moduleError/moduleError.base.js

@@ -102,4 +102,3 @@ export class ModuleError extends FrameworkError {
         };
     }
 }
-//# sourceMappingURL=moduleError.base.js.map

package/dist/modules/moduleError/moduleError.dependency.d.ts

@@ -1,10 +1,27 @@
 import type { ModuleId } from "../module.js";
+import type { ModuleRegistrationState } from "../moduleRegistry/moduleRegistry.type.js";
 import { ModuleError } from "./moduleError.base.js";
 /**
- * Error thrown when a required module dependency is missing.
+ * What is known about the dependency that could not be resolved.
+ */
+export interface MissingModuleDependencyContext {
+    /**
+     * Registration state of the dependency when it IS registered but did
+     * not take part in the lifecycle run (not loaded). Omitted when the
+     * dependency is not registered at all.
+     */
+    readonly dependencyState?: ModuleRegistrationState;
+}
+/**
+ * Error thrown when a required module dependency cannot be resolved.
+ *
+ * The message distinguishes a dependency that is not registered from
+ * one that is registered but was not loaded; the latter used to be
+ * reported as "missing module", which was misleading.
  */
 export declare class MissingModuleDependencyError extends ModuleError {
-    constructor(moduleId: ModuleId, dependencyId: ModuleId);
+    readonly dependencyState?: ModuleRegistrationState;
+    constructor(moduleId: ModuleId, dependencyId: ModuleId, context?: MissingModuleDependencyContext);
 }
 /**
  * Error thrown when a circular dependency is detected.
@@ -53,4 +70,3 @@ export declare class ModuleVersionMismatchError extends ModuleError {
         actualVersion: string | undefined;
     };
 }
-//# sourceMappingURL=moduleError.dependency.d.ts.map

package/dist/modules/moduleError/moduleError.dependency.js

@@ -1,15 +1,28 @@
 import { ModuleErrorCode, ModuleError } from "./moduleError.base.js";
+function describeMissingDependency(moduleId, dependencyId, dependencyState) {
+    if (dependencyState === undefined) {
+        return `Module "${moduleId}" requires missing module "${dependencyId}".`;
+    }
+    return (`Module "${moduleId}" depends on "${dependencyId}", which is registered but not loaded ` +
+        `(state: "${dependencyState}"). Load it before starting the lifecycle, or enable autoLoad on its definition.`);
+}
 /**
- * Error thrown when a required module dependency is missing.
+ * Error thrown when a required module dependency cannot be resolved.
+ *
+ * The message distinguishes a dependency that is not registered from
+ * one that is registered but was not loaded; the latter used to be
+ * reported as "missing module", which was misleading.
  */
 export class MissingModuleDependencyError extends ModuleError {
-    constructor(moduleId, dependencyId) {
-        super(`Module "${moduleId}" requires missing module "${dependencyId}".`, {
+    dependencyState;
+    constructor(moduleId, dependencyId, context = {}) {
+        super(describeMissingDependency(moduleId, dependencyId, context.dependencyState), {
             code: ModuleErrorCode.MISSING_DEPENDENCY,
             moduleId,
             dependencyId,
         });
         this.name = "MissingModuleDependencyError";
+        this.dependencyState = context.dependencyState;
     }
 }
 /**
@@ -67,4 +80,3 @@ export class ModuleVersionMismatchError extends ModuleError {
         };
     }
 }
-//# sourceMappingURL=moduleError.dependency.js.map

package/dist/modules/moduleError/moduleError.helpers.d.ts

@@ -19,4 +19,3 @@ export declare function toModuleError(error: unknown, options?: {
     readonly code?: ModuleErrorCode;
     readonly phase?: string;
 }): ModuleError;
-//# sourceMappingURL=moduleError.helpers.d.ts.map

package/dist/modules/moduleError/moduleError.helpers.js

@@ -29,4 +29,3 @@ export function toModuleError(error, options = {}) {
         cause: error,
     });
 }
-//# sourceMappingURL=moduleError.helpers.js.map

package/dist/modules/moduleError/moduleError.lifecycle.d.ts

@@ -58,4 +58,3 @@ export declare class InvalidModuleStateError extends ModuleError {
 export declare class ModuleOperationInProgressError extends ModuleError {
     constructor(operation: string);
 }
-//# sourceMappingURL=moduleError.lifecycle.d.ts.map

package/dist/modules/moduleError/moduleError.lifecycle.js

@@ -104,4 +104,3 @@ export class ModuleOperationInProgressError extends ModuleError {
         this.name = "ModuleOperationInProgressError";
     }
 }
-//# sourceMappingURL=moduleError.lifecycle.js.map

package/dist/modules/moduleError/moduleError.registration.d.ts

@@ -18,4 +18,3 @@ export declare class ModuleNotFoundError extends ModuleError {
 export declare class DuplicateModuleError extends ModuleError {
     constructor(moduleId: ModuleId);
 }
-//# sourceMappingURL=moduleError.registration.d.ts.map

package/dist/modules/moduleError/moduleError.registration.js

@@ -36,4 +36,3 @@ export class DuplicateModuleError extends ModuleError {
         this.name = "DuplicateModuleError";
     }
 }
-//# sourceMappingURL=moduleError.registration.js.map

package/dist/modules/moduleLifecycle/index.d.ts

@@ -10,4 +10,3 @@
  */
 export { type ModuleLifecyclePhase, type ModuleLifecycleState, type ModuleLifecycleHookName, type ModuleLifecycleStep, type ModuleLifecycleHooks, type ModuleLifecycleOptions, type ModuleLifecyclePhaseOptions, ModuleLifecycleError, type ModuleLifecycleResult, type ModuleLifecycleSkip, } from "./moduleLifecycle.type.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/modules/moduleLifecycle/index.js

@@ -10,4 +10,3 @@
  */
 export { ModuleLifecycleError, } from "./moduleLifecycle.type.js";
 export { ModuleLifecycleManager, createModuleLifecycleManager, } from "./moduleLifecycle.lifecycle.js";
-//# sourceMappingURL=index.js.map

package/dist/modules/moduleLifecycle/moduleLifecycle.exclusive.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Serialises module lifecycle operations, detaching one that was
+ * cancelled so teardown never queues behind a hook that may never settle.
+ */
+/**
+ * A single-lane lock for lifecycle phases.
+ *
+ * Phases must not overlap, so each operation waits for the previous
+ * one — except an operation whose `signal` has been aborted. That is a
+ * bootstrap the startup timeout already gave up on, possibly stuck in a
+ * hook that never settles; `stop()`/`destroy()` used to wait behind it
+ * for the whole shutdown timeout (30 s by default) after `start()` had
+ * long since rejected. Such an operation keeps running detached: it
+ * starts no further hook (the phase loop checks the signal), the
+ * module it is stuck in stays in its active phase, which teardown
+ * skips, and when it finally settles `onDetachedSettled` runs so a
+ * module that came up late can still be torn down.
+ */
+export declare class ExclusiveOperations {
+    private current;
+    /**
+     * Runs `operation` once no other (live) operation is running.
+     */
+    run<T>(operation: () => Promise<T>, signal?: AbortSignal, onDetachedSettled?: () => void): Promise<T>;
+}

package/dist/modules/moduleLifecycle/moduleLifecycle.exclusive.js

@@ -0,0 +1,63 @@
+/**
+ * Serialises module lifecycle operations, detaching one that was
+ * cancelled so teardown never queues behind a hook that may never settle.
+ */
+/**
+ * Resolves when `work` settles or `signal` aborts, whichever is first.
+ */
+function untilSettledOrAborted(work, signal) {
+    if (signal === undefined || signal.aborted)
+        return work;
+    return new Promise((resolve) => {
+        const done = () => {
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        signal.addEventListener("abort", done, { once: true });
+        void work.then(done, done);
+    });
+}
+/**
+ * A single-lane lock for lifecycle phases.
+ *
+ * Phases must not overlap, so each operation waits for the previous
+ * one — except an operation whose `signal` has been aborted. That is a
+ * bootstrap the startup timeout already gave up on, possibly stuck in a
+ * hook that never settles; `stop()`/`destroy()` used to wait behind it
+ * for the whole shutdown timeout (30 s by default) after `start()` had
+ * long since rejected. Such an operation keeps running detached: it
+ * starts no further hook (the phase loop checks the signal), the
+ * module it is stuck in stays in its active phase, which teardown
+ * skips, and when it finally settles `onDetachedSettled` runs so a
+ * module that came up late can still be torn down.
+ */
+export class ExclusiveOperations {
+    current;
+    /**
+     * Runs `operation` once no other (live) operation is running.
+     */
+    async run(operation, signal, onDetachedSettled) {
+        while (this.current !== undefined && !this.current.signal?.aborted) {
+            await untilSettledOrAborted(this.current.done, this.current.signal);
+        }
+        let release = () => undefined;
+        const held = {
+            done: new Promise((resolve) => {
+                release = resolve;
+            }),
+            signal,
+        };
+        this.current = held;
+        try {
+            return await operation();
+        }
+        finally {
+            const detached = this.current !== held;
+            if (!detached)
+                this.current = undefined;
+            release();
+            if (detached)
+                onDetachedSettled?.();
+        }
+    }
+}

package/dist/modules/moduleLifecycle/moduleLifecycle.lifecycle.d.ts

@@ -14,7 +14,8 @@ export declare class ModuleLifecycleManager {
     private readonly options;
     private readonly contextStorage;
     private readonly states;
-    private operation;
+    private readonly exclusive;
+    private tornDown;
     constructor(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions);
     initialize(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
     start(options?: ModuleLifecyclePhaseOptions): Promise<ModuleLifecycleResult>;
@@ -88,9 +89,27 @@ export declare class ModuleLifecycleManager {
      * as edges so the ordering reports them as missing.
      */
     private createGraph;
+    /**
+     * Startup order over the loaded modules. A dependency that is
+     * registered but not loaded used to be reported as a "missing
+     * module", which sent people looking for a typo; it is now described
+     * by its registration state.
+     */
     private getStartupOrder;
     private getShutdownOrder;
+    /**
+     * Serialises operations. One whose `signal` was aborted (a bootstrap
+     * abandoned by the startup timeout) is not waited for, so `stop()`
+     * and `destroy()` no longer queue behind a hook that may never
+     * settle; a module whose hook does settle later is torn down then.
+     */
     private runExclusive;
+    /**
+     * Best-effort teardown for modules an abandoned startup brought up
+     * after the runtime had already been shut down. Failures land on the
+     * module's lifecycle state as they would for any stop/destroy.
+     */
+    private finalizeLateModules;
 }
 /**
  * Resolves the dependencies of a registration: definition-declared
@@ -101,4 +120,3 @@ export declare class ModuleLifecycleManager {
 export declare function resolveRegistrationDependencies(registry: ModuleRegistry, registration: ModuleRegistration): readonly ModuleDependency[];
 /** Creates a module lifecycle manager. */
 export declare function createModuleLifecycleManager(registry: ModuleRegistry, loader: ModuleLoader, options?: ModuleLifecycleOptions): ModuleLifecycleManager;
-//# sourceMappingURL=moduleLifecycle.lifecycle.d.ts.map