@codefast/di 0.3.13 → 0.3.14-canary.1

package/dist/constraints.d.mts

@@ -3,15 +3,30 @@ import { ConstraintContext, Constructor } from "./binding.mjs";
 
 //#region src/constraints.d.ts
 /**
- * Matches when the direct parent materialization was registered for `registryKey`.
+ * Constraint predicate factory: matches when the direct parent on the materialization stack
+ * was registered under `registryKey`. Pass the result to {@link BindingBuilder.when}.
+ *
+ * @param registryKey - Token or constructor that the parent binding must be registered against.
+ * @returns A predicate compatible with {@link BindingBuilder.when}.
  */
 declare function whenParentIs(registryKey: Token<unknown> | Constructor<unknown>): (ctx: ConstraintContext) => boolean;
 /**
- * Matches when any ancestor on the materialization stack was registered for `registryKey`.
+ * Constraint predicate factory: matches when *any* ancestor on the materialization stack
+ * (not just the immediate parent) was registered under `registryKey`.
+ * Pass the result to {@link BindingBuilder.when}.
+ *
+ * @param registryKey - Token or constructor to search for across the full construction chain.
+ * @returns A predicate compatible with {@link BindingBuilder.when}.
  */
 declare function whenAnyAncestorIs(registryKey: Token<unknown> | Constructor<unknown>): (ctx: ConstraintContext) => boolean;
 /**
- * Matches when the immediate parent binding carries `tag` with `tagValue` (same metadata as {@link BindingBuilder.whenTagged} on the parent).
+ * Constraint predicate factory: matches when the immediate parent binding carries a tag
+ * whose key is `tag` and whose value is reference-equal to `tagValue` (`Object.is`).
+ * Pass the result to {@link BindingBuilder.when}.
+ *
+ * @param tag - Tag key to check on the parent binding.
+ * @param tagValue - Expected value; compared via `Object.is`.
+ * @returns A predicate compatible with {@link BindingBuilder.when}.
  */
 declare function whenTargetTagged(tag: string, tagValue: unknown): (ctx: ConstraintContext) => boolean;
 //#endregion

package/dist/constraints.mjs

