@codefast/di 0.10.0 → 0.11.0

package/dist/resolution/plan/instantiation-plan.js

@@ -1,11 +1,10 @@
-import { NO_INSTANCE } from "#/core/binding";
-import { tokenName } from "#/core/token";
-import { AsyncResolutionError } from "#/errors/errors";
-import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
-import { generateAsyncPlan, generatePlan, isPlanCodegenAvailable, PLAN_CODEGEN_THRESHOLD, } from "#/resolution/plan/plan-codegen";
-// Past this depth a dependency escapes to the runtime path rather than inlining further —
-// compiled closures nest one JS frame per level, and pathological graphs are the runtime's job.
-const PLAN_DEPTH_LIMIT = 32;
+import { NO_INSTANCE } from "#core/binding";
+import { tokenName } from "#core/token";
+import { AsyncResolutionError } from "#errors/errors";
+import { injectionSlotToResolveOptions } from "#injection/resolve-options";
+import { settleInOrder } from "#resolution/async-fan-out";
+import { enterSeededPath, leaveSeededPath } from "#resolution/path/resolution-path";
+import { generateAsyncPlan, generatePlan, isPlanCodegenAvailable, PLAN_CODEGEN_THRESHOLD, } from "#resolution/plan/plan-codegen";
 /**
  * Compilation asked to retry later (class lifecycle metadata not discovered yet).
  *
@@ -21,12 +20,28 @@ function allSynchronous(deps) {
     return true;
 }
 /**
- * The promise-aware combinator: run every dep thunk, await them together, then apply.
+ * The promise-aware combinator: run every dep thunk, settle them together, then apply.
  *
  * @remarks A dep's sync throw becomes that slot's rejection so its siblings still start — the
- * interpreted path starts every sibling before the first rejection propagates, and so does this.
+ * interpreted path starts every sibling before any failure is reported, and so does this; a failure
+ * is the first in declaration order, as it is on every other lane.
  */
 function settleThenApply(deps, apply) {
+    if (deps.length === 1) {
+        // One dependency has one outcome, so there is nothing to order and no fan-out to settle.
+        const only = deps[0].run;
+        const applyOne = (value) => apply([value]);
+        return () => {
+            let pending;
+            try {
+                pending = only();
+            }
+            catch (dependencyError) {
+                pending = Promise.reject(dependencyError);
+            }
+            return Promise.resolve(pending).then(applyOne);
+        };
+    }
     return () => {
         const pending = new Array(deps.length);
         for (let index = 0; index < deps.length; index += 1) {
@@ -37,7 +52,7 @@ function settleThenApply(deps, apply) {
                 pending[index] = Promise.reject(dependencyError);
             }
         }
-        return Promise.all(pending).then(apply);
+        return settleInOrder(pending, apply);
     };
 }
 /**
@@ -94,24 +109,52 @@ export class InstantiationPlanCompiler {
      * root-stack rule one level down: every sync lane pops what it pushes, so the owned array still
      * holds exactly the seed when a call returns. A reentrant call finds it claimed and mints its
      * own copy; a return that did not restore the length hands nothing back, so the next call mints.
+     * The plan pushed no frame for the ancestors it inlined, so the seed's bindings are marked in
+     * flight around the call: an escaped factory cycling back into one is caught as the interpreted
+     * path would catch it.
      */
     #compileEscapeThunk(token, ancestors, arity = "single", options) {
         const host = this.#host;
         const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
         const depth = frames.length;
         let owned = [...frames];
