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

@@ -11,20 +11,154 @@ npm install @zudojs/core
 ## Quick Start
 
 ```typescript
-import { createApplication } from "@zudojs/core";
+import { createApplication, defineModule } from "@zudojs/core";
 
-const app = await createApplication();
+const app = await createApplication({
+  modules: [
+    defineModule({
+      id: "users",
+      name: "Users",
+      factory: () => ({
+        id: "users",
+        name: "Users",
+        onInitialize: async () => {
+          /* prepare resources */
+        },
+        onShutdown: async () => {
+          /* release resources */
+        },
+      }),
+    }),
+  ],
+  runtime: {
+    name: "my-service",
+    mode: "production",
+    signals: { handleSigint: true, handleSigterm: true },
+  },
+});
 
-await app.start();
-await app.stop();
+await app.start(); // loads, initializes, and starts modules
+await app.stop(); // stops and destroys modules
+await app.start(); // restart: a fresh runtime is created
+await app.shutdown(); // stop + dispose; cannot be restarted afterwards
 ```
 
+`createApplication` wires the standard graph (container, configuration manager, logger, module registry/loader/lifecycle, runtime, application lifecycle). Every piece can also be assembled by hand:
+
+```typescript
+import {
+  Application,
+  ApplicationContext,
+  Lifecycle,
+  createRuntime,
+} from "@zudojs/core";
+
+const lifecycle = new Lifecycle();
+lifecycle.register({
+  name: "http-server",
+  start: async () => server.listen(),
+  stop: async () => server.close(),
+});
+
+const app = await Application.create({
+  lifecycle,
+  runtime: () => createRuntime(dependencies, options), // factory enables restart
+});
+```
+
+## Runtime
+
+`createRuntime(dependencies, options)` returns a single-use runtime:
+
+```
+CREATED → BOOTSTRAPPING → READY → STOPPING → STOPPED
+FAILED is reachable from every non-terminal state via fail() or a failure.
+```
+
+- `start()` loads, initializes, and starts modules through the bootstrap pipeline; `getStatus().bootstrap` reports counts, errors, and duration.
+- `stop()` stops and destroys modules through the shutdown pipeline; `getStatus().shutdown` reports the same.
+- `startup.timeoutMs` / `shutdown.timeoutMs` abort the pipeline with a `RuntimeTimeoutError`; the abandoned pipeline can never surface an unhandled rejection.
+- `continueOnInitializeError` / `continueOnStartError` (and the stop/destroy equivalents) make the runtime finish with `success: false` and the failures listed instead of throwing.
+- Every error the runtime throws extends `RuntimeError` (which itself extends `RuntimeError` from `@zudojs/errors`), so `isRuntimeError()` from either package recognises it.
+- `runtime.context` is the runtime's immutable `RuntimeExecutionContext` (`executionId` = runtime id, `service` = runtime name, `metadata.runtimeId/runtimeName/runtimeMode/runtimeRole` plus `RuntimeOptions.metadata`); `runtime.timing` holds the state-transition timestamps; `runtime.contextStorage` is the `ContextStorage` the context is established in (`RuntimeDependencies.contextStorage`, default `getDefaultContextStorage()`).
+
+### Signals
+
+When `signals.handleSigint` / `handleSigterm` / `handleSighup` are on (SIGINT and SIGTERM default to on), the runtime registers handlers on start and removes them on stop, failure, or dispose. The first signal triggers a graceful `stop()`. A second signal during shutdown is logged and ignored unless `signals.forceExitOnSecondSignal` is explicitly enabled, in which case the process exits with `signals.forceExitCode`. `handleUncaughtException` / `handleUnhandledRejection` mark the runtime failed and stop it. The runtime never calls `process.exit()` otherwise.
+
+## Modules
+
+Modules implement the `Module` contract and are driven by `ModuleLifecycleManager` in dependency order:
+
+```
+onInitialize → onReady → onShutdown → onDestroy
+```
+
+- Register definitions with `defineModule(...)` (or subclass `BaseModule`); dependencies may be plain ids or `{ id, optional, version }` objects, and version constraints (`^`, `~`, `>=`, exact) are checked when the graph is built.
+- Dependents are skipped when a dependency fails, and modules initialized before a failure are rolled back (stopped and destroyed).
+- `unloadModule(id)` stops, destroys, and forgets a module (refused while loaded dependents exist); `replaceModule(definition)` shuts the old instance down first.
+- Only the documented `on*` hooks are invoked. The legacy `initialize/start/stop/destroy` names are no longer called.
+
+## Configuration
+
+`createConfigurationManager({ registry, schemas, loaderOptions, validationOptions, redactorOptions })` loads registered sources by priority, deep-merges them, applies schema defaults, validates, and exposes an immutable `Configuration`.
+
+- `manager.on(type, listener)` / `manager.off(...)` receive the `configuration.initializing`, `configuration.loaded`, `configuration.validated`, `configuration.ready`, `configuration.failed`, `configuration.reloading`, and `configuration.reloaded` events (`"*"` subscribes to all of them).
+- `manager.getSection(name)` returns a scoped configuration for a registered section; `manager.reload()` keeps programmatic defaults and serialises overlapping reloads.
+- Values are deep-frozen; `toObject()` returns an independent deep copy. Path lookups never walk the prototype chain, and `getNumber` accepts only plain decimal numbers.
+- Secrets never reach errors or logs: validation, load, and source errors pass through the redactor, which matches whole key words (`password`, `secret`, `token`, `pwd`, `passphrase`, `auth`, `dsn`, `credential`, ...).
+
+## Logging
+
+`new ConsoleLogger({ level, structured, service, version, environment, context, redact })` emits structured JSON (circular and `BigInt` safe) or human-readable output.
+
+- `logger.child({ moduleId })` merges the context into every entry it emits; `LoggerOptions.context` is attached to every entry.
+- `LoggerOptions.contextStorage` makes the logger merge `executionId`, `correlationId`, `traceId`, `spanId`, and `runtimeId` from the active execution context beneath its own context (explicit values win). `createApplication` sets it on the logger it creates.
+- An unknown `level` throws `InvalidArgumentError` at construction rather than silently disabling logging.
+- Error causes are serialised recursively with a depth limit; `redact` (see `createLogRedactor()`) is applied to context and error details.
+- `trace` output goes through `console.debug`, so the structured-output invariant holds.
+
+## Execution context
+
+There is one execution-context model: the immutable `ExecutionContext` (`createExecutionContext`, `deriveExecutionContext`, `withExecutionMetadata`) propagated by `ContextStorage`, which wraps `AsyncLocalStorage`. `run(context, fn)` and `runDerived(overrides, fn)` establish a context for the callback and everything it awaits, `runWithValues(context, values, fn)` additionally binds a `ContextValues` collection (read back with `getValues()`), and `capture()` / `runSnapshot(snapshot, fn)` carry a context across queue or timer boundaries. `getDefaultContextStorage()` is the process-wide instance every component uses unless another is injected.
+
+Propagation is real at runtime:
+
+- `runtime.start()` and `runtime.stop()` run the bootstrap and shutdown pipelines inside `runtime.contextStorage.run(runtime.context, ...)`.
+- Each module hook (`onInitialize`, `onReady`, `onShutdown`, `onDestroy`) runs in a context derived from it: `module` is the module id, `operation` is the hook name, and `{ moduleId, phase }` is merged into `metadata`. `ModuleLifecycleOptions.contextStorage` selects the storage (default: the shared one).
+- `Application.start()` / `stop()` / `shutdown()` run lifecycle participants inside the runtime's context as well.
+- `createApplication` threads one storage (`CreateApplicationOptions.contextStorage`) through the `ApplicationContext` (`getContextStorage()`), the container's `currentScope` (so `"scoped"` providers resolve once per execution context), the module lifecycle, the runtime, and the logger.
+
+```typescript
+import { defineModule, getDefaultContextStorage } from "@zudojs/core";
+
+defineModule({
+  id: "users",
+  name: "Users",
+  factory: () => ({
+    id: "users",
+    name: "Users",
+    onInitialize: async () => {
+      const context = getDefaultContextStorage().require();
+      // context.executionId === runtime.identity.id
+      // context.metadata.moduleId === "users", context.metadata.phase === "initializing"
+    },
+  }),
+});
+```
+
+The former mutable `Context` class and `DefaultRuntimeContext` are gone; `Context`, `createContext`, `RuntimeContext`, and `createRuntimeContext` remain as deprecated aliases of the canonical names.
+
 ## Features
 
 - Application lifecycle management (start, stop, restart)
