@zudojs/core 0.0.1 → 1.0.0

package/dist/configuration/schema/configurationValidation.validator.d.ts

@@ -1,7 +1,7 @@
 import type { Configuration } from "../core/configuration.js";
 import { ConfigurationSchemaRegistry } from "../schema/configurationSchema.schema.js";
 import type { ConfigurationSchema, ConfigurationValidationIssue, ConfigurationValidationResult } from "../schema/configurationSchema.schema.js";
-import { FrameworkError } from "../../errors/frameworkError.error.js";
+import { ConfigurationError } from "../error/configurationError.error.js";
 /**
  * Result returned after validating configuration.
  */
@@ -49,7 +49,7 @@ export interface ConfigurationValidationOptions {
 /**
  * Error thrown when configuration validation fails.
  */
-export declare class ConfigurationValidationError extends FrameworkError {
+export declare class ConfigurationValidationError extends ConfigurationError {
     /**
      * All configuration validation issues.
      */
@@ -73,8 +73,20 @@ export declare function validateConfiguration(configuration: Configuration, regi
  *
  * This is the method application bootstrap code should normally
  * use when configuration is mandatory for startup.
+ *
+ * The returned configuration has schema default values applied:
+ * every registered schema whose path is missing from the
+ * configuration and which declares a default contributes that
+ * default (attributed to the "default" source).
  */
 export declare function validateConfigurationOrThrow(configuration: Configuration, registry: ConfigurationSchemaRegistry, options?: ConfigurationValidationOptions): Promise<Configuration>;
+/**
+ * Applies schema default values to a configuration.
+ *
+ * Values already present in the configuration are never
+ * overridden.
+ */
+export declare function applyConfigurationSchemaDefaults(configuration: Configuration, registry: ConfigurationSchemaRegistry): Configuration;
 /**
  * Validates one configuration schema.
  */

package/dist/configuration/schema/configurationValidation.validator.js

@@ -1,10 +1,31 @@
 import { ConfigurationSchemaRegistry } from "../schema/configurationSchema.schema.js";
-import { FrameworkError } from "../../errors/frameworkError.error.js";
 import { ErrorCode } from "../../errors/errorCode.code.js";
+import { ConfigurationError } from "../error/configurationError.error.js";
+import { ConfigurationRedactor } from "../error/configurationRedactor.redactor.js";
+/**
+ * Redactor used to scrub validation issues before they are
+ * embedded in error messages and details.
+ */
+const issueRedactor = new ConfigurationRedactor();
+/**
+ * Redacts sensitive information from a validation issue.
+ */
+function redactValidationIssue(issue) {
+    return {
+        path: issue.path,
+        message: issueRedactor.redactText(issue.message),
+        code: issue.code,
+        ...(issue.value !== undefined
+            ? {
+                value: issueRedactor.redactValueAtPath(issue.path, issue.value),
+            }
+            : {}),
+    };
+}
 /**
  * Error thrown when configuration validation fails.
  */
-export class ConfigurationValidationError extends FrameworkError {
+export class ConfigurationValidationError extends ConfigurationError {
     /**
      * All configuration validation issues.
      */
@@ -18,16 +39,21 @@ export class ConfigurationValidationError extends FrameworkError {
      */
     invalidSchemaCount;
     constructor(issues, schemaCount, invalidSchemaCount) {
-        super(createValidationErrorMessage(issues), {
-            code: ErrorCode.CONFIGURATION_VALIDATION_FAILED,
+        /*
+         * Issue values and messages are redacted before being
+         * embedded so validation failures on sensitive paths do
+         * not leak secrets into logs.
+         */
+        const redactedIssues = issues.map(redactValidationIssue);
+        super(ErrorCode.CONFIGURATION_VALIDATION_FAILED, createValidationErrorMessage(redactedIssues), {
             details: {
-                issues,
+                issues: redactedIssues,
                 schemaCount,
                 invalidSchemaCount,
             },
         });
         this.name = "ConfigurationValidationError";
-        this.issues = [...issues];
+        this.issues = redactedIssues;
         this.schemaCount = schemaCount;
         this.invalidSchemaCount = invalidSchemaCount;
     }
@@ -66,13 +92,35 @@ export async function validateConfiguration(configuration, registry, options = {
  *
  * This is the method application bootstrap code should normally
  * use when configuration is mandatory for startup.
+ *
+ * The returned configuration has schema default values applied:
+ * every registered schema whose path is missing from the
+ * configuration and which declares a default contributes that
+ * default (attributed to the "default" source).
  */
 export async function validateConfigurationOrThrow(configuration, registry, options = {}) {
     const report = await validateConfiguration(configuration, registry, options);
     if (!report.valid) {
         throw new ConfigurationValidationError(report.issues, report.schemaCount, report.invalidSchemaCount);
     }
-    return configuration;
+    return applyConfigurationSchemaDefaults(configuration, registry);
+}
+/**
+ * Applies schema default values to a configuration.
+ *
+ * Values already present in the configuration are never
+ * overridden.
+ */
+export function applyConfigurationSchemaDefaults(configuration, registry) {
+    let result = configuration;
+    for (const schema of registry.getAll()) {
+        if (schema.defaultValue === undefined)
+            continue;
+        if (result.has(schema.path))
+            continue;
+        result = result.with(schema.path, schema.defaultValue, "default");
+    }
+    return result;
 }
 /**
  * Validates one configuration schema.

package/dist/configuration/schema/index.d.ts

@@ -5,6 +5,6 @@
  */
 export { createConfigurationSchema, ConfigurationSchemaRegistry, createConfigurationSchemaRegistry, } from "./configurationSchema.schema.js";
 export type { ConfigurationValidationResult, ConfigurationValidationIssue, ConfigurationValidationContext, ConfigurationValidator, ConfigurationSchema, ConfigurationSchemaOptions, } from "./configurationSchema.schema.js";
-export { validateConfiguration, validateConfigurationOrThrow, validateSchema, } from "./configurationValidation.validator.js";
+export { ConfigurationValidationError, validateConfiguration, validateConfigurationOrThrow, validateSchema, applyConfigurationSchemaDefaults, } from "./configurationValidation.validator.js";
 export type { ConfigurationValidationReport, ConfigurationValidationOptions, } from "./configurationValidation.validator.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/configuration/schema/index.js

@@ -4,5 +4,5 @@
  * Configuration schemas and validation.
  */
 export { createConfigurationSchema, ConfigurationSchemaRegistry, createConfigurationSchemaRegistry, } from "./configurationSchema.schema.js";
-export { validateConfiguration, validateConfigurationOrThrow, validateSchema, } from "./configurationValidation.validator.js";
+export { ConfigurationValidationError, validateConfiguration, validateConfigurationOrThrow, validateSchema, applyConfigurationSchemaDefaults, } from "./configurationValidation.validator.js";
 //# sourceMappingURL=index.js.map

package/dist/container/container.d.ts

@@ -1,22 +1,52 @@
 import type { Provider } from "./provider.js";
 import type { Scope } from "./scope.js";
 import type { Token } from "./token.js";
+/**
+ * Options for the container.
+ */
+export interface ContainerOptions {
+    /**
+     * Returns the object identifying the current execution scope, for
+     * example the current ExecutionContext from a ContextStorage:
+     *
+     *   new Container({ currentScope: () => storage.get() })
+     *
+     * "scoped" providers resolve to one instance per returned object.
+     * When it returns undefined and no explicit scope is active, scoped
+     * providers behave as transient.
+     */
+    readonly currentScope?: () => object | undefined;
+}
 /**
  * Dependency Injection container for Zudojs applications.
  *
  * The container is responsible for registering and resolving
- * application dependencies.
+ * application dependencies with singleton, scoped, and transient
+ * lifetimes.
  */
 export declare class Container {
     private readonly providers;
+    private readonly scopedInstances;
+    private readonly currentScope;
+    private readonly resolving;
+    private activeScope;
+    constructor(options?: ContainerOptions);
     /**
      * Registers a provider in the container.
      */
     register<T>(token: Token<T>, provider: Provider<T>, scope?: Scope): void;
     /**
      * Resolves a dependency from the container.
+     *
+     * Scoped providers use the explicit scope active during resolution
+     * (see {@link createScope}) or the `currentScope` callback.
      */
     resolve<T>(token: Token<T>): T;
+    /**
+     * Creates an explicit resolution scope. Scoped providers resolved
+     * through the returned scope share one instance per scope.
+     */
+    createScope(): ContainerScope;
     /**
      * Checks whether a token has been registered.
      */
@@ -32,12 +62,29 @@ export declare class Container {
      */
     clear(): void;
     /**
-     * Creates an instance from a provider definition.
+     * Resolves a token within a specific scope key.
+     *
+     * @internal Used by ContainerScope.
      */
-    private createInstance;
+    resolveIn<T>(token: Token<T>, scopeKey: object | undefined): T;
     /**
-     * Produces a readable representation of a dependency token.
+     * Creates an instance from a provider definition, tracking the
+     * resolution chain so cycles fail fast with a diagnostic instead of
+     * a stack overflow.
      */
-    private describeToken;
+    private createInstance;
+}
+/**
+ * An explicit resolution scope created by {@link Container.createScope}.
+ *
+ * Scoped providers resolved through this object are cached for its
+ * lifetime; singleton and transient providers behave as usual.
+ */
+export declare class ContainerScope {
+    private readonly container;
+    private readonly key;
+    constructor(container: Container, key: object);
+    resolve<T>(token: Token<T>): T;
+    has<T>(token: Token<T>): boolean;
 }
 //# sourceMappingURL=container.d.ts.map

package/dist/container/container.js

@@ -1,12 +1,20 @@
-import { ProviderNotFoundError, ProviderAlreadyRegisteredError, } from "../errors/exceptions.js";
+import { ProviderNotFoundError, ProviderAlreadyRegisteredError, InvalidProviderError, DependencyResolutionError, } from "../errors/exceptions.js";
 /**
  * Dependency Injection container for Zudojs applications.
  *
  * The container is responsible for registering and resolving
- * application dependencies.
+ * application dependencies with singleton, scoped, and transient
+ * lifetimes.
  */
 export class Container {
     providers = new Map();
+    scopedInstances = new WeakMap();
+    currentScope;
+    resolving = [];
+    activeScope;
+    constructor(options = {}) {
+        this.currentScope = options.currentScope;
+    }
     /**
      * Registers a provider in the container.
      */
@@ -14,28 +22,30 @@ export class Container {
         if (this.providers.has(token)) {
             throw new ProviderAlreadyRegisteredError(token);
         }
+        if (!isProvider(provider)) {
+            throw new InvalidProviderError(token);
+        }
         this.providers.set(token, {
             provider: provider,
             scope,
+            resolved: false,
         });
     }
     /**
      * Resolves a dependency from the container.
+     *
+     * Scoped providers use the explicit scope active during resolution
+     * (see {@link createScope}) or the `currentScope` callback.
      */
     resolve(token) {
-        const registration = this.providers.get(token);
-        if (!registration) {
-            throw new ProviderNotFoundError(token);
-        }
-        if (registration.scope === "singleton" &&
-            registration.instance !== undefined) {
-            return registration.instance;
-        }
-        const instance = this.createInstance(registration.provider);
-        if (registration.scope === "singleton") {
-            registration.instance = instance;
-        }
-        return instance;
+        return this.resolveIn(token, this.activeScope ?? this.currentScope?.());
+    }
+    /**
+     * Creates an explicit resolution scope. Scoped providers resolved
+     * through the returned scope share one instance per scope.
+     */
+    createScope() {
+        return new ContainerScope(this, {});
     }
     /**
      * Checks whether a token has been registered.
@@ -58,34 +68,101 @@ export class Container {
         this.providers.clear();
     }
     /**
-     * Creates an instance from a provider definition.
+     * Resolves a token within a specific scope key.
+     *
+     * @internal Used by ContainerScope.
      */
-    createInstance(provider) {
-        if ("useValue" in provider) {
-            return provider.useValue;
+    resolveIn(token, scopeKey) {
+        const registration = this.providers.get(token);
+        if (!registration) {
+            throw new ProviderNotFoundError(token);
         }
-        if ("useFactory" in provider) {
-            return provider.useFactory(this);
+        if (registration.scope === "singleton" && registration.resolved) {
+            return registration.instance;
         }
-        if ("useClass" in provider) {
-            return new provider.useClass();
+        if (registration.scope === "scoped" && scopeKey) {
+            const cache = this.scopedInstances.get(scopeKey);
+            if (cache?.has(token)) {
+                return cache.get(token);
+            }
+        }
+        const instance = this.createInstance(token, registration, scopeKey);
+        if (registration.scope === "singleton") {
+            registration.instance = instance;
+            registration.resolved = true;
+        }
+        else if (registration.scope === "scoped" && scopeKey) {
+            let cache = this.scopedInstances.get(scopeKey);
+            if (!cache) {
+                cache = new Map();
+                this.scopedInstances.set(scopeKey, cache);
+            }
+            cache.set(token, instance);
         }
-        throw new Error("Invalid provider definition.");
+        return instance;
     }
     /**
-     * Produces a readable representation of a dependency token.
+     * Creates an instance from a provider definition, tracking the
+     * resolution chain so cycles fail fast with a diagnostic instead of
+     * a stack overflow.
      */
-    describeToken(token) {
-        if (typeof token === "string") {
-            return token;
+    createInstance(token, registration, scopeKey) {
+        if (this.resolving.includes(token)) {
+            throw new DependencyResolutionError("Circular dependency detected while resolving.", [...this.resolving, token]);
+        }
+        const provider = registration.provider;
+        if ("useValue" in provider) {
+            return provider.useValue;
+        }
+        const previousScope = this.activeScope;
+        this.resolving.push(token);
+        this.activeScope = scopeKey;
+        try {
+            if ("useFactory" in provider) {
+                return provider.useFactory(this);
+            }
+            return new provider.useClass();
         }
-        if (typeof token === "symbol") {
-            return token.description ?? token.toString();
+        catch (error) {
+            if (error instanceof DependencyResolutionError)
+                throw error;
+            throw new DependencyResolutionError(`Failed to resolve dependency.`, [...this.resolving], error);
         }
-        if (typeof token === "function") {
-            return token.name || "anonymous class";
+        finally {
+            this.resolving.pop();
+            this.activeScope = previousScope;
         }
-        return "unknown";
     }
 }
+/**
+ * An explicit resolution scope created by {@link Container.createScope}.
+ *
+ * Scoped providers resolved through this object are cached for its
+ * lifetime; singleton and transient providers behave as usual.
+ */
+export class ContainerScope {
+    container;
+    key;
+    constructor(container, key) {
+        this.container = container;
+        this.key = key;
+    }
+    resolve(token) {
+        return this.container.resolveIn(token, this.key);
+    }
+    has(token) {
+        return this.container.has(token);
+    }
+}
+function isProvider(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    if ("useValue" in value)
+        return true;
+    if ("useFactory" in value)
+        return typeof value.useFactory === "function";
+    if ("useClass" in value)
+        return typeof value.useClass === "function";
+    return false;
+}
 //# sourceMappingURL=container.js.map

package/dist/container/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Dependency Injection Container.
  */
-export { Container } from "./container.js";
+export { Container, ContainerScope, type ContainerOptions, } from "./container.js";
 export { createToken, type Token, type ConstructorToken } from "./token.js";
 export { type Provider, type ClassProvider, type FactoryProvider, type ValueProvider, type Constructor, } from "./provider.js";
 export { type Scope } from "./scope.js";

package/dist/container/index.js

@@ -1,7 +1,7 @@
 /**
  * Dependency Injection Container.
  */
-export { Container } from "./container.js";
+export { Container, ContainerScope, } from "./container.js";
 export { createToken } from "./token.js";
 export {} from "./provider.js";
 export {} from "./scope.js";

package/dist/container/scope.d.ts

@@ -8,13 +8,14 @@ export type Scope =
  */
 "singleton"
 /**
- * One instance for the lifetime of an execution context.
+ * One instance per resolution scope.
  *
- * Examples:
- * HTTP request
- * Background job
- * Message consumption
- * RPC request
+ * A scope is either an explicit `container.createScope()` or the
+ * object returned by the container's `currentScope` callback (for
+ * example the current ExecutionContext of an HTTP request,
+ * background job, message consumption, or RPC call).
+ *
+ * When no scope is active, scoped providers behave as transient.
  */
  | "scoped"
 /**

package/dist/context/core/contextAliases.deprecated.d.ts

@@ -0,0 +1,32 @@
+import type { CreateExecutionContextInput, ExecutionContext } from "./executionContext.context.js";
+import { createExecutionContext } from "./executionContext.context.js";
+/**
+ * Deprecated names kept for source compatibility.
+ *
+ * The framework has a single execution-context model: the
+ * immutable ExecutionContext propagated by ContextStorage. The
+ * former mutable `Context` class no longer exists; every alias
+ * below resolves to the canonical type or function so there is no
+ * second implementation to keep in sync.
+ */
+/**
+ * Known execution transports.
+ *
+ * @deprecated Use ExecutionContext.transport (a free-form string);
+ * this union is kept only as documentation of the conventional
+ * values.
+ */
+export type ContextType = "http" | "rpc" | "message" | "job" | "cli" | "worker" | "unknown";
+/**
+ * @deprecated Use ExecutionContext.
+ */
+export type Context = ExecutionContext;
+/**
+ * @deprecated Use CreateExecutionContextInput.
+ */
+export type CreateContextOptions = CreateExecutionContextInput;
+/**
+ * @deprecated Use createExecutionContext.
+ */
+export declare const createContext: typeof createExecutionContext;
+//# sourceMappingURL=contextAliases.deprecated.d.ts.map

package/dist/context/core/contextAliases.deprecated.js

@@ -0,0 +1,6 @@
+import { createExecutionContext } from "./executionContext.context.js";
+/**
+ * @deprecated Use createExecutionContext.
+ */
+export const createContext = createExecutionContext;
+//# sourceMappingURL=contextAliases.deprecated.js.map

package/dist/context/core/executionContext.context.d.ts

@@ -128,4 +128,12 @@ export declare function withExecutionMetadata(context: ExecutionContext, metadat
  * Returns the duration of an execution in milliseconds.
  */
 export declare function getExecutionDuration(context: ExecutionContext, endTime?: Date): number;
+/**
+ * Creates a framework execution identifier.
+ *
+ * This is the single shared implementation used by the context
+ * subsystem. Node.js >= 24 always provides crypto.randomUUID,
+ * so no weaker fallback exists.
+ */
+export declare function createExecutionId(): string;
 //# sourceMappingURL=executionContext.context.d.ts.map

package/dist/context/core/executionContext.context.js

@@ -1,3 +1,35 @@
+/**
+ * Maximum depth to which execution metadata is frozen.
+ *
+ * Execution metadata is expected to be small JSON-ish data;
+ * the bound protects against pathological structures.
+ */
+const MAX_METADATA_FREEZE_DEPTH = 8;
+/**
+ * Recursively freezes JSON-ish metadata up to a bounded depth.
+ *
+ * Already frozen nodes are skipped; non-plain objects (class
+ * instances) are frozen shallowly.
+ */
+function deepFreezeMetadata(value, depth = 0) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Object.isFrozen(value))
+        return value;
+    if (depth >= MAX_METADATA_FREEZE_DEPTH)
+        return Object.freeze(value);
+    if (Array.isArray(value)) {
+        for (const item of value)
+            deepFreezeMetadata(item, depth + 1);
+        return Object.freeze(value);
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype || prototype === null) {
+        for (const child of Object.values(value))
+            deepFreezeMetadata(child, depth + 1);
+    }
+    return Object.freeze(value);
+}
 /**
  * Creates a new execution context.
  */
@@ -14,7 +46,7 @@ export function createExecutionContext(input = {}) {
         operation: input.operation,
         transport: input.transport,
         startedAt: input.startedAt ?? new Date(),
-        metadata: Object.freeze({
+        metadata: deepFreezeMetadata({
             ...(input.metadata ?? {}),
         }),
     });
@@ -62,20 +94,11 @@ export function getExecutionDuration(context, endTime = new Date()) {
 /**
  * Creates a framework execution identifier.
  *
- * Uses crypto.randomUUID when available.
+ * This is the single shared implementation used by the context
+ * subsystem. Node.js >= 24 always provides crypto.randomUUID,
+ * so no weaker fallback exists.
  */
-function createExecutionId() {
-    if (typeof globalThis.crypto !== "undefined" &&
-        typeof globalThis.crypto.randomUUID === "function") {
-        return globalThis.crypto.randomUUID();
-    }
-    /**
-     * Fallback for environments where Web Crypto is unavailable.
-     */
-    return [
-        Date.now().toString(36),
-        Math.random().toString(36).slice(2),
-        Math.random().toString(36).slice(2),
-    ].join("-");
+export function createExecutionId() {
+    return globalThis.crypto.randomUUID();
 }
 //# sourceMappingURL=executionContext.context.js.map

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

@@ -3,7 +3,7 @@
  *
  * Core context types and key management.
  */
-export { Context, createContext, type ContextType, type ExecutionMetadata, type CreateContextOptions, } from "./context.js";
-export { createExecutionContext, deriveExecutionContext, withExecutionMetadata, getExecutionDuration, type ExecutionContext, type CreateExecutionContextInput, } from "./executionContext.context.js";
+export { createExecutionContext, deriveExecutionContext, withExecutionMetadata, getExecutionDuration, createExecutionId, type ExecutionContext, type CreateExecutionContextInput, } from "./executionContext.context.js";
 export { createContextKey, setContextValue, getContextValue, requireContextValue, hasContextValue, deleteContextValue, type ContextKey, type ContextValueStore, } from "./contextKey.key.js";
+export { createContext, type Context, type ContextType, type CreateContextOptions, } from "./contextAliases.deprecated.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/context/core/index.js

@@ -3,7 +3,7 @@
  *
  * Core context types and key management.
  */
-export { Context, createContext, } from "./context.js";
-export { createExecutionContext, deriveExecutionContext, withExecutionMetadata, getExecutionDuration, } from "./executionContext.context.js";
+export { createExecutionContext, deriveExecutionContext, withExecutionMetadata, getExecutionDuration, createExecutionId, } from "./executionContext.context.js";
 export { createContextKey, setContextValue, getContextValue, requireContextValue, hasContextValue, deleteContextValue, } from "./contextKey.key.js";
+export { createContext, } from "./contextAliases.deprecated.js";
 //# sourceMappingURL=index.js.map

package/dist/context/index.d.ts

@@ -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";