@codefast/di 0.6.0 → 0.6.2

package/src/container/container.ts

@@ -3,7 +3,7 @@ import { BindingChain } from "#/container/binding-builders";
 import type { Binding, BindingBuilder, BindToBuilder, ConstantBinding } from "#/core/binding";
 import { NO_INSTANCE } from "#/core/binding";
 import { effectiveBindingScope } from "#/core/binding-scope";
-import { constraintRequirementOf } from "#/core/constraint-requirement";
+import { constraintRequirementsOf } from "#/core/constraint-requirement";
 import type { AsyncModule, AsyncModuleBuilder, ModuleBuilder, SyncModule } from "#/core/module";
 import { isSyncModule, MODULE_SETUP } from "#/core/module";
 import { BindingRegistry } from "#/core/registry";
@@ -731,13 +731,15 @@ class DefaultContainer implements Container {
       if (predicate === undefined) {
         continue;
       }
-      const requirement = constraintRequirementOf(predicate);
-      if (requirement === undefined) {
+      const requirements = constraintRequirementsOf(predicate);
+      if (requirements.length === 0) {
         continue;
       }
       declaredSlotNames ??= this.#slotNamesInChain();
-      if (!declaredSlotNames.has(requirement.name)) {
-        throw new UnreachableConstraintError(tokenName(binding.token), requirement.name, requirement.helperName);
+      for (const requirement of requirements) {
+        if (!declaredSlotNames.has(requirement.name)) {
+          throw new UnreachableConstraintError(tokenName(binding.token), requirement.name, requirement.helperName);
+        }
       }
     }
   }

package/src/core/constraint-requirement.ts

@@ -44,8 +44,51 @@ export function requiringAncestorSlotName(
 /**
  * The requirement a predicate carries, if it was built by a helper that records one.
  *
+ * @remarks A composed predicate may carry several; this answers the first. `validate()` reads
+ * {@link constraintRequirementsOf} so no recorded requirement is skipped.
+ *
  * @since 0.6.0
  */
 export function constraintRequirementOf(predicate: BindingConstraint): ConstraintRequirement | undefined {
-  return (predicate as { [CONSTRAINT_REQUIREMENT]?: ConstraintRequirement })[CONSTRAINT_REQUIREMENT];
+  return constraintRequirementsOf(predicate)[0];
+}
+
+const NO_REQUIREMENTS: ReadonlyArray<ConstraintRequirement> = [];
+
+/**
+ * Every requirement a predicate carries — one from a helper, several from a composed chain.
+ *
+ * @since 0.6.1
+ */
+export function constraintRequirementsOf(predicate: BindingConstraint): ReadonlyArray<ConstraintRequirement> {
+  const payload = (
+    predicate as { [CONSTRAINT_REQUIREMENT]?: ConstraintRequirement | ReadonlyArray<ConstraintRequirement> }
+  )[CONSTRAINT_REQUIREMENT];
+  if (payload === undefined) {
+    return NO_REQUIREMENTS;
+  }
+  return Array.isArray(payload)
+    ? (payload as ReadonlyArray<ConstraintRequirement>)
+    : [payload as ConstraintRequirement];
+}
+
+/**
+ * Carries both sides' requirements onto a composed predicate, so chaining does not lose them.
+ *
+ * @since 0.6.1
+ */
+export function mergingConstraintRequirements(
+  composite: BindingConstraint,
+  left: BindingConstraint,
+  right: BindingConstraint,
+): BindingConstraint {
+  const merged = [...constraintRequirementsOf(left), ...constraintRequirementsOf(right)];
+  if (merged.length === 0) {
+    return composite;
+  }
+  Object.defineProperty(composite, CONSTRAINT_REQUIREMENT, {
+    value: merged.length === 1 ? merged[0] : merged,
+    enumerable: false,
+  });
+  return composite;
 }

package/src/core/tag.ts

@@ -95,22 +95,36 @@ export function tag<Value = unknown>(name: string): TagKey<Value> {
   const id = tagKeyCounter;
   const mask = (1 << (id % MASK_WIDTH)) as TagKeyMask;
   const interned = new Map<unknown, BindingTag<Value>>();
+  // One-entry cache in front of the intern map: an inline `.of()` at a call site usually repeats
+  // one value, and `Object.is` is the slot contract's own comparison, so a hit is exact — ±0 stay
+  // split and `NaN` hits itself, with no `internKeyFor` detour.
+  let lastValue: Value | undefined;
+  let lastPair: BindingTag<Value> | undefined;
 
   const key: TagKey<Value> = {
     name,
     id,
     mask,
     of(value: Value): BindingTag<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;
       }
 
       const pair = { key, value, mask } as BindingTag<Value>;
 
       interned.set(cacheKey, pair);
+      lastValue = value;
+      lastPair = pair;
 
       return pair;
     },

package/src/decorators/injectable.ts

@@ -60,16 +60,27 @@ export function injectable(): (target: unknown, context: ClassDecoratorContext)
 
 /**
  * @remarks Declaring dependencies constrains the class: the decorator only accepts one whose
- * constructor takes exactly what `deps` resolve to, in that order. A class taking fewer parameters
- * than `deps` declares still satisfies it, which is the one mismatch TypeScript's arity rules let
- * through — the surplus dependency is resolved and discarded.
+ * constructor takes exactly what `deps` resolve to, in that order — including arity, so a literal
+ * deps list longer than the constructor is a compile error rather than a resolved-and-discarded
+ * value. Optional trailing parameters admit every arity they declare, and a rest parameter admits
+ * any list. A deps *array* — one whose length the compiler cannot know — skips the arity check,
+ * which is also the deliberate spelling for declaring more dependencies than the constructor
+ * takes, e.g. for the dependency graph's edges.
  *
  * @since 0.3.16-canary.0
  */
 export function injectable<const Deps extends ReadonlyArray<InjectableDependency>>(
   deps: Deps,
   options?: InjectableOptions,
-): (target: abstract new (...args: InjectedParameters<Deps>) => unknown, context: ClassDecoratorContext) => void;
+): <Target extends abstract new (...args: InjectedParameters<Deps>) => unknown>(
+  target: Target &
+    (number extends Deps["length"]
+      ? unknown
+      : Deps["length"] extends ConstructorParameters<Target>["length"]
+        ? unknown
+        : never),
+  context: ClassDecoratorContext,
+) => void;
 
 /**
  * @since 0.6.0

package/src/resolution/cache/binding-lookup-cache.ts

@@ -6,6 +6,7 @@
  */
 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";
 
@@ -34,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
  */
@@ -47,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;
@@ -105,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) {
@@ -146,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/plan/instantiation-plan.ts

@@ -124,6 +124,16 @@ export interface InstantiationPlanHost {
     token: Token<unknown> | Constructor,
     options: ResolveOptions & { name: string },
   ): InstantiationPlanDependencyEntry | null;
+  /**
+   * The named lookup's single-tag twin, or `null` under the same rule.
+   *
+   * @remarks Optional so a host predating it stays a valid host — a compiler given none simply
+   * escapes the dependency, which is exactly the pre-settlement behavior.
+   */
+  lookupPathIndependentTaggedEntry?(
+    token: Token<unknown> | Constructor,
+    options: ResolveOptions,
+  ): InstantiationPlanDependencyEntry | null;
   /** The frame the interpreted path pushes for this binding, so escapes can replay it. */
   getResolutionFrame(binding: Binding): ResolutionFrame;
   /** Runtime resolve for an escaped dependency, seeded with the ancestor frames above it. */
@@ -169,8 +179,10 @@ export class InstantiationPlanCompiler {
   /**
    * Re-entry into the runtime resolver for a dependency the plan can't see through.
    *
-   * The ancestors are fixed at compile time, so the seeds are built once; each call copies
-   * them because the resolver pushes and pops on the arrays it is given.
+   * The ancestors are fixed at compile time, so the seed is built once and lent per call — the
+   * root-stack rule one level down: every sync lane pops what it pushes, so the owned array still
+   * holds exactly the seed when a call returns. A reentrant call finds it claimed and mints its
+   * own copy; a return that did not restore the length hands nothing back, so the next call mints.
    */
   #compileEscapeThunk(
     token: Token<unknown> | Constructor,
@@ -180,7 +192,19 @@ export class InstantiationPlanCompiler {
   ): () => unknown {
     const host = this.#host;
     const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
-    return () => host.resolveEscaped(token, options, arity, [...frames]);
+    const depth = frames.length;
+    let owned: Array<ResolutionFrame> | undefined = [...frames];
+    return () => {
+      const stack = owned ?? [...frames];
+      owned = undefined;
+      try {
+        return host.resolveEscaped(token, options, arity, stack);
+      } finally {
+        if (stack.length === depth) {
+          owned = stack;
+        }
+      }
+    };
   }
 
   // A resolved binding declares its deps as explicit descriptors — same rules as
@@ -246,6 +270,12 @@ export class InstantiationPlanCompiler {
         if (named !== null) {
           return this.#compileDepThunk(named, compileStack, depth, ancestors, options);
         }
+      } else {
+        // The host owns the whole single-tag decision, including whether the options qualify.
+        const tagged = this.#host.lookupPathIndependentTaggedEntry?.(token, options);
+        if (tagged !== null && tagged !== undefined) {
+          return this.#compileDepThunk(tagged, compileStack, depth, ancestors, options);
+        }
       }
       return this.#compileEscapeThunk(token, ancestors, "single", options);
     }
@@ -514,6 +544,12 @@ export class InstantiationPlanCompiler {
         if (named !== null) {
           return this.#compileAsyncDepThunk(named, compileStack, depth, ancestors, options);
         }
+      } else {
+        // The host owns the whole single-tag decision, including whether the options qualify.
+        const tagged = this.#host.lookupPathIndependentTaggedEntry?.(token, options);
+        if (tagged !== null && tagged !== undefined) {
+          return this.#compileAsyncDepThunk(tagged, compileStack, depth, ancestors, options);
+        }
       }
       return this.#compileAsyncEscapeThunk(token, ancestors, "single", options);
     }

