@codefast/di 0.11.0 → 0.12.0

package/dist/resolution/cache/class-introspector.js

@@ -3,175 +3,69 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import { constructWithAmbientResolution, runWithAmbientResolution } from "#ambient/active-container";
-import { InvalidMetadataError } from "#errors/errors";
-// Verified pairs, not verified classes: two readers may disagree about the same class, and a reader
-// that goes out of scope takes its record with it.
-const verifiedTargets = new WeakMap();
-const verifiedLifecycleTargets = new WeakMap();
-const verifiedAccessorTargets = new WeakMap();
-function isVerified(cache, reader, target) {
-    return cache.get(reader)?.has(target) ?? false;
-}
-function markVerified(cache, reader, target) {
-    let verified = cache.get(reader);
-    if (verified === undefined) {
-        verified = new WeakSet();
-        cache.set(reader, verified);
-    }
-    verified.add(target);
-}
-/**
- * Runs `validate` against a reader's metadata the first time this process sees the pair, then remembers it.
- *
- * @remarks An absent metadata answer needs no check; a verified pair is returned untouched, so the
- * shape assertion runs once per `(reader, target)` rather than per container.
- */
-function verifyOnce(cache, reader, target, metadata, validate) {
-    if (metadata === undefined || isVerified(cache, reader, target)) {
-        return metadata;
-    }
-    validate(metadata);
-    markVerified(cache, reader, target);
-    return metadata;
-}
-/**
- * A reader's constructor metadata for a class, verified the first time this process asks.
- *
- * @remarks Metadata cannot change once a class is defined, so re-checking per container would charge
- * every fresh container for a fact already established — a per-request child or a cold boot pays
- * that repeatedly.
- *
- * @since 0.6.0
- */
-export function verifyConstructorMetadata(reader, target) {
-    return verifyOnce(verifiedTargets, reader, target, reader.getConstructorMetadata(target), (metadata) => {
-        assertConstructorMetadata(metadata, target);
-    });
-}
-/**
- * Verifies what a reader claims about a class, since a `MetadataReader` is a public seam.
- *
- * @remarks Every path that reads constructor metadata comes through here, so a reader that answers
- * wrongly is a named error at the class it described rather than a `TypeError` raised later inside a
- * resolve. Only what a consumer dereferences is checked: `params` and each entry's `token`.
- * `optional`/`multi` degrade to falsy without crashing, and `index` is decorative — dependencies are
- * consumed positionally.
- *
- * @since 0.6.0
- */
-export function assertConstructorMetadata(metadata, target) {
-    if (metadata === undefined) {
-        return undefined;
-    }
-    if (typeof metadata !== "object" || metadata === null) {
-        throw new InvalidMetadataError(target.name, `constructor metadata: expected an object, received ${typeof metadata}`);
-    }
-    const params = Reflect.get(metadata, "params");
-    if (!Array.isArray(params)) {
-        throw new InvalidMetadataError(target.name, "constructor metadata: params is not an array");
-    }
-    for (const [position, param] of params.entries()) {
-        if (typeof param !== "object" || param === null) {
-            throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}] is not an object`);
-        }
-        const dependency = Reflect.get(param, "token");
-        if (typeof dependency !== "object" && typeof dependency !== "function") {
-            throw new InvalidMetadataError(target.name, `constructor metadata: params[${String(position)}].token is not a token or a class`);
-        }
-    }
-    return metadata;
-}
-/**
- * A reader's lifecycle metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export function verifyLifecycleMetadata(reader, target) {
-    return verifyOnce(verifiedLifecycleTargets, reader, target, reader.getLifecycleMetadata(target), (metadata) => {
-        if (typeof metadata !== "object" || metadata === null) {
-            throw new InvalidMetadataError(target.name, `lifecycle metadata: expected an object, received ${typeof metadata}`);
-        }
-        for (const phase of ["postConstruct", "preDestroy"]) {
-            const methods = Reflect.get(metadata, phase);
-            if (methods === undefined) {
-                continue;
-            }
-            if (!Array.isArray(methods)) {
-                throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase} is not an array`);
-            }
-            for (const [position, name] of methods.entries()) {
-                if (typeof name !== "string") {
-                    throw new InvalidMetadataError(target.name, `lifecycle metadata: ${phase}[${String(position)}] is not a string`);
-                }
-            }
-        }
-    });
-}
-/**
- * A reader's accessor metadata for a class, verified the first time this process asks.
- *
- * @since 0.6.0
- */
-export function verifyAccessorMetadata(reader, target) {
-    return verifyOnce(verifiedAccessorTargets, reader, target, reader.getAccessorMetadata?.(target), (metadata) => {
-        if (!Array.isArray(metadata)) {
-            throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
-        }
-        for (const [position, entry] of metadata.entries()) {
-            if (typeof entry !== "object" || entry === null) {
-                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}] is not an object`);
-            }
-            const key = Reflect.get(entry, "key");
-            if (typeof key !== "string" && typeof key !== "symbol") {
-                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].key is not a string or symbol`);
-            }
-            const descriptor = Reflect.get(entry, "descriptor");
-            if (typeof descriptor !== "object" || descriptor === null) {
-                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor is not an object`);
-            }
-            const dependency = Reflect.get(descriptor, "token");
-            if (typeof dependency !== "object" && typeof dependency !== "function") {
-                throw new InvalidMetadataError(target.name, `accessor metadata: [${String(position)}].descriptor.token is not a token or a class`);
-            }
-        }
-    });
-}
-const cachesByReader = new WeakMap();
-function cachesFor(reader) {
-    let caches = cachesByReader.get(reader);
-    if (caches === undefined) {
-        caches = { constructorMetadata: undefined, hasPostConstruct: undefined, needsActiveContainer: undefined };
-        cachesByReader.set(reader, caches);
+import { constructWithAmbientResolution, runWithAmbientResolution } from "#ambient-container";
+// A reader answers from the class alone, so its facts are shared by every container reading through it.
+const factsByReader = new WeakMap();
+function factsFor(reader) {
+    let byClass = factsByReader.get(reader);
+    if (byClass === undefined) {
+        byClass = new WeakMap();
+        factsByReader.set(reader, byClass);
     }
-    return caches;
+    return byClass;
 }
 /**
  * A per-class cache of constructor metadata and the activation facts derived from it.
  *
+ * @remarks A child inheriting its parent's reader takes the parent's facts too, and resolves a class
+ * the parent already met without reading its metadata again; a root finds them by reader on its first
+ * question.
+ *
  * @since 0.5.0-canary.8
  */
 export class ClassIntrospector {
-    #caches;
+    #byClass;
+    // The class asked about last and its record: a cold resolve asks about one class several times in a row.
+    #lastTarget;
+    #lastFacts;
     #reader;
     #container;
     constructor(reader, container, inherited) {
-        this.#caches = inherited !== undefined && inherited.#reader === reader ? inherited.#caches : undefined;
+        this.#byClass = inherited !== undefined && inherited.#reader === reader ? inherited.#byClass : undefined;
         this.#reader = reader;
         this.#container = container;
     }
-    #shared() {
-        return (this.#caches ??= cachesFor(this.#reader));
+    /** The record of what this reader has answered about a class, allocated on the class's first question. */
+    facts(target) {
+        if (target === this.#lastTarget) {
+            return this.#lastFacts;
+        }
+        const byClass = (this.#byClass ??= factsFor(this.#reader));
+        let facts = byClass.get(target);
+        if (facts === undefined) {
+            facts = {
+                constructorMetadata: undefined,
+                hasPostConstruct: undefined,
+                needsActiveContainer: undefined,
+                params: undefined,
+            };
+            byClass.set(target, facts);
+        }
+        this.#lastTarget = target;
+        this.#lastFacts = facts;
+        return facts;
     }
     constructorMetadata(target) {
-        const caches = this.#shared();
-        const cached = caches.constructorMetadata?.get(target);
-        if (cached !== undefined) {
-            return cached === null ? undefined : cached;
+        return this.constructorMetadataOf(target, this.facts(target));
+    }
+    /** The constructor metadata of a class whose facts the caller already holds. */
+    constructorMetadataOf(target, facts) {
+        let metadata = facts.constructorMetadata;
+        if (metadata === undefined) {
+            metadata = this.#reader.getConstructorMetadata(target) ?? null;
+            facts.constructorMetadata = metadata;
         }
-        const metadata = this.#reader.getConstructorMetadata(target);
-        (caches.constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
-        return metadata;
+        return metadata === null ? undefined : metadata;
     }
     /**
      * The nearest ancestor's own constructor metadata, for a subclass that declares none of its own.
@@ -197,26 +91,34 @@ export class ClassIntrospector {
      * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
      */
     knownPostConstruct(target) {
-        return this.#shared().hasPostConstruct?.get(target);
+        return this.facts(target).hasPostConstruct;
     }
     discoverPostConstruct(target) {
         const lifecycle = this.#reader.getLifecycleMetadata(target);
-        (this.#shared().hasPostConstruct ??= new WeakMap()).set(target, lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0);
+        this.facts(target).hasPostConstruct =
+            lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0;
     }
     /** True when the class has accessor injection, which reads the container during construction. */
     needsActiveContainer(target) {
-        const caches = this.#shared();
-        let needsActiveContainer = caches.needsActiveContainer?.get(target);
+        return this.needsActiveContainerOf(target, this.facts(target));
+    }
+    /** Whether a class whose facts the caller already holds reads the container during construction. */
+    needsActiveContainerOf(target, facts) {
+        let needsActiveContainer = facts.needsActiveContainer;
         if (needsActiveContainer === undefined) {
             needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
-            (caches.needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+            facts.needsActiveContainer = needsActiveContainer;
         }
         return needsActiveContainer;
     }
     instantiate(target, deps, resolution) {
+        return this.construct(target, deps, this.needsActiveContainer(target), resolution);
+    }
+    /** Builds an instance whose accessor need the caller already knows; an empty `deps` is a call with no arguments. */
+    construct(target, deps, needsActiveContainer, resolution) {
         const invokable = target;
-        if (!this.needsActiveContainer(target)) {
-            return new invokable(...deps);
+        if (!needsActiveContainer) {
+            return deps.length === 0 ? new invokable() : new invokable(...deps);
         }
         if (resolution === undefined) {
             return runWithAmbientResolution(this.#container, undefined, () => new invokable(...deps));

package/dist/resolution/cache/{binding-lookup-cache.d.ts → lookup.d.ts}

@@ -25,7 +25,8 @@ export interface DefaultLookupEntry<Owner> {
  *
  * @remarks `values` is kept only while every member is a hook-free constant or a hook-free singleton
  * whose instance is cached, and `activationVersion` is the chain's activation version that promise was
- * made under.
+ * made under. It is settled on the read that repeats the first, which `readBefore` records, so a
+ * container read once never builds it.
  *
  * @since 0.10.0
  */
@@ -33,6 +34,7 @@ export interface CollectionEntry {
     readonly candidates: ReadonlyArray<Binding>;
     values: ReadonlyArray<unknown> | undefined;
     activationVersion: number;
+    readBefore: boolean;
 }
 /**
  * A version-stamped cache of binding lookups by token and criterion across the container chain.
@@ -65,6 +67,9 @@ export declare class BindingLookupCache<Owner> {
     namedTaggedEntry(token: Token<unknown> | Constructor, nameCriterion: BindingTag, tag: BindingTag): DefaultLookupEntry<Owner> | null;
     /** The memoized root-level collection for a token, or `undefined` once the chain changed since it was stored. */
     collection(token: Token<unknown> | Constructor): CollectionEntry | undefined;
-    /** Stores a root-level collection under the chain version the last `collection()` read stamped. */
+    /**
+     * Stores a root-level collection under the chain version the last `collection()` read stamped, so a
+     * predicate that binds during the gather leaves the entry stale rather than current.
+     */
     rememberCollection(token: Token<unknown> | Constructor, entry: CollectionEntry): void;
 }

package/dist/resolution/cache/{binding-lookup-cache.js → lookup.js}

@@ -29,9 +29,9 @@ export class BindingLookupCache {
     #lastTagToken;
     #lastTag;
     #lastTaggedEntry = null;
-    // Root-level collections by token, stamped with the chain version like the two memos above.
+    // Root-level collections, stamped with the chain version like the memos above. Deferred into one object,
+    // because every per-request child builds this cache and almost none reads a collection at the root.
     #collections;
-    #collectionsVersion = -1;
     #registry;
     #owner;
     #parent;
@@ -171,16 +171,48 @@ export class BindingLookupCache {
     /** The memoized root-level collection for a token, or `undefined` once the chain changed since it was stored. */
     collection(token) {
         const version = this.chainVersion();
-        if (version !== this.#collectionsVersion) {
-            this.#collections?.clear();
-            this.#collectionsVersion = version;
+        const memo = this.#collections;
+        if (memo === undefined) {
+            this.#collections = { version, lastToken: undefined, lastEntry: undefined, byToken: undefined };
             return undefined;
         }
-        return this.#collections?.get(token);
+        if (version !== memo.version) {
+            memo.version = version;
+            memo.byToken?.clear();
+            // The rebuild that follows can throw, so the entry in front must not outlive the generation.
+            memo.lastToken = undefined;
+            return undefined;
+        }
+        if (token === memo.lastToken) {
+            return memo.lastEntry;
+        }
+        const entry = memo.byToken?.get(token);
+        if (entry !== undefined) {
+            memo.lastToken = token;
+            memo.lastEntry = entry;
+        }
+        return entry;
     }
-    /** Stores a root-level collection under the chain version the last `collection()` read stamped. */
+    /**
+     * Stores a root-level collection under the chain version the last `collection()` read stamped, so a
+     * predicate that binds during the gather leaves the entry stale rather than current.
+     */
     rememberCollection(token, entry) {
-        (this.#collections ??= new Map()).set(token, entry);
+        const memo = this.#collections;
+        if (memo === undefined) {
+            return;
+        }
+        if (memo.byToken !== undefined) {
+            memo.byToken.set(token, entry);
+        }
+        else if (memo.lastToken !== undefined && memo.lastEntry !== undefined) {
+            memo.byToken = new Map([
+                [memo.lastToken, memo.lastEntry],
+                [token, entry],
+            ]);
+        }
+        memo.lastToken = token;
+        memo.lastEntry = entry;
     }
     /**
      * Follows alias hops to the terminal entry, or declines with `null` on a cycle, which the full

package/dist/resolution/context.d.ts

@@ -1,7 +1,7 @@
 /** The `ResolutionContext` a factory is handed, and the callbacks the resolver answers it with. */
 import type { Token } from "#core/token";
 import type { ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#core/types";
-import type { BranchDepth, OwnedBranchStack } from "#resolution/path/resolution-path";
+import type { BranchDepth, OwnedBranchStack } from "#resolution/path";
 /**
  * The engine surface a resolution context calls back into to resolve further dependencies.
  *

package/dist/resolution/context.js

@@ -1,4 +1,4 @@
-import { bindingsOf, enterSeededPath, leaveSeededPath, UNOWNED_BRANCH } from "#resolution/path/resolution-path";
+import { bindingsOf, enterSeededPath, leaveSeededPath, UNOWNED_BRANCH } from "#resolution/path";
 /**
  * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
  *

package/dist/resolution/{path/resolution-path.js → path.js}

@@ -1,5 +1,5 @@
 /** Cycle-detection bookkeeping carried on the resolution stack itself. */
-import { CircularDependencyError } from "#errors/errors";
+import { CircularDependencyError } from "#errors";
 /** The key under which a resolver-built frame carries its binding, for marking a seeded path. */
 const FRAME_BINDING = Symbol("di:frame-binding");
 /**

package/dist/resolution/plan/{plan-codegen.d.ts → codegen.d.ts}

@@ -6,10 +6,8 @@ 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 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.
+ * @remarks A measured policy: the generated function costs a compile and a warm-up, so it repays only over
+ * many runs of one plan in one container, and a cold container or a per-request child keeps the closure.
  *
  * @since 0.10.0
  */

package/dist/resolution/plan/{plan-codegen.js → codegen.js}

@@ -3,10 +3,8 @@ import { settleInOrder } from "#resolution/async-fan-out";
 /**
  * The number of runs a plan's closure makes before the plan is generated as its own function.
  *
- * @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.
+ * @remarks A measured policy: the generated function costs a compile and a warm-up, so it repays only over
+ * many runs of one plan in one container, and a cold container or a per-request child keeps the closure.
  *
  * @since 0.10.0
  */

package/dist/resolution/plan/{instantiation-plan.d.ts → compiler.d.ts}

@@ -8,7 +8,7 @@ import type { Binding } from "#core/binding";
 import type { ConstructorInvocation } from "#core/constructor-type";
 import type { Token } from "#core/token";
 import type { Constructor, ResolutionFrame, ResolveOptions } from "#core/types";
-import type { ConstructorMetadata } from "#metadata/metadata-types";
+import type { ConstructorMetadata } from "#metadata/types";
 /**
  * Compilation asked to retry later (class lifecycle metadata not discovered yet).
  *

package/dist/resolution/plan/{instantiation-plan.js → compiler.js}

@@ -1,10 +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 { AsyncResolutionError } from "#errors";
+import { injectionSlotToResolveOptions } from "#injection/dependency-slot";
 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";
+import { enterSeededPath, leaveSeededPath } from "#resolution/path";
+import { generateAsyncPlan, generatePlan, isPlanCodegenAvailable, PLAN_CODEGEN_THRESHOLD, } from "#resolution/plan/codegen";
 /**
  * Compilation asked to retry later (class lifecycle metadata not discovered yet).
  *

package/dist/resolution/resolver.d.ts

@@ -3,13 +3,13 @@ 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 { ResolutionDiagnostics } from "#introspection/diagnostics";
+import type { LifecycleManager } from "#lifecycle/hooks";
+import type { ScopeManager } from "#lifecycle/scopes";
+import type { MetadataReader } from "#metadata/types";
+import type { DefaultLookupEntry } from "#resolution/cache/lookup";
 import type { ResolverCallbacks } from "#resolution/context";
-import type { BranchDepth } from "#resolution/path/resolution-path";
+import type { BranchDepth } from "#resolution/path";
 /**
  * The resolution engine driving binding selection, instantiation, scoping, and lifecycle hooks.
  *
@@ -51,7 +51,7 @@ export declare class DependencyResolver implements ResolverCallbacks {
      * 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. */
+    /** The async twin of `resolveRootCollection`: a stable value list answers 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>;
     /**