-        const run = () => {
-            const stack = owned ?? [...frames];
-            owned = undefined;
-            try {
-                return host.resolveEscaped(token, options, arity, stack);
-            }
-            finally {
-                if (stack.length === depth) {
-                    owned = stack;
+        // A plan root's own opaque dependency has one ancestor, and it is the common escape, so its
+        // marking is written out: one flag read and at most two writes, no loop and no call.
+        const only = ancestors.length === 1 ? ancestors[0] : undefined;
+        const run = only === undefined
+            ? () => {
+                const stack = owned ?? [...frames];
+                owned = undefined;
+                const alreadyInFlight = enterSeededPath(ancestors);
+                try {
+                    return host.resolveEscaped(token, options, arity, stack);
+                }
+                finally {
+                    leaveSeededPath(ancestors, alreadyInFlight);
+                    if (stack.length === depth) {
+                        owned = stack;
+                    }
                 }
             }
-        };
+            : () => {
+                const stack = owned ?? [...frames];
+                owned = undefined;
+                const wasInFlight = only.inFlight;
+                if (!wasInFlight) {
+                    only.inFlight = true;
+                }
+                try {
+                    return host.resolveEscaped(token, options, arity, stack);
+                }
+                finally {
+                    if (!wasInFlight) {
+                        only.inFlight = false;
+                    }
+                    if (stack.length === depth) {
+                        owned = stack;
+                    }
+                }
+            };
         return { run, node: { kind: "thunk", run } };
     }
     // A resolved binding declares its deps as explicit descriptors — same rules as
@@ -282,10 +325,7 @@ export class InstantiationPlanCompiler {
                 node: { kind: "singleton", binding: singletonBinding, escape },
             };
         }
