@zudojs/lifecycle 1.0.0 → 1.1.0

package/README.md

@@ -48,7 +48,19 @@ If a **critical** component (the default) fails any startup phase,
 `start()` rolls the application back (`stop` → `dispose`) and then
 **rejects** with a `LifecycleStartError`. Register a component with
 `{ critical: false }` when its failure should not abort startup — the
-component is marked `FAILED` and startup continues.
+component is marked `FAILED` and startup continues. A failed component
+takes no further part in startup (its later hooks are not invoked), and
+components that `dependsOn` it are not started either: they are marked
+`FAILED` with a `LifecycleComponentError` naming the failed dependency,
+and their own `critical` flag decides whether startup aborts.
+
+Rollback only undoes phases that ran: `stop()` is called on components
+whose `start` phase ran, and `dispose()` on components whose
+`initialize` phase ran.
+
+Calling `shutdown()` while `start()` is in flight waits for the
+executing stage to settle, tears down, and makes `start()` reject with a
+`LifecycleStartError` — later stages are never launched.
 
 ## Shutdown
 

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -47,7 +47,19 @@ export async function withAbort(fn, signal) {
             reject(new Error("Operation aborted"));
         };
         signal.addEventListener("abort", onAbort, { once: true });
-        fn(signal)
+        // A synchronously throwing `fn` rejected via the Promise executor
+        // but skipped both `.then` branches, so its abort listener was
+        // never removed and accumulated on a long-lived signal.
+        let operation;
+        try {
+            operation = fn(signal);
+        }
+        catch (error) {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+            return;
+        }
+        operation
             .then((result) => {
             signal.removeEventListener("abort", onAbort);
             resolve(result);

package/dist/lifecycleManager/lifecycleManager.context.d.ts

@@ -5,6 +5,7 @@
  * plus helper functions for component state transitions and event emission.
  */
 import { LifecycleState } from "@zudojs/constants";
+import type { LifecyclePhase } from "@zudojs/constants";
 import type { LifecycleStateMachine } from "../lifecycleState/lifecycleState.machine.js";
 import type { LifecycleRegistry } from "../lifecycleRegistry/lifecycleRegistry.core.js";
 import type { LifecycleExecutor } from "../lifecycleExecutor/lifecycleExecutor.core.js";
@@ -20,6 +21,16 @@ export interface LifecycleManagerContext {
     readonly shutdownTimeout: number;
     readonly componentStates: Map<string, LifecycleStateMachine>;
     readonly results: Map<string, ExecutionResult[]>;
+    /**
+     * Startup phases that were actually run for each component.
+     *
+     * Shutdown consults this so `stop()` is only invoked on components
+     * whose `start` phase ran and `dispose()` only on components whose
+     * `initialize` phase ran. Rollback after an early failure used to
+     * call `stop()` on components that had never started, which for a
+     * real server throws and was then reported as a component failure.
+     */
+    readonly attempted: Map<string, Set<LifecyclePhase>>;
     startTime: number;
     /**
      * Cancellation source for the current run.
@@ -39,6 +50,16 @@ export interface LifecycleManagerContext {
      * teardown.
      */
     shutdownPromise?: Promise<void>;
+    /**
+     * The startup stage currently executing, if any.
+     *
+     * A shutdown requested mid-startup waits for this to settle before
+     * running `stop()`, so a component is never stopped while its own
+     * `start()` is still in flight, and startup checks for a requested
+     * shutdown before launching each further stage so no hook runs
+     * after teardown has completed.
+     */
+    inFlight?: Promise<unknown>;
 }
 /** Records an execution result against its component. */
 export declare function recordResult(ctx: LifecycleManagerContext, result: ExecutionResult): void;
@@ -47,6 +68,18 @@ export declare function recordResult(ctx: LifecycleManagerContext, result: Execu
  * No-op if the transition is not valid from the current state.
  */
 export declare function transitionComponent(ctx: LifecycleManagerContext, id: string, targetState: LifecycleState): void;
+/**
+ * Marks a component as FAILED regardless of its current state.
+ *
+ * Used for components that are skipped because a dependency failed:
+ * they have not entered the phase, so no validated transition leads to
+ * FAILED from their current (IDLE / INITIALIZED / STARTED) state.
+ */
+export declare function failComponent(ctx: LifecycleManagerContext, id: string): void;
+/** Records that a startup phase ran for a component. */
+export declare function markAttempted(ctx: LifecycleManagerContext, id: string, phase: LifecyclePhase): void;
+/** Returns whether a startup phase ran for a component. */
+export declare function wasAttempted(ctx: LifecycleManagerContext, id: string, phase: LifecyclePhase): boolean;
 /**
  * Transitions multiple component state machines to the same target state.
  */

package/dist/lifecycleManager/lifecycleManager.context.js

@@ -20,6 +20,26 @@ export function transitionComponent(ctx, id, targetState) {
         sm.transition(targetState);
     }
 }
+/**
+ * Marks a component as FAILED regardless of its current state.
+ *
+ * Used for components that are skipped because a dependency failed:
+ * they have not entered the phase, so no validated transition leads to
+ * FAILED from their current (IDLE / INITIALIZED / STARTED) state.
+ */
+export function failComponent(ctx, id) {
+    ctx.componentStates.get(id)?.forceState(LifecycleState.FAILED);
+}
+/** Records that a startup phase ran for a component. */
+export function markAttempted(ctx, id, phase) {
+    const phases = ctx.attempted.get(id) ?? new Set();
+    phases.add(phase);
+    ctx.attempted.set(id, phases);
+}
+/** Returns whether a startup phase ran for a component. */
+export function wasAttempted(ctx, id, phase) {
+    return ctx.attempted.get(id)?.has(phase) ?? false;
+}
 /**
  * Transitions multiple component state machines to the same target state.
  */

package/dist/lifecycleManager/lifecycleManager.core.js

@@ -39,6 +39,7 @@ export class LifecycleManager {
             shutdownTimeout: options.shutdownTimeout ?? LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT,
             componentStates: new Map(),
             results: new Map(),
+            attempted: new Map(),
             startTime: 0,
             controller: new AbortController(),
         };

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -6,7 +6,7 @@
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { emitComponentFailed, recordResult, transitionComponent, } from "./lifecycleManager.context.js";
+import { emitComponentFailed, recordResult, transitionComponent, wasAttempted, } from "./lifecycleManager.context.js";
 /** Shutdown phases in execution order. */
 const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
 /**
@@ -38,6 +38,13 @@ async function runShutdown(ctx) {
     }
     ctx.events.emit("application:stopping", {});
     const deadline = Date.now() + ctx.shutdownTimeout;
+    // A startup stage still executing must settle before its components
+    // are stopped, otherwise `stop()` overlaps the component's own
+    // `start()`. Startup itself refuses to launch further stages once
+    // `shutdownPromise` is set, so this wait is bounded by one stage.
+    if (ctx.inFlight !== undefined) {
+        await raceDeadline(ctx, ctx.inFlight.then(() => undefined, () => undefined), Math.max(deadline - Date.now(), 1));
+    }
     // The shutdown deadline used to be checked only BETWEEN the two
     // phases, so a single hook that never settled hung shutdown (and the
     // process) forever. Race the whole phase against the remaining
@@ -91,11 +98,24 @@ async function raceDeadline(ctx, phase, remainingMs) {
     // rejection once the race has been decided.
     void phase.catch(() => { });
 }
-/** Executes a single shutdown phase across all registered components. */
+/**
+ * Executes a single shutdown phase across all registered components.
+ *
+ * A hook only runs for components that reached the matching startup
+ * phase: `stop()` when `start` ran, `dispose()` when `initialize` ran.
+ * Rollback after an early failure — and `shutdown()` on a manager that
+ * was never started — used to call `stop()` on components that had
+ * never started; a real server's `close()` throws in that situation
+ * and the phantom failure was then recorded against the component.
+ */
 async function executeShutdownPhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
     const context = createLifecycleContext(phase, ctx.startTime, ctx.controller.signal);
-    const failureState = phase === LifecyclePhase.STOP
+    const isStop = phase === LifecyclePhase.STOP;
+    const prerequisite = isStop
+        ? LifecyclePhase.START
+        : LifecyclePhase.INITIALIZE;
+    const successState = isStop
         ? LifecycleState.STOPPED
         : LifecycleState.DISPOSED;
     for (const stage of plan.stages) {
@@ -104,13 +124,30 @@ async function executeShutdownPhase(ctx, phase) {
             .filter((r) => r !== undefined);
         if (stageRegs.length === 0)
             continue;
+        const runnable = [];
         for (const reg of stageRegs) {
-            transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
+            if (!wasAttempted(ctx, reg.id, prerequisite)) {
+                // Never reached the phase this hook undoes. It still ends up
+                // DISPOSED so status reflects the teardown.
+                if (!isStop) {
+                    transitionComponent(ctx, reg.id, LifecycleState.DISPOSED);
+                }
+                continue;
+            }
+            runnable.push(reg);
+            // Only the stop phase moves a component into STOPPING; dispose
+            // runs from STOPPED (or FAILED) and transitions straight to
+            // DISPOSED.
+            if (isStop) {
+                transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
+            }
             ctx.events.emit("component:stopping", {
                 component: { componentId: reg.id },
             });
         }
-        const results = await ctx.executor.executeStage(stageRegs, phase, context, ctx.concurrency);
+        if (runnable.length === 0)
+            continue;
+        const results = await ctx.executor.executeStage(runnable, phase, context, ctx.concurrency);
         // Shutdown results used to be discarded entirely: a component whose
         // stop() or dispose() threw was still reported as cleanly STOPPED,
         // its failure never reached getStatus() or the event stream, and
@@ -118,7 +155,7 @@ async function executeShutdownPhase(ctx, phase) {
         for (const result of results) {
             recordResult(ctx, result);
             if (result.success) {
-                transitionComponent(ctx, result.id, failureState);
+                transitionComponent(ctx, result.id, successState);
                 ctx.events.emit("component:stopped", {
                     component: { componentId: result.id, duration: result.duration },
                 });

package/dist/lifecycleManager/lifecycleManager.startup.js

@@ -4,10 +4,10 @@
  * Startup orchestration — initializes, starts, and readies components.
  */
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
-import { LifecycleStartError } from "@zudojs/errors";
+import { LifecycleComponentError, LifecycleStartError } from "@zudojs/errors";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { transitionComponent, transitionComponentBatch, emitComponentFailed, recordResult, } from "./lifecycleManager.context.js";
+import { transitionComponent, transitionComponentBatch, emitComponentFailed, failComponent, markAttempted, recordResult, } from "./lifecycleManager.context.js";
 import { performShutdown } from "./lifecycleManager.shutdown.js";
 /** Maps startup phases to their target component state after success. */
 const SUCCESS_STATE = {
@@ -68,6 +68,7 @@ export async function performStartup(ctx) {
         if (failedInit) {
             throw new LifecycleStartError(failedInit.id, failedInit.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.INITIALIZE);
         ctx.state.transition(LifecycleState.INITIALIZED);
         ctx.events.emit("application:initialized", {
             duration: Date.now() - ctx.startTime,
@@ -77,6 +78,7 @@ export async function performStartup(ctx) {
         if (failedStart) {
             throw new LifecycleStartError(failedStart.id, failedStart.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.START);
         ctx.state.transition(LifecycleState.STARTED);
         // A failing `ready` hook on a critical component used to be
         // ignored completely: no state change, no rollback, and start()
@@ -85,6 +87,7 @@ export async function performStartup(ctx) {
         if (failedReady) {
             throw new LifecycleStartError(failedReady.id, failedReady.error);
         }
+        assertNotShuttingDown(ctx, LifecyclePhase.READY);
         ctx.state.transition(LifecycleState.READY);
         ctx.events.emit("application:ready", {
             duration: Date.now() - ctx.startTime,
@@ -94,7 +97,10 @@ export async function performStartup(ctx) {
         // Rollback happens on exactly one path, so a completed teardown is
         // never re-entered and its DISPOSED state is never overwritten
         // with FAILED.
-        if (ctx.state.state !== LifecycleState.FAILED &&
+        // When the failure IS a requested shutdown, the teardown already
+        // owns the application state.
+        if (ctx.shutdownPromise === undefined &&
+            ctx.state.state !== LifecycleState.FAILED &&
             ctx.state.state !== LifecycleState.DISPOSED) {
             ctx.state.forceState(LifecycleState.FAILED);
         }
@@ -102,9 +108,40 @@ export async function performStartup(ctx) {
         throw error;
     }
 }
+/**
+ * Throws when a shutdown has been requested while startup is running.
+ *
+ * Startup used to keep launching later stages after `shutdown()` had
+ * already torn everything down: a component started that way was
+ * never stopped, and the eventual failure was an opaque
+ * LifecycleStateError from the DISPOSED → INITIALIZED transition.
+ */
+function assertNotShuttingDown(ctx, phase) {
+    if (ctx.shutdownPromise !== undefined) {
+        throw new LifecycleStartError("application", new LifecycleComponentError("application", phase, new Error("Startup was cancelled because shutdown was requested while the application was starting.")));
+    }
+}
 /**
  * Executes a single startup phase across all registered components.
  * Returns the failure of the first critical component, or undefined.
+ *
+ * Two bookkeeping rules apply to every stage:
+ *
+ * - A component that FAILED an earlier phase, or whose dependency has
+ *   failed, does not enter this phase. It used to have `start()` and
+ *   `ready()` invoked after its own `initialize()` had thrown, and its
+ *   dependents were started as if the dependency were healthy —
+ *   silently voiding the `dependsOn` contract. A skipped dependent is
+ *   recorded as FAILED with a LifecycleComponentError naming the
+ *   failed dependency, and its own `critical` flag decides whether
+ *   startup aborts.
+ *
+ * - Every result of a stage is recorded, transitioned and announced
+ *   before a critical failure aborts the phase. Returning on the first
+ *   failed result dropped the results of siblings in the same stage,
+ *   which were then left in INITIALIZING / STARTING forever (no
+ *   transition leads out of those states except to their success or
+ *   FAILED) even after rollback had disposed them.
  */
 async function executePhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
@@ -117,21 +154,62 @@ async function executePhase(ctx, phase) {
             .filter((r) => r !== undefined);
         if (stageRegs.length === 0)
             continue;
-        transitionComponentBatch(ctx, stageRegs.map((r) => r.id), EXECUTING_STATE[phase]);
+        assertNotShuttingDown(ctx, phase);
+        const runnable = [];
+        let criticalFailure;
         for (const reg of stageRegs) {
+            if (ctx.componentStates.get(reg.id)?.state === LifecycleState.FAILED) {
+                // Already failed in an earlier phase; nothing more to run.
+                continue;
+            }
+            const failedDependency = reg.dependsOn.find((dep) => ctx.componentStates.get(dep)?.state === LifecycleState.FAILED);
+            if (failedDependency === undefined) {
+                runnable.push(reg);
+                continue;
+            }
+            const skipped = {
+                id: reg.id,
+                phase,
+                duration: 0,
+                success: false,
+                error: new LifecycleComponentError(reg.id, phase, new Error(`Component "${reg.id}" was not started because its dependency "${failedDependency}" failed.`)),
+            };
+            recordResult(ctx, skipped);
+            failComponent(ctx, reg.id);
+            emitComponentFailed(ctx, skipped);
+            if (reg.critical) {
+                criticalFailure ??= { id: reg.id, error: skipped.error };
+            }
+        }
+        if (criticalFailure) {
+            ctx.state.forceState(LifecycleState.FAILED);
+            return criticalFailure;
+        }
+        if (runnable.length === 0)
+            continue;
+        transitionComponentBatch(ctx, runnable.map((r) => r.id), EXECUTING_STATE[phase]);
+        for (const reg of runnable) {
+            markAttempted(ctx, reg.id, phase);
             ctx.events.emit(events.begin, {
                 component: { componentId: reg.id },
             });
         }
-        const results = await ctx.executor.executeStage(stageRegs, phase, context, ctx.concurrency);
+        const pending = ctx.executor.executeStage(runnable, phase, context, ctx.concurrency);
+        ctx.inFlight = pending;
+        let results;
+        try {
+            results = await pending;
+        }
+        finally {
+            ctx.inFlight = undefined;
+        }
         for (const result of results) {
             recordResult(ctx, result);
             if (!result.success) {
                 transitionComponent(ctx, result.id, LifecycleState.FAILED);
                 emitComponentFailed(ctx, result);
                 if (ctx.registry.get(result.id)?.critical) {
-                    ctx.state.forceState(LifecycleState.FAILED);
-                    return { id: result.id, error: result.error };
+                    criticalFailure ??= { id: result.id, error: result.error };
                 }
             }
             else {
@@ -141,6 +219,10 @@ async function executePhase(ctx, phase) {
                 });
             }
         }
+        if (criticalFailure) {
+            ctx.state.forceState(LifecycleState.FAILED);
+            return criticalFailure;
+        }
     }
     return undefined;
 }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@zudojs/lifecycle",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.",
   "license": "MIT",
+  "author": {
+    "name": "Oluwayemi Oyinlola",
+    "url": "https://github.com/oyinlola-tech"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -20,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.0",
-    "@zudojs/constants": "1.0.0"
+    "@zudojs/errors": "1.0.1",
+    "@zudojs/constants": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",