@codefast/di 0.8.0 → 0.8.1

package/src/resolution/context.ts

@@ -1,331 +0,0 @@
-/** The `ResolutionContext` a factory is handed, and the callbacks the resolver answers it with. */
-import type { Token } from "#/core/token";
-import type {
-  BindingIdentifier,
-  BindingKind,
-  BindingScope,
-  ConstraintContext,
-  Constructor,
-  ResolutionFrame,
-  ResolutionContext,
-  ResolveOptions,
-} from "#/core/types";
-import type { BranchDepth, OwnedBranchStack } from "#/resolution/path/resolution-path";
-import { UNOWNED_BRANCH } from "#/resolution/path/resolution-path";
-
-// ── ResolutionContext implementation ─────────────────────────────────────────────────────────────────────────────────
-
-/**
- * The engine surface a resolution context calls back into to resolve further dependencies.
- *
- * @since 0.3.16-canary.0
- */
-export interface ResolverCallbacks {
-  resolveFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>): Value;
-  resolve<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Value;
-  resolveAsyncFromContext<Value>(
-    token: Token<Value> | Constructor<Value>,
-    resolutionStack: Array<ResolutionFrame>,
-    branchDepth: BranchDepth,
-  ): Promise<Value>;
-  /** Not one of the eight `Value`-naming entry points: its caller is, and casts once. */
-  resolveAsyncFromCascade(token: Token<unknown> | Constructor): Promise<unknown>;
-  resolveAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Promise<Value>;
-  resolveOptional<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Value | undefined;
-  resolveOptionalAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Promise<Value | undefined>;
-  resolveAll<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Array<Value>;
-  resolveAllAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options: ResolveOptions | undefined,
-    resolutionStack: Array<ResolutionFrame>,
-  ): Promise<Array<Value>>;
-}
-
-/**
- * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
- *
- * @since 0.3.16-canary.0
- */
-export class DefaultResolutionContext implements ResolutionContext {
-  #resolver: ResolverCallbacks;
-  #resolutionStack: Array<ResolutionFrame>;
-  #currentOptions: ResolveOptions | undefined;
-
-  constructor(
-    resolver: ResolverCallbacks,
-    resolutionStack: Array<ResolutionFrame>,
-    currentOptions: ResolveOptions | undefined,
-  ) {
-    this.#resolver = resolver;
-    this.#resolutionStack = resolutionStack;
-    this.#currentOptions = currentOptions;
-  }
-
-  #graph: ConstraintContext | undefined;
-
-  get graph(): ConstraintContext {
-    if (this.#graph === undefined) {
-      this.#graph = new DefaultConstraintContext(this.#resolutionStack, this.#currentOptions);
-    }
-    return this.#graph;
-  }
-
-  reset(
-    resolver: ResolverCallbacks,
-    resolutionStack: Array<ResolutionFrame>,
-    currentOptions: ResolveOptions | undefined,
-  ): void {
-    // Compared before storing: a pooled context lives long enough to be in old space, so storing a
-    // pointer costs a write barrier, and a sync resolve hands every depth the same stack.
-    if (this.#resolver !== resolver) {
-      this.#resolver = resolver;
-    }
-    if (this.#resolutionStack !== resolutionStack) {
-      this.#resolutionStack = resolutionStack;
-    }
-    this.#currentOptions = currentOptions;
-    if (this.#graph !== undefined) {
-      this.#graph = undefined;
-    }
-  }
-
-  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
-    if (options === undefined) {
-      return this.#resolver.resolveFromContext(token, this.#resolutionStack);
-    }
-    return this.#resolver.resolve(token, options, this.#resolutionStack);
-  }
-
-  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
-    if (options === undefined) {
-      // UNOWNED_BRANCH: this frame's array is a sync stack it will pop, so the lane must copy it.
-      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, UNOWNED_BRANCH);
-    }
-    return this.#resolver.resolveAsync(token, options, this.#resolutionStack);
-  }
-
-  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#resolutionStack);
-  }
-
-  resolveOptionalAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, this.#resolutionStack);
-  }
-
-  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#resolutionStack);
-  }
-
-  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, this.#resolutionStack);
-  }
-}
-
-/**
- * One async level's resolution context, which is also its branch of the resolution stack.
- *
- * @remarks Separate from {@link DefaultResolutionContext} so the sync lane's pooled context keeps
- * reading its stack as a plain field: only an async branch has a prefix to take, because an async
- * level owns its branch of the stack.
- *
- * @since 0.5.0-canary.9
- */
-export class AsyncLevelContext implements ResolutionContext {
-  readonly #resolver: ResolverCallbacks;
-  readonly #resolutionStack: OwnedBranchStack;
-  readonly #currentOptions: ResolveOptions | undefined;
-  readonly #branchDepth: BranchDepth;
-
-  /**
-   * @param resolver - the engine callbacks every request on this level goes through
-   * @param resolutionStack - this level's own branch; the depth is read off it rather than passed,
-   * so the two cannot disagree about where this level sits
-   * @param currentOptions - the options of the request that opened this level, if any
-   */
-  constructor(
-    resolver: ResolverCallbacks,
-    resolutionStack: OwnedBranchStack,
-    currentOptions: ResolveOptions | undefined,
-  ) {
-    this.#resolver = resolver;
-    this.#resolutionStack = resolutionStack;
-    this.#currentOptions = currentOptions;
-    this.#branchDepth = resolutionStack.length as BranchDepth;
-  }
-
-  #graph: ConstraintContext | undefined;
-  #exactStackCache: Array<ResolutionFrame> | undefined;
-
-  get graph(): ConstraintContext {
-    if (this.#graph === undefined) {
-      this.#graph = new DefaultConstraintContext(this.#exactStack(), this.#currentOptions);
-    }
-    return this.#graph;
-  }
-
-  // The stack is append-only and a descendant may already have grown it past this level, so every
-  // caller but the async lane is handed this branch's prefix. It is fixed for the level's lifetime.
-  #exactStack(): Array<ResolutionFrame> {
-    return (this.#exactStackCache ??= this.#resolutionStack.slice(0, this.#branchDepth));
-  }
-
-  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
-    if (options === undefined) {
-      return this.#resolver.resolveFromContext(token, this.#exactStack());
-    }
-    return this.#resolver.resolve(token, options, this.#exactStack());
-  }
-
-  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
-    if (options === undefined) {
-      // The hot lane: the resolver reads this branch by depth, so nothing is materialized.
-      return this.#resolver.resolveAsyncFromContext(token, this.#resolutionStack, this.#branchDepth);
-    }
-    return this.#resolver.resolveAsync(token, options, this.#exactStack());
-  }
-
-  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#exactStack());
-  }
-
-  resolveOptionalAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, this.#exactStack());
-  }
-
-  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#exactStack());
-  }
-
-  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, this.#exactStack());
-  }
-}
-
-/**
- * The one context every level of an open synchronous factory cascade shares.
- *
- * @remarks It carries no per-level state at all: while the cascade is open, the resolver's stack
- * *is* this level's ancestor chain, so nothing has to be allocated per level.
- *
- * @since 0.5.0-canary.9
- */
-export class AsyncCascadeContext implements ResolutionContext {
-  readonly #resolver: ResolverCallbacks;
-  readonly #cascadeStack: Array<ResolutionFrame>;
-
-  constructor(resolver: ResolverCallbacks, cascadeStack: Array<ResolutionFrame>) {
-    this.#resolver = resolver;
-    this.#cascadeStack = cascadeStack;
-  }
-
-  get graph(): ConstraintContext {
-    // Not memoized: this context outlives every level, so a cached graph would describe whichever
-    // level asked first. The cascade stack is only this level's ancestors while it is open.
-    return new DefaultConstraintContext(this.#cascadeStack, undefined);
-  }
-
-  resolve<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value {
-    if (options === undefined) {
-      return this.#resolver.resolveFromContext(token, this.#cascadeStack);
-    }
-    return this.#resolver.resolve(token, options, this.#cascadeStack);
-  }
-
-  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value> {
-    if (options === undefined) {
-      return this.#resolver.resolveAsyncFromCascade(token) as Promise<Value>;
-    }
-    return this.#resolver.resolveAsync(token, options, [...this.#cascadeStack]);
-  }
-
-  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined {
-    return this.#resolver.resolveOptional(token, options, this.#cascadeStack);
-  }
-
-  resolveOptionalAsync<Value>(
-    token: Token<Value> | Constructor<Value>,
-    options?: ResolveOptions,
-  ): Promise<Value | undefined> {
-    return this.#resolver.resolveOptionalAsync(token, options, [...this.#cascadeStack]);
-  }
-
-  resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value> {
-    return this.#resolver.resolveAll(token, options, this.#cascadeStack);
-  }
-
-  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>> {
-    return this.#resolver.resolveAllAsync(token, options, [...this.#cascadeStack]);
-  }
-}
-
-class DefaultConstraintContext implements ConstraintContext {
-  readonly resolutionStack: ReadonlyArray<ResolutionFrame>;
-  readonly parent: ResolutionFrame | undefined;
-  readonly currentResolveOptions: Readonly<ResolveOptions> | undefined;
-
-  constructor(resolutionStack: ReadonlyArray<ResolutionFrame>, currentResolveOptions: ResolveOptions | undefined) {
-    this.resolutionStack = resolutionStack;
-    this.parent = resolutionStack.at(-1);
-    this.currentResolveOptions = currentResolveOptions;
-  }
-
-  // Derived per read, never cached: the stack this context aliases may be live, and the names must
-  // report it as it stands — exactly as the dedicated name array did.
-  get resolutionPath(): ReadonlyArray<string> {
-    const names = new Array<string>(this.resolutionStack.length);
-    for (let index = 0; index < this.resolutionStack.length; index += 1) {
-      names[index] = this.resolutionStack[index]!.tokenName;
-    }
-    return names;
-  }
-
-  #ancestors: ReadonlyArray<ResolutionFrame> | undefined;
-
-  get ancestors(): ReadonlyArray<ResolutionFrame> {
-    if (this.#ancestors === undefined) {
-      this.#ancestors = this.resolutionStack.length > 1 ? this.resolutionStack.slice(0, -1) : [];
-    }
-    return this.#ancestors;
-  }
-}
-
-/**
- * Creates the resolution-stack frame for one in-flight resolve.
- *
- * @since 0.3.16-canary.0
- */
-export function buildResolutionFrame(
-  tokenName: string,
-  scope: BindingScope,
-  bindingId: BindingIdentifier,
-  kind: BindingKind,
-  slot: ResolutionFrame["slot"],
-): ResolutionFrame {
-  return { tokenName, scope, bindingId, kind, slot };
-}

package/src/resolution/path/resolution-path.ts

@@ -1,167 +0,0 @@
-import type { BindingIdentifier, ResolutionFrame } from "#/core/types";
-/** Cycle-detection bookkeeping carried on the resolution stack itself. */
-import { CircularDependencyError } from "#/errors/errors";
-
-const RESOLUTION_SET_KEY: unique symbol = Symbol("di:resolution-set");
-/**
- * Where the cycle check switches from a linear frame scan to an attached Set.
- *
- * @remarks Measured rather than guessed: below this depth the linear scan wins, above it the Set does.
- *
- * @since 0.5.0-canary.7
- */
-export const RESOLUTION_SET_THRESHOLD = 32;
-type ResolutionStackWithSet = Array<ResolutionFrame> & { [RESOLUTION_SET_KEY]?: Set<BindingIdentifier> | undefined };
-
-/**
- * The token names along a stack plus the frame that closed the cycle — built only to throw.
- *
- * @since 0.6.0
- */
-export function cycleNamesOf(resolutionStack: ReadonlyArray<ResolutionFrame>, closingName: string): Array<string> {
-  const names = new Array<string>(resolutionStack.length + 1);
-  for (let index = 0; index < resolutionStack.length; index += 1) {
-    names[index] = resolutionStack[index]!.tokenName;
-  }
-  names[resolutionStack.length] = closingName;
-  return names;
-}
-
-/**
- * Marks a level as in-flight on this stack, throwing if its binding is already an ancestor.
- *
- * @remarks The check keys on binding identity — two distinct tokens may share a display name — and
- * the names an error prints are derived from the frames at the throw site. Unmark by popping the
- * stack plus `set?.delete(frame.bindingId)`. Sync only — the async lane never removes an entry, so
- * it extends a branch instead; see {@link extendResolutionBranch}.
- *
- * @returns the membership set once the stack is deep enough to carry one, else `undefined`.
- *
- * @since 0.5.0-canary.7
- */
-export function enterResolutionPath(
-  resolutionStack: Array<ResolutionFrame>,
-  frame: ResolutionFrame,
-): Set<BindingIdentifier> | undefined {
-  const stackWithSet = resolutionStack as ResolutionStackWithSet;
-  let resolutionSet = stackWithSet[RESOLUTION_SET_KEY];
-  // A live set mirrors the stack exactly, so a size that disagrees means it is holding ids of
-  // frames that unwound: the ones already on the stack when it attached were handed no set to
-  // delete from. Dropped rather than repaired, because the next deep frame rebuilds it.
-  if (resolutionSet !== undefined && resolutionSet.size !== resolutionStack.length) {
-    resolutionSet = undefined;
-    stackWithSet[RESOLUTION_SET_KEY] = undefined;
-  }
-  if (resolutionSet === undefined && resolutionStack.length >= RESOLUTION_SET_THRESHOLD) {
-    resolutionSet = new Set<BindingIdentifier>();
-    for (let index = 0; index < resolutionStack.length; index += 1) {
-      resolutionSet.add(resolutionStack[index]!.bindingId);
-    }
-    stackWithSet[RESOLUTION_SET_KEY] = resolutionSet;
-  }
-  if (resolutionSet === undefined) {
-    for (let index = 0; index < resolutionStack.length; index += 1) {
-      if (resolutionStack[index]!.bindingId === frame.bindingId) {
-        throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-      }
-    }
-  } else if (resolutionSet.has(frame.bindingId)) {
-    throw new CircularDependencyError(cycleNamesOf(resolutionStack, frame.tokenName));
-  }
-  resolutionStack.push(frame);
-  resolutionSet?.add(frame.bindingId);
-  return resolutionSet;
-}
-
-declare const BRANCH_BRAND: unique symbol;
-
-/**
- * A resolution stack one async branch owns, so appending to it cannot disturb another branch.
- *
- * @remarks Only {@link extendResolutionBranch} mints one. That is what makes "may this lane append
- * to this array" a question the compiler answers instead of a rule in a doc — a sync frame's stack,
- * which that frame will pop, is a plain `Array<ResolutionFrame>` and cannot reach a level that owns
- * its own.
- *
- * @since 0.5.0-canary.9
- */
-export type OwnedBranchStack = Array<ResolutionFrame> & { readonly [BRANCH_BRAND]: true };
-
-declare const BRANCH_DEPTH_BRAND: unique symbol;
-
-/**
- * How many leading entries of a stack belong to one async branch.
- *
- * @remarks Branded so a bare number cannot be passed: a depth from anywhere but this branch silently
- * re-parents a level.
- *
- * @since 0.5.0-canary.9
- */
-export type OwnedBranchDepth = number & { readonly [BRANCH_DEPTH_BRAND]: true };
-
-/**
- * A stack no async branch owns yet, so its first extension must copy rather than append.
- *
- * @since 0.5.0-canary.9
- */
-export const UNOWNED_BRANCH = -1;
-
-/**
- * How far into a stack one extension may reach: this branch's own depth, or nobody's.
- *
- * @remarks A union rather than a sentinel hidden inside the branded number, so the two cases are
- * visible at every signature that takes one and `=== UNOWNED_BRANCH` narrows to the owned case.
- *
- * @since 0.5.0-canary.9
- */
-export type BranchDepth = OwnedBranchDepth | typeof UNOWNED_BRANCH;
-
-/**
- * The depth a chain's first level extends from, over an array its caller just minted.
- *
- * @since 0.5.0-canary.9
- */
-export const ROOT_BRANCH = 0 as OwnedBranchDepth;
-
-/**
- * A branch's own depth: the length its stack had when this level took it.
- *
- * @since 0.5.0-canary.9
- */
-export function branchDepthOf(branch: OwnedBranchStack): OwnedBranchDepth {
-  return branch.length as OwnedBranchDepth;
-}
-
-/**
- * Extends one branch of an append-only stack, throwing if the binding is already an ancestor.
- *
- * @remarks The check compares binding ids on the frames; the names an error prints are derived at
- * the throw site. Appends in place while this branch still owns the next slot, and copies its own
- * prefix once a sibling has claimed it. Nothing is ever removed, so no async level has to observe
- * its own settlement to unwind.
- *
- * @since 0.5.0-canary.9
- */
-export function extendResolutionBranch(
-  resolutionStack: Array<ResolutionFrame>,
-  branchDepth: BranchDepth,
-  frame: ResolutionFrame,
-): OwnedBranchStack {
-  const depth = branchDepth === UNOWNED_BRANCH ? resolutionStack.length : branchDepth;
-  for (let index = 0; index < depth; index += 1) {
-    if (resolutionStack[index]!.bindingId === frame.bindingId) {
-      throw new CircularDependencyError(cycleNamesOf(resolutionStack.slice(0, depth), frame.tokenName));
-    }
-  }
-  // An unowned array belongs to a sync frame that will pop it, or carries a membership Set this
-  // lane cannot keep true; copying is what makes the branch's own appends safe.
-  if (branchDepth === resolutionStack.length) {
-    // The sole mint: appending in place needs a depth that came from a branch already owned, or
-    // ROOT_BRANCH over an array its caller minted for this chain alone.
-    resolutionStack.push(frame);
-    return resolutionStack as OwnedBranchStack;
-  }
-  const branch = resolutionStack.slice(0, depth);
-  branch.push(frame);
-  return branch as OwnedBranchStack;
-}