@zudojs/core 0.0.1 → 1.0.0

package/dist/context/index.js

@@ -1,5 +1,25 @@
 /**
  * Execution context.
+ *
+ * The framework has one execution-context model:
+ *
+ * - ExecutionContext (core/) is an immutable description of one
+ *   execution (ids, tracing, principal, metadata). New contexts are
+ *   created with createExecutionContext and refined with
+ *   deriveExecutionContext / withExecutionMetadata.
+ * - ContextStorage (provider/) propagates the current
+ *   ExecutionContext across async boundaries via AsyncLocalStorage.
+ *   getDefaultContextStorage() is the shared instance the runtime,
+ *   module lifecycle, application, container, and logger use unless
+ *   another storage is injected.
+ * - ContextValues (values/) carries strongly typed per-execution
+ *   values; ContextStorage.runWithValues / getValues / capture /
+ *   runSnapshot connect them to the storage, and ContextSnapshot
+ *   (snapshot/) carries both across scheduling boundaries.
+ *
+ * The runtime runs its bootstrap and shutdown pipelines, every
+ * module lifecycle hook, and application start/stop inside the
+ * runtime's own ExecutionContext (see RuntimeExecutionContext).
  */
 export * from "./core/index.js";
 export * from "./provider/index.js";

package/dist/context/provider/contextProvider.provider.d.ts

@@ -1,5 +1,5 @@
 import type { ExecutionContext } from "../core/executionContext.context.js";
