@zudojs/lifecycle 0.1.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,7 @@
 # @zudojs/lifecycle
 
-Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.
+Application and component lifecycle orchestration with a state machine,
+dependency ordering, graceful shutdown, rollback, and signal handling.
 
 ## Installation
 
@@ -13,22 +14,97 @@ npm install @zudojs/lifecycle
 ```typescript
 import { createLifecycleManager } from "@zudojs/lifecycle";
 
-const manager = createLifecycleManager({
-  components: [database, server, worker],
-});
+const manager = createLifecycleManager();
+
+manager.register(database, { id: "db" });
+manager.register(queue, { id: "queue", dependsOn: ["db"] });
+manager.register(server, { id: "server", dependsOn: ["queue"] });
 
 await manager.start();
-await manager.stop();
+// ... application running ...
+await manager.shutdown();
+manager.dispose();
+```
+
+Components are plain objects implementing any subset of the hooks:
+
+```typescript
+const database = {
+  name: "database",
+  async initialize(context) {},
+  async start(context) {},
+  async ready(context) {},
+  async stop(context) {},
+  async dispose(context) {},
+};
+```
+
+## Startup and rollback
+
+Phases run in order: `initialize` → `start` → `ready`. Components with
+no dependency relationship run in parallel (bounded by `concurrency`).
+
+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.
+
+## Shutdown
+
+`shutdown()` runs `stop` → `dispose` in reverse dependency order. It is
+single-flight: concurrent callers, including the rollback triggered by a
+failing startup and the process signal handler, all await the same run.
+
+`shutdownTimeout` (default 30s) is a real wall-clock deadline for the
+whole sequence. When it expires the lifecycle context's `AbortSignal` is
+aborted so hooks that observe it can unwind, and shutdown completes
+regardless. A component that ignores the signal is abandoned, not
+awaited forever.
+
+Failing `stop()`/`dispose()` hooks are recorded: the component is marked
+`FAILED`, a `component:failed` event is emitted, and the result appears
+in `getStatus()`.
+
+## Cancellation
+
+Every hook receives a `LifecycleContext` whose `signal` is shared by the
+whole run and is aborted when the shutdown deadline expires. Long-running
+hooks should honour it:
+
+```typescript
+async stop(context) {
+  await drain({ signal: context.signal });
+}
 ```
 
-## Features
+## Events
+
+`manager.events.on(type, listener)` subscribes to:
+
+- `component:registered`, `component:initializing`, `component:initialized`,
+  `component:starting`, `component:started`, `component:ready`,
+  `component:stopping`, `component:stopped`, `component:failed`
+- `application:initializing`, `application:initialized`,
+  `application:starting`, `application:ready`, `application:stopping`,
+  `application:stopped`, `application:disposed`
+
+Listener exceptions are swallowed so observability never breaks the
+lifecycle.
+
+## Options
+
+```typescript
+createLifecycleManager({
+  concurrency: 10,        // parallel component operations per stage
+  shutdownTimeout: 30_000, // global shutdown deadline (ms)
+  handleSignals: true,     // install process signal handlers
+  signals: ["SIGINT", "SIGTERM"], // defaults to DEFAULT_SHUTDOWN_SIGNALS
+});
+```
 
-- State machine for lifecycle phases
-- Dependency ordering between components
-- Graceful shutdown with timeouts
-- Rollback on startup failure
-- Signal handling
-- Lifecycle hooks and events
+Per-component: `id`, `dependsOn`, `priority`, `critical`, `timeout`,
+`retry: { attempts, delay, maxDelay, backoff }`.
 
 ## Use Cases
 

package/dist/lifecycleExecutor/lifecycleExecutor.core.js

