@codefast/di 0.5.0-canary.5 → 0.5.0-canary.7

package/src/registry.ts

@@ -3,83 +3,136 @@ import { bindingSlotEquals, bindingSlotToString } from "#/binding";
 import type { Token } from "#/token";
 import type { BindingIdentifier, Constructor, DependencyKey } from "#/types";
 
+// Superset of every binding kind's fields, used to normalize hidden classes below.
+type BindingFieldSuperset = Binding & {
+  readonly scope?: unknown;
+  readonly target?: unknown;
+  readonly factory?: unknown;
+  readonly deps?: unknown;
+  readonly value?: unknown;
+  readonly onActivation?: unknown;
+  readonly onDeactivation?: unknown;
+};
+
+/**
+ * Rebuilds a binding with every kind's fields in one fixed key order, so all stored
+ * bindings share a single V8 hidden class. Mixed binding kinds otherwise turn the
+ * resolver's hot property reads (kind/scope/factory/...) megamorphic, which costs
+ * ~30% throughput in processes that exercise many kinds. The value-erasing cast is
+ * safe: every declared field is copied verbatim and `kind` stays the discriminant.
+ */
+function normalizeBindingShape(binding: Binding): Binding {
+  const source = binding as BindingFieldSuperset;
+  return {
+    kind: source.kind,
+    id: source.id,
+    inFlight: false,
+    frame: undefined,
+    token: source.token,
+    slot: source.slot,
+    predicate: source.predicate,
+    scope: source.scope,
+    target: source.target,
+    factory: source.factory,
+    deps: source.deps,
+    value: source.value,
+    onActivation: source.onActivation,
+    onDeactivation: source.onDeactivation,
+  } as Binding;
+}
+
 /**
  * @since 0.3.16-canary.0
  */
 export class BindingRegistry {
+  // Monotonic mutation counter — lets resolvers version-stamp lookup caches across a container chain.
+  #version = 0;
   // Map from token key -> array of bindings (order matters for last-wins)
-  private readonly _bindings = new Map<DependencyKey, Array<Binding>>();
+  readonly #bindings = new Map<DependencyKey, Array<Binding>>();
   // Fast lookup by binding ID
-  private readonly _byId = new Map<BindingIdentifier, Binding>();
+  readonly #byId = new Map<BindingIdentifier, Binding>();
   // Fast lookup for slot { name, tags: [] }
-  private readonly _simpleNamed = new Map<DependencyKey, Map<string, Binding>>();
+  readonly #simpleNamed = new Map<DependencyKey, Map<string, Binding>>();
   // Fast path for one default slot binding with no predicate
-  private readonly _fastDefault = new Map<DependencyKey, Binding>();
+  readonly #fastDefault = new Map<DependencyKey, Binding>();
   // Fast lookup for slot { name: undefined, tags: [[key, value]] } with no predicate
-  private readonly _simpleTagged = new Map<DependencyKey, Map<string, Map<unknown, Binding>>>();
+  readonly #simpleTagged = new Map<DependencyKey, Map<string, Map<unknown, Binding>>>();
+
+  /** Monotonic version — increments on every mutation. */
+  get version(): number {
+    return this.#version;
+  }
 
-  /** Add or replace binding using slot-aware last-wins. */
-  add(binding: Binding): void {
+  /** Add or replace binding using slot-aware last-wins. Returns the displaced binding, if any. */
+  add(uncommittedBinding: Binding): Binding | undefined {
+    this.#version += 1;
+    const binding = normalizeBindingShape(uncommittedBinding);
     const key = binding.token as DependencyKey;
     // ✓ TS6.0: Map.getOrInsert (ES2025) replaces the manual get+check+set upsert
-    const bindingsForToken = this._bindings.getOrInsert(key, []);
+    const bindingsForToken = this.#bindings.getOrInsert(key, []);
 
     // Only apply last-wins for slot-based bindings (not predicate-only)
-    if (!this._isPurePredicateBinding(binding)) {
+    let displacedBinding: Binding | undefined;
+    if (!this.#isPurePredicateBinding(binding)) {
       const existingIndex = bindingsForToken.findIndex(
-        (candidate) => !this._isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
+        (candidate) => !this.#isPurePredicateBinding(candidate) && bindingSlotEquals(candidate.slot, binding.slot),
       );
       if (existingIndex !== -1) {
-        const replacedBinding = bindingsForToken[existingIndex]!;
-        this._byId.delete(replacedBinding.id);
+        displacedBinding = bindingsForToken[existingIndex]!;
+        this.#byId.delete(displacedBinding.id);
         bindingsForToken.splice(existingIndex, 1);
+        this.#deindexSimpleNamedBinding(key, displacedBinding);
+        this.#deindexSimpleTaggedBinding(key, displacedBinding);
       }
     }
 
     bindingsForToken.push(binding);
-    this._byId.set(binding.id, binding);
-    this._indexSimpleNamedBinding(key, binding);
-    this._indexSimpleTaggedBinding(key, binding);
-    this._refreshFastDefaultForToken(key);
+    this.#byId.set(binding.id, binding);
+    this.#indexSimpleNamedBinding(key, binding);
+    this.#indexSimpleTaggedBinding(key, binding);
+    this.#refreshFastDefaultForToken(key);
+    return displacedBinding;
   }
 
   /** Remove all bindings for a token. Returns removed bindings. */
   removeByToken(token: Token<unknown> | Constructor): Array<Binding> {
+    this.#version += 1;
     const key = token as DependencyKey;
-    const bindingsForToken = this._bindings.get(key) ?? [];
-    this._bindings.delete(key);
-    this._simpleNamed.delete(key);
-    this._simpleTagged.delete(key);
-    this._fastDefault.delete(key);
+    const bindingsForToken = this.#bindings.get(key) ?? [];
+    this.#bindings.delete(key);
+    this.#simpleNamed.delete(key);
+    this.#simpleTagged.delete(key);
+    this.#fastDefault.delete(key);
     for (const binding of bindingsForToken) {
-      this._byId.delete(binding.id);
+      this.#byId.delete(binding.id);
     }
     return bindingsForToken;
   }
 
   /** Remove a specific binding by ID. Returns the removed binding or undefined. */
   removeById(id: BindingIdentifier): Binding | undefined {
-    const binding = this._byId.get(id);
+    const binding = this.#byId.get(id);
     if (binding === undefined) {
       return undefined;
     }
-    this._byId.delete(id);
+    this.#version += 1;
+    this.#byId.delete(id);
     const key = binding.token as DependencyKey;
-    const bindingsForToken = this._bindings.get(key);
+    const bindingsForToken = this.#bindings.get(key);
     if (bindingsForToken !== undefined) {
       const bindingIndex = bindingsForToken.findIndex((candidate) => candidate.id === id);
       if (bindingIndex !== -1) {
         bindingsForToken.splice(bindingIndex, 1);
       }
-      this._deindexSimpleNamedBinding(key, binding);
-      this._deindexSimpleTaggedBinding(key, binding);
+      this.#deindexSimpleNamedBinding(key, binding);
+      this.#deindexSimpleTaggedBinding(key, binding);
       if (bindingsForToken.length === 0) {
-        this._bindings.delete(key);
-        this._simpleNamed.delete(key);
-        this._simpleTagged.delete(key);
-        this._fastDefault.delete(key);
+        this.#bindings.delete(key);
+        this.#simpleNamed.delete(key);
+        this.#simpleTagged.delete(key);
+        this.#fastDefault.delete(key);
       } else {
-        this._refreshFastDefaultForToken(key);
+        this.#refreshFastDefaultForToken(key);
       }
     }
     return binding;
@@ -87,25 +140,25 @@ export class BindingRegistry {
 
   /** Get all bindings for a token. */
   getAll(token: Token<unknown> | Constructor): ReadonlyArray<Binding> {
-    return this._bindings.get(token as DependencyKey) ?? [];
+    return this.#bindings.get(token as DependencyKey) ?? [];
   }
 
   /** Get binding by ID. */
   getById(id: BindingIdentifier): Binding | undefined {
-    return this._byId.get(id);
+    return this.#byId.get(id);
   }
 
   /** Check if any binding exists for token. */
   has(token: Token<unknown> | Constructor): boolean {
     const key = token as DependencyKey;
-    const list = this._bindings.get(key);
+    const list = this.#bindings.get(key);
     return list !== undefined && list.length > 0;
   }
 
   /** All bindings in the registry. */
   allBindings(): ReadonlyArray<Binding> {
     const allBindings: Array<Binding> = [];
-    for (const bindingsForToken of this._bindings.values()) {
+    for (const bindingsForToken of this.#bindings.values()) {
       allBindings.push(...bindingsForToken);
     }
     return allBindings;
@@ -113,54 +166,55 @@ export class BindingRegistry {
 
   /** Remove all bindings. Returns all removed. */
   clear(): ReadonlyArray<Binding> {
+    this.#version += 1;
     const all = this.allBindings();
-    this._bindings.clear();
-    this._byId.clear();
-    this._simpleNamed.clear();
-    this._simpleTagged.clear();
-    this._fastDefault.clear();
+    this.#bindings.clear();
+    this.#byId.clear();
+    this.#simpleNamed.clear();
+    this.#simpleTagged.clear();
+    this.#fastDefault.clear();
     return all;
   }
 
   getSimpleNamed(token: Token<unknown> | Constructor, name: string): Binding | undefined {
-    return this._simpleNamed.get(token as DependencyKey)?.get(name);
+    return this.#simpleNamed.get(token as DependencyKey)?.get(name);
   }
 
   getSimpleTagged(token: Token<unknown> | Constructor, tagKey: string, tagValue: unknown): Binding | undefined {
-    return this._simpleTagged
+    return this.#simpleTagged
       .get(token as DependencyKey)
       ?.get(tagKey)
       ?.get(tagValue);
   }
 
   getFastDefault(token: Token<unknown> | Constructor): Binding | undefined {
-    return this._fastDefault.get(token as DependencyKey);
+    return this.#fastDefault.get(token as DependencyKey);
   }
 
   /** Summarize available slot strings for a token (for error messages). */
   availableSlotStrings(token: Token<unknown> | Constructor): Array<string> {
-    const bindingsForToken = this._bindings.get(token as DependencyKey) ?? [];
+    const bindingsForToken = this.#bindings.get(token as DependencyKey) ?? [];
     return bindingsForToken.map((binding) => bindingSlotToString(binding.slot));
   }
 
-  private _indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #indexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
       return;
     }
     const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this._simpleTagged.getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
+    const byTagKey = this.#simpleTagged.getOrInsert(tokenKey, new Map<string, Map<unknown, Binding>>());
     const byTagValue = byTagKey.getOrInsert(tagKey, new Map<unknown, Binding>());
     byTagValue.set(tagValue, binding);
   }
 
-  private _deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #deindexSimpleTaggedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name !== undefined || slot.tags.length !== 1 || binding.predicate !== undefined) {
       return;
     }
     const [tagKey, tagValue] = slot.tags[0]!;
-    const byTagKey = this._simpleTagged.get(tokenKey);
+    const byTagKey = this.#simpleTagged.get(tokenKey);
     if (byTagKey === undefined) {
       return;
     }
@@ -174,13 +228,13 @@ export class BindingRegistry {
       if (byTagValue.size === 0) {
         byTagKey.delete(tagKey);
         if (byTagKey.size === 0) {
-          this._simpleTagged.delete(tokenKey);
+          this.#simpleTagged.delete(tokenKey);
         }
       }
     }
   }
 
-  private _isPurePredicateBinding(binding: Binding): boolean {
+  #isPurePredicateBinding(binding: Binding): boolean {
     const slot = binding.slot;
     const hasPredicate = binding.predicate !== undefined;
     const hasConstraint = slot.name !== undefined || slot.tags.length > 0;
@@ -188,21 +242,21 @@ export class BindingRegistry {
     return hasPredicate && !hasConstraint;
   }
 
-  private _indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #indexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name === undefined || slot.tags.length > 0) {
       return;
     }
-    const bindingsByName = this._simpleNamed.getOrInsert(tokenKey, new Map<string, Binding>());
+    const bindingsByName = this.#simpleNamed.getOrInsert(tokenKey, new Map<string, Binding>());
     bindingsByName.set(slot.name, binding);
   }
 
-  private _deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
+  #deindexSimpleNamedBinding(tokenKey: DependencyKey, binding: Binding): void {
     const slot = binding.slot;
     if (slot.name === undefined || slot.tags.length > 0) {
       return;
     }
-    const bindingsByName = this._simpleNamed.get(tokenKey);
+    const bindingsByName = this.#simpleNamed.get(tokenKey);
     if (bindingsByName === undefined) {
       return;
     }
@@ -210,23 +264,23 @@ export class BindingRegistry {
     if (currentBinding?.id === binding.id) {
       bindingsByName.delete(slot.name);
       if (bindingsByName.size === 0) {
-        this._simpleNamed.delete(tokenKey);
+        this.#simpleNamed.delete(tokenKey);
       }
     }
   }
 
-  private _refreshFastDefaultForToken(tokenKey: DependencyKey): void {
-    const bindingsForToken = this._bindings.get(tokenKey);
+  #refreshFastDefaultForToken(tokenKey: DependencyKey): void {
+    const bindingsForToken = this.#bindings.get(tokenKey);
     if (bindingsForToken === undefined || bindingsForToken.length !== 1) {
-      this._fastDefault.delete(tokenKey);
+      this.#fastDefault.delete(tokenKey);
       return;
     }
     const onlyBinding = bindingsForToken[0]!;
     const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
     if (!isDefaultSlot || onlyBinding.predicate !== undefined) {
-      this._fastDefault.delete(tokenKey);
+      this.#fastDefault.delete(tokenKey);
       return;
     }
-    this._fastDefault.set(tokenKey, onlyBinding);
+    this.#fastDefault.set(tokenKey, onlyBinding);
   }
 }

package/src/{binding-select.ts → resolution/binding-select.ts}

@@ -21,9 +21,22 @@ export function selectBinding(
   if (candidates.length === 1) {
     return candidates[0];
   }
-  // Multiple candidates — check if any is unambiguous (slot-based selection)
-  // Slot-based bindings already have last-wins applied in registry, so
-  // multiple candidates here means ambiguous predicate-only bindings
+  // Most specific wins: a single matching predicate-carrying candidate beats
+  // predicate-less ones (a predicate is a deliberate specialization of the
+  // default). Two matching predicates are genuinely ambiguous.
+  let predicatedCandidate: Binding | undefined;
+  for (const candidate of candidates) {
+    if (candidate.predicate !== undefined) {
+      if (predicatedCandidate !== undefined) {
+        predicatedCandidate = undefined;
+        break;
+      }
+      predicatedCandidate = candidate;
+    }
+  }
+  if (predicatedCandidate !== undefined) {
+    return predicatedCandidate;
+  }
   throw new AmbiguousBindingError(
     tokenDisplayName,
     candidates.map((c) => c.id),

package/src/{environment.ts → resolution/environment.ts}

@@ -1,4 +1,4 @@
-import type { Container } from "#/container";
+import type { Container } from "#/container/container";
 import type { Token } from "#/token";
 import type {
   BindingIdentifier,
@@ -13,18 +13,18 @@ import type {
 
 // ── Active container ──────────────────────────────────────────────────────────
 
-let _activeContainer: Container | undefined;
+let activeContainer: Container | undefined;
 
 /**
  * @since 0.3.16-canary.0
  */
 export function runWithContainer<Result>(container: Container, fn: () => Result): Result {
-  const prev = _activeContainer;
-  _activeContainer = container;
+  const prev = activeContainer;
+  activeContainer = container;
   try {
     return fn();
   } finally {
-    _activeContainer = prev;
+    activeContainer = prev;
   }
 }
 
@@ -32,7 +32,7 @@ export function runWithContainer<Result>(container: Container, fn: () => Result)
  * @since 0.3.16-canary.0
  */
 export function getActiveContainer(): Container | undefined {
-  return _activeContainer;
+  return activeContainer;
 }
 
 // ── ResolutionContext implementation ──────────────────────────────────────────
@@ -93,10 +93,10 @@ export interface ResolverCallbacks {
  * @since 0.3.16-canary.0
  */
 export class DefaultResolutionContext implements ResolutionContext {
-  private _resolver: ResolverCallbacks;
-  private _resolutionPath: Array<string>;
-  private _resolutionStack: Array<ResolutionFrame>;
-  private _currentOptions: ResolveOptions | undefined;
+  #resolver: ResolverCallbacks;
+  #resolutionPath: Array<string>;
+  #resolutionStack: Array<ResolutionFrame>;
+  #currentOptions: ResolveOptions | undefined;
 
   constructor(
     resolver: ResolverCallbacks,
@@ -104,19 +104,19 @@ export class DefaultResolutionContext implements ResolutionContext {
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ) {
-    this._resolver = resolver;
-    this._resolutionPath = resolutionPath;
-    this._resolutionStack = resolutionStack;
-    this._currentOptions = currentOptions;
+    this.#resolver = resolver;
+    this.#resolutionPath = resolutionPath;
+    this.#resolutionStack = resolutionStack;
+    this.#currentOptions = currentOptions;
   }
 
-  private _graph: ConstraintContext | undefined;
+  #graph: ConstraintContext | undefined;
 
   get graph(): ConstraintContext {
-    if (this._graph === undefined) {
-      this._graph = new DefaultConstraintContext(this._resolutionPath, this._resolutionStack, this._currentOptions);
+    if (this.#graph === undefined) {
+      this.#graph = new DefaultConstraintContext(this.#resolutionPath, this.#resolutionStack, this.#currentOptions);
     }
-    return this._graph;
+    return this.#graph;
   }
 
   reset(
@@ -125,47 +125,47 @@ export class DefaultResolutionContext implements ResolutionContext {
     resolutionStack: Array<ResolutionFrame>,
     currentOptions: ResolveOptions | undefined,
   ): void {
-    this._resolver = resolver;
-    this._resolutionPath = resolutionPath;
-    this._resolutionStack = resolutionStack;
-    this._currentOptions = currentOptions;
-    this._graph = undefined;
+    this.#resolver = resolver;
+    this.#resolutionPath = resolutionPath;
+    this.#resolutionStack = resolutionStack;
+    this.#currentOptions = currentOptions;
+    this.#graph = undefined;
   }
 
   resolve<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
     if (options === undefined) {
-      return this._resolver.resolveFromContext(token, this._resolutionPath, this._resolutionStack);
+      return this.#resolver.resolveFromContext(token, this.#resolutionPath, this.#resolutionStack);
     }
-    return this._resolver.resolve(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolve(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
     if (options === undefined) {
-      return this._resolver.resolveAsyncFromContext(token, this._resolutionPath, this._resolutionStack);
+      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionPath, this.#resolutionStack);
     }
-    return this._resolver.resolveAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this._resolver.resolveOptional(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveOptional(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveOptionalAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Value | undefined> {
-    return this._resolver.resolveOptionalAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAll<const Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this._resolver.resolveAll(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAll(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 
   resolveAllAsync<const Value>(
     token: Token<Value> | Constructor<Value>,
     options?: ResolveOptions,
   ): Promise<Array<Value>> {
-    return this._resolver.resolveAllAsync(token, options, this._resolutionPath, this._resolutionStack);
+    return this.#resolver.resolveAllAsync(token, options, this.#resolutionPath, this.#resolutionStack);
   }
 }
 
@@ -186,13 +186,13 @@ class DefaultConstraintContext implements ConstraintContext {
     this.currentResolveOptions = currentResolveOptions;
   }
 
-  private _ancestors: ReadonlyArray<ResolutionFrame> | undefined;
+  #ancestors: ReadonlyArray<ResolutionFrame> | undefined;
 
   get ancestors(): ReadonlyArray<ResolutionFrame> {
-    if (this._ancestors === undefined) {
-      this._ancestors = this.resolutionStack.length > 1 ? this.resolutionStack.slice(0, -1) : [];
+    if (this.#ancestors === undefined) {
+      this.#ancestors = this.resolutionStack.length > 1 ? this.resolutionStack.slice(0, -1) : [];
     }
-    return this._ancestors;
+    return this.#ancestors;
   }
 }