@codefast/di 0.3.13 → 0.3.14-canary.0

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

@@ -5,6 +5,9 @@ import { ContainerGraphJson, ContainerSnapshot, DotGraphOptions } from "./inspec
 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,102 @@ 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. */
+  /**
+   * 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. */
+  /**
+   * 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,11 +120,17 @@ 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

package/dist/container.mjs

@@ -10,18 +10,48 @@ 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;
 	constructor(ownRegistry, ownScopeManager, parent, resolver, metadataReader) {
 		this.ownRegistry = ownRegistry;
@@ -30,6 +60,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 +82,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, {
@@ -162,7 +198,9 @@ 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();
@@ -205,9 +243,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;
@@ -257,6 +303,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 +314,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);
@@ -307,11 +363,22 @@ var DefaultContainer = class DefaultContainer {
 	[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 +389,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 +400,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 +415,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 +436,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 +453,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 };

package/dist/decorators/inject.mjs

@@ -1,7 +1,9 @@
 import { InternalError } from "../errors.mjs";
 import { CODEFAST_DI_ACCESSOR_INJECTIONS } from "../metadata/metadata-keys.mjs";
 //#region src/decorators/inject.ts
-/** Validates and normalises the `tag` option from {@link InjectOptions}; throws {@link InternalError} on bad input. */
+/**
+* Validates and normalises the `tag` option from {@link InjectOptions}; throws {@link InternalError} on bad input.
+*/
 function normalizeTag(tag) {
 	if (tag === void 0) return;
 	if (!Array.isArray(tag) || tag.length !== 2) throw new InternalError(`@inject tag must be a tuple [tagKey, value] with length 2; received ${String(tag)}`);
@@ -9,7 +11,9 @@ function normalizeTag(tag) {
 	if (typeof tagName !== "string") throw new InternalError(`@inject tag key must be a string; received ${typeof tagName}`);
 	return [tagName, value];
 }
-/** Builds an {@link InjectionDescriptor} from a token, optional flag, and raw inject options. */
+/**
+* Builds an {@link InjectionDescriptor} from a token, optional flag, and raw inject options.
+*/
 function toDescriptor(token, optional, options) {
 	const normalizedTag = normalizeTag(options?.tag);
 	if (options?.name !== void 0) return {
@@ -27,16 +31,34 @@ function toDescriptor(token, optional, options) {
 		optional
 	};
 }
-/** Type guard — returns `true` when `value` is a TC39 `ClassAccessorDecoratorContext` (accessor field). */
+/**
+* Type guard — returns `true` when `value` is a TC39 `ClassAccessorDecoratorContext` (accessor field).
+*/
 function isAccessorDecoratorContext(value) {
 	return typeof value === "object" && value !== null && "kind" in value && value.kind === "accessor";
 }
 /**
-* 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.
 *
-* As a deps-array entry: `@injectable([inject(Logger, { name: 'file' })])`
-* As an accessor decorator: `@inject(Logger) accessor logger!: LoggerService`
+* ```ts
+* @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.
 */
 function inject(token, optionsOrContext) {
 	if (isAccessorDecoratorContext(optionsOrContext)) {
@@ -54,16 +76,33 @@ function inject(token, optionsOrContext) {
 	return toDescriptor(token, false, optionsOrContext);
 }
 /**
-* 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).
 */
 function optional(token, options) {
 	return toDescriptor(token, true, options);
 }
-/** 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).
+*/
+function injectAll(token, options) {
+	return {
+		...toDescriptor(token, false, options),
+		all: true
+	};
+}
+/**
+* Type-guard — returns `true` when `value` is an {@link InjectionDescriptor}.
+*/
 function isInjectionDescriptor(value) {
 	if (typeof value !== "object" || value === null) return false;
 	return "token" in value && "optional" in value;
 }
 //#endregion
-export { inject, isInjectionDescriptor, optional };
+export { inject, injectAll, isInjectionDescriptor, optional };

package/dist/decorators/injectable.d.mts

@@ -6,7 +6,8 @@ import { InjectionDescriptor } from "../metadata/metadata-types.mjs";
 /**
  * A single entry in the `deps` array passed to `@injectable()`.
  * Can be a plain token/constructor (resolved with no hint) or an {@link InjectionDescriptor}
- * produced by {@link inject} / {@link optional} when name, tag, or optional semantics are needed.
+ * produced by `inject` / `optional` / `injectAll` when name, tag, optional, or resolve-all
+ * semantics are needed.
  */
 type InjectableDependency = Token<unknown> | Constructor<unknown> | InjectionDescriptor<unknown>;
 /**

package/dist/decorators/injectable.mjs

@@ -2,6 +2,11 @@ import { InternalError } from "../errors.mjs";
 import { CODEFAST_DI_CONSTRUCTOR_METADATA } from "../metadata/metadata-keys.mjs";
 import { isInjectionDescriptor } from "./inject.mjs";
 //#region src/decorators/injectable.ts
+/**
+* Global mutable registry of classes decorated with `@injectable({ autoRegister: true })`.
+* Populated at class-definition time (via `context.addInitializer`), drained by
+* {@link Container.loadAutoRegistered}. Entries accumulate for the lifetime of the process.
+*/
 const AUTO_REGISTER_REGISTRY = [];
 /**
 * Returns all classes decorated with `@injectable({ autoRegister: true })`.
@@ -10,14 +15,21 @@ const AUTO_REGISTER_REGISTRY = [];
 function getAutoRegistered() {
 	return AUTO_REGISTER_REGISTRY;
 }
-/** Converts a single `@injectable` deps-array entry into a {@link ParamMetadata} record. */
+/**
+* Normalises a single `@injectable` deps-array entry into the uniform {@link ParamMetadata}
+* shape used by the resolver's constructor-instantiation path.
+*
+* - {@link InjectionDescriptor} entries carry `optional`, `name`, and `tag` fields.
+* - Plain token / constructor entries are wrapped with `optional: false` and no hint.
+*/
 function toParamMetadata(dependency, index) {
 	if (isInjectionDescriptor(dependency)) return {
 		index,
 		token: dependency.token,
 		optional: dependency.optional,
 		name: dependency.name,
-		tag: dependency.tag
+		tag: dependency.tag,
+		all: dependency.all === true ? true : void 0
 	};
 	return {
 		index,

package/dist/decorators/lifecycle-decorators.d.mts

@@ -1,12 +1,24 @@
 //#region src/decorators/lifecycle-decorators.d.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.
  */
 declare function postConstruct(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
 /**
- * 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.
  */
 declare function preDestroy(): (target: () => unknown, context: ClassMethodDecoratorContext) => void;
 //#endregion