-- Execution context propagation using `AsyncLocalStorage`
-- Runtime state machine with dependency ordering
-- Signal handling for graceful shutdown (SIGINT, SIGTERM)
+- Execution context propagation via `ContextStorage` (`AsyncLocalStorage`)
+- Dependency-ordered module lifecycle with rollback on failure
+- Configuration loading, validation, schema defaults, redaction, and events
+- Structured, redaction-aware logging
+- Runtime state machine with dependency-ordered module lifecycle
+- Signal handling for graceful shutdown (SIGINT, SIGTERM, SIGHUP)
+- Dependency injection container with singleton, scoped (per execution context), and transient lifetimes
 
 ## Use Cases
 

package/dist/application/application.d.ts

@@ -2,24 +2,65 @@ import type { ApplicationContext } from "./applicationContext.context.js";
 import type { ApplicationState } from "./applicationState.state.js";
 import type { Lifecycle } from "../lifecycle/core/lifecycle.js";
 import type { Runtime } from "../runtime/runtime.js";
+/**
+ * Creates a fresh Runtime. Because a Runtime is single-use, an
+ * Application needs a factory to support restart.
+ */
+export type RuntimeFactory = () => Runtime;
 export interface ApplicationOptions {
     readonly context?: ApplicationContext;
     readonly lifecycle?: Lifecycle;
-    readonly runtime?: Runtime;
+    /**
+     * The runtime to orchestrate, or a factory that creates one. With
+     * a factory, every start after a stop gets a new runtime so the
+     * application can be restarted; with an instance, restart throws.
+     */
+    readonly runtime?: Runtime | RuntimeFactory;
 }
