@codefast/di 0.7.0 → 0.8.0

package/src/errors/errors.ts

@@ -1,6 +1,10 @@
+import type { BindingTag } from "#/core/tag";
+import { slotName } from "#/core/tag";
 import type { BindingIdentifier, BindingScope, ResolveOptions } from "#/core/types";
 
 /**
+ * Base class for every error the library throws, each carrying a machine-readable `code`.
+ *
  * @since 0.3.16-canary.0
  */
 export abstract class DiError extends Error {
@@ -13,6 +17,8 @@ export abstract class DiError extends Error {
 }
 
 /**
+ * An internal assertion failure — a library bug, never caller misuse.
+ *
  * @since 0.3.16-canary.0
  */
 export class InternalError extends DiError {
@@ -24,6 +30,8 @@ export class InternalError extends DiError {
 }
 
 /**
+ * A token with no binding at all, even after walking the parent container chain.
+ *
  * @since 0.3.16-canary.0
  */
 export class TokenNotBoundError extends DiError {
@@ -37,19 +45,42 @@ export class TokenNotBoundError extends DiError {
 }
 
 // Options carry caller values a tag may hold — a bigint or a circular object must not make the
-// diagnostic itself throw and mask the real error.
+// diagnostic itself throw and mask the real error. The reserved criterion renders as `name`.
 function describeResolveOptions(options: ResolveOptions): string {
   try {
-    return (
-      JSON.stringify(options, (_key, value: unknown) => (typeof value === "bigint" ? `${String(value)}n` : value)) ??
-      "undefined"
-    );
+    let name = options.name;
+    const criteria: Array<string> = [];
+    const add = (criterion: BindingTag): void => {
+      if (criterion.key === slotName) {
+        name ??= String(criterion.value);
+      } else {
+        criteria.push(`${criterion.key.name}=${String(criterion.value)}`);
+      }
+    };
+    if (options.tag !== undefined) {
+      add(options.tag);
+    }
+    if (options.tags !== undefined) {
+      for (const criterion of options.tags) {
+        add(criterion);
+      }
+    }
+    const display: { name?: string; tags?: Array<string> } = {};
+    if (name !== undefined) {
+      display.name = name;
+    }
+    if (criteria.length > 0) {
+      display.tags = criteria;
+    }
+    return JSON.stringify(display) ?? "undefined";
   } catch {
     return "[unserializable options]";
   }
 }
 
 /**
+ * A token that has bindings, none of whose slots match the given `ResolveOptions`.
+ *
  * @since 0.3.16-canary.0
  */
 export class NoMatchingBindingError extends DiError {
@@ -69,6 +100,8 @@ export class NoMatchingBindingError extends DiError {
 }
 
 /**
+ * Two or more candidate bindings that matched without the more-specific rule deciding a winner.
+ *
  * @since 0.3.16-canary.0
  */
 export class AmbiguousBindingError extends DiError {
@@ -86,6 +119,8 @@ export class AmbiguousBindingError extends DiError {
 }
 
 /**
+ * A dependency cycle detected along the resolution path, alias chains included.
+ *
  * @since 0.3.16-canary.0
  */
 export class CircularDependencyError extends DiError {
@@ -99,6 +134,8 @@ export class CircularDependencyError extends DiError {
 }
 
 /**
+ * A sync `resolve()` of a token whose factory — or a dependency's factory — is async.
+ *
  * @since 0.3.16-canary.0
  */
 export class AsyncResolutionError extends DiError {
@@ -120,6 +157,8 @@ export class AsyncResolutionError extends DiError {
 }
 
 /**
+ * A sync `unbind()` of a binding whose `onDeactivation` handler is async.
+ *
  * @since 0.3.16-canary.0
  */
 export class AsyncDeactivationError extends DiError {
@@ -133,6 +172,8 @@ export class AsyncDeactivationError extends DiError {
 }
 
 /**
+ * The tokens, scopes, and resolution path describing a captive-dependency violation.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ScopeViolationDetails {
@@ -144,6 +185,8 @@ export interface ScopeViolationDetails {
 }
 
 /**
+ * A captive dependency — a longer-lived binding depending on a shorter-lived one.
+ *
  * @since 0.3.16-canary.0
  */
 export class ScopeViolationError extends DiError {
@@ -251,6 +294,8 @@ export class InvalidMetadataError extends DiError {
 }
 
 /**
+ * A class the container must construct but that carries no `@injectable()` metadata.
+ *
  * @since 0.3.16-canary.0
  */
 export class MissingMetadataError extends DiError {
@@ -266,6 +311,8 @@ export class MissingMetadataError extends DiError {
 }
 
 /**
+ * A sync `load()` given a module that needs async setup.
+ *
  * @since 0.3.16-canary.0
  */
 export class AsyncModuleLoadError extends DiError {
@@ -279,6 +326,8 @@ export class AsyncModuleLoadError extends DiError {
 }
 
 /**
+ * A synchronous disposal attempt on a container whose `onDeactivation` handlers may be async.
+ *
  * @since 0.3.16-canary.0
  */
 export class SyncDisposalNotSupportedError extends DiError {
@@ -292,6 +341,8 @@ export class SyncDisposalNotSupportedError extends DiError {
 }
 
 /**
+ * A `scoped` binding resolved from a container with no child scope context.
+ *
  * @since 0.3.16-canary.0
  */
 export class MissingScopeContextError extends DiError {
@@ -355,6 +406,8 @@ export class ChainNotRegisteredError extends DiError {
 }
 
 /**
+ * A `rebind()` of a token that has no own binding in this container.
+ *
  * @since 0.3.16-canary.0
  */
 export class RebindUnboundTokenError extends DiError {
@@ -410,6 +463,8 @@ export class StaticMemberDecoratorError extends DiError {
 }
 
 /**
+ * An operation attempted on a container that has already been disposed.
+ *
  * @since 0.3.16-canary.0
  */
 export class DisposedContainerError extends DiError {
@@ -421,6 +476,8 @@ export class DisposedContainerError extends DiError {
 }
 
 /**
+ * A `@postConstruct` or `onActivation` hook that returned a `Promise` on a sync resolution path.
+ *
  * @since 0.3.16-canary.0
  */
 export class AsyncActivationError extends DiError {

package/src/index.ts

@@ -21,7 +21,7 @@ export { token, tokenName } from "#/core/token";
 export type { Token } from "#/core/token";
 
 // Tag — the interned slot criteria a `whenTagged` and a resolve both take
-export { coversTagKeys, NO_TAG_KEYS, tag, tagKeyMaskOf } from "#/core/tag";
+export { coversTagKeys, NO_TAG_KEYS, slotName, tag, tagKeyMaskOf } from "#/core/tag";
 export type { TagKey, TagKeyMask } from "#/core/tag";
 
 // Binding builders — types only

package/src/injection/descriptor.ts

@@ -4,6 +4,8 @@ import type { BindingTag, Constructor, TokenValue } from "#/core/types";
 import type { DependencySlot } from "#/injection/resolve-options";
 
 /**
+ * Slot-selection options — a name and tags — a declared dependency narrows its binding with.
+ *
  * @since 0.3.16-canary.0
  */
 export interface InjectOptions {
@@ -31,6 +33,8 @@ export interface InjectionDescriptor<out Value = unknown> extends DependencySlot
 }
 
 /**
+ * A dependency as declared: a bare token, a class, or a full injection descriptor.
+ *
  * @since 0.3.16-canary.0
  */
 export type InjectableDependency<Value = unknown> = Token<Value> | Constructor<Value> | InjectionDescriptor<Value>;
@@ -60,6 +64,8 @@ export type ResolvedDependencyValue<Dependency> = Dependency extends { readonly
 type DescribedValue<Dependency> = Dependency extends InjectionDescriptor<infer Value> ? Value : TokenValue<Dependency>;
 
 /**
+ * Returns whether the value is an `InjectionDescriptor`, dual-role `inject()` functions included.
+ *
  * @since 0.3.16-canary.0
  */
 export function isInjectionDescriptor(value: unknown): value is InjectionDescriptor {
@@ -81,6 +87,8 @@ export function isInjectionDescriptor(value: unknown): value is InjectionDescrip
 }
 
 /**
+ * Normalises a declared dependency to a plain `InjectionDescriptor`.
+ *
  * @since 0.3.16-canary.0
  */
 export function normalizeToDescriptor(dependency: InjectableDependency): InjectionDescriptor {
@@ -172,6 +180,8 @@ export function buildInjectionDescriptor<Value>(
 }
 
 /**
+ * Creates a descriptor that resolves to `undefined` instead of throwing when no binding matches.
+ *
  * @since 0.3.16-canary.0
  */
 export function optional<Value>(
@@ -189,6 +199,8 @@ export function optional<Value>(
 }
 
 /**
+ * Creates a descriptor that resolves every matching binding for the token into an array.
+ *
  * @since 0.3.16-canary.0
  */
 export function injectAll<Value>(

package/src/injection/resolve-options.ts

@@ -1,4 +1,5 @@
 import type { BindingTag } from "#/core/tag";
+import { slotName, slotNameCriterionOf } from "#/core/tag";
 import type { Token } from "#/core/token";
 import type { Constructor, ResolveOptions } from "#/core/types";
 
@@ -19,37 +20,39 @@ export interface DependencySlot {
 }
 
 /**
- * A request whose only criterion is a name — the shape the registry has a direct index for.
+ * The lone criterion of a request that carries exactly one, whatever its spelling — the shape the
+ * registry has a direct index for.
  *
- * @since 0.5.0-canary.9
- */
-export function isNameOnlyOptions(options: ResolveOptions): options is ResolveOptions & { name: string } {
-  return (
-    options.name !== undefined && options.tag === undefined && (options.tags === undefined || options.tags.length === 0)
-  );
-}
-
-/**
- * The lone tag of a request that asks for exactly one, written either way — the shape the registry
- * has a direct tag index for.
- *
- * @remarks Both spellings answer here, so the index is not something one of them silently misses.
+ * @remarks Every spelling answers here, so the index is not something one of them silently misses;
+ * a name folds to the reserved `slotName` criterion, making the name lane the tag lane.
  *
  * @since 0.5.0-canary.9
  */
-export function singleTagOnlyOf(options: ResolveOptions): BindingTag | undefined {
-  if (options.name !== undefined) {
+export function singleCriterionOnlyOf(options: ResolveOptions | undefined): BindingTag | undefined {
+  if (options === undefined) {
     return undefined;
   }
+  if (options.name !== undefined) {
+    return loneNameCriterionOf(options);
+  }
   const listed = options.tags;
   const shorthand = options.tag;
   if (shorthand !== undefined) {
-    // Both sources present means the request carries two tags, which no single-tag index can answer.
     return listed === undefined || listed.length === 0 ? shorthand : undefined;
   }
   return listed !== undefined && listed.length === 1 ? listed[0] : undefined;
 }
 
+/** The name spelling's half of the fold, kept apart so the common body stays small enough to inline. */
+function loneNameCriterionOf(options: ResolveOptions): BindingTag | undefined {
+  // A name next to any tag means the request carries two criteria, which no single index answers.
+  if (options.tag !== undefined || (options.tags !== undefined && options.tags.length > 0)) {
+    return undefined;
+  }
+  // Read, not minted: a request must not retain a name no binding ever declared.
+  return slotNameCriterionOf(options.name as string);
+}
+
 /** Shared core: build a ResolveOptions from already-normalised name + tags. */
 function buildOptions(
   name: string | undefined,
@@ -83,8 +86,12 @@ export function injectionSlotToResolveOptions(
 /** Where a slot's derived options are memoized, so the same object is handed out every resolve. */
 const MEMOIZED_RESOLVE_OPTIONS: unique symbol = Symbol("di:resolve-options");
 
+/** Where a slot's folded lone criterion is memoized — `null` records "computed: none". */
+const MEMOIZED_SINGLE_CRITERION: unique symbol = Symbol("di:single-criterion");
+
 interface SlotWithMemoizedOptions {
   [MEMOIZED_RESOLVE_OPTIONS]?: ResolveOptions;
+  [MEMOIZED_SINGLE_CRITERION]?: BindingTag | null;
 }
 
 /**
@@ -126,6 +133,44 @@ function memoizeResolveOptions(
   return built;
 }
 
+/**
+ * The lone criterion a dependency's fixed criteria fold to, memoized on the slot like its options —
+ * `null` means the fold answered "none".
+ *
+ * @remarks A slot's criteria never change after declaration, so the fold happens once per slot
+ * rather than per hop — which is what keeps a named dependency's resolve off the intern map. A
+ * lone name whose criterion is not interned yet is left unmemoized: a later `whenNamed` binding
+ * mints it, and the next fold must see that.
+ *
+ * @since 0.8.0
+ */
+export function singleCriterionForSlot(injectionSlot: DependencySlot): BindingTag | null {
+  const slot = injectionSlot as SlotWithMemoizedOptions;
+  const memoized = slot[MEMOIZED_SINGLE_CRITERION];
+  if (memoized !== undefined) {
+    return memoized;
+  }
+  const options = resolveOptionsForSlot(injectionSlot);
+  const criterion = singleCriterionOnlyOf(options);
+  const folded = criterion ?? null;
+  if (criterion !== undefined || !isLoneNameOptions(options)) {
+    try {
+      slot[MEMOIZED_SINGLE_CRITERION] = folded;
+    } catch {
+      // A frozen slot re-folds on every hop rather than throwing.
+    }
+  }
+  return folded;
+}
+
+/** A slot request whose only criterion is a name — the one shape whose fold can change after a bind. */
+function isLoneNameOptions(options: ResolveOptions | undefined): boolean {
+  // Slot-derived options never carry the `tag` shorthand — `buildOptions` folds it into `tags`.
+  return (
+    options !== undefined && options.name !== undefined && (options.tags === undefined || options.tags.length === 0)
+  );
+}
+
 /**
  * Resolve options derived from a binding slot (tags may be empty; omits when nothing to match).
  *
@@ -140,5 +185,17 @@ export function bindingSlotToResolveOptions(bindingSlot: {
   readonly tags?: ReadonlyArray<BindingTag> | undefined;
 }): ResolveOptions | undefined {
   const tags = bindingSlot.tags;
-  return buildOptions(bindingSlot.name, tags !== undefined && tags.length > 0 ? tags : undefined);
+  let name = bindingSlot.name;
+  let criteria: ReadonlyArray<BindingTag> | undefined = tags !== undefined && tags.length > 0 ? tags : undefined;
+  if (criteria !== undefined) {
+    // A reserved criterion folds into `name` — carried in `tags` it would be said twice or, on a
+    // descriptor that spells its name as a tag, not at all.
+    const reserved = criteria.find((criterion) => criterion.key === slotName);
+    if (reserved !== undefined) {
+      name ??= reserved.value as string;
+      const rest = criteria.filter((criterion) => criterion.key !== slotName);
+      criteria = rest.length > 0 ? rest : undefined;
+    }
+  }
+  return buildOptions(name, criteria);
 }

package/src/introspection/dependency-graph.ts

@@ -1,6 +1,7 @@
 import type { Binding } from "#/core/binding";
 import { effectiveBindingScope } from "#/core/binding-scope";
 import type { BindingRegistry } from "#/core/registry";
+import { slotName } from "#/core/tag";
 import type { Token } from "#/core/token";
 import { tokenName } from "#/core/token";
 import type { BindingKind, BindingScope, Constructor } from "#/core/types";
@@ -43,6 +44,8 @@ export interface GraphEdge {
 }
 
 /**
+ * A container's dependency graph as plain JSON — nodes, edges, and whether the parent is included.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ContainerGraphJson {
@@ -52,6 +55,8 @@ export interface ContainerGraphJson {
 }
 
 /**
+ * Options controlling what a dependency graph includes.
+ *
  * @since 0.3.16-canary.0
  */
 export interface GraphOptions {
@@ -92,12 +97,23 @@ function matchingTargets(candidates: ReadonlyArray<Binding>, ref: DependencySlot
   return candidates.filter((candidate) => matchesSlot(candidate.slot, criterion));
 }
 
+/** The name a dependency asks for, whichever spelling carries it. */
+function refSlotName(ref: DependencySlot): string | undefined {
+  if (ref.name !== undefined) {
+    return ref.name;
+  }
+  const reserved = ref.tags?.find((criterion) => criterion.key === slotName);
+  return reserved === undefined ? undefined : String(reserved.value);
+}
+
 function edgeLabel(ref: DependencySlot, index: number): string {
+  const name = refSlotName(ref);
+  const firstPlainTag = ref.tags?.find((criterion) => criterion.key !== slotName);
   const criterion =
-    ref.name !== undefined
-      ? `name:${ref.name}`
-      : ref.tags !== undefined && ref.tags.length > 0
-        ? `tag:${ref.tags[0]?.key.name}=${String(ref.tags[0]?.value)}`
+    name !== undefined
+      ? `name:${name}`
+      : firstPlainTag !== undefined
+        ? `tag:${firstPlainTag.key.name}=${String(firstPlainTag.value)}`
         : `[${index}]`;
 
   return ref.optional ? `${criterion} optional` : criterion;
@@ -166,23 +182,25 @@ function addDependencyEdges(
       return;
     }
 
+    const unboundSlotName = refSlotName(ref);
     accumulator.edges.push({
       from,
       to: unboundNodeIdFor(accumulator, ref.token),
       label,
       optional: true,
-      ...(ref.name !== undefined ? { slotName: ref.name } : {}),
+      ...(unboundSlotName !== undefined ? { slotName: unboundSlotName } : {}),
     });
 
     return;
   }
 
+  const requestedName = refSlotName(ref);
   for (const target of targets) {
     // A multi dep with no criterion of its own fans out — each edge names the slot it hits.
-    const slotName = target.slot.name ?? ref.name;
+    const edgeSlotName = target.slot.name ?? requestedName;
     const perTargetLabel =
-      ref.multi && ref.name === undefined && slotName !== undefined
-        ? edgeLabel({ ...ref, name: slotName }, index)
+      ref.multi && requestedName === undefined && edgeSlotName !== undefined
+        ? edgeLabel({ ...ref, name: edgeSlotName }, index)
         : label;
 
     accumulator.edges.push({
@@ -190,7 +208,7 @@ function addDependencyEdges(
       to: target.id,
       label: perTargetLabel,
       optional: ref.optional,
-      ...(slotName !== undefined ? { slotName } : {}),
+      ...(edgeSlotName !== undefined ? { slotName: edgeSlotName } : {}),
     });
   }
 }
@@ -255,6 +273,8 @@ function addRegistryBindings(
 }
 
 /**
+ * Builds the JSON dependency graph of a registry's bindings, optionally including the parent's.
+ *
  * @since 0.3.16-canary.0
  */
 export function buildDependencyGraph(

package/src/introspection/graph-adapters/cytoscape.ts

@@ -1,6 +1,8 @@
 import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
+ * A dependency-graph node in Cytoscape's element format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface CytoscapeNode {
@@ -15,6 +17,8 @@ export interface CytoscapeNode {
 }
 
 /**
+ * A dependency-graph edge in Cytoscape's element format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface CytoscapeEdge {
@@ -29,11 +33,15 @@ export interface CytoscapeEdge {
 }
 
 /**
+ * The flat node-and-edge list Cytoscape takes as its `elements` input.
+ *
  * @since 0.3.16-canary.0
  */
 export type CytoscapeElements = ReadonlyArray<CytoscapeNode | CytoscapeEdge>;
 
 /**
+ * Converts a container's dependency graph into Cytoscape's element list.
+ *
  * @since 0.3.16-canary.0
  */
 export function toCytoscapeGraph(graph: ContainerGraphJson): CytoscapeElements {

package/src/introspection/graph-adapters/dot.ts

@@ -7,6 +7,8 @@ function escapeDotString(value: string): string {
 }
 
 /**
+ * Renders a container's dependency graph as Graphviz DOT source.
+ *
  * @since 0.3.16-canary.0
  */
 export function toDotGraph(graph: ContainerGraphJson): string {

package/src/introspection/graph-adapters/reactflow.ts

@@ -1,6 +1,8 @@
 import type { ContainerGraphJson, GraphNode } from "#/introspection/dependency-graph";
 
 /**
+ * A dependency-graph node in React Flow's node format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowNode {
@@ -16,6 +18,8 @@ export interface ReactFlowNode {
 }
 
 /**
+ * A dependency-graph edge in React Flow's edge format.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowEdge {
@@ -28,6 +32,8 @@ export interface ReactFlowEdge {
 }
 
 /**
+ * The nodes-and-edges pair a React Flow viewer renders.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ReactFlowGraph {
@@ -45,6 +51,8 @@ const GRID_CELL_WIDTH_PX = 200;
 const GRID_CELL_HEIGHT_PX = 100;
 
 /**
+ * Converts a container's dependency graph into React Flow nodes and edges on an initial grid.
+ *
  * @since 0.5.0-canary.7
  */
 export function toReactFlowGraph(graph: ContainerGraphJson): ReactFlowGraph {

package/src/introspection/inspector.ts

@@ -18,6 +18,8 @@ import { selectAllBindings } from "#/resolution/select/binding-select";
 // ── Public types ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * A read-only view of one binding: token, kind, scope, slot, and id.
+ *
  * @since 0.3.16-canary.0
  */
 export interface BindingSnapshot {
@@ -32,6 +34,8 @@ export interface BindingSnapshot {
 }
 
 /**
+ * A read-only view of one container's own bindings and state.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ContainerSnapshot {
@@ -44,6 +48,8 @@ export interface ContainerSnapshot {
 // ── Inspector ────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The read-only introspection surface behind a container's `inspect()`.
+ *
  * @since 0.3.16-canary.0
  */
 export class Inspector {

package/src/lifecycle/lifecycle-manager.ts

@@ -13,6 +13,8 @@ import { AsyncActivationError, AsyncDeactivationError, InvalidMetadataError } fr
 import type { MetadataReader } from "#/metadata/metadata-types";
 
 /**
+ * One container's registry of container-level activation and deactivation hooks, keyed by token.
+ *
  * @since 0.3.16-canary.0
  */
 export class LifecycleManager {

package/src/lifecycle/scope-manager.ts

@@ -5,6 +5,8 @@ import type { BindingIdentifier } from "#/core/types";
 import { MissingScopeContextError } from "#/errors/errors";
 
 /**
+ * One container's instance caches — singletons, in-flight async creations, and the scoped cache.
+ *
  * @since 0.3.16-canary.0
  */
 export class ScopeManager {

package/src/metadata/metadata-keys.ts

@@ -1,12 +1,18 @@
 /**
+ * The metadata key `@injectable` writes a class's constructor dependencies under.
+ *
  * @since 0.3.16-canary.0
  */
 export const INJECTABLE_KEY: unique symbol = Symbol("di:injectable");
 /**
+ * The metadata key `@postConstruct` and `@preDestroy` record method names under.
+ *
  * @since 0.3.16-canary.0
  */
 export const LIFECYCLE_KEY: unique symbol = Symbol("di:lifecycle");
 /**
+ * The metadata key `@inject` accessors record their injection descriptors under.
+ *
  * @since 0.3.16-canary.0
  */
 export const INJECT_ACCESSOR_KEY: unique symbol = Symbol("di:inject-accessor");

package/src/metadata/metadata-reader-token.ts

@@ -3,6 +3,8 @@ import type { Token } from "#/core/token";
 import type { MetadataReader } from "#/metadata/metadata-types";
 
 /**
+ * The token a custom `MetadataReader` is bound to for a container to pick up.
+ *
  * @since 0.3.16-canary.0
  */
 export const MetadataReaderToken: Token<MetadataReader> = token<MetadataReader>("MetadataReader");

package/src/metadata/metadata-types.ts

@@ -15,6 +15,8 @@ export interface ParamMetadata extends DependencySlot {
 }
 
 /**
+ * A class's declared constructor dependencies, as a `MetadataReader` reports them.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ConstructorMetadata {
@@ -22,6 +24,8 @@ export interface ConstructorMetadata {
 }
 
 /**
+ * The `postConstruct` and `preDestroy` method names a class declares.
+ *
  * @since 0.3.16-canary.0
  */
 export interface LifecycleMetadata {
@@ -40,6 +44,8 @@ export interface MutableLifecycleMetadata {
 }
 
 /**
+ * The port a container reads class metadata through — constructor deps, lifecycle, and accessors.
+ *
  * @since 0.3.16-canary.0
  */
 export interface MetadataReader {