@zudojs/lifecycle 1.2.3 → 1.3.0

package/README.md

@@ -60,9 +60,11 @@ 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.
+Rollback only undoes phases that were reached: `stop()` is called on
+components whose `start` completed (or timed out, so its outcome is
+unknown) — never on one whose `start()` threw — and `dispose()` on
+components whose `initialize` was invoked, even if it failed, because a
+half-initialised component may still hold resources.
 
 Calling `shutdown()` while `start()` is in flight waits for the
 executing stage to settle, tears down, and makes `start()` reject with a
@@ -78,7 +80,11 @@ failing startup and the process signal handler, all await the same run.
 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.
+awaited forever. Expiry is never silent: every component whose hook was
+still running is marked `FAILED` with a `LifecycleTimeoutError` result,
+one `application:shutdown-timeout` event is emitted (its `error` is the
+timeout), `manager.shutdownTimedOut` reads `true`, and nothing is
+emitted after `shutdown()` has resolved.
 
 Failing `stop()`/`dispose()` hooks are recorded: the component is marked
 `FAILED`, a `component:failed` event is emitted, and the result appears
@@ -86,9 +92,11 @@ 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:
+Every hook invocation receives a `LifecycleContext` whose `signal` is
+derived from the run: it is aborted when that component's `timeout`
+elapses and when the shutdown deadline expires. Long-running hooks
+should honour it — a `start()` that does is what lets `start()` reject
+at the component timeout instead of at the hook's own pace:
 
 ```typescript
 async stop(context) {
@@ -101,11 +109,19 @@ async stop(context) {
 `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`
+  `component:starting`, `component:started`, `component:readying`,
+  `component:ready`, `component:retrying`, `component:stopping`,
+  `component:stopped`, `component:disposing`, `component:disposed`,
+  `component:failed`
 - `application:initializing`, `application:initialized`,
-  `application:starting`, `application:ready`, `application:stopping`,
-  `application:stopped`, `application:disposed`
+  `application:starting`, `application:readying`, `application:ready`,
+  `application:stopping`, `application:shutdown-timeout`,
+  `application:stopped`, `application:disposing`, `application:disposed`
+
+Every phase has its own begin/end pair (the ready and dispose phases
+used to reuse `starting` and `stopping`/`stopped`). `component:retrying`
+carries `component.attempt` (1-based), `component.delay` (ms) and the
+`component.error` being retried.
 
 Listener exceptions are swallowed so observability never breaks the
 lifecycle.
@@ -134,10 +150,23 @@ stops first and the highest stops last.
 `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()`.
+`retry.attempts` is the number of retries after the first call, not the
+total (`attempts: 3` allows four invocations); `delay` defaults to 500 ms,
+`maxDelay` to 10 000 ms and `backoff` to `"exponential"` (doubling per
+retry, capped at `maxDelay`). `retry` covers hooks that throw; a hook that
+times out is not retried, because it is still running and a second call
+would overlap it. Its `context.signal` is aborted and it is tracked per
+component: before that component's `stop()`/`dispose()` the executor
+waits for it — a `stop()` that overran its timeout is a drain and is
+waited for until the shutdown deadline, a startup hook that ignored its
+timeout only for one more `timeout` — so hooks of one component never
+overlap and one hung `start()` no longer delays every other component's
+teardown.
+
+`DependencyGraph.addEdge` creates its endpoints, so a typo in a
+dependency id sorts as a leaf. `getUndeclaredNodes()` lists such nodes
+and `validate({ requireDeclared: true })` rejects them; the manager's
+registry already rejects an unknown `dependsOn` at `start()`.
 
 With `handleSignals`, SIGINT/SIGTERM listeners are installed by `start()`,
 not by the constructor, and removed once shutdown finishes. A second

package/dist/index.d.ts

@@ -28,15 +28,14 @@ export type { LifecycleContext } from "./lifecycleContext/index.js";
 export { createLifecycleContext } from "./lifecycleContext/index.js";
 export { LifecycleRegistry } from "./lifecycleRegistry/index.js";
 export { DependencyGraph, topologicalSort, reverseTopologicalSort, withTimeout, withAbort, withConcurrency, } from "./lifecycleInternal/index.js";
-export type { TopologicalStage } from "./lifecycleInternal/index.js";
+export type { DependencyGraphValidationOptions, TopologicalStage, } from "./lifecycleInternal/index.js";
 export { buildExecutionPlan } from "./lifecyclePlan/index.js";
 export type { ExecutionStage, ExecutionPlan } from "./lifecyclePlan/index.js";
 export { LifecycleExecutor } from "./lifecycleExecutor/index.js";
-export type { ExecutionResult } from "./lifecycleExecutor/index.js";
+export type { ExecutionResult, LifecycleExecutorOptions, LifecycleRetryNotice, } from "./lifecycleExecutor/index.js";
 export { LifecycleManager, createLifecycleManager, } from "./lifecycleManager/index.js";
 export type { LifecycleManagerOptions } from "./lifecycleManager/index.js";
 export { LifecycleEventEmitter } from "./lifecycleEvents/index.js";
 export type { LifecycleEventType, LifecycleComponentEvent, LifecycleApplicationEvent, LifecycleEvent, LifecycleEventListener, } from "./lifecycleEvents/index.js";
 export { installSignalHandlers, DEFAULT_SHUTDOWN_SIGNALS, } from "./lifecycleSignal/index.js";
 export type { SignalHandlerOptions } from "./lifecycleSignal/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -25,10 +25,16 @@ export { LifecycleStateMachine } from "./lifecycleState/index.js";
 export { STARTUP_PHASES, SHUTDOWN_PHASES, getPhaseHookName, getComponentMethod, } from "./lifecyclePhase/index.js";
 export { createLifecycleContext } from "./lifecycleContext/index.js";
 export { LifecycleRegistry } from "./lifecycleRegistry/index.js";
+/*
+ * Graph and async utilities. These live in the `lifecycleInternal`
+ * folder because the manager is their first consumer, but they are a
+ * supported part of the public API: `DependencyGraph` and the sorts
+ * are what `buildExecutionPlan` is built on, and `withTimeout` /
+ * `withAbort` / `withConcurrency` are reusable outside the manager.
+ */
 export { DependencyGraph, topologicalSort, reverseTopologicalSort, withTimeout, withAbort, withConcurrency, } from "./lifecycleInternal/index.js";
 export { buildExecutionPlan } from "./lifecyclePlan/index.js";
 export { LifecycleExecutor } from "./lifecycleExecutor/index.js";
 export { LifecycleManager, createLifecycleManager, } from "./lifecycleManager/index.js";
 export { LifecycleEventEmitter } from "./lifecycleEvents/index.js";
 export { installSignalHandlers, DEFAULT_SHUTDOWN_SIGNALS, } from "./lifecycleSignal/index.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleComponent/index.d.ts

@@ -4,4 +4,3 @@
  * Lifecycle component interface and registration types.
  */
 export type { LifecycleComponent, LifecycleRegistrationOptions, LifecycleRetryOptions, LifecycleRegistration, } from "./lifecycleComponent.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycleComponent/index.js

@@ -4,4 +4,3 @@
  * Lifecycle component interface and registration types.
  */
 export {};
-//# sourceMappingURL=index.js.map

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

@@ -40,22 +40,42 @@ export interface LifecycleRegistrationOptions {
     /** If true, application startup fails when this component fails. Defaults to true. */
     readonly critical?: boolean;
     /**
-     * Timeout in ms for individual component operations. `Infinity` means
-     * no bound; NaN and negative values are rejected at registration.
+     * Timeout in ms for each hook invocation. Defaults to
+     * `LIFECYCLE_DEFAULT_TIMEOUT` (30 s). `Infinity` means no bound; NaN
+     * and negative values are rejected at registration.
+     *
+     * When it elapses the hook's `context.signal` is aborted, the hook is
+     * recorded as failed with `timedOut: true` and is never retried, and
+     * startup rolls back. The same budget bounds the wait, before this
+     * component's `stop()`/`dispose()`, for an earlier hook of this
+     * component that is still running after its own timeout.
      */
     readonly timeout?: number;
     /** Retry configuration for failed operations. */
     readonly retry?: LifecycleRetryOptions;
 }
-/** Retry options for component operations. */
+/**
+ * Retry options for component operations.
+ *
+ * Retries apply to every phase hook. A hook that threw (or rejected)
+ * is retried after a delay; a hook that exceeded `timeout` is never
+ * retried, because it is still running and cannot be cancelled. Each
+ * retry is announced through the `component:retrying` event.
+ */
 export interface LifecycleRetryOptions {
-    /** Maximum number of retry attempts. */
+    /**
+     * Number of retries after the first call, not the total number of
+     * calls: `attempts: 3` allows up to four invocations. Defaults to 0.
+     */
     readonly attempts?: number;
-    /** Delay between retries in ms. */
+    /** Delay before the first retry in ms. Defaults to 500. */
     readonly delay?: number;
-    /** Maximum delay between retries in ms. */
+    /** Cap on the delay between retries in ms. Defaults to 10 000. */
     readonly maxDelay?: number;
-    /** Backoff strategy. */
+    /**
+     * Backoff strategy. `"exponential"` (the default) doubles `delay` on
+     * every retry up to `maxDelay`; `"fixed"` waits `delay` each time.
+     */
     readonly backoff?: "fixed" | "exponential";
 }
 /** A component with its registration metadata. */
@@ -75,4 +95,3 @@ export interface LifecycleRegistration {
     /** Retry configuration. */
     readonly retry: LifecycleRetryOptions;
 }
-//# sourceMappingURL=lifecycleComponent.type.d.ts.map

package/dist/lifecycleComponent/lifecycleComponent.type.js

@@ -4,4 +4,3 @@
  * Lifecycle component interface — the contract for managed resources.
  */
 export {};
-//# sourceMappingURL=lifecycleComponent.type.js.map

package/dist/lifecycleContext/index.d.ts

@@ -5,4 +5,3 @@
  */
 export type { LifecycleContext } from "./lifecycleContext.type.js";
 export { createLifecycleContext } from "./lifecycleContext.type.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycleContext/index.js

@@ -4,4 +4,3 @@
  * Lifecycle context type and factory.
  */
 export { createLifecycleContext } from "./lifecycleContext.type.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleContext/lifecycleContext.type.d.ts

@@ -20,4 +20,3 @@ export interface LifecycleContext {
 }
 /** Creates a lifecycle context. */
 export declare function createLifecycleContext(phase: LifecyclePhase, startedAt: number, signal?: AbortSignal, metadata?: Record<string, unknown>): LifecycleContext;
-//# sourceMappingURL=lifecycleContext.type.d.ts.map

package/dist/lifecycleContext/lifecycleContext.type.js

@@ -12,4 +12,3 @@ export function createLifecycleContext(phase, startedAt, signal, metadata) {
         metadata: new Map(Object.entries(metadata ?? {})),
     };
 }
-//# sourceMappingURL=lifecycleContext.type.js.map

package/dist/lifecycleEvents/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { LifecycleEventEmitter } from "./lifecycleEvents.core.js";
 export type { LifecycleEventType, LifecycleComponentEvent, LifecycleApplicationEvent, LifecycleEvent, LifecycleEventListener, } from "./lifecycleEvents.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/lifecycleEvents/index.js

@@ -4,4 +4,3 @@
  * Lifecycle event emitter for observability integration.
  */
 export { LifecycleEventEmitter } from "./lifecycleEvents.core.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleEvents/lifecycleEvents.core.d.ts

@@ -3,16 +3,28 @@
  *
  * Lifecycle event emitter — emits typed events for observability integration.
  */
-/** Lifecycle event types. */
-export type LifecycleEventType = "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";
+/**
+ * Lifecycle event types.
+ *
+ * Every phase has its own begin/end pair: the ready phase emits
+ * `component:readying` / `component:ready` and the dispose phase
+ * `component:disposing` / `component:disposed`. They used to reuse
+ * `component:starting` and `component:stopping`/`component:stopped`,
+ * so a listener could not tell the phases apart.
+ */
+export type LifecycleEventType = "component:registered" | "component:initializing" | "component:initialized" | "component:starting" | "component:started" | "component:readying" | "component:ready" | "component:retrying" | "component:stopping" | "component:stopped" | "component:disposing" | "component:disposed" | "component:failed" | "application:initializing" | "application:initialized" | "application:starting" | "application:readying" | "application:ready" | "application:stopping" | "application:shutdown-timeout" | "application:stopped" | "application:disposing" | "application:disposed";
 /** Event payload for component events. */
 export interface LifecycleComponentEvent {
     /** Component ID. */
     readonly componentId: string;
     /** Duration in ms (for completion events). */
     readonly duration?: number;
-    /** Error if the event represents a failure. */
+    /** Error if the event represents a failure (or the error being retried). */
     readonly error?: unknown;
+    /** 1-based retry number (`component:retrying` only). */
+    readonly attempt?: number;
+    /** Milliseconds until that retry runs (`component:retrying` only). */
+    readonly delay?: number;
 }
 /** Event payload for application events. */
 export interface LifecycleApplicationEvent {
@@ -29,7 +41,11 @@ export interface LifecycleEvent {
     readonly component?: LifecycleComponentEvent;
     /** Duration in ms (for completion events). */
     readonly duration?: number;
-    /** Error if the event represents a failure. */
+    /**
+     * Error if the event represents a failure. For
+     * `application:shutdown-timeout` this is the LifecycleTimeoutError
+     * describing the expired deadline.
+     */
     readonly error?: unknown;
     /** Timestamp. */
     readonly timestamp: number;
@@ -49,4 +65,3 @@ export declare class LifecycleEventEmitter {
     /** Removes all listeners. */
     clear(): void;
 }
-//# sourceMappingURL=lifecycleEvents.core.d.ts.map

package/dist/lifecycleEvents/lifecycleEvents.core.js

@@ -43,4 +43,3 @@ export class LifecycleEventEmitter {
         this._listeners.clear();
     }
 }
-//# sourceMappingURL=lifecycleEvents.core.js.map

package/dist/lifecycleExecutor/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * @zudojs/lifecycle/executor
  *
- * Lifecycle executor — runs component hooks with timeout, retry, and concurrency.
+ * Runs component hooks with timeout, retry, per-invocation
+ * cancellation, and priority-aware concurrency.
  */
 export { LifecycleExecutor } from "./lifecycleExecutor.core.js";
-export type { ExecutionResult } from "./lifecycleExecutor.core.js";
-//# sourceMappingURL=index.d.ts.map
+export type { ExecutionResult, LifecycleExecutorOptions, LifecycleRetryNotice, } from "./lifecycleExecutor.type.js";

package/dist/lifecycleExecutor/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/lifecycle/executor
  *
- * Lifecycle executor — runs component hooks with timeout, retry, and concurrency.
+ * Runs component hooks with timeout, retry, per-invocation
+ * cancellation, and priority-aware concurrency.
  */
 export { LifecycleExecutor } from "./lifecycleExecutor.core.js";
-//# sourceMappingURL=index.js.map

package/dist/lifecycleExecutor/lifecycleExecutor.abandoned.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @zudojs/lifecycle/executor/abandoned
+ *
+ * Tracks hook invocations that outlived their timeout.
+ */
+import { LifecyclePhase } from "@zudojs/constants";
+/** Predicate over the phase of an abandoned hook. */
+export type PhaseFilter = (phase: LifecyclePhase) => boolean;
+/** True for `stop` and `dispose`. */
+export declare function isShutdownPhase(phase: LifecyclePhase): boolean;
+/** True for `initialize`, `start` and `ready`. */
+export declare function isStartupPhase(phase: LifecyclePhase): boolean;
+/**
+ * Registry of hooks that are still running after their timeout fired.
+ *
+ * A timed-out hook cannot be cancelled, only abandoned. It is kept
+ * here, per component, so that the component's next hook can wait for
+ * it instead of overlapping it (three `listen()` calls on one port).
+ */
+export declare class AbandonedHooks {
+    private readonly byComponent;
+    /** Starts tracking an invocation; it is forgotten once it settles. */
+    track(id: string, phase: LifecyclePhase, invocation: Promise<unknown>): void;
+    /** Pending invocations of one component (or all), optionally by phase. */
+    pending(id?: string, filter?: PhaseFilter): readonly Promise<unknown>[];
+    /**
+     * Resolves once the selected invocations have settled, or as soon as
+     * `signal` aborts (the shutdown deadline), whichever comes first.
+     */
+    settle(id?: string, filter?: PhaseFilter, signal?: AbortSignal): Promise<void>;
+}

package/dist/lifecycleExecutor/lifecycleExecutor.abandoned.js

@@ -0,0 +1,75 @@
+/**
+ * @zudojs/lifecycle/executor/abandoned
+ *
+ * Tracks hook invocations that outlived their timeout.
+ */
+import { LifecyclePhase } from "@zudojs/constants";
+/** True for `stop` and `dispose`. */
+export function isShutdownPhase(phase) {
+    return phase === LifecyclePhase.STOP || phase === LifecyclePhase.DISPOSE;
+}
+/** True for `initialize`, `start` and `ready`. */
+export function isStartupPhase(phase) {
+    return !isShutdownPhase(phase);
+}
+/**
+ * Registry of hooks that are still running after their timeout fired.
+ *
+ * A timed-out hook cannot be cancelled, only abandoned. It is kept
+ * here, per component, so that the component's next hook can wait for
+ * it instead of overlapping it (three `listen()` calls on one port).
+ */
+export class AbandonedHooks {
+    byComponent = new Map();
+    /** Starts tracking an invocation; it is forgotten once it settles. */
+    track(id, phase, invocation) {
+        const hook = {
+            phase,
+            settled: invocation.catch(() => undefined),
+        };
+        const set = this.byComponent.get(id) ?? new Set();
+        set.add(hook);
+        this.byComponent.set(id, set);
+        void hook.settled.finally(() => {
+            set.delete(hook);
+            if (set.size === 0 && this.byComponent.get(id) === set) {
+                this.byComponent.delete(id);
+            }
+        });
+    }
+    /** Pending invocations of one component (or all), optionally by phase. */
+    pending(id, filter) {
+        const sets = id === undefined
+            ? [...this.byComponent.values()]
+            : [this.byComponent.get(id) ?? new Set()];
+        return sets
+            .flatMap((set) => [...set])
+            .filter((hook) => filter?.(hook.phase) ?? true)
+            .map((hook) => hook.settled);
+    }
+    /**
+     * Resolves once the selected invocations have settled, or as soon as
+     * `signal` aborts (the shutdown deadline), whichever comes first.
+     */
+    async settle(id, filter, signal) {
+        for (;;) {
+            const pending = this.pending(id, filter);
+            if (pending.length === 0 || signal?.aborted)
+                return;
+            await raceAbort(Promise.allSettled(pending), signal);
+        }
+    }
+}
+function raceAbort(work, signal) {
+    if (signal === undefined) {
+        return work.then(() => undefined);
+    }
+    return new Promise((resolve) => {
+        const done = () => {
+            signal.removeEventListener("abort", done);
+            resolve();
+        };
+        signal.addEventListener("abort", done, { once: true });
+        void work.then(done, done);
+    });
+}

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

@@ -6,32 +6,28 @@
 import type { LifecyclePhase } from "@zudojs/constants";
 import type { LifecycleRegistration } from "../lifecycleComponent/lifecycleComponent.type.js";
 import type { LifecycleContext } from "../lifecycleContext/lifecycleContext.type.js";
-/** Result of executing a component hook. */
-export interface ExecutionResult {
-    /** Component ID. */
-    readonly id: string;
-    /** The phase that was executed. */
-    readonly phase: LifecyclePhase;
-    /** Duration in ms. */
-    readonly duration: number;
-    /** Error if the hook failed. */
-    readonly error?: unknown;
-    /** Whether the operation succeeded. */
-    readonly success: boolean;
-}
+import type { ExecutionResult, LifecycleExecutorOptions } from "./lifecycleExecutor.type.js";
 /**
  * Executes lifecycle component hooks with timeout, retry, and concurrency support.
+ *
+ * Every invocation gets its own AbortSignal, derived from the run
+ * signal and aborted when the component's `timeout` elapses, so a hook
+ * that honours `context.signal` unwinds promptly. One that ignores it
+ * keeps running and is tracked per component: before that component's
+ * `stop()`/`dispose()` the executor waits for it — a drain that overran
+ * its stop timeout is waited for until the global deadline, a startup
+ * hook that ignored its timeout only for one more `timeout` — so hooks
+ * of one component never overlap.
  */
 export declare class LifecycleExecutor {
-    /** Hook invocations still running after their timeout fired. */
     private readonly abandoned;
+    private readonly onRetry;
+    constructor(options?: LifecycleExecutorOptions);
     /**
-     * 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.
+     * Resolves once every hook abandoned by a timeout has settled — those
+     * of one component when `id` is given, otherwise all of them.
      */
-    settleAbandoned(): Promise<void>;
+    settleAbandoned(id?: string): Promise<void>;
     /**
      * Executes a single component hook.
      */
@@ -42,11 +38,9 @@ export declare class LifecycleExecutor {
      * The stage arrives already ordered by priority (descending for
      * startup, ascending for shutdown). Components sharing a priority run
      * together, limited by `concurrency`; the next priority group only
-     * begins once the previous one has settled. Launching the whole stage
-     * concurrently made `priority` observable only at `concurrency: 1`,
-     * so a `priority: 100` component documented as starting first lost
-     * the race to any sibling with a faster hook.
+     * begins once the previous one has settled.
      */
     executeStage(registrations: readonly LifecycleRegistration[], phase: LifecyclePhase, context: LifecycleContext, concurrency: number): Promise<readonly ExecutionResult[]>;
+    private invoke;
+    private notifyRetry;
 }
-//# sourceMappingURL=lifecycleExecutor.core.d.ts.map