@codefast/di 0.5.0 → 0.6.1

package/src/resolution/{binding-lookup-cache.ts → cache/binding-lookup-cache.ts}

@@ -1,12 +1,14 @@
 /**
  * Options-less token → terminal binding, memoized per container chain.
  *
- * @see `ARCHITECTURE.md` — why these caches form their own parent chain.
+ * @remarks Each cache links to its parent's, so a child answers from its own chain without walking
+ * the container hierarchy again.
  */
-import type { Binding } from "#/binding";
-import type { BindingRegistry } from "#/registry";
-import type { Token } from "#/token";
-import type { Constructor } from "#/types";
+import type { Binding } from "#/core/binding";
+import type { BindingRegistry } from "#/core/registry";
+import type { BindingTag } from "#/core/tag";
+import type { Token } from "#/core/token";
+import type { Constructor } from "#/core/types";
 
 /**
  * A token's terminal binding with alias hops already folded, plus the container that owns it.
@@ -33,6 +35,8 @@ export const ALIAS_HOP_LIMIT = 32;
  */
 const newNameToEntryMap = <Owner>(): Map<string, DefaultLookupEntry<Owner> | null> => new Map();
 
+const newTagToEntryMap = <Owner>(): Map<BindingTag, DefaultLookupEntry<Owner> | null> => new Map();
+
 /**
  * @since 0.5.0-canary.9
  */
@@ -46,6 +50,14 @@ export class BindingLookupCache<Owner> {
   #lastEntry: DefaultLookupEntry<Owner> | null = null;
   readonly #byTokenAndName = new Map<Token<unknown> | Constructor, Map<string, DefaultLookupEntry<Owner> | null>>();
   #namedVersion = -1;
+  readonly #byTokenAndTag = new Map<Token<unknown> | Constructor, Map<BindingTag, DefaultLookupEntry<Owner> | null>>();
+  #taggedVersion = -1;
+  // One entry in front of the tag map, and the map is not written until a second distinct request
+  // shape appears: a per-request child usually asks one (token, tag) once, and the inner-map
+  // allocation was that shape's whole regression when this memo landed.
+  #lastTagToken: Token<unknown> | Constructor | undefined;
+  #lastTag: BindingTag | undefined;
+  #lastTaggedEntry: DefaultLookupEntry<Owner> | null = null;
 
   readonly #registry: BindingRegistry;
   readonly #owner: Owner;
@@ -104,6 +116,37 @@ export class BindingLookupCache<Owner> {
     return entry;
   }
 
+  /** `null` when the tag's shape needs the full selection path. */
+  taggedEntry(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
+    const version = this.chainVersion();
+    if (version !== this.#taggedVersion) {
+      this.#byTokenAndTag.clear();
+      this.#taggedVersion = version;
+      this.#lastTagToken = undefined;
+      this.#lastTag = undefined;
+    } else if (token === this.#lastTagToken && tag === this.#lastTag) {
+      return this.#lastTaggedEntry;
+    }
+    let entry: DefaultLookupEntry<Owner> | null | undefined;
+    if (this.#lastTagToken === undefined) {
+      // First shape this cache generation sees: answer from the walk and defer the map entirely.
+      entry = this.#findTaggedInChain(token, tag);
+    } else {
+      // Keyed by the criterion object itself: criteria are interned, so identity is the slot
+      // contract's own `Object.is` — the same exactness the registry's tagged index relies on.
+      const byTag = this.#byTokenAndTag.getOrInsertComputed(token, newTagToEntryMap);
+      entry = byTag.get(tag);
+      if (entry === undefined) {
+        entry = this.#findTaggedInChain(token, tag);
+        byTag.set(tag, entry);
+      }
+    }
+    this.#lastTagToken = token;
+    this.#lastTag = tag;
+    this.#lastTaggedEntry = entry;
+    return entry;
+  }
+
   #foldAliases(token: Token<unknown> | Constructor): DefaultLookupEntry<Owner> | null {
     let current = token;
     for (let hop = 0; hop < ALIAS_HOP_LIMIT; hop += 1) {
@@ -145,4 +188,19 @@ export class BindingLookupCache<Owner> {
     }
     return this.#parent === undefined ? null : this.#parent.#findNamedInChain(token, name);
   }
+
+  #findTaggedInChain(token: Token<unknown> | Constructor, tag: BindingTag): DefaultLookupEntry<Owner> | null {
+    const tagged = this.#registry.getSimpleTagged(token, tag);
+    if (tagged !== undefined) {
+      // Predicates need a live context; aliases carry options through the full path.
+      if (tagged.predicate !== undefined || tagged.kind === "alias") {
+        return null;
+      }
+      return { binding: tagged, owner: this.#owner };
+    }
+    if (this.#registry.has(token)) {
+      return null;
+    }
+    return this.#parent === undefined ? null : this.#parent.#findTaggedInChain(token, tag);
+  }
 }

