@zudojs/runtime 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

@@ -10,24 +10,145 @@ npm install @zudojs/runtime
 
 ## Quick Start
 
+`createRuntime` takes the framework services the runtime orchestrates,
+then the runtime's own options.
+
 ```typescript
 import { createRuntime } from "@zudojs/runtime";
 
-const runtime = createRuntime({
-  services: [api, database, queue],
-});
+const runtime = createRuntime(
+  {
+    modules: new Map([
+      ["database", database],
+      ["api", api],
+    ]),
+    logger,
+    container,
+    eventBus,
+  },
+  {
+    environment: "production",
+    applicationName: "my-app",
+  },
+);
 
 await runtime.start();
 await runtime.stop();
 ```
 
+Modules start in dependency order and stop in reverse.
+
+## Readiness and health
+
+Readiness checks are registered on the runtime and re-evaluated on demand.
+A registered check starts out failing until it is first run, so registering
+one on a running runtime moves it to `degraded` until it passes.
+
+```typescript
+runtime.registerReadinessCheck("database", () => database.isConnected());
+
+await runtime.runReadinessChecks();
+
+runtime.ready; // false while any check fails
+runtime.health.state; // "healthy" | "degraded" | ...
+runtime.readiness.checks.get("database"); // per-check result and duration
+```
+
+`runtime.health` is derived from the lifecycle state and the readiness
+checks: a running runtime is `healthy` when every check passes and
+`degraded` when any check fails; every other lifecycle state maps onto
+`starting`, `stopping`, `unhealthy` or `unknown`. A change emits
+`runtime.health.changed` on the event bus.
+
+`runtime.status` and `runtime.context` are read live, so `state`, `ready`,
+`health`, `startedAt`, `stoppedAt`, `failedAt` and `error` always reflect
+the runtime as it is now — including on the failure path, where
+`context.error` names what went wrong.
+
+By default a readiness check that does not settle within 5 seconds is
+recorded as failed; pass `readinessCheckTimeout` to change that bound, or
+`0` to remove it.
+
+## Module context
+
+Modules receive a `ModuleContext` giving them the framework services they
+are allowed to reach. Configuration and the application context are
+supplied through the runtime's dependencies:
+
+```typescript
+const runtime = createRuntime(
+  { modules, logger, container, eventBus, configuration, application },
+  options,
+);
+```
+
+`configuration` backs `context.getConfiguration()`, `context.getConfig()`
+and `context.requireConfig()`; it defaults to an empty manager loaded at
+startup. `application` backs `context.application` — a module that reads
+it when none was supplied gets a clear error rather than an empty object.
+`context.hasModule()` and `context.getModuleContext()` resolve against the
+registered modules, and a module keeps the same context across every
+lifecycle phase.
+
+## Runtime events
+
+With `emitEvents` (the default), the runtime publishes on the event bus.
+Subscribe with `bus.on(type, handler)`; the payload types are in
+`RuntimeEventMap`.
+
+| Event | Payload |
+| --- | --- |
+| `runtime.initializing`, `runtime.running`, `runtime.stopping`, `runtime.stopped` | `RuntimeEventPayload` |
+| `runtime.failed` | `RuntimeFailureEventPayload` |
+| `runtime.module.initializing` / `initialized` / `starting` / `started` / `stopping` / `stopped` / `failed` | `RuntimeModuleEventPayload` |
+| `runtime.shutdown.drain`, `runtime.shutdown.complete` | `RuntimeEventPayload` |
+| `runtime.health.changed` | `RuntimeHealthEventPayload` |
+| `runtime.readiness.changed` | `RuntimeReadinessEventPayload` |
+
+```typescript
+bus.on("runtime.module.failed", (event) => {
+  const { moduleId, moduleName, error, durationMs } = event.payload;
+  alert(`${moduleName} (${moduleId}) failed after ${durationMs}ms`, error);
+});
+```
+
+Every `runtime.module.*` event names the module it is about. A listener
+that throws is logged and contained; it never fails the lifecycle phase
+that produced the event.
+
+## Options
+
+```typescript
+createRuntime(dependencies, {
+  environment: "production", // required
+  applicationName: "my-app", // required
+  applicationVersion: "1.4.0",
+  runtimeId: "rt_custom", // generated when omitted
+  handleSignals: true, // SIGTERM/SIGINT trigger a graceful stop
+  handleFatalErrors: true, // uncaughtException/unhandledRejection
+  startupTimeout: 60_000,
+  shutdownTimeout: 30_000,
+  emitEvents: true,
+  trackReadiness: true,
+  trackHealth: true,
+  readinessCheckTimeout: 5_000, // 0 removes the bound
+  parallelInitialization: false, // initialize each depth group at once
+  metadata: { region: "eu-west-1" },
+});
+```
+
+`parallelInitialization` initializes modules that share a dependency depth
+concurrently. They do not depend on one another by construction, but
+enabling it surfaces any ordering a module assumed without declaring, so
+it is opt-in.
+
 ## Features
 
