@zudojs/runtime 0.1.0 → 1.1.0

package/dist/lifecycle/lifecycle.core.js

@@ -1,73 +1,108 @@
+import { createConfigurationManager } from "@zudojs/core";
+import { createModuleEventPayload } from "../runtimeEvents/runtimeEvents.core.js";
 import { resolveDependencies } from "../dependencyGraph/index.js";
-import { RuntimeStartError, RuntimeStopError, RuntimeDependencyError, } from "../runtimeError/index.js";
+import { RuntimeDependencyError, RuntimeStateError, } from "../runtimeError/index.js";
 /**
  * Manages the lifecycle of runtime modules.
  */
 export class LifecycleManager {
     modules;
     logger;
-    container;
-    runtimeId;
-    environment;
     options;
+    onModuleEvent;
+    runtimeId;
     initializedModules = [];
     startedModules = [];
-    constructor(modules, logger, container, runtimeId, environment, options = {}) {
+    configuration;
+    application;
+    contexts = new Map();
+    constructor(modules, logger, options = {}, services = {}) {
         this.modules = modules;
         this.logger = logger;
-        this.container = container;
-        this.runtimeId = runtimeId;
-        this.environment = environment;
+        this.configuration = services.configuration ?? createConfigurationManager();
+        this.application = services.application;
+        this.onModuleEvent = options.onModuleEvent;
+        this.runtimeId = options.runtimeId ?? "";
         this.options = {
             shutdownTimeout: options.shutdownTimeout ?? 30_000,
             continueOnFailure: options.continueOnFailure ?? false,
-            parallelInitialization: options.parallelInitialization ?? true,
+            // Defaults to sequential: initializing a whole depth group at once
+            // is a real behaviour change for modules that assume ordering
+            // beyond what they declared, so it is opt-in.
+            parallelInitialization: options.parallelInitialization ?? false,
         };
     }
+    /**
+     * Publishes a per-module lifecycle event.
+     *
+     * A throwing listener must not fail the phase that produced the event,
+     * so delivery failures are contained here.
+     */
+    emitModuleEvent(type, moduleId, state, options = {}) {
+        if (!this.onModuleEvent) {
+            return;
+        }
+        const module = this.modules.get(moduleId);
+        try {
+            this.onModuleEvent(type, createModuleEventPayload(this.runtimeId, state, moduleId, module?.name ?? moduleId, options));
+        }
+        catch (error) {
+            this.logger.warn("A runtime module event listener threw.", {
+                eventType: type,
+                moduleId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Loads the configuration manager once, before modules are initialized,
+     * so that `context.getConfiguration()` is usable from the first hook.
+     */
+    async ensureConfigurationReady() {
+        if (this.configuration.isReady()) {
+            return;
+        }
+        try {
+            await this.configuration.initialize();
+        }
+        catch (error) {
+            this.logger.warn("Configuration failed to load.", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     /**
      * Initializes all modules in dependency order.
      */
     async initialize() {
         const startTime = Date.now();
+        // Reset the per-run bookkeeping. Appending across runs would make a
+        // stop-then-start cycle initialize and stop every module twice.
+        this.initializedModules = [];
+        this.startedModules = [];
+        await this.ensureConfigurationReady();
         const succeeded = [];
         const failed = [];
         const depGraph = this.buildModuleDependencyGraph();
-        for (const moduleId of depGraph.order) {
-            const module = this.modules.get(moduleId);
-            if (!module) {
-                failed.push({
-                    moduleId,
-                    phase: "initialize",
-                    error: new RuntimeDependencyError(moduleId, "unknown"),
-                    durationMs: 0,
-                });
-                continue;
-            }
-            const moduleStartTime = Date.now();
-            try {
-                if (module.onInitialize) {
-                    const context = this.createModuleContext(module);
-                    await module.onInitialize(context);
+        // Modules within a depth group have no dependency on one another, so
+        // they may be initialized together when the caller opts in.
+        const groups = this.options.parallelInitialization
+            ? depGraph.parallelGroups
+            : depGraph.order.map((moduleId) => [moduleId]);
+        for (const group of groups) {
+            const results = await Promise.all(group.map((moduleId) => this.initializeModule(moduleId)));
+            for (const result of results) {
+                if (result.failure) {
+                    failed.push(result.failure);
                 }
-                succeeded.push(moduleId);
-                this.initializedModules.push(moduleId);
-                this.logger.debug(`Module "${moduleId}" initialized.`, {
-                    durationMs: Date.now() - moduleStartTime,
-                });
-            }
-            catch (error) {
-                const failure = {
-                    moduleId,
-                    phase: "initialize",
-                    error: error instanceof Error ? error : new Error(String(error)),
-                    durationMs: Date.now() - moduleStartTime,
-                };
-                failed.push(failure);
-                this.logger.error(`Module "${moduleId}" failed during initialization.`, { error: failure.error });
-                if (!this.options.continueOnFailure) {
-                    break;
+                else {
+                    succeeded.push(result.moduleId);
+                    this.initializedModules.push(result.moduleId);
                 }
             }
+            if (failed.length > 0 && !this.options.continueOnFailure) {
+                break;
+            }
         }
         return Object.freeze({
             phase: "initialize",
@@ -76,11 +111,58 @@ export class LifecycleManager {
             durationMs: Date.now() - startTime,
         });
     }
+    /**
+     * Initializes a single module, converting a throw into a failure.
+     */
+    async initializeModule(moduleId) {
+        const module = this.modules.get(moduleId);
+        if (!module) {
+            return {
+                moduleId,
+                failure: {
+                    moduleId,
+                    phase: "initialize",
+                    error: new RuntimeDependencyError(moduleId, "unknown"),
+                    durationMs: 0,
+                },
+            };
+        }
+        const startedAt = Date.now();
+        this.emitModuleEvent("runtime.module.initializing", moduleId, "initializing");
+        try {
+            if (module.onInitialize) {
+                await module.onInitialize(this.createModuleContext(module));
+            }
+            const durationMs = Date.now() - startedAt;
+            this.logger.debug(`Module "${moduleId}" initialized.`, { durationMs });
+            this.emitModuleEvent("runtime.module.initialized", moduleId, "initialized", {
+                durationMs,
+            });
+            return { moduleId };
+        }
+        catch (error) {
+            const failure = {
+                moduleId,
+                phase: "initialize",
+                error: error instanceof Error ? error : new Error(String(error)),
+                durationMs: Date.now() - startedAt,
+            };
+            this.logger.error(`Module "${moduleId}" failed during initialization.`, {
+                error: failure.error,
+            });
+            this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
+                durationMs: failure.durationMs,
+                error: failure.error,
+            });
+            return { moduleId, failure };
+        }
+    }
     /**
      * Starts all modules in dependency order.
      */
     async start() {
         const startTime = Date.now();
+        this.startedModules = [];
         const succeeded = [];
         const failed = [];
         for (const moduleId of this.initializedModules) {
@@ -88,6 +170,7 @@ export class LifecycleManager {
             if (!module)
                 continue;
             const moduleStartTime = Date.now();
+            this.emitModuleEvent("runtime.module.starting", moduleId, "starting");
             try {
                 if (module.onReady) {
                     const context = this.createModuleContext(module);
@@ -95,8 +178,10 @@ export class LifecycleManager {
                 }
                 succeeded.push(moduleId);
                 this.startedModules.push(moduleId);
-                this.logger.debug(`Module "${moduleId}" started.`, {
-                    durationMs: Date.now() - moduleStartTime,
+                const durationMs = Date.now() - moduleStartTime;
+                this.logger.debug(`Module "${moduleId}" started.`, { durationMs });
+                this.emitModuleEvent("runtime.module.started", moduleId, "started", {
+                    durationMs,
                 });
             }
             catch (error) {
@@ -110,6 +195,10 @@ export class LifecycleManager {
                 this.logger.error(`Module "${moduleId}" failed during startup.`, {
                     error: failure.error,
                 });
+                this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
+                    durationMs: failure.durationMs,
+                    error: failure.error,
+                });
                 if (!this.options.continueOnFailure) {
                     break;
                 }
@@ -135,14 +224,17 @@ export class LifecycleManager {
             if (!module)
                 continue;
             const moduleStartTime = Date.now();
+            this.emitModuleEvent("runtime.module.stopping", moduleId, "stopping");
             try {
                 if (module.onShutdown) {
                     const context = this.createModuleContext(module);
                     await module.onShutdown(context);
                 }
                 succeeded.push(moduleId);
-                this.logger.debug(`Module "${moduleId}" stopped.`, {
-                    durationMs: Date.now() - moduleStartTime,
+                const durationMs = Date.now() - moduleStartTime;
+                this.logger.debug(`Module "${moduleId}" stopped.`, { durationMs });
+                this.emitModuleEvent("runtime.module.stopped", moduleId, "stopped", {
+                    durationMs,
                 });
             }
             catch (error) {
@@ -156,6 +248,10 @@ export class LifecycleManager {
                 this.logger.error(`Module "${moduleId}" failed during shutdown.`, {
                     error: failure.error,
                 });
+                this.emitModuleEvent("runtime.module.failed", moduleId, "failed", {
+                    durationMs: failure.durationMs,
+                    error: failure.error,
+                });
             }
         }
         return Object.freeze({
@@ -203,6 +299,11 @@ export class LifecycleManager {
                 });
             }
         }
+        // The runtime no longer owns these modules; a subsequent start
+        // rebuilds the lists from scratch.
+        this.startedModules = [];
+        this.initializedModules = [];
+        this.contexts.clear();
         return Object.freeze({
             phase: "destroy",
             succeeded: Object.freeze(succeeded),
@@ -211,51 +312,127 @@ export class LifecycleManager {
         });
     }
     /**
-     * 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.
      */
     async rollback() {
-        const reversedModules = [...this.startedModules].reverse();
-        for (const moduleId of reversedModules) {
+        const failures = [];
+        for (const moduleId of [...this.startedModules].reverse()) {
             const module = this.modules.get(moduleId);
             if (!module?.onShutdown)
                 continue;
+            const startedAt = Date.now();
             try {
-                const context = this.createModuleContext(module);
-                await module.onShutdown(context);
+                await module.onShutdown(this.createModuleContext(module));
                 this.logger.debug(`Module "${moduleId}" rolled back.`);
             }
             catch (error) {
+                failures.push({
+                    moduleId,
+                    phase: "stop",
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    durationMs: Date.now() - startedAt,
+                });
                 this.logger.error(`Module "${moduleId}" rollback failed.`, {
                     errorMessage: error instanceof Error ? error.message : String(error),
                 });
             }
         }
+        for (const moduleId of [...this.initializedModules].reverse()) {
+            const module = this.modules.get(moduleId);
+            if (!module?.onDestroy)
+                continue;
+            const startedAt = Date.now();
+            try {
+                await module.onDestroy(this.createModuleContext(module));
+                this.logger.debug(`Module "${moduleId}" destroyed during rollback.`);
+            }
+            catch (error) {
+                failures.push({
+                    moduleId,
+                    phase: "destroy",
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    durationMs: Date.now() - startedAt,
+                });
+                this.logger.error(`Module "${moduleId}" destruction failed.`, {
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        // A rolled-back runtime owns nothing; clear the bookkeeping so a
+        // later shutdown does not stop modules a second time.
+        this.startedModules = [];
+        this.initializedModules = [];
+        this.contexts.clear();
+        return failures;
     }
     /**
      * Creates a module context for lifecycle hooks.
      */
     createModuleContext(module) {
-        return {
+        const existing = this.contexts.get(module.id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const configuration = this.configuration;
+        const application = this.application;
+        const logger = this.logger;
+        const contexts = this.contexts;
+        const modules = this.modules;
+        const context = {
             id: module.id,
             name: module.name,
             version: module.version,
             options: module.options ?? {},
             scope: module.scope,
-            application: {},
-            configuration: {},
-            logger: this.logger,
-            getConfiguration: () => ({}),
-            getConfig: () => undefined,
-            requireConfig: (path) => {
-                throw new Error(`Config "${path}" not found.`);
+            // `application` is a getter so that a runtime started without an
+            // application context fails loudly at the point of use, rather than
+            // handing modules an empty object that lies about its type.
+            get application() {
+                if (application === undefined) {
+                    throw new RuntimeStateError(`Module "${module.id}" accessed "context.application", but no ` +
+                        `ApplicationContext was supplied to the runtime.`);
+                }
+                return application;
             },
-            getModuleContext: () => undefined,
-            hasModule: () => false,
+            configuration,
+            logger,
+            getConfiguration: () => configuration.getConfiguration(),
+            getConfig: (path) => configuration.get(path),
+            requireConfig: (path) => configuration.require(path),
+            // Only a module's declared dependencies are reachable. Handing
+            // every module every other module's configuration and application
+            // context makes the declared dependency graph advisory.
+            getModuleContext: (moduleId) => {
+                const allowed = moduleId === module.id ||
+                    (module.dependencies ?? []).includes(moduleId);
+                return allowed ? contexts.get(moduleId) : undefined;
+            },
+            hasModule: (moduleId) => modules.has(moduleId),
         };
+        this.contexts.set(module.id, context);
+        return context;
     }
     /**
      * Builds a dependency graph from registered modules.
      */
+    /**
+     * Modules that reached `onInitialize`, in initialization order.
+     */
+    getInitializedModules() {
+        return Object.freeze([...this.initializedModules]);
+    }
+    /**
+     * Modules that reached `onReady`, in start order.
+     */
+    getStartedModules() {
+        return Object.freeze([...this.startedModules]);
+    }
     buildModuleDependencyGraph() {
         const moduleDeps = new Map();
         for (const [id, module] of this.modules) {

package/dist/lifecycle/lifecycle.type.d.ts

@@ -1,4 +1,5 @@
-import type { Module } from "@zudojs/core";
+import type { ConfigurationManager, Module, ModuleContext } from "@zudojs/core";
+import type { RuntimeModuleEventPayload, RuntimeModuleEventType } from "../runtimeEvents/runtimeEvents.type.js";
 /**
  * Lifecycle hook phases for modules.
  */
@@ -40,12 +41,58 @@ export interface ManagedModule {
     readonly depth: number;
     readonly dependencies: readonly string[];
 }
+/**
+ * Framework services made available to modules through their
+ * {@link ModuleContext}.
+ *
+ * Both are optional so a runtime can be started without a configuration
+ * layer, but a module that reaches for a service the host did not supply
+ * gets a clear error rather than a silently empty object.
+ */
+export interface ModuleContextServices {
+    /**
+     * Configuration manager backing `getConfiguration`, `getConfig` and
+     * `requireConfig`. Defaults to an empty, uninitialized manager.
+     */
+    readonly configuration?: ConfigurationManager;
+    /**
+     * Application context exposed as `context.application`.
+     *
+     * `ApplicationContext` is not part of `@zudojs/core`'s published entry
+     * points, so the runtime cannot construct one itself; a host that has an
+     * application context passes it in here.
+     */
+    readonly application?: ModuleContext["application"];
+}
+/**
+ * Receives a per-module lifecycle event.
+ */
+export type ModuleEventListener = (type: RuntimeModuleEventType, payload: RuntimeModuleEventPayload) => void;
 /**
  * Options for lifecycle management.
  */
 export interface LifecycleManagerOptions {
     readonly shutdownTimeout?: number;
     readonly continueOnFailure?: boolean;
+    /**
+     * Receives one event per module per lifecycle phase.
+     *
+     * The lifecycle is the only layer that knows which module is running,
+     * so it is the only layer that can populate a
+     * {@link RuntimeModuleEventPayload}. Without this the runtime published
+     * two phase-wide events with no module on them, and every
+     * `runtime.module.*` entry in `RuntimeEventMap` named a payload nothing
+     * produced.
+     */
+    readonly onModuleEvent?: ModuleEventListener;
+    /** Runtime identifier stamped onto emitted module events. */
+    readonly runtimeId?: string;
+    /**
+     * Whether modules at the same dependency depth are initialized
+     * concurrently. Defaults to `false`. Modules within a depth group do
+     * not depend on one another, but enabling this surfaces any ordering
+     * a module assumed without declaring.
+     */
     readonly parallelInitialization?: boolean;
 }
 //# sourceMappingURL=lifecycle.type.d.ts.map

package/dist/readiness/index.d.ts

@@ -2,5 +2,5 @@
  * Runtime readiness tracking.
  */
 export { ReadinessTracker } from "./readiness.core.js";
-export type { ReadinessState, ReadinessCheck, ReadinessTrackerState, ReadinessOptions, } from "./readiness.type.js";
+export type { ReadinessState, ReadinessCheck, ReadinessCheckFn, ReadinessTrackerState, ReadinessOptions, } from "./readiness.type.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/readiness/readiness.core.d.ts

@@ -1,22 +1,54 @@
-import type { ReadinessState, ReadinessTrackerState, ReadinessOptions } from "./readiness.type.js";
+import type { ReadinessState, ReadinessCheckFn, ReadinessTrackerState, ReadinessOptions } from "./readiness.type.js";
 /**
  * Tracks runtime readiness state.
  */
 export declare class ReadinessTracker {
     private state;
     private readonly checks;
+    private readonly checkFns;
     private readonly autoMarkReady;
+    private readonly checkTimeout;
     private ready;
     private reason?;
+    private running;
     constructor(options?: ReadinessOptions);
     /**
      * Registers a readiness check.
+     *
+     * The check function is retained so it can be re-evaluated later by
+     * `updateCheck(name)` or `runChecks()`. Registration does not run the
+     * check: it starts out not-ready until it is first evaluated.
      */
-    registerCheck(name: string, check: () => boolean | Promise<boolean>): void;
+    registerCheck(name: string, check: ReadinessCheckFn): void;
     /**
-     * Updates a readiness check result.
+     * Removes a readiness check.
+     *
+     * Returns whether a check with that name was registered.
      */
-    updateCheck(name: string, check: () => boolean | Promise<boolean>): Promise<void>;
+    removeCheck(name: string): boolean;
+    /**
+     * Evaluates a readiness check and records its result.
+     *
+     * Re-runs the function registered under `name` unless a replacement is
+     * supplied, in which case the replacement is stored and used from then on.
+     */
+    updateCheck(name: string, check?: ReadinessCheckFn): Promise<void>;
+    /**
+     * Re-evaluates every registered check.
+     */
+    runChecks(): Promise<void>;
+    /**
+     * Whether any readiness check is registered.
+     */
+    hasChecks(): boolean;
+    /**
+     * Runs a single check and records its result and duration.
+     */
+    private evaluateCheck;
+    /**
+     * Runs a check under a timeout, clearing the timer either way.
+     */
+    private withCheckTimeout;
     /**
      * Marks the runtime as ready.
      */