@zudojs/core 0.0.1 → 1.0.0

package/dist/lifecycle/core/lifecycle.js

@@ -1,3 +1,4 @@
+import { InvalidStateError } from "../../errors/exceptions.js";
 /** Lifecycle states supported by the Zudojs application runtime. */
 export const LifecycleState = {
     CREATED: "created",
@@ -9,12 +10,32 @@ export const LifecycleState = {
     STOPPED: "stopped",
     FAILED: "failed",
 };
-/** Coordinates initialization, startup, shutdown, and disposal of application resources. */
+/**
+ * Coordinates initialization, startup, shutdown, and disposal of
+ * application resources.
+ *
+ * State machine:
+ *
+ *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
+ *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
+ *   any phase failure → FAILED; initialize()/start() retry from FAILED
+ *   resume with the participant that failed; stop() from FAILED unwinds
+ *   whatever started.
+ *
+ * Concurrent callers of the same phase share the in-flight promise.
+ */
 export class Lifecycle {
     state = LifecycleState.CREATED;
     participants = [];
     logger;
     continueOnShutdownError;
+    initializedCount = 0;
+    startedCount = 0;
+    disposed = false;
+    failedPhase;
+    initializePromise;
+    startPromise;
+    stopPromise;
     constructor(options = {}) {
         this.logger = options.logger;
         this.continueOnShutdownError = options.continueOnShutdownError ?? true;
@@ -25,11 +46,20 @@ export class Lifecycle {
     getParticipants() {
         return [...this.participants];
     }
+    /**
+     * Whether dispose() has run. A disposed lifecycle cannot be
+     * restarted.
+     */
+    isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Registers a participant. Only allowed before initialization
+     * begins so every participant goes through every phase.
+     */
     register(participant) {
-        if (this.state !== LifecycleState.CREATED &&
-            this.state !== LifecycleState.INITIALIZING &&
-            this.state !== LifecycleState.INITIALIZED) {
-            throw new Error(`Cannot register lifecycle participant "${participant.name}" while application is "${this.state}".`);
+        if (this.state !== LifecycleState.CREATED) {
+            throw new InvalidStateError(`Cannot register lifecycle participant "${participant.name}" while application is "${this.state}".`, { participant: participant.name, state: this.state });
         }
         this.participants.push(participant);
         this.logger?.debug("Lifecycle participant registered", {
@@ -37,101 +67,132 @@ export class Lifecycle {
         });
     }
     async initialize() {
-        if (this.state === LifecycleState.INITIALIZED)
-            return;
-        if (this.state === LifecycleState.INITIALIZING)
-            return this.waitForInitialization();
-        if (this.state !== LifecycleState.CREATED)
-            throw new Error(`Cannot initialize application while state is "${this.state}".`);
-        this.state = LifecycleState.INITIALIZING;
-        this.logger?.debug("Application initialization started");
+        switch (this.state) {
+            case LifecycleState.INITIALIZED:
+            case LifecycleState.STARTING:
+            case LifecycleState.RUNNING:
+                return;
+            case LifecycleState.INITIALIZING:
+                return this.initializePromise;
+            case LifecycleState.FAILED:
+                if (this.failedPhase !== "initialize") {
+                    if (this.failedPhase === "start")
+                        return;
+                    throw this.invalidState("initialize");
+                }
+                break;
+            case LifecycleState.STOPPED:
+                // A lifecycle stopped after a failed initialization resumes
+                // the pending participants; a fully initialized one is done.
+                if (this.disposed)
+                    throw this.invalidState("initialize");
+                if (this.initializedCount >= this.participants.length)
+                    return;
+                break;
+            case LifecycleState.CREATED:
+                break;
+            default:
+                throw this.invalidState("initialize");
+        }
+        this.initializePromise = this.runInitialize();
         try {
-            for (const participant of this.participants) {
-                this.logger?.debug("Initializing lifecycle participant", {
-                    participant: participant.name,
-                });
-                await participant.initialize?.();
-            }
-            this.state = LifecycleState.INITIALIZED;
-            this.logger?.info("Application initialization completed");
+            await this.initializePromise;
         }
-        catch (error) {
-            this.state = LifecycleState.FAILED;
-            this.logger?.error("Application initialization failed", error);
-            throw error;
+        finally {
+            this.initializePromise = undefined;
         }
     }
     async start() {
-        if (this.state === LifecycleState.RUNNING ||
-            this.state === LifecycleState.STARTING)
-            return;
-        if (this.state === LifecycleState.CREATED)
-            await this.initialize();
-        if (this.state === LifecycleState.INITIALIZING)
-            await this.waitForInitialization();
-        if (this.state !== LifecycleState.INITIALIZED)
-            throw new Error(`Cannot start application while state is "${this.state}".`);
-        this.state = LifecycleState.STARTING;
-        this.logger?.debug("Application startup started");
+        switch (this.state) {
+            case LifecycleState.RUNNING:
+                return;
+            case LifecycleState.STARTING:
+                return this.startPromise;
+            case LifecycleState.INITIALIZING:
+                await this.initializePromise;
+                return this.start();
+            case LifecycleState.CREATED:
+                await this.initialize();
+                return this.start();
+            case LifecycleState.FAILED:
+                if (this.failedPhase === "initialize") {
+                    await this.initialize();
+                    return this.start();
+                }
+                if (this.failedPhase !== "start") {
+                    throw this.invalidState("start");
+                }
+                break;
+            case LifecycleState.STOPPED:
+                if (this.disposed)
+                    throw this.invalidState("start");
+                if (this.initializedCount < this.participants.length) {
+                    await this.initialize();
+                    return this.start();
+                }
+                break;
+            case LifecycleState.INITIALIZED:
+                break;
+            default:
+                throw this.invalidState("start");
+        }
+        this.startPromise = this.runStart();
         try {
-            for (const participant of this.participants) {
-                this.logger?.debug("Starting lifecycle participant", {
-                    participant: participant.name,
-                });
-                await participant.start?.();
-            }
-            this.state = LifecycleState.RUNNING;
-            this.logger?.info("Application startup completed");
+            await this.startPromise;
         }
-        catch (error) {
-            this.state = LifecycleState.FAILED;
-            this.logger?.error("Application startup failed", error);
-            throw error;
+        finally {
+            this.startPromise = undefined;
         }
     }
-    async waitForInitialization() {
-        for (let attempt = 0; attempt < 100; attempt++) {
-            if (this.state === LifecycleState.INITIALIZED ||
-                this.state === LifecycleState.FAILED)
+    async stop() {
+        switch (this.state) {
+            case LifecycleState.STOPPED:
                 return;
-            if (this.state !== LifecycleState.INITIALIZING)
+            case LifecycleState.STOPPING:
+                return this.stopPromise;
+            case LifecycleState.INITIALIZING:
+                await this.initializePromise?.catch(() => undefined);
+                return this.stop();
+            case LifecycleState.STARTING:
+                await this.startPromise?.catch(() => undefined);
+                return this.stop();
+            case LifecycleState.CREATED:
+            case LifecycleState.INITIALIZED:
+                // Nothing has started; no stop hooks to run.
+                this.state = LifecycleState.STOPPED;
                 return;
-            await new Promise((resolve) => setTimeout(resolve, 10));
+            case LifecycleState.FAILED:
+                if (this.failedPhase === "dispose")
+                    throw this.invalidState("stop");
+                break;
+            case LifecycleState.RUNNING:
+                break;
+            default:
+                throw this.invalidState("stop");
         }
-        throw new Error(`Timed out waiting for initialization to complete. Current state: "${this.state}".`);
-    }
-    async stop() {
-        if (this.state === LifecycleState.STOPPED)
-            return;
-        if (this.state !== LifecycleState.RUNNING &&
-            this.state !== LifecycleState.FAILED)
-            throw new Error(`Cannot stop application while state is "${this.state}".`);
-        this.state = LifecycleState.STOPPING;
-        this.logger?.debug("Application shutdown started");
-        const errors = [];
-        for (let i = this.participants.length - 1; i >= 0; i--) {
-            const participant = this.participants[i];
-            try {
-                this.logger?.debug("Stopping lifecycle participant", {
-                    participant: participant.name,
-                });
-                await participant.stop?.();
-            }
-            catch (error) {
-                errors.push(error);
-                this.logger?.error("Failed to stop lifecycle participant", error, {
-                    participant: participant.name,
-                });
-                if (!this.continueOnShutdownError)
-                    break;
-            }
+        this.stopPromise = this.runStop();
+        try {
+            await this.stopPromise;
+        }
+        finally {
+            this.stopPromise = undefined;
         }
-        this.state = LifecycleState.STOPPED;
-        this.logger?.info("Application shutdown completed");
-        if (errors.length > 0)
-            throw new AggregateError(errors, "One or more lifecycle participants failed to stop.");
     }
+    /**
+     * Disposes every participant in reverse registration order.
+     *
+     * Idempotent. Participants that are still running are not stopped
+     * first; use shutdown() for stop-then-dispose.
+     */
     async dispose() {
+        if (this.disposed)
+            return;
+        if (this.state === LifecycleState.STOPPING ||
+            this.state === LifecycleState.STARTING ||
+            this.state === LifecycleState.INITIALIZING) {
+            throw this.invalidState("dispose");
+        }
+        this.disposed = true;
         const errors = [];
         for (let i = this.participants.length - 1; i >= 0; i--) {
             const participant = this.participants[i];
@@ -150,6 +211,15 @@ export class Lifecycle {
                     break;
             }
         }
+        this.initializedCount = 0;
+        this.startedCount = 0;
+        if (errors.length > 0 && !this.continueOnShutdownError) {
+            this.state = LifecycleState.FAILED;
+            this.failedPhase = "dispose";
+        }
+        else if (this.state !== LifecycleState.FAILED) {
+            this.state = LifecycleState.STOPPED;
+        }
         if (errors.length > 0)
             throw new AggregateError(errors, "One or more lifecycle participants failed to dispose.");
     }
@@ -175,5 +245,101 @@ export class Lifecycle {
         if (disposeError)
             throw disposeError;
     }
+    async runInitialize() {
+        this.state = LifecycleState.INITIALIZING;
+        this.failedPhase = undefined;
+        this.logger?.debug("Application initialization started");
+        try {
+            for (let i = this.initializedCount; i < this.participants.length; i++) {
+                const participant = this.participants[i];
+                this.logger?.debug("Initializing lifecycle participant", {
+                    participant: participant.name,
+                });
+                await participant.initialize?.();
+                this.initializedCount = i + 1;
+            }
+            this.state = LifecycleState.INITIALIZED;
+            this.logger?.info("Application initialization completed");
+        }
+        catch (error) {
+            this.state = LifecycleState.FAILED;
+            this.failedPhase = "initialize";
+            this.logger?.error("Application initialization failed", error);
+            throw error;
+        }
+    }
+    async runStart() {
+        this.state = LifecycleState.STARTING;
+        this.failedPhase = undefined;
+        this.logger?.debug("Application startup started");
+        try {
+            for (let i = this.startedCount; i < this.participants.length; i++) {
+                const participant = this.participants[i];
+                this.logger?.debug("Starting lifecycle participant", {
+                    participant: participant.name,
+                });
+                await participant.start?.();
+                this.startedCount = i + 1;
+            }
+            this.state = LifecycleState.RUNNING;
+            this.logger?.info("Application startup completed");
+        }
+        catch (error) {
+            this.state = LifecycleState.FAILED;
+            this.failedPhase = "start";
+            this.logger?.error("Application startup failed", error);
+            throw error;
+        }
+    }
+    async runStop() {
+        this.state = LifecycleState.STOPPING;
+        this.failedPhase = undefined;
+        this.logger?.debug("Application shutdown started");
+        const errors = [];
+        let aborted = false;
+        // Only participants whose start() completed are stopped.
+        for (let i = this.startedCount - 1; i >= 0; i--) {
+            const participant = this.participants[i];
+            try {
+                this.logger?.debug("Stopping lifecycle participant", {
+                    participant: participant.name,
+                });
+                await participant.stop?.();
+                this.startedCount = i;
+            }
+            catch (error) {
+                errors.push(error);
+                this.logger?.error("Failed to stop lifecycle participant", error, {
+                    participant: participant.name,
+                });
+                if (!this.continueOnShutdownError) {
+                    aborted = true;
+                    break;
+                }
+                this.startedCount = i;
+            }
+        }
+        if (aborted) {
+            this.state = LifecycleState.FAILED;
+            this.failedPhase = "stop";
+        }
+        else {
+            this.startedCount = 0;
+            this.state = LifecycleState.STOPPED;
+            this.logger?.info("Application shutdown completed");
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, "One or more lifecycle participants failed to stop.");
+    }
+    invalidState(operation) {
+        const label = operation === "initialize"
+            ? "initialize"
+            : operation === "start"
+                ? "start"
+                : operation === "stop"
+                    ? "stop"
+                    : "dispose";
+        return new InvalidStateError(`Cannot ${label} application while state is "${this.state}".`, { operation, state: this.state });
+    }
 }
 //# sourceMappingURL=lifecycle.js.map

package/dist/lifecycle/core/lifecycleRegistry.registry.d.ts

@@ -50,6 +50,10 @@ export declare class LifecycleRegistry {
      *
      * Components are executed in reverse registration order
      * during stopping and destruction.
+     *
+     * Names are unique within a registry: an explicit duplicate name is
+     * rejected, while derived names (constructor names) are made unique
+     * with a numeric suffix so getByName() is unambiguous.
      */
     register(component: LifecycleComponent, name?: string): LifecycleRegistration;
     /**
@@ -84,6 +88,10 @@ export declare class LifecycleRegistry {
      * Removes all registrations.
      */
     clear(): void;
+    /**
+     * Suffixes a derived name until it is unique within the registry.
+     */
+    private uniqueName;
     /**
      * Creates a stable registration ID.
      */

package/dist/lifecycle/core/lifecycleRegistry.registry.js

@@ -1,3 +1,4 @@
+import { InvalidArgumentError } from "../../errors/exceptions.js";
 /**
  * Registry responsible for lifecycle component registration
  * and deterministic ordering.
@@ -13,11 +14,18 @@ export class LifecycleRegistry {
      *
      * Components are executed in reverse registration order
      * during stopping and destruction.
+     *
+     * Names are unique within a registry: an explicit duplicate name is
+     * rejected, while derived names (constructor names) are made unique
+     * with a numeric suffix so getByName() is unambiguous.
      */
     register(component, name) {
+        if (name !== undefined && this.getByName(name)) {
+            throw new InvalidArgumentError(`A lifecycle component named "${name}" is already registered.`, { name });
+        }
         const registration = {
             id: this.createId(),
-            name: name ?? this.resolveComponentName(component),
+            name: name ?? this.uniqueName(this.resolveComponentName(component)),
             component,
             order: this.sequence,
             isParticipant: this.isLifecycleParticipant(component),
@@ -79,6 +87,17 @@ export class LifecycleRegistry {
     clear() {
         this.registrations.length = 0;
     }
+    /**
+     * Suffixes a derived name until it is unique within the registry.
+     */
+    uniqueName(base) {
+        if (!this.getByName(base))
+            return base;
+        let index = 2;
+        while (this.getByName(`${base}#${index}`))
+            index += 1;
+        return `${base}#${index}`;
+    }
     /**
      * Creates a stable registration ID.
      */

package/dist/lifecycle/manager/lifecycleManager.manager.d.ts

@@ -1,6 +1,6 @@
 import type { Logger } from "../../logging/core/logger.js";
 import { type LifecycleHook } from "../core/lifecycleHook.hook.js";
-import { LifecycleState, type LifecycleParticipant } from "../core/lifecycle.js";
+import { type LifecycleState, type LifecycleParticipant } from "../core/lifecycle.js";
 /** Anything that can participate in the managed application lifecycle. */
 export type ManagedLifecycleComponent = LifecycleParticipant | LifecycleHook;
 /** Options for LifecycleManager. */
@@ -11,21 +11,40 @@ export interface LifecycleManagerOptions {
 /**
  * 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 declare class LifecycleManager {
     private readonly lifecycle;
     private readonly components;
     private readonly logger?;
-    private readonly continueOnShutdownError;
     constructor(options?: LifecycleManagerOptions);
     getState(): LifecycleState;
     getComponents(): readonly ManagedLifecycleComponent[];
+    /**
+     * Registers a component. Only allowed before initialization begins.
+     */
     register(component: ManagedLifecycleComponent): void;
     initialize(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
     destroy(): Promise<void>;
     shutdown(): Promise<void>;
+    /**
+     * Normalizes a component into a LifecycleParticipant. Hook methods
+     * (onInitialize, ...) win over participant methods (initialize, ...)
+     * when a component exposes both, so each phase runs once.
+     */
+    private toParticipant;
     private runHook;
     private isLifecycleParticipant;
     private getComponentName;