-- Service dependency ordering
+- Module dependency ordering
 - Graceful shutdown with rollback
 - Signal handling (SIGINT, SIGTERM)
-- Readiness and health checks
-- Lifecycle hooks (onStart, onStop, onReady)
+- Readiness checks and derived health
+- Lifecycle hooks (onInitialize, onReady, onShutdown, onDestroy)
 
 ## Use Cases
 

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

@@ -1,18 +1,24 @@
-import type { DependencyGraph, DependencyResolutionResult, ParallelModuleGroup } from "./dependencyGraph.type.js";
+import type { DependencyGraph, DependencyResolutionResult } from "./dependencyGraph.type.js";
 /**
  * Builds a dependency graph from module IDs and their dependencies.
  */
 export declare function buildDependencyGraph(modules: ReadonlyMap<string, readonly string[]>): DependencyGraph;
 /**
  * Resolves module dependencies into an initialization order.
+ *
+ * Missing dependencies are rejected before ordering. Previously an
+ * unregistered dependency contributed depth `0` and was silently
+ * dropped, so a typo in a module's `dependencies` degraded into an
+ * unordered start that failed later inside `onInitialize`.
  */
 export declare function resolveDependencies(modules: ReadonlyMap<string, readonly string[]>): DependencyResolutionResult;
-/**
- * Returns parallel module groups for concurrent initialization.
- */
-export declare function getParallelGroups(modules: ReadonlyMap<string, readonly string[]>): readonly ParallelModuleGroup[];
 /**
  * Validates that all module dependencies exist.
+ *
+ * @throws {RuntimeDependencyError} naming both the module and the
+ * dependency it declared. Reporting a missing dependency as a circular
+ * one, as this previously did, sends the reader looking for a cycle that
+ * does not exist.
  */
 export declare function validateDependencies(modules: ReadonlyMap<string, readonly string[]>): void;
 //# sourceMappingURL=dependencyGraph.core.d.ts.map

package/dist/dependencyGraph/dependencyGraph.core.js

@@ -1,4 +1,4 @@
-import { RuntimeCircularDependencyError } from "../runtimeError/runtimeError.base.js";
+import { RuntimeCircularDependencyError, RuntimeDependencyError, } from "../runtimeError/runtimeError.base.js";
 /**
  * Builds a dependency graph from module IDs and their dependencies.
  */
@@ -76,8 +76,14 @@ export function buildDependencyGraph(modules) {
 }
 /**
  * Resolves module dependencies into an initialization order.
+ *
+ * Missing dependencies are rejected before ordering. Previously an
+ * unregistered dependency contributed depth `0` and was silently
+ * dropped, so a typo in a module's `dependencies` degraded into an
+ * unordered start that failed later inside `onInitialize`.
  */
 export function resolveDependencies(modules) {
+    validateDependencies(modules);
     const graph = buildDependencyGraph(modules);
     if (graph.hasCircularDependency) {
         throw new RuntimeCircularDependencyError(graph.circularDependencies[0] ?? []);
@@ -99,24 +105,19 @@ export function resolveDependencies(modules) {
         circularDependencies: [],
     });
 }
