@codefast/di 0.3.13-canary.4 → 0.3.14-canary.0

package/dist/decorators/lifecycle-decorators.mjs

@@ -1,8 +1,14 @@
 import { CODEFAST_DI_LIFECYCLE_METADATA } from "../metadata/metadata-keys.mjs";
 //#region src/decorators/lifecycle-decorators.ts
 /**
-* Stage 3 method decorator: marks a method to be called after the class is instantiated by the container.
-* Order: construct → `@postConstruct()` → `.onActivation()` → cache.
+* Stage 3 method decorator: marks a method to be called after the class is instantiated
+* by the container and before the `onActivation` hook runs.
+*
+* Lifecycle order: `new Class(…)` → **`@postConstruct()`** → `onActivation()` → scope cache.
+*
+* Only one method per class may carry this decorator; a second application throws.
+* If the decorated method returns a `Promise` during synchronous resolution,
+* {@link AsyncResolutionError} is thrown — use `Container.resolveAsync()` instead.
 */
 function postConstruct() {
 	return (_target, context) => {
@@ -16,8 +22,14 @@ function postConstruct() {
 	};
 }
 /**
-* Stage 3 method decorator: marks a method to be called before the instance is destroyed by the container.
-* Order: `.onDeactivation()` → `@preDestroy()`.
+* Stage 3 method decorator: marks a method to be called when the container disposes or
+* unloads the owning binding.
+*
+* Lifecycle order: `onDeactivation()` → **`@preDestroy()`**.
+*
+* Only one method per class may carry this decorator; a second application throws.
+* If the decorated method returns a `Promise` during synchronous disposal,
+* an error is thrown — use `Container.disposeAsync()` instead.
 */
 function preDestroy() {
 	return (_target, context) => {

package/dist/dependency-graph.d.mts

@@ -3,27 +3,50 @@ import { Binding, BindingIdentifier, ResolveHint } from "./binding.mjs";
 import { MetadataReader } from "./metadata/metadata-types.mjs";
 
 //#region src/dependency-graph.d.ts
-/** A directed edge in the static dependency graph produced by {@link collectStaticDependencyEdges}. */
+/**
+ * A directed edge in the static dependency graph produced by {@link collectStaticDependencyEdges}.
+ */
 type StaticDependencyEdge = {
   readonly fromBindingId: BindingIdentifier;
   readonly toBindingId: BindingIdentifier;
   readonly resolutionPath: readonly string[];
-  readonly edgeKind: "sync" | "async"; /** True when the resolved target binding carries a {@link BindingBuilder.when} predicate (runtime may skip this edge). */
-  readonly toBindingConditional: boolean; /** Constructor inject hint for this edge (named / tagged), when known statically. */
-  readonly injectHintLabel?: string; /** True when the consumer binding is an alias (rebind to another token). */
+  readonly edgeKind: "sync" | "async";
+  /**
+   * True when the resolved target binding carries a {@link BindingBuilder.when} predicate (runtime may skip this edge).
+   */
+  readonly toBindingConditional: boolean;
+  /**
+   * Constructor inject hint for this edge (named / tagged), when known statically.
+   */
+  readonly injectHintLabel?: string;
+  /**
+   * True when the consumer binding is an alias (rebind to another token).
+   */
   readonly isAliasEdge: boolean;
 };
-/** A single resolved dependency entry produced by {@link listResolvedDependencies}. */
+/**
+ * A single resolved dependency entry produced by {@link listResolvedDependencies}.
+ */
 type ResolvedDependency = {
   readonly binding: Binding<unknown>;
   readonly path: readonly string[];
   readonly injectHintLabel?: string;
 };
-/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+/**
+ * Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`).
+ */
 declare function injectHintLabelFromResolveHint(hint: ResolveHint | undefined): string | undefined;
 /**
- * Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
- * Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+ * Lists the direct static dependencies of `consumer` by inspecting binding metadata.
+ *
+ * - `constant` / `dynamic` / `async-dynamic` — no enumerable deps (empty array).
+ * - `alias` — single dependency on the alias target (chased through alias chains).
+ * - `resolved` — one dependency per entry in `dependencyTokens`; a missing binding
+ *   always throws {@link InternalError} (there is no optional concept for `resolved`).
+ * - `class` — one dependency per `@injectable()` constructor parameter
+ *   (requires a {@link MetadataReader}). Parameters marked `optional` whose token
+ *   has no binding are silently skipped; non-optional missing tokens throw
+ *   {@link InternalError}.
  */
 declare function listResolvedDependencies(consumer: Binding<unknown>, lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined, reader: MetadataReader | undefined, pathPrefix: readonly string[]): readonly ResolvedDependency[];
 /**

package/dist/dependency-graph.mjs

@@ -1,7 +1,9 @@
 import { InternalError } from "./errors.mjs";
-import { registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
+import { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry } from "./binding-select.mjs";
 //#region src/dependency-graph.ts
-/** Converts a tag value to a printable string for graph edge labels. */
+/**
+* Converts a tag value to a printable string for graph edge labels.
+*/
 function formatTagValueForGraph(value) {
 	if (typeof value === "string") return value;
 	try {
@@ -10,7 +12,9 @@ function formatTagValueForGraph(value) {
 		return String(value);
 	}
 }
-/** Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`). */
+/**
+* Converts a {@link ResolveHint} to a human-readable edge label for graph output (`name: x` / `tag: k=v`).
+*/
 function injectHintLabelFromResolveHint(hint) {
 	if (hint === void 0) return;
 	if (hint.name !== void 0) return `name: ${hint.name}`;
@@ -19,7 +23,9 @@ function injectHintLabelFromResolveHint(hint) {
 		return `tag: ${tagKey}=${formatTagValueForGraph(tagValue)}`;
 	}
 }
-/** Returns `"async"` when either the consumer or dependency binding is an `async-dynamic` factory. */
+/**
+* Returns `"async"` when either the consumer or dependency binding is an `async-dynamic` factory.
+*/
 function edgeKindFor(consumer, dependency) {
 	if (consumer.kind === "async-dynamic" || dependency.kind === "async-dynamic") return "async";
 	return "sync";
@@ -37,7 +43,13 @@ function resolveDefaultBinding(lookup, depKey, pathPrefix) {
 }
 /**
 * Follows alias bindings until a non-alias binding is reached.
-* Returns the last reachable binding; stops if an alias target is unregistered.
+* Returns the last reachable binding; stops early if an alias target is unregistered.
+*
+* **Warning:** This is a static walk with no cycle detection (`visiting` set). If the
+* registry contains a cyclic alias chain (A → B → A), this function will loop
+* indefinitely. The runtime resolver prevents such cycles via its own `visiting`
+* guard, but callers invoking `expandAliasChain` on a manually-constructed or
+* corrupted registry must ensure alias chains are acyclic.
 */
 function expandAliasChain(lookup, start, pathPrefix) {
 	let current = start;
@@ -52,8 +64,16 @@ function expandAliasChain(lookup, start, pathPrefix) {
 	return current;
 }
 /**
-* Lists direct static dependencies (constructor metadata, `toResolved` tokens, alias targets).
-* Factories (`toDynamic` / `toAsyncDynamic`) have no enumerable dependency keys.
+* Lists the direct static dependencies of `consumer` by inspecting binding metadata.
+*
+* - `constant` / `dynamic` / `async-dynamic` — no enumerable deps (empty array).
+* - `alias` — single dependency on the alias target (chased through alias chains).
+* - `resolved` — one dependency per entry in `dependencyTokens`; a missing binding
+*   always throws {@link InternalError} (there is no optional concept for `resolved`).
+* - `class` — one dependency per `@injectable()` constructor parameter
+*   (requires a {@link MetadataReader}). Parameters marked `optional` whose token
+*   has no binding are silently skipped; non-optional missing tokens throw
+*   {@link InternalError}.
 */
 function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 	switch (consumer.kind) {
@@ -90,6 +110,20 @@ function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 				const tok = param.token;
 				const label = registryKeyLabel(tok);
 				const nextPath = [...pathPrefix, label];
+				const paramHint = param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0;
+				if (param.all === true) {
+					const bindings = lookup(tok);
+					if (bindings === void 0 || bindings.length === 0) return [];
+					const candidates = filterMatchingBindings(bindings, paramHint, void 0);
+					if (candidates.length === 0) return [];
+					return candidates.map((binding) => {
+						return {
+							binding: expandAliasChain(lookup, binding, nextPath),
+							path: nextPath,
+							injectHintLabel: injectHintLabelFromResolveHint(paramHint)
+						};
+					});
+				}
 				const binding = resolveDefaultBinding(lookup, tok, pathPrefix);
 				if (binding === void 0) {
 					if (param.optional) return [];
@@ -98,7 +132,7 @@ function listResolvedDependencies(consumer, lookup, reader, pathPrefix) {
 				return [{
 					binding: expandAliasChain(lookup, binding, nextPath),
 					path: nextPath,
-					injectHintLabel: injectHintLabelFromResolveHint(param.name !== void 0 ? { name: param.name } : param.tag !== void 0 ? { tag: param.tag } : void 0)
+					injectHintLabel: injectHintLabelFromResolveHint(paramHint)
 				}];
 			});
 		}

package/dist/errors.d.mts

@@ -2,74 +2,177 @@ import { Binding, BindingIdentifier, BindingScope, ResolveHint } from "./binding
 
 //#region src/errors.d.ts
 /**
- * Base error for all `@codefast/di` failures. Subclasses expose a stable, machine-readable `code`.
+ * Formats a resolution path array into a human-readable `"A -> B -> C"` string.
+ */
+declare function formatResolutionPath(resolutionPath: readonly string[]): string;
+/**
+ * Base error for all `@codefast/di` failures.
+ *
+ * Every concrete subclass exposes a stable, machine-readable {@link DiError.code} property
+ * (e.g. `"TOKEN_NOT_BOUND"`) so consumers can `switch` on error type without relying
+ * on `instanceof` across package versions.
  */
 declare abstract class DiError extends Error {
+  /**
+   * Machine-readable error code, constant per subclass (e.g. `"TOKEN_NOT_BOUND"`).
+   */
   abstract readonly code: string;
   constructor(message: string, options?: ErrorOptions);
 }
 /**
  * Raised for internal programming errors — invalid library usage or unexpected state that
- * indicates a bug in the caller (e.g. accessing an uninitialized container, misconfigured binding).
+ * indicates a bug in the caller or the library itself.
+ *
+ * Examples: double `to*()` call on a {@link BindingBuilder}, ambiguous binding resolution
+ * with multiple candidates, or scope mutation on a constant binding.
+ *
+ * Code: `"INTERNAL_ERROR"`
  */
 declare class InternalError extends DiError {
   readonly code = "INTERNAL_ERROR";
 }
 /**
- * Raised when a name/tag filter matches no binding although other bindings exist for the token.
+ * Raised when bindings exist for the token but none match the provided name/tag hint.
+ * Distinguishes from {@link TokenNotBoundError} (no bindings at all).
+ *
+ * Thrown when a `{ name }` or `{ tag }` hint is specified but no registered binding satisfies it
+ * (e.g. `Container.resolve`, `Container.resolveAsync`, `Container.resolveOptional`,
+ * `Container.resolveAll`, `Container.resolveAllAsync`, and binding selection helpers such as
+ * {@link selectBindingForRegistry}).
+ *
+ * Code: `"NO_MATCHING_BINDING"`
  */
 declare class NoMatchingBindingError extends DiError {
   readonly code = "NO_MATCHING_BINDING";
+  /**
+   * The `Token.name` or `Constructor.name` that was resolved.
+   */
   readonly tokenName: string;
+  /**
+   * The name/tag hint that failed to match any binding.
+   */
   readonly hint: ResolveHint;
+  /**
+   * Label path from the resolution root to the failing token.
+   */
   readonly resolutionPath: readonly string[];
   constructor(tokenName: string, hint: ResolveHint, resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when resolving a value for a token that has no binding.
+ * Raised when no binding exists for the requested token or constructor.
+ *
+ * Thrown by `Container.resolve`, `Container.resolveAsync`, and during transitive
+ * dependency resolution when a required token has never been registered.
+ *
+ * Note on optional resolution:
+ * - Root-level `Container.resolveOptional` returns `undefined` when **that key** has no
+ *   registry entries (it never throws this error for the root key in that case). Missing
+ *   **transitive** dependencies still throw during instantiation.
+ * - `ResolutionContext.resolveOptional` (used inside factories) catches this error
+ *   internally to return `undefined` for missing dependencies.
+ *
+ * Code: `"TOKEN_NOT_BOUND"`
  */
 declare class TokenNotBoundError extends DiError {
   readonly code = "TOKEN_NOT_BOUND";
+  /**
+   * The `Token.name` or `Constructor.name` that could not be found.
+   */
   readonly tokenName: string;
+  /**
+   * Label path from the resolution root to the missing token.
+   */
   readonly resolutionPath: readonly string[];
   constructor(tokenName: string, resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when the dependency graph contains a cycle during resolution.
+ * Raised when a token is encountered a second time on the same resolution call stack,
+ * indicating a cyclic dependency (A → B → … → A).
+ *
+ * Also raised during module loading when `import()` forms a cycle between modules.
+ *
+ * Code: `"CIRCULAR_DEPENDENCY"`
  */
 declare class CircularDependencyError extends DiError {
   readonly code = "CIRCULAR_DEPENDENCY";
+  /**
+   * Full label path including the repeated token at the end.
+   */
   readonly resolutionPath: readonly string[];
+  /**
+   * Mutable copy of {@link resolutionPath} for consumer convenience.
+   */
   readonly cycle: string[];
   constructor(resolutionPath: readonly string[], options?: ErrorOptions);
 }
 /**
- * Raised when a class binding requires `@injectable()` / `Symbol.metadata` constructor metadata but none is present.
+ * Raised when the container's {@link MetadataReader} is **configured** and reports no
+ * constructor metadata for a `class` binding whose implementation has `arity > 0`.
+ *
+ * If `metadataReader` is `undefined`, the resolver calls `new ImplementationClass()` without
+ * this check — this error is **not** thrown in that configuration.
+ *
+ * Fix: add `@injectable([...deps])` on the class (so `getConstructorMetadata` returns params),
+ * or omit constructor parameters if you intentionally run without a reader.
+ *
+ * Code: `"MISSING_METADATA"`
  */
 declare class MissingMetadataError extends DiError {
   readonly code = "MISSING_METADATA";
+  /**
+   * Name of the class that is missing `@injectable()` metadata.
+   */
   readonly className: string;
+  /**
+   * Label path from the resolution root to the class binding.
+   */
   readonly resolutionPath: readonly string[];
   constructor(className: string, resolutionPath: readonly string[], options?: ErrorOptions);
 }
-/** Raised when `load()` is used with an async module. */
+/**
+ * Raised when the synchronous `Container.load()` is called with an {@link AsyncModule}.
+ * Use `Container.loadAsync()` or `Container.fromModulesAsync()` instead.
+ *
+ * Code: `"ASYNC_MODULE_LOAD"`
+ */
 declare class AsyncModuleLoadError extends DiError {
   readonly code = "ASYNC_MODULE_LOAD";
+  /**
+   * Name of the async module that was passed to the sync loader.
+   */
   readonly moduleName: string;
   constructor(moduleName: string, options?: ErrorOptions);
 }
 /**
- * Raised when `resolve()` is called on a binding chain that contains an async factory or
- * an async `onActivation` handler. Use `resolveAsync()` / `resolveAllAsync()` instead.
+ * Raised when synchronous `Container.resolve()` / `Container.resolveAll()` encounters an
+ * async operation: an `async-dynamic` factory, a `toDynamic` factory that returns a Promise,
+ * an `onActivation` handler that returns a Promise, or a `@postConstruct` method that
+ * returns a Promise.
+ *
+ * Fix: switch to `Container.resolveAsync()` / `Container.resolveAllAsync()`.
+ *
+ * Code: `"ASYNC_RESOLUTION"`
  */
 declare class AsyncResolutionError extends DiError {
   readonly code = "ASYNC_RESOLUTION";
+  /**
+   * Token or class name that triggered the async path.
+   */
   readonly tokenName: string;
+  /**
+   * Label path from the resolution root to the async binding.
+   */
   readonly resolutionPath: readonly string[];
+  /**
+   * Human-readable description of why async resolution was required.
+   */
   readonly reason: string;
   constructor(tokenName: string, resolutionPath: readonly string[], reason: string, options?: ErrorOptions);
 }
-/** Structured payload attached to {@link ScopeViolationError}. */
+/**
+ * Structured payload passed to the {@link ScopeViolationError} constructor.
+ * Carries identities and scopes of both the long-lived consumer and the shorter-lived dependency.
+ */
 type ScopeViolationDetails = {
   readonly consumerBindingId: BindingIdentifier;
   readonly consumerKind: Binding<unknown>["kind"];
@@ -82,8 +185,16 @@ type ScopeViolationDetails = {
   readonly resolutionPath: readonly string[];
 };
 /**
- * Raised when a long-lived binding would capture a shorter-lived (scoped or transient) dependency
- * (captive dependency). Constant value dependencies are excluded.
+ * Raised for a **captive dependency**: a singleton consumer resolves (or would resolve) a
+ * non-constant binding whose lifetime is `scoped` or `transient`. Constant bindings are exempt.
+ *
+ * - **Runtime:** each resolution step checks the parent on the materialization stack, so
+ *   violations are detected along the actual construction chain.
+ * - **`Container.validate()`:** {@link validateScopeRules} walks **direct** static edges from
+ *   {@link listResolvedDependencies} only — it does not recursively expand the whole graph,
+ *   so it may miss violations that appear only deeper in the dependency tree.
+ *
+ * Code: `"SCOPE_VIOLATION"`
  */
 declare class ScopeViolationError extends DiError {
   readonly code = "SCOPE_VIOLATION";
@@ -97,4 +208,4 @@ declare class ScopeViolationError extends DiError {
   constructor(details: ScopeViolationDetails, options?: ErrorOptions);
 }
 //#endregion
-export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError };
+export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError, formatResolutionPath };

package/dist/errors.mjs

@@ -1,9 +1,18 @@
 //#region src/errors.ts
-/** Formats a resolution path array into a human-readable `"A -> B -> C"` string. */
+/**
+* Formats a resolution path array into a human-readable `"A -> B -> C"` string.
+*/
 function formatResolutionPath(resolutionPath) {
 	return resolutionPath.length > 0 ? resolutionPath.join(" -> ") : "(empty)";
 }
-/** Serializes a {@link ResolveHint} to a debug string; never throws even for exotic values. */
+const SCOPE_LABELS = {
+	singleton: "Singleton",
+	scoped: "Scoped",
+	transient: "Transient"
+};
+/**
+* Serializes a {@link ResolveHint} to a debug string; never throws even for exotic values.
+*/
 function safeSerializeHint(hint) {
 	if (hint === void 0) return "(none)";
 	try {
@@ -19,7 +28,11 @@ function safeSerializeHint(hint) {
 	}
 }
 /**
-* Base error for all `@codefast/di` failures. Subclasses expose a stable, machine-readable `code`.
+* Base error for all `@codefast/di` failures.
+*
+* Every concrete subclass exposes a stable, machine-readable {@link DiError.code} property
+* (e.g. `"TOKEN_NOT_BOUND"`) so consumers can `switch` on error type without relying
+* on `instanceof` across package versions.
 */
 var DiError = class extends Error {
 	constructor(message, options) {
@@ -29,21 +42,43 @@ var DiError = class extends Error {
 };
 /**
 * Raised for internal programming errors — invalid library usage or unexpected state that
-* indicates a bug in the caller (e.g. accessing an uninitialized container, misconfigured binding).
+* indicates a bug in the caller or the library itself.
+*
+* Examples: double `to*()` call on a {@link BindingBuilder}, ambiguous binding resolution
+* with multiple candidates, or scope mutation on a constant binding.
+*
+* Code: `"INTERNAL_ERROR"`
 */
 var InternalError = class extends DiError {
 	code = "INTERNAL_ERROR";
 };
 /**
-* Raised when a name/tag filter matches no binding although other bindings exist for the token.
+* Raised when bindings exist for the token but none match the provided name/tag hint.
+* Distinguishes from {@link TokenNotBoundError} (no bindings at all).
+*
+* Thrown when a `{ name }` or `{ tag }` hint is specified but no registered binding satisfies it
+* (e.g. `Container.resolve`, `Container.resolveAsync`, `Container.resolveOptional`,
+* `Container.resolveAll`, `Container.resolveAllAsync`, and binding selection helpers such as
+* {@link selectBindingForRegistry}).
+*
+* Code: `"NO_MATCHING_BINDING"`
 */
 var NoMatchingBindingError = class extends DiError {
 	code = "NO_MATCHING_BINDING";
+	/**
+	* The `Token.name` or `Constructor.name` that was resolved.
+	*/
 	tokenName;
+	/**
+	* The name/tag hint that failed to match any binding.
+	*/
 	hint;
+	/**
+	* Label path from the resolution root to the failing token.
+	*/
 	resolutionPath;
 	constructor(tokenName, hint, resolutionPath, options) {
-		const pathText = resolutionPath.length > 0 ? resolutionPath.join(" -> ") : "(empty)";
+		const pathText = formatResolutionPath(resolutionPath);
 		const hintText = safeSerializeHint(hint);
 		super(`No binding matched resolve options ${hintText} for token "${tokenName}" (resolution path: ${pathText})`, options);
 		this.tokenName = tokenName;
@@ -52,11 +87,29 @@ var NoMatchingBindingError = class extends DiError {
 	}
 };
 /**
-* Raised when resolving a value for a token that has no binding.
+* Raised when no binding exists for the requested token or constructor.
+*
+* Thrown by `Container.resolve`, `Container.resolveAsync`, and during transitive
+* dependency resolution when a required token has never been registered.
+*
+* Note on optional resolution:
+* - Root-level `Container.resolveOptional` returns `undefined` when **that key** has no
+*   registry entries (it never throws this error for the root key in that case). Missing
+*   **transitive** dependencies still throw during instantiation.
+* - `ResolutionContext.resolveOptional` (used inside factories) catches this error
+*   internally to return `undefined` for missing dependencies.
+*
+* Code: `"TOKEN_NOT_BOUND"`
 */
 var TokenNotBoundError = class extends DiError {
 	code = "TOKEN_NOT_BOUND";
+	/**
+	* The `Token.name` or `Constructor.name` that could not be found.
+	*/
 	tokenName;
+	/**
+	* Label path from the resolution root to the missing token.
+	*/
 	resolutionPath;
 	constructor(tokenName, resolutionPath, options) {
 		const pathText = formatResolutionPath(resolutionPath);
@@ -66,11 +119,22 @@ var TokenNotBoundError = class extends DiError {
 	}
 };
 /**
-* Raised when the dependency graph contains a cycle during resolution.
+* Raised when a token is encountered a second time on the same resolution call stack,
+* indicating a cyclic dependency (A → B → … → A).
+*
+* Also raised during module loading when `import()` forms a cycle between modules.
+*
+* Code: `"CIRCULAR_DEPENDENCY"`
 */
 var CircularDependencyError = class extends DiError {
 	code = "CIRCULAR_DEPENDENCY";
+	/**
+	* Full label path including the repeated token at the end.
+	*/
 	resolutionPath;
+	/**
+	* Mutable copy of {@link resolutionPath} for consumer convenience.
+	*/
 	cycle;
 	constructor(resolutionPath, options) {
 		const pathText = formatResolutionPath(resolutionPath);
@@ -80,11 +144,26 @@ var CircularDependencyError = class extends DiError {
 	}
 };
 /**
-* Raised when a class binding requires `@injectable()` / `Symbol.metadata` constructor metadata but none is present.
+* Raised when the container's {@link MetadataReader} is **configured** and reports no
+* constructor metadata for a `class` binding whose implementation has `arity > 0`.
+*
+* If `metadataReader` is `undefined`, the resolver calls `new ImplementationClass()` without
+* this check — this error is **not** thrown in that configuration.
+*
+* Fix: add `@injectable([...deps])` on the class (so `getConstructorMetadata` returns params),
+* or omit constructor parameters if you intentionally run without a reader.
+*
+* Code: `"MISSING_METADATA"`
 */
 var MissingMetadataError = class extends DiError {
 	code = "MISSING_METADATA";
+	/**
+	* Name of the class that is missing `@injectable()` metadata.
+	*/
 	className;
+	/**
+	* Label path from the resolution root to the class binding.
+	*/
 	resolutionPath;
 	constructor(className, resolutionPath, options) {
 		const pathText = formatResolutionPath(resolutionPath);
@@ -93,9 +172,17 @@ var MissingMetadataError = class extends DiError {
 		this.resolutionPath = resolutionPath;
 	}
 };
-/** Raised when `load()` is used with an async module. */
+/**
+* Raised when the synchronous `Container.load()` is called with an {@link AsyncModule}.
+* Use `Container.loadAsync()` or `Container.fromModulesAsync()` instead.
+*
+* Code: `"ASYNC_MODULE_LOAD"`
+*/
 var AsyncModuleLoadError = class extends DiError {
 	code = "ASYNC_MODULE_LOAD";
+	/**
+	* Name of the async module that was passed to the sync loader.
+	*/
 	moduleName;
 	constructor(moduleName, options) {
 		super(`Cannot load async module "${moduleName}" synchronously; use loadAsync() or Container.fromModulesAsync().`, options);
@@ -103,13 +190,28 @@ var AsyncModuleLoadError = class extends DiError {
 	}
 };
 /**
-* Raised when `resolve()` is called on a binding chain that contains an async factory or
-* an async `onActivation` handler. Use `resolveAsync()` / `resolveAllAsync()` instead.
+* Raised when synchronous `Container.resolve()` / `Container.resolveAll()` encounters an
+* async operation: an `async-dynamic` factory, a `toDynamic` factory that returns a Promise,
+* an `onActivation` handler that returns a Promise, or a `@postConstruct` method that
+* returns a Promise.
+*
+* Fix: switch to `Container.resolveAsync()` / `Container.resolveAllAsync()`.
+*
+* Code: `"ASYNC_RESOLUTION"`
 */
 var AsyncResolutionError = class extends DiError {
 	code = "ASYNC_RESOLUTION";
+	/**
+	* Token or class name that triggered the async path.
+	*/
 	tokenName;
+	/**
+	* Label path from the resolution root to the async binding.
+	*/
 	resolutionPath;
+	/**
+	* Human-readable description of why async resolution was required.
+	*/
 	reason;
 	constructor(tokenName, resolutionPath, reason, options) {
 		const pathText = formatResolutionPath(resolutionPath);
@@ -120,8 +222,16 @@ var AsyncResolutionError = class extends DiError {
 	}
 };
 /**
-* Raised when a long-lived binding would capture a shorter-lived (scoped or transient) dependency
-* (captive dependency). Constant value dependencies are excluded.
+* Raised for a **captive dependency**: a singleton consumer resolves (or would resolve) a
+* non-constant binding whose lifetime is `scoped` or `transient`. Constant bindings are exempt.
+*
+* - **Runtime:** each resolution step checks the parent on the materialization stack, so
+*   violations are detected along the actual construction chain.
+* - **`Container.validate()`:** {@link validateScopeRules} walks **direct** static edges from
+*   {@link listResolvedDependencies} only — it does not recursively expand the whole graph,
+*   so it may miss violations that appear only deeper in the dependency tree.
+*
+* Code: `"SCOPE_VIOLATION"`
 */
 var ScopeViolationError = class extends DiError {
 	code = "SCOPE_VIOLATION";
@@ -136,9 +246,7 @@ var ScopeViolationError = class extends DiError {
 		const pathText = formatResolutionPath(details.resolutionPath);
 		const consumerLabel = details.consumerLabel ?? String(details.consumerBindingId);
 		const dependencyLabel = details.dependencyLabel ?? String(details.dependencyBindingId);
-		const consumerScopeLabel = details.consumerScope.charAt(0).toUpperCase() + details.consumerScope.slice(1);
-		const dependencyScopeLabel = details.dependencyScope.charAt(0).toUpperCase() + details.dependencyScope.slice(1);
-		super(`Scope Violation: ${consumerScopeLabel} "${consumerLabel}" cannot depend on ${dependencyScopeLabel} "${dependencyLabel}" (resolution path: ${pathText})`, options);
+		super(`Scope Violation: ${SCOPE_LABELS[details.consumerScope]} "${consumerLabel}" cannot depend on ${SCOPE_LABELS[details.dependencyScope]} "${dependencyLabel}" (resolution path: ${pathText})`, options);
 		this.consumerBindingId = details.consumerBindingId;
 		this.consumerKind = details.consumerKind;
 		this.consumerScope = details.consumerScope;
@@ -149,4 +257,4 @@ var ScopeViolationError = class extends DiError {
 	}
 };
 //#endregion
-export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError };
+export { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError, formatResolutionPath };

package/dist/index.d.mts

@@ -3,8 +3,8 @@ import { ActivationHandler, BindingBuilder, BindingIdentifier, BindingScope, Con
 import { ContainerGraphJson, ContainerSnapshot } from "./inspector.mjs";
 import { AsyncModule, AsyncModuleBuilder, Module, ModuleBuilder } from "./module.mjs";
 import { Container } from "./container.mjs";
-import { InjectOptions, inject, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
+import { InjectOptions, inject, injectAll, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
 import { InjectableDependency, getAutoRegistered, injectable } from "./decorators/injectable.mjs";
 import { postConstruct, preDestroy } from "./decorators/lifecycle-decorators.mjs";
 import { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationDetails, ScopeViolationError, TokenNotBoundError } from "./errors.mjs";
-export { type ActivationHandler, AsyncModule, type AsyncModuleBuilder, AsyncModuleLoadError, AsyncResolutionError, type BindingBuilder, type BindingIdentifier, type BindingScope, CircularDependencyError, type ConstraintContext, type Constructor, Container, type ContainerGraphJson, type ContainerSnapshot, type DeactivationHandler, DiError, type InjectOptions, type InjectableDependency, InternalError, MissingMetadataError, Module, type ModuleBuilder, NoMatchingBindingError, type ResolveOptions, type ScopeViolationDetails, ScopeViolationError, type Token, TokenNotBoundError, type TokenValue, getAutoRegistered, inject, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };
+export { type ActivationHandler, AsyncModule, type AsyncModuleBuilder, AsyncModuleLoadError, AsyncResolutionError, type BindingBuilder, type BindingIdentifier, type BindingScope, CircularDependencyError, type ConstraintContext, type Constructor, Container, type ContainerGraphJson, type ContainerSnapshot, type DeactivationHandler, DiError, type InjectOptions, type InjectableDependency, InternalError, MissingMetadataError, Module, type ModuleBuilder, NoMatchingBindingError, type ResolveOptions, type ScopeViolationDetails, ScopeViolationError, type Token, TokenNotBoundError, type TokenValue, getAutoRegistered, inject, injectAll, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };