@zudojs/lifecycle 1.1.1 → 1.2.1

package/README.md

@@ -124,6 +124,13 @@ createLifecycleManager({
 Per-component: `id`, `dependsOn`, `priority`, `critical`, `timeout`,
 `retry: { attempts, delay, maxDelay, backoff }`.
 
+`priority` orders components that share a dependency level, and it is a
+barrier rather than a hint: every component at one priority completes the
+phase before the next priority starts, so `priority: 10` really does start
+before `priority: 0`. Components sharing a priority still run together, up
+to `concurrency`. Shutdown mirrors it — within a level the lowest priority
+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.

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

@@ -28,7 +28,14 @@ export interface LifecycleRegistrationOptions {
     readonly id?: string;
     /** IDs of components that must start before this one. */
     readonly dependsOn?: readonly string[];
-    /** Priority for ordering within the same dependency level. Higher = earlier. */
+    /**
+     * Priority for ordering within the same dependency level. Higher = earlier.
+     *
+     * Priority is a barrier, not a hint: every component at one priority
+     * finishes the phase before the next priority begins, and shutdown
+     * runs the mirror image (lowest priority stops first). Components
+     * sharing a priority still run concurrently.
+     */
     readonly priority?: number;
     /** If true, application startup fails when this component fails. Defaults to true. */
     readonly critical?: boolean;

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

@@ -37,7 +37,15 @@ export declare class LifecycleExecutor {
      */
     execute(registration: LifecycleRegistration, phase: LifecyclePhase, context: LifecycleContext): Promise<ExecutionResult>;
     /**
-     * Executes a stage of components in parallel with concurrency limit.
+     * Executes a stage of components, honouring priority as a barrier.
+     *
+     * 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.
      */
     executeStage(registrations: readonly LifecycleRegistration[], phase: LifecyclePhase, context: LifecycleContext, concurrency: number): Promise<readonly ExecutionResult[]>;
 }

package/dist/lifecycleExecutor/lifecycleExecutor.core.js

@@ -96,17 +96,49 @@ export class LifecycleExecutor {
         };
     }
     /**
-     * Executes a stage of components in parallel with concurrency limit.
+     * Executes a stage of components, honouring priority as a barrier.
+     *
+     * 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.
      */
     async executeStage(registrations, phase, context, concurrency) {
         const results = [];
-        await withConcurrency(registrations, concurrency, async (reg) => {
-            const result = await this.execute(reg, phase, context);
-            results.push(result);
-        });
+        for (const batch of groupByPriority(registrations)) {
+            await withConcurrency(batch, concurrency, async (reg) => {
+                const result = await this.execute(reg, phase, context);
+                results.push(result);
+            });
+        }
         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);
+        }
+        current.push(reg);
+    }
+    return batches;
+}
 /** Calculates retry delay with backoff. */
 function calculateDelay(config, attempt) {
     const base = config.delay ?? 500;

package/dist/lifecycleInternal/asyncUtils.core.js

@@ -3,7 +3,7 @@
  *
  * Async utilities for timeout, abort, and concurrency control.
  */
-import { LifecycleTimeoutError } from "@zudojs/errors";
+import { ErrorCode, LifecycleError, LifecycleTimeoutError, } from "@zudojs/errors";
 import { assertTimeoutBudget, isBounded, toTimerDelay, } from "./timeoutBudget.core.js";
 /**
  * Executes an async operation with a timeout.
@@ -49,11 +49,11 @@ export async function withTimeout(fn, timeoutMs, componentId, phase) {
  */
 export async function withAbort(fn, signal) {
     if (signal.aborted) {
-        throw new Error("Operation aborted");
+        throw abortError();
     }
     return new Promise((resolve, reject) => {
         const onAbort = () => {
-            reject(new Error("Operation aborted"));
+            reject(abortError());
         };
         signal.addEventListener("abort", onAbort, { once: true });
         // A synchronously throwing `fn` rejected via the Promise executor
@@ -79,6 +79,12 @@ export async function withAbort(fn, signal) {
         });
     });
 }
+/** The typed error surfaced when a `withAbort` operation is cancelled. */
+function abortError() {
+    return new LifecycleError("Operation aborted", {
+        code: ErrorCode.LIFECYCLE_COMPONENT,
+    });
+}
 /**
  * Executes async operations with a concurrency limit.
  */

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

