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

package/dist/module.d.mts

@@ -3,14 +3,27 @@ import { BindingBuilder, Constructor } from "./binding.mjs";
 
 //#region src/module.d.ts
 /**
- * Builder passed to synchronous module setup: register bindings and import other sync modules.
+ * Builder passed to the setup callback of a synchronous {@link Module}.
+ * Use `import()` to declare module dependencies (sync modules only —
+ * passing an {@link AsyncModule} throws {@link InternalError}) and `bind()` to register tokens.
+ *
+ * **Single slot (last-wins)** — `bind(key).to*(...)` with no `whenNamed` / `whenTagged` / `when`
+ * *before* the `to*()` call replaces all prior bindings for `key` from this module pass.
+ *
+ * **Multi-binding** — put at least one disambiguator *before* `to*()` (e.g.
+ * `bind(key).whenNamed("a").to*(...)`, `whenTagged` before `to*()`, or `when` before `to*()`).
+ * Each such line **appends** another binding so {@link Container.resolveAll} can return every
+ * implementation. Use this order in modules; chaining `.to*(...).whenNamed()` only updates that
+ * binding in place and does not stack multiple registrations across lines.
  */
 type ModuleBuilder = {
   readonly import: (...modules: Module[]) => void;
   readonly bind: <Value>(key: Token<Value> | Constructor<Value>) => BindingBuilder<Value>;
 };
 /**
- * Builder passed to async module setup.
+ * Builder passed to the setup callback of an {@link AsyncModule}.
+ * Unlike {@link ModuleBuilder}, `import()` accepts both sync and async modules.
+ * Async sub-imports are collected and awaited **after** the setup callback returns.
  */
 type AsyncModuleBuilder = {
   readonly import: (...modules: (Module | AsyncModule)[]) => void;
@@ -24,8 +37,17 @@ type AsyncModuleBuilder = {
  * binding ids each module produced; the module itself never sees a container reference.
  */
 declare class Module {
+  /**
+   * Human-readable label used in error messages, graph output, and module-cycle diagnostics.
+   */
   readonly name: string;
+  /**
+   * The user-supplied setup callback; invoked exactly once per `load()` call.
+   */
   private readonly syncSetup;
+  /**
+   * @internal Use {@link Module.create} instead.
+   */
   private constructor();
   /**
    * Defines a synchronous module.
@@ -46,9 +68,19 @@ declare class Module {
 /**
  * An async module whose setup callback may `await` before registering bindings.
  * Prefer {@link Module.createAsync} over constructing this class directly.
+ *
+ * Load via `Container.loadAsync()` or `Container.fromModulesAsync()`;
+ * passing an `AsyncModule` to the synchronous `Container.load()` throws
+ * {@link AsyncModuleLoadError}.
  */
 declare class AsyncModule {
+  /**
+   * Human-readable label used in error messages and graph output.
+   */
   readonly name: string;
+  /**
+   * The user-supplied async setup callback; invoked exactly once per `loadAsync()` call.
+   */
   private readonly asyncSetup;
   constructor(name: string, asyncSetup: (builder: AsyncModuleBuilder) => Promise<void>);
   /**

package/dist/module.mjs

@@ -7,8 +7,17 @@
 * binding ids each module produced; the module itself never sees a container reference.
 */
 var Module = class Module {
+	/**
+	* Human-readable label used in error messages, graph output, and module-cycle diagnostics.
+	*/
 	name;
+	/**
+	* The user-supplied setup callback; invoked exactly once per `load()` call.
+	*/
 	syncSetup;
+	/**
+	* @internal Use {@link Module.create} instead.
+	*/
 	constructor(name, syncSetup) {
 		this.name = name;
 		this.syncSetup = syncSetup;
@@ -38,9 +47,19 @@ var Module = class Module {
 /**
 * An async module whose setup callback may `await` before registering bindings.
 * Prefer {@link Module.createAsync} over constructing this class directly.
+*
+* Load via `Container.loadAsync()` or `Container.fromModulesAsync()`;
+* passing an `AsyncModule` to the synchronous `Container.load()` throws
+* {@link AsyncModuleLoadError}.
 */
 var AsyncModule = class {
+	/**
+	* Human-readable label used in error messages and graph output.
+	*/
 	name;
+	/**
+	* The user-supplied async setup callback; invoked exactly once per `loadAsync()` call.
+	*/
 	asyncSetup;
 	constructor(name, asyncSetup) {
 		this.name = name;

package/dist/registry.d.mts

@@ -7,15 +7,39 @@ import { Binding, BindingIdentifier, Constructor } from "./binding.mjs";
  */
 type RegistryKey = Token<unknown> | Constructor<unknown>;
 /**
- * Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+ * Flat, in-memory storage for {@link Binding} entries keyed by {@link RegistryKey}.
+ * Each key maps to an ordered list of bindings (multi-binding support).
+ *
+ * The registry is a "dumb" store — it does not perform selection, scope caching, or
+ * lifecycle management. Those concerns live in `DependencyResolver` and `ScopeManager`.
+ *
+ * Mutation styles:
+ * - `add` — append-only; never removes existing entries.
+ * - `replaceById` — swaps a single binding in place by ID; no removal callback.
+ * - `remove` / `removeById` — delete entries **without** notifying callers; the caller
+ *   is responsible for draining the scope cache before calling these.
+ * - `replaceKeyLastWins` — replaces all bindings for a key with a single new one **and**
+ *   invokes the `onReplaced` callback for each evicted binding, giving the caller
+ *   (typically the container or scope manager) a chance to run deactivation.
  */
 declare class BindingRegistry {
+  /**
+   * Primary index: registry key → ordered binding list.
+   * Reference equality on the key (i.e. the same {@link Token} or {@link Constructor} object).
+   */
   private readonly bindingsByKey;
-  /** Appends `binding` to the list for `key` (multi-binding: each call adds an entry). */
+  /**
+   * Appends `binding` to the list for `key` (multi-binding: each call adds an entry).
+   */
   add<Value>(key: Token<Value> | Constructor<Value>, binding: Binding<Value>): void;
-  /** Returns all bindings registered for `key`, or `undefined` if none exist. */
+  /**
+   * Returns all bindings registered for `key`, or `undefined` if none exist.
+   */
   get<Value>(key: Token<Value> | Constructor<Value>): readonly Binding<Value>[] | undefined;
-  /** Removes all bindings for `key` without running any deactivation hooks. */
+  /**
+   * Removes all bindings for `key`. Does **not** invoke any callback — the caller must
+   * drain the scope cache (run deactivation) for the affected bindings before calling this.
+   */
   remove(key: RegistryKey): void;
   /**
    * Returns owned registry rows (does not include parent containers).
@@ -24,13 +48,20 @@ declare class BindingRegistry {
     key: RegistryKey;
     bindings: readonly Binding<unknown>[];
   }[];
-  /** Removes the single binding with the given `id` across all keys. */
+  /**
+   * Removes the single binding whose `id` matches, scanning all keys.
+   * Like {@link remove}, does **not** invoke a removal callback.
+   */
   removeById(id: BindingIdentifier): void;
-  /** Swaps the binding with the given `id` in place, preserving its position in the list. */
+  /**
+   * Swaps the binding with the given `id` in place, preserving its position in the list.
+   */
   replaceById(id: BindingIdentifier, next: Binding<unknown>): void;
   /**
-   * Replaces all bindings for `key` with a single binding (module "last-wins" semantics).
-   * Invokes `onReplaced` for every removed binding so scopes can run deactivation.
+   * Replaces all bindings for `key` with a single new binding (module "last-wins" semantics).
+   * Unlike {@link remove} / {@link removeById}, this method invokes `onReplaced` for every
+   * evicted binding **before** inserting the replacement, giving the caller (e.g. the
+   * container's scope manager) a chance to release cached instances and run deactivation hooks.
    */
   replaceKeyLastWins<Value>(key: Token<Value> | Constructor<Value>, binding: Binding<Value>, onReplaced: (removed: Binding<unknown>) => void): void;
 }

package/dist/registry.mjs

@@ -1,10 +1,29 @@
 //#region src/registry.ts
 /**
-* Dumb storage for bindings keyed by token or constructor. Selection and construction logic live elsewhere.
+* Flat, in-memory storage for {@link Binding} entries keyed by {@link RegistryKey}.
+* Each key maps to an ordered list of bindings (multi-binding support).
+*
+* The registry is a "dumb" store — it does not perform selection, scope caching, or
+* lifecycle management. Those concerns live in `DependencyResolver` and `ScopeManager`.
+*
+* Mutation styles:
+* - `add` — append-only; never removes existing entries.
+* - `replaceById` — swaps a single binding in place by ID; no removal callback.
+* - `remove` / `removeById` — delete entries **without** notifying callers; the caller
+*   is responsible for draining the scope cache before calling these.
+* - `replaceKeyLastWins` — replaces all bindings for a key with a single new one **and**
+*   invokes the `onReplaced` callback for each evicted binding, giving the caller
+*   (typically the container or scope manager) a chance to run deactivation.
 */
 var BindingRegistry = class {
+	/**
+	* Primary index: registry key → ordered binding list.
+	* Reference equality on the key (i.e. the same {@link Token} or {@link Constructor} object).
+	*/
 	bindingsByKey = /* @__PURE__ */ new Map();
-	/** Appends `binding` to the list for `key` (multi-binding: each call adds an entry). */
+	/**
+	* Appends `binding` to the list for `key` (multi-binding: each call adds an entry).
+	*/
 	add(key, binding) {
 		const registryKey = key;
 		const nextBinding = binding;
@@ -12,11 +31,16 @@ var BindingRegistry = class {
 		const merged = existing === void 0 ? [nextBinding] : [...existing, nextBinding];
 		this.bindingsByKey.set(registryKey, merged);
 	}
-	/** Returns all bindings registered for `key`, or `undefined` if none exist. */
+	/**
+	* Returns all bindings registered for `key`, or `undefined` if none exist.
+	*/
 	get(key) {
 		return this.bindingsByKey.get(key);
 	}
-	/** Removes all bindings for `key` without running any deactivation hooks. */
+	/**
+	* Removes all bindings for `key`. Does **not** invoke any callback — the caller must
+	* drain the scope cache (run deactivation) for the affected bindings before calling this.
+	*/
 	remove(key) {
 		this.bindingsByKey.delete(key);
 	}
@@ -29,7 +53,10 @@ var BindingRegistry = class {
 			bindings
 		}));
 	}
-	/** Removes the single binding with the given `id` across all keys. */
+	/**
+	* Removes the single binding whose `id` matches, scanning all keys.
+	* Like {@link remove}, does **not** invoke a removal callback.
+	*/
 	removeById(id) {
 		for (const [registryKey, list] of [...this.bindingsByKey.entries()]) {
 			const filtered = list.filter((binding) => binding.id !== id);
@@ -38,7 +65,9 @@ var BindingRegistry = class {
 			else this.bindingsByKey.set(registryKey, filtered);
 		}
 	}
-	/** Swaps the binding with the given `id` in place, preserving its position in the list. */
+	/**
+	* Swaps the binding with the given `id` in place, preserving its position in the list.
+	*/
 	replaceById(id, next) {
 		for (const [registryKey, list] of this.bindingsByKey.entries()) {
 			const index = list.findIndex((binding) => binding.id === id);
@@ -50,8 +79,10 @@ var BindingRegistry = class {
 		}
 	}
 	/**
-	* Replaces all bindings for `key` with a single binding (module "last-wins" semantics).
-	* Invokes `onReplaced` for every removed binding so scopes can run deactivation.
+	* Replaces all bindings for `key` with a single new binding (module "last-wins" semantics).
+	* Unlike {@link remove} / {@link removeById}, this method invokes `onReplaced` for every
+	* evicted binding **before** inserting the replacement, giving the caller (e.g. the
+	* container's scope manager) a chance to release cached instances and run deactivation hooks.
 	*/
 	replaceKeyLastWins(key, binding, onReplaced) {
 		const registryKey = key;

package/dist/resolver.d.mts

@@ -5,29 +5,114 @@ import { MetadataReader } from "./metadata/metadata-types.mjs";
 import { ScopeManager } from "./scope.mjs";
 
 //#region src/resolver.d.ts
-/** Dependencies injected into {@link DependencyResolver} at construction time. */
+/**
+ * Dependencies injected into {@link DependencyResolver} at construction time.
+ */
 type ResolverDependencies = {
-  /** Looks up all bindings registered for a given registry key (own + parent containers). */readonly lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined; /** Manages singleton/scoped instance caches and deactivation. */
-  readonly scopeManager: ScopeManager; /** Reads `@injectable()` and lifecycle metadata from constructors. Omit to disable decorator support. */
+  /**
+   * Looks up all bindings registered for a given registry key (own + parent containers).
+   */
+  readonly lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined;
+  /**
+   * Manages singleton/scoped instance caches and deactivation.
+   */
+  readonly scopeManager: ScopeManager;
+  /**
+   * Reads `@injectable()` and lifecycle metadata from constructors. Omit to disable decorator support.
+   */
   readonly metadataReader?: MetadataReader;
 };
 /**
- * Walks the binding graph, manages circular-dependency detection, delegates caching to
- * {@link ScopeManager}, and calls lifecycle hooks. Used exclusively by the container.
+ * Stateless graph walker: selects a binding, checks for cycles and scope violations,
+ * delegates instance caching to `ScopeManager`, and runs lifecycle hooks.
+ *
+ * Resolution algorithm (per token):
+ * 1. Lookup all bindings for the registry key.
+ * 2. Apply name/tag hint and `when()` constraint filtering.
+ * 3. Circular-dependency check via a mutable `visiting` set (per call tree).
+ * 4. Captive-dependency check via the `materializationStack`.
+ * 5. Scope-cache hit → return cached instance.
+ * 6. Scope-cache miss → `materialize` → `@postConstruct` → `onActivation` → cache.
+ *
+ * Used exclusively by `DefaultContainer`; not part of the public API.
  */
 declare class DependencyResolver {
   private readonly deps;
   constructor(deps: ResolverDependencies);
-  /** Entry point for synchronous single-binding resolution (no path prefix). */
+  /**
+   * Entry point for synchronous single-binding resolution.
+   *
+   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
+   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
+   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
+   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
+   * @throws {@link AsyncResolutionError} — an `async-dynamic` binding or async lifecycle/activation on the sync path.
+   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
+   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
+   */
   resolveRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
-  /** Entry point for async single-binding resolution (no path prefix). */
+  /**
+   * Entry point for async single-binding resolution. Awaits `async-dynamic` factories
+   * and async lifecycle hooks that would cause {@link AsyncResolutionError} on the sync path.
+   *
+   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
+   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
+   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
+   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
+   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
+   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
+   */
   resolveAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value>;
-  /** Returns `undefined` instead of throwing when no binding is found; still throws on circular deps or async factories. */
+  /**
+   * Optional resolution for the **requested key only**: returns `undefined` when that key has no
+   * bindings or every candidate is filtered out **without** a name/tag hint — without throwing
+   * {@link TokenNotBoundError} for those cases. Instantiating the selected binding still runs the
+   * normal sync resolution path for nested dependencies; an unregistered transitive dependency
+   * throws {@link TokenNotBoundError} as usual.
+   *
+   * Behavioral rules:
+   * 1. If the registry key is completely unbound → returns `undefined`.
+   * 2. If no candidate survives constraint filtering (without a hint) → returns `undefined`.
+   * 3. If a name/tag hint was provided but no binding matches it → throws {@link NoMatchingBindingError}.
+   * 4. Still throws on: circular dependencies, async operations on the sync path,
+   *    scope violations, ambiguous multi-binding matches, and {@link TokenNotBoundError} when a
+   *    required nested dependency is unbound.
+   */
   resolveOptionalRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
-  /** Resolves all bindings for `key` synchronously; throws on async factories. */
+  /**
+   * Resolves every matching binding for `key` synchronously into an array.
+   * Returns an empty array when no bindings exist (does not throw).
+   *
+   * @throws {@link AsyncResolutionError} — any candidate is `async-dynamic`.
+   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
+   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveRoot}).
+   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
+   * @throws {@link ScopeViolationError} — captive dependency during materialization.
+   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
+   */
   resolveAllRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
-  /** Resolves all bindings for `key`, awaiting any async factories in the set. */
+  /**
+   * Async counterpart of {@link resolveAllRoot}: resolves every matching binding for `key`,
+   * awaiting `async-dynamic` factories. Returns an empty array when no bindings exist.
+   *
+   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
+   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveAsyncRoot}).
+   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
+   * @throws {@link ScopeViolationError} — captive dependency during materialization.
+   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
+   */
   resolveAllAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
+  /**
+   * Context-aware sync `resolveAll`: extends the current resolution path and preserves
+   * visiting/materialization stacks so nested multi-resolution participates in cycle and
+   * captive-dependency checks exactly like single-value {@link resolve}.
+   */
+  private resolveAll;
+  /**
+   * Async counterpart of {@link resolveAll}: keeps the current path and materialization stack
+   * so `when()` constraints and scope validation behave consistently for nested multi-resolution.
+   */
+  private resolveAllAsync;
   /**
    * Assembles the read-only {@link ConstraintContext} snapshot passed to `when()` predicates.
    * Extracts the top-of-stack frame as `parent` and the rest as `ancestors`.
@@ -46,6 +131,9 @@ declare class DependencyResolver {
    */
   private createContext;
   /**
+   * Core synchronous resolution: lookup → filter → cycle check → scope check → instantiate.
+   * Called recursively when a binding's dependencies need resolution.
+   *
    * @param key - Token or constructor being resolved.
    * @param hint - Optional name/tag filter for multi-binding selection.
    * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
@@ -54,6 +142,9 @@ declare class DependencyResolver {
    */
   private resolve;
   /**
+   * Core async resolution: same pipeline as {@link resolve} but awaits `async-dynamic`
+   * factories and async lifecycle hooks instead of throwing {@link AsyncResolutionError}.
+   *
    * @param key - Token or constructor being resolved.
    * @param hint - Optional name/tag filter for multi-binding selection.
    * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
@@ -77,8 +168,12 @@ declare class DependencyResolver {
    */
   private assertCaptiveDependencyFromMaterializationStack;
   /**
-   * Synchronously produces the raw instance for a binding without touching the scope cache.
-   * Dispatches on `binding.kind`; throws {@link AsyncResolutionError} for `async-dynamic` factories.
+   * Synchronously produces the raw instance for a binding **without** touching the scope cache
+   * or running lifecycle hooks. The caller ({@link instantiateBinding}) wraps this with
+   * cache logic and post-construction hooks.
+   *
+   * Dispatches on `binding.kind`; throws {@link AsyncResolutionError} if the binding is
+   * `async-dynamic` or if a `dynamic` / `resolved` factory returns a Promise.
    */
   private materialize;
   /**