@zudojs/core 0.1.0 → 1.1.0

package/dist/lifecycle/manager/lifecycleManager.manager.js

@@ -1,20 +1,29 @@
 import { hasDestroyHook, hasInitializeHook, hasStartHook, hasStopHook, } from "../core/lifecycleHook.hook.js";
-import { Lifecycle, LifecycleState, } from "../core/lifecycle.js";
+import { Lifecycle, } from "../core/lifecycle.js";
 /**
  * Coordinates lifecycle hooks and lifecycle participants.
  * Primary API for application-level lifecycle management.
+ *
+ * Every component, whether it uses the hook interfaces (onInitialize,
+ * onStart, onStop, onDestroy) or the participant API (initialize,
+ * start, stop, dispose), is normalized into a single participant and
+ * driven by one Lifecycle state machine. This guarantees:
+ *
+ * - global registration order across both component kinds
+ *   (initialize/start forward, stop/destroy reverse),
+ * - a component exposing both shapes runs exactly once per phase
+ *   (the `onX` hook takes precedence),
+ * - state guards, retries, and concurrency rules of Lifecycle.
  */
 export class LifecycleManager {
     lifecycle;
     components = [];
     logger;
-    continueOnShutdownError;
     constructor(options = {}) {
         this.logger = options.logger;
-        this.continueOnShutdownError = options.continueOnShutdownError ?? true;
         this.lifecycle = new Lifecycle({
             logger: this.logger,
-            continueOnShutdownError: this.continueOnShutdownError,
+            continueOnShutdownError: options.continueOnShutdownError ?? true,
         });
     }
     getState() {
@@ -23,119 +32,71 @@ export class LifecycleManager {
     getComponents() {
         return [...this.components];
     }
+    /**
+     * Registers a component. Only allowed before initialization begins.
+     */
     register(component) {
+        this.lifecycle.register(this.toParticipant(component));
         this.components.push(component);
-        if (this.isLifecycleParticipant(component))
-            this.lifecycle.register(component);
     }
     async initialize() {
-        if (this.getState() !== LifecycleState.CREATED)
-            return;
         this.logger?.debug("Lifecycle manager initialization started");
-        try {
-            for (const component of this.components) {
-                if (hasInitializeHook(component))
-                    await this.runHook(component, "onInitialize", "initialize");
-            }
-            await this.lifecycle.initialize();
-            this.logger?.debug("Lifecycle manager initialization completed");
-        }
-        catch (error) {
-            this.logger?.error("Lifecycle manager initialization failed", error);
-            throw error;
-        }
+        await this.lifecycle.initialize();
+        this.logger?.debug("Lifecycle manager initialization completed");
     }
     async start() {
-        if (this.getState() === LifecycleState.CREATED)
-            await this.initialize();
         this.logger?.debug("Lifecycle manager startup started");
-        try {
-            for (const component of this.components) {
-                if (hasStartHook(component))
-                    await this.runHook(component, "onStart", "start");
-            }
-            await this.lifecycle.start();
-            this.logger?.debug("Lifecycle manager startup completed");
-        }
-        catch (error) {
-            this.logger?.error("Lifecycle manager startup failed", error);
-            throw error;
-        }
+        await this.lifecycle.start();
+        this.logger?.debug("Lifecycle manager startup completed");
     }
     async stop() {
-        const errors = [];
         this.logger?.debug("Lifecycle manager shutdown started");
-        for (let i = this.components.length - 1; i >= 0; i--) {
-            const component = this.components[i];
-            if (!hasStopHook(component))
-                continue;
-            try {
-                await this.runHook(component, "onStop", "stop");
-            }
-            catch (error) {
-                errors.push(error);
-                if (!this.continueOnShutdownError)
-                    break;
-            }
-        }
-        try {
-            await this.lifecycle.stop();
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, "Lifecycle shutdown completed with errors.");
+        await this.lifecycle.stop();
         this.logger?.debug("Lifecycle manager shutdown completed");
     }
     async destroy() {
-        const errors = [];
         this.logger?.debug("Lifecycle manager destruction started");
-        for (let i = this.components.length - 1; i >= 0; i--) {
-            const component = this.components[i];
-            if (!hasDestroyHook(component))
-                continue;
-            try {
-                await this.runHook(component, "onDestroy", "destroy");
-            }
-            catch (error) {
-                errors.push(error);
-                if (!this.continueOnShutdownError)
-                    break;
-            }
-        }
-        try {
-            await this.lifecycle.dispose();
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, "Lifecycle destruction completed with errors.");
+        await this.lifecycle.dispose();
         this.logger?.debug("Lifecycle manager destruction completed");
     }
     async shutdown() {
-        const errors = [];
-        try {
-            await this.stop();
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        try {
-            await this.destroy();
-        }
-        catch (error) {
-            errors.push(error);
-        }
-        if (errors.length > 0)
-            throw new AggregateError(errors, "Application shutdown completed with errors.");
+        await this.lifecycle.shutdown();
     }
-    async runHook(component, hook, label) {
-        this.logger?.debug(`Running lifecycle ${label} hook`, {
-            component: this.getComponentName(component),
-        });
-        await component[hook]?.();
+    /**
+     * Normalizes a component into a LifecycleParticipant. Hook methods
+     * (onInitialize, ...) win over participant methods (initialize, ...)
+     * when a component exposes both, so each phase runs once.
+     */
+    toParticipant(component) {
+        const name = this.getComponentName(component);
+        const participant = this.isLifecycleParticipant(component)
+            ? component
+            : undefined;
+        const initialize = hasInitializeHook(component)
+            ? () => this.runHook(name, "initialize", () => component.onInitialize())
+            : participant?.initialize
+                ? () => this.runHook(name, "initialize", () => participant.initialize())
+                : undefined;
+        const start = hasStartHook(component)
+            ? () => this.runHook(name, "start", () => component.onStart())
+            : participant?.start
+                ? () => this.runHook(name, "start", () => participant.start())
+                : undefined;
+        const stop = hasStopHook(component)
+            ? () => this.runHook(name, "stop", () => component.onStop())
+            : participant?.stop
+                ? () => this.runHook(name, "stop", () => participant.stop())
+                : undefined;
+        const dispose = hasDestroyHook(component)
+            ? () => this.runHook(name, "destroy", () => component.onDestroy())
+            : participant?.dispose
+                ? () => this.runHook(name, "destroy", () => participant.dispose())
+                : undefined;
+        return { name, initialize, start, stop, dispose };
+    }
+    async runHook(component, label, hook) {
+        this.logger?.debug(`Running lifecycle ${label} hook`, { component });
+        await hook();
     }
     isLifecycleParticipant(component) {
         return (typeof component === "object" &&
@@ -149,7 +110,9 @@ export class LifecycleManager {
         if (typeof component === "object" &&
             component !== null &&
             "constructor" in component &&
-            typeof component.constructor === "function")
+            typeof component.constructor === "function" &&
+            component.constructor.name &&
+            component.constructor !== Object)
             return component.constructor.name;
         return "anonymous";
     }

package/dist/lifecycle/scope/lifecycleScope.scope.d.ts

@@ -9,6 +9,7 @@ export declare const LifecycleScopeState: {
     readonly RUNNING: "running";
     readonly STOPPING: "stopping";
     readonly STOPPED: "stopped";
+    readonly DESTROYED: "destroyed";
     readonly FAILED: "failed";
 };
 export type LifecycleScopeState = (typeof LifecycleScopeState)[keyof typeof LifecycleScopeState];
@@ -22,11 +23,15 @@ export interface LifecycleScopeOptions {
 /**
  * Represents an independently managed lifecycle boundary.
  * Can represent an Application, Module, Plugin, Worker, Service, or Feature.
+ *
+ * Children are initialized/started after the parent's own components
+ * and stopped/destroyed before them. A destroyed child detaches from
+ * its parent so it is never re-destroyed.
  */
 export declare class LifecycleScope {
     private state;
     private readonly name;
-    private readonly parent?;
+    private parent?;
     private readonly logger?;
     private readonly continueOnShutdownError;
     private readonly registry;
@@ -41,9 +46,25 @@ export declare class LifecycleScope {
     unregister(id: string): boolean;
     initialize(): Promise<void>;
     start(): Promise<void>;
+    /**
+     * Stops children (reverse order) and then this scope's components
+     * (reverse registration order).
+     *
+     * A scope that never started transitions straight to STOPPED without
+     * running any stop hook. When `continueOnShutdownError` is false the
+     * first failure aborts the phase and leaves the scope FAILED.
+     */
     stop(): Promise<void>;
+    /**
+     * Destroys children (reverse order) and then this scope's
+     * components. Idempotent: a destroyed scope is detached from its
+     * parent and never destroyed again.
+     */
     destroy(): Promise<void>;
     shutdown(): Promise<void>;
     private addChild;
+    private removeChild;
+    private detach;
+    private invalidState;
 }
 //# sourceMappingURL=lifecycleScope.scope.d.ts.map

package/dist/lifecycle/scope/lifecycleScope.scope.js

@@ -1,4 +1,5 @@
 import { LifecycleRegistry } from "../core/lifecycleRegistry.registry.js";
+import { InvalidStateError } from "../../errors/exceptions.js";
 /** Lifecycle scope state. */
 export const LifecycleScopeState = {
     CREATED: "created",
@@ -8,11 +9,16 @@ export const LifecycleScopeState = {
     RUNNING: "running",
     STOPPING: "stopping",
     STOPPED: "stopped",
+    DESTROYED: "destroyed",
     FAILED: "failed",
 };
 /**
  * Represents an independently managed lifecycle boundary.
  * Can represent an Application, Module, Plugin, Worker, Service, or Feature.
+ *
+ * Children are initialized/started after the parent's own components
+ * and stopped/destroyed before them. A destroyed child detaches from
+ * its parent so it is never re-destroyed.
  */
 export class LifecycleScope {
     state = LifecycleScopeState.CREATED;
@@ -48,7 +54,7 @@ export class LifecycleScope {
     register(component, name) {
         if (this.state !== LifecycleScopeState.CREATED &&
             this.state !== LifecycleScopeState.INITIALIZED) {
-            throw new Error(`Cannot register component in lifecycle scope "${this.name}" while state is "${this.state}".`);
+            throw new InvalidStateError(`Cannot register component in lifecycle scope "${this.name}" while state is "${this.state}".`, { scope: this.name, state: this.state });
         }
         return this.registry.register(component, name);
     }
@@ -60,7 +66,7 @@ export class LifecycleScope {
             this.state === LifecycleScopeState.RUNNING)
             return;
         if (this.state !== LifecycleScopeState.CREATED)
-            throw new Error(`Cannot initialize lifecycle scope "${this.name}" while state is "${this.state}".`);
+            throw this.invalidState("initialize");
         this.state = LifecycleScopeState.INITIALIZING;
         this.logger?.debug("Initializing lifecycle scope", { scope: this.name });
         try {
@@ -75,7 +81,7 @@ export class LifecycleScope {
                     await component.initialize();
                 }
             }
-            for (const child of this.children)
+            for (const child of [...this.children])
                 await child.initialize();
             this.state = LifecycleScopeState.INITIALIZED;
             this.logger?.debug("Lifecycle scope initialized", { scope: this.name });
@@ -94,7 +100,7 @@ export class LifecycleScope {
         if (this.state === LifecycleScopeState.CREATED)
             await this.initialize();
         if (this.state !== LifecycleScopeState.INITIALIZED)
-            throw new Error(`Cannot start lifecycle scope "${this.name}" while state is "${this.state}".`);
+            throw this.invalidState("start");
         this.state = LifecycleScopeState.STARTING;
         this.logger?.debug("Starting lifecycle scope", { scope: this.name });
         try {
@@ -108,7 +114,7 @@ export class LifecycleScope {
                     await component.start();
                 }
             }
-            for (const child of this.children)
+            for (const child of [...this.children])
                 await child.start();
             this.state = LifecycleScopeState.RUNNING;
             this.logger?.debug("Lifecycle scope started", { scope: this.name });
@@ -121,15 +127,36 @@ export class LifecycleScope {
             throw error;
         }
     }
+    /**
+     * Stops children (reverse order) and then this scope's components
+     * (reverse registration order).
+     *
+     * A scope that never started transitions straight to STOPPED without
+     * running any stop hook. When `continueOnShutdownError` is false the
+     * first failure aborts the phase and leaves the scope FAILED.
+     */
     async stop() {
-        if (this.state === LifecycleScopeState.STOPPED)
-            return;
-        if (this.state !== LifecycleScopeState.RUNNING &&
-            this.state !== LifecycleScopeState.FAILED) {
-            throw new Error(`Cannot stop lifecycle scope "${this.name}" while state is "${this.state}".`);
+        switch (this.state) {
+            case LifecycleScopeState.STOPPED:
+            case LifecycleScopeState.DESTROYED:
+                return;
+            case LifecycleScopeState.CREATED:
+            case LifecycleScopeState.INITIALIZED:
+                // Nothing started here; cascade the state to children only.
+                for (let i = this.children.length - 1; i >= 0; i--) {
+                    await this.children[i].stop();
+                }
+                this.state = LifecycleScopeState.STOPPED;
+                return;
+            case LifecycleScopeState.RUNNING:
+            case LifecycleScopeState.FAILED:
+                break;
+            default:
+                throw this.invalidState("stop");
         }
         this.state = LifecycleScopeState.STOPPING;
         const errors = [];
+        let aborted = false;
         this.logger?.debug("Stopping lifecycle scope", { scope: this.name });
         for (let i = this.children.length - 1; i >= 0; i--) {
             try {
@@ -137,11 +164,13 @@ export class LifecycleScope {
             }
             catch (error) {
                 errors.push(error);
-                if (!this.continueOnShutdownError)
+                if (!this.continueOnShutdownError) {
+                    aborted = true;
                     break;
+                }
             }
         }
-        if (errors.length === 0 || this.continueOnShutdownError) {
+        if (!aborted) {
             for (const registration of this.registry.getReverse()) {
                 const component = registration.component;
                 try {
@@ -159,17 +188,33 @@ export class LifecycleScope {
                         scope: this.name,
                         component: registration.name,
                     });
-                    if (!this.continueOnShutdownError)
+                    if (!this.continueOnShutdownError) {
+                        aborted = true;
                         break;
+                    }
                 }
             }
         }
-        this.state = LifecycleScopeState.STOPPED;
+        this.state = aborted
+            ? LifecycleScopeState.FAILED
+            : LifecycleScopeState.STOPPED;
         if (errors.length > 0)
             throw new AggregateError(errors, `Lifecycle scope "${this.name}" stopped with errors.`);
     }
+    /**
+     * Destroys children (reverse order) and then this scope's
+     * components. Idempotent: a destroyed scope is detached from its
+     * parent and never destroyed again.
+     */
     async destroy() {
+        if (this.state === LifecycleScopeState.DESTROYED)
+            return;
+        if (this.state === LifecycleScopeState.INITIALIZING ||
+            this.state === LifecycleScopeState.STARTING ||
+            this.state === LifecycleScopeState.STOPPING)
+            throw this.invalidState("destroy");
         const errors = [];
+        let aborted = false;
         this.logger?.debug("Destroying lifecycle scope", { scope: this.name });
         for (let i = this.children.length - 1; i >= 0; i--) {
             try {
@@ -177,11 +222,13 @@ export class LifecycleScope {
             }
             catch (error) {
                 errors.push(error);
-                if (!this.continueOnShutdownError)
+                if (!this.continueOnShutdownError) {
+                    aborted = true;
                     break;
+                }
             }
         }
-        if (errors.length === 0 || this.continueOnShutdownError) {
+        if (!aborted) {
             for (const registration of this.registry.getReverse()) {
                 const component = registration.component;
                 try {
@@ -200,11 +247,20 @@ export class LifecycleScope {
                         scope: this.name,
                         component: registration.name,
                     });
-                    if (!this.continueOnShutdownError)
+                    if (!this.continueOnShutdownError) {
+                        aborted = true;
                         break;
+                    }
                 }
             }
         }
+        if (aborted) {
+            this.state = LifecycleScopeState.FAILED;
+        }
+        else {
+            this.state = LifecycleScopeState.DESTROYED;
+            this.detach();
+        }
         if (errors.length > 0)
             throw new AggregateError(errors, `Lifecycle scope "${this.name}" destroyed with errors.`);
     }
@@ -230,5 +286,17 @@ export class LifecycleScope {
             return;
         this.children.push(child);
     }
+    removeChild(child) {
+        const index = this.children.indexOf(child);
+        if (index !== -1)
+            this.children.splice(index, 1);
+    }
+    detach() {
+        this.parent?.removeChild(this);
+        this.parent = undefined;
+    }
+    invalidState(operation) {
+        return new InvalidStateError(`Cannot ${operation} lifecycle scope "${this.name}" while state is "${this.state}".`, { scope: this.name, operation, state: this.state });
+    }
 }
 //# sourceMappingURL=lifecycleScope.scope.js.map

package/dist/logging/console/consoleLogger.logger.d.ts

@@ -20,15 +20,34 @@ export declare class ConsoleLogger extends BaseLogger {
     constructor(options?: LoggerOptions, context?: LoggerContext);
     /**
      * Writes a log entry to the console.
+     *
+     * The context received here has already been merged with the
+     * logger's persistent context by BaseLogger. Fields of the
+     * current execution context (when a ContextStorage is configured
+     * and a context is active) are merged beneath it.
      */
     protected write(level: LogLevelType, message: string, context?: LogContext, error?: unknown): void;
     /**
      * Creates a child logger that inherits the current
-     * logger configuration and adds persistent context.
+     * logger configuration.
+     *
+     * The context received here is the fully merged context
+     * (parent persistent context plus child additions) produced
+     * by BaseLogger.child().
      */
     protected createChild(context: LogContext): ConsoleLogger;
+    /**
+     * Merges the ambient execution context (if any) beneath the
+     * supplied context. Never throws: a failing storage lookup leaves
+     * the context untouched.
+     */
+    private withExecutionContext;
     /**
      * Writes the log entry as JSON.
+     *
+     * Serialization is crash-safe: circular references, BigInt
+     * values, and throwing toJSON implementations degrade to
+     * placeholder strings instead of throwing.
      */
     private writeStructured;
     /**

package/dist/logging/console/consoleLogger.logger.js

@@ -1,5 +1,7 @@
-import { LogLevel, LogLevelPriority, shouldLog, } from "../core/logLevel.level.js";
-import { serializeLogError } from "../core/logEntry.entry.js";
+import { LogLevel, LogLevelPriority, isLogLevel, shouldLog, } from "../core/logLevel.level.js";
+import { InvalidArgumentError } from "../../errors/exceptions.js";
+import { safeLogStringify, sanitizeLogValue, serializeLogError, } from "../core/logEntry.entry.js";
+import { loggerContextFromExecution } from "../core/loggerContext.context.js";
 import { DEFAULT_LOGGER_OPTIONS, } from "../core/loggerOptions.options.js";
 import { BaseLogger } from "../core/logger.js";
 /**
@@ -22,26 +24,45 @@ export class ConsoleLogger extends BaseLogger {
             ...options.context,
             ...context,
         });
+        const level = options.level ?? DEFAULT_LOGGER_OPTIONS.level;
+        /*
+         * An unknown level would make every severity comparison false
+         * and silently disable all logging, so it is rejected at
+         * construction instead. Levels are case-sensitive.
+         */
+        if (!isLogLevel(level)) {
+            throw new InvalidArgumentError(`Unknown log level "${String(level)}". Expected one of: ${Object.keys(LogLevelPriority).join(", ")}.`, { level });
+        }
         this.options = {
             ...DEFAULT_LOGGER_OPTIONS,
             ...options,
+            level,
         };
     }
     /**
      * Writes a log entry to the console.
+     *
+     * The context received here has already been merged with the
+     * logger's persistent context by BaseLogger. Fields of the
+     * current execution context (when a ContextStorage is configured
+     * and a context is active) are merged beneath it.
      */
     write(level, message, context, error) {
         if (!shouldLog(level, this.options.level)) {
             return;
         }
+        const redact = this.options.redact;
+        context = this.withExecutionContext(context);
         const entry = {
             level,
             message,
             timestamp: new Date(),
-            context,
+            context: context !== undefined && redact !== undefined
+                ? redact(sanitizeLogValue(context))
+                : context,
             ...(error !== undefined
                 ? {
-                    error: serializeLogError(error),
+                    error: serializeLogError(error, { redact }),
                 }
                 : {}),
         };
@@ -53,21 +74,61 @@ export class ConsoleLogger extends BaseLogger {
     }
     /**
      * Creates a child logger that inherits the current
-     * logger configuration and adds persistent context.
+     * logger configuration.
+     *
+     * The context received here is the fully merged context
+     * (parent persistent context plus child additions) produced
+     * by BaseLogger.child().
      */
     createChild(context) {
-        return new ConsoleLogger(this.options, {
-            ...this.options.context,
+        return new ConsoleLogger({
+            ...this.options,
+            context: undefined,
+        }, context);
+    }
+    /**
+     * Merges the ambient execution context (if any) beneath the
+     * supplied context. Never throws: a failing storage lookup leaves
+     * the context untouched.
+     */
+    withExecutionContext(context) {
+        const storage = this.options.contextStorage;
+        if (!storage)
+            return context;
+        let execution;
+        try {
+            execution = storage.get();
+        }
+        catch {
+            return context;
+        }
+        if (!execution)
+            return context;
+        return {
+            ...loggerContextFromExecution(execution),
             ...context,
-        });
+        };
     }
     /**
      * Writes the log entry as JSON.
+     *
+     * Serialization is crash-safe: circular references, BigInt
+     * values, and throwing toJSON implementations degrade to
+     * placeholder strings instead of throwing.
      */
     writeStructured(entry) {
         const output = {
             level: entry.level,
             message: entry.message,
+            ...(this.options.service !== undefined
+                ? { service: this.options.service }
+                : {}),
+            ...(this.options.version !== undefined
+                ? { version: this.options.version }
+                : {}),
+            ...(this.options.environment !== undefined
+                ? { environment: this.options.environment }
+                : {}),
             ...(this.options.timestamps
                 ? {
                     timestamp: entry.timestamp.toISOString(),
@@ -86,7 +147,7 @@ export class ConsoleLogger extends BaseLogger {
                 }
                 : {}),
         };
-        this.writeToConsole(entry.level, JSON.stringify(output));
+        this.writeToConsole(entry.level, safeLogStringify(output));
     }
     /**
      * Writes a human-readable log entry.
@@ -108,7 +169,12 @@ export class ConsoleLogger extends BaseLogger {
     writeToConsole(level, message) {
         switch (level) {
             case LogLevel.TRACE:
-                console.trace(message);
+                /*
+                 * console.trace prints a stack trace for every call,
+                 * which makes trace-level logs unreadable. Trace output
+                 * goes through console.debug (console.log fallback).
+                 */
+                (console.debug ?? console.log)(message);
                 break;
             case LogLevel.DEBUG:
                 console.debug(message);
@@ -170,7 +236,7 @@ export class ConsoleLogger extends BaseLogger {
             return value;
         }
         try {
-            return JSON.stringify(value);
+            return JSON.stringify(sanitizeLogValue(value));
         }
         catch {
             return "[unserializable]";