package/src/resolution/resolver.ts

@@ -436,6 +436,18 @@ export class DependencyResolver implements ResolverCallbacks {
       }
       return { binding: entry.binding };
     },
+    // The named rule verbatim, on the single-tag lane's memo.
+    lookupPathIndependentTaggedEntry: (token, options) => {
+      const singleTag = singleTagOnlyOf(options);
+      if (singleTag === undefined) {
+        return null;
+      }
+      const entry = this.#lookup.taggedEntry(token, singleTag);
+      if (entry === null || entry.binding.predicate !== undefined || !matchesSlot(entry.binding.slot, options)) {
+        return null;
+      }
+      return { binding: entry.binding };
+    },
     getResolutionFrame: (binding) => this.#getResolutionFrame(binding),
     // Dispatches exactly as #resolveDep does, so an escaped dep is indistinguishable
     // from the same dep on a fully interpreted resolve.
@@ -509,6 +521,22 @@ export class DependencyResolver implements ResolverCallbacks {
         }
         // Everything else keeps the full path (context, activation, guards).
       }
+    } else if (options !== undefined) {
+      // Single-tag fast lane: the named lane's tagged twin, memoizing the chain walk.
+      const singleTag = singleTagOnlyOf(options);
+      if (singleTag !== undefined) {
+        const taggedEntry = this.#lookup.taggedEntry(token, singleTag);
+        if (taggedEntry !== null) {
+          const taggedBinding = taggedEntry.binding;
+          if (taggedEntry.owner.#isPlainConstant(taggedBinding)) {
+            return taggedBinding.value as Value;
+          }
+          if (taggedBinding.scope === "singleton" && taggedBinding.instance !== NO_INSTANCE) {
+            return taggedBinding.instance as Value;
+          }
+          // Everything else keeps the full path (context, activation, guards).
+        }
+      }
     }
 
     const { binding, owner } = this.#requireBinding(token, options, resolutionStack);