+/**
+ * Top-level application object.
+ *
+ * Orchestrates an optional Lifecycle (application-level participants)
+ * and an optional Runtime (module subsystem): start() runs the
+ * lifecycle first and then the runtime; stop() unwinds in reverse.
+ *
+ * When a runtime is present, start(), stop(), and shutdown() run
+ * inside the runtime's execution context (`runtime.contextStorage`
+ * / `runtime.context`), so lifecycle participants observe the same
+ * context as module hooks.
+ */
 export declare class Application {
     private readonly context?;
     private readonly lifecycle?;
-    private readonly runtime?;
+    private readonly runtimeFactory?;
+    private runtime?;
     private _state;
     private constructor();
     static create(options?: ApplicationOptions): Promise<Application>;
     get state(): ApplicationState;
     get applicationContext(): ApplicationContext | undefined;
+    /**
+     * The current runtime, if any. Changes across restarts when a
+     * runtime factory is used.
+     */
     get applicationRuntime(): Runtime | undefined;
     initialize(): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * Stops the application and releases lifecycle resources. The
+     * application cannot be restarted afterwards.
+     */
     shutdown(): Promise<void>;
+    /**
+     * Runs an operation inside the runtime's execution context, or
+     * directly when the application has no runtime.
+     */
+    private inRuntimeContext;
+    /**
+     * Returns a startable runtime: the configured instance while it is
+     * unused, or a new one from the factory after a stop/failure.
+     */
+    private ensureRuntime;
 }
 //# sourceMappingURL=application.d.ts.map

