@codefast/di 0.9.0 → 0.10.1

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

@@ -1,7 +1,8 @@
-import { NO_INSTANCE } from "#/core/binding";
-import { tokenName } from "#/core/token";
-import { AsyncResolutionError } from "#/errors/errors";
-import { injectionSlotToResolveOptions } from "#/injection/resolve-options";
+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;
@@ -46,13 +47,45 @@ function settleThenApply(deps, apply) {
  */
 export class InstantiationPlanCompiler {
     #host;
+    #generatedPlanCount = 0;
     constructor(host) {
         this.#host = host;
     }
+    /** Plans this compiler has generated as functions of their own. */
+    get generatedPlanCount() {
+        return this.#generatedPlanCount;
+    }
     compile(binding) {
-        return binding.kind === "class"
+        const compiled = binding.kind === "class"
             ? this.#compileClassPlan(binding, new Set(), 0, [])
             : this.#compileResolvedPlan(binding, new Set(), 0, []);
+        if (compiled === null || compiled === PLAN_RETRY) {
+            return compiled;
+        }
+        const host = this.#host;
+        return this.#tiered(compiled.run, () => generatePlan(compiled.node), (current, next) => host.replacePlan(binding, current, next));
+    }
+    /**
+     * The closure runs first; a plan that keeps running is generated as a function of its own and
+     * takes the closure's place in the host's map, so nothing resolved a few times ever compiles one.
+     */
+    #tiered(closure, generate, replace) {
+        if (!isPlanCodegenAvailable()) {
+            return closure;
+        }
+        let runs = 0;
+        const plan = () => {
+            runs += 1;
+            if (runs === PLAN_CODEGEN_THRESHOLD) {
+                const generated = generate();
+                if (generated !== null) {
+                    this.#generatedPlanCount += 1;
+                }
+                replace(plan, generated ?? closure);
+            }
+            return closure();
+        };
+        return plan;
     }
     /**
      * Re-entry into the runtime resolver for a dependency the plan can't see through.
@@ -67,7 +100,7 @@ export class InstantiationPlanCompiler {
         const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
         const depth = frames.length;
         let owned = [...frames];
-        return () => {
+        const run = () => {
             const stack = owned ?? [...frames];
             owned = undefined;
             try {
@@ -79,37 +112,42 @@ export class InstantiationPlanCompiler {
                 }
             }
         };
+        return { run, node: { kind: "thunk", run } };
     }
     // A resolved binding declares its deps as explicit descriptors — same rules as
     // class params, with the factory call (and its sync-only check) in place of `new`.
     #compileResolvedPlan(binding, compileStack, depth, ancestors) {
-        if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding)) {
+        if (binding.activationHook !== undefined || this.#host.hasActivationHandlers(binding)) {
             return null;
         }
         const factory = binding.factory;
         const tokenDisplayName = tokenName(binding.token);
-        const depThunks = new Array(binding.deps.length);
+        const deps = new Array(binding.deps.length);
         const depAncestors = [...ancestors, binding];
-        compileStack.add(binding.id);
+        compileStack.add(binding.identifier);
         try {
             for (let index = 0; index < binding.deps.length; index += 1) {
-                const thunk = this.#compileInjectionThunk(binding.deps[index], compileStack, depth, depAncestors);
-                if (thunk === PLAN_RETRY) {
-                    return thunk;
+                const dep = this.#compileInjectionThunk(binding.deps[index], compileStack, depth, depAncestors);
+                if (dep === PLAN_RETRY) {
+                    return dep;
                 }
-                depThunks[index] = thunk;
+                deps[index] = dep;
             }
         }
         finally {
-            compileStack.delete(binding.id);
+            compileStack.delete(binding.identifier);
         }
-        return () => {
-            const factoryResult = factory(...depThunks.map((thunk) => thunk()));
+        const runs = deps.map((dep) => dep.run);
+        const settle = (factoryResult) => {
             if (factoryResult instanceof Promise) {
                 throw new AsyncResolutionError(tokenDisplayName);
             }
             return factoryResult;
         };
+        return {
+            run: () => settle(factory(...runs.map((run) => run()))),
+            node: { kind: "call", factory, settle, deps: deps.map((dep) => dep.node) },
+        };
     }
     /**
      * One dependency of a plan node — a constructor param or a `toResolved` descriptor.
@@ -141,7 +179,7 @@ export class InstantiationPlanCompiler {
         return this.#compileDepThunk(entry, compileStack, depth, ancestors);
     }
     #compileClassPlan(binding, compileStack, depth, ancestors) {
-        if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding)) {
+        if (binding.activationHook !== undefined || this.#host.hasActivationHandlers(binding)) {
             return null;
         }
         const target = binding.target;
@@ -149,77 +187,105 @@ export class InstantiationPlanCompiler {
         if (hasPostConstruct === undefined) {
             return PLAN_RETRY;
         }
-        if (hasPostConstruct || this.#host.needsActiveContainer(target)) {
+        if (hasPostConstruct) {
+            return null;
+        }
+        // An accessor-injected class compiles only as the plan's root: its accessors resolve during
+        // construction with the class's own frame on the path, and a root has no static ancestors to replay.
+        const withAccessors = this.#host.needsActiveContainer(target);
+        if (withAccessors && depth !== 0) {
             return null;
         }
         const invokable = target;
         const meta = this.#host.getConstructorMetadata(target);
         if (meta === undefined) {
             // Metadata-less classes with required params throw on the runtime path — keep them there.
-            return target.length === 0 ? () => new invokable() : null;
+            if (target.length !== 0) {
+                return null;
+            }
+            return this.#classNode(binding, invokable, withAccessors, []);
         }
         const params = meta.params;
         if (params.length === 0) {
-            return () => new invokable();
+            return this.#classNode(binding, invokable, withAccessors, []);
         }
-        const depThunks = new Array(params.length);
+        const deps = new Array(params.length);
         const depAncestors = [...ancestors, binding];
-        compileStack.add(binding.id);
+        compileStack.add(binding.identifier);
         try {
             for (let index = 0; index < params.length; index += 1) {
-                const thunk = this.#compileInjectionThunk(params[index], compileStack, depth, depAncestors);
-                if (thunk === PLAN_RETRY) {
-                    return thunk;
+                const dep = this.#compileInjectionThunk(params[index], compileStack, depth, depAncestors);
+                if (dep === PLAN_RETRY) {
+                    return dep;
                 }
-                depThunks[index] = thunk;
+                deps[index] = dep;
             }
         }
         finally {
-            compileStack.delete(binding.id);
+            compileStack.delete(binding.identifier);
         }
-        switch (depThunks.length) {
+        return this.#classNode(binding, invokable, withAccessors, deps);
+    }
+    // The closure is hand-written per arity up to three so the common shapes spread nothing.
+    #classNode(binding, invokable, withAccessors, deps) {
+        const nodes = deps.map((dep) => dep.node);
+        if (withAccessors) {
+            const host = this.#host;
+            const construct = (values) => host.constructWithAccessors(binding, invokable, values);
+            const runs = deps.map((dep) => dep.run);
+            return { run: () => construct(runs.map((run) => run())), node: { kind: "accessors", construct, deps: nodes } };
+        }
+        const node = { kind: "construct", target: invokable, deps: nodes };
+        switch (deps.length) {
+            case 0:
+                return { run: () => new invokable(), node };
             case 1: {
-                const dep0 = depThunks[0];
-                return () => new invokable(dep0());
+                const dep0 = deps[0].run;
+                return { run: () => new invokable(dep0()), node };
             }
             case 2: {
-                const dep0 = depThunks[0];
-                const dep1 = depThunks[1];
-                return () => new invokable(dep0(), dep1());
+                const dep0 = deps[0].run;
+                const dep1 = deps[1].run;
+                return { run: () => new invokable(dep0(), dep1()), node };
             }
             case 3: {
-                const dep0 = depThunks[0];
-                const dep1 = depThunks[1];
-                const dep2 = depThunks[2];
-                return () => new invokable(dep0(), dep1(), dep2());
+                const dep0 = deps[0].run;
+                const dep1 = deps[1].run;
+                const dep2 = deps[2].run;
+                return { run: () => new invokable(dep0(), dep1(), dep2()), node };
+            }
+            default: {
+                const runs = deps.map((dep) => dep.run);
+                return { run: () => new invokable(...runs.map((run) => run())), node };
             }
-            default:
-                return () => new invokable(...depThunks.map((thunk) => thunk()));
         }
     }
     #compileDepThunk(entry, compileStack, depth, ancestors, options) {
         const { binding } = entry;
-        if (binding.kind === "constant" && binding.onActivation === undefined) {
+        if (binding.kind === "constant" && binding.activationHook === undefined) {
             if (!this.#host.hasActivationHandlers(binding)) {
                 const value = binding.value;
-                return () => value;
+                return { run: () => value, node: { kind: "value", value } };
             }
         }
         const scope = binding.scope;
         if (scope === "singleton") {
             // Cached-singleton read; the first materialization escapes so it sees the same ancestors
             // (and therefore the same cycle detection) the interpreted path would have built.
-            const escape = this.#compileEscapeThunk(binding.token, ancestors, "single", options);
+            const escape = this.#compileEscapeThunk(binding.token, ancestors, "single", options).run;
             const singletonBinding = binding;
-            return () => {
-                const cached = singletonBinding.instance;
-                return cached === NO_INSTANCE ? escape() : cached;
+            return {
+                run: () => {
+                    const cached = singletonBinding.instance;
+                    return cached === NO_INSTANCE ? escape() : cached;
+                },
+                node: { kind: "singleton", binding: singletonBinding, escape },
             };
         }
         if (scope === "transient" &&
             binding.kind === "class" &&
             depth < PLAN_DEPTH_LIMIT &&
-            !compileStack.has(binding.id)) {
+            !compileStack.has(binding.identifier)) {
             const inlined = this.#compileClassPlan(binding, compileStack, depth + 1, ancestors);
             if (inlined !== null) {
                 return inlined;
@@ -244,18 +310,17 @@ export class InstantiationPlanCompiler {
         if (node === null || node === PLAN_RETRY) {
             return node;
         }
-        return node.run;
+        const host = this.#host;
+        return this.#tiered(node.run, () => generateAsyncPlan(node.node), (current, next) => host.replaceAsyncPlan(binding, current, next));
     }
     #compileAsyncEscapeThunk(token, ancestors, arity = "single", options) {
         const host = this.#host;
         const frames = ancestors.map((ancestor) => host.getResolutionFrame(ancestor));
-        return {
-            run: () => host.resolveEscapedAsync(token, options, arity, [...frames]),
-            promiseShape: "always",
-        };
+        const run = () => host.resolveEscapedAsync(token, options, arity, [...frames]);
+        return { run, promiseShape: "always", node: { kind: "thunk", run } };
     }
     #compileAsyncClassNode(binding, compileStack, depth, ancestors) {
-        if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding)) {
+        if (binding.activationHook !== undefined || this.#host.hasActivationHandlers(binding)) {
             return null;
         }
         const target = binding.target;
@@ -268,17 +333,22 @@ export class InstantiationPlanCompiler {
         }
         const invokable = target;
         const meta = this.#host.getConstructorMetadata(target);
+        const leaf = {
+            run: () => new invokable(),
+            promiseShape: "never",
+            node: { kind: "construct", target: invokable, deps: [], awaits: false },
+        };
         if (meta === undefined) {
             // Metadata-less classes with required params throw on the runtime path — keep them there.
-            return target.length === 0 ? { run: () => new invokable(), promiseShape: "never" } : null;
+            return target.length === 0 ? leaf : null;
         }
         const params = meta.params;
         if (params.length === 0) {
-            return { run: () => new invokable(), promiseShape: "never" };
+            return leaf;
         }
         const depThunks = new Array(params.length);
         const depAncestors = [...ancestors, binding];
-        compileStack.add(binding.id);
+        compileStack.add(binding.identifier);
         try {
             for (let index = 0; index < params.length; index += 1) {
                 const thunk = this.#compileAsyncInjectionThunk(params[index], compileStack, depth, depAncestors);
@@ -289,36 +359,43 @@ export class InstantiationPlanCompiler {
             }
         }
         finally {
-            compileStack.delete(binding.id);
+            compileStack.delete(binding.identifier);
         }
+        const nodes = depThunks.map((thunk) => thunk.node);
         if (allSynchronous(depThunks)) {
+            const node = { kind: "construct", target: invokable, deps: nodes, awaits: false };
             switch (depThunks.length) {
                 case 1: {
                     const dep0 = depThunks[0].run;
-                    return { run: () => new invokable(dep0()), promiseShape: "never" };
+                    return { run: () => new invokable(dep0()), promiseShape: "never", node };
                 }
                 case 2: {
                     const dep0 = depThunks[0].run;
                     const dep1 = depThunks[1].run;
-                    return { run: () => new invokable(dep0(), dep1()), promiseShape: "never" };
+                    return { run: () => new invokable(dep0(), dep1()), promiseShape: "never", node };
                 }
                 default:
                     return {
                         run: () => new invokable(...depThunks.map((thunk) => thunk.run())),
                         promiseShape: "never",
+                        node,
                     };
             }
         }
-        return { run: settleThenApply(depThunks, (values) => new invokable(...values)), promiseShape: "always" };
+        return {
+            run: settleThenApply(depThunks, (values) => new invokable(...values)),
+            promiseShape: "always",
+            node: { kind: "construct", target: invokable, deps: nodes, awaits: true },
+        };
     }
     #compileAsyncResolvedNode(binding, compileStack, depth, ancestors) {
-        if (binding.onActivation !== undefined || this.#host.hasActivationHandlers(binding)) {
+        if (binding.activationHook !== undefined || this.#host.hasActivationHandlers(binding)) {
             return null;
         }
         const factory = binding.factory;
         const depThunks = new Array(binding.deps.length);
         const depAncestors = [...ancestors, binding];
-        compileStack.add(binding.id);
+        compileStack.add(binding.identifier);
         try {
             for (let index = 0; index < binding.deps.length; index += 1) {
                 const thunk = this.#compileAsyncInjectionThunk(binding.deps[index], compileStack, depth, depAncestors);
@@ -329,15 +406,24 @@ export class InstantiationPlanCompiler {
             }
         }
         finally {
-            compileStack.delete(binding.id);
+            compileStack.delete(binding.identifier);
         }
         // A sync-kind factory may still hand back a promise on this path — the async entry awaits it,
         // so the consumer is told to as well.
         const directShape = binding.kind === "resolved-async" ? "always" : "maybe";
+        const nodes = depThunks.map((thunk) => thunk.node);
         if (allSynchronous(depThunks)) {
-            return { run: () => factory(...depThunks.map((thunk) => thunk.run())), promiseShape: directShape };
+            return {
+                run: () => factory(...depThunks.map((thunk) => thunk.run())),
+                promiseShape: directShape,
+                node: { kind: "call", factory, deps: nodes, awaits: false },
+            };
         }
-        return { run: settleThenApply(depThunks, (values) => factory(...values)), promiseShape: "always" };
+        return {
+            run: settleThenApply(depThunks, (values) => factory(...values)),
+            promiseShape: "always",
+            node: { kind: "call", factory, deps: nodes, awaits: true },
+        };
     }
     /** Mirrors {@link InstantiationPlanCompiler.#compileInjectionThunk}, escaping through the async dispatch. */
     #compileAsyncInjectionThunk(descriptor, compileStack, depth, ancestors) {
@@ -364,28 +450,33 @@ export class InstantiationPlanCompiler {
     }
     #compileAsyncDepThunk(entry, compileStack, depth, ancestors, options) {
         const { binding } = entry;
-        if (binding.kind === "constant" && binding.onActivation === undefined) {
+        if (binding.kind === "constant" && binding.activationHook === undefined) {
             if (!this.#host.hasActivationHandlers(binding)) {
                 const value = binding.value;
                 // The interpreted path funnels every dependency through an await, which unwraps a
                 // promise-valued constant — so one compiles as needing that same await.
-                return { run: () => value, promiseShape: value instanceof Promise ? "always" : "never" };
+                return {
+                    run: () => value,
+                    promiseShape: value instanceof Promise ? "always" : "never",
+                    node: { kind: "value", value },
+                };
             }
         }
         const scope = binding.scope;
         if (scope === "singleton") {
             // Cached-singleton read; the cold materialization escapes with the same criteria.
-            const escape = this.#compileAsyncEscapeThunk(binding.token, ancestors, "single", options);
+            const escape = this.#compileAsyncEscapeThunk(binding.token, ancestors, "single", options).run;
             const singletonBinding = binding;
             return {
                 run: () => {
                     const cached = singletonBinding.instance;
-                    return cached === NO_INSTANCE ? escape.run() : cached;
+                    return cached === NO_INSTANCE ? escape() : cached;
                 },
                 promiseShape: "maybe",
+                node: { kind: "singleton", binding: singletonBinding, escape },
             };
         }
-        if (scope === "transient" && depth < PLAN_DEPTH_LIMIT && !compileStack.has(binding.id)) {
+        if (scope === "transient" && depth < PLAN_DEPTH_LIMIT && !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

@@ -0,0 +1,100 @@
+/**
+ * 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";
+/**
+ * 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.
+ *
+ * @since 0.10.0
+ */
+export declare const PLAN_CODEGEN_THRESHOLD = 32;
+/**
+ * The shape of a compiled sync plan: what its closure does, stated as data the generator can read.
+ *
+ * @remarks Every leaf the compiler could not see through is a `thunk` and stays opaque — generated
+ * code calls it exactly as the closure did, so an escape keeps its frames, its dispatch and its errors.
+ *
+ * @since 0.10.0
+ */
+export type PlanNode = {
+    readonly kind: "construct";
+    readonly target: ConstructorInvocation;
+    readonly deps: ReadonlyArray<PlanNode>;
+} | {
+    readonly kind: "accessors";
+    readonly construct: (deps: Array<unknown>) => unknown;
+    readonly deps: ReadonlyArray<PlanNode>;
+} | {
+    readonly kind: "call";
+    readonly factory: (...args: Array<unknown>) => unknown;
+    readonly settle: (result: unknown) => unknown;
+    readonly deps: ReadonlyArray<PlanNode>;
+} | {
+    readonly kind: "value";
+    readonly value: unknown;
+} | {
+    readonly kind: "singleton";
+    readonly binding: Binding;
+    readonly escape: () => unknown;
+} | {
+    readonly kind: "thunk";
+    readonly run: () => unknown;
+};
+/**
+ * The shape of a compiled async plan.
+ *
+ * @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.
+ *
+ * @since 0.10.0
+ */
+export type AsyncPlanNode = {
+    readonly kind: "construct";
+    readonly target: ConstructorInvocation;
+    readonly deps: ReadonlyArray<AsyncPlanNode>;
+    readonly awaits: boolean;
+} | {
+    readonly kind: "call";
+    readonly factory: (...args: Array<unknown>) => unknown;
+    readonly deps: ReadonlyArray<AsyncPlanNode>;
+    readonly awaits: boolean;
+} | {
+    readonly kind: "value";
+    readonly value: unknown;
+} | {
+    readonly kind: "singleton";
+    readonly binding: Binding;
+    readonly escape: () => unknown;
+} | {
+    readonly kind: "thunk";
+    readonly run: () => unknown;
+};
+/**
+ * Whether this runtime lets the engine compile a function from source.
+ *
+ * @remarks A Content Security Policy without `unsafe-eval` refuses the `Function` constructor; every
+ * plan then stays a closure, which behaves identically.
+ *
+ * @since 0.10.0
+ */
+export declare function isPlanCodegenAvailable(): boolean;
+/**
+ * Generates a plan as a function of its own, or `null` when the runtime refuses to compile one.
+ *
+ * @remarks The source carries a serial so no two plans share a compilation-cache entry: V8 keys
+ * type feedback by function literal, and one literal per plan is the whole point.
+ *
+ * @since 0.10.0
+ */
+export declare function generatePlan(node: PlanNode): (() => unknown) | null;
+/**
+ * Generates an async plan as a function of its own, or `null` when the runtime refuses to compile one.
+ *
+ * @since 0.10.0
+ */
+export declare function generateAsyncPlan(node: AsyncPlanNode): (() => unknown) | null;