@codefast/di 0.7.1 → 0.8.1

package/src/resolution/select/binding-select.ts

@@ -1,210 +0,0 @@
-import type { Binding, BindingSlot } from "#/core/binding";
-import type { BindingTag, TagKeyMask } from "#/core/tag";
-import { coversTagKeys, NO_TAG_KEYS } from "#/core/tag";
-import type { ConstraintContext, ResolveOptions } from "#/core/types";
-import { AmbiguousBindingError } from "#/errors/errors";
-
-/**
- * Selects 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>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-  tokenDisplayName: string,
-): Binding | undefined {
-  const candidates = filterBindings(bindings, options, ctx, true);
-  if (candidates.length === 0) {
-    return undefined;
-  }
-  if (candidates.length === 1) {
-    return candidates[0];
-  }
-  // Most specific wins, predicate before tag count: a lone predicate-carrying candidate beats
-  // predicate-less ones, a predicate being a deliberate specialization of the default. This order is
-  // what keeps every resolution that already succeeds deciding the same way.
-  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;
-  }
-  // Reached only where the throw was: a slot declaring more of what the request carries is the more
-  // specific match, so an over-specified request resolves instead of being ambiguous.
-  const mostSpecific = mostSpecificByTagCount(candidates);
-  if (mostSpecific !== undefined) {
-    return mostSpecific;
-  }
-  throw new AmbiguousBindingError(
-    tokenDisplayName,
-    candidates.map((c) => c.id),
-  );
-}
-
-/** The lone candidate declaring more tags than every other, or `undefined` when that is a tie. */
-function mostSpecificByTagCount(candidates: ReadonlyArray<Binding>): Binding | undefined {
-  let best: Binding | undefined;
-  let bestCount = -1;
-  let tied = false;
-  for (const candidate of candidates) {
-    const count = candidate.slot.tags.length;
-    if (count > bestCount) {
-      best = candidate;
-      bestCount = count;
-      tied = false;
-    } else if (count === bestCount) {
-      tied = true;
-    }
-  }
-  return tied ? undefined : best;
-}
-
-/**
- * Selects all candidates matching options + predicates.
- *
- * @since 0.3.16-canary.0
- */
-export function selectAllBindings(
-  bindings: ReadonlyArray<Binding>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-): Array<Binding> {
-  // `resolveAll` matches the slot only when the request carries a criterion; with none it takes
-  // every binding, where `resolve` would read an absent criterion as "the default slot".
-  return filterBindings(bindings, options, ctx, options !== undefined && hasSlotCriterion(options));
-}
-
-/**
- * @param bindings - the token's candidates, in registration order
- * @param options - the request's selection criteria, if any
- * @param ctx - what the constraint predicates read
- * @param requiresSlotMatch - `resolve` always matches the slot, where an absent criterion means
- * "the default slot"; `resolveAll` matches only when the request carries one
- */
-function filterBindings(
-  bindings: ReadonlyArray<Binding>,
-  options: ResolveOptions | undefined,
-  ctx: ConstraintContext,
-  requiresSlotMatch: boolean,
-): Array<Binding> {
-  const result: Array<Binding> = [];
-  // A predicate is user code that may rebind the token mid-walk, but the registry replaces a
-  // token's list on mutation instead of splicing it, so this walk keeps its own list — no copy.
-  for (let index = 0; index < bindings.length; index += 1) {
-    const binding = bindings[index]!;
-    if (requiresSlotMatch && !matchesSlot(binding.slot, options)) {
-      continue;
-    }
-    const predicate = binding.predicate;
-    if (predicate === undefined) {
-      result.push(binding);
-      continue;
-    }
-    if (predicate(ctx)) {
-      result.push(binding);
-    }
-  }
-  return result;
-}
-
-function hasSlotCriterion(options: ResolveOptions): boolean {
-  return options.name !== undefined || requestedTagKeyMask(options) !== NO_TAG_KEYS;
-}
-
-/**
- * Whether a binding's slot satisfies a request: names must be equal, and every tag the slot
- * declares must be among the tags requested.
- *
- * @remarks The tag half is a key-mask subset test before any criterion is read, so a slot the
- * request cannot satisfy is rejected in one word compare. Criteria are interned, so what follows is
- * identity.
- *
- * @since 0.5.0-canary.9
- */
-export function matchesSlot(slot: BindingSlot, options: ResolveOptions | undefined): boolean {
-  const requestedName = options?.name;
-
-  if (slot.name !== undefined) {
-    if (slot.name !== requestedName) {
-      return false;
-    }
-  } else if (requestedName !== undefined) {
-    return false;
-  }
-
-  const slotMask = slot.keyMask;
-  const requestMask = requestedTagKeyMask(options);
-
-  if (slotMask === NO_TAG_KEYS) {
-    // A request carrying tags needs a tagged slot: an untagged binding never matches.
-    return requestMask === NO_TAG_KEYS;
-  }
-  if (!coversTagKeys(requestMask, slotMask)) {
-    return false;
-  }
-
-  // The mask can collide two keys onto one bit, so the exact criteria still have to be confirmed.
-  const slotTags = slot.tags;
-
-  for (let index = 0; index < slotTags.length; index += 1) {
-    if (!requestCarries(options, slotTags[index]!)) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * The key set a request covers, across both spellings the shorthand folds into one.
- *
- * @since 0.6.0
- */
-export function requestedTagKeyMask(options: ResolveOptions | undefined): TagKeyMask {
-  if (options === undefined) {
-    return NO_TAG_KEYS;
-  }
-  const single = options.tag;
-  const listed = options.tags;
-  let mask = single === undefined ? NO_TAG_KEYS : single.mask;
-
-  if (listed !== undefined) {
-    for (let index = 0; index < listed.length; index += 1) {
-      mask = (mask | listed[index]!.mask) as TagKeyMask;
-    }
-  }
-
-  return mask;
-}
-
-/** Whether a request names this exact criterion — identity, because criteria are interned. */
-function requestCarries(options: ResolveOptions | undefined, criterion: BindingTag): boolean {
-  if (options === undefined) {
-    return false;
-  }
-  if (options.tag === criterion) {
-    return true;
-  }
-  const listed = options.tags;
-
-  if (listed === undefined) {
-    return false;
-  }
-  for (let index = 0; index < listed.length; index += 1) {
-    if (listed[index] === criterion) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/resolution/select/constraints.ts

@@ -1,146 +0,0 @@
-import { requiringAncestorSlotName } from "#/core/constraint-requirement";
-import type { BindingTag } from "#/core/tag";
-import { coversTagKeys, tagKeyMaskOf } from "#/core/tag";
-import type { Token } from "#/core/token";
-import { tokenName } from "#/core/token";
-import type { BindingConstraint, Constructor } from "#/core/types";
-import { EmptyTagCriteriaError } from "#/errors/errors";
-
-/**
- * Matches when the direct parent frame resolves the given token.
- *
- * @since 0.3.16-canary.0
- */
-export function whenParentIs(token: Token<unknown> | Constructor): BindingConstraint {
-  const tokenDisplayName = tokenName(token);
-  return (constraintContext) =>
-    constraintContext.parent !== undefined && constraintContext.parent.tokenName === tokenDisplayName;
-}
-
-/**
- * Matches when there is no direct parent frame, or it resolves a different token.
- *
- * @since 0.3.16-canary.0
- */
-export function whenNoParentIs(token: Token<unknown> | Constructor): BindingConstraint {
-  const tokenDisplayName = tokenName(token);
-  return (constraintContext) =>
-    constraintContext.parent === undefined || constraintContext.parent.tokenName !== tokenDisplayName;
-}
-
-/**
- * Matches when at least one ancestor frame resolves the given token.
- *
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
-  const tokenDisplayName = tokenName(token);
-  return (constraintContext) =>
-    constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.tokenName === tokenDisplayName);
-}
-
-/**
- * Matches when no ancestor frame resolves the given token.
- *
- * @since 0.3.16-canary.0
- */
-export function whenNoAncestorIs(token: Token<unknown> | Constructor): BindingConstraint {
-  const tokenDisplayName = tokenName(token);
-  return (constraintContext) =>
-    constraintContext.ancestors.every((ancestorFrame) => ancestorFrame.tokenName !== tokenDisplayName);
-}
-
-/**
- * Matches when the direct parent slot carries the given name.
- *
- * @since 0.3.16-canary.0
- */
-export function whenParentNamed(name: string): BindingConstraint {
-  return requiringAncestorSlotName(
-    (constraintContext) => constraintContext.parent !== undefined && constraintContext.parent.slot.name === name,
-    name,
-    "whenParentNamed",
-  );
-}
-
-/**
- * Matches when at least one ancestor slot carries the given name.
- *
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorNamed(name: string): BindingConstraint {
-  return requiringAncestorSlotName(
-    (constraintContext) => constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.name === name),
-    name,
-    "whenAnyAncestorNamed",
-  );
-}
-
-/**
- * Matches when the direct parent slot carries the given tag pair.
- *
- * @since 0.3.16-canary.0
- */
-export function whenParentTagged(criterion: BindingTag): BindingConstraint {
-  return (constraintContext) =>
-    constraintContext.parent !== undefined && constraintContext.parent.slot.tags.includes(criterion);
-}
-
-/**
- * Matches when at least one ancestor slot carries the given tag pair.
- *
- * @since 0.3.16-canary.0
- */
-export function whenAnyAncestorTagged(criterion: BindingTag): BindingConstraint {
-  return (constraintContext) =>
-    constraintContext.ancestors.some((ancestorFrame) => ancestorFrame.slot.tags.includes(criterion));
-}
-
-/**
- * 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>): BindingConstraint {
-  assertHasCriteria(tags, "whenParentTaggedAll");
-  const wanted = tagKeyMaskOf(tags);
-  return (constraintContext) => {
-    const { parent } = constraintContext;
-    if (parent === undefined || !coversTagKeys(parent.slot.keyMask, wanted)) {
-      return false;
-    }
-    return tags.every((criterion) => parent.slot.tags.includes(criterion));
-  };
-}
-
-/**
- * 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>): BindingConstraint {
-  assertHasCriteria(tags, "whenAnyAncestorTaggedAll");
-  const wanted = tagKeyMaskOf(tags);
-  return (constraintContext) =>
-    constraintContext.ancestors.some(
-      (frame) =>
-        coversTagKeys(frame.slot.keyMask, wanted) && tags.every((criterion) => frame.slot.tags.includes(criterion)),
-    );
-}
-
-/**
- * Refuses a criteria list with nothing in it.
- *
- * @remarks "carries all of no criteria" is vacuously true, so an empty list quietly turns the
- * constraint into "has an ancestor at all" — a weaker predicate than the caller wrote, and one that
- * still wins specificity over an unconstrained binding.
- */
-function assertHasCriteria(tags: ReadonlyArray<BindingTag>, helperName: string): void {
-  if (tags.length === 0) {
-    throw new EmptyTagCriteriaError(helperName);
-  }
-}