@codefast/di 0.7.0 → 0.8.0

package/src/container/container.ts

@@ -50,6 +50,8 @@ import { DependencyResolver } from "#/resolution/resolver";
 // ── Container interface ──────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The public surface: binding, resolving, modules, lifecycle hooks, child scopes, and disposal.
+ *
  * @since 0.3.16-canary.0
  */
 export interface Container {
@@ -114,6 +116,8 @@ export interface ContainerOptions {
 }
 
 /**
+ * The factory surface the `Container` companion object exposes.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ContainerStatic {
@@ -182,9 +186,6 @@ class DefaultContainer implements Container {
     if (this.#moduleRefs !== undefined || this.#moduleBindingIds !== undefined) {
       builtSubsystems.push("container.moduleTables");
     }
-    if (this.#registry.isNamedIndexBuilt) {
-      builtSubsystems.push("registry.namedIndex");
-    }
     if (this.#registry.isTaggedIndexBuilt) {
       builtSubsystems.push("registry.taggedIndex");
     }
@@ -695,8 +696,10 @@ class DefaultContainer implements Container {
         ) {
           continue;
         }
+        // Warm the binding itself — re-selecting by its own criteria could pick a different
+        // candidate whose criteria are a subset of them.
         const slotOptions = bindingSlotToResolveOptions(binding.slot);
-        await this.resolveAsync(binding.token, slotOptions);
+        await this.#resolver.warmBindingAsync(binding, slotOptions);
       }
     }
   }
@@ -944,6 +947,8 @@ function throwCollected(errors: ReadonlyArray<unknown>, message: string): void {
 // ── Container static ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The companion factory that creates containers, empty or preloaded from modules.
+ *
  * @since 0.3.16-canary.0
  */
 export const Container: ContainerStatic = {

package/src/core/binding.ts

@@ -1,5 +1,5 @@
 import type { BindingTag, TagKeyMask } from "#/core/tag";
-import { NO_TAG_KEYS } from "#/core/tag";
+import { NO_TAG_KEYS, slotName, tagKeyMaskOf } from "#/core/tag";
 import type { Token } from "#/core/token";
 import type {
   ActivationHandler,
@@ -16,24 +16,48 @@ import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue
 // ── BindingSlot ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
- * The name-plus-tags coordinate a binding registers under and a request matches against.
+ * The criterion set a binding registers under and a request matches against.
  *
  * @since 0.3.16-canary.0
  */
 export interface BindingSlot {
+  /** Derived view of the reserved `slotName` criterion — `undefined` when the slot carries none. */
   readonly name: string | undefined;
+  /** The whole criterion set, the reserved name criterion included. */
   readonly tags: ReadonlyArray<BindingTag>;
   /** OR of this slot's tag keys, so the subset test is one word compare. */
   readonly keyMask: TagKeyMask;
 }
 
 /**
- * Returns whether two slots carry the same name and tag set, in any tag order.
+ * Builds a slot from its criterion set, deriving the name view and key mask.
+ *
+ * @remarks The one place the derived `name` is computed — a slot assembled any other way can carry
+ * a name criterion the readers of the view never see.
+ *
+ * @since 0.8.0
+ */
+export function createBindingSlot(tags: ReadonlyArray<BindingTag>): BindingSlot {
+  let name: string | undefined;
+  for (const criterion of tags) {
+    if (criterion.key === slotName) {
+      name = criterion.value as string;
+      break;
+    }
+  }
+  // Frozen like DEFAULT_BINDING_SLOT's list: frames and snapshots alias a slot's tags.
+  return { name, tags: Object.freeze([...tags]), keyMask: tagKeyMaskOf(tags) };
+}
+
+/**
+ * Returns whether two slots carry the same criterion set, in any order.
+ *
+ * @remarks The derived `name` is not compared — the criterion set alone is the identity.
  *
  * @since 0.3.16-canary.0
  */
 export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean {
-  if (left.name !== right.name || left.keyMask !== right.keyMask || left.tags.length !== right.tags.length) {
+  if (left.keyMask !== right.keyMask || left.tags.length !== right.tags.length) {
     return false;
   }
   for (const criterion of left.tags) {
@@ -68,7 +92,7 @@ export const DEFAULT_BINDING_SLOT: BindingSlot = { name: undefined, tags: Object
  * @since 0.3.16-canary.0
  */
 export function bindingSlotToString(slot: BindingSlot): string {
-  if (slot.name === undefined && slot.tags.length === 0) {
+  if (slot.tags.length === 0) {
     return "default";
   }
   const parts: Array<string> = [];
@@ -76,6 +100,10 @@ export function bindingSlotToString(slot: BindingSlot): string {
     parts.push(`name:${slot.name}`);
   }
   for (const criterion of slot.tags) {
+    // The reserved criterion already printed as the `name:` part.
+    if (criterion.key === slotName) {
+      continue;
+    }
     parts.push(`tag:${criterion.key.name}=${String(criterion.value)}`);
   }
   return parts.join(",");

package/src/core/module.ts

@@ -16,6 +16,8 @@ const ASYNC_MODULE_BRAND: unique symbol = Symbol("di:async-module");
 export const MODULE_SETUP: unique symbol = Symbol("di:module-setup");
 
 /**
+ * A named, reusable group of bindings a container applies synchronously via `load()`.
+ *
  * @since 0.3.16-canary.0
  */
 export interface SyncModule {
@@ -25,6 +27,8 @@ export interface SyncModule {
 }
 
 /**
+ * A named group of bindings whose setup is async, applied via `loadAsync()`.
+ *
  * @since 0.3.16-canary.0
  */
 export interface AsyncModule {
@@ -36,6 +40,8 @@ export interface AsyncModule {
 // ── Builder interfaces ───────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The binding surface a sync module's setup callback receives.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ModuleBuilder {
@@ -44,6 +50,8 @@ export interface ModuleBuilder {
 }
 
 /**
+ * The binding surface an async module's setup callback receives; its `import` accepts async modules too.
+ *
  * @since 0.3.16-canary.0
  */
 export interface AsyncModuleBuilder {
@@ -54,6 +62,8 @@ export interface AsyncModuleBuilder {
 // ── Static factories ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The companion factory that creates `SyncModule` values.
+ *
  * @since 0.3.16-canary.0
  */
 export const SyncModule = {
@@ -67,6 +77,8 @@ export const SyncModule = {
 };
 
 /**
+ * The companion factory that creates `AsyncModule` values.
+ *
  * @since 0.3.16-canary.0
  */
 export const AsyncModule = {
@@ -82,6 +94,8 @@ export const AsyncModule = {
 // ── Module — unified API ─────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The unified module factory — `create` for sync modules, `createAsync` for async ones.
+ *
  * @since 0.3.16-canary.0
  */
 export const Module = {
@@ -94,6 +108,8 @@ export const Module = {
 };
 
 /**
+ * Narrows a module union to `SyncModule` by checking its brand.
+ *
  * @since 0.3.16-canary.0
  */
 export function isSyncModule(module: SyncModule | AsyncModule): module is SyncModule {

package/src/core/registry.ts

@@ -6,6 +6,8 @@ import type { Token } from "#/core/token";
 import type { BindingIdentifier, Constructor, DependencyKey } from "#/core/types";
 
 /**
+ * One container's binding store, indexed by token, binding id, and slot for fast lookup.
+ *
  * @since 0.3.16-canary.0
  */
 export class BindingRegistry {
@@ -15,15 +17,13 @@ export class BindingRegistry {
   readonly #bindings = new Map<DependencyKey, Array<Binding>>();
   // Fast lookup by binding ID
   readonly #byId = new Map<BindingIdentifier, Binding>();
-  // Fast lookup for slot { name, tags: [] } — unallocated until a named binding is registered.
-  #simpleNamed: Map<DependencyKey, Map<string, Binding>> | undefined;
   // Fast path for one default slot binding with no predicate
   readonly #fastDefault = new Map<DependencyKey, Binding>();
-  // Fast lookup for a slot carrying exactly one tag — keyed by the interned criterion itself, so
-  // the (key, value) pair is one hash rather than two. Unallocated until a tagged binding lands.
+  // Fast lookup for a slot carrying exactly one criterion (a lone name folds here too) — keyed by
+  // the interned criterion itself, so the pair is one hash. Unallocated until such a slot lands.
   #simpleTagged: Map<DependencyKey, Map<BindingTag, Binding>> | undefined;
-  // Name-less slots with two or more tags, bucketed by their FIRST criterion. A matching slot's
-  // every tag is in the request, so walking the request's buckets finds each candidate exactly once.
+  // Slots with two or more criteria, bucketed by their FIRST criterion. A matching slot's every
+  // criterion is in the request, so walking the request's buckets finds each candidate exactly once.
   #multiTagged: Map<DependencyKey, Map<BindingTag, Array<Binding>>> | undefined;
 
   // Set on the first constant registered and never cleared. Teardown only needs the negative answer
@@ -77,7 +77,6 @@ export class BindingRegistry {
         if (existingIndex !== -1) {
           displacedBinding = bindingsForToken[existingIndex]!;
           this.#byId.delete(displacedBinding.id);
-          this.#deindexSimpleNamedBinding(key, displacedBinding);
           this.#deindexSimpleTaggedBinding(key, displacedBinding);
           this.#deindexMultiTaggedBinding(key, displacedBinding);
         }
@@ -90,7 +89,6 @@ export class BindingRegistry {
 
     this.#bindings.set(key, nextBindings);
     this.#byId.set(binding.id, binding);
-    this.#indexSimpleNamedBinding(key, binding);
     this.#indexSimpleTaggedBinding(key, binding);
     this.#indexMultiTaggedBinding(key, binding);
     this.#refreshFastDefaultForToken(key);
@@ -103,7 +101,6 @@ export class BindingRegistry {
     const key: DependencyKey = token;
     const bindingsForToken = this.#bindings.get(key) ?? [];
     this.#bindings.delete(key);
-    this.#simpleNamed?.delete(key);
     this.#simpleTagged?.delete(key);
     this.#multiTagged?.delete(key);
     this.#fastDefault.delete(key);
@@ -127,12 +124,10 @@ export class BindingRegistry {
       const bindingIndex = bindingsForToken.findIndex((candidate) => candidate.id === id);
       // Copy-on-write, like `add`: a walk holding the current array must not lose its place.
       const remaining = bindingIndex === -1 ? bindingsForToken : bindingsForToken.toSpliced(bindingIndex, 1);
-      this.#deindexSimpleNamedBinding(key, binding);
       this.#deindexSimpleTaggedBinding(key, binding);
       this.#deindexMultiTaggedBinding(key, binding);
       if (remaining.length === 0) {
         this.#bindings.delete(key);
-        this.#simpleNamed?.delete(key);
         this.#simpleTagged?.delete(key);
         this.#multiTagged?.delete(key);
         this.#fastDefault.delete(key);
@@ -176,7 +171,6 @@ export class BindingRegistry {
     const all = this.allBindings();
     this.#bindings.clear();
     this.#byId.clear();
-    this.#simpleNamed?.clear();
     this.#simpleTagged?.clear();
     this.#multiTagged?.clear();
     this.#fastDefault.clear();
@@ -197,10 +191,6 @@ export class BindingRegistry {
     );
   }
 
-  getSimpleNamed(token: Token<unknown> | Constructor, name: string): Binding | undefined {
-    return this.#simpleNamed?.get(token)?.get(name);
-  }
-
   /**
    * The binding indexed under one criterion.
    *
@@ -285,33 +275,6 @@ export class BindingRegistry {
     }
   }
 
-  #indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const name = simpleNameOf(binding);
-    if (name === undefined) {
-      return;
-    }
-    this.#simpleNamed ??= new Map();
-    const bindingsByName = getOrInsert(this.#simpleNamed, tokenKey, new Map<string, Binding>());
-    bindingsByName.set(name, binding);
-  }
-
-  #deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
-    const name = simpleNameOf(binding);
-    if (name === undefined) {
-      return;
-    }
-    const bindingsByName = this.#simpleNamed?.get(tokenKey);
-    if (bindingsByName === undefined) {
-      return;
-    }
-    if (bindingsByName.get(name)?.id === binding.id) {
-      bindingsByName.delete(name);
-      if (bindingsByName.size === 0) {
-        this.#simpleNamed!.delete(tokenKey);
-      }
-    }
-  }
-
   #refreshFastDefaultForToken(tokenKey: DependencyKey): void {
     const bindingsForToken = this.#bindings.get(tokenKey);
     const onlyBinding = bindingsForToken?.length === 1 ? bindingsForToken[0]! : undefined;
@@ -322,48 +285,35 @@ export class BindingRegistry {
     this.#fastDefault.delete(tokenKey);
   }
 
-  /** Whether the deferred named-slot index has had to be built. */
-  get isNamedIndexBuilt(): boolean {
-    return this.#simpleNamed !== undefined;
-  }
-
   /** Whether the deferred tagged-slot index has had to be built. */
   get isTaggedIndexBuilt(): boolean {
     return this.#simpleTagged !== undefined;
   }
 }
 
-/** The name a binding is indexed under, or `undefined` when its slot is more than a plain name. */
-function simpleNameOf(binding: Binding): string | undefined {
-  const { name, tags } = binding.slot;
-  return name !== undefined && tags.length === 0 ? name : undefined;
-}
-
 /**
- * The tag a binding is indexed under, or `undefined` when its slot is more than one plain tag.
+ * The criterion a binding is indexed under, or `undefined` when its slot carries more than one.
  *
- * @remarks Carries predicate-bearing bindings too, exactly as the name index does: every lane that
- * reads this index already re-checks what it finds, so an indexed hit was never unconditional.
+ * @remarks Carries predicate-bearing bindings too: every lane that reads this index already
+ * re-checks what it finds, so an indexed hit was never unconditional.
  */
 function simpleTagOf(binding: Binding): BindingTag | undefined {
-  const { name, tags } = binding.slot;
-  return name === undefined && tags.length === 1 ? tags[0] : undefined;
+  const { tags } = binding.slot;
+  return tags.length === 1 ? tags[0] : undefined;
 }
 
-/** The first criterion a multi-tag slot is bucketed under, or `undefined` for any other shape. */
+/** The first criterion a multi-criterion slot is bucketed under, or `undefined` for any other shape. */
 function multiTagFirstOf(binding: Binding): BindingTag | undefined {
-  const { name, tags } = binding.slot;
-  return name === undefined && tags.length >= 2 ? tags[0] : undefined;
+  const { tags } = binding.slot;
+  return tags.length >= 2 ? tags[0] : undefined;
 }
 
 /** A binding nothing has to be matched against: the default slot, no predicate. */
 function isDefaultSlotBinding(binding: Binding): boolean {
-  const { name, tags } = binding.slot;
-  return name === undefined && tags.length === 0 && binding.predicate === undefined;
+  return binding.slot.tags.length === 0 && binding.predicate === undefined;
 }
 
 /** A predicate with no slot constraint: last-wins does not apply to it. */
 function isPurePredicateBinding(binding: Binding): boolean {
-  const { name, tags } = binding.slot;
-  return binding.predicate !== undefined && name === undefined && tags.length === 0;
+  return binding.predicate !== undefined && binding.slot.tags.length === 0;
 }

package/src/core/tag.ts

@@ -58,6 +58,14 @@ export interface TagKey<Value = unknown> {
   readonly mask: TagKeyMask;
   /** The criterion for one value, interned: the same value always yields the same object. */
   of(value: Value): BindingTag<Value>;
+  /**
+   * The interned criterion for a value, or `undefined` when none was ever minted.
+   *
+   * @remarks Reading without minting is what keeps a request-side value from being retained for
+   * the process lifetime: a value no binding ever declared has no criterion, so a lookup can
+   * answer "no match" without inserting one.
+   */
+  peek(value: Value): BindingTag<Value> | undefined;
 }
 
 let tagKeyCounter = -1;
@@ -101,6 +109,28 @@ export function tag<Value = unknown>(name: string): TagKey<Value> {
   let lastValue: Value | undefined;
   let lastPair: BindingTag<Value> | undefined;
 
+  // The miss paths live outside `of()`/`peek()` so the hot wrappers stay small enough to inline.
+  const internPair = (value: Value): BindingTag<Value> => {
+    const cacheKey = internKeyFor(value);
+    const existing = interned.get(cacheKey);
+
+    if (existing !== undefined) {
+      lastValue = value;
+      lastPair = existing;
+
+      return existing;
+    }
+
+    const pair = { key, value, mask } as BindingTag<Value>;
+
+    interned.set(cacheKey, pair);
+    lastValue = value;
+    lastPair = pair;
+
+    return pair;
+  };
+  const peekInterned = (value: Value): BindingTag<Value> | undefined => interned.get(internKeyFor(value));
+
   const key: TagKey<Value> = {
     name,
     id,
@@ -109,30 +139,54 @@ export function tag<Value = unknown>(name: string): TagKey<Value> {
       if (lastPair !== undefined && Object.is(value, lastValue)) {
         return lastPair;
       }
-
-      const cacheKey = internKeyFor(value);
-      const existing = interned.get(cacheKey);
-
-      if (existing !== undefined) {
-        lastValue = value;
-        lastPair = existing;
-
-        return existing;
+      return internPair(value);
+    },
+    peek(value: Value): BindingTag<Value> | undefined {
+      if (lastPair !== undefined && Object.is(value, lastValue)) {
+        return lastPair;
       }
-
-      const pair = { key, value, mask } as BindingTag<Value>;
-
-      interned.set(cacheKey, pair);
-      lastValue = value;
-      lastPair = pair;
-
-      return pair;
+      return peekInterned(value);
     },
   };
 
   return key;
 }
 
+/**
+ * The reserved key a slot's name is a criterion of.
+ *
+ * @remarks `whenNamed(n)` and a request's `name` are sugar for `slotName.of(n)`, so one selection
+ * model serves both spellings — a name takes part in key masks, indexes and specificity like any
+ * criterion. What reserves the key is its identity; diagnostics render its criteria as `name:<value>`.
+ *
+ * @since 0.8.0
+ */
+export const slotName: TagKey<string> = tag<string>("di:name");
+
+// One-entry front for the reserved key's read: a name's criterion never changes once minted, so a
+// hit is sound forever, and a miss is never cached so a later `whenNamed` bind is still seen.
+let lastPeekedName: string | undefined;
+let lastPeekedCriterion: BindingTag<string> | undefined;
+
+/**
+ * The reserved criterion for a name, or `undefined` while no binding has declared it.
+ *
+ * @remarks Reads without minting, so a request-side name no binding declared is never retained.
+ *
+ * @since 0.8.0
+ */
+export function slotNameCriterionOf(name: string): BindingTag<string> | undefined {
+  if (name === lastPeekedName) {
+    return lastPeekedCriterion;
+  }
+  const criterion = slotName.peek(name);
+  if (criterion !== undefined) {
+    lastPeekedName = name;
+    lastPeekedCriterion = criterion;
+  }
+  return criterion;
+}
+
 /**
  * The key set a list of criteria covers.
  *

package/src/core/token.ts

@@ -3,6 +3,8 @@ import type { Constructor } from "#/core/constructor-type";
 declare const TOKEN_BRAND: unique symbol;
 
 /**
+ * A branded identifier carrying the value type its bindings resolve to.
+ *
  * @since 0.3.16-canary.0
  */
 export interface Token<out Value> {
@@ -11,6 +13,8 @@ export interface Token<out Value> {
 }
 
 /**
+ * Creates a named `Token` for the given value type.
+ *
  * @since 0.3.16-canary.0
  */
 export function token<Value>(name: string): Token<Value> {
@@ -18,6 +22,8 @@ export function token<Value>(name: string): Token<Value> {
 }
 
 /**
+ * Returns the display name of a token or class used as a dependency key.
+ *
  * @since 0.3.16-canary.0
  */
 export function tokenName(dependency: Token<unknown> | Constructor): string {

package/src/core/types.ts

@@ -16,6 +16,8 @@ export type DependencyKey = Token<unknown> | Constructor;
 // ── BindingScope ─────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The lifetime a binding's instances are cached under.
+ *
  * @since 0.3.16-canary.0
  */
 export type BindingScope = "singleton" | "transient" | "scoped";
@@ -24,6 +26,8 @@ export type BindingScope = "singleton" | "transient" | "scoped";
 
 declare const BINDING_ID_BRAND: unique symbol;
 /**
+ * A branded string that uniquely identifies one binding.
+ *
  * @since 0.3.16-canary.0
  */
 export type BindingIdentifier = string & { readonly [BINDING_ID_BRAND]: true };
@@ -31,6 +35,8 @@ export type BindingIdentifier = string & { readonly [BINDING_ID_BRAND]: true };
 // ── BindingKind ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The strategy a binding produces values with, set by the `to*()` call that created it.
+ *
  * @since 0.3.16-canary.0
  */
 export type BindingKind = "class" | "dynamic" | "dynamic-async" | "resolved" | "resolved-async" | "constant" | "alias";
@@ -38,11 +44,15 @@ export type BindingKind = "class" | "dynamic" | "dynamic-async" | "resolved" | "
 // ── Handlers ─────────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * A hook that runs after an instance is created and returns the instance to hand out.
+ *
  * @since 0.3.16-canary.0
  */
 export type ActivationHandler<Value> = (ctx: ResolutionContext, instance: Value) => Value | Promise<Value>;
 
 /**
+ * A hook that runs when a cached instance is released from its scope.
+ *
  * @since 0.3.16-canary.0
  */
 export type DeactivationHandler<Value> = (instance: Value) => void | Promise<void>;
@@ -50,6 +60,8 @@ export type DeactivationHandler<Value> = (instance: Value) => void | Promise<voi
 // ── ResolveOptions ───────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * Slot-selection criteria — a name and tags — that narrow which binding a resolve call matches.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolveOptions {
@@ -67,6 +79,8 @@ export interface ResolveOptions {
 // ── ResolutionFrame ──────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * One entry of the resolution stack: the token, scope, binding, and slot being resolved.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolutionFrame {
@@ -84,6 +98,8 @@ export interface ResolutionFrame {
 // ── ConstraintContext ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The resolution-time view — path, stack, parent, and ancestors — a `BindingConstraint` inspects.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ConstraintContext {
@@ -105,6 +121,8 @@ export type BindingConstraint = (ctx: ConstraintContext) => boolean;
 // ── ResolutionContext ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The container view a dynamic factory or activation handler resolves further dependencies through.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolutionContext {
@@ -123,6 +141,8 @@ export interface ResolutionContext {
 // ── TokenValue ───────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The value type a token or class constructor resolves to.
+ *
  * @since 0.3.16-canary.0
  */
 export type TokenValue<Type> =

package/src/decorators/inject.ts

@@ -35,6 +35,8 @@ type ClassAccessorDecorator<This, Value> = (
 ) => ClassAccessorDecoratorResult<This, Value> | void;
 
 /**
+ * Creates a dual-role value: an injection descriptor that also works as a class accessor decorator.
+ *
  * @since 0.3.16-canary.0
  */
 export function inject<Value>(

package/src/decorators/injectable.ts

@@ -7,6 +7,8 @@ import type { ParamMetadata } from "#/metadata/metadata-types";
 // ── AutoRegisterRegistry ─────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The collector `@injectable` registers a class into, for a container to bind later.
+ *
  * @since 0.3.16-canary.0
  */
 export interface AutoRegisterRegistry {
@@ -15,6 +17,8 @@ export interface AutoRegisterRegistry {
 }
 
 /**
+ * Creates an empty auto-register registry.
+ *
  * @since 0.3.16-canary.0
  */
 export function createAutoRegisterRegistry(): AutoRegisterRegistry {
@@ -32,6 +36,8 @@ export function createAutoRegisterRegistry(): AutoRegisterRegistry {
 // ── InjectableOptions ────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * Auto-registration options `@injectable` accepts alongside its deps list.
+ *
  * @since 0.3.16-canary.0
  */
 export interface InjectableOptions {
@@ -83,6 +89,8 @@ export function injectable<const Deps extends ReadonlyArray<InjectableDependency
 ) => void;
 
 /**
+ * Writes the declared dependencies into the class's metadata and optionally auto-registers it.
+ *
  * @since 0.6.0
  */
 export function injectable(

package/src/decorators/lifecycle-decorators.ts

@@ -25,6 +25,8 @@ function recordLifecycleMethod(phase: "postConstruct" | "preDestroy"): MethodDec
 }
 
 /**
+ * Marks an instance method to run after the container constructs and wires the instance.
+ *
  * @since 0.3.16-canary.0
  */
 export function postConstruct(): MethodDecorator {
@@ -32,6 +34,8 @@ export function postConstruct(): MethodDecorator {
 }
 
 /**
+ * Marks an instance method to run when the instance's container or scope is disposed.
+ *
  * @since 0.3.16-canary.0
  */
 export function preDestroy(): MethodDecorator {