@codefast/di 0.5.0 → 0.6.1

package/src/{resolution → core}/binding-scope.ts

@@ -1,5 +1,5 @@
-import type { Binding } from "#/binding";
-import type { BindingScope } from "#/types";
+import type { Binding } from "#/core/binding";
+import type { BindingScope } from "#/core/types";
 
 /**
  * The scope a binding resolves under.

package/src/{binding.ts → core/binding.ts}

@@ -1,39 +1,43 @@
-import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/decorators/inject";
-import type { Token } from "#/token";
+import type { BindingTag, TagKeyMask } from "#/core/tag";
+import { NO_TAG_KEYS } from "#/core/tag";
+import type { Token } from "#/core/token";
 import type {
   ActivationHandler,
   BindingIdentifier,
   BindingScope,
-  BindingTag,
   Constructor,
   DeactivationHandler,
   ResolutionContext,
   ResolutionFrame,
-  ConstraintContext,
-} from "#/types";
+  BindingConstraint,
+} from "#/core/types";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/injection/descriptor";
 
-// ── BindingSlot ───────────────────────────────────────────────────────────────────
+// ── BindingSlot ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * The name-plus-tags coordinate a binding registers under and a request matches against.
+ *
  * @since 0.3.16-canary.0
  */
 export interface BindingSlot {
   readonly name: string | undefined;
   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.
+ *
  * @since 0.3.16-canary.0
  */
 export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolean {
-  if (left.name !== right.name) {
-    return false;
-  }
-  if (left.tags.length !== right.tags.length) {
+  if (left.name !== right.name || left.keyMask !== right.keyMask || left.tags.length !== right.tags.length) {
     return false;
   }
-  for (const [tagKey, tagValue] of left.tags) {
-    if (!right.tags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue))) {
+  for (const criterion of left.tags) {
+    if (!right.tags.includes(criterion)) {
       return false;
     }
   }
@@ -48,11 +52,19 @@ export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolea
 export const NO_INSTANCE: unique symbol = Symbol("di:no-instance");
 
 /**
+ * The slot every unconstrained binding shares.
+ *
+ * @remarks Tags are frozen where they are built (here and in the builder's re-tag), never per
+ * binding: frames and snapshots alias the array, so a caller's write throws instead of corrupting
+ * the registry.
+ *
  * @since 0.3.16-canary.0
  */
-export const DEFAULT_BINDING_SLOT = { name: undefined, tags: [] } satisfies BindingSlot;
+export const DEFAULT_BINDING_SLOT: BindingSlot = { name: undefined, tags: Object.freeze([]), keyMask: NO_TAG_KEYS };
 
 /**
+ * Formats a slot for diagnostics — `default`, or its `name:`/`tag:` parts.
+ *
  * @since 0.3.16-canary.0
  */
 export function bindingSlotToString(slot: BindingSlot): string {
@@ -63,13 +75,13 @@ export function bindingSlotToString(slot: BindingSlot): string {
   if (slot.name !== undefined) {
     parts.push(`name:${slot.name}`);
   }
-  for (const [tagKey, tagValue] of slot.tags) {
-    parts.push(`tag:${tagKey}=${String(tagValue)}`);
+  for (const criterion of slot.tags) {
+    parts.push(`tag:${criterion.key.name}=${String(criterion.value)}`);
   }
   return parts.join(",");
 }
 
-// ── BindingBase ───────────────────────────────────────────────────────────────
+// ── BindingBase ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
 interface BindingBase<Value> {
   readonly id: BindingIdentifier;
@@ -89,17 +101,17 @@ interface BindingBase<Value> {
    *
    * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
    */
-  frame?: ResolutionFrame | undefined;
+  frame: ResolutionFrame | undefined;
   /**
    * Cached singleton instance, or {@link NO_INSTANCE}.
    *
    * @remarks A binding belongs to exactly one container, so its singleton slot is per-binding —
    * a field read replaces a keyed lookup on the hottest resolve shape there is.
    */
-  instance?: unknown;
+  instance: unknown;
   readonly token: Token<Value> | Constructor<Value>;
   readonly slot: BindingSlot;
-  readonly predicate?: ((ctx: ConstraintContext) => boolean) | undefined;
+  readonly predicate?: BindingConstraint | undefined;
 }
 
 type BindingBaseKeys = keyof BindingBase<unknown>;
@@ -118,9 +130,11 @@ interface BindingLifecycleHooks<Value> {
   onDeactivation?(instance: Value): void | Promise<void>;
 }
 
-// ── Binding kinds ─────────────────────────────────────────────────────────────
+// ── Binding kinds ────────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
+ * A binding that instantiates a constructor.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ClassBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -130,6 +144,8 @@ export interface ClassBinding<Value> extends BindingBase<Value>, BindingLifecycl
 }
 
 /**
+ * A binding that computes its value with a synchronous factory.
+ *
  * @since 0.3.16-canary.0
  */
 export interface DynamicBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -139,6 +155,8 @@ export interface DynamicBinding<Value> extends BindingBase<Value>, BindingLifecy
 }
 
 /**
+ * A binding whose factory returns a promise of the value.
+ *
  * @since 0.3.16-canary.0
  */
 export interface DynamicAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -148,6 +166,8 @@ export interface DynamicAsyncBinding<Value> extends BindingBase<Value>, BindingL
 }
 
 /**
+ * A binding whose factory is called with its declared dependencies already resolved.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolvedBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -158,6 +178,8 @@ export interface ResolvedBinding<Value> extends BindingBase<Value>, BindingLifec
 }
 
 /**
+ * The async form of {@link ResolvedBinding} — the factory returns a promise.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ResolvedAsyncBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -168,6 +190,8 @@ export interface ResolvedAsyncBinding<Value> extends BindingBase<Value>, Binding
 }
 
 /**
+ * A binding that hands out one fixed value, so its scope is always `singleton`.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ConstantBinding<Value> extends BindingBase<Value>, BindingLifecycleHooks<Value> {
@@ -177,6 +201,8 @@ export interface ConstantBinding<Value> extends BindingBase<Value>, BindingLifec
 }
 
 /**
+ * A binding that defers to whatever binding its target token selects.
+ *
  * @since 0.3.16-canary.0
  */
 export interface AliasBinding<Value> extends BindingBase<Value> {
@@ -192,6 +218,8 @@ export interface AliasBinding<Value> extends BindingBase<Value> {
 }
 
 /**
+ * Every binding shape the engine resolves, discriminated by `kind`.
+ *
  * @since 0.3.16-canary.0
  */
 export type Binding<Value = unknown> =
@@ -203,35 +231,38 @@ export type Binding<Value = unknown> =
   | ConstantBinding<Value>
   | AliasBinding<Value>;
 
+/** `Omit` applied per union member, since a bare `Omit` would collapse the union into one shape. */
+type DistributiveOmit<Union, Keys extends PropertyKey> = Union extends unknown ? Omit<Union, Keys> : never;
+
 /**
  * Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied.
  *
+ * @remarks Derived rather than listed: a new binding kind joins this the moment it joins
+ * {@link Binding}, so the two unions cannot diverge.
+ *
  * @since 0.3.16-canary.0
  */
-export type PartialBinding<Value> =
-  | Omit<ClassBinding<Value>, BindingBaseKeys>
-  | Omit<DynamicBinding<Value>, BindingBaseKeys>
-  | Omit<DynamicAsyncBinding<Value>, BindingBaseKeys>
-  | Omit<ResolvedBinding<Value>, BindingBaseKeys>
-  | Omit<ResolvedAsyncBinding<Value>, BindingBaseKeys>
-  | Omit<ConstantBinding<Value>, BindingBaseKeys>
-  | Omit<AliasBinding<Value>, BindingBaseKeys>;
+export type PartialBinding<Value> = DistributiveOmit<Binding<Value>, BindingBaseKeys>;
 
-// ── ID generation ─────────────────────────────────────────────────────────────
+// ── ID generation ────────────────────────────────────────────────────────────────────────────────────────────────────
 
 let bindingIdCounter = 0;
 /**
+ * Returns a process-unique identifier for a new binding.
+ *
  * @since 0.3.16-canary.0
  */
 export function generateBindingId(): BindingIdentifier {
   return String(++bindingIdCounter) as BindingIdentifier;
 }
 
-// ── Construction ──────────────────────────────────────────────────────────────
+// ── Construction ─────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** Every key any member declares — a bare `keyof` on a union gives only the shared ones. */
+type KeysOfUnion<Union> = Union extends unknown ? keyof Union : never;
 
 // Superset of every kind's fields, so one literal can copy any binding shape.
-/** Union of every key any binding kind declares — `keyof` a union would give the intersection. */
-type BindingFieldName = Binding<unknown> extends infer Kind ? (Kind extends unknown ? keyof Kind : never) : never;
+type BindingFieldName = KeysOfUnion<Binding<unknown>>;
 
 /**
  * Completeness guard for {@link createBinding}'s literal.
@@ -256,9 +287,13 @@ type BindingFieldSuperset = {
 /**
  * The single construction site for bindings — one literal, one V8 hidden class.
  *
- * @see `ARCHITECTURE.md` — why the field order and the single site are load-bearing.
+ * @remarks Field order is fixed and this is the only construction site, so every binding shares one
+ * hidden class. Reordering the fields, or adding a second site, gives that up.
  *
  * @param source - the kind-specific payload, or an existing binding to re-slot
+ * @param token - the key requests resolve the binding by
+ * @param slot - the name + tags a request must match to select this binding
+ * @param predicate - a custom constraint, or `undefined` for none
  * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
  *
  * @since 0.5.0-canary.8
@@ -267,7 +302,7 @@ export function createBinding<Value>(
   source: PartialBinding<Value> | Binding<Value>,
   token: Token<Value> | Constructor<Value>,
   slot: BindingSlot,
-  predicate: ((ctx: ConstraintContext) => boolean) | undefined,
+  predicate: BindingConstraint | undefined,
   id: BindingIdentifier = generateBindingId(),
 ): Binding<Value> {
   const fields = source as BindingFieldSuperset;
@@ -276,7 +311,8 @@ export function createBinding<Value>(
     id,
     inFlight: false,
     frame: undefined,
-    instance: (source as { instance?: unknown }).instance ?? NO_INSTANCE,
+    // An `in` probe, not `??`: a re-slotted singleton may legitimately hold a cached `undefined`.
+    instance: "instance" in fields ? fields.instance : NO_INSTANCE,
     token,
     slot,
     predicate,
@@ -314,6 +350,16 @@ export function refinableFields<Value>(binding: Binding<Value>): RefinableBindin
   return binding as RefinableBindingFields<Value>;
 }
 
+/**
+ * Writable view of the memoized frame, which is a cache rather than part of a binding's identity.
+ *
+ * @remarks Named for the same reason as {@link RefinableBindingFields}: a write view stated once
+ * cannot drift from `Binding`, where an inline cast at each site can.
+ */
+interface MemoizedFrameField {
+  frame: ResolutionFrame | undefined;
+}
+
 /**
  * Drops the memoized resolution frame, for a refinement that changes what the frame reports.
  *
@@ -323,10 +369,10 @@ export function refinableFields<Value>(binding: Binding<Value>): RefinableBindin
  * @since 0.5.0-canary.9
  */
 export function clearBindingFrame<Value>(binding: Binding<Value>): void {
-  (binding as { frame: ResolutionFrame | undefined }).frame = undefined;
+  (binding as MemoizedFrameField).frame = undefined;
 }
 
-// ── Builder interfaces ────────────────────────────────────────────────────────
+// ── Builder interfaces ───────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * Common slot-constraint + id methods shared by all concrete binding builders.
@@ -334,14 +380,16 @@ export function clearBindingFrame<Value>(binding: Binding<Value>): void {
  * @since 0.3.16-canary.0
  */
 export interface SlotConstrainedBuilder {
-  when(predicate: (ctx: ConstraintContext) => boolean): this;
+  when(predicate: BindingConstraint): this;
   whenNamed(name: string): this;
-  whenTagged(tag: string, value: unknown): this;
+  whenTagged(criterion: BindingTag): this;
   whenDefault(): this;
   id(): BindingIdentifier;
 }
 
 /**
+ * The `to*` step of the fluent chain, choosing what a token resolves to.
+ *
  * @since 0.3.16-canary.0
  */
 export interface BindToBuilder<Value> {
@@ -362,6 +410,8 @@ export interface BindToBuilder<Value> {
 }
 
 /**
+ * The scope-selection step of the fluent chain.
+ *
  * @since 0.3.16-canary.0
  */
 export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
@@ -371,6 +421,8 @@ export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
 }
 
 /**
+ * The fluent chain for a constant — lifecycle hooks only, since the scope is fixed.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
@@ -379,11 +431,15 @@ export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
 }
 
 /**
+ * The fluent chain for an alias — slot constraints only, since scoping belongs to the target.
+ *
  * @since 0.3.16-canary.0
  */
 export interface AliasBindingBuilder extends SlotConstrainedBuilder {}
 
 /**
+ * The fluent chain after `singleton()`, where both lifecycle hooks stay available.
+ *
  * @since 0.3.16-canary.0
  */
 export interface SingletonBindingBuilder<Value> {
@@ -393,6 +449,8 @@ export interface SingletonBindingBuilder<Value> {
 }
 
 /**
+ * The fluent chain after `transient()`, where activation is the one lifecycle hook offered.
+ *
  * @since 0.3.16-canary.0
  */
 export interface TransientBindingBuilder<Value> {
@@ -401,11 +459,15 @@ export interface TransientBindingBuilder<Value> {
 }
 
 /**
+ * The fluent chain after `scoped()`, sharing the `transient()` surface.
+ *
  * @since 0.3.16-canary.0
  */
 export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {}
 
 /**
+ * The fluent chain a constant enters once a lifecycle hook is added.
+ *
  * @since 0.3.16-canary.0
  */
 export interface SingletonLifecycleBuilder<Value> {

package/src/core/constraint-requirement.ts

@@ -0,0 +1,94 @@
+/** What a constraint needs to exist before it can ever match, so `validate()` can check for it. */
+import type { BindingConstraint } from "#/core/types";
+
+/**
+ * Key the requirement is attached under.
+ *
+ * @remarks A symbol on the predicate rather than a field in the binding: resolution never reads it,
+ * so carrying it costs a resolve nothing.
+ *
+ * @since 0.6.0
+ */
+export const CONSTRAINT_REQUIREMENT: unique symbol = Symbol("di:constraint-requirement");
+
+/**
+ * The slot name a constraint waits for on an ancestor.
+ *
+ * @remarks Only names are described. A tag criterion is interned, so a typo cannot produce one that
+ * looks valid, while a name is a bare string that nothing checks.
+ *
+ * @since 0.6.0
+ */
+export interface ConstraintRequirement {
+  readonly requires: "ancestorSlotName";
+  readonly name: string;
+  /** The helper that built the predicate, so a report can name what the caller wrote. */
+  readonly helperName: string;
+}
+
+/**
+ * Records what a predicate waits for. Called once, where the predicate is built.
+ *
+ * @since 0.6.0
+ */
+export function requiringAncestorSlotName(
+  predicate: BindingConstraint,
+  name: string,
+  helperName: string,
+): BindingConstraint {
+  const requirement: ConstraintRequirement = { requires: "ancestorSlotName", name, helperName };
+  Object.defineProperty(predicate, CONSTRAINT_REQUIREMENT, { value: requirement, enumerable: false });
+  return predicate;
+}
+
+/**
+ * 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 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/{constructor-type.ts → core/constructor-type.ts}

@@ -6,7 +6,7 @@
  *
  * @since 0.3.16-canary.0
  */
-export type Constructor<Value = unknown> = new (...args: Array<never>) => Value;
+export type Constructor<out Value = unknown> = new (...args: Array<never>) => Value;
 
 /**
  * Class constructor as invoked by the resolver after metadata-driven

package/src/{module.ts → core/module.ts}

@@ -1,8 +1,8 @@
-import type { BindToBuilder } from "#/binding";
-import type { Token } from "#/token";
-import type { Constructor } from "#/types";
+import type { BindToBuilder } from "#/core/binding";
+import type { Token } from "#/core/token";
+import type { Constructor } from "#/core/types";
 
-// ── Branded types (runtime symbols for branding) ─────────────────────────────
+// ── Branded types (runtime symbols for branding) ─────────────────────────────────────────────────────────────────────
 
 const SYNC_MODULE_BRAND: unique symbol = Symbol("di:sync-module");
 const ASYNC_MODULE_BRAND: unique symbol = Symbol("di:async-module");
@@ -33,13 +33,13 @@ export interface AsyncModule {
   readonly [MODULE_SETUP]: (builder: AsyncModuleBuilder) => Promise<void>;
 }
 
-// ── Builder interfaces ────────────────────────────────────────────────────────
+// ── Builder interfaces ───────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
  */
 export interface ModuleBuilder {
-  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
   import(...modules: Array<SyncModule>): void;
 }
 
@@ -47,11 +47,11 @@ export interface ModuleBuilder {
  * @since 0.3.16-canary.0
  */
 export interface AsyncModuleBuilder {
-  bind<const Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
+  bind<Value>(token: Token<Value> | Constructor<Value>): BindToBuilder<Value>;
   import(...modules: Array<SyncModule | AsyncModule>): void;
 }
 
-// ── Static factories ──────────────────────────────────────────────────────────
+// ── Static factories ─────────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -79,7 +79,7 @@ export const AsyncModule = {
   },
 };
 
-// ── Module — unified API ──────────────────────────────────────────────────────
+// ── Module — unified API ─────────────────────────────────────────────────────────────────────────────────────────────
 
 /**
  * @since 0.3.16-canary.0
@@ -97,5 +97,5 @@ export const Module = {
  * @since 0.3.16-canary.0
  */
 export function isSyncModule(module: SyncModule | AsyncModule): module is SyncModule {
-  return (module as SyncModule)[SYNC_MODULE_BRAND];
+  return (module as Partial<SyncModule>)[SYNC_MODULE_BRAND] === true;
 }