@codefast/di 0.8.1 → 0.10.0

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

@@ -0,0 +1,185 @@
+import { NO_INSTANCE } from "#/core/binding";
+/**
+ * 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 const PLAN_CODEGEN_THRESHOLD = 32;
+const rejectWith = (error) => Promise.reject(error);
+let codegenAvailable;
+let generatedCount = 0;
+/**
+ * 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 function isPlanCodegenAvailable() {
+    if (codegenAvailable === undefined) {
+        try {
+            // The one probe of the constructor this module exists to use; a refusal here disables it for good.
+            // oxlint-disable-next-line typescript/no-implied-eval
+            codegenAvailable = new Function("return true")() === true;
+        }
+        catch {
+            codegenAvailable = false;
+        }
+    }
+    return codegenAvailable;
+}
+/**
+ * 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 function generatePlan(node) {
+    if (!isPlanCodegenAvailable()) {
+        return null;
+    }
+    const emitter = new PlanEmitter();
+    return compileRendered(emitter, emitter.expression(node));
+}
+/**
+ * Generates an async plan as a function of its own, or `null` when the runtime refuses to compile one.
+ *
+ * @since 0.10.0
+ */
+export function generateAsyncPlan(node) {
+    if (!isPlanCodegenAvailable()) {
+        return null;
+    }
+    const emitter = new PlanEmitter();
+    return compileRendered(emitter, emitter.asyncExpression(node));
+}
+function compileRendered(emitter, expression) {
+    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};};`;
+    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
+        const factory = new Function(...emitter.names, body);
+        return factory(...emitter.values);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Renders a plan tree as one expression 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.
+ */
+class PlanEmitter {
+    names = [];
+    values = [];
+    hoisted = [];
+    #localsByFunction = [[]];
+    #hoistedCount = 0;
+    #slotByValue = new Map();
+    /** The plan function's own temporaries. */
+    get locals() {
+        return this.#localsByFunction[0];
+    }
+    expression(node) {
+        switch (node.kind) {
+            case "construct":
+                return `new ${this.#slot(node.target, "C")}(${this.#list(node.deps)})`;
+            case "accessors":
+                return `${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})`;
+            }
+            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")}()`;
+        }
+    }
+    asyncExpression(node) {
+        switch (node.kind) {
+            case "construct": {
+                const target = this.#slot(node.target, "C");
+                return node.awaits
+                    ? this.#settled(node.deps, (values) => `new ${target}(${values})`)
+                    : `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)})`;
+            }
+            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")}()`;
+        }
+    }
+    #list(deps) {
+        return deps.map((dep) => this.expression(dep)).join(", ");
+    }
+    #asyncList(deps) {
+        return deps.map((dep) => this.asyncExpression(dep)).join(", ");
+    }
+    // Every dependency starts in order, a sync throw becomes that slot's rejection so its siblings still
+    // start, and the node applies to the settled values — the interpreted async path, rendered.
+    #settled(deps, apply) {
+        const index = this.#hoistedCount;
+        this.#hoistedCount += 1;
+        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 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);}`);
+        }
+        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}()`;
+    }
+    #local() {
+        const locals = this.#localsByFunction.at(-1);
+        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})`;
+    }
+    // One parameter per distinct value, so a class constructed four times is one constructor with four sites.
+    #slot(value, prefix) {
+        let name = this.#slotByValue.get(value);
+        if (name === undefined) {
+            name = `${prefix}${String(this.names.length)}`;
+            this.#slotByValue.set(value, name);
+            this.names.push(name);
+            this.values.push(value);
+        }
+        return name;
+    }
+}

package/dist/resolution/resolver.d.ts

@@ -29,8 +29,8 @@ export declare class DependencyResolver implements ResolverCallbacks {
     constructor(registry: BindingRegistry, scope: ScopeManager, lifecycle: LifecycleManager, metadataReader: MetadataReader, container: Container, parent: DependencyResolver | undefined);
     /** The reader this resolver was built with, which is the one its container answers with. */
     get metadataReader(): MetadataReader;
-    /** Structural counts for the {@link ResolutionDiagnostics} a container reports. */
-    describeCaches(): Pick<ResolutionDiagnostics, "compiledPlanCount" | "compiledAsyncPlanCount" | "syncContextPoolSize">;
+    /** Structural counts and the resolver-owned collaborators built so far, for the {@link ResolutionDiagnostics} a container reports. */
+    describeCaches(): Pick<ResolutionDiagnostics, "compiledPlanCount" | "compiledAsyncPlanCount" | "generatedPlanCount" | "syncContextPoolSize" | "builtSubsystems">;
     /**
      * Binding lookup aligned with `resolve` — used by `Container.validate` without instantiating.
      */
@@ -42,7 +42,17 @@ export declare class DependencyResolver implements 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>, precomputedCriterion?: BindingTag | null): Value;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, precomputedCriterion?: BindingTag | null): Value | undefined;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Array<Value>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): ReadonlyArray<Value>;
+    /**
+     * A root-level, options-less collection read through its memo: the value list when it is stable,
+     * the candidate list otherwise.
+     *
+     * @remarks Its own entry rather than a branch in `resolveAll`, so the options lane keeps the exact
+     * shape it had; the container routes a top-level read with no options here.
+     */
+    resolveRootCollection<Value>(token: Token<Value> | Constructor<Value>): ReadonlyArray<Value>;
+    /** The async twin of `resolveRootCollection`: a stable value list settles at once, candidates fan out as usual. */
+    resolveRootCollectionAsync<Value>(token: Token<Value> | Constructor<Value>): Promise<ReadonlyArray<Value>>;
     resolveAsyncFromContext<Value>(token: Token<Value> | Constructor<Value>, resolutionStack: Array<ResolutionFrame>, branchDepth: BranchDepth): Promise<Value>;
     /**
      * Instantiates one owned binding directly, bypassing selection.
@@ -53,7 +63,7 @@ export declare class DependencyResolver implements ResolverCallbacks {
     warmBindingAsync(binding: Binding, options: ResolveOptions | undefined): Promise<unknown>;
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>, branchDepth?: BranchDepth, precomputedCriterion?: BindingTag | null): Promise<Value>;
     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<Array<Value>>;
+    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.
      *