@zudojs/lifecycle 1.1.0 → 1.1.1

package/README.md

@@ -3,6 +3,12 @@
 Application and component lifecycle orchestration with a state machine,
 dependency ordering, graceful shutdown, rollback, and signal handling.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-lifecycle](https://zudojs.oyinlola.site/docs/packages-lifecycle) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-lifecycle.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -109,8 +115,8 @@ lifecycle.
 ```typescript
 createLifecycleManager({
   concurrency: 10,        // parallel component operations per stage
-  shutdownTimeout: 30_000, // global shutdown deadline (ms)
-  handleSignals: true,     // install process signal handlers
+  shutdownTimeout: 30_000, // global shutdown deadline (ms); Infinity = none
+  handleSignals: true,     // install signal handlers on start()
   signals: ["SIGINT", "SIGTERM"], // defaults to DEFAULT_SHUTDOWN_SIGNALS
 });
 ```
@@ -118,6 +124,18 @@ createLifecycleManager({
 Per-component: `id`, `dependsOn`, `priority`, `critical`, `timeout`,
 `retry: { attempts, delay, maxDelay, backoff }`.
 
+`timeout` and `shutdownTimeout` accept `Infinity` for "no bound"; NaN and
+negative values throw a `RangeError` when registered or constructed, and
+finite values above 2^31-1 ms are clamped to the largest timer delay.
+`retry` covers hooks that fail; a hook that times out is not retried,
+because it is still running and a second call would overlap it.
+`shutdown()` waits (within its deadline) for such an abandoned hook to
+settle before calling `stop()`.
+
+With `handleSignals`, SIGINT/SIGTERM listeners are installed by `start()`,
+not by the constructor, and removed once shutdown finishes. A second
+signal while shutdown is running exits the process with code 1.
+
 ## Use Cases
 
 - Coordinating service startup and shutdown

package/dist/lifecycleComponent/lifecycleComponent.type.d.ts

@@ -32,7 +32,10 @@ export interface LifecycleRegistrationOptions {
     readonly priority?: number;
     /** If true, application startup fails when this component fails. Defaults to true. */
     readonly critical?: boolean;
-    /** Timeout in ms for individual component operations. */
+    /**
+     * Timeout in ms for individual component operations. `Infinity` means
+     * no bound; NaN and negative values are rejected at registration.
+     */
     readonly timeout?: number;
     /** Retry configuration for failed operations. */
     readonly retry?: LifecycleRetryOptions;

package/dist/lifecycleExecutor/lifecycleExecutor.core.d.ts

@@ -23,6 +23,15 @@ export interface ExecutionResult {
  * Executes lifecycle component hooks with timeout, retry, and concurrency support.
  */
 export declare class LifecycleExecutor {
+    /** Hook invocations still running after their timeout fired. */
+    private readonly abandoned;
+    /**
+     * Resolves once every hook abandoned by a timeout has settled.
+     *
+     * Shutdown waits on this before stopping components, so `stop()`
+     * never overlaps a `start()` that is still running.
+     */
+    settleAbandoned(): Promise<void>;
     /**
      * Executes a single component hook.
      */

package/dist/lifecycleExecutor/lifecycleExecutor.core.js

@@ -5,11 +5,24 @@
  */
 import { withTimeout, withConcurrency } from "../lifecycleInternal/index.js";
 import { getComponentMethod } from "../lifecyclePhase/index.js";
-import { LifecycleComponentError } from "@zudojs/errors";
+import { LifecycleComponentError, LifecycleTimeoutError, } from "@zudojs/errors";
 /**
  * Executes lifecycle component hooks with timeout, retry, and concurrency support.
  */
 export class LifecycleExecutor {
+    /** Hook invocations still running after their timeout fired. */
+    abandoned = new Set();
+    /**
+     * Resolves once every hook abandoned by a timeout has settled.
+     *
+     * Shutdown waits on this before stopping components, so `stop()`
+     * never overlaps a `start()` that is still running.
+     */
+    async settleAbandoned() {
+        while (this.abandoned.size > 0) {
+            await Promise.allSettled([...this.abandoned]);
+        }
+    }
     /**
      * Executes a single component hook.
      */
@@ -36,12 +49,13 @@ export class LifecycleExecutor {
                 lastError ??= new LifecycleComponentError(registration.id, phase, context.signal.reason);
                 break;
             }
+            let invocation;
             try {
-                await withTimeout(async () => {
-                    const result = hook.call(registration.component, context);
-                    if (result instanceof Promise) {
-                        await result;
-                    }
+                await withTimeout(() => {
+                    invocation = (async () => {
+                        await hook.call(registration.component, context);
+                    })();
+                    return invocation;
                 }, registration.timeout, registration.id, phase);
                 return {
                     id: registration.id,
@@ -52,6 +66,16 @@ export class LifecycleExecutor {
             }
             catch (error) {
                 lastError = error;
+                // A timed-out hook is still running; withTimeout cannot cancel
+                // it. Retrying would run the same start() concurrently (three
+                // listen() calls on one port), so a timeout is final and the
+                // abandoned invocation is tracked for shutdown to wait on.
+                if (error instanceof LifecycleTimeoutError && invocation) {
+                    const abandoned = invocation.catch(() => undefined);
+                    this.abandoned.add(abandoned);
+                    void abandoned.finally(() => this.abandoned.delete(abandoned));
+                    break;
+                }
                 if (attempt < maxAttempts - 1) {
                     const delay = calculateDelay(retryConfig, attempt);
                     await sleep(delay, context.signal);

package/dist/lifecycleInternal/asyncUtils.core.d.ts

@@ -6,6 +6,10 @@
 /**
  * Executes an async operation with a timeout.
  * Throws LifecycleTimeoutError if the timeout is exceeded.
+ *
+ * `Infinity` runs the operation unbounded; values above the largest
+ * timer delay are clamped to it. NaN or a negative value rejects with a
+ * RangeError instead of arming a 1 ms timer.
  */
 export declare function withTimeout<T>(fn: () => Promise<T>, timeoutMs: number, componentId: string, phase: string): Promise<T>;
 /**

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -4,15 +4,24 @@
  * Async utilities for timeout, abort, and concurrency control.
  */
 import { LifecycleTimeoutError } from "@zudojs/errors";
+import { assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
 /**
  * Executes an async operation with a timeout.
  * Throws LifecycleTimeoutError if the timeout is exceeded.
+ *
+ * `Infinity` runs the operation unbounded; values above the largest
+ * timer delay are clamped to it. NaN or a negative value rejects with a
+ * RangeError instead of arming a 1 ms timer.
  */
 export async function withTimeout(fn, timeoutMs, componentId, phase) {
+    assertTimeoutBudget("timeout", timeoutMs);
+    if (!isBounded(timeoutMs)) {
+        return fn();
+    }
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => {
             reject(new LifecycleTimeoutError(componentId, phase, timeoutMs));
-        }, timeoutMs);
+        }, toTimerDelay(timeoutMs));
         // 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

package/dist/lifecycleInternal/index.d.ts

@@ -7,4 +7,5 @@ export { DependencyGraph } from "./dependencyGraph.core.js";
 export { topologicalSort, reverseTopologicalSort, } from "./topologicalSort.core.js";
 export type { TopologicalStage } from "./topologicalSort.core.js";
 export { withTimeout, withAbort, withConcurrency } from "./asyncUtils.core.js";
+export { MAX_TIMER_DELAY, assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycleInternal/index.js

@@ -6,4 +6,5 @@
 export { DependencyGraph } from "./dependencyGraph.core.js";
 export { topologicalSort, reverseTopologicalSort, } from "./topologicalSort.core.js";
 export { withTimeout, withAbort, withConcurrency } from "./asyncUtils.core.js";
+export { MAX_TIMER_DELAY, assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
 //# sourceMappingURL=index.js.map

package/dist/lifecycleInternal/timeoutBudget.core.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @zudojs/lifecycle/internal/timeout-budget
+ *
+ * Validation and normalisation for millisecond budgets handed to timers.
+ */
+/** Largest delay `setTimeout` can represent (2^31 - 1 ms). */
+export declare const MAX_TIMER_DELAY = 2147483647;
+/**
+ * Validates a millisecond budget.
+ *
+ * `Infinity` is accepted and means "no bound". NaN, negative values and
+ * non-numbers are rejected up front: `setTimeout` silently turns them
+ * (and `Infinity`) into a 1 ms timer, and `LifecycleTimeoutError`'s
+ * constructor then threw inside that timer callback, which crashed the
+ * process instead of failing the component.
+ *
+ * @param name - Option name, used in the error message.
+ * @param value - The budget to check.
+ * @throws RangeError when the value is not a non-negative number.
+ */
+export declare function assertTimeoutBudget(name: string, value: unknown): void;
+/**
+ * Whether a validated budget actually bounds anything.
+ */
+export declare function isBounded(value: number): boolean;
+/**
+ * Clamps a finite budget to what a timer can represent.
+ */
+export declare function toTimerDelay(value: number): number;
+//# sourceMappingURL=timeoutBudget.core.d.ts.map

package/dist/lifecycleInternal/timeoutBudget.core.js

@@ -0,0 +1,38 @@
+/**
+ * @zudojs/lifecycle/internal/timeout-budget
+ *
+ * Validation and normalisation for millisecond budgets handed to timers.
+ */
+/** Largest delay `setTimeout` can represent (2^31 - 1 ms). */
+export const MAX_TIMER_DELAY = 2_147_483_647;
+/**
+ * Validates a millisecond budget.
+ *
+ * `Infinity` is accepted and means "no bound". NaN, negative values and
+ * non-numbers are rejected up front: `setTimeout` silently turns them
+ * (and `Infinity`) into a 1 ms timer, and `LifecycleTimeoutError`'s
+ * constructor then threw inside that timer callback, which crashed the
+ * process instead of failing the component.
+ *
+ * @param name - Option name, used in the error message.
+ * @param value - The budget to check.
+ * @throws RangeError when the value is not a non-negative number.
+ */
+export function assertTimeoutBudget(name, value) {
+    if (typeof value !== "number" || Number.isNaN(value) || value < 0) {
+        throw new RangeError(`${name} must be a non-negative number of milliseconds (Infinity for no bound), got ${String(value)}.`);
+    }
+}
+/**
+ * Whether a validated budget actually bounds anything.
+ */
+export function isBounded(value) {
+    return Number.isFinite(value);
+}
+/**
+ * Clamps a finite budget to what a timer can represent.
+ */
+export function toTimerDelay(value) {
+    return Math.min(Math.max(0, value), MAX_TIMER_DELAY);
+}
+//# sourceMappingURL=timeoutBudget.core.js.map

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

@@ -13,9 +13,16 @@ import { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.j
 export interface LifecycleManagerOptions {
     /** Maximum concurrent component operations. */
     readonly concurrency?: number;
-    /** Global shutdown timeout in ms. */
+    /**
+     * Global shutdown timeout in ms. `Infinity` means no deadline; NaN
+     * and negative values are rejected by the constructor.
+     */
     readonly shutdownTimeout?: number;
-    /** Whether to automatically install signal handlers. */
+    /**
+     * Whether to install SIGINT/SIGTERM handlers. They are installed by
+     * `start()` (not the constructor) and removed once shutdown finishes,
+     * and a second signal during shutdown exits with code 1.
+     */
     readonly handleSignals?: boolean;
     /** Signals to listen for. */
     readonly signals?: readonly NodeJS.Signals[];
@@ -37,6 +44,8 @@ export declare class LifecycleManager {
     private readonly _ctx;
     private _startPromise?;
     private _removeSignalHandlers?;
+    private readonly _handleSignals;
+    private readonly _signals;
     constructor(options?: LifecycleManagerOptions);
     /** Registers a component with the lifecycle manager. */
     register(component: LifecycleComponent, options?: LifecycleRegistrationOptions): void;
@@ -50,6 +59,7 @@ export declare class LifecycleManager {
      * Idempotent — returns the same promise if called multiple times.
      */
     shutdown(): Promise<void>;
+    private releaseSignalHandlers;
     /** Returns the current application state. */
     get state(): LifecycleState;
     /** Returns the event emitter for lifecycle events. */

package/dist/lifecycleManager/lifecycleManager.core.js

@@ -12,6 +12,7 @@ import { LifecycleEventEmitter } from "../lifecycleEvents/lifecycleEvents.core.j
 import { installSignalHandlers } from "../lifecycleSignal/lifecycleSignal.handler.js";
 import { performStartup } from "./lifecycleManager.startup.js";
 import { performShutdown } from "./lifecycleManager.shutdown.js";
+import { assertTimeoutBudget } from "../lifecycleInternal/index.js";
 /**
  * Orchestrates application and component lifecycle.
  *
@@ -29,7 +30,12 @@ export class LifecycleManager {
     _ctx;
     _startPromise;
     _removeSignalHandlers;
+    _handleSignals;
+    _signals;
     constructor(options = {}) {
+        if (options.shutdownTimeout !== undefined) {
+            assertTimeoutBudget("shutdownTimeout", options.shutdownTimeout);
+        }
         this._ctx = {
             registry: new LifecycleRegistry(),
             state: new LifecycleStateMachine("application"),
@@ -43,14 +49,12 @@ export class LifecycleManager {
             startTime: 0,
             controller: new AbortController(),
         };
-        if (options.handleSignals !== false) {
-            this._removeSignalHandlers = installSignalHandlers({
-                signals: options.signals,
-                handler: () => {
-                    void this.shutdown();
-                },
-            });
-        }
+        // Installing in the constructor disabled Ctrl-C for the whole
+        // process as soon as a manager existed (tests, libraries), and the
+        // listener outlived shutdown, so a process with a leaked handle
+        // could no longer be interrupted.
+        this._handleSignals = options.handleSignals !== false;
+        this._signals = options.signals;
     }
     /** Registers a component with the lifecycle manager. */
     register(component, options = {}) {
@@ -70,7 +74,20 @@ export class LifecycleManager {
         if (this._startPromise) {
             return this._startPromise;
         }
-        this._startPromise = performStartup(this._ctx);
+        if (this._handleSignals && this._removeSignalHandlers === undefined) {
+            this._removeSignalHandlers = installSignalHandlers({
+                signals: this._signals,
+                handler: () => {
+                    void this.shutdown();
+                },
+            });
+        }
+        this._startPromise = performStartup(this._ctx).catch(async (error) => {
+            // A failed startup rolls back through the shared shutdown.
+            await this._ctx.shutdownPromise?.catch(() => undefined);
+            this.releaseSignalHandlers();
+            throw error;
+        });
         return this._startPromise;
     }
     /**
@@ -80,7 +97,16 @@ export class LifecycleManager {
     async shutdown() {
         // performShutdown is itself single-flight, so a shutdown started by
         // startup rollback and one started here are the SAME run.
-        return performShutdown(this._ctx);
+        try {
+            await performShutdown(this._ctx);
+        }
+        finally {
+            this.releaseSignalHandlers();
+        }
+    }
+    releaseSignalHandlers() {
+        this._removeSignalHandlers?.();
+        this._removeSignalHandlers = undefined;
     }
     /** Returns the current application state. */
     get state() {
@@ -112,8 +138,7 @@ export class LifecycleManager {
      * component teardown — call `shutdown()` first for that.
      */
     dispose() {
-        this._removeSignalHandlers?.();
-        this._removeSignalHandlers = undefined;
+        this.releaseSignalHandlers();
         this._ctx.events.clear();
     }
 }

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -6,6 +6,7 @@
 import { LifecyclePhase, LifecycleState } from "@zudojs/constants";
 import { buildExecutionPlan } from "../lifecyclePlan/lifecyclePlan.core.js";
 import { createLifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
+import { isBounded, toTimerDelay } from "../lifecycleInternal/index.js";
 import { emitComponentFailed, recordResult, transitionComponent, wasAttempted, } from "./lifecycleManager.context.js";
 /** Shutdown phases in execution order. */
 const SHUTDOWN_PHASES = [LifecyclePhase.STOP, LifecyclePhase.DISPOSE];
@@ -45,6 +46,9 @@ async function runShutdown(ctx) {
     if (ctx.inFlight !== undefined) {
         await raceDeadline(ctx, ctx.inFlight.then(() => undefined, () => undefined), Math.max(deadline - Date.now(), 1));
     }
+    // Hooks abandoned by a component timeout are still running; stopping
+    // their component now would overlap its own start().
+    await raceDeadline(ctx, ctx.executor.settleAbandoned(), 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
@@ -79,12 +83,19 @@ async function runShutdown(ctx) {
  * so it can never hold the event loop open.
  */
 async function raceDeadline(ctx, phase, remainingMs) {
+    // An unbounded budget (shutdownTimeout: Infinity) waits for the phase.
+    // Handing Infinity to setTimeout fired after 1 ms and abandoned every
+    // stop()/dispose() while reporting the application DISPOSED.
+    if (!isBounded(remainingMs)) {
+        await phase.catch(() => { });
+        return;
+    }
     let timer;
     const expiry = new Promise((resolve) => {
         timer = setTimeout(() => {
             ctx.controller.abort(new Error(`Lifecycle shutdown exceeded its ${ctx.shutdownTimeout}ms deadline.`));
             resolve();
-        }, remainingMs);
+        }, toTimerDelay(remainingMs));
     });
     try {
         await Promise.race([phase, expiry]);

package/dist/lifecycleRegistry/lifecycleRegistry.core.js

@@ -4,7 +4,7 @@
  * Lifecycle registry — manages component registration, validation, and lookup.
  */
 import { LIFECYCLE_DEFAULT_TIMEOUT } from "@zudojs/constants";
-import { DependencyGraph } from "../lifecycleInternal/index.js";
+import { DependencyGraph, assertTimeoutBudget, } from "../lifecycleInternal/index.js";
 /**
  * Registry for lifecycle components.
  * Validates registration, builds dependency graph, and freezes on demand.
@@ -19,6 +19,9 @@ export class LifecycleRegistry {
             throw new Error("Cannot register components after registry is frozen");
         }
         const id = options.id ?? component.name;
+        if (options.timeout !== undefined) {
+            assertTimeoutBudget(`Component "${id}" timeout`, options.timeout);
+        }
         if (this._registrations.has(id)) {
             throw new Error(`Component "${id}" is already registered`);
         }

package/dist/lifecycleSignal/lifecycleSignal.handler.d.ts

@@ -9,6 +9,15 @@ export interface SignalHandlerOptions {
     readonly signals?: readonly NodeJS.Signals[];
     /** Function to call when a signal is received. */
     readonly handler: () => void;
+    /**
+     * Whether a second signal, received while the first is still being
+     * handled, exits the process with code 1. Defaults to `true`: the
+     * installed listener replaces Node's default exit, so without this a
+     * wedged shutdown could not be interrupted short of SIGKILL.
+     */
+    readonly forceExitOnSecondSignal?: boolean;
+    /** Exit hook, injected for testing. Defaults to `process.exit`. */
+    readonly exit?: (code: number) => void;
 }
 /** Default signal configuration for graceful shutdown. */
 export declare const DEFAULT_SHUTDOWN_SIGNALS: readonly NodeJS.Signals[];

package/dist/lifecycleSignal/lifecycleSignal.handler.js

@@ -15,9 +15,18 @@ export function installSignalHandlers(options) {
     // changing the constant had no effect on the actual default.
     const signals = options.signals ?? DEFAULT_SHUTDOWN_SIGNALS;
     const handler = options.handler;
+    const forceExit = options.forceExitOnSecondSignal ?? true;
+    const exit = options.exit ?? ((code) => process.exit(code));
+    let received = false;
     const installed = [];
     for (const signal of signals) {
         const listener = () => {
+            if (received) {
+                if (forceExit)
+                    exit(1);
+                return;
+            }
+            received = true;
             handler();
         };
         process.on(signal, listener);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/lifecycle",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.",
   "license": "MIT",
   "author": {
@@ -24,8 +24,8 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1",
-    "@zudojs/constants": "1.0.1"
+    "@zudojs/errors": "1.1.0",
+    "@zudojs/constants": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.4.1",