@zudojs/core 0.1.0 → 1.1.0

package/dist/runtime/index.d.ts

@@ -4,21 +4,23 @@
  * Public API for the core runtime subsystem.
  */
 export { DefaultRuntime, createRuntime } from "./runtime.js";
-export type { RuntimeState as RuntimeLifecycleState, RuntimeDependencies, RuntimeStatus, Runtime, } from "./runtime.js";
+export type { RuntimeLifecycleState, RuntimeDependencies, RuntimeStatus, Runtime, } from "./runtime.js";
 export { DEFAULT_RUNTIME_OPTIONS, resolveRuntimeOptions, validateRuntimeOptions, isRuntimeMode, isRuntimeRole, assertRuntimeMode, assertRuntimeRole, } from "./runtimeOptions/index.js";
-export type { RuntimeMode, RuntimeRole, RuntimeOptions, RuntimeStartupOptions, RuntimeShutdownOptions, RuntimeSignalOptions, RuntimeDiagnosticsOptions, RuntimeInfrastructure, ResolvedRuntimeOptions, } from "./runtimeOptions/index.js";
-export { RuntimeState, TERMINAL_RUNTIME_STATES, STARTABLE_RUNTIME_STATES, STOPPABLE_RUNTIME_STATES, TRANSITIONAL_RUNTIME_STATES, isRuntimeState, isRuntimeReady, isRuntimeFailed, isRuntimeTransitioning, isRuntimeTerminal, canStartRuntime, canStopRuntime, canTransitionRuntime, assertRuntimeState, assertRuntimeTransition, createRuntimeStateSnapshot, createRuntimeStateTransition, getRuntimeStateLabel, getRuntimeStates, getNextRuntimeStates, InvalidRuntimeStateError, InvalidRuntimeTransitionError, } from "./runtimeState.state.js";
-export type { RuntimeStateSnapshot, RuntimeStateTransition, } from "./runtimeState.state.js";
-export { DefaultRuntimeContext, createRuntimeId, createRuntimeIdentity, createRuntimeContext, } from "./runtimeContext/index.js";
-export type { RuntimeIdentity, RuntimeTiming, RuntimeContextDependencies, RuntimeContext, RuntimeContextState, } from "./runtimeContext/index.js";
-export { DefaultRuntimeEnvironment, createRuntimeEnvironment, detectRuntimeEngine, detectPlatform, detectProcessInfo, detectHostInfo, detectCI, detectContainer, RuntimeEnvironmentError, } from "./runtimeEnvironment/index.js";
-export type { RuntimePlatform, RuntimeEngine, RuntimeEnvironmentVariables, RuntimeProcessInfo, RuntimeHostInfo, RuntimeEngineInfo, RuntimeEnvironmentInfo, RuntimeEnvironment, RuntimeEnvironmentOptions, } from "./runtimeEnvironment/index.js";
-export { DefaultRuntimeManager, createRuntimeManager, RuntimeManagerError, } from "./runtimeManager/index.js";
-export type { RuntimeManagerDependencies, RuntimeManager, } from "./runtimeManager/index.js";
-export { DefaultRuntimeBootstrap, RuntimeBootstrapError, } from "./runtimeBootstrap/index.js";
-export type { RuntimeBootstrapDependencies, RuntimeBootstrapOptions, RuntimeBootstrapPhase, RuntimeBootstrapResult, RuntimeBootstrapErrorInfo, } from "./runtimeBootstrap/index.js";
-export { DefaultRuntimeShutdown, RuntimeShutdownError, } from "./runtimeShutdown/index.js";
-export type { RuntimeShutdownDependencies, RuntimeShutdownConfig, RuntimeShutdownPhase, RuntimeShutdownResult, RuntimeShutdownErrorInfo, } from "./runtimeShutdown/index.js";
-export { RuntimeError, RuntimeErrorCode, RuntimeStateError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeLoadError, RuntimeTimeoutError, RuntimeDependencyError, RuntimeNotReadyError, RuntimeUnsupportedOperationError, RuntimeCancellationError, toRuntimeError, isRuntimeError, hasRuntimeErrorCode, createRuntimeError, } from "./runtimeError/index.js";
+export type { RuntimeMode, RuntimeRole, RuntimeOptions, RuntimeStartupOptions, RuntimeShutdownOptions, RuntimeSignalOptions, RuntimeDiagnosticsOptions, RuntimeEnvironmentOverrides, ResolvedRuntimeOptions, } from "./runtimeOptions/index.js";
+export { RuntimeState, TERMINAL_RUNTIME_STATES, STARTABLE_RUNTIME_STATES, STOPPABLE_RUNTIME_STATES, TRANSITIONAL_RUNTIME_STATES, isRuntimeState, isRuntimeReady, isRuntimeFailed, isRuntimeTransitioning, isRuntimeTerminal, canStartRuntime, canStopRuntime, canTransitionRuntime, assertRuntimeState, assertRuntimeTransition, createRuntimeStateSnapshot, createRuntimeStateTransition, getRuntimeStateLabel, getRuntimeStates, getNextRuntimeStates, } from "./runtimeState.state.js";
+export type { RuntimeStateSnapshot, RuntimeStateTransition, RuntimeTiming, } from "./runtimeState.state.js";
+export { createRuntimeId, createRuntimeIdentity, createRuntimeExecutionContext, createRuntimeContext, } from "./runtimeContext/index.js";
+export type { RuntimeIdentity, RuntimeExecutionMetadata, RuntimeExecutionContext, RuntimeContext, } from "./runtimeContext/index.js";
+export { DefaultRuntimeEnvironment, createRuntimeEnvironment, detectRuntimeEngine, detectPlatform, detectProcessInfo, detectHostInfo, detectCI, detectContainer, MissingEnvironmentVariableError, } from "./runtimeEnvironment/index.js";
+export type { RuntimePlatform, RuntimeEngine, RuntimeEnvironmentVariables, RuntimeProcessInfo, RuntimeHostInfo, RuntimeEngineInfo, RuntimeEnvironmentInfo, RuntimeEnvironmentSummary, RuntimeEnvironment, RuntimeEnvironmentOptions, } from "./runtimeEnvironment/index.js";
+export { DefaultRuntimeBootstrap } from "./runtimeBootstrap/index.js";
+export type { RuntimeBootstrap, RuntimeBootstrapDependencies, RuntimeBootstrapOptions, RuntimeBootstrapPhase, RuntimeBootstrapResult, RuntimeBootstrapErrorInfo, } from "./runtimeBootstrap/index.js";
+export { DefaultRuntimeShutdown } from "./runtimeShutdown/index.js";
+export type { RuntimeShutdown, RuntimeShutdownDependencies, RuntimeShutdownConfig, RuntimeShutdownPhase, RuntimeShutdownResult, RuntimeShutdownErrorInfo, } from "./runtimeShutdown/index.js";
+export { RuntimeSignalManager } from "./runtimeSignals/index.js";
+export type { RuntimeTerminationSignal, RuntimeProcessEvent, RuntimeSignalTarget, RuntimeSignalHandlers, RuntimeSignalManagerOptions, } from "./runtimeSignals/index.js";
+export { withRuntimeTimeout } from "./runtimeTimeout.js";
+export type { TimeoutAwareOperation, RuntimeTimeoutOptions, } from "./runtimeTimeout.js";
+export { RuntimeError, RuntimeErrorCode, InvalidRuntimeStateError, InvalidRuntimeTransitionError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeLoadError, RuntimeTimeoutError, RuntimeDependencyError, RuntimeNotReadyError, RuntimeUnsupportedOperationError, RuntimeCancellationError, toRuntimeError, isRuntimeError, hasRuntimeErrorCode, createRuntimeError, } from "./runtimeError/index.js";
 export type { RuntimeOperation, RuntimeErrorPhase, RuntimeErrorMetadata, RuntimeErrorOptions, RuntimeErrorJSON, } from "./runtimeError/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -14,29 +14,33 @@ export { DEFAULT_RUNTIME_OPTIONS, resolveRuntimeOptions, validateRuntimeOptions,
 /*
  * Runtime state
  */