@@ -29,6 +29,13 @@ export class LifecycleExecutor {
         const retryConfig = registration.retry;
         const maxAttempts = 1 + (retryConfig.attempts ?? 0);
         for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            // A hook must not be retried (or even started) once the run has
+            // been cancelled — the context signal is aborted by the shutdown
+            // deadline and by startup rollback.
+            if (context.signal.aborted) {
+                lastError ??= new LifecycleComponentError(registration.id, phase, context.signal.reason);
+                break;
+            }
             try {
                 await withTimeout(async () => {
                     const result = hook.call(registration.component, context);
@@ -47,7 +54,7 @@ export class LifecycleExecutor {
                 lastError = error;
                 if (attempt < maxAttempts - 1) {
                     const delay = calculateDelay(retryConfig, attempt);
-                    await sleep(delay);
+                    await sleep(delay, context.signal);
                 }
             }
         }
@@ -55,7 +62,12 @@ export class LifecycleExecutor {
             id: registration.id,
             phase,
             duration: Date.now() - startTime,
-            error: lastError,
+            // LifecycleComponentError was imported but never constructed, so
+            // callers received a bare hook error with no indication of which
+            // component or phase produced it.
+            error: lastError instanceof LifecycleComponentError
+                ? lastError
+                : new LifecycleComponentError(registration.id, phase, lastError),
             success: false,
         };
     }
@@ -81,8 +93,27 @@ function calculateDelay(config, attempt) {
     }
     return base;
 }
-/** Sleeps for the given duration. */
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Sleeps for the given duration, waking early when the run is aborted.
+ *
+ * An unconditional timer would keep the process alive for a full retry
+ * backoff after shutdown had already been requested.
+ */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve();
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
 }
 //# sourceMappingURL=lifecycleExecutor.core.js.map

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -13,12 +13,23 @@ export async function withTimeout(fn, timeoutMs, componentId, phase) {
         const timer = setTimeout(() => {
             reject(new LifecycleTimeoutError(componentId, phase, timeoutMs));
         }, timeoutMs);
-        fn()
-            .then((result) => {
+        // The timer must be cleared on EVERY exit path. A synchronously
+        // throwing `fn` used to escape before `.catch` was attached,
+        // leaving an armed timer that kept the event loop alive for the
+        // whole timeout after the operation had already failed.
+        let operation;
+        try {
+            operation = fn();
+        }
+        catch (error) {
+            clearTimeout(timer);
+            reject(error);
+            return;
+        }
+        operation.then((result) => {
             clearTimeout(timer);
             resolve(result);
-        })
-            .catch((error) => {
+        }, (error) => {
             clearTimeout(timer);
             reject(error);
         });
@@ -51,19 +62,40 @@ export async function withAbort(fn, signal) {
  * Executes async operations with a concurrency limit.
  */
 export async function withConcurrency(items, concurrency, fn) {
+    const limit = Number.isFinite(concurrency) && concurrency > 0
+        ? Math.floor(concurrency)
+        : 1;
     const executing = new Set();
-    const results = [];
-    for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const p = fn(item, i).then(() => {
-            executing.delete(p);
+    // Every scheduled task is settled before this function returns, and
+    // the FIRST failure is rethrown afterwards. The previous version
+    // removed a task from `executing` only on success, so one rejection
+    // left a permanently-rejected promise in the race set, abandoned the
+    // remaining items, and produced an unhandled rejection for every
+    // task still in flight.
+    const settled = [];
+    let firstError;
+    let failed = false;
+    // `entries()` yields the element typed as T, so no non-null
+    // assertion is needed to satisfy noUncheckedIndexedAccess.
+    for (const [index, item] of items.entries()) {
+        const task = fn(item, index).catch((error) => {
+            if (!failed) {
+                failed = true;
+                firstError = error;
+            }
         });
-        executing.add(p);
-        results.push(p);
-        if (executing.size >= concurrency) {
+        const tracked = task.then(() => {
+            executing.delete(tracked);
+        });
+        executing.add(tracked);
+        settled.push(tracked);
+        if (executing.size >= limit) {
             await Promise.race(executing);
         }
     }
-    await Promise.all(results);
+    await Promise.all(settled);
+    if (failed) {
+        throw firstError;
+    }
 }
 //# sourceMappingURL=asyncUtils.core.js.map

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

@@ -21,7 +21,27 @@ export interface LifecycleManagerContext {
     readonly componentStates: Map<string, LifecycleStateMachine>;
     readonly results: Map<string, ExecutionResult[]>;
     startTime: number;
+    /**
+     * Cancellation source for the current run.
+     *
+     * Its signal is the one handed to every component hook through
+     * LifecycleContext. It is aborted when the global shutdown deadline
+     * expires, so a hook that honours the signal can bail out instead of
+     * hanging the process.
+     */
+    readonly controller: AbortController;
+    /**
+     * The in-flight shutdown, shared by every caller.
+     *
+     * Startup rollback and LifecycleManager.shutdown() both go through
+     * this field, so a signal arriving during a failing startup joins the
+     * rollback already running instead of starting a second, overlapping
+     * teardown.
+     */
+    shutdownPromise?: Promise<void>;
 }
+/** Records an execution result against its component. */
+export declare function recordResult(ctx: LifecycleManagerContext, result: ExecutionResult): void;
 /**
  * Safely transitions a component state machine to the target state.
  * No-op if the transition is not valid from the current state.

package/dist/lifecycleManager/lifecycleManager.context.js

@@ -5,6 +5,11 @@
  * plus helper functions for component state transitions and event emission.
  */
 import { LifecycleState } from "@zudojs/constants";
+/** Records an execution result against its component. */
+export function recordResult(ctx, result) {
+    const existing = ctx.results.get(result.id) ?? [];
+    ctx.results.set(result.id, [...existing, result]);
+}
 /**
  * Safely transitions a component state machine to the target state.
  * No-op if the transition is not valid from the current state.

package/dist/lifecycleManager/lifecycleManager.core.d.ts

@@ -36,7 +36,6 @@ export interface LifecycleManagerOptions {
 export declare class LifecycleManager {
     private readonly _ctx;
     private _startPromise?;
-    private _shutdownPromise?;
     private _removeSignalHandlers?;
     constructor(options?: LifecycleManagerOptions);
     /** Registers a component with the lifecycle manager. */
@@ -62,7 +61,12 @@ export declare class LifecycleManager {
         state: LifecycleState;
         results: readonly ExecutionResult[];
     }>;
-    /** Disposes the lifecycle manager and cleans up resources. */
+    /**
+     * Disposes the lifecycle manager and cleans up resources.
+     *
+     * This removes signal handlers and listeners only; it does NOT run
+     * component teardown — call `shutdown()` first for that.
+     */
     dispose(): void;
 }
 /** Creates a new lifecycle manager. */

package/dist/lifecycleManager/lifecycleManager.core.js

@@ -28,7 +28,6 @@ import { performShutdown } from "./lifecycleManager.shutdown.js";
 export class LifecycleManager {
     _ctx;
     _startPromise;
-    _shutdownPromise;
     _removeSignalHandlers;
     constructor(options = {}) {
         this._ctx = {
@@ -41,6 +40,7 @@ export class LifecycleManager {
             componentStates: new Map(),
             results: new Map(),
             startTime: 0,
+            controller: new AbortController(),
         };
         if (options.handleSignals !== false) {
             this._removeSignalHandlers = installSignalHandlers({
@@ -77,11 +77,9 @@ export class LifecycleManager {
      * Idempotent — returns the same promise if called multiple times.
      */
     async shutdown() {
-        if (this._shutdownPromise) {
-            return this._shutdownPromise;
-        }
-        this._shutdownPromise = performShutdown(this._ctx);
-        return this._shutdownPromise;
+        // performShutdown is itself single-flight, so a shutdown started by
+        // startup rollback and one started here are the SAME run.
+        return performShutdown(this._ctx);
     }
     /** Returns the current application state. */
     get state() {
@@ -106,9 +104,15 @@ export class LifecycleManager {
         }
         return status;
     }
-    /** Disposes the lifecycle manager and cleans up resources. */
+    /**
+     * Disposes the lifecycle manager and cleans up resources.
+     *
+     * This removes signal handlers and listeners only; it does NOT run
+     * component teardown — call `shutdown()` first for that.
+     */
     dispose() {
         this._removeSignalHandlers?.();
+        this._removeSignalHandlers = undefined;
         this._ctx.events.clear();
     }
 }

package/dist/lifecycleManager/lifecycleManager.shutdown.d.ts

@@ -6,7 +6,10 @@
 import type { LifecycleManagerContext } from "./lifecycleManager.context.js";
 /**
  * Performs the full shutdown sequence: stop → dispose.
- * Idempotent — safe to call multiple times.
+ *
+ * Idempotent and single-flight: concurrent callers (a signal handler
+ * and a failing startup, say) all await the SAME teardown rather than
+ * running overlapping ones.
  */
 export declare function performShutdown(ctx: LifecycleManagerContext): Promise<void>;
 //# sourceMappingURL=lifecycleManager.shutdown.d.ts.map

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -6,27 +6,51 @@
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-import { transitionComponent } from "./lifecycleManager.context.js";
+import { emitComponentFailed, recordResult, transitionComponent, } from "./lifecycleManager.context.js";
 /** Shutdown phases in execution order. */
-const SHUTDOWN_PHASES = ["stop", "dispose"];
+const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
 /**
  * Performs the full shutdown sequence: stop → dispose.
- * Idempotent — safe to call multiple times.
+ *
+ * Idempotent and single-flight: concurrent callers (a signal handler
+ * and a failing startup, say) all await the SAME teardown rather than
+ * running overlapping ones.
  */
-export async function performShutdown(ctx) {
+export function performShutdown(ctx) {
+    ctx.shutdownPromise ??= runShutdown(ctx);
+    return ctx.shutdownPromise;
+}
+async function runShutdown(ctx) {
     if (ctx.state.state === LifecycleState.DISPOSED)
         return;
+    // Shutdown must always be possible, including mid-startup. A plain
+    // transition() threw LifecycleStateError when shutdown() was called
+    // while the application was still INITIALIZING or STARTING, so a
+    // signal arriving during startup crashed instead of tearing down.
     if (ctx.state.state !== LifecycleState.STOPPING &&
         ctx.state.state !== LifecycleState.FAILED) {
-        ctx.state.transition(LifecycleState.STOPPING);
+        if (ctx.state.canTransition(LifecycleState.STOPPING)) {
+            ctx.state.transition(LifecycleState.STOPPING);
+        }
+        else {
+            ctx.state.forceState(LifecycleState.STOPPING);
+        }
     }
     ctx.events.emit("application:stopping", {});
     const deadline = Date.now() + ctx.shutdownTimeout;
+    // 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
+    // budget and abort the run's signal when it expires, so hooks that
+    // honour cancellation stop and the rest are abandoned.
     for (const phase of SHUTDOWN_PHASES) {
-        if (deadline - Date.now() <= 0)
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+            ctx.controller.abort(new Error(`Lifecycle shutdown exceeded its ${ctx.shutdownTimeout}ms deadline.`));
             break;
+        }
         try {
-            await executeShutdownPhase(ctx, phase);
+            await raceDeadline(ctx, executeShutdownPhase(ctx, phase), remaining);
         }
         catch {
             // Shutdown must continue even if individual components fail.
@@ -36,11 +60,44 @@ export async function performShutdown(ctx) {
     ctx.events.emit("application:stopped", {
         duration: Date.now() - ctx.startTime,
     });
+    ctx.events.emit("application:disposed", {
+        duration: Date.now() - ctx.startTime,
+    });
+}
+/**
+ * Resolves when the phase finishes or the shutdown budget runs out.
+ *
+ * On expiry the run's AbortController is aborted so in-flight hooks
+ * observing `context.signal` unwind, and the timer is always cleared
+ * so it can never hold the event loop open.
+ */
+async function raceDeadline(ctx, phase, remainingMs) {
+    let timer;
+    const expiry = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ctx.controller.abort(new Error(`Lifecycle shutdown exceeded its ${ctx.shutdownTimeout}ms deadline.`));
+            resolve();
+        }, remainingMs);
+    });
+    try {
+        await Promise.race([phase, expiry]);
+    }
+    finally {
+        if (timer !== undefined) {
+            clearTimeout(timer);
+        }
+    }
+    // The abandoned phase promise must never surface as an unhandled
+    // rejection once the race has been decided.
+    void phase.catch(() => { });
 }
 /** Executes a single shutdown phase across all registered components. */
 async function executeShutdownPhase(ctx, phase) {
     const plan = buildExecutionPlan(ctx.registry.getAll(), phase);
-    const context = createLifecycleContext(phase, ctx.startTime);
+    const context = createLifecycleContext(phase, ctx.startTime, ctx.controller.signal);
+    const failureState = phase === LifecyclePhase.STOP
+        ? LifecycleState.STOPPED
+        : LifecycleState.DISPOSED;
     for (const stage of plan.stages) {
         const stageRegs = stage.components
             .map((id) => ctx.registry.get(id))
@@ -49,11 +106,26 @@ async function executeShutdownPhase(ctx, phase) {
             continue;
         for (const reg of stageRegs) {
             transitionComponent(ctx, reg.id, LifecycleState.STOPPING);
+            ctx.events.emit("component:stopping", {
+                component: { componentId: reg.id },
+            });
         }
-        await ctx.executor.executeStage(stageRegs, phase, context, ctx.concurrency);
-        const targetState = phase === "stop" ? LifecycleState.STOPPED : LifecycleState.DISPOSED;
-        for (const reg of stageRegs) {
-            transitionComponent(ctx, reg.id, targetState);
+        const results = await ctx.executor.executeStage(stageRegs, 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
+        // operators had no way to learn a resource had leaked.
+        for (const result of results) {
+            recordResult(ctx, result);
+            if (result.success) {
+                transitionComponent(ctx, result.id, failureState);
+                ctx.events.emit("component:stopped", {
+                    component: { componentId: result.id, duration: result.duration },
+                });
+                continue;
+            }
+            transitionComponent(ctx, result.id, LifecycleState.FAILED);
+            emitComponentFailed(ctx, result);
         }
     }
 }

package/dist/lifecycleManager/lifecycleManager.startup.d.ts

@@ -6,6 +6,12 @@
 import type { LifecycleManagerContext } from "./lifecycleManager.context.js";
 /**
  * Performs the full startup sequence: initialize → start → ready.
+ *
+ * When a CRITICAL component fails, the application is rolled back
+ * (stop → dispose) and this function REJECTS with a LifecycleStartError.
+ * It previously resolved normally after rolling everything back, so
+ * `await manager.start()` reported success for an application that had
+ * just been torn down.
  */
 export declare function performStartup(ctx: LifecycleManagerContext): Promise<void>;
 //# sourceMappingURL=lifecycleManager.startup.d.ts.map