@codefast/di 0.5.0-canary.7 → 0.5.0-canary.9

package/src/resolution/resolution-path.ts

@@ -1,21 +1,12 @@
-/**
- * Cycle-detection bookkeeping shared by every resolution path.
- *
- * The resolution path is a plain string array for cheap push/pop; past
- * RESOLUTION_SET_THRESHOLD entries an O(1) membership Set is attached to the
- * array itself (symbol-keyed) so very deep graphs keep bounded cycle checks.
- */
+/** Cycle-detection bookkeeping carried on the resolution path itself. */
 import { CircularDependencyError } from "#/errors";
+import type { ResolutionFrame } from "#/types";
 
 const RESOLUTION_SET_KEY: unique symbol = Symbol("di:resolution-set");
 /**
  * Where the cycle check switches from a linear `Array.includes` scan to an attached Set.
  *
- * @remarks Re-measured on Node 26 / M3 Max over an async transient chain (ns/op at depth
- * 16 / 32 / 64 / 128): a threshold of 128 gives 1275 / 3641 / 9645 / 26082, of 32 gives
- * 1202 / 3285 / 7735 / 16837, of 16 gives 1299 / 3694 / 7449 / 15625. Switching at 32 wins
- * the shallow-to-mid depths real graphs actually have while staying close to the best deep
- * numbers; the previous value of 128 was the worst of the three almost everywhere.
+ * @see `ARCHITECTURE.md` — the depth sweep this value comes from.
  *
  * @since 0.5.0-canary.7
  */
@@ -23,33 +14,19 @@ export const RESOLUTION_SET_THRESHOLD = 32;
 type ResolutionPathWithSet = Array<string> & { [RESOLUTION_SET_KEY]?: Set<string> };
 
 /**
- * Shared cycle guard for every transient resolution path: attaches the O(1) membership
- * Set to the path array (lazily past RESOLUTION_SET_THRESHOLD, eagerly when `forceSet`),
- * throws on a repeated token, then marks the token on both structures.
+ * Marks a token as in-flight on this path, throwing if it is already there.
+ *
+ * @remarks Unmark with `resolutionPath.pop()` plus `set?.delete(name)`. Sync only — the async lane
+ * never removes an entry, so it extends a branch instead; see {@link extendResolutionBranch}.
+ *
+ * @returns the membership set once the path is deep enough to carry one, else `undefined`.
  *
- * Callers unmark with `resolutionPath.pop()` + `set?.delete(name)` on unwind.
- */
-export function enterResolutionPath(
-  resolutionPath: Array<string>,
-  tokenDisplayName: string,
-  forceSet: true,
-): Set<string>;
-export function enterResolutionPath(
-  resolutionPath: Array<string>,
-  tokenDisplayName: string,
-  forceSet: boolean,
-): Set<string> | undefined;
-/**
  * @since 0.5.0-canary.7
  */