package/src/resolution/cache/class-introspector.ts

@@ -0,0 +1,251 @@
+/**
+ * Per-class decorator metadata, cached by constructor.
+ *
+ * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
+ */
+
+import { runWithAmbientResolution } from "#/ambient/active-container";
+import type { AmbientResolution } from "#/ambient/active-container";
+import type { Container } from "#/container/container";
+import type { ConstructorInvocation } from "#/core/constructor-type";
+import type { Constructor } from "#/core/types";
+import { InvalidMetadataError } from "#/errors/errors";
+import type { InjectionDescriptor } from "#/injection/descriptor";
+import type { ConstructorMetadata, LifecycleMetadata, MetadataReader } from "#/metadata/metadata-types";
+
+// Verified pairs, not verified classes: two readers may disagree about the same class, and a reader
+// that goes out of scope takes its record with it.
+const verifiedTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
+const verifiedLifecycleTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
+const verifiedAccessorTargets = new WeakMap<MetadataReader, WeakSet<Constructor>>();
+
+function isVerified(
+  cache: WeakMap<MetadataReader, WeakSet<Constructor>>,
+  reader: MetadataReader,
+  target: Constructor,
+): boolean {
+  return cache.get(reader)?.has(target) ?? false;
+}
+
+function markVerified(
+  cache: WeakMap<MetadataReader, WeakSet<Constructor>>,
+  reader: MetadataReader,
+  target: Constructor,
+): void {
+  let verified = cache.get(reader);
+  if (verified === undefined) {
+    verified = new WeakSet();
+    cache.set(reader, verified);
+  }
+  verified.add(target);
+}
+
+/**
+ * A reader's constructor metadata for a class, verified the first time this process asks.
+ *
+ * @remarks Metadata cannot change once a class is defined, so re-checking per container would charge
+ * every fresh container for a fact already established — a per-request child or a cold boot pays
+ * that repeatedly.
+ *
+ * @since 0.6.0
+ */
+export function verifyConstructorMetadata(
+  reader: MetadataReader,
+  target: Constructor,
+): ConstructorMetadata | undefined {
+  const metadata = reader.getConstructorMetadata(target);
+  if (metadata === undefined) {
+    return undefined;
+  }
+  if (isVerified(verifiedTargets, reader, target)) {
+    return metadata;
+  }
+  assertConstructorMetadata(metadata, target);
+  markVerified(verifiedTargets, reader, target);
+
+  return metadata;
+}
+
+/**
+ * Verifies what a reader claims about a class, since a `MetadataReader` is a public seam.
+ *
+ * @remarks Every path that reads constructor metadata comes through here, so a reader that answers
+ * wrongly is a named error at the class it described rather than a `TypeError` raised later inside a
+ * resolve. Only what a consumer dereferences is checked: `params` and each entry's `token`.
+ * `optional`/`multi` degrade to falsy without crashing, and `index` is decorative — dependencies are
+ * consumed positionally.
+ *
+ * @since 0.6.0
+ */
+export function assertConstructorMetadata(metadata: unknown, target: Constructor): ConstructorMetadata | undefined {
+  if (metadata === undefined) {
+    return undefined;
+  }
+  if (typeof metadata !== "object" || metadata === null) {
+    throw new InvalidMetadataError(
+      target.name,
+      `constructor metadata: expected an object, received ${typeof metadata}`,
+    );
+  }
+  const params: unknown = Reflect.get(metadata, "params");
+  if (!Array.isArray(params)) {
+    throw new InvalidMetadataError(target.name, "constructor metadata: params is not an array");
+  }
+  for (const [position, param] of params.entries()) {
+    if (typeof param !== "object" || param === null) {
+      throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}] is not an object`);
+    }
+    const dependency: unknown = Reflect.get(param, "token");
+    if (typeof dependency !== "object" && typeof dependency !== "function") {
+      throw new InvalidMetadataError(
+        target.name,
+        `constructor metadata: params[${String(position)}].token is not a token or a class`,
+      );
+    }
+  }
+
+  return metadata as ConstructorMetadata;
+}
+
+/**
+ * A reader's lifecycle metadata for a class, verified the first time this process asks.
+ *
+ * @since 0.6.0
+ */
+export function verifyLifecycleMetadata(reader: MetadataReader, target: Constructor): LifecycleMetadata | undefined {
+  const metadata = reader.getLifecycleMetadata(target);
+  if (metadata === undefined || isVerified(verifiedLifecycleTargets, reader, target)) {
+    return metadata;
+  }
+  if (typeof metadata !== "object" || metadata === null) {
+    throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
+  }
+  for (const phase of ["postConstruct", "preDestroy"] as const) {
+    const methods: unknown = Reflect.get(metadata, phase);
+    if (methods === undefined) {
+      continue;
+    }
+    if (!Array.isArray(methods)) {
+      throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
+    }
+    for (const [position, name] of methods.entries()) {
+      if (typeof name !== "string") {
+        throw new InvalidMetadataError(
+          target.name,
+          `lifecycle metadata: ${phase}[${String(position)}] is not a string`,
+        );
+      }
+    }
+  }
+  markVerified(verifiedLifecycleTargets, reader, target);
+  return metadata;
+}
+
+/**
+ * A reader's accessor metadata for a class, verified the first time this process asks.
+ *
+ * @since 0.6.0
+ */
+export function verifyAccessorMetadata(
+  reader: MetadataReader,
+  target: Constructor,
+): ReadonlyArray<{ readonly key: string | symbol; readonly descriptor: InjectionDescriptor }> | undefined {
+  const metadata = reader.getAccessorMetadata?.(target);
+  if (metadata === undefined || isVerified(verifiedAccessorTargets, reader, target)) {
+    return metadata;
+  }
+  if (!Array.isArray(metadata)) {
+    throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
+  }
+  for (const [position, entry] of metadata.entries()) {
+    if (typeof entry !== "object" || entry === null) {
+      throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
+    }
+    const key: unknown = Reflect.get(entry, "key");
+    if (typeof key !== "string" && typeof key !== "symbol") {
+      throw new InvalidMetadataError(
+        target.name,
+        `accessor metadata: [${String(position)}].key is not a string or symbol`,
+      );
+    }
+    const descriptor: unknown = Reflect.get(entry, "descriptor");
+    if (typeof descriptor !== "object" || descriptor === null) {
+      throw new InvalidMetadataError(
+        target.name,
+        `accessor metadata: [${String(position)}].descriptor is not an object`,
+      );
+    }
+    const dependency: unknown = Reflect.get(descriptor, "token");
+    if (typeof dependency !== "object" && typeof dependency !== "function") {
+      throw new InvalidMetadataError(
+        target.name,
+        `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`,
+      );
+    }
+  }
+  markVerified(verifiedAccessorTargets, reader, target);
+  return metadata;
+}
+
+/**
+ * @since 0.5.0-canary.8
+ */
+export class ClassIntrospector {
+  // Unallocated until the container resolves its first class binding — a container bound entirely
+  // to constants, factories or aliases never introspects one.
+  #constructorMetadata: WeakMap<Constructor, ConstructorMetadata | null> | undefined;
+  #hasPostConstruct: WeakMap<Constructor, boolean> | undefined;
+  #needsActiveContainer: WeakMap<Constructor, boolean> | undefined;
+  readonly #reader: MetadataReader;
+  readonly #container: Container;
+
+  constructor(reader: MetadataReader, container: Container) {
+    this.#reader = reader;
+    this.#container = container;
+  }
+
+  constructorMetadata(target: Constructor): ConstructorMetadata | undefined {
+    const cached = this.#constructorMetadata?.get(target);
+    if (cached !== undefined) {
+      return cached === null ? undefined : cached;
+    }
+    const metadata = this.#reader.getConstructorMetadata(target);
+    (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+    return metadata;
+  }
+
+  /**
+   * Whether the class has a `@postConstruct` hook, or `undefined` until {@link discoverPostConstruct}.
+   *
+   * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
+   */
+  knownPostConstruct(target: Constructor): boolean | undefined {
+    return this.#hasPostConstruct?.get(target);
+  }
+
+  discoverPostConstruct(target: Constructor): void {
+    const lifecycle = this.#reader.getLifecycleMetadata(target);
+    (this.#hasPostConstruct ??= new WeakMap()).set(
+      target,
+      lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0,
+    );
+  }
+
+  /** True when the class has accessor injection, which reads the container during construction. */
+  needsActiveContainer(target: Constructor): boolean {
+    let needsActiveContainer = this.#needsActiveContainer?.get(target);
+    if (needsActiveContainer === undefined) {
+      needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
+      (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+    }
+    return needsActiveContainer;
+  }
+
+  instantiate(target: Constructor, deps: Array<unknown>, resolution?: AmbientResolution): unknown {
+    const invokable = target as ConstructorInvocation;
+    if (!this.needsActiveContainer(target)) {
+      return new invokable(...deps);
+    }
+    return runWithAmbientResolution(this.#container, resolution, () => new invokable(...deps));
+  }
+}