@zudojs/lifecycle 1.2.2 → 1.3.0

package/dist/lifecycleExecutor/lifecycleExecutor.core.js

@@ -6,93 +6,90 @@
 import { withTimeout, withConcurrency } from "../lifecycleInternal/index.js";
 import { getComponentMethod } from "../lifecyclePhase/index.js";
 import { LifecycleComponentError, LifecycleTimeoutError, } from "@zudojs/errors";
+import { AbandonedHooks, isShutdownPhase, isStartupPhase, } from "./lifecycleExecutor.abandoned.js";
+import { calculateDelay, groupByPriority, sleep } from "./lifecycleExecutor.retry.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 class LifecycleExecutor {
-    /** Hook invocations still running after their timeout fired. */
-    abandoned = new Set();
+    abandoned = new AbandonedHooks();
+    onRetry;
+    constructor(options = {}) {
+        this.onRetry = options.onRetry;
+    }
     /**
-     * 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.
      */
-    async settleAbandoned() {
-        while (this.abandoned.size > 0) {
-            await Promise.allSettled([...this.abandoned]);
-        }
+    settleAbandoned(id) {
+        return this.abandoned.settle(id);
     }
     /**
      * Executes a single component hook.
      */
     async execute(registration, phase, context) {
-        const methodName = getComponentMethod(phase);
-        const hook = registration.component[methodName];
+        const { id } = registration;
+        const hook = registration.component[getComponentMethod(phase)];
         if (typeof hook !== "function") {
-            return {
-                id: registration.id,
-                phase,
-                duration: 0,
-                success: true,
-            };
+            return { id, phase, duration: 0, success: true };
+        }
+        if (isShutdownPhase(phase)) {
+            await this.abandoned.settle(id, isShutdownPhase, context.signal);
         }
         const startTime = Date.now();
+        const maxAttempts = 1 + (registration.retry.attempts ?? 0);
         let lastError;
-        const retryConfig = registration.retry;
-        const maxAttempts = 1 + (retryConfig.attempts ?? 0);
+        let timedOut = false;
         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);
+                lastError ??= new LifecycleComponentError(id, phase, context.signal.reason);
                 break;
             }
+            const controller = new AbortController();
             let invocation;
             try {
                 await withTimeout(() => {
-                    invocation = (async () => {
-                        await hook.call(registration.component, context);
-                    })();
+                    invocation = this.invoke(registration, phase, hook, {
+                        ...context,
+                        signal: AbortSignal.any([context.signal, controller.signal]),
+                    });
                     return invocation;
-                }, registration.timeout, registration.id, phase);
-                return {
-                    id: registration.id,
-                    phase,
-                    duration: Date.now() - startTime,
-                    success: true,
-                };
+                }, registration.timeout, id, phase);
+                return { id, phase, duration: Date.now() - startTime, success: true };
             }
             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));
+                    timedOut = true;
+                    controller.abort(error);
+                    this.abandoned.track(id, phase, invocation);
                     break;
                 }
                 if (attempt < maxAttempts - 1) {
-                    const delay = calculateDelay(retryConfig, attempt);
+                    const delay = calculateDelay(registration.retry, attempt);
+                    this.notifyRetry({ id, phase, attempt: attempt + 1, delay, error });
                     await sleep(delay, context.signal);
                 }
             }
         }
         return {
-            id: registration.id,
+            id,
             phase,
             duration: Date.now() - startTime,
-            // 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),
+                : new LifecycleComponentError(id, phase, lastError),
             success: false,
+            ...(timedOut && { timedOut: true }),
         };
     }
     /**
@@ -101,75 +98,37 @@ export 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.
      */
     async executeStage(registrations, phase, context, concurrency) {
         const results = [];
         for (const batch of groupByPriority(registrations)) {
             await withConcurrency(batch, concurrency, async (reg) => {
-                const result = await this.execute(reg, phase, context);
-                results.push(result);
+                results.push(await this.execute(reg, phase, context));
             });
         }
         return results;
     }