-        if (scope === "transient" &&
-            binding.kind === "class" &&
-            depth < PLAN_DEPTH_LIMIT &&
-            !compileStack.has(binding.identifier)) {
+        if (scope === "transient" && binding.kind === "class" && !compileStack.has(binding.identifier)) {
             const inlined = this.#compileClassPlan(binding, compileStack, depth + 1, ancestors);
             if (inlined !== null) {
                 return inlined;
@@ -476,7 +516,7 @@ export class InstantiationPlanCompiler {
                 node: { kind: "singleton", binding: singletonBinding, escape },
             };
         }
-        if (scope === "transient" && depth < PLAN_DEPTH_LIMIT && !compileStack.has(binding.identifier)) {
+        if (scope === "transient" && !compileStack.has(binding.identifier)) {
             let inlined = null;
             if (binding.kind === "class") {
                 inlined = this.#compileAsyncClassNode(binding, compileStack, depth + 1, ancestors);

package/dist/resolution/plan/plan-codegen.d.ts

@@ -1,17 +1,19 @@
 /**
  * Generates a hot instantiation plan as a function of its own, so its call sites answer for one plan only.
  */
-import type { Binding } from "#/core/binding";
-import type { ConstructorInvocation } from "#/core/constructor-type";
+import type { Binding } from "#core/binding";
+import type { ConstructorInvocation } from "#core/constructor-type";
 /**
- * Runs a plan's closure makes before the plan is generated as its own function.
+ * The number of runs a plan's closure makes before the plan is generated as its own function.
  *
- * @remarks Below it a plan stays a closure, which is all a cold container or a per-request child
- * ever runs; above it a plan pays one compile for call sites nothing else feeds.
+ * @remarks A measured policy, not a machine width, a contract value or bind-time data: generating
+ * costs some fifty closure runs and the new function runs cold for thirty more, so it repays only
+ * over runs in the thousands. Below it a plan stays a closure, which is all a cold container or a
+ * per-request child ever runs.
  *
  * @since 0.10.0
  */
-export declare const PLAN_CODEGEN_THRESHOLD = 32;
+export declare const PLAN_CODEGEN_THRESHOLD = 1024;
 /**
  * The shape of a compiled sync plan: what its closure does, stated as data the generator can read.
  *
@@ -49,7 +51,8 @@ export type PlanNode = {
  *
  * @remarks A node that `awaits` has a dependency that may yield a promise, so it runs as the
  * interpreted async path does: every dependency starts in order, a sync throw becomes that slot's
- * rejection, and the constructor or factory runs on the settled values.
+ * rejection, the constructor or factory runs on the settled values, and a failure is reported in
+ * declaration order.
  *
  * @since 0.10.0
  */

package/dist/resolution/plan/plan-codegen.js

@@ -1,13 +1,16 @@
-import { NO_INSTANCE } from "#/core/binding";
+import { NO_INSTANCE } from "#core/binding";
+import { settleInOrder } from "#resolution/async-fan-out";
 /**
- * Runs a plan's closure makes before the plan is generated as its own function.
+ * The number of runs a plan's closure makes before the plan is generated as its own function.
  *
- * @remarks Below it a plan stays a closure, which is all a cold container or a per-request child
- * ever runs; above it a plan pays one compile for call sites nothing else feeds.
+ * @remarks A measured policy, not a machine width, a contract value or bind-time data: generating
+ * costs some fifty closure runs and the new function runs cold for thirty more, so it repays only
+ * over runs in the thousands. Below it a plan stays a closure, which is all a cold container or a
+ * per-request child ever runs.
  *
  * @since 0.10.0
  */
-export const PLAN_CODEGEN_THRESHOLD = 32;
+export const PLAN_CODEGEN_THRESHOLD = 1024;
 const rejectWith = (error) => Promise.reject(error);
 let codegenAvailable;
 let generatedCount = 0;
@@ -59,10 +62,10 @@ export function generateAsyncPlan(node) {
     const emitter = new PlanEmitter();
     return compileRendered(emitter, emitter.asyncExpression(node));
 }
-function compileRendered(emitter, expression) {
+function compileRendered(emitter, result) {
     generatedCount += 1;
     const locals = emitter.locals.length === 0 ? "" : `let ${emitter.locals.join(", ")};`;
-    const body = `"use strict";/* plan ${String(generatedCount)} */${emitter.hoisted.join("")}return () => {${locals}return ${expression};};`;
+    const body = `"use strict";/* plan ${String(generatedCount)} */${emitter.hoisted.join("")}return () => {${locals}${emitter.statements.join("")}return ${result};};`;
     try {
         // Compiling from source is the mechanism: one function literal per plan is what gives it its own feedback.
         // oxlint-disable-next-line typescript/no-implied-eval
@@ -74,40 +77,50 @@ function compileRendered(emitter, expression) {
     }
 }
 /**
- * Renders a plan tree as one expression over parameters that carry every value the plan closes over.
+ * Renders a plan tree as a flat sequence of statements over parameters that carry every value the plan closes over.
  *
- * @remarks A node that awaits its dependencies renders as an inner function of the same source, so
- * every plan's awaiting nodes have call sites of their own too.
+ * @remarks Each node becomes one assignment to a local after its dependencies' assignments, in declaration
+ * order, so the generated function evaluates exactly as the nested closure did while nesting nothing: a
+ * graph of any depth renders as that many statements, never as an expression that deep. A node that awaits
+ * its dependencies renders as an inner function of the same shape, so every plan's awaiting nodes have call
+ * sites of their own too.
  */
 class PlanEmitter {
     names = [];
     values = [];
     hoisted = [];
-    #localsByFunction = [[]];
+    #frames = [
+        { locals: [], statements: [] },
+    ];
     #hoistedCount = 0;
     #slotByValue = new Map();
     /** The plan function's own temporaries. */
     get locals() {
-        return this.#localsByFunction[0];
+        return this.#frames[0].locals;
     }
+    /** The plan function's statements, in evaluation order. */
+    get statements() {
+        return this.#frames[0].statements;
+    }
+    /** Emits a node's statements and returns the reference that holds its value. */
     expression(node) {
         switch (node.kind) {
             case "construct":
-                return `new ${this.#slot(node.target, "C")}(${this.#list(node.deps)})`;
+                return this.#define(`new ${this.#slot(node.target, "C")}(${this.#list(node.deps)})`);
             case "accessors":
-                return `${this.#slot(node.construct, "A")}([${this.#list(node.deps)}])`;
+                return this.#define(`${this.#slot(node.construct, "A")}([${this.#list(node.deps)}])`);
             case "call": {
-                // The settle only ever throws, so it runs on the promise branch alone and the plain result returns as is.
-                const local = this.#local();
-                const call = `${this.#slot(node.factory, "F")}(${this.#list(node.deps)})`;
-                return `((${local} = ${call}) instanceof ${this.#slot(Promise, "P")} ? ${this.#slot(node.settle, "S")}(${local}) : ${local})`;
+                // The settle only ever throws, so it runs on the promise branch alone and the plain result stands.
+                const local = this.#define(`${this.#slot(node.factory, "F")}(${this.#list(node.deps)})`);
+                this.#statement(`if (${local} instanceof ${this.#slot(Promise, "P")}) ${local} = ${this.#slot(node.settle, "S")}(${local});`);
+                return local;
             }
             case "value":
                 return this.#slot(node.value, "V");
             case "singleton":
                 return this.#singletonRead(node.binding, node.escape);
             case "thunk":
-                return `${this.#slot(node.run, "T")}()`;
+                return this.#define(`${this.#slot(node.run, "T")}()`);
         }
     }
     asyncExpression(node) {
@@ -116,20 +129,20 @@ class PlanEmitter {
                 const target = this.#slot(node.target, "C");
                 return node.awaits
                     ? this.#settled(node.deps, (values) => `new ${target}(${values})`)
-                    : `new ${target}(${this.#asyncList(node.deps)})`;
+                    : this.#define(`new ${target}(${this.#asyncList(node.deps)})`);
             }
             case "call": {
                 const factory = this.#slot(node.factory, "F");
                 return node.awaits
                     ? this.#settled(node.deps, (values) => `${factory}(${values})`)
-                    : `${factory}(${this.#asyncList(node.deps)})`;
+                    : this.#define(`${factory}(${this.#asyncList(node.deps)})`);
             }
             case "value":
                 return this.#slot(node.value, "V");
             case "singleton":
                 return this.#singletonRead(node.binding, node.escape);
             case "thunk":
-                return `${this.#slot(node.run, "T")}()`;
+                return this.#define(`${this.#slot(node.run, "T")}()`);
         }
     }
     #list(deps) {
@@ -146,30 +159,45 @@ class PlanEmitter {
         const name = `n${String(index)}`;
         const applyName = `a${String(index)}`;
         const reject = this.#slot(rejectWith, "R");
-        const promise = this.#slot(Promise, "P");
-        this.#localsByFunction.push([]);
+        const frame = { locals: [], statements: [] };
+        this.#frames.push(frame);
         const pendings = [];
-        const statements = [];
         for (let position = 0; position < deps.length; position += 1) {
             const pending = `p${String(position)}`;
             pendings.push(pending);
-            statements.push(`try{${pending}=${this.asyncExpression(deps[position])};}catch(e){${pending}=${reject}(e);}`);
+            // A dependency's own statements run inside its try, so its sync throw is its rejection alone.
+            const mark = frame.statements.length;
+            const reference = this.asyncExpression(deps[position]);
+            const inner = frame.statements.splice(mark).join("");
+            frame.statements.push(`try{${inner}${pending}=${reference};}catch(e){${pending}=${reject}(e);}`);
         }
-        const locals = [...pendings, ...this.#localsByFunction.pop()];
-        const values = deps.map((_dep, position) => `v[${String(position)}]`).join(",");
-        this.hoisted.push(`const ${applyName}=(v)=>${apply(values)};const ${name}=()=>{let ${locals.join(",")};${statements.join("")}return ${promise}.all([${pendings.join(",")}]).then(${applyName});};`);
-        return `${name}()`;
+        this.#frames.pop();
+        const locals = [...pendings, ...frame.locals];
+        // One dependency has one outcome, so there is nothing to order and no fan-out to settle.
+        const settled = deps.length === 1
+            ? `const ${applyName}=(v0)=>${apply("v0")};const ${name}=()=>{let ${locals.join(",")};${frame.statements.join("")}return ${this.#slot(Promise, "P")}.resolve(p0).then(${applyName});};`
+            : `const ${applyName}=(v)=>${apply(deps.map((_dep, position) => `v[${String(position)}]`).join(","))};const ${name}=()=>{let ${locals.join(",")};${frame.statements.join("")}return ${this.#slot(settleInOrder, "W")}([${pendings.join(",")}],${applyName});};`;
+        this.hoisted.push(settled);
+        return this.#define(`${name}()`);
+    }
+    #define(expression) {
+        const local = this.#local();
+        this.#statement(`${local} = ${expression};`);
+        return local;
+    }
+    #statement(statement) {
+        this.#frames.at(-1).statements.push(statement);
     }
     #local() {
-        const locals = this.#localsByFunction.at(-1);
+        const locals = this.#frames.at(-1).locals;
         const local = `t${String(locals.length)}`;
         locals.push(local);
         return local;
     }
     #singletonRead(binding, escape) {
-        const local = this.#local();
-        const slot = this.#slot(binding, "B");
-        return `((${local} = ${slot}.instance) === ${this.#slot(NO_INSTANCE, "N")} ? ${this.#slot(escape, "E")}() : ${local})`;
+        const local = this.#define(`${this.#slot(binding, "B")}.instance`);
+        this.#statement(`if (${local} === ${this.#slot(NO_INSTANCE, "N")}) ${local} = ${this.#slot(escape, "E")}();`);
+        return local;
     }
     // One parameter per distinct value, so a class constructed four times is one constructor with four sites.
     #slot(value, prefix) {

package/dist/resolution/resolver.d.ts

@@ -1,15 +1,15 @@
-import type { Container } from "#/container/container";
-import type { Binding } from "#/core/binding";
-import type { BindingRegistry } from "#/core/registry";
-import type { Token } from "#/core/token";
-import type { BindingTag, Constructor, ResolutionFrame, ResolveOptions } from "#/core/types";
-import type { ResolutionDiagnostics } from "#/errors/diagnostics";
-import type { LifecycleManager } from "#/lifecycle/lifecycle-manager";
-import type { ScopeManager } from "#/lifecycle/scope-manager";
-import type { MetadataReader } from "#/metadata/metadata-types";
-import type { DefaultLookupEntry } from "#/resolution/cache/binding-lookup-cache";
-import type { ResolverCallbacks } from "#/resolution/context";
-import type { BranchDepth } from "#/resolution/path/resolution-path";
+import type { Container } from "#container/container";
+import type { Binding } from "#core/binding";
+import type { BindingRegistry } from "#core/registry";
+import type { Token } from "#core/token";
+import type { BindingTag, Constructor, ResolutionFrame, ResolveOptions } from "#core/types";
+import type { ResolutionDiagnostics } from "#errors/diagnostics";
+import type { LifecycleManager } from "#lifecycle/lifecycle-manager";
+import type { ScopeManager } from "#lifecycle/scope-manager";
+import type { MetadataReader } from "#metadata/metadata-types";
+import type { DefaultLookupEntry } from "#resolution/cache/binding-lookup-cache";
+import type { ResolverCallbacks } from "#resolution/context";
+import type { BranchDepth } from "#resolution/path/resolution-path";
 /**
  * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
  *
@@ -65,12 +65,11 @@ export declare class DependencyResolver implements ResolverCallbacks {
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, branchDepth?: BranchDepth, precomputedCriterion?: BindingTag | null): Promise<Value | undefined>;
     resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, branchDepth?: BranchDepth): Promise<ReadonlyArray<Value>>;
     /**
-     * Entry for a request a factory makes from inside an open synchronous cascade.
+     * Entry for an options-less resolve the container starts: the root of a branch of its own.
      *
-     * @remarks A request arriving with no cascade open came out of a continuation, so its ancestors
-     * are on no call stack — it escapes to the branch lane.
+     * @remarks A statically-visible transient graph answers from its compiled async plan; everything
+     * else opens a branch over a fresh array, so every level's context keeps its own ancestors for as
+     * long as the factory holds it — across an `await` included.
      */
-    resolveAsyncFromCascade(token: Token<unknown> | Constructor): Promise<unknown>;
-    /** Entry for a resolve the container starts, which opens the cascade rather than joining one. */
     resolveAsyncFromRoot(token: Token<unknown> | Constructor): Promise<unknown>;
 }