@codefast/di 0.9.0 → 0.10.1

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

@@ -3,8 +3,8 @@
  *
  * @remarks Metadata cannot change once a class is defined, so nothing here needs version stamping.
  */
-import { runWithAmbientResolution } from "#/ambient/active-container";
-import { InvalidMetadataError } from "#/errors/errors";
+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();
@@ -21,6 +21,20 @@ function markVerified(cache, reader, target) {
     }
     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.
  *
@@ -31,16 +45,9 @@ function markVerified(cache, reader, target) {
  * @since 0.6.0
  */
 export function verifyConstructorMetadata(reader, target) {
-    const metadata = reader.getConstructorMetadata(target);
-    if (metadata === undefined) {
-        return undefined;
-    }
-    if (isVerified(verifiedTargets, reader, target)) {
-        return metadata;
-    }
-    assertConstructorMetadata(metadata, target);
-    markVerified(verifiedTargets, reader, target);
-    return metadata;
+    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.
@@ -81,29 +88,25 @@ export function assertConstructorMetadata(metadata, target) {
  * @since 0.6.0
  */
 export function verifyLifecycleMetadata(reader, target) {
-    const metadata = reader.getLifecycleMetadata(target);
-    if (metadata === undefined || isVerified(verifiedLifecycleTargets, reader, target)) {
-        return 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;
+    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}`);
         }
-        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`);
+        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`);
+                }
             }
         }
-    }
-    markVerified(verifiedLifecycleTargets, reader, target);
-    return metadata;
+    });
 }
 /**
  * A reader's accessor metadata for a class, verified the first time this process asks.
@@ -111,32 +114,37 @@ export function verifyLifecycleMetadata(reader, target) {
  * @since 0.6.0
  */
 export function verifyAccessorMetadata(reader, target) {
-    const metadata = reader.getAccessorMetadata?.(target);
-    if (metadata === undefined || isVerified(verifiedAccessorTargets, reader, target)) {
-        return 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`);
+    return verifyOnce(verifiedAccessorTargets, reader, target, reader.getAccessorMetadata?.(target), (metadata) => {
+        if (!Array.isArray(metadata)) {
+            throw new InvalidMetadataError(target.name, "accessor metadata: expected an array");
         }
-        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`);
+        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`);
+            }
         }
-    }
-    markVerified(verifiedAccessorTargets, reader, target);
-    return metadata;
+    });
+}
+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);
+    }
+    return caches;
 }
 /**
  * A per-class cache of constructor metadata and the activation facts derived from it.
@@ -144,24 +152,25 @@ export function verifyAccessorMetadata(reader, target) {
  * @since 0.5.0-canary.8
  */
 export class ClassIntrospector {
-    // Unallocated until the container resolves its first class binding — a container bound entirely
-    // to constants, factories or aliases never introspects one.
-    #constructorMetadata;
-    #hasPostConstruct;
-    #needsActiveContainer;
+    #caches;
     #reader;
     #container;
-    constructor(reader, container) {
+    constructor(reader, container, inherited) {
+        this.#caches = inherited !== undefined && inherited.#reader === reader ? inherited.#caches : undefined;
         this.#reader = reader;
         this.#container = container;
     }
+    #shared() {
+        return (this.#caches ??= cachesFor(this.#reader));
+    }
     constructorMetadata(target) {
-        const cached = this.#constructorMetadata?.get(target);
+        const caches = this.#shared();
+        const cached = caches.constructorMetadata?.get(target);
         if (cached !== undefined) {
             return cached === null ? undefined : cached;
         }
         const metadata = this.#reader.getConstructorMetadata(target);
-        (this.#constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
+        (caches.constructorMetadata ??= new WeakMap()).set(target, metadata ?? null);
         return metadata;
     }
     /**
@@ -170,18 +179,19 @@ export class ClassIntrospector {
      * @remarks Callers treat unknown as "assume it does", so the first activation settles it.
      */
     knownPostConstruct(target) {
-        return this.#hasPostConstruct?.get(target);
+        return this.#shared().hasPostConstruct?.get(target);
     }
     discoverPostConstruct(target) {
         const lifecycle = this.#reader.getLifecycleMetadata(target);
-        (this.#hasPostConstruct ??= new WeakMap()).set(target, lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0);
+        (this.#shared().hasPostConstruct ??= new WeakMap()).set(target, lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0);
     }
     /** True when the class has accessor injection, which reads the container during construction. */
     needsActiveContainer(target) {
-        let needsActiveContainer = this.#needsActiveContainer?.get(target);
+        const caches = this.#shared();
+        let needsActiveContainer = caches.needsActiveContainer?.get(target);
         if (needsActiveContainer === undefined) {
             needsActiveContainer = (this.#reader.getAccessorMetadata?.(target)?.length ?? 0) > 0;
-            (this.#needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
+            (caches.needsActiveContainer ??= new WeakMap()).set(target, needsActiveContainer);
         }
         return needsActiveContainer;
     }
@@ -190,6 +200,9 @@ export class ClassIntrospector {
         if (!this.needsActiveContainer(target)) {
             return new invokable(...deps);
         }
-        return runWithAmbientResolution(this.#container, resolution, () => new invokable(...deps));
+        if (resolution === undefined) {
+            return runWithAmbientResolution(this.#container, undefined, () => new invokable(...deps));
+        }
+        return constructWithAmbientResolution(this.#container, resolution, invokable, deps);
     }
 }

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 { BindingIdentifier, BindingKind, BindingScope, ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#/core/types";
-import type { BranchDepth, OwnedBranchStack } from "#/resolution/path/resolution-path";
+import type { Token } from "#core/token";
+import type { BindingIdentifier, BindingKind, BindingScope, ConstraintContext, Constructor, ResolutionFrame, ResolutionContext, ResolveOptions } from "#core/types";
+import type { BranchDepth, OwnedBranchStack } from "#resolution/path/resolution-path";
 /**
  * The engine surface a resolution context calls back into to resolve further dependencies.
  *
@@ -16,8 +16,8 @@ export interface ResolverCallbacks {
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<Array<Value>>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): ReadonlyArray<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options: ResolveOptions | undefined, resolutionStack: Array<ResolutionFrame>): Promise<ReadonlyArray<Value>>;
 }
 /**
  * The `ResolutionContext` handed to factories and hooks, backed by the engine's callbacks.
@@ -33,8 +33,8 @@ export declare class DefaultResolutionContext implements ResolutionContext {
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
 }
 /**
  * One async level's resolution context, which is also its branch of the resolution stack.
@@ -59,8 +59,8 @@ export declare class AsyncLevelContext implements ResolutionContext {
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
 }
 /**
  * The one context every level of an open synchronous factory cascade shares.
@@ -78,8 +78,8 @@ export declare class AsyncCascadeContext implements ResolutionContext {
     resolveAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value>;
     resolveOptional<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Value | undefined;
     resolveOptionalAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Value | undefined>;
-    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Array<Value>;
-    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<Array<Value>>;
+    resolveAll<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): ReadonlyArray<Value>;
+    resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, options?: ResolveOptions): Promise<ReadonlyArray<Value>>;
 }
 /**
  * Creates the resolution-stack frame for one in-flight resolve.

package/dist/resolution/context.js

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

package/dist/resolution/path/resolution-path.d.ts

@@ -1,4 +1,4 @@
-import type { BindingIdentifier, ResolutionFrame } from "#/core/types";
+import type { BindingIdentifier, ResolutionFrame } from "#core/types";
 /**
  * Where the cycle check switches from a linear frame scan to an attached Set.
  *

package/dist/resolution/path/resolution-path.js

@@ -1,5 +1,5 @@
 /** Cycle-detection bookkeeping carried on the resolution stack itself. */
-import { CircularDependencyError } from "#/errors/errors";
+import { CircularDependencyError } from "#errors/errors";
 const RESOLUTION_SET_KEY = Symbol("di:resolution-set");
 /**
  * Where the cycle check switches from a linear frame scan to an attached Set.

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

@@ -4,10 +4,11 @@
  * @remarks A dependency the compiler cannot inline escapes to a resolver callback instead; the
  * closure must stay callable for it, which is what bounds what may be inlined.
  */
-import type { Binding } from "#/core/binding";
-import type { Token } from "#/core/token";
-import type { Constructor, ResolutionFrame, ResolveOptions } from "#/core/types";
-import type { ConstructorMetadata } from "#/metadata/metadata-types";
+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";
 /**
  * Compilation asked to retry later (class lifecycle metadata not discovered yet).
  *
@@ -41,6 +42,11 @@ export interface InstantiationPlanHost {
     /** Cached postConstruct presence — `undefined` until a runtime resolve discovers it. */
     knownPostConstruct(target: Constructor): boolean | undefined;
     needsActiveContainer(target: Constructor): boolean;
+    /**
+     * Constructs a class whose accessors resolve during construction, with the container ambient and
+     * the binding's frame on the path so an accessor that cycles back is still caught.
+     */
+    constructWithAccessors(binding: Binding, target: ConstructorInvocation, deps: Array<unknown>): unknown;
     getConstructorMetadata(target: Constructor): ConstructorMetadata | undefined;
     /** Options-less lookup with alias hops folded; `null` when the fast lane can't answer. */
     lookupDependencyEntry(token: Token<unknown> | Constructor): InstantiationPlanDependencyEntry | null;
@@ -54,6 +60,10 @@ export interface InstantiationPlanHost {
     lookupPathIndependentEntry(token: Token<unknown> | Constructor, options: ResolveOptions): InstantiationPlanDependencyEntry | null;
     /** The frame the interpreted path pushes for this binding, so escapes can replay it. */
     getResolutionFrame(binding: Binding): ResolutionFrame;
+    /** Swaps a plan the host still holds for its successor; a plan the host has since dropped stays dropped. */
+    replacePlan(binding: Binding, current: () => unknown, next: () => unknown): void;
+    /** The async counterpart of {@link InstantiationPlanHost.replacePlan}, over the async plan map. */
+    replaceAsyncPlan(binding: Binding, current: () => unknown, next: () => unknown): void;
     /** Runtime resolve for an escaped dependency, seeded with the ancestor frames above it. */
     resolveEscaped(token: Token<unknown> | Constructor, options: ResolveOptions | undefined, arity: EscapeArity, resolutionStack: Array<ResolutionFrame>): unknown;
     /** The async counterpart of {@link InstantiationPlanHost.resolveEscaped}, replaying the async dispatch. */
@@ -74,6 +84,8 @@ export type EscapeArity = "all" | "optional" | "single";
 export declare class InstantiationPlanCompiler {
     #private;
     constructor(host: InstantiationPlanHost);
+    /** Plans this compiler has generated as functions of their own. */
+    get generatedPlanCount(): number;
     compile(binding: Binding & {
         kind: "class" | "resolved";
     }): InstantiationPlanCompileResult;