-}
-/**
- * Splits an already-ordered stage into runs of equal priority.
- *
- * Consecutive grouping preserves whatever order the execution plan
- * produced, so a caller that does not care about priority (every
- * component at the default 0) still gets a single fully concurrent
- * batch.
- */
-function groupByPriority(registrations) {
-    const batches = [];
-    let current;
-    let currentPriority;
-    for (const reg of registrations) {
-        if (current === undefined || reg.priority !== currentPriority) {
-            current = [];
-            currentPriority = reg.priority;
-            batches.push(current);
+    async invoke(registration, phase, hook, context) {
+        if (isShutdownPhase(phase)) {
+            await this.abandoned.settle(registration.id, isStartupPhase, context.signal);
+            // The wait was cut short by the component timeout (or the run
+            // deadline): the earlier hook is still running, so this one must
+            // not start on top of it.
+            if (context.signal.aborted) {
+                throw context.signal.reason instanceof Error
+                    ? context.signal.reason
+                    : new LifecycleComponentError(registration.id, phase, context.signal.reason);
+            }
         }
-        current.push(reg);
+        await hook.call(registration.component, context);
     }
-    return batches;
-}
-/** Calculates retry delay with backoff. */
-function calculateDelay(config, attempt) {
-    const base = config.delay ?? 500;
-    const max = config.maxDelay ?? 10_000;
-    const backoff = config.backoff ?? "exponential";
-    if (backoff === "exponential") {
-        return Math.min(base * 2 ** attempt, max);
-    }
-    return base;
-}
-/**
- * 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;
+    notifyRetry(notice) {
+        try {
+            this.onRetry?.(notice);
         }
-        const timer = setTimeout(() => {
-            signal.removeEventListener("abort", onAbort);
-            resolve();
-        }, ms);
-        function onAbort() {
-            clearTimeout(timer);
-            resolve();
+        catch {
+            // A listener must not break the retry loop.
         }
-        signal.addEventListener("abort", onAbort, { once: true });
-    });
+    }
 }
-//# sourceMappingURL=lifecycleExecutor.core.js.map

package/dist/lifecycleExecutor/lifecycleExecutor.retry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @zudojs/lifecycle/executor/retry
+ *
+ * Retry delay, cancellable sleep and priority batching for the executor.
+ */
+import type { LifecycleRegistration, LifecycleRetryOptions } from "../lifecycleComponent/lifecycleComponent.type.js";
+/**
+ * Calculates the delay before retry number `attempt + 1`.
+ *
+ * `attempt` is 0 for the first retry. Exponential backoff doubles the
+ * base delay per retry and is capped at `maxDelay`; fixed backoff
+ * always waits `delay`.
+ */
+export declare function calculateDelay(config: LifecycleRetryOptions, attempt: number): number;
+/**
+ * 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.
+ */
+export declare function sleep(ms: number, signal: AbortSignal): Promise<void>;
+/**
+ * Splits an already-ordered stage into runs of equal priority.
+ *
+ * Consecutive grouping preserves whatever order the execution plan
+ * produced, so a caller that does not care about priority (every
+ * component at the default 0) still gets a single fully concurrent
+ * batch.
+ */
+export declare function groupByPriority(registrations: readonly LifecycleRegistration[]): readonly (readonly LifecycleRegistration[])[];

package/dist/lifecycleExecutor/lifecycleExecutor.retry.js

@@ -0,0 +1,66 @@
+/**
+ * @zudojs/lifecycle/executor/retry
+ *
+ * Retry delay, cancellable sleep and priority batching for the executor.
+ */
+/**
+ * Calculates the delay before retry number `attempt + 1`.
+ *
+ * `attempt` is 0 for the first retry. Exponential backoff doubles the
+ * base delay per retry and is capped at `maxDelay`; fixed backoff
+ * always waits `delay`.
+ */
+export function calculateDelay(config, attempt) {
+    const base = config.delay ?? 500;
+    const max = config.maxDelay ?? 10_000;
+    const backoff = config.backoff ?? "exponential";
+    if (backoff === "exponential") {
+        return Math.min(base * 2 ** attempt, max);
+    }
+    return base;
+}
+/**
+ * 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.
+ */
+export 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 });
+    });
+}
+/**
+ * Splits an already-ordered stage into runs of equal priority.
+ *
+ * Consecutive grouping preserves whatever order the execution plan
+ * produced, so a caller that does not care about priority (every
+ * component at the default 0) still gets a single fully concurrent
+ * batch.
+ */
+export function groupByPriority(registrations) {
+    const batches = [];
+    let current;
+    let currentPriority;
+    for (const reg of registrations) {
+        if (current === undefined || reg.priority !== currentPriority) {
+            current = [];
+            currentPriority = reg.priority;
+            batches.push(current);
+        }
+        current.push(reg);
+    }
+    return batches;
+}

