@codefast/di 0.3.16-canary.2 → 0.4.0-canary.4

package/src/binding-select.ts

@@ -0,0 +1,158 @@
+import type { Binding } from "#/binding";
+import { AmbiguousBindingError } from "#/errors";
+import type { BindingTag, ConstraintContext, ResolveOptions } from "#/types";
+
+/**
+ * Select a single candidate from a list of bindings using slot matching + predicates.
+ * Returns undefined if no match, throws AmbiguousBindingError if multiple match.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function selectBinding(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+  tokenDisplayName: string,
+): Binding | undefined {
+  const candidates = filterBindings(bindings, hint, ctx);
+  if (candidates.length === 0) {
+    return undefined;
+  }
+  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
+  throw new AmbiguousBindingError(
+    tokenDisplayName,
+    candidates.map((c) => c.id),
+  );
+}
+
+/**
+ * Select all candidates matching hint + predicates.
+ *
+ * @since 0.3.16-canary.0
+ */
+export function selectAllBindings(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+): Array<Binding> {
+  return filterBindings(bindings, hint, ctx, "all");
+}
+
+function filterBindings(
+  bindings: ReadonlyArray<Binding>,
+  hint: ResolveOptions | undefined,
+  ctx: ConstraintContext,
+  selectionMode: "single" | "all" = "single",
+): Array<Binding> {
+  if (hint === undefined) {
+    const resultWithoutHint: Array<Binding> = [];
+    if (selectionMode === "all") {
+      for (const binding of bindings) {
+        if (matchesPredicate(binding, ctx)) {
+          resultWithoutHint.push(binding);
+        }
+      }
+    } else {
+      for (const binding of bindings) {
+        const slot = binding.slot;
+        if (slot.name === undefined && slot.tags.length === 0 && matchesPredicate(binding, ctx)) {
+          resultWithoutHint.push(binding);
+        }
+      }
+    }
+    return resultWithoutHint;
+  }
+
+  const result: Array<Binding> = [];
+  for (const binding of bindings) {
+    const slotMatched = selectionMode === "all" ? matchesSlotForResolveAll(binding, hint) : matchesSlot(binding, hint);
+    if (slotMatched && matchesPredicate(binding, ctx)) {
+      result.push(binding);
+    }
+  }
+  return result;
+}
+
+function matchesSlotForResolveAll(binding: Binding, hint: ResolveOptions | undefined): boolean {
+  const hasExplicitSlotFilter =
+    hint !== undefined &&
+    (hint.name !== undefined || (hint.tags !== undefined && hint.tags.length > 0) || hint.tag !== undefined);
+  if (!hasExplicitSlotFilter) {
+    return true;
+  }
+  return matchesSlot(binding, hint);
+}
+
+function matchesSlot(binding: Binding, hint: ResolveOptions | undefined): boolean {
+  const slot = binding.slot;
+  const hintName = hint?.name;
+  const hintTags = hint?.tags;
+  const singleHintTag = hint?.tag;
+  const hasHintTags = (hintTags?.length ?? 0) > 0 || singleHintTag !== undefined;
+
+  // Match by name
+  if (slot.name !== undefined) {
+    if (hintName === undefined) {
+      return false;
+    }
+    if (slot.name !== hintName) {
+      return false;
+    }
+  } else if (hintName !== undefined) {
+    // Binding has no name but hint requests a specific name — no match
+    return false;
+  }
+
+  // Match by tags — binding's tags must all be present in hint
+  if (slot.tags.length > 0) {
+    if (!hasHintTags) {
+      return false;
+    }
+    for (const [tagKey, tagValue] of slot.tags) {
+      if (!matchHintTag(tagKey, tagValue, hintTags, singleHintTag)) {
+        return false;
+      }
+    }
+  } else if (hasHintTags) {
+    // Binding has no tags but hint requires tags — no match for tagged slots
+    // But: default slot (no tags, no name) can match when hint has tags if there are no tag-slotted bindings
+    // Actually per spec: resolveAll with tags only returns bindings that have those tags
+    // and resolve with tags requires exact match
+    return false;
+  }
+
+  return true;
+}
+
+function matchHintTag(
+  tagKey: string,
+  tagValue: unknown,
+  hintTags: ReadonlyArray<BindingTag> | undefined,
+  singleHintTag: BindingTag | undefined,
+): boolean {
+  if (singleHintTag !== undefined && singleHintTag[0] === tagKey && Object.is(singleHintTag[1], tagValue)) {
+    return true;
+  }
+  if (hintTags === undefined || hintTags.length === 0) {
+    return false;
+  }
+  for (let index = 0; index < hintTags.length; index += 1) {
+    const hintTag = hintTags[index]!;
+    if (hintTag[0] === tagKey && Object.is(hintTag[1], tagValue)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function matchesPredicate(binding: Binding, ctx: ConstraintContext): boolean {
+  if (binding.predicate === undefined) {
+    return true;
+  }
+  return binding.predicate(ctx);
+}

package/src/binding.ts

@@ -0,0 +1,277 @@
+import type { InjectionDescriptor } from "#/decorators/inject";
+import type { Token } from "#/token";
+import type {
+  ActivationHandler,
+  BindingIdentifier,
+  BindingScope,
+  BindingTag,
+  Constructor,
+  DeactivationHandler,
+  DependencyKey,
+  ResolutionContext,
+  TokenValue,
+  ConstraintContext,
+} from "#/types";
+
+// ── BindingSlot ───────────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingSlot {
+  readonly name: string | undefined;
+  readonly tags: ReadonlyArray<BindingTag>;
+}
+
+/**
+ * @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) {
+    return false;
+  }
+  for (const [tagKey, tagValue] of left.tags) {
+    if (!right.tags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export const DEFAULT_BINDING_SLOT = { name: undefined, tags: [] } satisfies BindingSlot;
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function bindingSlotToString(slot: BindingSlot): string {
+  if (slot.name === undefined && slot.tags.length === 0) {
+    return "default";
+  }
+  const parts: Array<string> = [];
+  if (slot.name !== undefined) {
+    parts.push(`name:${slot.name}`);
+  }
+  for (const [tagKey, tagValue] of slot.tags) {
+    parts.push(`tag:${tagKey}=${String(tagValue)}`);
+  }
+  return parts.join(",");
+}
+
+// ── BindingBase ───────────────────────────────────────────────────────────────
+
+interface BindingBase<Value> {
+  readonly id: BindingIdentifier;
+  readonly token: Token<Value> | Constructor<Value>;
+  readonly slot: BindingSlot;
+  readonly predicate?: (ctx: ConstraintContext) => boolean;
+}
+
+type BindingBaseKeys = keyof BindingBase<unknown>;
+
+// ── Binding kinds ─────────────────────────────────────────────────────────────
+
+/**
+ * @since 0.3.16-canary.0
+ */
+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>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+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>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+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>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ResolvedBinding<Value> extends BindingBase<Value> {
+  readonly kind: "resolved";
+  readonly factory: (...args: Array<unknown>) => Value;
+  readonly deps: ReadonlyArray<InjectionDescriptor>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
+  readonly kind: "resolved-async";
+  readonly factory: (...args: Array<unknown>) => Promise<Value>;
+  readonly deps: ReadonlyArray<InjectionDescriptor>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ConstantBinding<Value> extends BindingBase<Value> {
+  readonly kind: "constant";
+  readonly value: Value;
+  readonly scope: "singleton";
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AliasBinding<Value> extends BindingBase<Value> {
+  readonly kind: "alias";
+  readonly target: Token<Value> | Constructor<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export type Binding<Value = unknown> =
+  | ClassBinding<Value>
+  | DynamicBinding<Value>
+  | DynamicAsyncBinding<Value>
+  | ResolvedBinding<Value>
+  | ResolvedAsyncBinding<Value>
+  | ConstantBinding<Value>
+  | AliasBinding<Value>;
+
+/**
+ * Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied.
+ *
+ * @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>;
+
+// ── ID generation ─────────────────────────────────────────────────────────────
+
+let _idCounter = 0;
+/**
+ * @since 0.3.16-canary.0
+ */
+export function generateBindingId(): BindingIdentifier {
+  return String(++_idCounter) as BindingIdentifier;
+}
+
+// ── Builder interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Common slot-constraint + id methods shared by all concrete binding builders.
+ *
+ * @since 0.3.16-canary.0
+ */
+export interface SlotConstrainedBuilder {
+  when(predicate: (ctx: ConstraintContext) => boolean): this;
+  whenNamed(name: string): this;
+  whenTagged(tag: string, value: unknown): this;
+  whenDefault(): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindToBuilder<Value> {
+  to(type: Constructor<Value>): BindingBuilder<Value>;
+  toSelf(): BindingBuilder<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,
+    deps: Deps,
+  ): BindingBuilder<Value>;
+  toResolvedAsync<const Deps extends ReadonlyArray<DependencyKey>>(
+    factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Promise<Value>,
+    deps: Deps,
+  ): BindingBuilder<Value>;
+  toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface BindingBuilder<Value> extends SlotConstrainedBuilder {
+  singleton(): SingletonBindingBuilder<Value>;
+  transient(): TransientBindingBuilder<Value>;
+  scoped(): ScopedBindingBuilder<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ConstantBindingBuilder<Value> extends SlotConstrainedBuilder {
+  onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+  onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface AliasBindingBuilder extends SlotConstrainedBuilder {}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface TransientBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export interface SingletonLifecycleBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}

package/src/constraints.ts

@@ -0,0 +1,121 @@
+import type { Token } from "#/token";
+import { tokenName } from "#/token";
+import type { BindingTag, ConstraintContext, Constructor } from "#/types";
+
+function tokenNameOf(token: Token<unknown> | Constructor): string {
+  return tokenName(token);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentIs(token: Token<unknown> | Constructor): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.parent !== undefined && constraintContext.parent.tokenName === tokenDisplayName;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenNoParentIs(token: Token<unknown> | Constructor): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.parent === undefined || constraintContext.parent.tokenName !== tokenDisplayName;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.tokenName === tokenDisplayName);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenNoAncestorIs(
+  token: Token<unknown> | Constructor,
+): (constraintContext: ConstraintContext) => boolean {
+  const tokenDisplayName = tokenNameOf(token);
+  return (constraintContext) =>
+    constraintContext.ancestors.every((ancestorFrame) => ancestorFrame.tokenName !== tokenDisplayName);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentNamed(name: string): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.name === name;
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorNamed(name: string): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.name === name);
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenParentTagged(tag: string, value: unknown): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.parent !== undefined &&
+    constraintContext.parent.slot.tags.some(([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value));
+}
+
+/**
+ * @since 0.3.16-canary.0
+ */
+export function whenAnyAncestorTagged(tag: string, value: unknown): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.ancestors.some((ancestorFrame) =>
+      ancestorFrame.slot.tags.some(([tagKey, tagValue]) => tagKey === tag && Object.is(tagValue, value)),
+    );
+}
+
+/**
+ * Matches when the direct parent slot carries **all** of the given tag pairs.
+ * Equivalent to AND-composing multiple `whenParentTagged` calls but evaluates
+ * in a single predicate invocation — no intermediate closure allocations.
+ *
+ * @since 0.3.16-canary.1
+ */
+export function whenParentTaggedAll(
+  tags: ReadonlyArray<BindingTag>,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) => {
+    const { parent } = constraintContext;
+    if (parent === undefined) {
+      return false;
+    }
+    const { tags: parentTags } = parent.slot;
+    return tags.every(([tagKey, tagValue]) =>
+      parentTags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue)),
+    );
+  };
+}
+
+/**
+ * Matches when at least one ancestor slot carries **all** of the given tag pairs.
+ * Equivalent to AND-composing multiple `whenAnyAncestorTagged` calls but evaluates
+ * in a single predicate invocation — no intermediate closure allocations.
+ *
+ * @since 0.3.16-canary.1
+ */
+export function whenAnyAncestorTaggedAll(
+  tags: ReadonlyArray<BindingTag>,
+): (constraintContext: ConstraintContext) => boolean {
+  return (constraintContext) =>
+    constraintContext.ancestors.some((frame) => {
+      const { tags: frameTags } = frame.slot;
+      return tags.every(([tagKey, tagValue]) =>
+        frameTags.some(([otherKey, otherValue]) => otherKey === tagKey && Object.is(otherValue, tagValue)),
+      );
+    });
+}

package/src/constructor-type.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type Constructor<Value = unknown> = new (...args: Array<never>) => Value;
+
+/**
+ * Class constructor as invoked by the resolver after metadata-driven
+ * resolution of `unknown[]` dependencies — separate from {@link Constructor},
+ * which is the public assignable class token.
+ *
+ * @since 0.3.16-canary.0
+ */
+export type ConstructorInvocation = new (...args: Array<unknown>) => unknown;