-import { ContextStorage } from "../provider/contextStorage.storage.js";
+import type { ContextStorage } from "./contextStorage.storage.js";
 /**
  * Provides access to the current execution context.
  *
@@ -32,7 +32,9 @@ export interface ContextProvider {
  * Default ContextProvider implementation.
  *
  * Uses ContextStorage internally while keeping that
- * implementation detail hidden behind the provider contract.
+ * implementation detail hidden behind the provider contract. When
+ * no storage is supplied the process-wide default storage is used,
+ * so the provider observes the same context the runtime establishes.
  */
 export declare class DefaultContextProvider implements ContextProvider {
     private readonly storage;
@@ -55,7 +57,8 @@ export declare class DefaultContextProvider implements ContextProvider {
     run<T>(context: ExecutionContext, callback: () => T): T;
 }
 /**
- * Creates the default framework context provider.
+ * Creates the default framework context provider, optionally bound
+ * to a specific ContextStorage.
  */
-export declare function createContextProvider(): ContextProvider;
+export declare function createContextProvider(storage?: ContextStorage): ContextProvider;
 //# sourceMappingURL=contextProvider.provider.d.ts.map

package/dist/context/provider/contextProvider.provider.js

@@ -1,13 +1,15 @@
-import { ContextStorage } from "../provider/contextStorage.storage.js";
+import { getDefaultContextStorage } from "./defaultContextStorage.storage.js";
 /**
  * Default ContextProvider implementation.
  *
  * Uses ContextStorage internally while keeping that
- * implementation detail hidden behind the provider contract.
+ * implementation detail hidden behind the provider contract. When
+ * no storage is supplied the process-wide default storage is used,
+ * so the provider observes the same context the runtime establishes.
  */
 export class DefaultContextProvider {
     storage;
-    constructor(storage = new ContextStorage()) {
+    constructor(storage = getDefaultContextStorage()) {
         this.storage = storage;
     }
     /**
@@ -36,9 +38,10 @@ export class DefaultContextProvider {
     }
 }
 /**
- * Creates the default framework context provider.
+ * Creates the default framework context provider, optionally bound
+ * to a specific ContextStorage.
  */
-export function createContextProvider() {
-    return new DefaultContextProvider();
+export function createContextProvider(storage) {
+    return new DefaultContextProvider(storage);
 }
 //# sourceMappingURL=contextProvider.provider.js.map

package/dist/context/provider/contextStorage.storage.d.ts

@@ -1,4 +1,15 @@
 import type { ExecutionContext } from "../core/executionContext.context.js";
+import { ContextValues } from "../values/contextValues.values.js";
+import type { ContextSnapshot } from "../snapshot/contextSnapshot.snapshot.js";
+/**
+ * Overrides accepted when deriving an execution context from
+ * the current one.
+ */
+export type ExecutionContextOverrides = Partial<Omit<ExecutionContext, "executionId" | "startedAt" | "metadata">> & {
+    readonly executionId?: string;
+    readonly startedAt?: Date;
+    readonly metadata?: Record<string, unknown>;
+};
 /**
  * Stores the current ExecutionContext across asynchronous
  * boundaries.
@@ -6,9 +17,14 @@ import type { ExecutionContext } from "../core/executionContext.context.js";
  * This allows framework components to access the current
  * execution without explicitly passing the context through
  * every function call.
+ *
+ * Alongside the ExecutionContext, an optional ContextValues
+ * collection can travel with the execution, connecting typed
+ * context values to the async storage.
  */
 export declare class ContextStorage {
     private readonly storage;
+    private readonly valuesStorage;
     /**
      * Runs a function inside an execution context.
      *
@@ -33,19 +49,43 @@ export declare class ContextStorage {
      */
     has(): boolean;
     /**
-     * Executes a callback with a derived execution context.
-     */
-    runWith<T>(context: ExecutionContext, callback: () => T): T;
-    /**
-     * Executes a callback using the current context with
-     * a temporary derived context.
+     * Executes a callback within a context derived from the
+     * current one.
+     *
+     * The current context is read from storage and combined with
+     * the supplied overrides via deriveExecutionContext, so
+     * correlation and tracing information propagates into the
+     * derived scope. Throws when no context is active.
      */
-    runDerived<T>(context: ExecutionContext, callback: () => T): T;
+    runDerived<T>(overrides: ExecutionContextOverrides, callback: () => T): T;
     /**
      * Clears the current execution context by executing the
      * callback outside the current storage context.
      */
     runWithoutContext<T>(callback: () => T): T;
+    /**
+     * Runs a callback with both an execution context and a typed
+     * ContextValues collection bound to the async scope.
+     */
+    runWithValues<T>(context: ExecutionContext, values: ContextValues, callback: () => T): T;
+    /**
+     * Returns the ContextValues bound to the current async scope,
+     * when one was provided via runWithValues or runSnapshot.
+     */
+    getValues(): ContextValues | undefined;
+    /**
+     * Captures the current execution context and its values as an
+     * immutable snapshot for later restoration (for example, when
+     * scheduling background work).
+     *
+     * Throws when no execution context is active.
+     */
+    capture(): ContextSnapshot;
+    /**
+     * Runs a callback inside the execution context and values of
+     * a previously captured snapshot.
+     */
+    runSnapshot<T>(snapshot: ContextSnapshot, callback: () => T): T;
 }
 /**
  * Creates a ContextStorage instance.

package/dist/context/provider/contextStorage.storage.js

@@ -1,4 +1,9 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { deriveExecutionContext } from "../core/executionContext.context.js";
+import { ContextValues } from "../values/contextValues.values.js";
+import { createContextValues } from "../values/contextValues.values.js";
+import { createContextSnapshot } from "../snapshot/contextSnapshot.snapshot.js";
+import { ExecutionContextNotFoundError } from "../../errors/exceptions.js";
 /**
  * Stores the current ExecutionContext across asynchronous
  * boundaries.
@@ -6,9 +11,14 @@ import { AsyncLocalStorage } from "node:async_hooks";
  * This allows framework components to access the current
  * execution without explicitly passing the context through
  * every function call.
+ *
+ * Alongside the ExecutionContext, an optional ContextValues
+ * collection can travel with the execution, connecting typed
+ * context values to the async storage.
  */
 export class ContextStorage {
     storage = new AsyncLocalStorage();
+    valuesStorage = new AsyncLocalStorage();
     /**
      * Runs a function inside an execution context.
      *
@@ -34,7 +44,7 @@ export class ContextStorage {
     require() {
         const context = this.get();
         if (!context) {
-            throw new Error("No execution context is available.");
+            throw new ExecutionContextNotFoundError();
         }
         return context;
     }
@@ -45,24 +55,56 @@ export class ContextStorage {
         return this.get() !== undefined;
     }
     /**
-     * Executes a callback with a derived execution context.
-     */
-    runWith(context, callback) {
-        return this.run(context, callback);
-    }
-    /**
-     * Executes a callback using the current context with
-     * a temporary derived context.
+     * Executes a callback within a context derived from the
+     * current one.
+     *
+     * The current context is read from storage and combined with
+     * the supplied overrides via deriveExecutionContext, so
+     * correlation and tracing information propagates into the
+     * derived scope. Throws when no context is active.
      */
-    runDerived(context, callback) {
-        return this.storage.run(context, callback);
+    runDerived(overrides, callback) {
+        const current = this.require();
+        const derived = deriveExecutionContext(current, overrides);
+        return this.storage.run(derived, callback);
     }
     /**
      * Clears the current execution context by executing the
      * callback outside the current storage context.
      */
     runWithoutContext(callback) {
-        return this.storage.exit(callback);
+        return this.storage.exit(() => this.valuesStorage.exit(callback));
+    }
+    /**
+     * Runs a callback with both an execution context and a typed
+     * ContextValues collection bound to the async scope.
+     */
+    runWithValues(context, values, callback) {
+        return this.storage.run(context, () => this.valuesStorage.run(values, callback));
+    }
+    /**
+     * Returns the ContextValues bound to the current async scope,
+     * when one was provided via runWithValues or runSnapshot.
+     */
+    getValues() {
+        return this.valuesStorage.getStore();
+    }
+    /**
+     * Captures the current execution context and its values as an
+     * immutable snapshot for later restoration (for example, when
+     * scheduling background work).
+     *
+     * Throws when no execution context is active.
+     */
+    capture() {
+        return createContextSnapshot(this.require(), this.getValues() ?? createContextValues());
+    }
+    /**
+     * Runs a callback inside the execution context and values of
+     * a previously captured snapshot.
+     */
+    runSnapshot(snapshot, callback) {
+        return this.runWithValues(snapshot.context, snapshot.values, callback);
     }
 }
 /**

package/dist/context/provider/defaultContextStorage.storage.d.ts

@@ -0,0 +1,18 @@
+import { ContextStorage } from "./contextStorage.storage.js";
+/**
+ * The process-wide default ContextStorage.
+ *
+ * Every framework component that needs ambient execution context
+ * (runtime, module lifecycle, application, container scoping,
+ * logging) falls back to this instance when no storage is injected,
+ * so they all observe the same AsyncLocalStorage by default.
+ * Inject a dedicated ContextStorage everywhere when isolation is
+ * required (for example in tests that run applications in
+ * parallel).
+ */
+export declare const defaultContextStorage: ContextStorage;
+/**
+ * Returns the process-wide default ContextStorage.
+ */
+export declare function getDefaultContextStorage(): ContextStorage;
+//# sourceMappingURL=defaultContextStorage.storage.d.ts.map

package/dist/context/provider/defaultContextStorage.storage.js

@@ -0,0 +1,20 @@
+import { ContextStorage } from "./contextStorage.storage.js";
+/**
+ * The process-wide default ContextStorage.
+ *
+ * Every framework component that needs ambient execution context
+ * (runtime, module lifecycle, application, container scoping,
+ * logging) falls back to this instance when no storage is injected,
+ * so they all observe the same AsyncLocalStorage by default.
+ * Inject a dedicated ContextStorage everywhere when isolation is
+ * required (for example in tests that run applications in
+ * parallel).
+ */
+export const defaultContextStorage = new ContextStorage();
+/**
+ * Returns the process-wide default ContextStorage.
+ */
+export function getDefaultContextStorage() {
+    return defaultContextStorage;
+}
+//# sourceMappingURL=defaultContextStorage.storage.js.map

package/dist/context/provider/index.d.ts

@@ -3,6 +3,7 @@
  *
  * Async context storage and provider.
  */
-export { ContextStorage, createContextStorage, } from "./contextStorage.storage.js";
+export { ContextStorage, createContextStorage, type ExecutionContextOverrides, } from "./contextStorage.storage.js";
+export { defaultContextStorage, getDefaultContextStorage, } from "./defaultContextStorage.storage.js";
 export { DefaultContextProvider, createContextProvider, type ContextProvider, } from "./contextProvider.provider.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/context/provider/index.js

@@ -4,5 +4,6 @@
  * Async context storage and provider.
  */
 export { ContextStorage, createContextStorage, } from "./contextStorage.storage.js";
+export { defaultContextStorage, getDefaultContextStorage, } from "./defaultContextStorage.storage.js";
 export { DefaultContextProvider, createContextProvider, } from "./contextProvider.provider.js";
 //# sourceMappingURL=index.js.map

package/dist/errors/exceptions.d.ts

@@ -25,6 +25,24 @@ export declare class ProviderNotFoundError extends FrameworkError {
 export declare class ProviderAlreadyRegisteredError extends FrameworkError {
     constructor(token: unknown);
 }
+/**
+ * Thrown when a provider definition is not one of the supported
+ * shapes (useValue, useFactory, useClass).
+ */
+export declare class InvalidProviderError extends FrameworkError {
+    constructor(token: unknown);
+}
+/**
+ * Thrown when a dependency cannot be resolved, for example because
+ * the resolution chain contains a cycle or a factory failed.
+ */
+export declare class DependencyResolutionError extends FrameworkError {
+    /**
+     * Tokens in resolution order, ending with the token that failed.
+     */
+    readonly chain: readonly string[];
+    constructor(message: string, chain: readonly unknown[], cause?: unknown);
+}
 /**
  * Thrown when configuration is required but cannot be found.
  */
@@ -49,4 +67,8 @@ export declare class ModuleNotFoundError extends FrameworkError {
 export declare class AdapterNotFoundError extends FrameworkError {
     constructor(adapterName: string);
 }
+/**
+ * Creates a readable representation of a dependency token.
+ */
+export declare function describeToken(token: unknown): string;
 //# sourceMappingURL=exceptions.d.ts.map

package/dist/errors/exceptions.js

@@ -54,6 +54,43 @@ export class ProviderAlreadyRegisteredError extends FrameworkError {
         this.name = "ProviderAlreadyRegisteredError";
     }
 }
+/**
+ * Thrown when a provider definition is not one of the supported
+ * shapes (useValue, useFactory, useClass).
+ */
+export class InvalidProviderError extends FrameworkError {
+    constructor(token) {
+        super(`Invalid provider definition for token "${describeToken(token)}".`, {
+            code: ErrorCode.INVALID_PROVIDER,
+            details: {
+                token: describeToken(token),
+            },
+        });
+        this.name = "InvalidProviderError";
+    }
+}
+/**
+ * Thrown when a dependency cannot be resolved, for example because
+ * the resolution chain contains a cycle or a factory failed.
+ */
+export class DependencyResolutionError extends FrameworkError {
+    /**
+     * Tokens in resolution order, ending with the token that failed.
+     */
+    chain;
+    constructor(message, chain, cause) {
+        const describedChain = chain.map(describeToken);
+        super(message, {
+            code: ErrorCode.DEPENDENCY_RESOLUTION_FAILED,
+            details: {
+                chain: describedChain,
+            },
+            cause,
+        });
+        this.name = "DependencyResolutionError";
+        this.chain = Object.freeze(describedChain);
+    }
+}
 /**
  * Thrown when configuration is required but cannot be found.
  */
@@ -110,7 +147,7 @@ export class AdapterNotFoundError extends FrameworkError {
 /**
  * Creates a readable representation of a dependency token.
  */
-function describeToken(token) {
+export function describeToken(token) {
     if (typeof token === "string") {
         return token;
     }

package/dist/errors/frameworkError.error.d.ts

@@ -17,14 +17,13 @@ export interface FrameworkErrorOptions {
 }
 /**
  * Serializable representation of a FrameworkError.
+ *
+ * Mirrors exactly what {@link FrameworkError.toJSON} returns: the
+ * serialized BaseError fields plus the optional structured details.
  */
-export interface FrameworkErrorJSON {
-    readonly name: string;
-    readonly message: string;
-    readonly code: string;
-    readonly status?: number;
+export type FrameworkErrorJSON = SerializedBaseError & {
     readonly details?: unknown;
-}
+};
 /**
  * Base error class for all Zudojs framework errors.
  *
@@ -44,8 +43,6 @@ export declare class FrameworkError extends ApplicationError {
     /**
      * Converts the error into a structured representation.
      */
-    toJSON(): SerializedBaseError & {
-        readonly details?: unknown;
-    };
+    toJSON(): FrameworkErrorJSON;
 }
 //# sourceMappingURL=frameworkError.error.d.ts.map

package/dist/errors/index.d.ts

@@ -6,5 +6,5 @@
 export { ErrorCode } from "./errorCode.code.js";
 export type { ErrorCode as ErrorCodeType } from "./errorCode.code.js";
 export { FrameworkError, type FrameworkErrorJSON, } from "./frameworkError.error.js";
-export { InvalidArgumentError, InvalidStateError, ProviderNotFoundError, ProviderAlreadyRegisteredError, ConfigurationNotFoundError, ExecutionContextNotFoundError, AdapterNotFoundError, } from "./exceptions.js";
+export { InvalidArgumentError, InvalidStateError, ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderError, DependencyResolutionError, ConfigurationNotFoundError, ExecutionContextNotFoundError, ModuleNotFoundError, AdapterNotFoundError, describeToken, } from "./exceptions.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/index.js

@@ -5,5 +5,5 @@
  */
 export { ErrorCode } from "./errorCode.code.js";
 export { FrameworkError, } from "./frameworkError.error.js";
-export { InvalidArgumentError, InvalidStateError, ProviderNotFoundError, ProviderAlreadyRegisteredError, ConfigurationNotFoundError, ExecutionContextNotFoundError, AdapterNotFoundError, } from "./exceptions.js";
+export { InvalidArgumentError, InvalidStateError, ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderError, DependencyResolutionError, ConfigurationNotFoundError, ExecutionContextNotFoundError, ModuleNotFoundError, AdapterNotFoundError, describeToken, } from "./exceptions.js";
 //# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  * Public API
  * ----------
  *
+ * container
  * contracts
  * errors
  * logging
@@ -14,6 +15,7 @@
  * configuration
  * modules
  * runtime
+ * application
  *
  * Internal implementation details should not be imported directly
  * by consumers when a public export is available here.
@@ -26,5 +28,7 @@ export * from "./lifecycle/index.js";
 export * from "./context/index.js";
 export * from "./configuration/index.js";
 export * from "./modules/index.js";
+export { ModuleNotFoundError } from "./modules/index.js";
 export * from "./runtime/index.js";
+export * from "./application/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -6,6 +6,7 @@
  * Public API
  * ----------
  *
+ * container
  * contracts
  * errors
  * logging
@@ -14,6 +15,7 @@
  * configuration
  * modules
  * runtime
+ * application
  *
  * Internal implementation details should not be imported directly
  * by consumers when a public export is available here.
@@ -66,10 +68,22 @@ export * from "./configuration/index.js";
  * ============================================================
  */
 export * from "./modules/index.js";
+/*
+ * The module subsystem's ModuleNotFoundError is the one thrown by the
+ * registry, loader, and runtime, so it wins at the root. The generic
+ * core error of the same name remains available via "./errors".
+ */
+export { ModuleNotFoundError } from "./modules/index.js";
 /*
  * ============================================================
  * Runtime
  * ============================================================
  */
 export * from "./runtime/index.js";
+/*
+ * ============================================================
+ * Application
+ * ============================================================
+ */
+export * from "./application/index.js";
 //# sourceMappingURL=index.js.map

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

@@ -3,7 +3,7 @@
  *
  * Core lifecycle state machine, hooks, and registry.
  */
-export { LifecycleState, type LifecycleParticipant } from "./lifecycle.js";
+export { Lifecycle, LifecycleState, type LifecycleOptions, type LifecycleParticipant, } from "./lifecycle.js";
 export { hasInitializeHook, hasStartHook, hasStopHook, hasDestroyHook, type OnInitialize, type OnStart, type OnStop, type OnDestroy, type LifecycleHook, } from "./lifecycleHook.hook.js";
 export { LifecycleRegistry, type LifecycleComponent, type LifecycleRegistration, } from "./lifecycleRegistry.registry.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lifecycle/core/index.js

@@ -3,7 +3,7 @@
  *
  * Core lifecycle state machine, hooks, and registry.
  */
-export { LifecycleState } from "./lifecycle.js";
+export { Lifecycle, LifecycleState, } from "./lifecycle.js";
 export { hasInitializeHook, hasStartHook, hasStopHook, hasDestroyHook, } from "./lifecycleHook.hook.js";
 export { LifecycleRegistry, } from "./lifecycleRegistry.registry.js";
 //# sourceMappingURL=index.js.map

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

@@ -22,23 +22,68 @@ export interface LifecycleParticipant {
 /** Options used by the lifecycle manager. */
 export interface LifecycleOptions {
     readonly logger?: Logger;
+    /**
+     * Whether stop/dispose should keep going after a participant fails.
+     * When false the phase aborts at the first failure and the lifecycle
+     * is left FAILED (remaining participants are not unwound).
+     *
+     * Defaults to true.
+     */
     readonly continueOnShutdownError?: boolean;
 }
-/** Coordinates initialization, startup, shutdown, and disposal of application resources. */
+/**
+ * Coordinates initialization, startup, shutdown, and disposal of
+ * application resources.
+ *
+ * State machine:
+ *
+ *   CREATED → INITIALIZING → INITIALIZED → STARTING → RUNNING
+ *   RUNNING → STOPPING → STOPPED → (STARTING → RUNNING) restart
+ *   any phase failure → FAILED; initialize()/start() retry from FAILED
+ *   resume with the participant that failed; stop() from FAILED unwinds
+ *   whatever started.
+ *
+ * Concurrent callers of the same phase share the in-flight promise.
+ */
 export declare class Lifecycle {
     private state;
     private readonly participants;
     private readonly logger?;
     private readonly continueOnShutdownError;
+    private initializedCount;
+    private startedCount;
+    private disposed;
+    private failedPhase;
+    private initializePromise;
+    private startPromise;
+    private stopPromise;
     constructor(options?: LifecycleOptions);
     getState(): LifecycleState;
     getParticipants(): readonly LifecycleParticipant[];
+    /**
+     * Whether dispose() has run. A disposed lifecycle cannot be
+     * restarted.
+     */
+    isDisposed(): boolean;
+    /**
+     * Registers a participant. Only allowed before initialization
+     * begins so every participant goes through every phase.
+     */
     register(participant: LifecycleParticipant): void;
     initialize(): Promise<void>;
     start(): Promise<void>;
-    private waitForInitialization;
     stop(): Promise<void>;
+    /**
+     * Disposes every participant in reverse registration order.
+     *
+     * Idempotent. Participants that are still running are not stopped
+     * first; use shutdown() for stop-then-dispose.
+     */
     dispose(): Promise<void>;
     shutdown(): Promise<void>;
+    private runInitialize;
+    private runStart;
+    private runStop;
+    private invalidState;
 }
 //# sourceMappingURL=lifecycle.d.ts.map