package/dist/lifecycleExecutor/lifecycleExecutor.type.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @zudojs/lifecycle/executor/types
+ *
+ * Result and option types for the lifecycle executor.
+ */
+import type { LifecyclePhase } from "@zudojs/constants";
+/** 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;
+    /**
+     * True when the operation exceeded the component's `timeout`.
+     *
+     * For a startup phase that is the hook itself; for `stop`/`dispose`
+     * it also covers the wait for the component's own earlier hook that
+     * is still running after its timeout. A timed-out hook keeps running
+     * (it cannot be cancelled), is never retried, and is tracked so the
+     * component's next hook does not overlap it.
+     */
+    readonly timedOut?: boolean;
+}
+/** Details of a retry the executor is about to perform. */
+export interface LifecycleRetryNotice {
+    /** Component ID. */
+    readonly id: string;
+    /** The phase being retried. */
+    readonly phase: LifecyclePhase;
+    /** 1-based number of the retry about to run (1 = first retry). */
+    readonly attempt: number;
+    /** Milliseconds the executor waits before that retry. */
+    readonly delay: number;
+    /** The error that triggered the retry. */
+    readonly error: unknown;
+}
+/** Options for creating a lifecycle executor. */
+export interface LifecycleExecutorOptions {
+    /**
+     * Called before each retry delay. The lifecycle manager forwards it
+     * as the `component:retrying` event. Exceptions are swallowed.
+     */
+    readonly onRetry?: (notice: LifecycleRetryNotice) => void;
+}

package/dist/lifecycleExecutor/lifecycleExecutor.type.js

@@ -0,0 +1,6 @@
+/**
+ * @zudojs/lifecycle/executor/types
+ *
+ * Result and option types for the lifecycle executor.
+ */
+export {};

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

@@ -20,4 +20,3 @@ export declare function withAbort<T>(fn: (signal: AbortSignal) => Promise<T>, si
  * Executes async operations with a concurrency limit.
  */
 export declare function withConcurrency<T>(items: readonly T[], concurrency: number, fn: (item: T, index: number) => Promise<void>): Promise<void>;
-//# sourceMappingURL=asyncUtils.core.d.ts.map

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -125,4 +125,3 @@ export async function withConcurrency(items, concurrency, fn) {
         throw firstError;
     }
 }
-//# sourceMappingURL=asyncUtils.core.js.map

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

@@ -3,27 +3,54 @@
  *
  * Directed acyclic graph for component dependency tracking.
  */
+/** Options for {@link DependencyGraph.validate}. */
+export interface DependencyGraphValidationOptions {
+    /**
+     * Also reject nodes that only appear as an edge endpoint and were
+     * never passed to `addNode`. Off by default, because `addEdge` has
+     * always created its endpoints; turn it on when the node set is
+     * known up front (the registry does its own equivalent check on
+     * `dependsOn` and names the missing registration).
+     */
+    readonly requireDeclared?: boolean;
+}
 /**
  * A directed acyclic graph of component dependencies.
+ *
+ * `addEdge` creates any endpoint it has not seen, so an undeclared
+ * node (a typo in a dependency id, say) sorts as a leaf in the first
+ * stage. The graph remembers which nodes were declared with `addNode`:
+ * inspect them with `getUndeclaredNodes()` or reject them with
+ * `validate({ requireDeclared: true })`.
  */
 export declare class DependencyGraph {
     private readonly _edges;
     private readonly _reverseEdges;
-    /** Adds a node to the graph. */
+    private readonly _declared;
+    /** Declares a node in the graph. */
     addNode(id: string): void;
     /** Adds a directed edge: from depends on to. */
     addEdge(from: string, to: string): void;
-    /** Returns all nodes. */
+    /** Returns all nodes, declared or not, in insertion order. */
     getNodes(): readonly string[];
     /** Returns the nodes that the given node depends on. */
     getDependencies(id: string): readonly string[];
     /** Returns the nodes that depend on the given node. */
     getDependents(id: string): readonly string[];
+    /** Returns the nodes referenced by an edge but never passed to `addNode`. */
+    getUndeclaredNodes(): readonly string[];
+    /**
+     * Validates that the graph has no circular dependencies, throwing
+     * LifecycleDependencyError with the cycle path if one is found. With
+     * `requireDeclared` it first throws LifecycleError
+     * (LIFECYCLE_DEPENDENCY) for an edge to a node that was never added.
+     */
+    validate(options?: DependencyGraphValidationOptions): void;
     /**
-     * Validates that the graph has no circular dependencies.
-     * Throws LifecycleDependencyError with the cycle path if found.
+     * Returns one dependency cycle as a closed path (first id repeated
+     * last), or undefined when the graph is acyclic.
      */
-    validate(): void;
-    private _detectCycle;
+    findCycle(): readonly string[] | undefined;
+    private ensureNode;
+    private assertDeclared;
 }