-export function enterResolutionPath(
-  resolutionPath: Array<string>,
-  tokenDisplayName: string,
-  forceSet: boolean,
-): Set<string> | undefined {
+export function enterResolutionPath(resolutionPath: Array<string>, tokenDisplayName: string): Set<string> | undefined {
   const pathWithSet = resolutionPath as ResolutionPathWithSet;
   let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
-  if (resolutionSet === undefined && (forceSet || resolutionPath.length >= RESOLUTION_SET_THRESHOLD)) {
+  if (resolutionSet === undefined && resolutionPath.length >= RESOLUTION_SET_THRESHOLD) {
     resolutionSet = new Set<string>(resolutionPath);
     pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
   }
@@ -61,17 +38,119 @@ export function enterResolutionPath(
   return resolutionSet;
 }
 
+declare const BRANCH_BRAND: unique symbol;
+
 /**
- * Unwinds the innermost `enterResolutionPath` entry, keeping the attached membership Set in
- * sync. Callers that already hold the entry's name can pop and delete directly; this exists for
- * unwind paths that only have the path array — notably the async chain's shared settle callback,
- * which serves every level and therefore cannot capture a per-level name.
+ * A resolution path one async branch owns, so appending to it cannot disturb another branch.
  *
- * @since 0.5.0-canary.7
+ * @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 path,
+ * which that frame will pop, is a plain `Array<string>` and cannot reach a level that owns its own.
+ *
+ * @since 0.5.0-canary.9
+ */
+export type OwnedBranchPath = Array<string> & { readonly [BRANCH_BRAND]: true };
+
+/**
+ * The stack half of {@link OwnedBranchPath}, minted only by {@link extendResolutionStackBranch}.
+ *
+ * @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 path 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 path 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 path 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 path had when this level took it.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function branchDepthOf(branch: OwnedBranchPath): OwnedBranchDepth {
+  return branch.length as OwnedBranchDepth;
+}
+
+/**
+ * Extends one branch of an append-only path, throwing if the entry is already an ancestor.
+ *
+ * @remarks 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 — see `ARCHITECTURE.md`.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function extendResolutionBranch(
+  resolutionPath: Array<string>,
+  branchDepth: BranchDepth,
+  tokenDisplayName: string,
+): OwnedBranchPath {
+  const depth = branchDepth === UNOWNED_BRANCH ? resolutionPath.length : branchDepth;
+  for (let index = 0; index < depth; index += 1) {
+    if (resolutionPath[index] === tokenDisplayName) {
+      throw new CircularDependencyError([...resolutionPath.slice(0, depth), tokenDisplayName]);
+    }
+  }
+  // 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 === resolutionPath.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.
+    resolutionPath.push(tokenDisplayName);
+    return resolutionPath as OwnedBranchPath;
+  }
+  const branch = resolutionPath.slice(0, depth);
+  branch.push(tokenDisplayName);
+  return branch as OwnedBranchPath;
+}
+
+/**
+ * The stack half of {@link extendResolutionBranch}; frames carry no cycle to detect.
+ *
+ * @since 0.5.0-canary.9
  */
-export function exitResolutionPath(resolutionPath: Array<string>): void {
-  const tokenDisplayName = resolutionPath.pop();
-  if (tokenDisplayName !== undefined) {
-    (resolutionPath as ResolutionPathWithSet)[RESOLUTION_SET_KEY]?.delete(tokenDisplayName);
+export function extendResolutionStackBranch(
+  resolutionStack: Array<ResolutionFrame>,
+  branchDepth: BranchDepth,
+  frame: ResolutionFrame,
+): OwnedBranchStack {
+  if (branchDepth === resolutionStack.length) {
+    resolutionStack.push(frame);
+    return resolutionStack as OwnedBranchStack;
   }
+  const branch = resolutionStack.slice(0, branchDepth === UNOWNED_BRANCH ? resolutionStack.length : branchDepth);
+  branch.push(frame);
+  return branch as OwnedBranchStack;
 }

package/src/resolution/resolve-options.ts

@@ -1,5 +1,45 @@
-import type { BindingSlot } from "#/binding";
-import type { BindingTag, ResolveOptions } from "#/types";
+import type { Token } from "#/token";
+import type { BindingTag, Constructor, ResolveOptions } from "#/types";
+
+/**
+ * What one resolvable dependency declares.
+ *
+ * @remarks Both dependency sources — a constructor's `ParamMetadata` and a `toResolved`
+ * `InjectionDescriptor` — are this shape, which is why one resolve routine serves both.
+ *
+ * @since 0.5.0-canary.9
+ */
+export interface DependencySlot {
+  readonly token: Token<unknown> | Constructor;
+  readonly optional: boolean;
+  readonly multi: boolean;
+  readonly name?: string;
+  readonly tags?: ReadonlyArray<BindingTag>;
+}
+
+/**
+ * A request whose only criterion is a name — the shape the registry has a direct index for.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function isNameOnlyOptions(options: ResolveOptions): options is ResolveOptions & { name: string } {
+  return (
+    options.name !== undefined && options.tag === undefined && (options.tags === undefined || options.tags.length === 0)
+  );
+}
+
+/**
+ * The lone entry of a request whose only criterion is a one-element `tags` list — the shape the
+ * registry has a direct tag index for.
+ *
+ * @since 0.5.0-canary.9
+ */
+export function singleTagOnlyOf(options: ResolveOptions): BindingTag | undefined {
+  if (options.name !== undefined || options.tag !== undefined) {
+    return undefined;
+  }
+  return options.tags !== undefined && options.tags.length === 1 ? options.tags[0] : undefined;
+}
 
 /** Shared core: build a ResolveOptions from already-normalised name + tags. */
 function buildOptions(
@@ -33,10 +73,17 @@ export function injectionSlotToResolveOptions(injectionSlot: {
 }
 
 /**
- * Resolve options derived from a binding {@link BindingSlot} (tags may be empty; omits when nothing to match).
+ * Resolve options derived from a binding slot (tags may be empty; omits when nothing to match).
+ *
+ * @remarks Takes the slot structurally rather than as `BindingSlot`, so the slot on a public
+ * `BindingSnapshot` — where `name` is an optional property, not a required one holding `undefined` —
+ * is accepted by the same call.
  *
  * @since 0.3.16-canary.0
  */
-export function bindingSlotToResolveOptions(bindingSlot: BindingSlot): ResolveOptions | undefined {
+export function bindingSlotToResolveOptions(bindingSlot: {
+  readonly name?: string | undefined;
+  readonly tags: ReadonlyArray<BindingTag>;
+}): ResolveOptions | undefined {
   return buildOptions(bindingSlot.name, bindingSlot.tags.length > 0 ? bindingSlot.tags : undefined);
 }