@codefast/di 0.5.0-canary.6 → 0.5.0-canary.8

package/src/binding.ts

@@ -1,4 +1,4 @@
-import type { InjectionDescriptor } from "#/decorators/inject";
+import type { InjectableDependency, InjectionDescriptor, ResolvedDependencyValue } from "#/decorators/inject";
 import type { Token } from "#/token";
 import type {
   ActivationHandler,
@@ -7,9 +7,8 @@ import type {
   BindingTag,
   Constructor,
   DeactivationHandler,
-  DependencyKey,
   ResolutionContext,
-  TokenValue,
+  ResolutionFrame,
   ConstraintContext,
 } from "#/types";
 
@@ -41,6 +40,13 @@ export function bindingSlotEquals(left: BindingSlot, right: BindingSlot): boolea
   return true;
 }
 
+/**
+ * Cached singleton absent — distinguishes "not resolved yet" from a cached `undefined`.
+ *
+ * @since 0.5.0-canary.8
+ */
+export const NO_INSTANCE: unique symbol = Symbol("di:no-instance");
+
 /**
  * @since 0.3.16-canary.0
  */
@@ -67,9 +73,31 @@ export function bindingSlotToString(slot: BindingSlot): string {
 
 interface BindingBase<Value> {
   readonly id: BindingIdentifier;
+  /**
+   * True while this binding's factory is on the sync resolution stack — the sync lane's cycle check.
+   *
+   * @remarks Resolver-owned bookkeeping; callers never set it. See `ARCHITECTURE.md` for why the
+   * sync and async lanes detect cycles differently.
+   */
+  inFlight?: boolean | undefined;
+  /**
+   * Memoized resolution frame for this binding. Its contents derive only from immutable binding
+   * fields, so it is computed once on first resolve and reused instead of a per-resolver Map
+   * lookup on every hop.
+   *
+   * @remarks Resolver-owned bookkeeping — `registry.add` normalizes it, so callers never set it.
+   */
+  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;
   readonly token: Token<Value> | Constructor<Value>;
   readonly slot: BindingSlot;
-  readonly predicate?: (ctx: ConstraintContext) => boolean;
+  readonly predicate?: ((ctx: ConstraintContext) => boolean) | undefined;
 }
 
 type BindingBaseKeys = keyof BindingBase<unknown>;
@@ -83,8 +111,8 @@ export interface ClassBinding<Value> extends BindingBase<Value> {
   readonly kind: "class";
   readonly target: Constructor<Value>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -94,8 +122,8 @@ export interface DynamicBinding<Value> extends BindingBase<Value> {
   readonly kind: "dynamic";
   readonly factory: (ctx: ResolutionContext) => Value;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -105,8 +133,8 @@ export interface DynamicAsyncBinding<Value> extends BindingBase<Value> {
   readonly kind: "dynamic-async";
   readonly factory: (ctx: ResolutionContext) => Promise<Value>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -117,8 +145,8 @@ export interface ResolvedBinding<Value> extends BindingBase<Value> {
   readonly factory: (...args: Array<unknown>) => Value;
   readonly deps: ReadonlyArray<InjectionDescriptor>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -129,8 +157,8 @@ export interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
   readonly factory: (...args: Array<unknown>) => Promise<Value>;
   readonly deps: ReadonlyArray<InjectionDescriptor>;
   readonly scope: BindingScope;
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -140,8 +168,8 @@ export interface ConstantBinding<Value> extends BindingBase<Value> {
   readonly kind: "constant";
   readonly value: Value;
   readonly scope: "singleton";
-  readonly onActivation?: ActivationHandler<Value>;
-  readonly onDeactivation?: DeactivationHandler<Value>;
+  readonly onActivation?: ActivationHandler<Value> | undefined;
+  readonly onDeactivation?: DeactivationHandler<Value> | undefined;
 }
 
 /**
@@ -180,12 +208,99 @@ export type PartialBinding<Value> =
 
 // ── ID generation ─────────────────────────────────────────────────────────────
 
-let _idCounter = 0;
+let bindingIdCounter = 0;
 /**
  * @since 0.3.16-canary.0
  */
 export function generateBindingId(): BindingIdentifier {
-  return String(++_idCounter) as BindingIdentifier;
+  return String(++bindingIdCounter) as BindingIdentifier;
+}
+
+// ── Construction ──────────────────────────────────────────────────────────────
+
+// 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;
+
+/**
+ * Completeness guard for {@link createBinding}'s literal.
+ *
+ * @remarks The literal is `satisfies` this, so a field added to any binding kind that the literal
+ * forgets to write is a compile error rather than a binding silently missing it.
+ */
+type ConstructedBindingFields = Record<BindingFieldName, unknown>;
+
+type BindingFieldSuperset = {
+  readonly kind: Binding["kind"];
+  readonly instance?: unknown;
+  readonly scope?: unknown;
+  readonly target?: unknown;
+  readonly factory?: unknown;
+  readonly deps?: unknown;
+  readonly value?: unknown;
+  readonly onActivation?: unknown;
+  readonly onDeactivation?: unknown;
+};
+
+/**
+ * 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.
+ *
+ * @param source - the kind-specific payload, or an existing binding to re-slot
+ * @param id - reuse a caller's id to keep a fluent chain's `id()` stable across refinements
+ *
+ * @since 0.5.0-canary.8
+ */
+export function createBinding<Value>(
+  source: PartialBinding<Value> | Binding<Value>,
+  token: Token<Value> | Constructor<Value>,
+  slot: BindingSlot,
+  predicate: ((ctx: ConstraintContext) => boolean) | undefined,
+  id: BindingIdentifier = generateBindingId(),
+): Binding<Value> {
+  const fields = source as BindingFieldSuperset;
+  return {
+    kind: fields.kind,
+    id,
+    inFlight: false,
+    frame: undefined,
+    instance: (source as { instance?: unknown }).instance ?? NO_INSTANCE,
+    token,
+    slot,
+    predicate,
+    scope: fields.scope,
+    target: fields.target,
+    factory: fields.factory,
+    deps: fields.deps,
+    value: fields.value,
+    onActivation: fields.onActivation,
+    onDeactivation: fields.onDeactivation,
+  } satisfies ConstructedBindingFields as Binding<Value>;
+}
+
+/**
+ * Writable view of the only fields a fluent chain may refine after registration.
+ *
+ * @remarks No registry index is keyed on these, so a builder that owns the registered object
+ * can write them directly instead of re-registering. `token`, `slot`, `predicate` and `id`
+ * are excluded on purpose — changing those means re-indexing.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface RefinableBindingFields<Value> {
+  onActivation: ActivationHandler<Value> | undefined;
+  onDeactivation: DeactivationHandler<Value> | undefined;
+  scope: BindingScope;
+}
+
+/**
+ * Narrows a registered binding to the fields a fluent chain may still refine.
+ *
+ * @since 0.5.0-canary.8
+ */
+export function refinableFields<Value>(binding: Binding<Value>): RefinableBindingFields<Value> {
+  return binding as RefinableBindingFields<Value>;
 }
 
 // ── Builder interfaces ────────────────────────────────────────────────────────
@@ -212,12 +327,12 @@ export interface BindToBuilder<Value> {
   toConstantValue(value: Value): ConstantBindingBuilder<Value>;
   toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
   toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
-  toResolved<const Deps extends ReadonlyArray<DependencyKey>>(
-    factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Value,
+  toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(
+    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Value,
     deps: Deps,
   ): BindingBuilder<Value>;
-  toResolvedAsync<const Deps extends ReadonlyArray<DependencyKey>>(
-    factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Promise<Value>,
+  toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(
+    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Promise<Value>,
     deps: Deps,
   ): BindingBuilder<Value>;
   toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;

package/src/constructor-type.ts

@@ -1,9 +1,8 @@
 /**
- * A class (newable) that produces `Value`. Rest parameters are `never[]` so
- * real classes with typed constructors remain assignable under
- * `strictFunctionTypes` (unlike `unknown[]`, which is not assignable from
- * narrower parameter types). Runtime construction still uses the real shape;
- * this alias is the DI “class token” surface only.
+ * A class token: newable, producing `Value`.
+ *
+ * @remarks Rest parameters are `never[]` so classes with typed constructors stay assignable under
+ * `strictFunctionTypes`. Construction uses the real shape; this alias is the token surface only.
  *
  * @since 0.3.16-canary.0
  */

package/src/container/binding-builders.ts

@@ -0,0 +1,294 @@
+/**
+ * The fluent chain `bind()` returns: it registers the binding and refines it in place.
+ *
+ * @see `ARCHITECTURE.md` — why one object plays every role, and what pins the ordering.
+ */
+import type {
+  AliasBindingBuilder,
+  Binding,
+  BindingBuilder,
+  BindingSlot,
+  BindToBuilder,
+  ConstantBindingBuilder,
+  PartialBinding,
+  ScopedBindingBuilder,
+  SingletonBindingBuilder,
+  SingletonLifecycleBuilder,
+  TransientBindingBuilder,
+} from "#/binding";
+import { bindingSlotEquals, createBinding, DEFAULT_BINDING_SLOT, refinableFields } from "#/binding";
+import type { InjectableDependency, ResolvedDependencyValue } from "#/decorators/inject";
+import { normalizeToDescriptor } from "#/decorators/inject";
+import { ChainNotRegisteredError } from "#/errors";
+import type { BindingRegistry } from "#/registry";
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+import type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingScope,
+  ConstraintContext,
+  Constructor,
+  DeactivationHandler,
+  ResolutionContext,
+} from "#/types";
+
+function updateSlotTag(slot: BindingSlot, tag: string, value: unknown): BindingSlot {
+  const tags = [...slot.tags];
+  const existingIndex = tags.findIndex(([key]) => key === tag);
+  if (existingIndex === -1) {
+    tags.push([tag, value]);
+  } else {
+    tags[existingIndex] = [tag, value];
+  }
+  return { ...slot, tags };
+}
+
+// True when re-adding `restored` would immediately be displaced again by `current`
+// (both slot-based with equal slots) — in that case the replacement was legitimate.
+function displacesRestoredBinding(current: Binding, restored: Binding): boolean {
+  const currentIsPurePredicate =
+    current.predicate !== undefined && current.slot.name === undefined && current.slot.tags.length === 0;
+  if (currentIsPurePredicate) {
+    return false;
+  }
+  return bindingSlotEquals(current.slot, restored.slot);
+}
+
+/** Record a module's binding id, dropping the id the chain re-slotted away from. */
+function trackBindingForModule(
+  ids: Array<BindingIdentifier>,
+  id: BindingIdentifier,
+  previousId: BindingIdentifier | undefined,
+): void {
+  if (previousId !== undefined) {
+    const previousIndex = ids.indexOf(previousId);
+    if (previousIndex !== -1) {
+      ids.splice(previousIndex, 1);
+    }
+  }
+  ids.push(id);
+}
+
+// ── Registration target ───────────────────────────────────────────────────────
+
+/**
+ * Where a chain registers, and on whose behalf.
+ *
+ * @remarks Built once per container and shared by every chain it creates. `moduleBindingIds` is
+ * present exactly when the chain belongs to a module load.
+ *
+ * @since 0.5.0-canary.8
+ */
+export interface BindingRegistration {
+  readonly registry: BindingRegistry;
+  readonly moduleBindingIds: Array<BindingIdentifier> | undefined;
+}
+
+// ── BindingChain ──────────────────────────────────────────────────────────────
+
+/**
+ * The one builder behind `bind()` and every `to*()` return type. Each interface exposes only the
+ * calls that are legal at that point in the chain; the runtime object is shared because every
+ * refinement is the same operation — narrow the registered binding, keep its id.
+ *
+ * @since 0.5.0-canary.8
+ */
+export class BindingChain<Value>
+  implements
+    AliasBindingBuilder,
+    BindingBuilder<Value>,
+    BindToBuilder<Value>,
+    ConstantBindingBuilder<Value>,
+    ScopedBindingBuilder<Value>,
+    SingletonBindingBuilder<Value>,
+    SingletonLifecycleBuilder<Value>,
+    TransientBindingBuilder<Value>
+{
+  // Undefined until a `to*()` call registers the binding.
+  #binding: Binding<Value> | undefined;
+  // Allocated only by a chain that actually displaces something — most never do.
+  #displacedByChain: Array<Binding> | undefined;
+  readonly #token: Token<Value> | Constructor<Value>;
+  readonly #registration: BindingRegistration;
+
+  constructor(token: Token<Value> | Constructor<Value>, registration: BindingRegistration) {
+    this.#token = token;
+    this.#registration = registration;
+  }
+
+  /** The registered binding, or a loud failure if no `to*()` has run yet. */
+  #registered(): Binding<Value> {
+    if (this.#binding === undefined) {
+      throw new ChainNotRegisteredError(tokenName(this.#token));
+    }
+    return this.#binding;
+  }
+
+  #register(partial: PartialBinding<Value>): this {
+    // Each `to*()` starts its own registration, so anything a previous one displaced is not this
+    // registration's to restore.
+    this.#displacedByChain = undefined;
+    this.#binding = createBinding(partial, this.#token, DEFAULT_BINDING_SLOT, undefined);
+    this.#commit(this.#binding, undefined);
+    return this;
+  }
+
+  // ── Registration ───────────────────────────────────────────────────────────
+
+  to(type: Constructor<Value>): BindingBuilder<Value> {
+    return this.#register({ kind: "class", target: type, scope: "transient" });
+  }
+
+  toSelf(): BindingBuilder<Value> {
+    if (typeof this.#token !== "function") {
+      throw new Error("toSelf() requires token to be a Constructor");
+    }
+    return this.#register({ kind: "class", target: this.#token, scope: "transient" });
+  }
+
+  toConstantValue(value: Value): ConstantBindingBuilder<Value> {
+    return this.#register({ kind: "constant", scope: "singleton", value });
+  }
+
+  toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value> {
+    return this.#register({ kind: "dynamic", factory, scope: "transient" });
+  }
+
+  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value> {
+    return this.#register({ kind: "dynamic-async", factory, scope: "transient" });
+  }
+
+  toResolved<const Deps extends ReadonlyArray<InjectableDependency>>(
+    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Value,
+    deps: Deps,
+  ): BindingBuilder<Value> {
+    return this.#register({
+      kind: "resolved",
+      deps: deps.map((dependency) => normalizeToDescriptor(dependency)),
+      factory: factory as (...args: Array<unknown>) => Value,
+      scope: "transient",
+    });
+  }
+
+  toResolvedAsync<const Deps extends ReadonlyArray<InjectableDependency>>(
+    factory: (...args: { [K in keyof Deps]: ResolvedDependencyValue<NoInfer<Deps>[K]> }) => Promise<Value>,
+    deps: Deps,
+  ): BindingBuilder<Value> {
+    return this.#register({
+      kind: "resolved-async",
+      deps: deps.map((dependency) => normalizeToDescriptor(dependency)),
+      factory: factory as (...args: Array<unknown>) => Promise<Value>,
+      scope: "transient",
+    });
+  }
+
+  toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder {
+    return this.#register({ kind: "alias", target });
+  }
+
+  // ── Refinement ─────────────────────────────────────────────────────────────
+
+  // Slot and predicate are what the registry indexes on, so a re-slot rebuilds the binding and
+  // re-registers it — under the original id, keeping `id()` stable for the whole chain.
+  #reslot(slot: BindingSlot, predicate: ((ctx: ConstraintContext) => boolean) | undefined): this {
+    const previous = this.#registered();
+    this.#binding = createBinding(previous, previous.token, slot, predicate, previous.id);
+    this.#commit(this.#binding, previous.id);
+    return this;
+  }
+
+  #withScope(scope: BindingScope): this {
+    refinableFields(this.#registered()).scope = scope;
+    this.#registration.registry.touch();
+    return this;
+  }
+
+  when(predicate: (ctx: ConstraintContext) => boolean): this {
+    return this.#reslot(this.#registered().slot, predicate);
+  }
+
+  whenNamed(name: string): this {
+    return this.#reslot({ ...this.#registered().slot, name }, this.#registered().predicate);
+  }
+
+  whenTagged(tag: string, value: unknown): this {
+    const binding = this.#registered();
+    return this.#reslot(updateSlotTag(binding.slot, tag, value), binding.predicate);
+  }
+
+  whenDefault(): this {
+    // The default slot is what a fresh registration already has, so there is nothing to re-slot —
+    // but an unregistered chain must fail here exactly as it does in every other refinement.
+    this.#registered();
+    return this;
+  }
+
+  singleton(): SingletonBindingBuilder<Value> {
+    return this.#withScope("singleton");
+  }
+
+  transient(): TransientBindingBuilder<Value> {
+    return this.#withScope("transient");
+  }
+
+  scoped(): ScopedBindingBuilder<Value> {
+    return this.#withScope("scoped");
+  }
+
+  onActivation(fn: ActivationHandler<Value>): this {
+    refinableFields(this.#registered()).onActivation = fn;
+    this.#registration.registry.touch();
+    return this;
+  }
+
+  onDeactivation(fn: DeactivationHandler<Value>): this {
+    refinableFields(this.#registered()).onDeactivation = fn;
+    this.#registration.registry.touch();
+    return this;
+  }
+
+  id(): BindingIdentifier {
+    return this.#registered().id;
+  }
+
+  // ── Registry ───────────────────────────────────────────────────────────────
+
+  /**
+   * Register `binding`, first removing `previousId` when the chain is re-slotting.
+   *
+   * @remarks A `when*()` that follows `to*()` re-slots an already-live binding and can displace one
+   * the final shape would never conflict with. Those stay parked in `#displacedByChain` until the
+   * chain settles, then get restored.
+   */
+  #commit(binding: Binding<Value>, previousId: BindingIdentifier | undefined): void {
+    const { registry, moduleBindingIds } = this.#registration;
+    // The registry is heterogeneous by design — one instance holds every value type — so the
+    // chain's `Binding<Value>` is erased once, here, rather than at each call site.
+    const registered = binding as Binding;
+
+    if (previousId !== undefined) {
+      registry.removeById(previousId);
+    }
+    const displaced = registry.add(registered);
+    if (displaced !== undefined) {
+      (this.#displacedByChain ??= []).push(displaced);
+    }
+    if (previousId !== undefined && this.#displacedByChain !== undefined) {
+      this.#restoreNonConflicting(registered, this.#displacedByChain);
+    }
+    if (moduleBindingIds !== undefined) {
+      trackBindingForModule(moduleBindingIds, registered.id, previousId);
+    }
+  }
+
+  #restoreNonConflicting(binding: Binding, displaced: Array<Binding>): void {
+    for (let index = displaced.length - 1; index >= 0; index -= 1) {
+      const candidate = displaced[index]!;
+      if (!displacesRestoredBinding(binding, candidate)) {
+        this.#registration.registry.add(candidate);
+        displaced.splice(index, 1);
+      }
+    }
+  }
+}