-export { RuntimeState, TERMINAL_RUNTIME_STATES, STARTABLE_RUNTIME_STATES, STOPPABLE_RUNTIME_STATES, TRANSITIONAL_RUNTIME_STATES, isRuntimeState, isRuntimeReady, isRuntimeFailed, isRuntimeTransitioning, isRuntimeTerminal, canStartRuntime, canStopRuntime, canTransitionRuntime, assertRuntimeState, assertRuntimeTransition, createRuntimeStateSnapshot, createRuntimeStateTransition, getRuntimeStateLabel, getRuntimeStates, getNextRuntimeStates, InvalidRuntimeStateError, InvalidRuntimeTransitionError, } from "./runtimeState.state.js";
+export { RuntimeState, TERMINAL_RUNTIME_STATES, STARTABLE_RUNTIME_STATES, STOPPABLE_RUNTIME_STATES, TRANSITIONAL_RUNTIME_STATES, isRuntimeState, isRuntimeReady, isRuntimeFailed, isRuntimeTransitioning, isRuntimeTerminal, canStartRuntime, canStopRuntime, canTransitionRuntime, assertRuntimeState, assertRuntimeTransition, createRuntimeStateSnapshot, createRuntimeStateTransition, getRuntimeStateLabel, getRuntimeStates, getNextRuntimeStates, } from "./runtimeState.state.js";
 /*
  * Runtime context
  */
