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

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, DiError, InternalError, MissingMetadataError, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError } from "./errors.mjs";
-import { inject, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
+import { inject, injectAll, isInjectionDescriptor, optional } from "./decorators/inject.mjs";
 import { getAutoRegistered, injectable } from "./decorators/injectable.mjs";
 import { AsyncModule, Module } from "./module.mjs";
 import { Container } from "./container.mjs";
 import { token } from "./token.mjs";
 import { postConstruct, preDestroy } from "./decorators/lifecycle-decorators.mjs";
-export { AsyncModule, AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, Container, DiError, InternalError, MissingMetadataError, Module, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError, getAutoRegistered, inject, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };
+export { AsyncModule, AsyncModuleLoadError, AsyncResolutionError, CircularDependencyError, Container, DiError, InternalError, MissingMetadataError, Module, NoMatchingBindingError, ScopeViolationError, TokenNotBoundError, getAutoRegistered, inject, injectAll, injectable, isInjectionDescriptor, optional, postConstruct, preDestroy, token };

package/dist/inspector.d.mts

@@ -4,35 +4,50 @@ import { MetadataReader } from "./metadata/metadata-types.mjs";
 import { collectStaticDependencyEdges } from "./dependency-graph.mjs";
 
 //#region src/inspector.d.ts
-/** Whether a singleton/scoped binding's instance is currently held in the scope cache. */
+/**
+ * Whether a singleton/scoped binding's instance is currently held in the scope cache.
+ */
 type BindingActivationStatus = "cached" | "not-cached" | "transient";
-/** Per-binding row inside a {@link ContainerSnapshot}. */
+/**
+ * Per-binding row inside a {@link ContainerSnapshot}.
+ */
 type ContainerBindingSnapshot = {
   readonly registryKeyLabel: string;
   readonly bindingId: BindingIdentifier;
   readonly kind: Binding<unknown>["kind"];
   readonly scope: BindingScope;
-  readonly activationStatus: BindingActivationStatus; /** True when {@link BindingBuilder.when} was used (runtime predicate; static graph may still show edges). */
+  readonly activationStatus: BindingActivationStatus;
+  /**
+   * True when {@link BindingBuilder.when} was used (runtime predicate; static graph may still show edges).
+   */
   readonly hasConditionalConstraint: boolean;
   readonly moduleId?: string;
 };
-/** Full debug snapshot returned by {@link Container.inspect}. */
+/**
+ * Full debug snapshot returned by {@link Container.inspect}.
+ */
 type ContainerSnapshot = {
   readonly bindings: readonly ContainerBindingSnapshot[];
 };
-/** Structured dependency graph returned by {@link Container.generateDependencyGraph} with `format: "json"`. */
+/**
+ * Structured dependency graph returned by {@link Container.generateDependencyGraph} with `format: "json"`.
+ */
 type ContainerGraphJson = {
   nodes: ContainerBindingSnapshot[];
   edges: ReturnType<typeof collectStaticDependencyEdges>[number][];
 };
-/** Read-only view of the container internals exposed to {@link ContainerInspector}. */
+/**
+ * Read-only view of the container internals exposed to {@link ContainerInspector}.
+ */
 type ContainerInspectorContext = {
   collectAllRegistryKeys(): readonly RegistryKey[];
   lookupBindings(key: RegistryKey): readonly Binding<unknown>[] | undefined;
   isBindingCached(binding: Binding<unknown>): boolean;
   metadataReader: MetadataReader | undefined;
 };
-/** Options for {@link Container.generateDependencyGraph}. */
+/**
+ * Options for {@link Container.generateDependencyGraph}.
+ */
 type DotGraphOptions = {
   /**
    * When true, omit registry keys whose label starts with `CODEFAST_DI_` (framework-style tokens)
@@ -41,17 +56,18 @@ type DotGraphOptions = {
   readonly hideInternals?: boolean;
 };
 /**
- * Read-only introspection and Graphviz DOT export for a container graph.
- */
-/**
- * Reads the registry and scope-cache state to produce debug snapshots and dependency graphs.
- * Instantiated internally by the container; advanced consumers can construct it directly via
- * the `@codefast/di/inspector` subpath export.
+ * Reads the container's registry and scope-cache state to produce debug snapshots
+ * and dependency-graph output (Graphviz DOT / typed JSON).
+ *
+ * Constructed internally by the container; advanced consumers can also construct it
+ * directly via the `@codefast/di/inspector` subpath export.
  */
 declare class ContainerInspector {
   private readonly ctx;
   constructor(ctx: ContainerInspectorContext);
-  /** Collects all registered bindings into a flat, serialisable snapshot. */
+  /**
+   * Collects all registered bindings into a flat, serialisable snapshot.
+   */
   getSnapshot(): ContainerSnapshot;
   /**
    * Produces a Graphviz `digraph` string with HTML-label nodes and styled edges.
@@ -59,12 +75,20 @@ declare class ContainerInspector {
    * Pass `hideInternals: true` to suppress `CODEFAST_DI_`-prefixed tokens.
    */
   generateDotGraph(options?: DotGraphOptions): string;
+  /**
+   * Overloaded entry point: returns DOT format by default, or a typed {@link ContainerGraphJson}
+   * when `format: "json"` is specified.
+   */
   generateDependencyGraph(options?: DotGraphOptions & {
     format?: "dot";
   }): string;
   generateDependencyGraph(options: DotGraphOptions & {
     format: "json";
   }): ContainerGraphJson;
+  /**
+   * Builds the typed JSON graph (nodes + edges) used by the `"json"` format path.
+   * Applies the same `hideInternals` / deduplication logic as {@link generateDotGraph}.
+   */
   generateDependencyGraphJsonTyped(options?: DotGraphOptions): ContainerGraphJson;
   /**
    * Produces a JSON graph representation with `nodes` and `edges`.

package/dist/inspector.mjs

@@ -1,20 +1,28 @@
 import { registryKeyLabel } from "./binding-select.mjs";
 import { collectStaticDependencyEdges } from "./dependency-graph.mjs";
 //#region src/inspector.ts
-/** Maps a binding's scope and cache state to a {@link BindingActivationStatus} label. */
+/**
+* Maps a binding's scope and cache state to a {@link BindingActivationStatus} label.
+*/
 function activationStatusFor(binding, isCached) {
 	if (binding.scope === "transient") return "transient";
 	return isCached(binding) ? "cached" : "not-cached";
 }
-/** Escapes a string for use as a DOT `label="..."` attribute value. */
+/**
+* Escapes a string for use as a DOT `label="..."` attribute value.
+*/
 function dotEscapeLabel(text) {
 	return text.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"").replaceAll("\n", "\\n");
 }
-/** Escapes a string for safe embedding inside a DOT HTML-label (`<...>`) table cell. */
+/**
+* Escapes a string for safe embedding inside a DOT HTML-label (`<...>`) table cell.
+*/
 function dotEscapeHtml(text) {
 	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
 }
-/** Returns the Graphviz node shape name for a given binding kind. */
+/**
+* Returns the Graphviz node shape name for a given binding kind.
+*/
 function nodeShapeForKind(kind) {
 	switch (kind) {
 		case "constant": return "ellipse";
@@ -26,7 +34,9 @@ function nodeShapeForKind(kind) {
 		default: return kind;
 	}
 }
-/** Returns DOT fill-color and style attributes that visually distinguish binding scopes. */
+/**
+* Returns DOT fill-color and style attributes that visually distinguish binding scopes.
+*/
 function scopeVisualAttributes(scope) {
 	switch (scope) {
 		case "singleton": return "style=\"filled\", fillcolor=\"#FFD700\", penwidth=2";
@@ -35,31 +45,38 @@ function scopeVisualAttributes(scope) {
 		default: return scope;
 	}
 }
-/** Strips non-alphanumeric characters from a module name to produce a valid DOT subgraph identifier. */
+/**
+* Strips non-alphanumeric characters from a module name to produce a valid DOT subgraph identifier.
+*/
 function sanitizeClusterId(moduleName) {
 	return moduleName.replace(/[^0-9a-zA-Z_]/g, "_");
 }
-/** Returns `true` when the label string belongs to a framework-internal registry key. */
+/**
+* Returns `true` when the label string belongs to a framework-internal registry key.
+*/
 function registryKeyLabelIsInternal(label) {
 	return label.startsWith("CODEFAST_DI_");
 }
-/** Returns `true` when the registry key resolves to an internal framework label. */
+/**
+* Returns `true` when the registry key resolves to an internal framework label.
+*/
 function isInternalRegistryKey(key) {
 	return registryKeyLabelIsInternal(registryKeyLabel(key));
 }
 /**
-* Read-only introspection and Graphviz DOT export for a container graph.
-*/
-/**
-* Reads the registry and scope-cache state to produce debug snapshots and dependency graphs.
-* Instantiated internally by the container; advanced consumers can construct it directly via
-* the `@codefast/di/inspector` subpath export.
+* Reads the container's registry and scope-cache state to produce debug snapshots
+* and dependency-graph output (Graphviz DOT / typed JSON).
+*
+* Constructed internally by the container; advanced consumers can also construct it
+* directly via the `@codefast/di/inspector` subpath export.
 */
 var ContainerInspector = class {
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
-	/** Collects all registered bindings into a flat, serialisable snapshot. */
+	/**
+	* Collects all registered bindings into a flat, serialisable snapshot.
+	*/
 	getSnapshot() {
 		const bindings = [];
 		const seen = /* @__PURE__ */ new Set();
@@ -182,6 +199,10 @@ var ContainerInspector = class {
 		if (options?.format === "json") return this.generateDependencyGraphJsonTyped(options);
 		return this.generateDotGraph(options);
 	}
+	/**
+	* Builds the typed JSON graph (nodes + edges) used by the `"json"` format path.
+	* Applies the same `hideInternals` / deduplication logic as {@link generateDotGraph}.
+	*/
 	generateDependencyGraphJsonTyped(options) {
 		const hideInternals = options?.hideInternals === true;
 		const snapshot = this.getSnapshot();

package/dist/lifecycle.d.mts

@@ -3,15 +3,30 @@ import { LifecycleMetadata } from "./metadata/metadata-types.mjs";
 
 //#region src/lifecycle.d.ts
 /**
- * Runs `onActivation` synchronously; rejects async activations on sync resolution paths.
+ * Duck-typed Promise check: returns `true` when `value` has a `then` method.
+ * Used throughout the lifecycle layer to guard against async return values on sync resolution paths.
+ */
+declare function isPromiseLike(value: unknown): value is Promise<unknown>;
+/**
+ * Runs `onActivation` synchronously on a newly constructed instance.
+ * If the handler returns a Promise during synchronous resolution, throws
+ * {@link AsyncResolutionError} — callers must use `resolveAsync` for async activation handlers.
+ *
+ * Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** → cache.
  */
 declare function runActivation(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, pathLabels: readonly string[]): unknown;
 /**
- * Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+ * Reads lifecycle metadata ({@link LifecycleMetadata}) directly from a constructor's
+ * `Symbol.metadata` object. Bypasses the {@link MetadataReader} abstraction —
+ * used by the scope manager during deactivation when the reader is not available.
  */
 declare function readLifecycleMetadataFromCtor(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 /**
- * Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+ * Runs the `@postConstruct()` method synchronously if present.
+ * Throws {@link AsyncResolutionError} if the method returns a Promise — async lifecycle
+ * methods require `resolveAsync`.
+ *
+ * Lifecycle ordering: `construct` → **`@postConstruct`** → `onActivation` → cache.
  */
 declare function runPostConstruct(implementationClass: Constructor<unknown>, instance: unknown, pathLabels?: string[]): void;
 /**
@@ -19,16 +34,23 @@ declare function runPostConstruct(implementationClass: Constructor<unknown>, ins
  */
 declare function runPostConstructAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
 /**
- * Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+ * Runs the `@preDestroy()` method synchronously if present.
+ * Throws if the method returns a Promise — use `disposeAsync()` / `unloadAsync()` for async teardown.
+ *
+ * Lifecycle ordering: `onDeactivation` → **`@preDestroy`**.
  */
 declare function runPreDestroy(implementationClass: Constructor<unknown>, instance: unknown): void;
 /**
  * Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+ *
+ * Lifecycle ordering: `onDeactivation` → **`@preDestroy`** (async variant).
  */
 declare function runPreDestroyAsync(implementationClass: Constructor<unknown>, instance: unknown): Promise<void>;
 /**
- * Runs `onActivation`, awaiting promises returned by the handler.
+ * Runs `onActivation`, awaiting if the handler returns a Promise.
+ *
+ * Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** (async variant) → cache.
  */
 declare function runActivationAsync(binding: Binding<unknown>, instance: unknown, ctx: ResolutionContext, _pathLabels: readonly string[]): Promise<unknown>;
 //#endregion
-export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };
+export { isPromiseLike, readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

package/dist/lifecycle.mjs

@@ -1,11 +1,19 @@
 import { AsyncResolutionError } from "./errors.mjs";
 import { CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata/metadata-keys.mjs";
 //#region src/lifecycle.ts
+/**
+* Duck-typed Promise check: returns `true` when `value` has a `then` method.
+* Used throughout the lifecycle layer to guard against async return values on sync resolution paths.
+*/
 function isPromiseLike(value) {
 	return typeof value === "object" && value !== null && "then" in value && typeof value.then === "function";
 }
 /**
-* Runs `onActivation` synchronously; rejects async activations on sync resolution paths.
+* Runs `onActivation` synchronously on a newly constructed instance.
+* If the handler returns a Promise during synchronous resolution, throws
+* {@link AsyncResolutionError} — callers must use `resolveAsync` for async activation handlers.
+*
+* Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** → cache.
 */
 function runActivation(binding, instance, ctx, pathLabels) {
 	const handler = binding.onActivation;
@@ -16,7 +24,9 @@ function runActivation(binding, instance, ctx, pathLabels) {
 	return activationResult;
 }
 /**
-* Reads lifecycle metadata directly from a constructor's Symbol.metadata.
+* Reads lifecycle metadata ({@link LifecycleMetadata}) directly from a constructor's
+* `Symbol.metadata` object. Bypasses the {@link MetadataReader} abstraction —
+* used by the scope manager during deactivation when the reader is not available.
 */
 function readLifecycleMetadataFromCtor(implementationClass) {
 	const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
@@ -25,7 +35,11 @@ function readLifecycleMetadataFromCtor(implementationClass) {
 	return typeof raw === "object" && raw !== null ? raw : void 0;
 }
 /**
-* Runs the `@postConstruct()` method synchronously if present. Throws if it returns a Promise.
+* Runs the `@postConstruct()` method synchronously if present.
+* Throws {@link AsyncResolutionError} if the method returns a Promise — async lifecycle
+* methods require `resolveAsync`.
+*
+* Lifecycle ordering: `construct` → **`@postConstruct`** → `onActivation` → cache.
 */
 function runPostConstruct(implementationClass, instance, pathLabels) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -33,8 +47,7 @@ function runPostConstruct(implementationClass, instance, pathLabels) {
 	const methodName = meta.postConstruct;
 	const lifecycleMethod = instance[methodName];
 	if (typeof lifecycleMethod !== "function") return;
-	const postConstructResult = lifecycleMethod.call(instance);
-	if (typeof postConstructResult === "object" && postConstructResult !== null && "then" in postConstructResult && typeof postConstructResult.then === "function") {
+	if (isPromiseLike(lifecycleMethod.call(instance))) {
 		const labels = pathLabels ?? [];
 		throw new AsyncResolutionError(labels[labels.length - 1] ?? "(unknown)", labels, `@postConstruct() "${methodName}" returned a Promise during synchronous resolution`);
 	}
@@ -50,7 +63,10 @@ async function runPostConstructAsync(implementationClass, instance) {
 	await lifecycleMethod.call(instance);
 }
 /**
-* Runs the `@preDestroy()` method synchronously if present. Throws if it returns a Promise.
+* Runs the `@preDestroy()` method synchronously if present.
+* Throws if the method returns a Promise — use `disposeAsync()` / `unloadAsync()` for async teardown.
+*
+* Lifecycle ordering: `onDeactivation` → **`@preDestroy`**.
 */
 function runPreDestroy(implementationClass, instance) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -58,11 +74,12 @@ function runPreDestroy(implementationClass, instance) {
 	const methodName = meta.preDestroy;
 	const lifecycleMethod = instance[methodName];
 	if (typeof lifecycleMethod !== "function") return;
-	const preDestroyResult = lifecycleMethod.call(instance);
-	if (typeof preDestroyResult === "object" && preDestroyResult !== null && "then" in preDestroyResult && typeof preDestroyResult.then === "function") throw new Error(`@preDestroy() "${methodName}" returned a Promise during synchronous disposal; use disposeAsync() / unloadAsync().`);
+	if (isPromiseLike(lifecycleMethod.call(instance))) throw new Error(`@preDestroy() "${methodName}" returned a Promise during synchronous disposal; use disposeAsync() / unloadAsync().`);
 }
 /**
 * Runs the `@preDestroy()` method, awaiting if it returns a Promise.
+*
+* Lifecycle ordering: `onDeactivation` → **`@preDestroy`** (async variant).
 */
 async function runPreDestroyAsync(implementationClass, instance) {
 	const meta = readLifecycleMetadataFromCtor(implementationClass);
@@ -72,7 +89,9 @@ async function runPreDestroyAsync(implementationClass, instance) {
 	await lifecycleMethod.call(instance);
 }
 /**
-* Runs `onActivation`, awaiting promises returned by the handler.
+* Runs `onActivation`, awaiting if the handler returns a Promise.
+*
+* Lifecycle ordering: `construct` → `@postConstruct` → **`onActivation`** (async variant) → cache.
 */
 async function runActivationAsync(binding, instance, ctx, _pathLabels) {
 	const handler = binding.onActivation;
@@ -80,4 +99,4 @@ async function runActivationAsync(binding, instance, ctx, _pathLabels) {
 	return await handler(ctx, instance);
 }
 //#endregion
-export { readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };
+export { isPromiseLike, readLifecycleMetadataFromCtor, runActivation, runActivationAsync, runPostConstruct, runPostConstructAsync, runPreDestroy, runPreDestroyAsync };

package/dist/metadata/metadata-keys.d.mts

@@ -1,16 +1,27 @@
 //#region src/metadata/metadata-keys.d.ts
 /**
- * Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+ * Well-known property key for constructor injection metadata on `Symbol.metadata`.
+ * Written by `@injectable()`, read by `SymbolMetadataReader.getConstructorMetadata()`.
+ * The `:v1` suffix is a schema version — bump only when the `ConstructorMetadata` shape changes.
  */
 declare const CODEFAST_DI_CONSTRUCTOR_METADATA = "codefast/di:constructor-metadata:v1";
-/** Well-known key for accessor field injection metadata written by `@inject` on `accessor` fields. */
+/**
+ * Well-known property key for accessor-field injection metadata on `Symbol.metadata`.
+ * Written by `@inject()` when used as an accessor decorator; read during post-construction
+ * property injection by the resolver.
+ */
 declare const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
-/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+/**
+ * Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`.
+ */
 declare const CODEFAST_DI_LIFECYCLE_METADATA = "codefast/di:lifecycle-metadata:v1";
 /**
- * Runtime symbol for the decorator metadata object (TC39 `Symbol.metadata`).
- * Node may expose this only via `Symbol.for("Symbol.metadata")` until the global
- * `Symbol.metadata` property is available.
+ * Returns the runtime symbol used to access TC39 decorator metadata on a class.
+ *
+ * Prefers the native `Symbol.metadata` when available (Stage 3 decorators); falls back to
+ * `Symbol.for("Symbol.metadata")` for Node/runtime versions that polyfill or partially
+ * implement the proposal. The fallback key is the de facto convention used by TypeScript
+ * and polyfill libraries.
  */
 declare function decoratorMetadataObjectSymbol(): symbol;
 //#endregion

package/dist/metadata/metadata-keys.mjs

@@ -1,16 +1,27 @@
 //#region src/metadata/metadata-keys.ts
 /**
-* Well-known key for Codefast DI constructor metadata on `Symbol.metadata`.
+* Well-known property key for constructor injection metadata on `Symbol.metadata`.
+* Written by `@injectable()`, read by `SymbolMetadataReader.getConstructorMetadata()`.
+* The `:v1` suffix is a schema version — bump only when the `ConstructorMetadata` shape changes.
 */
 const CODEFAST_DI_CONSTRUCTOR_METADATA = "codefast/di:constructor-metadata:v1";
-/** Well-known key for accessor field injection metadata written by `@inject` on `accessor` fields. */
+/**
+* Well-known property key for accessor-field injection metadata on `Symbol.metadata`.
+* Written by `@inject()` when used as an accessor decorator; read during post-construction
+* property injection by the resolver.
+*/
 const CODEFAST_DI_ACCESSOR_INJECTIONS = "codefast/di:accessor-injections:v1";
-/** Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`. */
+/**
+* Well-known key for lifecycle method names written by `@postConstruct()` / `@preDestroy()`.
+*/
 const CODEFAST_DI_LIFECYCLE_METADATA = "codefast/di:lifecycle-metadata:v1";
 /**
-* Runtime symbol for the decorator metadata object (TC39 `Symbol.metadata`).
-* Node may expose this only via `Symbol.for("Symbol.metadata")` until the global
-* `Symbol.metadata` property is available.
+* Returns the runtime symbol used to access TC39 decorator metadata on a class.
+*
+* Prefers the native `Symbol.metadata` when available (Stage 3 decorators); falls back to
+* `Symbol.for("Symbol.metadata")` for Node/runtime versions that polyfill or partially
+* implement the proposal. The fallback key is the de facto convention used by TypeScript
+* and polyfill libraries.
 */
 function decoratorMetadataObjectSymbol() {
 	return typeof Symbol.metadata === "symbol" ? Symbol.metadata : Symbol.for("Symbol.metadata");

package/dist/metadata/metadata-types.d.mts

@@ -2,7 +2,9 @@ import { Token } from "../token.mjs";
 import { Constructor } from "../binding.mjs";
 
 //#region src/metadata/metadata-types.d.ts
-/** Metadata written per `accessor` field decorated with `@inject`; collected into `Symbol.metadata`. */
+/**
+ * Metadata written per `accessor` field decorated with `@inject`; collected into `Symbol.metadata`.
+ */
 type AccessorInjectionMetadata = {
   readonly name: string;
   readonly token: Token<unknown> | Constructor<unknown>;
@@ -12,11 +14,12 @@ type AccessorInjectionMetadata = {
     readonly tag?: readonly [tag: string, value: unknown];
   };
 };
-/** Lifecycle method names written by `@postConstruct()` / `@preDestroy()` into `Symbol.metadata`. */
+/**
+ * Lifecycle method names written by `@postConstruct()` / `@preDestroy()` into `Symbol.metadata`.
+ */
 type LifecycleMetadata = {
   readonly postConstruct?: string;
   readonly preDestroy?: string;
-  readonly accessorInjections?: readonly AccessorInjectionMetadata[];
 };
 /**
  * Per-parameter injection description collected by `@injectable()`.
@@ -27,6 +30,11 @@ type ParamMetadata = {
   readonly optional: boolean;
   readonly name?: string;
   readonly tag?: readonly [tag: string, value: unknown];
+  /**
+   * When true, the parameter receives every binding for `token` as an array (same semantics as
+   * `Container.resolveAll` / `ResolutionContext.resolveAll`), using `name` / `tag` as a filter when set.
+   */
+  readonly all?: boolean;
 };
 /**
  * Resolved form of an `inject()` / `optional()` call: token + optional flag + optional resolve hint.
@@ -36,7 +44,8 @@ type InjectionDescriptor<Value = unknown> = {
   readonly token: Token<Value> | Constructor<Value>;
   readonly optional: boolean;
   readonly name?: string;
-  readonly tag?: readonly [tag: string, value: unknown];
+  readonly tag?: readonly [tag: string, value: unknown]; /** When true, resolve every binding for {@link InjectionDescriptor.token} into an array. */
+  readonly all?: boolean;
 };
 /**
  * Constructor injection shape stored on the class `Symbol.metadata` object.
@@ -45,10 +54,25 @@ type ConstructorMetadata = {
   readonly params: readonly ParamMetadata[];
 };
 /**
- * Abstraction for reading DI metadata (section 6.4) without tying callers to `Symbol.metadata`.
+ * Abstraction for reading DI metadata without tying callers to `Symbol.metadata` directly.
+ * The {@link DependencyResolver} uses this to instantiate `class` bindings and read lifecycle hooks.
+ *
+ * The default implementation is {@link SymbolMetadataReader}; consumers can supply a custom
+ * reader (e.g. backed by a static config object) via `ResolverDependencies.metadataReader`.
  */
 type MetadataReader = {
+  /**
+   * Returns constructor parameter injection metadata for `implementationClass`, or `undefined`
+   * if the class has no own `@injectable()` metadata. When a {@link MetadataReader} is
+   * configured on the container, `undefined` here combined with `arity > 0` on the class
+   * causes {@link MissingMetadataError} during resolution; when no reader is configured, the
+   * resolver instantiates with zero arguments instead (see `DependencyResolver` class binding path).
+   */
   getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
+  /**
+   * Returns lifecycle method names (`@postConstruct` / `@preDestroy`), or `undefined` if none.
+   * Optional: when absent the resolver skips lifecycle hooks entirely.
+   */
   getLifecycleMetadata?(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 };
 //#endregion

package/dist/metadata/param-registry.mjs

@@ -1,4 +1,10 @@
 //#region src/metadata/param-registry.ts
+/**
+* WeakMap keyed by constructor → pending parameter metadata.
+* Entries are populated by legacy parameter decorators that fire *before* the
+* `@injectable()` class decorator runs, and consumed (via {@link takePendingMap})
+* by the class decorator to merge into the final {@link ConstructorMetadata}.
+*/
 const pendingByConstructor = /* @__PURE__ */ new WeakMap();
 /**
 * Returns the pending `ParamMetadata` map for `implementationClass`, creating it on first access.

package/dist/metadata/symbol-metadata-reader.d.mts

@@ -3,12 +3,29 @@ import { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "./metada
 
 //#region src/metadata/symbol-metadata-reader.d.ts
 /**
- * Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+ * Default {@link MetadataReader} implementation backed by TC39 `Symbol.metadata`.
+ *
+ * Constructor metadata (`@injectable()`) is read with `Object.hasOwn` to prevent
+ * a subclass from silently inheriting a parent's dependency list — each class must
+ * declare its own `@injectable()` decorator or be constructed with zero arguments.
+ *
+ * Lifecycle metadata (`@postConstruct` / `@preDestroy`) *is* inherited through the
+ * prototype chain, matching the intent that a parent's lifecycle hook applies to children.
  */
 declare class SymbolMetadataReader implements MetadataReader {
-  /** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+  /**
+   * Reads constructor param metadata written by `@injectable()`.
+   * Returns `undefined` if no own metadata is present on the class.
+   *
+   * @remarks
+   * Uses `Object.hasOwn` intentionally — TC39 `Symbol.metadata` prototype-chains from
+   * parent to child, so without this guard a subclass without `@injectable()` would
+   * silently inherit the parent's parameter list and inject the wrong dependency count.
+   */
   getConstructorMetadata(implementationClass: Constructor<unknown>): ConstructorMetadata | undefined;
-  /** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+  /**
+   * Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes.
+   */
   getLifecycleMetadata(implementationClass: Constructor<unknown>): LifecycleMetadata | undefined;
 }
 //#endregion

package/dist/metadata/symbol-metadata-reader.mjs

@@ -1,15 +1,32 @@
 import { CODEFAST_DI_CONSTRUCTOR_METADATA, CODEFAST_DI_LIFECYCLE_METADATA, decoratorMetadataObjectSymbol } from "./metadata-keys.mjs";
 //#region src/metadata/symbol-metadata-reader.ts
-/** Type guard — returns `true` when `value` has the shape of a {@link ConstructorMetadata} object. */
+/**
+* Type guard — returns `true` when `value` has the shape of a {@link ConstructorMetadata} object.
+*/
 function isConstructorMetadata(value) {
 	if (typeof value !== "object" || value === null || !("params" in value)) return false;
 	return Array.isArray(value.params);
 }
 /**
-* Reads {@link ConstructorMetadata} from the standard `Symbol.metadata` object.
+* Default {@link MetadataReader} implementation backed by TC39 `Symbol.metadata`.
+*
+* Constructor metadata (`@injectable()`) is read with `Object.hasOwn` to prevent
+* a subclass from silently inheriting a parent's dependency list — each class must
+* declare its own `@injectable()` decorator or be constructed with zero arguments.
+*
+* Lifecycle metadata (`@postConstruct` / `@preDestroy`) *is* inherited through the
+* prototype chain, matching the intent that a parent's lifecycle hook applies to children.
 */
 var SymbolMetadataReader = class {
-	/** Reads constructor param metadata written by `@injectable()`. Returns `undefined` if none present. */
+	/**
+	* Reads constructor param metadata written by `@injectable()`.
+	* Returns `undefined` if no own metadata is present on the class.
+	*
+	* @remarks
+	* Uses `Object.hasOwn` intentionally — TC39 `Symbol.metadata` prototype-chains from
+	* parent to child, so without this guard a subclass without `@injectable()` would
+	* silently inherit the parent's parameter list and inject the wrong dependency count.
+	*/
 	getConstructorMetadata(implementationClass) {
 		const rawMetadata = implementationClass[decoratorMetadataObjectSymbol()];
 		if (typeof rawMetadata !== "object" || rawMetadata === null) return;
@@ -19,7 +36,9 @@ var SymbolMetadataReader = class {
 		if (!isConstructorMetadata(raw)) return;
 		return raw;
 	}
-	/** Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes. */
+	/**
+	* Reads lifecycle method names written by `@postConstruct()` / `@preDestroy()`. Inherits from parent classes.
+	*/
 	getLifecycleMetadata(implementationClass) {
 		const metadataObject = implementationClass[decoratorMetadataObjectSymbol()];
 		if (typeof metadataObject !== "object" || metadataObject === null) return;