@zudojs/core 0.1.0 → 1.0.0

package/dist/runtime/runtime.d.ts

@@ -5,10 +5,28 @@ import type { Module } from "../modules/module.js";
 import type { ModuleLoader } from "../modules/moduleLoader/index.js";
 import type { ModuleLifecycleManager } from "../modules/moduleLifecycle/index.js";
 import type { ModuleRegistry } from "../modules/moduleRegistry/index.js";
-import { RuntimeError as BaseRuntimeError, RuntimeStateError as BaseRuntimeStateError } from "@zudojs/errors";
-/** Runtime lifecycle state. */
-export type RuntimeState = "created" | "bootstrapping" | "ready" | "stopping" | "stopped" | "failed";
-/** Dependencies required by the runtime. */
+import type { Disposable } from "../contracts/disposable.js";
+import type { ContextStorage } from "../context/provider/contextStorage.storage.js";
+import { RuntimeState } from "./runtimeState.state.js";
+import type { RuntimeStateSnapshot, RuntimeTiming } from "./runtimeState.state.js";
+import type { RuntimeExecutionContext, RuntimeIdentity } from "./runtimeContext/index.js";
+import type { RuntimeEnvironment } from "./runtimeEnvironment/index.js";
+import type { RuntimeOptions, ResolvedRuntimeOptions } from "./runtimeOptions/index.js";
+import type { RuntimeBootstrap, RuntimeBootstrapResult } from "./runtimeBootstrap/runtimeBootstrap.type.js";
+import type { RuntimeShutdown, RuntimeShutdownResult } from "./runtimeShutdown/runtimeShutdown.type.js";
+import type { RuntimeSignalTarget } from "./runtimeSignals/runtimeSignals.js";
+/**
+ * Runtime lifecycle state as a plain string union (the values of the
+ * RuntimeState enum).
+ */
+export type RuntimeLifecycleState = `${RuntimeState}`;
+/**
+ * Dependencies required by the runtime.
+ *
+ * `bootstrap`, `shutdown`, `environment`, `signalTarget`, and
+ * `contextStorage` are optional overrides; the runtime creates
+ * defaults when omitted.
+ */
 export interface RuntimeDependencies {
     readonly application: ApplicationContext;
     readonly configuration: ConfigurationManager;
@@ -16,21 +34,70 @@ export interface RuntimeDependencies {
     readonly moduleRegistry: ModuleRegistry;
     readonly moduleLoader: ModuleLoader;
     readonly moduleLifecycle: ModuleLifecycleManager;
+    readonly environment?: RuntimeEnvironment;
+    readonly bootstrap?: RuntimeBootstrap;
+    readonly shutdown?: RuntimeShutdown;
+    readonly signalTarget?: RuntimeSignalTarget;
+    /**
+     * ContextStorage the runtime establishes its execution context
+     * in around start() and stop(). Defaults to the process-wide
+     * storage from getDefaultContextStorage(). Supply the same
+     * storage to the ModuleLifecycleManager (and the container's
+     * `currentScope`) when injecting a custom one.
+     */
+    readonly contextStorage?: ContextStorage;
 }
-/** Runtime status snapshot. */
+/**
+ * Runtime status snapshot.
+ */
 export interface RuntimeStatus {
     readonly state: RuntimeState;
     readonly startedAt?: Date;
     readonly stoppedAt?: Date;
     readonly failedAt?: Date;
+    readonly timing: RuntimeTiming;
     readonly error?: unknown;
+    readonly bootstrap?: RuntimeBootstrapResult;
+    readonly shutdown?: RuntimeShutdownResult;
 }
-/** Runtime contract. */
-export interface Runtime {
+/**
+ * Runtime contract.
+ *
+ * A runtime is single-use: CREATED → BOOTSTRAPPING → READY → STOPPING
+ * → STOPPED, with FAILED reachable from every non-terminal state. A
+ * stopped or failed runtime cannot be started again; create a new one.
+ */
+export interface Runtime extends Disposable {
     readonly state: RuntimeState;
+    /**
+     * The runtime's immutable execution context. Active (via
+     * `contextStorage`) during start(), stop(), and every module
+     * lifecycle hook the runtime drives.
+     */
+    readonly context: RuntimeExecutionContext;
+    /** Storage in which `context` is established. */
+    readonly contextStorage: ContextStorage;
+    /** Timestamps of the state transitions observed so far. */
+    readonly timing: RuntimeTiming;
+    readonly environment: RuntimeEnvironment;
+    readonly identity: RuntimeIdentity;
+    readonly options: ResolvedRuntimeOptions;
+    readonly ready: boolean;
+    readonly stopped: boolean;
+    readonly failed: boolean;
+    /** Whether process signal handlers are currently registered. */
+    readonly signalHandlersRegistered: boolean;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Marks the runtime as failed from any non-terminal state. Does not
+     * unwind modules by itself; call `stop()` afterwards to do so.
+     */
+    fail(error?: unknown): void;
+    dispose(): Promise<void>;
     getStatus(): RuntimeStatus;
+    getStateSnapshot(): RuntimeStateSnapshot;
+    getUptime(): number;
     getApplicationContext(): ApplicationContext;
     getConfiguration(): ConfigurationManager;
     getLogger(): Logger;
@@ -40,41 +107,74 @@ export interface Runtime {
     getModule(moduleId: string): Module | undefined;
     requireModule(moduleId: string): Module;
 }
-/** Error thrown for invalid runtime operations. */
-export declare class RuntimeStateError extends BaseRuntimeStateError {
-    constructor(message: string);
-}
-/** Error thrown when runtime startup/shutdown fails. */
-export declare class RuntimeError extends BaseRuntimeError {
-    readonly moduleIds: readonly string[];
-    constructor(message: string, moduleIds?: readonly string[]);
-}
 /**
  * Default runtime implementation.
- * Orchestrates Application, Configuration, Logger, ModuleRegistry,
- * ModuleLoader, ModuleLifecycleManager.
+ *
+ * Owns the runtime state machine and identity, and orchestrates the
+ * bootstrap and shutdown services, the module subsystem, and process
+ * signal handling.
  */
 export declare class DefaultRuntime implements Runtime {
+    private readonly _options;
+    private readonly _identity;
+    private readonly _context;
+    private readonly _contextStorage;
+    private readonly _environment;
+    private readonly _bootstrap;
+    private readonly _shutdown;
+    private readonly _signals;
+    private readonly _application;
+    private readonly _configuration;
+    private readonly _logger;
+    private readonly _moduleRegistry;
+    private readonly _moduleLoader;
+    private readonly _moduleLifecycle;
     private _state;
-    private startedAt;
-    private stoppedAt;
-    private failedAt;
-    private error;
-    private startPromise;
-    private stopPromise;
-    private readonly application;
-    private readonly configuration;
-    private readonly logger;
-    private readonly moduleRegistry;
-    private readonly moduleLoader;
-    private readonly moduleLifecycle;
-    constructor(dependencies: RuntimeDependencies);
+    private _timing;
+    private _error;
+    private _startPromise;
+    private _stopPromise;
+    private _unwound;
+    constructor(dependencies: RuntimeDependencies, options?: RuntimeOptions);
     get state(): RuntimeState;
+    get context(): RuntimeExecutionContext;
+    get contextStorage(): ContextStorage;
+    get timing(): RuntimeTiming;
+    get environment(): RuntimeEnvironment;
+    get identity(): RuntimeIdentity;
+    get options(): ResolvedRuntimeOptions;
+    get ready(): boolean;
+    get stopped(): boolean;
+    get failed(): boolean;
+    get signalHandlersRegistered(): boolean;
     start(): Promise<void>;
     stop(): Promise<void>;
+    fail(error?: unknown): void;
+    dispose(): Promise<void>;
     private performStart;
     private performStop;
+    /**
+     * Best-effort module unwinding used after a failure. Errors are
+     * logged and swallowed; the runtime stays FAILED.
+     */
+    private unwind;
+    /**
+     * Runs an operation inside the runtime's execution context so that
+     * module hooks, container factories, and loggers reached from it
+     * observe the context through `contextStorage`.
+     */
+    private inContext;
+    private runShutdown;
+    private handleSignal;
+    private handleFatal;
+    private transitionTo;
+    private recordTimingForState;
+    private recordTiming;
+    private logContext;
+    private errorContext;
     getStatus(): RuntimeStatus;
+    getStateSnapshot(): RuntimeStateSnapshot;
+    getUptime(): number;
     getApplicationContext(): ApplicationContext;
     getConfiguration(): ConfigurationManager;
     getLogger(): Logger;
@@ -84,6 +184,8 @@ export declare class DefaultRuntime implements Runtime {
     getModule(moduleId: string): Module | undefined;
     requireModule(moduleId: string): Module;
 }
-/** Creates a runtime. */
-export declare function createRuntime(dependencies: RuntimeDependencies): Runtime;
+/**
+ * Creates a runtime.
+ */
+export declare function createRuntime(dependencies: RuntimeDependencies, options?: RuntimeOptions): Runtime;
 //# sourceMappingURL=runtime.d.ts.map