-export { DefaultRuntimeContext, createRuntimeId, createRuntimeIdentity, createRuntimeContext, } from "./runtimeContext/index.js";
+export { createRuntimeId, createRuntimeIdentity, createRuntimeExecutionContext, createRuntimeContext, } from "./runtimeContext/index.js";
 /*
  * Runtime environment
  */
-export { DefaultRuntimeEnvironment, createRuntimeEnvironment, detectRuntimeEngine, detectPlatform, detectProcessInfo, detectHostInfo, detectCI, detectContainer, RuntimeEnvironmentError, } from "./runtimeEnvironment/index.js";
-/*
- * Runtime manager
- */
-export { DefaultRuntimeManager, createRuntimeManager, RuntimeManagerError, } from "./runtimeManager/index.js";
+export { DefaultRuntimeEnvironment, createRuntimeEnvironment, detectRuntimeEngine, detectPlatform, detectProcessInfo, detectHostInfo, detectCI, detectContainer, MissingEnvironmentVariableError, } from "./runtimeEnvironment/index.js";
 /*
  * Runtime bootstrap
  */
-export { DefaultRuntimeBootstrap, RuntimeBootstrapError, } from "./runtimeBootstrap/index.js";
+export { DefaultRuntimeBootstrap } from "./runtimeBootstrap/index.js";
 /*
  * Runtime shutdown
  */
-export { DefaultRuntimeShutdown, RuntimeShutdownError, } from "./runtimeShutdown/index.js";
+export { DefaultRuntimeShutdown } from "./runtimeShutdown/index.js";
+/*
+ * Runtime signals
+ */
+export { RuntimeSignalManager } from "./runtimeSignals/index.js";
+/*
+ * Runtime timeout
+ */
+export { withRuntimeTimeout } from "./runtimeTimeout.js";
 /*
  * Runtime errors
  */
-export { RuntimeError, RuntimeErrorCode, RuntimeStateError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeLoadError, RuntimeTimeoutError, RuntimeDependencyError, RuntimeNotReadyError, RuntimeUnsupportedOperationError, RuntimeCancellationError, toRuntimeError, isRuntimeError, hasRuntimeErrorCode, createRuntimeError, } from "./runtimeError/index.js";
+export { RuntimeError, RuntimeErrorCode, InvalidRuntimeStateError, InvalidRuntimeTransitionError, RuntimeStartError, RuntimeStopError, RuntimeInitializationError, RuntimeLoadError, RuntimeTimeoutError, RuntimeDependencyError, RuntimeNotReadyError, RuntimeUnsupportedOperationError, RuntimeCancellationError, toRuntimeError, isRuntimeError, hasRuntimeErrorCode, createRuntimeError, } from "./runtimeError/index.js";
 //# sourceMappingURL=index.js.map

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