-/**
- * Returns parallel module groups for concurrent initialization.
- */
-export function getParallelGroups(modules) {
-    const result = resolveDependencies(modules);
-    return result.parallelGroups.map((group, index) => Object.freeze({
-        modules: group,
-        depth: index,
-    }));
-}
 /**
  * Validates that all module dependencies exist.
+ *
+ * @throws {RuntimeDependencyError} naming both the module and the
+ * dependency it declared. Reporting a missing dependency as a circular
+ * one, as this previously did, sends the reader looking for a cycle that
+ * does not exist.
  */
 export function validateDependencies(modules) {
     for (const [moduleId, deps] of modules) {
         for (const depId of deps) {
             if (!modules.has(depId)) {
-                throw new RuntimeCircularDependencyError([moduleId, depId]);
+                throw new RuntimeDependencyError(moduleId, depId);
             }
         }
     }

package/dist/dependencyGraph/dependencyGraph.type.d.ts

@@ -25,13 +25,6 @@ export interface DependencyResolutionResult {
     readonly hasCircularDependency: boolean;
     readonly circularDependencies: readonly (readonly string[])[];
 }
-/**
- * A group of modules that can be initialized concurrently.
- */
-export interface ParallelModuleGroup {
-    readonly modules: readonly string[];
-    readonly depth: number;
-}
 /**
  * Error information for circular dependencies.
  */

package/dist/dependencyGraph/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Module dependency graph and resolution.
  */
-export { buildDependencyGraph, resolveDependencies, getParallelGroups, validateDependencies, } from "./dependencyGraph.core.js";
-export type { DependencyNode, DependencyGraph, DependencyResolutionResult, ParallelModuleGroup, CircularDependencyInfo, } from "./dependencyGraph.type.js";
+export { buildDependencyGraph, resolveDependencies, validateDependencies, } from "./dependencyGraph.core.js";
+export type { DependencyNode, DependencyGraph, DependencyResolutionResult, CircularDependencyInfo, } from "./dependencyGraph.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/dependencyGraph/index.js

@@ -1,5 +1,5 @@
 /**
  * Module dependency graph and resolution.
  */
-export { buildDependencyGraph, resolveDependencies, getParallelGroups, validateDependencies, } from "./dependencyGraph.core.js";
+export { buildDependencyGraph, resolveDependencies, validateDependencies, } from "./dependencyGraph.core.js";
 //# sourceMappingURL=index.js.map

package/dist/health/health.core.d.ts

@@ -0,0 +1,12 @@
+import type { RuntimeHealth, RuntimeState } from "../runtimeState/runtimeState.type.js";
+import type { ReadinessTrackerState } from "../readiness/readiness.type.js";
+/**
+ * Computes runtime health from the lifecycle state and readiness checks.
+ *
+ * A running runtime is `healthy` when every readiness check passes (a
+ * runtime with no checks registered counts as healthy) and `degraded`
+ * when at least one check is failing. Every other lifecycle state maps
+ * directly onto a health state.
+ */
+export declare function computeRuntimeHealth(state: RuntimeState, readiness: ReadinessTrackerState): RuntimeHealth;
+//# sourceMappingURL=health.core.d.ts.map

package/dist/health/health.core.js

@@ -0,0 +1,55 @@
+/**
+ * Maps the runtime lifecycle state onto a health state, for the states
+ * where health is determined by the lifecycle alone.
+ *
+ * Returns `undefined` while the runtime is running, because health then
+ * depends on the readiness checks rather than on the state.
+ */
+function healthStateFor(state) {
+    switch (state) {
+        case "created":
+        case "stopped":
+            return "unknown";
+        case "initializing":
+        case "initialized":
+        case "starting":
+            return "starting";
+        case "stopping":
+            return "stopping";
+        case "failed":
+            return "unhealthy";
+        case "running":
+            return undefined;
+    }
+}
+/**
+ * Converts readiness checks into health checks.
+ */
+function toHealthChecks(readiness) {
+    return Object.freeze([...readiness.checks.values()].map((check) => Object.freeze({
+        name: check.name,
+        healthy: check.ready,
+        durationMs: check.durationMs,
+        ...(check.message !== undefined && { message: check.message }),
+    })));
+}
+/**
+ * Computes runtime health from the lifecycle state and readiness checks.
+ *
+ * A running runtime is `healthy` when every readiness check passes (a
+ * runtime with no checks registered counts as healthy) and `degraded`
+ * when at least one check is failing. Every other lifecycle state maps
+ * directly onto a health state.
+ */
+export function computeRuntimeHealth(state, readiness) {
+    const checks = toHealthChecks(readiness);
+    const lifecycleState = healthStateFor(state);
+    const healthState = lifecycleState ??
+        (checks.every((check) => check.healthy) ? "healthy" : "degraded");
+    return Object.freeze({
+        state: healthState,
+        checks,
+        timestamp: new Date(),
+    });
+}
+//# sourceMappingURL=health.core.js.map

package/dist/health/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime health computation.
+ */
+export { computeRuntimeHealth } from "./health.core.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/health/index.js

@@ -0,0 +1,5 @@
+/**
+ * Runtime health computation.
+ */
+export { computeRuntimeHealth } from "./health.core.js";
+//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -18,11 +18,11 @@ export * from "./runtimeEvents/index.js";
 export * from "./runtimeContext/index.js";
 export * from "./dependencyGraph/index.js";
 export * from "./readiness/index.js";
+export * from "./health/index.js";
 export * from "./lifecycle/index.js";
 export * from "./startup/index.js";
 export * from "./shutdown/index.js";
 export * from "./signalHandler/index.js";
 export * from "./runtimeError/index.js";
 export * from "./registry/index.js";
-export * from "./testRuntime/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -17,11 +17,14 @@ export * from "./runtimeEvents/index.js";
 export * from "./runtimeContext/index.js";
 export * from "./dependencyGraph/index.js";
 export * from "./readiness/index.js";
+export * from "./health/index.js";
 export * from "./lifecycle/index.js";
 export * from "./startup/index.js";
 export * from "./shutdown/index.js";
 export * from "./signalHandler/index.js";
 export * from "./runtimeError/index.js";
 export * from "./registry/index.js";
-export * from "./testRuntime/index.js";
+// `testRuntime` is intentionally NOT exported from the package root: it
+// is a testing helper, and re-exporting it here put a test-only module
+// on the main entry point. Import it from "@zudojs/runtime/testing".
 //# sourceMappingURL=index.js.map

package/dist/lifecycle/index.d.ts

@@ -2,5 +2,5 @@
  * Module lifecycle management.
  */
 export { LifecycleManager } from "./lifecycle.core.js";
-export type { LifecyclePhase, LifecycleResult, LifecycleFailure, LifecycleContext, ManagedModule, LifecycleManagerOptions, } from "./lifecycle.type.js";
+export type { LifecyclePhase, LifecycleResult, LifecycleFailure, LifecycleContext, ManagedModule, LifecycleManagerOptions, ModuleContextServices, ModuleEventListener, } from "./lifecycle.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/lifecycle.core.d.ts

@@ -1,24 +1,41 @@
 import type { Logger } from "@zudojs/logger";
-import type { Container } from "@zudojs/container";
 import type { Module } from "@zudojs/core";
-import type { LifecycleResult, LifecycleManagerOptions } from "./lifecycle.type.js";
+import type { LifecycleResult, LifecycleFailure, LifecycleManagerOptions, ModuleContextServices } from "./lifecycle.type.js";
 /**
  * Manages the lifecycle of runtime modules.
  */
 export declare class LifecycleManager {
     private readonly modules;
     private readonly logger;
-    private readonly container;
-    private readonly runtimeId;
-    private readonly environment;
     private readonly options;
-    private readonly initializedModules;
-    private readonly startedModules;
-    constructor(modules: ReadonlyMap<string, Module>, logger: Logger, container: Container, runtimeId: string, environment: string, options?: LifecycleManagerOptions);
+    private readonly onModuleEvent;
+    private readonly runtimeId;
+    private initializedModules;
+    private startedModules;
+    private readonly configuration;
+    private readonly application;
+    private readonly contexts;
+    constructor(modules: ReadonlyMap<string, Module>, logger: Logger, options?: LifecycleManagerOptions, services?: ModuleContextServices);
+    /**
+     * Publishes a per-module lifecycle event.
+     *
+     * A throwing listener must not fail the phase that produced the event,
+     * so delivery failures are contained here.
+     */
+    private emitModuleEvent;
+    /**
+     * Loads the configuration manager once, before modules are initialized,
+     * so that `context.getConfiguration()` is usable from the first hook.
+     */
+    private ensureConfigurationReady;
     /**
      * Initializes all modules in dependency order.
      */
     initialize(): Promise<LifecycleResult>;
+    /**
+     * Initializes a single module, converting a throw into a failure.
+     */
+    private initializeModule;
     /**
      * Starts all modules in dependency order.
      */
@@ -32,9 +49,15 @@ export declare class LifecycleManager {
      */
     destroy(): Promise<LifecycleResult>;
     /**
-     * Rolls back initialization for modules that were started.
+     * Rolls back a failed startup.
+     *
+     * Started modules are shut down, and every module that reached
+     * `onInitialize` is then destroyed — including those that never
+     * started because an earlier module failed. Rolling back only the
+     * started ones leaves everything they had already acquired behind with
+     * no route to release it.
      */
-    rollback(): Promise<void>;
+    rollback(): Promise<readonly LifecycleFailure[]>;
     /**
      * Creates a module context for lifecycle hooks.
      */
@@ -42,6 +65,14 @@ export declare class LifecycleManager {
     /**
      * Builds a dependency graph from registered modules.
      */
+    /**
+     * Modules that reached `onInitialize`, in initialization order.
+     */
+    getInitializedModules(): readonly string[];
+    /**
+     * Modules that reached `onReady`, in start order.
+     */
+    getStartedModules(): readonly string[];
     private buildModuleDependencyGraph;
 }
 //# sourceMappingURL=lifecycle.core.d.ts.map