package/dist/application/application.js

@@ -1,12 +1,32 @@
+import { RuntimeState } from "../runtime/runtimeState.state.js";
+import { InvalidStateError } from "../errors/exceptions.js";
+/**
+ * Top-level application object.
+ *
+ * Orchestrates an optional Lifecycle (application-level participants)
+ * and an optional Runtime (module subsystem): start() runs the
+ * lifecycle first and then the runtime; stop() unwinds in reverse.
+ *
+ * When a runtime is present, start(), stop(), and shutdown() run
+ * inside the runtime's execution context (`runtime.contextStorage`
+ * / `runtime.context`), so lifecycle participants observe the same
+ * context as module hooks.
+ */
 export class Application {
     context;
     lifecycle;
+    runtimeFactory;
     runtime;
     _state;
     constructor(options = {}) {
         this.context = options.context;
         this.lifecycle = options.lifecycle;
-        this.runtime = options.runtime;
+        if (typeof options.runtime === "function") {
+            this.runtimeFactory = options.runtime;
+        }
+        else {
+            this.runtime = options.runtime;
+        }
         this._state = "created";
     }
     static async create(options = {}) {
@@ -20,6 +40,10 @@ export class Application {
     get applicationContext() {
         return this.context;
     }
+    /**
+     * The current runtime, if any. Changes across restarts when a
+     * runtime factory is used.
+     */
     get applicationRuntime() {
         return this.runtime;
     }
@@ -45,11 +69,17 @@ export class Application {
             await this.initialize();
         }
         if (this._state !== "initialized" && this._state !== "stopped") {
-            throw new Error(`Application cannot start from state "${this._state}".`);
+            throw new InvalidStateError(`Application cannot start from state "${this._state}".`, { state: this._state });
         }
+        // Resolve the runtime first so a refused restart leaves the
+        // application untouched.
+        const runtime = this.ensureRuntime();
         this._state = "starting";
         try {
-            await this.lifecycle?.start();
+            await this.inRuntimeContext(runtime, async () => {
+                await this.lifecycle?.start();
+                await runtime?.start();
+            });
             this._state = "running";
         }
         catch (error) {
@@ -64,23 +94,91 @@ export class Application {
             return;
         }
         if (this._state !== "running" && this._state !== "failed") {
-            throw new Error(`Application cannot stop from state "${this._state}".`);
+            throw new InvalidStateError(`Application cannot stop from state "${this._state}".`, { state: this._state });
         }
         this._state = "stopping";
-        try {
-            await this.lifecycle?.stop();
-            this._state = "stopped";
-        }
-        catch (error) {
+        const errors = [];
+        const runtime = this.runtime;
+        await this.inRuntimeContext(runtime, async () => {
+            try {
+                await runtime?.stop();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await this.lifecycle?.stop();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        });
+        if (errors.length > 0) {
             this._state = "failed";
-            throw error;
+            if (errors.length === 1)
+                throw errors[0];
+            throw new AggregateError(errors, "Application stop completed with errors.");
         }
+        this._state = "stopped";
     }
+    /**
+     * Stops the application and releases lifecycle resources. The
+     * application cannot be restarted afterwards.
+     */
     async shutdown() {
-        if (this._state === "stopped") {
-            return;
+        const errors = [];
+        const runtime = this.runtime;
+        await this.inRuntimeContext(runtime, async () => {
+            try {
+                await this.stop();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await runtime?.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+            try {
+                await this.lifecycle?.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        });
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, "Application shutdown completed with errors.");
+        }
+    }
+    /**
+     * Runs an operation inside the runtime's execution context, or
+     * directly when the application has no runtime.
+     */
+    inRuntimeContext(runtime, operation) {
+        if (!runtime)
+            return operation();
+        return runtime.contextStorage.run(runtime.context, operation);
+    }
+    /**
+     * Returns a startable runtime: the configured instance while it is
+     * unused, or a new one from the factory after a stop/failure.
+     */
+    ensureRuntime() {
+        const current = this.runtime;
+        const reusable = current !== undefined && current.state === RuntimeState.CREATED;
+        if (reusable)
+            return current;
+        if (this.runtimeFactory) {
+            this.runtime = this.runtimeFactory();
+            return this.runtime;
         }
-        await this.stop();
+        if (current === undefined)
+            return undefined;
+        throw new InvalidStateError(`Application runtime is "${current.state}" and cannot be restarted; supply a runtime factory to enable restart.`, { runtimeState: current.state });
     }
 }
 //# sourceMappingURL=application.js.map

package/dist/application/applicationContext.context.d.ts

@@ -2,11 +2,25 @@ import type { Container } from "../container/container.js";
 import type { Configuration } from "../configuration/core/configuration.js";
 import type { ModuleRegistry } from "../modules/moduleRegistry/index.js";
 import type { Logger } from "../logging/core/logger.js";
+import type { ContextStorage } from "../context/provider/contextStorage.storage.js";
 export interface ApplicationContextOptions {
     readonly container: Container;
-    readonly configuration: Configuration;
+    /**
+     * The application configuration, or a function returning the
+     * current one. Pass a function (for example
+     * `() => manager.getConfiguration()`) so that
+     * `getConfiguration()` reflects configuration reloads instead of
+     * the snapshot taken when the context was created.
+     */
+    readonly configuration: Configuration | (() => Configuration);
     readonly modules: ModuleRegistry;
     readonly logger: Logger;
+    /**
+     * ContextStorage the application's runtime propagates its
+     * execution context through. Defaults to
+     * getDefaultContextStorage().
+     */
+    readonly contextStorage?: ContextStorage;
 }
 /**
  * Provides access to the core services and state of a Zudojs application.
@@ -19,6 +33,7 @@ export declare class ApplicationContext {
     private readonly configuration;
     private readonly modules;
     private readonly logger;
+    private readonly contextStorage;
     constructor(options: ApplicationContextOptions);
     /**
      * Dependency injection container.
@@ -26,6 +41,10 @@ export declare class ApplicationContext {
     getContainer(): Container;
     /**
      * Application configuration.
+     *
+     * When the context was created with a configuration accessor
+     * (as `createApplication` does), this returns the configuration
+     * manager's current configuration, including reloads.
      */
     getConfiguration(): Configuration;
     /**
@@ -36,5 +55,12 @@ export declare class ApplicationContext {
      * Application logger.
      */
     getLogger(): Logger;
+    /**
+     * Execution context storage. Inside module hooks, container
+     * factories, and lifecycle participants driven by the runtime,
+     * `getContextStorage().get()` returns the runtime's execution
+     * context.
+     */
+    getContextStorage(): ContextStorage;
 }
 //# sourceMappingURL=applicationContext.context.d.ts.map

package/dist/application/applicationContext.context.js

@@ -1,3 +1,4 @@
+import { getDefaultContextStorage } from "../context/provider/defaultContextStorage.storage.js";
 /**
  * Provides access to the core services and state of a Zudojs application.
  *
@@ -9,11 +10,17 @@ export class ApplicationContext {
     configuration;
     modules;
     logger;
+    contextStorage;
     constructor(options) {
         this.container = options.container;
-        this.configuration = options.configuration;
+        const configuration = options.configuration;
+        this.configuration =
+            typeof configuration === "function"
+                ? configuration
+                : () => configuration;
         this.modules = options.modules;
         this.logger = options.logger;
+        this.contextStorage = options.contextStorage ?? getDefaultContextStorage();
     }
     /**
      * Dependency injection container.
@@ -23,9 +30,13 @@ export class ApplicationContext {
     }
     /**
      * Application configuration.
+     *
+     * When the context was created with a configuration accessor
+     * (as `createApplication` does), this returns the configuration
+     * manager's current configuration, including reloads.
      */
     getConfiguration() {
-        return this.configuration;
+        return this.configuration();
     }
     /**
      * Registered application modules.
@@ -39,5 +50,14 @@ export class ApplicationContext {
     getLogger() {
         return this.logger;
     }
+    /**
+     * Execution context storage. Inside module hooks, container
+     * factories, and lifecycle participants driven by the runtime,
+     * `getContextStorage().get()` returns the runtime's execution
+     * context.
+     */
+    getContextStorage() {
+        return this.contextStorage;
+    }
 }
 //# sourceMappingURL=applicationContext.context.js.map

package/dist/application/createApplication.d.ts

@@ -0,0 +1,78 @@
+import { Application } from "./application.js";
+import { Container } from "../container/container.js";
+import { ConfigurationManager } from "../configuration/configurationManager.manager.js";
+import type { Logger } from "../logging/core/logger.js";
+import type { LoggerOptions } from "../logging/core/loggerOptions.options.js";
+import type { LifecycleParticipant } from "../lifecycle/core/lifecycle.js";
+import type { ModuleDefinition } from "../modules/moduleDefinition.definition.js";
+import type { ModuleRegistry } from "../modules/moduleRegistry/index.js";
+import type { RuntimeOptions } from "../runtime/runtimeOptions/runtimeOptions.type.js";
+import type { RuntimeSignalTarget } from "../runtime/runtimeSignals/runtimeSignals.js";
+import type { ContextStorage } from "../context/provider/contextStorage.storage.js";
+/**
+ * Options for {@link createApplication}.
+ */
+export interface CreateApplicationOptions {
+    /**
+     * Module definitions to register before the runtime starts.
+     */
+    readonly modules?: readonly ModuleDefinition[];
+    /**
+     * Application-level lifecycle participants (registered on the
+     * application Lifecycle in order).
+     */
+    readonly participants?: readonly LifecycleParticipant[];
+    /**
+     * Runtime options (name, mode, role, startup/shutdown/signal
+     * behaviour). The startup/shutdown continueOn*Error flags are also
+     * applied to the module lifecycle manager so both layers agree.
+     */
+    readonly runtime?: RuntimeOptions;
+    /**
+     * Pre-built configuration manager. Initialized here if it has not
+     * been initialized yet.
+     */
+    readonly configuration?: ConfigurationManager;
+    /**
+     * Logger, or options for the default ConsoleLogger.
+     */
+    readonly logger?: Logger | LoggerOptions;
+    /**
+     * Dependency container for the application context. When omitted a
+     * Container whose `currentScope` is the current execution context
+     * (from `contextStorage`) is created, so "scoped" providers resolve
+     * to one instance per execution context.
+     */
+    readonly container?: Container;
+    /**
+     * ContextStorage shared by the application context, container
+     * scoping, module lifecycle, runtime, and (when the logger is
+     * created here) the logger. Defaults to getDefaultContextStorage().
+     */
+    readonly contextStorage?: ContextStorage;
+    /**
+     * Module registry; created when omitted.
+     */
+    readonly moduleRegistry?: ModuleRegistry;
+    /**
+     * Process-like target for signal handling (tests inject an emitter).
+     */
+    readonly signalTarget?: RuntimeSignalTarget;
+    /**
+     * Start the application before returning. Defaults to false.
+     */
+    readonly autoStart?: boolean;
+}
+/**
+ * Wires the standard application graph — container, configuration,
+ * logger, module registry/loader/lifecycle, runtime, and application
+ * lifecycle — and returns an initialized Application. One
+ * ContextStorage is threaded through every piece, so the runtime's
+ * execution context is visible from module hooks, container
+ * factories, lifecycle participants, and log entries.
+ *
+ * The runtime is created through a factory, so the application can be
+ * restarted (stop() then start()) with a fresh runtime each time.
+ */
+export declare function createApplication(options?: CreateApplicationOptions): Promise<Application>;
+//# sourceMappingURL=createApplication.d.ts.map