-//# sourceMappingURL=dependencyGraph.core.d.ts.map

package/dist/lifecycleInternal/dependencyGraph.core.js

@@ -3,30 +3,34 @@
  *
  * Directed acyclic graph for component dependency tracking.
  */
-import { LifecycleDependencyError } from "@zudojs/errors";
+import { ErrorCode, LifecycleDependencyError, LifecycleError, } from "@zudojs/errors";
+import { findDependencyCycle } from "./dependencyGraph.cycle.js";
 /**
  * A directed acyclic graph of component dependencies.
+ *
+ * `addEdge` creates any endpoint it has not seen, so an undeclared
+ * node (a typo in a dependency id, say) sorts as a leaf in the first
+ * stage. The graph remembers which nodes were declared with `addNode`:
+ * inspect them with `getUndeclaredNodes()` or reject them with
+ * `validate({ requireDeclared: true })`.
  */
 export class DependencyGraph {
     _edges = new Map();
     _reverseEdges = new Map();
-    /** Adds a node to the graph. */
+    _declared = new Set();
+    /** Declares a node in the graph. */
     addNode(id) {
-        if (!this._edges.has(id)) {
-            this._edges.set(id, new Set());
-        }
-        if (!this._reverseEdges.has(id)) {
-            this._reverseEdges.set(id, new Set());
-        }
+        this._declared.add(id);
+        this.ensureNode(id);
     }
     /** Adds a directed edge: from depends on to. */
     addEdge(from, to) {
-        this.addNode(from);
-        this.addNode(to);
+        this.ensureNode(from);
+        this.ensureNode(to);
         this._edges.get(from).add(to);
         this._reverseEdges.get(to).add(from);
     }
-    /** Returns all nodes. */
+    /** Returns all nodes, declared or not, in insertion order. */
     getNodes() {
         return [...this._edges.keys()];
     }
@@ -38,37 +42,50 @@ export class DependencyGraph {
     getDependents(id) {
         return [...(this._reverseEdges.get(id) ?? [])];
     }
+    /** Returns the nodes referenced by an edge but never passed to `addNode`. */
+    getUndeclaredNodes() {
+        return this.getNodes().filter((id) => !this._declared.has(id));
+    }
     /**
-     * Validates that the graph has no circular dependencies.
-     * Throws LifecycleDependencyError with the cycle path if found.
+     * Validates that the graph has no circular dependencies, throwing
+     * LifecycleDependencyError with the cycle path if one is found. With
+     * `requireDeclared` it first throws LifecycleError
+     * (LIFECYCLE_DEPENDENCY) for an edge to a node that was never added.
      */
-    validate() {
-        const visited = new Set();
-        const inStack = new Set();
-        const path = [];
-        for (const node of this._edges.keys()) {
-            if (!visited.has(node)) {
-                this._detectCycle(node, visited, inStack, path);
-            }
+    validate(options = {}) {
+        if (options.requireDeclared === true) {
+            this.assertDeclared();
+        }
+        const cycle = this.findCycle();
+        if (cycle !== undefined) {
+            throw new LifecycleDependencyError(cycle);
         }
     }
-    _detectCycle(node, visited, inStack, path) {
-        visited.add(node);
-        inStack.add(node);
-        path.push(node);
-        const deps = this._edges.get(node) ?? new Set();
-        for (const dep of deps) {
-            if (inStack.has(dep)) {
-                const cycleStart = path.indexOf(dep);
-                const cycle = [...path.slice(cycleStart), dep];
-                throw new LifecycleDependencyError(cycle);
-            }
-            if (!visited.has(dep)) {
-                this._detectCycle(dep, visited, inStack, path);
-            }
+    /**
+     * Returns one dependency cycle as a closed path (first id repeated
+     * last), or undefined when the graph is acyclic.
+     */
+    findCycle() {
+        return findDependencyCycle(this);
+    }
+    ensureNode(id) {
+        if (!this._edges.has(id)) {
+            this._edges.set(id, new Set());
         }
-        path.pop();
-        inStack.delete(node);
+        if (!this._reverseEdges.has(id)) {
+            this._reverseEdges.set(id, new Set());
+        }
+    }
+    assertDeclared() {
+        const undeclared = this.getUndeclaredNodes();
+        const missing = undeclared[0];
+        if (missing === undefined)
+            return;
+        const dependent = this.getDependents(missing)[0];
+        throw new LifecycleError(`Component "${dependent ?? missing}" depends on "${missing}" which was never added to the graph.`, {
+            code: ErrorCode.LIFECYCLE_DEPENDENCY,
+            componentId: dependent,
+            metadata: { dependency: missing, undeclared },
+        });
     }
 }
-//# sourceMappingURL=dependencyGraph.core.js.map

package/dist/lifecycleInternal/dependencyGraph.cycle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @zudojs/lifecycle/internal/dependency-graph/cycle
+ *
+ * Iterative cycle search over a dependency graph.
+ */
+/** The part of a graph the search needs. */
+export interface CycleSearchGraph {
+    getNodes(): readonly string[];
+    getDependencies(id: string): readonly string[];
+}
+/**
+ * Returns one dependency cycle as a closed path (first id repeated
+ * last), or undefined when the graph is acyclic.
+ *
+ * The search is iterative so a very deep graph cannot overflow the
+ * call stack, and it reports the actual loop: the topological sort
+ * used to list every node that was still blocked, which for one
+ * three-node loop meant naming the whole application.
+ */
+export declare function findDependencyCycle(graph: CycleSearchGraph): readonly string[] | undefined;

package/dist/lifecycleInternal/dependencyGraph.cycle.js

@@ -0,0 +1,57 @@
+/**
+ * @zudojs/lifecycle/internal/dependency-graph/cycle
+ *
+ * Iterative cycle search over a dependency graph.
+ */
+/**
+ * Returns one dependency cycle as a closed path (first id repeated
+ * last), or undefined when the graph is acyclic.
+ *
+ * The search is iterative so a very deep graph cannot overflow the
+ * call stack, and it reports the actual loop: the topological sort
+ * used to list every node that was still blocked, which for one
+ * three-node loop meant naming the whole application.
+ */
+export function findDependencyCycle(graph) {
+    const visited = new Set();
+    for (const start of graph.getNodes()) {
+        if (visited.has(start))
+            continue;
+        const cycle = findCycleFrom(graph, start, visited);
+        if (cycle !== undefined)
+            return cycle;
+    }
+    return undefined;
+}
+function findCycleFrom(graph, start, visited) {
+    const stack = [
+        { id: start, dependencies: graph.getDependencies(start), next: 0 },
+    ];
+    const inPath = new Set([start]);
+    const path = [start];
+    while (stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.next >= frame.dependencies.length) {
+            stack.pop();
+            path.pop();
+            inPath.delete(frame.id);
+            visited.add(frame.id);
+            continue;
+        }
+        const dependency = frame.dependencies[frame.next];
+        frame.next += 1;
+        if (inPath.has(dependency)) {
+            return Object.freeze([...path.slice(path.indexOf(dependency)), dependency]);
+        }
+        if (visited.has(dependency))
+            continue;
+        stack.push({
+            id: dependency,
+            dependencies: graph.getDependencies(dependency),
+            next: 0,
+        });
+        inPath.add(dependency);
+        path.push(dependency);
+    }
+    return undefined;
+}