@zudojs/lifecycle 0.1.0 → 1.1.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,109 @@ 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. 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
+
+`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);
         });
@@ -36,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);
@@ -51,19 +74,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;
+            }
+        });
+        const tracked = task.then(() => {
+            executing.delete(tracked);
         });
-        executing.add(p);
-        results.push(p);
-        if (executing.size >= concurrency) {
+        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

@@ -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,13 +21,65 @@ 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.
+     *
+     * 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>;
+    /**
+     * 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;
 /**
  * Safely transitions a component state machine to the target state.
  * 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

@@ -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.
@@ -15,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.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 = {
@@ -40,7 +39,9 @@ export class LifecycleManager {
             shutdownTimeout: options.shutdownTimeout ?? LIFECYCLE_DEFAULT_SHUTDOWN_TIMEOUT,
             componentStates: new Map(),
             results: new Map(),
+            attempted: new Map(),
             startTime: 0,
+            controller: new AbortController(),
         };
         if (options.handleSignals !== false) {
             this._removeSignalHandlers = installSignalHandlers({
@@ -77,11 +78,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 +105,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