@@ -1,18 +1,33 @@
 //#region src/constraints.ts
 /**
-* Matches when the direct parent materialization was registered for `registryKey`.
+* Constraint predicate factory: matches when the direct parent on the materialization stack
+* was registered under `registryKey`. Pass the result to {@link BindingBuilder.when}.
+*
+* @param registryKey - Token or constructor that the parent binding must be registered against.
+* @returns A predicate compatible with {@link BindingBuilder.when}.
 */
 function whenParentIs(registryKey) {
 	return (ctx) => ctx.parent?.registryKey === registryKey;
 }
 /**
-* Matches when any ancestor on the materialization stack was registered for `registryKey`.
+* Constraint predicate factory: matches when *any* ancestor on the materialization stack
+* (not just the immediate parent) was registered under `registryKey`.
+* Pass the result to {@link BindingBuilder.when}.
+*
+* @param registryKey - Token or constructor to search for across the full construction chain.
+* @returns A predicate compatible with {@link BindingBuilder.when}.
 */
 function whenAnyAncestorIs(registryKey) {
 	return (ctx) => ctx.materializationStack.some((frame) => frame.registryKey === registryKey);
 }
 /**
-* Matches when the immediate parent binding carries `tag` with `tagValue` (same metadata as {@link BindingBuilder.whenTagged} on the parent).
+* Constraint predicate factory: matches when the immediate parent binding carries a tag
+* whose key is `tag` and whose value is reference-equal to `tagValue` (`Object.is`).
+* Pass the result to {@link BindingBuilder.when}.
+*
+* @param tag - Tag key to check on the parent binding.
+* @param tagValue - Expected value; compared via `Object.is`.
+* @returns A predicate compatible with {@link BindingBuilder.when}.
 */
 function whenTargetTagged(tag, tagValue) {
 	return (ctx) => {

package/dist/container.d.mts

@@ -1,10 +1,13 @@
 import { Token } from "./token.mjs";
 import { RegistryKey } from "./registry.mjs";
-import { Binding, BindingBuilder, BindingIdentifier, Constructor, ResolveHint, ResolveOptions } from "./binding.mjs";
-import { ContainerGraphJson, ContainerSnapshot, DotGraphOptions } from "./inspector.mjs";
+import { Binding, BindingBuilder, BindingIdentifier, Constructor, ResolveHint } from "./binding.mjs";
+import { ContainerGraphJson, ContainerSnapshot, GraphOptions } from "./inspector.mjs";
 import { AsyncModule, Module } from "./module.mjs";
 
 //#region src/container.d.ts
+/**
+ * Union of sync and async modules accepted by `loadAsync` / `unloadAsync`.
+ */
 type ModuleLike = Module | AsyncModule;
 /**
  * Public contract for an IoC container (registry, modules, resolution, lifecycle).
@@ -14,56 +17,97 @@ type ModuleLike = Module | AsyncModule;
  * {@link Container.dispose} automatically at scope exit (TC39 Explicit Resource Management).
  */
 interface Container extends AsyncDisposable {
-  /** Starts a fluent binding builder for the given token or constructor. */
+  /**
+   * Starts a fluent binding builder for the given token or constructor.
+   */
   bind<Value>(token: Token<Value> | Constructor<Value>): BindingBuilder<Value>;
-  /** Removes all existing bindings for the token (with sync deactivation) then starts a fresh builder. */
+  /**
+   * Removes all existing bindings for the token (with sync deactivation) then starts a fresh builder.
+   */
   rebind<Value>(token: Token<Value> | Constructor<Value>): BindingBuilder<Value>;
-  /** Removes all bindings for a token or a single binding by its {@link BindingIdentifier}; runs sync deactivation. */
+  /**
+   * Removes all bindings for a token or a single binding by its {@link BindingIdentifier}; runs sync deactivation.
+   */
   unbind(tokenOrId: RegistryKey | BindingIdentifier): void;
-  /** Same as {@link unbind} but awaits async `onDeactivation` handlers before removing. */
+  /**
+   * Same as {@link unbind} but awaits async `onDeactivation` handlers before removing.
+   */
   unbindAsync(tokenOrId: RegistryKey | BindingIdentifier): Promise<void>;
-  /** Returns `true` if at least one binding exists for `token`, optionally filtered by `hint`. */
+  /**
+   * Returns `true` if at least one binding exists for `token`, optionally filtered by `hint`.
+   */
   has(token: RegistryKey, hint?: ResolveHint): boolean;
-  /** Resolves the token synchronously. Throws {@link AsyncResolutionError} if any binding in the chain is async. */
+  /**
+   * Resolves the token synchronously. Throws {@link AsyncResolutionError} if any binding in the chain is async.
+   */
   resolve<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
-  /** Resolves the token, awaiting any async factory in the chain. Safe for both sync and async bindings. */
+  /**
+   * Resolves the token, awaiting any async factory in the chain. Safe for both sync and async bindings.
+   */
   resolveAsync<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value>;
-  /** Resolves all bindings registered for the token (multi-binding). Throws {@link AsyncResolutionError} if any is async. */
+  /**
+   * Resolves all bindings registered for the token (multi-binding). Throws {@link AsyncResolutionError} if any is async.
+   */
   resolveAll<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
-  /** Async variant of {@link resolveAll} — safe when the multi-binding set contains async factories. */
+  /**
+   * Async variant of {@link resolveAll} — safe when the multi-binding set contains async factories.
+   */
   resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
-  /** Resolves the token or returns `undefined` if no binding is registered (never throws on missing). */
+  /**
+   * Resolves the token or returns `undefined` if no binding is registered (never throws on missing).
+   */
   resolveOptional<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
-  /** Registers bindings from one or more synchronous modules. Re-loading a module already present is a no-op. */
+  /**
+   * Registers bindings from one or more synchronous modules. Re-loading a module already present is a no-op.
+   */
   load(...modules: Module[]): void;
-  /** Registers bindings from sync and/or async modules, awaiting each async setup in sequence. */
+  /**
+   * Registers bindings from sync and/or async modules, awaiting each async setup in sequence.
+   */
   loadAsync(...modules: ModuleLike[]): Promise<void>;
-  /** Removes all bindings contributed by the given modules; runs sync deactivation on released singletons. */
+  /**
+   * Removes all bindings contributed by the given modules; runs sync deactivation on released singletons.
+   */
   unload(...modules: ModuleLike[]): void;
-  /** Same as {@link unload} but awaits async `onDeactivation` handlers. */
+  /**
+   * Same as {@link unload} but awaits async `onDeactivation` handlers.
+   */
   unloadAsync(...modules: ModuleLike[]): Promise<void>;
-  /** Eagerly constructs every singleton binding so the first request is never cold. */
+  /**
+   * Eagerly constructs every singleton binding so the first request is never cold.
+   */
   initializeAsync(): Promise<void>;
-  /** Scans {@link getAutoRegistered} entries and binds each to its declared scope. Returns the count added. */
+  /**
+   * Scans {@link getAutoRegistered} entries and binds each to its declared scope. Returns the count added.
+   */
   loadAutoRegistered(): number;
-  /** Checks for scope violations (captive dependencies). Throws {@link ScopeViolationError} on the first violation found. */
+  /**
+   * Checks for scope violations (captive dependencies). Throws {@link ScopeViolationError} on the first violation found.
+   */
   validate(): void;
-  /** Returns a debug snapshot of all registered bindings and their activation state. */
+  /**
+   * Returns a debug snapshot of all registered bindings and their activation state.
+   */
   inspect(): ContainerSnapshot;
-  /** Renders the dependency graph as a Graphviz DOT string (default) or a typed JSON object. */
-  generateDependencyGraph(options?: DotGraphOptions & {
-    format?: "dot";
-  }): string;
-  generateDependencyGraph(options: DotGraphOptions & {
-    format: "json";
-  }): ContainerGraphJson;
-  /** Creates a child container that inherits bindings from this container without polluting its registry. */
+  /**
+   * Returns the canonical dependency graph as typed JSON (`nodes` + `edges`).
+   */
+  generateDependencyGraph(options?: GraphOptions): ContainerGraphJson;
+  /**
+   * Creates a child container that inherits bindings from this container without polluting its registry.
+   */
   createChild(): Container;
-  /** @throws Always — container disposal is async; use `await using` or `await container.dispose()`. */
+  /**
+   * @throws Always — container disposal is async; use `await using` or `await container.dispose()`.
+   */
   [Symbol.dispose](): never;
-  /** Returns the raw binding list for a token without triggering resolution. `undefined` means no binding. */
+  /**
+   * Returns the raw binding list for a token without triggering resolution. `undefined` means no binding.
+   */
   lookupBindings(token: RegistryKey): readonly Binding<unknown>[] | undefined;
-  /** Runs all `onDeactivation` hooks on active singletons and releases all caches. */
+  /**
+   * Runs all `onDeactivation` hooks on active singletons and releases all caches.
+   */
   dispose(): Promise<void>;
   [Symbol.asyncDispose](): Promise<void>;
 }
@@ -71,12 +115,18 @@ interface Container extends AsyncDisposable {
  * Factory functions for {@link Container} instances (interface + namespace merge).
  */
 declare namespace Container {
-  /** Creates an empty container with no bindings. */
+  /**
+   * Creates an empty container with no bindings.
+   */
   function create(): Container;
-  /** Creates a container and immediately loads the given sync modules. */
+  /**
+   * Creates a container and immediately loads the given sync modules.
+   */
   function fromModules(...modules: Module[]): Container;
-  /** Creates a container and awaits loading of sync and/or async modules. */
+  /**
+   * Creates a container and awaits loading of sync and/or async modules.
+   */
   function fromModulesAsync(...modules: (Module | AsyncModule)[]): Promise<Container>;
 }
 //#endregion
-export { type BindingIdentifier, Container, type ContainerGraphJson, type ContainerSnapshot, type ResolveOptions };
+export { Container };

package/dist/container.mjs

@@ -10,19 +10,53 @@ import { validateScopeRules } from "./scope-validation.mjs";
 import { ScopeManager } from "./scope.mjs";
 import { isDevelopmentOrTestEnvironment } from "./environment.mjs";
 //#region src/container.ts
+/**
+* Derives a {@link ResolveHint} from a binding's name or first tag.
+* Used by {@link DefaultContainer.initializeAsync} to re-resolve named/tagged singletons
+* through the standard resolution path.
+*/
 function resolveHintForBinding(binding) {
 	if (binding.bindingName !== void 0) return { name: binding.bindingName };
 	for (const [tagKey, tagValue] of binding.tags) return { tag: [tagKey, tagValue] };
 }
 /**
+* Module {@link ModuleBuilder.bind}: append when the binding is disambiguated **at first
+* registration** (`whenNamed` / `whenTagged` / `when` before `to*()`). Otherwise replace
+* all bindings for the token (last-wins). Chaining `.whenNamed()` after `.to*()` only updates
+* in place and does not enable multi-binding for subsequent module lines — use hint-before-`to*()`
+* in modules (same style as `container.bind(...).whenNamed("x").to*(...)` in the package README).
+*/
+function moduleBindingUsesMultiSlot(built) {
+	return built.bindingName !== void 0 || built.tags.size > 0 || built.constraint !== void 0;
+}
+/**
 * Default IoC container: registry + scoped caches + synchronous / asynchronous resolution.
 * @internal Implementation of {@link Container}; not part of the public package contract.
 */
 var DefaultContainer = class DefaultContainer {
+	/**
+	* Stack guard for detecting circular sync module imports during {@link ensureSyncModuleLoaded}.
+	*/
 	syncModuleStack = [];
+	/**
+	* Stack guard for detecting circular async module imports during {@link ensureAsyncModuleLoaded}.
+	*/
 	asyncModuleStack = [];
+	/**
+	* Tracks loaded modules → their binding IDs so {@link unload} / {@link unloadAsync} can
+	* remove exactly the bindings contributed by each module.
+	* Also serves as a deduplication set: a module present as a key is considered loaded.
+	*/
 	loadedModules = /* @__PURE__ */ new Map();
+	/**
+	* True after the first dev/test one-shot scope validation has run for the current registry state.
+	* Reset to `false` by {@link invalidateDevValidationState} on every registry mutation.
+	*/
 	devValidationRan = false;
+	/**
+	* Internal constructor for root/child instances.
+	* Use {@link Container.create}, {@link Container.fromModules}, or {@link createChild}.
+	*/
 	constructor(ownRegistry, ownScopeManager, parent, resolver, metadataReader) {
 		this.ownRegistry = ownRegistry;
 		this.ownScopeManager = ownScopeManager;
@@ -30,6 +64,10 @@ var DefaultContainer = class DefaultContainer {
 		this.resolver = resolver;
 		this.metadataReader = metadataReader;
 	}
+	/**
+	* Creates a root container with an empty registry and fresh singleton/scoped caches.
+	* Wires the circular container↔resolver reference via a mutable {@link ContainerRef} holder.
+	*/
 	static create() {
 		const ownRegistry = new BindingRegistry();
 		const ownScopeManager = ScopeManager.createRoot();
@@ -48,7 +86,9 @@ var DefaultContainer = class DefaultContainer {
 		return container;
 	}
 	/**
-	* Starts a fluent binding registered on this container when {@link BindingBuilder.build} runs.
+	* Starts a fluent {@link BindingBuilder} for the given token or constructor.
+	* The binding is registered into this container's registry immediately when a
+	* `to*()` strategy method is called on the returned builder.
 	*/
 	bind(token) {
 		return new BindingBuilder(token, void 0, {
@@ -62,6 +102,12 @@ var DefaultContainer = class DefaultContainer {
 			}
 		});
 	}
+	/**
+	* Fast registry presence check without instantiation.
+	*
+	* When `hint` is provided, this only verifies that at least one binding matches
+	* the name/tag discriminator; it does not evaluate runtime `when()` predicates.
+	*/
 	has(token, hint) {
 		const list = this.lookupBindings(token);
 		if (list === void 0 || list.length === 0) return false;
@@ -75,6 +121,12 @@ var DefaultContainer = class DefaultContainer {
 			return true;
 		});
 	}
+	/**
+	* Removes bindings by token or by binding id and synchronously releases cached instances.
+	*
+	* - `binding id` path removes one binding and its cache entry.
+	* - `token` path removes all owned bindings for that key at once.
+	*/
 	unbind(tokenOrId) {
 		this.invalidateDevValidationState();
 		if (typeof tokenOrId === "string") {
@@ -86,6 +138,9 @@ var DefaultContainer = class DefaultContainer {
 		if (owned !== void 0) for (const binding of owned) this.ownScopeManager.releaseBinding(binding);
 		this.ownRegistry.remove(tokenOrId);
 	}
+	/**
+	* Async counterpart of {@link unbind}; awaits deactivation hooks before registry removal.
+	*/
 	async unbindAsync(tokenOrId) {
 		this.invalidateDevValidationState();
 		if (typeof tokenOrId === "string") {
@@ -97,6 +152,11 @@ var DefaultContainer = class DefaultContainer {
 		if (owned !== void 0) for (const binding of owned) await this.ownScopeManager.releaseBindingAsync(binding);
 		this.ownRegistry.remove(tokenOrId);
 	}
+	/**
+	* Replaces all owned bindings for `token` and returns a fresh builder.
+	*
+	* Existing cached instances for the removed bindings are synchronously released first.
+	*/
 	rebind(token) {
 		this.invalidateDevValidationState();
 		const owned = this.ownRegistry.get(token);
@@ -162,12 +222,18 @@ var DefaultContainer = class DefaultContainer {
 			this.maybeRunDevValidationOnce();
 		}
 	}
-	/** Async variant of {@link resolve}; same dev/test validation and runtime scope enforcement. */
+	/**
+	* Async variant of {@link resolve}; same dev/test validation and runtime scope enforcement.
+	*/
 	resolveAsync(key, hint) {
 		return this.resolver.resolveAsyncRoot(key, hint).finally(() => {
 			this.maybeRunDevValidationOnce();
 		});
 	}
+	/**
+	* Optional root resolution: returns `undefined` when the requested key is absent (or filtered out
+	* without a name/tag hint), while preserving normal errors for nested required dependencies.
+	*/
 	resolveOptional(key, hint) {
 		try {
 			return this.resolver.resolveOptionalRoot(key, hint);
@@ -175,6 +241,10 @@ var DefaultContainer = class DefaultContainer {
 			this.maybeRunDevValidationOnce();
 		}
 	}
+	/**
+	* Synchronously resolves every matching binding for a key.
+	* Returns an empty array when no binding exists.
+	*/
 	resolveAll(key, hint) {
 		try {
 			return this.resolver.resolveAllRoot(key, hint);
@@ -205,9 +275,17 @@ var DefaultContainer = class DefaultContainer {
 			}
 		}
 	}
+	/**
+	* Marks the dev/test one-shot validation as stale so the next resolve or load triggers it again.
+	* Called on every registry mutation (bind, unbind, rebind, load, unload).
+	*/
 	invalidateDevValidationState() {
 		this.devValidationRan = false;
 	}
+	/**
+	* Runs scope validation at most once per registry epoch when `NODE_ENV` is not `"production"`.
+	* Guards against repeated validation on successive resolves without intervening mutations.
+	*/
 	maybeRunDevValidationOnce() {
 		if (!isDevelopmentOrTestEnvironment()) return;
 		if (this.devValidationRan) return;
@@ -231,11 +309,16 @@ var DefaultContainer = class DefaultContainer {
 	inspect() {
 		return this.createInspector().getSnapshot();
 	}
+	/**
+	* Delegates canonical dependency-graph generation to {@link ContainerInspector}.
+	*/
 	generateDependencyGraph(options) {
-		const inspector = this.createInspector();
-		if (options?.format === "json") return inspector.generateDependencyGraph(options);
-		return inspector.generateDotGraph(options);
+		return this.createInspector().generateDependencyGraph(options);
 	}
+	/**
+	* Registers every class collected by `@injectable({ autoRegister: true })`.
+	* Returns how many entries were processed.
+	*/
 	loadAutoRegistered() {
 		const entries = getAutoRegistered();
 		let count = 0;
@@ -257,6 +340,9 @@ var DefaultContainer = class DefaultContainer {
 	[Symbol.dispose]() {
 		throw new InternalError("Container disposal is async. Use `await using container = Container.create()` or call `await container.dispose()` instead of `using`.");
 	}
+	/**
+	* Constructs a {@link ContainerInspector} wired to this container's full hierarchy.
+	*/
 	createInspector() {
 		return new ContainerInspector({
 			collectAllRegistryKeys: () => this.collectAllRegistryKeysInHierarchy(),
@@ -265,11 +351,18 @@ var DefaultContainer = class DefaultContainer {
 			metadataReader: this.metadataReader
 		});
 	}
+	/**
+	* Collects the union of all registry keys from this container and every ancestor.
+	* Deduplicates by reference equality (tokens are objects).
+	*/
 	collectAllRegistryKeysInHierarchy() {
 		const keys = /* @__PURE__ */ new Set();
 		this.accumulateRegistryKeysFromHierarchy(keys, this);
 		return [...keys];
 	}
+	/**
+	* Recursive helper: walks the parent chain bottom-up, adding each level's registry keys.
+	*/
 	accumulateRegistryKeysFromHierarchy(keys, container) {
 		if (container === void 0) return;
 		for (const entry of container.ownRegistry.listEntries()) keys.add(entry.key);
@@ -296,22 +389,42 @@ var DefaultContainer = class DefaultContainer {
 		holder.current = child;
 		return child;
 	}
+	/**
+	* Lookup helper with parent fallback: own bindings take precedence over parent bindings.
+	*/
 	lookupBindings(token) {
 		const own = this.ownRegistry.get(token);
 		if (own !== void 0 && own.length > 0) return own;
 		return this.parent?.lookupBindings(token);
 	}
+	/**
+	* Disposes this container's scope manager and runs async deactivation hooks.
+	*/
 	async dispose() {
 		await this.ownScopeManager.disposeAsync();
 	}
+	/**
+	* Async-dispose protocol hook used by `await using`.
+	*/
 	[Symbol.asyncDispose]() {
 		return this.dispose();
 	}
+	/**
+	* Returns a `bind` function scoped to a module. Registrations are tracked in
+	* {@link loadedModules} for {@link unload}.
+	*
+	* - **Last-wins** (replaces every binding for that token): `bind(token).to*(...)` with no
+	*   `whenNamed` / `whenTagged` / `when` **before** the `to*()` call.
+	* - **Multi-binding** (append): call `whenNamed`, `whenTagged`, and/or `when` **before** `to*()`
+	*   so the disambiguator exists at registration time — supports `resolveAll` and per-binding
+	*   hints in {@link Container.initializeAsync}.
+	*/
 	bindForModule(owner) {
 		return (token) => new BindingBuilder(token, owner.name, {
 			register: (built) => {
 				this.invalidateDevValidationState();
-				this.ownRegistry.replaceKeyLastWins(token, built, (removed) => {
+				if (moduleBindingUsesMultiSlot(built)) this.ownRegistry.add(token, built);
+				else this.ownRegistry.replaceKeyLastWins(token, built, (removed) => {
 					this.ownScopeManager.releaseBinding(removed);
 				});
 				this.recordBindingForModule(owner, built.id);
@@ -322,6 +435,9 @@ var DefaultContainer = class DefaultContainer {
 			}
 		});
 	}
+	/**
+	* Appends a binding ID to the tracking list for `owner` so {@link unload} can remove it later.
+	*/
 	recordBindingForModule(owner, id) {
 		const list = this.loadedModules.get(owner);
 		if (list === void 0) {
@@ -330,6 +446,10 @@ var DefaultContainer = class DefaultContainer {
 		}
 		list.push(id);
 	}
+	/**
+	* Creates the {@link ModuleBuilder} passed to a sync module's setup callback.
+	* The `import` method throws {@link InternalError} if an {@link AsyncModule} is passed.
+	*/
 	createSyncModuleBuilder(module) {
 		return {
 			import: (...deps) => {
@@ -341,6 +461,11 @@ var DefaultContainer = class DefaultContainer {
 			bind: this.bindForModule(module)
 		};
 	}
+	/**
+	* Creates the {@link AsyncModuleBuilder} and a companion `awaitImports` thunk.
+	* Async sub-imports are collected into `pendingImports` and flushed after the module's
+	* own setup returns — this avoids interleaving setup code with dependency loading.
+	*/
 	createAsyncModuleBuilder(module) {
 		const pendingImports = [];
 		return {
@@ -357,6 +482,11 @@ var DefaultContainer = class DefaultContainer {
 			}
 		};
 	}
+	/**
+	* Loads a sync module if not already loaded. Detects circular module imports via
+	* {@link syncModuleStack} and throws {@link CircularDependencyError} with the full cycle path.
+	* The module is marked as loaded *before* its setup runs so that re-entrant imports are deduped.
+	*/
 	ensureSyncModuleLoaded(module) {
 		if (this.loadedModules.has(module)) return;
 		if (this.syncModuleStack.includes(module)) throw new CircularDependencyError([...this.syncModuleStack.map((stackedModule) => stackedModule.name), module.name]);
@@ -369,6 +499,10 @@ var DefaultContainer = class DefaultContainer {
 			this.syncModuleStack.pop();
 		}
 	}
+	/**
+	* Async counterpart of {@link ensureSyncModuleLoaded}: loads the module's async setup,
+	* then flushes any pending async sub-imports collected during setup.
+	*/
 	async ensureAsyncModuleLoaded(asyncModule) {
 		if (this.loadedModules.has(asyncModule)) return;
 		if (this.asyncModuleStack.includes(asyncModule)) throw new CircularDependencyError([...this.asyncModuleStack.map((stackedAsyncModule) => stackedAsyncModule.name), asyncModule.name]);

package/dist/decorators/inject.d.mts

@@ -3,22 +3,53 @@ import { Constructor, ResolveHint } from "../binding.mjs";
 import { InjectionDescriptor } from "../metadata/metadata-types.mjs";
 
 //#region src/decorators/inject.d.ts
-/** Options forwarded to the container when resolving an injected dependency. */
+/**
+ * Name/tag hint forwarded to the container when resolving an injected dependency.
+ * Alias for {@link ResolveHint}; used as the second parameter of {@link inject} and {@link optional}.
+ */
 type InjectOptions = ResolveHint;
 /**
- * Creates an {@link InjectionDescriptor} for use in an `@injectable(deps)` array, or as an
- * `accessor` field decorator for post-construction property injection.
+ * Dual-purpose injection helper:
+ *
+ * **1. As a deps-array entry** — returns an {@link InjectionDescriptor} carrying the token,
+ * optional flag (`false`), and any name/tag hint. Used inside `@injectable([...deps])`.
+ *
+ * ```ts
+ * @injectable([inject(Logger, { name: 'file' })])
+ * class UserService { constructor(log: Logger) {} }
+ * ```
+ *
+ * **2. As a Stage 3 accessor decorator** — writes accessor-injection metadata into
+ * `Symbol.metadata` and returns a no-op sentinel. The container performs the actual
+ * injection after construction.
+ *
+ * ```ts
+ * @inject(Logger) accessor logger!: LoggerService;
+ * ```
  *
- * As a deps-array entry: `@injectable([inject(Logger, { name: 'file' })])`
- * As an accessor decorator: `@inject(Logger) accessor logger!: LoggerService`
+ * @param token - The injection key (token or constructor) to resolve.
+ * @param optionsOrContext - Either an {@link InjectOptions} hint or the TC39
+ *   `ClassAccessorDecoratorContext` automatically supplied by the runtime.
  */
 declare function inject<Value>(token: Token<Value> | Constructor<Value>, optionsOrContext?: InjectOptions | ClassAccessorDecoratorContext): InjectionDescriptor<Value>;
 /**
- * Same as {@link inject} but marks the dependency as optional — resolves to `undefined` instead
- * of throwing {@link TokenNotBoundError} when no binding exists.
+ * Same as {@link inject} but marks the dependency as optional (`InjectionDescriptor.optional = true`).
+ * During resolution, an unbound token resolves to `undefined` instead of throwing
+ * {@link TokenNotBoundError}. Only usable as a deps-array entry (not as an accessor decorator).
  */
 declare function optional<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value>;
-/** Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}. */
+/**
+ * Deps-array helper for `@injectable()`: injects **all** bindings registered for `token`
+ * (same semantics as {@link Container.resolveAll} / {@link ResolutionContext.resolveAll}).
+ * Use for multi-binding — constructor parameter type should be `T[]` (or a readonly array).
+ *
+ * Optional {@link InjectOptions.name} / `tag` narrow which bindings are collected (unusual; most
+ * callers omit options and register disambiguators on each binding instead).
+ */
+declare function injectAll<Value>(token: Token<Value> | Constructor<Value>, options?: InjectOptions): InjectionDescriptor<Value>;
+/**
+ * Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}.
+ */
 declare function isInjectionDescriptor(value: unknown): value is InjectionDescriptor;
 //#endregion
-export { InjectOptions, inject, isInjectionDescriptor, optional };
+export { InjectOptions, inject, injectAll, isInjectionDescriptor, optional };