@@ -14,6 +14,13 @@ export type TopologicalStage = readonly string[];
 export declare function topologicalSort(graph: DependencyGraph, priorities?: ReadonlyMap<string, number>): readonly TopologicalStage[];
 /**
  * Performs reverse topological sort for shutdown ordering.
+ *
+ * Both the stage list AND each stage's contents are reversed, so a
+ * shutdown is the exact mirror of the startup order: within a stage the
+ * lowest-priority component is torn down first and the highest-priority
+ * one last. Only the stage list used to be reversed, which left every
+ * stage in descending-priority order — harmless while stages ran fully
+ * concurrently, but wrong now that priority is a real sub-stage barrier.
  */
 export declare function reverseTopologicalSort(graph: DependencyGraph, priorities?: ReadonlyMap<string, number>): readonly TopologicalStage[];
 //# sourceMappingURL=topologicalSort.core.d.ts.map

package/dist/lifecycleInternal/topologicalSort.core.js

@@ -42,9 +42,16 @@ export function topologicalSort(graph, priorities) {
 }
 /**
  * Performs reverse topological sort for shutdown ordering.
+ *
+ * Both the stage list AND each stage's contents are reversed, so a
+ * shutdown is the exact mirror of the startup order: within a stage the
+ * lowest-priority component is torn down first and the highest-priority
+ * one last. Only the stage list used to be reversed, which left every
+ * stage in descending-priority order — harmless while stages ran fully
+ * concurrently, but wrong now that priority is a real sub-stage barrier.
  */
 export function reverseTopologicalSort(graph, priorities) {
     const stages = topologicalSort(graph, priorities);
-    return Object.freeze([...stages].reverse().map((stage) => Object.freeze([...stage])));
+    return Object.freeze([...stages].reverse().map((stage) => Object.freeze([...stage].reverse())));
 }
 //# sourceMappingURL=topologicalSort.core.js.map

package/dist/lifecycleManager/lifecycleManager.shutdown.js

@@ -66,6 +66,14 @@ async function runShutdown(ctx) {
         catch {
             // Shutdown must continue even if individual components fail.
         }
+        // A stop()/dispose() hook that blew its own component timeout joins
+        // the abandoned set DURING this phase, so the pre-phase settle above
+        // cannot have covered it. Without this wait, DISPOSE ran on top of a
+        // stop() that was still draining and shutdown() resolved (reporting
+        // DISPOSED) while the hook kept running — the exact overlap the
+        // pre-phase settle was added to prevent. Still bounded by the global
+        // shutdown deadline.
+        await raceDeadline(ctx, ctx.executor.settleAbandoned(), Math.max(deadline - Date.now(), 1));
     }
     ctx.state.forceState(LifecycleState.DISPOSED);
     ctx.events.emit("application:stopped", {

package/dist/lifecycleRegistry/lifecycleRegistry.core.js

@@ -5,6 +5,7 @@
  */
 import { LIFECYCLE_DEFAULT_TIMEOUT } from "@zudojs/constants";
 import { DependencyGraph, assertTimeoutBudget, } from "../lifecycleInternal/index.js";
+import { ErrorCode, LifecycleError } from "@zudojs/errors";
 /**
  * Registry for lifecycle components.
  * Validates registration, builds dependency graph, and freezes on demand.
@@ -16,14 +17,17 @@ export class LifecycleRegistry {
     /** Registers a component with optional configuration. */
     register(component, options = {}) {
         if (this._frozen) {
-            throw new Error("Cannot register components after registry is frozen");
+            throw new LifecycleError("Cannot register components after registry is frozen", { code: ErrorCode.LIFECYCLE_COMPONENT });
         }
         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`);
+            throw new LifecycleError(`Component "${id}" is already registered`, {
+                code: ErrorCode.LIFECYCLE_COMPONENT,
+                componentId: id,
+            });
         }
         const registration = {
             id,
@@ -51,7 +55,11 @@ export class LifecycleRegistry {
         for (const [id, reg] of this._registrations) {
             for (const dep of reg.dependsOn) {
                 if (!this._registrations.has(dep)) {
-                    throw new Error(`Component "${id}" depends on "${dep}" which is not registered`);
+                    throw new LifecycleError(`Component "${id}" depends on "${dep}" which is not registered`, {
+                        code: ErrorCode.LIFECYCLE_DEPENDENCY,
+                        componentId: id,
+                        metadata: { dependency: dep },
+                    });
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/lifecycle",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Application and component lifecycle orchestration with state machine, dependency ordering, graceful shutdown, rollback, and signals.",
   "license": "MIT",
   "author": {
@@ -24,13 +24,13 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.1.0",
-    "@zudojs/constants": "1.1.0"
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/constants": "1.1.2"
   },
   "devDependencies": {
-    "@types/node": "^26.4.1",
+    "@types/node": "^26.6.2",
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=24.0.0"
@@ -45,7 +45,7 @@
     "startup",
     "shutdown"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-lifecycle",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },