@codefast/di 1.0.0-canary.6 → 1.0.0-canary.7

package/dist/resolver.js

@@ -0,0 +1,1208 @@
+import { selectAllBindings, selectBinding } from "#/binding-select";
+import { buildResolutionFrame, DefaultResolutionContext, runWithContainer } from "#/environment";
+import { AsyncResolutionError, CircularDependencyError, InternalError, MissingMetadataError, MissingScopeContextError, NoMatchingBindingError, TokenNotBoundError, } from "#/errors";
+import { injectionSlotToResolveOptions } from "#/resolve-options";
+import { tokenName } from "#/token";
+const RESOLUTION_SET_KEY = Symbol("di:resolution-set");
+const RESOLUTION_SET_THRESHOLD = 32;
+const EMPTY_STRING_LIST = [];
+const EMPTY_FRAME_LIST = [];
+const ROOT_CONSTRAINT_CONTEXT = {
+    resolutionPath: EMPTY_STRING_LIST,
+    resolutionStack: EMPTY_FRAME_LIST,
+    parent: undefined,
+    ancestors: EMPTY_FRAME_LIST,
+    currentResolveOptions: undefined,
+};
+/**
+ * @since 0.3.16-canary.0
+ */
+export class DependencyResolver {
+    _registry;
+    _scope;
+    _lifecycle;
+    _metadataReader;
+    _container;
+    _parent;
+    _frameByBindingId = new Map();
+    _syncResolutionContextPool = [];
+    // Deep-path state for _resolveTransientDynamicSyncFromContext (depth ≥ RESOLUTION_SET_THRESHOLD):
+    //
+    // Cycle detection — generation-based marking (replaces Set<BindingIdentifier>):
+    //   _deepCycleMarks: Map<BindingIdentifier, generation> records which bindings are "in flight"
+    //     during the current deep chain.  A binding is considered "active" when its recorded
+    //     generation matches _deepCycleGen.
+    //   _deepCycleGen: monotonically incremented at the start of each new deep chain.  This acts
+    //     as an implicit bulk-clear: old marks from a previous chain have a stale generation number
+    //     and are treated as absent — no explicit Map.delete or Map.clear is needed at all.
+    //     Eliminating the per-level Map.delete call (was ~10 ns × 480 levels) is the primary
+    //     motivation for this design.
+    //
+    // _deepActiveLevels: tracks how many deep levels are currently on the call stack so we know
+    //   when the deep portion has fully unwound and can reset _deepSyncCtxPath.
+    //
+    // _deepSyncCtx / _deepSyncCtxPath: single shared context for the deep chain; avoids one
+    //   per-depth pool reset (5 property writes) for every level beyond the threshold.
+    //   resolutionStack is NOT pushed in the deep path — no GC write-barriers for object arrays.
+    //   Trade-off: ctx.graph.resolutionStack only reflects the first RESOLUTION_SET_THRESHOLD
+    //   frames; code relying on ctx.graph.parent inside a deep transient-dynamic factory will see
+    //   the frame at the threshold boundary, not the current depth.
+    _deepCycleMarks = new Map();
+    _deepCycleGen = 0;
+    _deepActiveLevels = 0;
+    _deepSyncCtx;
+    _deepSyncCtxPath;
+    // Async shared-context state for _resolveTransientDynamicAsyncFromContext (shallow path):
+    //
+    // For a SEQUENTIAL async chain (depth < RESOLUTION_SET_THRESHOLD), all levels share the same
+    // resolutionPath and resolutionStack arrays (passed by reference through ctx.resolveAsync).
+    // Because the context stores references rather than snapshots, a single DefaultResolutionContext
+    // can serve the entire chain without any per-level allocation or reset — the arrays reflect the
+    // current chain state automatically as we push/pop.
+    //
+    // _deepAsyncCtx: the shared context, lazily created on the first chain entry and reset
+    //   (5 property writes) at the start of each new root call.  Levels 2-N of the same chain
+    //   reuse it with ZERO setup cost.
+    //
+    // _deepAsyncCtxPath: identity pointer of the resolutionPath array that "owns" the shared
+    //   context.  Used to distinguish two cases:
+    //     • same reference → inner level of the owning chain → reuse ctx with no setup
+    //     • different reference → concurrent chain (e.g. Promise.all) → fall back to a fresh
+    //       DefaultResolutionContext allocation for that call
+    //
+    // _deepAsyncActiveLevels: counts active levels of the OWNING chain so we know when to
+    //   release the path pointer (set _deepAsyncCtxPath = undefined).
+    //   Concurrent fallback calls are NOT counted — they don't interfere with the owner.
+    //
+    // resolutionStack is NOT pushed in this path (same trade-off as the deep sync path):
+    //   ctx.graph.resolutionStack will always be empty for async transient-dynamic chains.
+    //   Factories that inspect ctx.graph.parent should use the conventional sync binding approach.
+    //
+    // The function is NOT declared async so that V8 does not create an AsyncGeneratorObject and
+    // an implicit Promise on every invocation; instead each level calls factoryPromise.then(cleanup)
+    // which chains natively without the extra async state-machine overhead.
+    _deepAsyncCtx;
+    _deepAsyncCtxPath;
+    _deepAsyncActiveLevels = 0;
+    _classHasPostConstruct = new WeakMap();
+    _classNeedsActiveContainer = new WeakMap();
+    _classConstructorMetadata = new WeakMap();
+    _activationNeedByBindingId = new Map();
+    _activationCacheVersion = -1;
+    constructor(_registry, _scope, _lifecycle, _metadataReader, _container, _parent) {
+        this._registry = _registry;
+        this._scope = _scope;
+        this._lifecycle = _lifecycle;
+        this._metadataReader = _metadataReader;
+        this._container = _container;
+        this._parent = _parent;
+    }
+    // ── Binding lookup ─────────────────────────────────────────────────────────
+    _findBinding(token, options, resolutionPath, resolutionStack) {
+        if (options === undefined) {
+            const fastDefaultBinding = this._registry.getFastDefault(token);
+            if (fastDefaultBinding !== undefined) {
+                return { binding: fastDefaultBinding, owner: this };
+            }
+        }
+        if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+            const namedBinding = this._registry.getSimpleNamed(token, options.name);
+            if (namedBinding !== undefined &&
+                this._matchesBindingFast(namedBinding, options, resolutionPath, resolutionStack)) {
+                return { binding: namedBinding, owner: this };
+            }
+        }
+        if (options !== undefined &&
+            options.name === undefined &&
+            options.tag === undefined &&
+            (options.tags?.length ?? 0) === 1) {
+            const [tagKey, tagValue] = options.tags[0];
+            const tagged = this._registry.getSimpleTagged(token, tagKey, tagValue);
+            if (tagged !== undefined) {
+                return { binding: tagged, owner: this };
+            }
+        }
+        const bindings = this._registry.getAll(token);
+        if (bindings.length > 0) {
+            if (bindings.length === 1) {
+                const onlyBinding = bindings[0];
+                const isDefaultSlot = onlyBinding.slot.name === undefined && onlyBinding.slot.tags.length === 0;
+                if (options === undefined && isDefaultSlot && onlyBinding.predicate === undefined) {
+                    return { binding: onlyBinding, owner: this };
+                }
+                if (this._matchesBindingFast(onlyBinding, options, resolutionPath, resolutionStack)) {
+                    return { binding: onlyBinding, owner: this };
+                }
+            }
+            const ctx = this._makeConstraintContext(resolutionPath, resolutionStack, options);
+            const binding = selectBinding(bindings, options, ctx, this._getTokenName(token));
+            if (binding !== undefined) {
+                return { binding, owner: this };
+            }
+        }
+        if (this._parent !== undefined) {
+            return this._parent._findBinding(token, options, resolutionPath, resolutionStack);
+        }
+        return undefined;
+    }
+    /**
+     * Binding lookup aligned with `resolve` — used by `Container.validate` without instantiating.
+     */
+    peekBindingForValidate(token, options) {
+        return this._findBinding(token, options, [], []);
+    }
+    /**
+     * Mirrors {@link DependencyResolver.resolveAll} candidate selection only (no instantiation).
+     */
+    peekCandidateBindingsForValidate(token, options) {
+        if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+            return this._getSimpleNamedBindingsFromChain(token, options.name);
+        }
+        const allBindings = this._getAllBindingsFromChain(token);
+        if (allBindings.length === 0) {
+            return [];
+        }
+        const ctx = this._makeConstraintContext([], [], options);
+        return selectAllBindings(allBindings, options, ctx);
+    }
+    // ── Sync resolve ───────────────────────────────────────────────────────────
+    resolveFromContext(token, resolutionPath, resolutionStack) {
+        const fastBinding = this._registry.getFastDefault(token);
+        if (fastBinding !== undefined) {
+            if (fastBinding.kind === "alias") {
+                return this.resolveFromContext(fastBinding.target, resolutionPath, resolutionStack);
+            }
+            const scope = fastBinding.scope ?? "transient";
+            if (scope === "transient" &&
+                fastBinding.kind === "dynamic" &&
+                fastBinding.onActivation === undefined &&
+                (this._lifecycle.activationVersion === 0 || !this._lifecycle.hasActivationHandlers(fastBinding.token))) {
+                return this._resolveTransientDynamicSyncFromContext(fastBinding, resolutionPath, resolutionStack);
+            }
+            if (scope === "singleton" && this._scope.hasSingleton(fastBinding.id)) {
+                return this._scope.getSingleton(fastBinding.id);
+            }
+            if (scope === "scoped") {
+                if (!this._scope.isChild) {
+                    throw new MissingScopeContextError(this._getTokenName(fastBinding.token));
+                }
+                if (this._scope.hasScoped(fastBinding.id)) {
+                    return this._scope.getScoped(fastBinding.id);
+                }
+            }
+            return this._resolveBinding(fastBinding, undefined, resolutionPath, resolutionStack);
+        }
+        return this.resolve(token, undefined, resolutionPath, resolutionStack);
+    }
+    resolve(token, options, resolutionPath, resolutionStack) {
+        const found = this._findBinding(token, options, resolutionPath, resolutionStack);
+        if (found === undefined) {
+            const ownBindings = this._registry.getAll(token);
+            if (ownBindings.length > 0) {
+                throw new NoMatchingBindingError(this._getTokenName(token), options ?? {}, this._getAvailableSlots(token));
+            }
+            throw new TokenNotBoundError(this._getTokenName(token));
+        }
+        const { binding, owner } = found;
+        // Follow alias
+        if (binding.kind === "alias") {
+            return this.resolve(binding.target, options, resolutionPath, resolutionStack);
+        }
+        const scope = binding.scope ?? "transient";
+        // Singleton from a parent resolver: delegate so the parent caches it correctly
+        if (scope === "singleton" && owner !== this) {
+            return owner._resolveBinding(binding, options, resolutionPath, resolutionStack);
+        }
+        // Scoped/transient (or own singleton): resolve with this resolver's container/scope
+        return this._resolveBinding(binding, options, resolutionPath, resolutionStack);
+    }
+    _resolveBinding(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            !this._lifecycle.hasActivationHandlers(binding.token)) {
+            return binding.value;
+        }
+        const scope = binding.scope ?? "transient";
+        // Singleton cache check
+        if (scope === "singleton") {
+            if (this._scope.hasSingleton(binding.id)) {
+                return this._scope.getSingleton(binding.id);
+            }
+        }
+        // Scoped cache check
+        if (scope === "scoped") {
+            if (!this._scope.isChild) {
+                throw new MissingScopeContextError(this._getTokenName(binding.token));
+            }
+            if (this._scope.hasScoped(binding.id)) {
+                return this._scope.getScoped(binding.id);
+            }
+        }
+        const frame = this._getResolutionFrame(binding);
+        const tokenDisplayName = frame.tokenName;
+        const pathWithSet = resolutionPath;
+        let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
+        if (resolutionSet === undefined && resolutionPath.length >= RESOLUTION_SET_THRESHOLD) {
+            resolutionSet = new Set(resolutionPath);
+            pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+        }
+        // Circular dependency detection
+        if (resolutionSet !== undefined ? resolutionSet.has(tokenDisplayName) : resolutionPath.includes(tokenDisplayName)) {
+            const cycle = [...resolutionPath, tokenDisplayName];
+            throw new CircularDependencyError(cycle);
+        }
+        resolutionPath.push(tokenDisplayName);
+        resolutionSet?.add(tokenDisplayName);
+        resolutionStack.push(frame);
+        const needsActivation = this._needsActivation(binding);
+        if (!needsActivation && scope === "transient" && binding.kind === "dynamic") {
+            const resolutionCtx = this._acquireSyncResolutionContext(resolutionPath, resolutionStack, options);
+            try {
+                const dynamicResult = binding.factory(resolutionCtx);
+                if (dynamicResult instanceof Promise) {
+                    throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+                }
+                resolutionStack.pop();
+                resolutionPath.pop();
+                resolutionSet?.delete(tokenDisplayName);
+                return dynamicResult;
+            }
+            catch (error) {
+                resolutionStack.pop();
+                resolutionPath.pop();
+                resolutionSet?.delete(tokenDisplayName);
+                throw error;
+            }
+        }
+        try {
+            const needsResolutionContext = needsActivation || this._requiresResolutionContext(binding);
+            const resolutionCtx = needsResolutionContext
+                ? this._acquireSyncResolutionContext(resolutionPath, resolutionStack, options)
+                : undefined;
+            const instance = this._instantiateSync(binding, resolutionCtx, resolutionPath, resolutionStack);
+            const shouldActivate = this._refreshActivationCacheIfNeeded(binding, needsActivation);
+            const activated = shouldActivate
+                ? this._lifecycle.runActivationSync(resolutionCtx, binding, instance, this._metadataReader)
+                : instance;
+            // Cache by scope
+            if (scope === "singleton") {
+                this._scope.setSingleton(binding.id, activated);
+            }
+            else if (scope === "scoped") {
+                this._scope.setScoped(binding.id, activated);
+            }
+            return activated;
+        }
+        finally {
+            resolutionStack.pop();
+            resolutionPath.pop();
+            resolutionSet?.delete(tokenDisplayName);
+        }
+    }
+    _instantiateSync(binding, ctx, resolutionPath, resolutionStack) {
+        switch (binding.kind) {
+            case "constant":
+                return binding.value;
+            case "dynamic": {
+                if (ctx === undefined) {
+                    throw new InternalError("dynamic binding requires resolution context");
+                }
+                const factoryResult = binding.factory(ctx);
+                if (factoryResult instanceof Promise) {
+                    throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+                }
+                return factoryResult;
+            }
+            case "dynamic-async":
+                throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+            case "class": {
+                const deps = this._resolveClassDeps(binding.target, resolutionPath, resolutionStack);
+                const instance = this._instantiateClass(binding.target, deps);
+                return instance;
+            }
+            case "resolved": {
+                const deps = this._resolveDescriptorDeps(binding.deps, resolutionPath, resolutionStack);
+                const factoryResult = binding.factory(...deps);
+                if (factoryResult instanceof Promise) {
+                    throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+                }
+                return factoryResult;
+            }
+            case "resolved-async":
+                throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+            case "alias":
+                throw new InternalError("alias should have been followed before instantiation");
+        }
+    }
+    _resolveClassDeps(target, resolutionPath, resolutionStack) {
+        const meta = this._getConstructorMetadata(target);
+        if (meta === undefined) {
+            if (target.length === 0) {
+                return [];
+            }
+            throw new MissingMetadataError(target.name);
+        }
+        if (meta.params.length === 0) {
+            return [];
+        }
+        if (meta.params.length === 1) {
+            const param = meta.params[0];
+            const paramOptions = injectionSlotToResolveOptions(param);
+            if (param.multi) {
+                return [this.resolveAll(param.token, paramOptions, resolutionPath, resolutionStack)];
+            }
+            if (param.optional) {
+                return [this.resolveOptional(param.token, paramOptions, resolutionPath, resolutionStack)];
+            }
+            if (paramOptions === undefined) {
+                return [this.resolveFromContext(param.token, resolutionPath, resolutionStack)];
+            }
+            return [this.resolve(param.token, paramOptions, resolutionPath, resolutionStack)];
+        }
+        const deps = new Array(meta.params.length);
+        for (let index = 0; index < meta.params.length; index += 1) {
+            const param = meta.params[index];
+            const paramOptions = injectionSlotToResolveOptions(param);
+            if (param.multi) {
+                deps[index] = this.resolveAll(param.token, paramOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            if (param.optional) {
+                deps[index] = this.resolveOptional(param.token, paramOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            deps[index] =
+                paramOptions === undefined
+                    ? this.resolveFromContext(param.token, resolutionPath, resolutionStack)
+                    : this.resolve(param.token, paramOptions, resolutionPath, resolutionStack);
+        }
+        return deps;
+    }
+    _resolveDescriptorDeps(deps, resolutionPath, resolutionStack) {
+        const resolved = new Array(deps.length);
+        for (let index = 0; index < deps.length; index += 1) {
+            const dep = deps[index];
+            const depOptions = injectionSlotToResolveOptions(dep);
+            if (dep.multi) {
+                resolved[index] = this.resolveAll(dep.token, depOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            if (dep.optional) {
+                resolved[index] = this.resolveOptional(dep.token, depOptions, resolutionPath, resolutionStack);
+                continue;
+            }
+            resolved[index] =
+                depOptions === undefined
+                    ? this.resolveFromContext(dep.token, resolutionPath, resolutionStack)
+                    : this.resolve(dep.token, depOptions, resolutionPath, resolutionStack);
+        }
+        return resolved;
+    }
+    resolveOptional(token, options, resolutionPath, resolutionStack) {
+        if (this._findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+            return undefined;
+        }
+        return this.resolve(token, options, resolutionPath, resolutionStack);
+    }
+    resolveAll(token, options, resolutionPath, resolutionStack) {
+        if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+            const namedCandidates = this._getSimpleNamedBindingsFromChain(token, options.name);
+            if (namedCandidates.length === 0) {
+                return [];
+            }
+            const resolved = new Array(namedCandidates.length);
+            for (let index = 0; index < namedCandidates.length; index += 1) {
+                resolved[index] = this._resolveCandidateSync(namedCandidates[index], options, resolutionPath, resolutionStack);
+            }
+            return resolved;
+        }
+        const allBindings = this._getAllBindingsFromChain(token);
+        if (allBindings.length === 0) {
+            return [];
+        }
+        const ctx = this._makeConstraintContext(resolutionPath, resolutionStack, options);
+        const candidates = selectAllBindings(allBindings, options, ctx);
+        const resolved = new Array(candidates.length);
+        for (let index = 0; index < candidates.length; index += 1) {
+            resolved[index] = this._resolveCandidateSync(candidates[index], options, resolutionPath, resolutionStack);
+        }
+        return resolved;
+    }
+    // ── Async resolve ──────────────────────────────────────────────────────────
+    resolveAsyncFromContext(token, resolutionPath, resolutionStack) {
+        const fastBinding = this._registry.getFastDefault(token);
+        if (fastBinding !== undefined) {
+            if (fastBinding.kind === "alias") {
+                return this.resolveAsyncFromContext(fastBinding.target, resolutionPath, resolutionStack);
+            }
+            const scope = fastBinding.scope ?? "transient";
+            if (scope === "transient" &&
+                (fastBinding.kind === "dynamic" || fastBinding.kind === "dynamic-async") &&
+                fastBinding.onActivation === undefined &&
+                (this._lifecycle.activationVersion === 0 || !this._lifecycle.hasActivationHandlers(fastBinding.token))) {
+                return this._resolveTransientDynamicAsyncFromContext(fastBinding, resolutionPath, resolutionStack);
+            }
+            if (scope === "singleton" && this._scope.hasSingleton(fastBinding.id)) {
+                return Promise.resolve(this._scope.getSingleton(fastBinding.id));
+            }
+            if (scope === "scoped") {
+                if (!this._scope.isChild) {
+                    return Promise.reject(new MissingScopeContextError(this._getTokenName(fastBinding.token)));
+                }
+                if (this._scope.hasScoped(fastBinding.id)) {
+                    return Promise.resolve(this._scope.getScoped(fastBinding.id));
+                }
+            }
+            return this._resolveBindingAsync(fastBinding, undefined, resolutionPath, resolutionStack);
+        }
+        return this.resolveAsync(token, undefined, resolutionPath, resolutionStack);
+    }
+    async resolveAsync(token, options, resolutionPath, resolutionStack) {
+        const found = this._findBinding(token, options, resolutionPath, resolutionStack);
+        if (found === undefined) {
+            const ownBindings = this._registry.getAll(token);
+            if (ownBindings.length > 0) {
+                throw new NoMatchingBindingError(this._getTokenName(token), options ?? {}, this._getAvailableSlots(token));
+            }
+            throw new TokenNotBoundError(this._getTokenName(token));
+        }
+        const { binding, owner } = found;
+        if (binding.kind === "alias") {
+            return this.resolveAsync(binding.target, options, resolutionPath, resolutionStack);
+        }
+        const scope = binding.scope ?? "transient";
+        if (scope === "singleton" && owner !== this) {
+            return owner._resolveBindingAsync(binding, options, resolutionPath, resolutionStack);
+        }
+        return this._resolveBindingAsync(binding, options, resolutionPath, resolutionStack);
+    }
+    async _resolveBindingAsync(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            !this._lifecycle.hasActivationHandlers(binding.token)) {
+            return binding.value;
+        }
+        const scope = binding.scope ?? "transient";
+        // Singleton cache
+        if (scope === "singleton") {
+            if (this._scope.hasSingleton(binding.id)) {
+                return this._scope.getSingleton(binding.id);
+            }
+            // In-flight dedup
+            const inflight = this._scope.getInflight(binding.id);
+            if (inflight !== undefined) {
+                return inflight;
+            }
+        }
+        // Scoped cache
+        if (scope === "scoped") {
+            if (!this._scope.isChild) {
+                throw new MissingScopeContextError(this._getTokenName(binding.token));
+            }
+            if (this._scope.hasScoped(binding.id)) {
+                return this._scope.getScoped(binding.id);
+            }
+        }
+        const frame = this._getResolutionFrame(binding);
+        const frameName = frame.tokenName;
+        const pathWithSet = resolutionPath;
+        let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
+        if (resolutionSet === undefined && resolutionPath.length >= RESOLUTION_SET_THRESHOLD) {
+            resolutionSet = new Set(resolutionPath);
+            pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+        }
+        if (resolutionSet !== undefined ? resolutionSet.has(frameName) : resolutionPath.includes(frameName)) {
+            throw new CircularDependencyError([...resolutionPath, frameName]);
+        }
+        resolutionPath.push(frameName);
+        resolutionSet?.add(frameName);
+        resolutionStack.push(frame);
+        const needsActivation = this._needsActivation(binding);
+        if (!needsActivation && scope === "transient" && (binding.kind === "dynamic" || binding.kind === "dynamic-async")) {
+            const resolutionCtx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, options);
+            try {
+                if (binding.kind === "dynamic-async") {
+                    return await binding.factory(resolutionCtx);
+                }
+                const dynamicResult = binding.factory(resolutionCtx);
+                return dynamicResult instanceof Promise ? await dynamicResult : dynamicResult;
+            }
+            finally {
+                resolutionStack.pop();
+                resolutionPath.pop();
+                resolutionSet?.delete(frameName);
+            }
+        }
+        const needsResolutionContext = needsActivation || this._requiresResolutionContext(binding);
+        const resolutionCtx = needsResolutionContext
+            ? new DefaultResolutionContext(this, resolutionPath, resolutionStack, options)
+            : undefined;
+        try {
+            if (scope === "singleton") {
+                const createSingletonPromise = async () => {
+                    const instance = await this._instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
+                    const shouldActivate = this._refreshActivationCacheIfNeeded(binding, needsActivation);
+                    const activated = shouldActivate
+                        ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader)
+                        : instance;
+                    this._scope.setSingleton(binding.id, activated);
+                    this._scope.clearInflight(binding.id);
+                    return activated;
+                };
+                const singletonPromise = createSingletonPromise().catch((err) => {
+                    this._scope.clearInflight(binding.id);
+                    throw err;
+                });
+                this._scope.setInflight(binding.id, singletonPromise);
+                return await singletonPromise;
+            }
+            const instance = await this._instantiateAsync(binding, resolutionCtx, resolutionPath, resolutionStack);
+            const shouldActivate = this._refreshActivationCacheIfNeeded(binding, needsActivation);
+            const activated = shouldActivate
+                ? await this._lifecycle.runActivation(resolutionCtx, binding, instance, this._metadataReader)
+                : instance;
+            if (scope === "scoped") {
+                this._scope.setScoped(binding.id, activated);
+            }
+            return activated;
+        }
+        finally {
+            resolutionStack.pop();
+            resolutionPath.pop();
+            resolutionSet?.delete(frameName);
+        }
+    }
+    async _instantiateAsync(binding, ctx, resolutionPath, resolutionStack) {
+        switch (binding.kind) {
+            case "constant":
+                return binding.value;
+            case "dynamic": {
+                if (ctx === undefined) {
+                    throw new InternalError("dynamic binding requires resolution context");
+                }
+                const factoryResult = binding.factory(ctx);
+                return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+            }
+            case "dynamic-async":
+                if (ctx === undefined) {
+                    throw new InternalError("dynamic-async binding requires resolution context");
+                }
+                return binding.factory(ctx);
+            case "class": {
+                const deps = await this._resolveClassDepsAsync(binding.target, resolutionPath, resolutionStack);
+                const instance = this._instantiateClass(binding.target, deps);
+                return instance;
+            }
+            case "resolved": {
+                if (ctx === undefined) {
+                    throw new InternalError("resolved binding requires resolution context");
+                }
+                const deps = await this._resolveDescriptorDepsAsync(binding.deps, resolutionPath, resolutionStack);
+                const factoryResult = binding.factory(...deps);
+                return factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+            }
+            case "resolved-async": {
+                const deps = await this._resolveDescriptorDepsAsync(binding.deps, resolutionPath, resolutionStack);
+                return binding.factory(...deps);
+            }
+            case "alias":
+                throw new InternalError("alias should have been followed before instantiation");
+        }
+    }
+    async _resolveClassDepsAsync(target, resolutionPath, resolutionStack) {
+        const meta = this._getConstructorMetadata(target);
+        if (meta === undefined) {
+            if (target.length === 0) {
+                return [];
+            }
+            throw new MissingMetadataError(target.name);
+        }
+        if (meta.params.length === 0) {
+            return [];
+        }
+        if (meta.params.length === 1) {
+            const param = meta.params[0];
+            const paramOptions = injectionSlotToResolveOptions(param);
+            if (param.multi) {
+                return [await this.resolveAllAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+            }
+            if (param.optional) {
+                return [await this.resolveOptionalAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+            }
+            if (paramOptions === undefined) {
+                return [await this.resolveAsyncFromContext(param.token, resolutionPath, resolutionStack)];
+            }
+            return [await this.resolveAsync(param.token, paramOptions, resolutionPath, resolutionStack)];
+        }
+        const pending = new Array(meta.params.length);
+        const shouldCloneContext = meta.params.length > 1;
+        for (let index = 0; index < meta.params.length; index += 1) {
+            const param = meta.params[index];
+            const paramOptions = injectionSlotToResolveOptions(param);
+            if (param.multi) {
+                pending[index] = this.resolveAllAsync(param.token, paramOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else if (param.optional) {
+                pending[index] = this.resolveOptionalAsync(param.token, paramOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else {
+                pending[index] =
+                    paramOptions === undefined
+                        ? this.resolveAsyncFromContext(param.token, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack)
+                        : this.resolveAsync(param.token, paramOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+        }
+        return Promise.all(pending);
+    }
+    async _resolveDescriptorDepsAsync(deps, resolutionPath, resolutionStack) {
+        const pending = new Array(deps.length);
+        const shouldCloneContext = deps.length > 1;
+        for (let index = 0; index < deps.length; index += 1) {
+            const dep = deps[index];
+            const depOptions = injectionSlotToResolveOptions(dep);
+            if (dep.multi) {
+                pending[index] = this.resolveAllAsync(dep.token, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else if (dep.optional) {
+                pending[index] = this.resolveOptionalAsync(dep.token, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+            else {
+                pending[index] =
+                    depOptions === undefined
+                        ? this.resolveAsyncFromContext(dep.token, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack)
+                        : this.resolveAsync(dep.token, depOptions, shouldCloneContext ? [...resolutionPath] : resolutionPath, shouldCloneContext ? [...resolutionStack] : resolutionStack);
+            }
+        }
+        return Promise.all(pending);
+    }
+    async resolveOptionalAsync(token, options, resolutionPath, resolutionStack) {
+        if (this._findBinding(token, options, resolutionPath, resolutionStack) === undefined) {
+            return undefined;
+        }
+        return this.resolveAsync(token, options, resolutionPath, resolutionStack);
+    }
+    async resolveAllAsync(token, options, resolutionPath, resolutionStack) {
+        if (options?.name !== undefined && options.tag === undefined && (options.tags?.length ?? 0) === 0) {
+            const namedCandidates = this._getSimpleNamedBindingsFromChain(token, options.name);
+            if (namedCandidates.length === 0) {
+                return [];
+            }
+            const pending = new Array(namedCandidates.length);
+            for (let index = 0; index < namedCandidates.length; index += 1) {
+                pending[index] = this._resolveCandidateAsync(namedCandidates[index], options, resolutionPath, resolutionStack);
+            }
+            return Promise.all(pending);
+        }
+        const allBindings = this._getAllBindingsFromChain(token);
+        if (allBindings.length === 0) {
+            return [];
+        }
+        const ctx = this._makeConstraintContext(resolutionPath, resolutionStack, options);
+        const candidates = selectAllBindings(allBindings, options, ctx);
+        const pending = new Array(candidates.length);
+        for (let index = 0; index < candidates.length; index += 1) {
+            pending[index] = this._resolveCandidateAsync(candidates[index], options, resolutionPath, resolutionStack);
+        }
+        return Promise.all(pending);
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    _getAllBindingsFromChain(token) {
+        const ownBindings = this._registry.getAll(token);
+        if (this._parent === undefined) {
+            return ownBindings;
+        }
+        const result = [...ownBindings];
+        let current = this._parent;
+        while (current !== undefined) {
+            const own = current._registry.getAll(token);
+            if (own.length > 0) {
+                result.push(...own);
+            }
+            current = current._parent;
+        }
+        return result;
+    }
+    _getSimpleNamedBindingsFromChain(token, name) {
+        const ownBinding = this._registry.getSimpleNamed(token, name);
+        if (this._parent === undefined) {
+            return ownBinding !== undefined ? [ownBinding] : [];
+        }
+        const result = [];
+        if (ownBinding !== undefined) {
+            result.push(ownBinding);
+        }
+        let current = this._parent;
+        while (current !== undefined) {
+            const binding = current._registry.getSimpleNamed(token, name);
+            if (binding !== undefined) {
+                result.push(binding);
+            }
+            current = current._parent;
+        }
+        return result;
+    }
+    _getAvailableSlots(token) {
+        return this._registry.availableSlotStrings(token);
+    }
+    _makeConstraintContext(resolutionPath, resolutionStack, options) {
+        if (options === undefined && resolutionPath.length === 0 && resolutionStack.length === 0) {
+            return ROOT_CONSTRAINT_CONTEXT;
+        }
+        const parent = resolutionStack.at(-1);
+        const ancestors = resolutionStack.length > 1 ? resolutionStack.slice(0, -1) : [];
+        return {
+            resolutionPath,
+            resolutionStack,
+            parent,
+            ancestors,
+            currentResolveOptions: options,
+        };
+    }
+    _matchesBindingFast(binding, options, resolutionPath, resolutionStack) {
+        if (!this._matchesSlotFast(binding.slot, options)) {
+            return false;
+        }
+        if (binding.predicate === undefined) {
+            return true;
+        }
+        const ctx = this._makeConstraintContext(resolutionPath, resolutionStack, options);
+        return binding.predicate(ctx);
+    }
+    _matchesSlotFast(slot, options) {
+        const requestedName = options?.name;
+        const requestedTags = options?.tags;
+        const singleRequestedTag = options?.tag;
+        const hasRequestedTags = (requestedTags?.length ?? 0) > 0 || singleRequestedTag !== undefined;
+        if (slot.name !== undefined) {
+            if (requestedName === undefined || slot.name !== requestedName) {
+                return false;
+            }
+        }
+        else if (requestedName !== undefined) {
+            return false;
+        }
+        if (slot.tags.length > 0) {
+            if (!hasRequestedTags) {
+                return false;
+            }
+            for (const [tagKey, tagValue] of slot.tags) {
+                if (!this._matchesRequestedTag(tagKey, tagValue, requestedTags, singleRequestedTag)) {
+                    return false;
+                }
+            }
+        }
+        else if (hasRequestedTags) {
+            return false;
+        }
+        return true;
+    }
+    _getTokenName(token) {
+        return tokenName(token);
+    }
+    _getConstructorMetadata(target) {
+        const cached = this._classConstructorMetadata.get(target);
+        if (cached !== undefined) {
+            return cached === null ? undefined : cached;
+        }
+        const metadata = this._metadataReader.getConstructorMetadata(target);
+        this._classConstructorMetadata.set(target, metadata ?? null);
+        return metadata;
+    }
+    _instantiateClass(target, deps) {
+        let needsActiveContainer = this._classNeedsActiveContainer.get(target);
+        if (needsActiveContainer === undefined) {
+            const accessorMetadata = this._metadataReader.getAccessorMetadata?.(target);
+            needsActiveContainer = (accessorMetadata?.length ?? 0) > 0;
+            this._classNeedsActiveContainer.set(target, needsActiveContainer);
+        }
+        const invokable = target;
+        if (!needsActiveContainer) {
+            return new invokable(...deps);
+        }
+        return runWithContainer(this._container, () => new invokable(...deps));
+    }
+    _matchesRequestedTag(tagKey, tagValue, requestedTags, singleRequestedTag) {
+        if (singleRequestedTag !== undefined &&
+            singleRequestedTag[0] === tagKey &&
+            Object.is(singleRequestedTag[1], tagValue)) {
+            return true;
+        }
+        if (requestedTags === undefined || requestedTags.length === 0) {
+            return false;
+        }
+        for (let index = 0; index < requestedTags.length; index += 1) {
+            const requestedTag = requestedTags[index];
+            if (requestedTag[0] === tagKey && Object.is(requestedTag[1], tagValue)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    _resolveTransientDynamicSyncFromContext(binding, resolutionPath, resolutionStack) {
+        // ── Shallow path (depth < RESOLUTION_SET_THRESHOLD) ──────────────────────────────────
+        // Use resolutionPath.includes for cycle detection: for tiny arrays (depth 0–31) this is
+        // faster than a Set lookup. Keep resolutionStack push/pop and the per-depth pool so
+        // ctx.graph reflects correct state for shallow-chain factories.
+        if (resolutionPath.length < RESOLUTION_SET_THRESHOLD) {
+            const frame = this._getResolutionFrame(binding);
+            const tokenDisplayName = frame.tokenName;
+            if (resolutionPath.includes(tokenDisplayName)) {
+                throw new CircularDependencyError([...resolutionPath, tokenDisplayName]);
+            }
+            resolutionPath.push(tokenDisplayName);
+            resolutionStack.push(frame);
+            const resolutionCtx = this._acquireSyncResolutionContext(resolutionPath, resolutionStack, undefined);
+            try {
+                const dynamicResult = binding.factory(resolutionCtx);
+                if (dynamicResult instanceof Promise) {
+                    throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+                }
+                return dynamicResult;
+            }
+            finally {
+                resolutionStack.pop();
+                resolutionPath.pop();
+            }
+        }
+        // ── Deep path (depth >= RESOLUTION_SET_THRESHOLD) ────────────────────────────────────
+        // At this depth the O(N) array scan becomes expensive.  Switch to a class-level
+        // Set<BindingIdentifier> for O(1) cycle detection.
+        //
+        // Performance decisions vs. shallow path:
+        //  1. _getResolutionFrame is NOT called: frameName is only needed for resolutionPath.push
+        //     and error messages.  Both are handled below without the frame Map lookup.
+        //  2. resolutionPath.push / pop is SKIPPED: cycle detection uses _deepCycleIds (binding IDs),
+        //     so path membership tracking through the string array is unnecessary.  Eliminating
+        //     ~480 array writes per 512-chain avoids GC write-barriers on every level.
+        //     Trade-off: CircularDependencyError thrown for a deep cycle (depth > 32) will only
+        //     include the first 32 path elements in its message; levels 32+ are omitted.
+        //  3. The shared context is set up ONCE (when _deepActiveLevels === 0) rather than
+        //     re-checked on every level — saves two property reads + a reference comparison
+        //     for each of the ~480 subsequent deep-chain levels.
+        //
+        // Reentrancy: if a *different* deep chain is currently active (factory called
+        // container.resolve() internally and that inner chain also reached the threshold),
+        // fall back to the slow path to avoid cross-chain Set pollution.
+        if (this._deepActiveLevels > 0 && this._deepSyncCtxPath !== resolutionPath) {
+            return this._resolveTransientDynamicSyncSlow(binding, resolutionPath, resolutionStack);
+        }
+        // First deep level: bump the generation (implicitly clearing all stale cycle marks from
+        // previous chains), seed the marks with the shallow-path frames already on the
+        // resolution stack, then initialise (or reset) the shared context once for the
+        // whole deep chain.
+        if (this._deepActiveLevels === 0) {
+            const gen = ++this._deepCycleGen;
+            for (const stackFrame of resolutionStack) {
+                this._deepCycleMarks.set(stackFrame.bindingId, gen);
+            }
+            let ctx = this._deepSyncCtx;
+            if (ctx === undefined) {
+                ctx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+                this._deepSyncCtx = ctx;
+            }
+            else {
+                ctx.reset(this, resolutionPath, resolutionStack, undefined);
+            }
+            this._deepSyncCtxPath = resolutionPath;
+        }
+        if (this._deepCycleMarks.get(binding.id) === this._deepCycleGen) {
+            throw new CircularDependencyError([...resolutionPath, tokenName(binding.token)]);
+        }
+        this._deepCycleMarks.set(binding.id, this._deepCycleGen);
+        this._deepActiveLevels++;
+        try {
+            // Use the pre-initialised context directly — no local variable needed.
+            const dynamicResult = binding.factory(this._deepSyncCtx);
+            if (dynamicResult instanceof Promise) {
+                throw new AsyncResolutionError(tokenName(binding.token), tokenName(binding.token));
+            }
+            return dynamicResult;
+        }
+        finally {
+            // No Map.delete needed: the generation counter makes old marks invisible.
+            // Only reset the path pointer when the last deep level unwinds.
+            if (--this._deepActiveLevels === 0) {
+                this._deepSyncCtxPath = undefined;
+            }
+        }
+    }
+    _resolveTransientDynamicSyncSlow(binding, resolutionPath, resolutionStack) {
+        // Rare fallback used when deep-chain reentrancy is detected (a factory called
+        // container.resolve() directly and the resulting chain also reached the threshold).
+        const frame = this._getResolutionFrame(binding);
+        const tokenDisplayName = frame.tokenName;
+        const pathWithSet = resolutionPath;
+        let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
+        if (resolutionSet === undefined) {
+            resolutionSet = new Set(resolutionPath);
+            pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+        }
+        if (resolutionSet.has(tokenDisplayName)) {
+            throw new CircularDependencyError([...resolutionPath, tokenDisplayName]);
+        }
+        resolutionPath.push(tokenDisplayName);
+        resolutionSet.add(tokenDisplayName);
+        resolutionStack.push(frame);
+        const resolutionCtx = this._acquireSyncResolutionContext(resolutionPath, resolutionStack, undefined);
+        try {
+            const dynamicResult = binding.factory(resolutionCtx);
+            if (dynamicResult instanceof Promise) {
+                throw new AsyncResolutionError(tokenDisplayName, tokenDisplayName);
+            }
+            return dynamicResult;
+        }
+        finally {
+            resolutionStack.pop();
+            resolutionPath.pop();
+            resolutionSet.delete(tokenDisplayName);
+        }
+    }
+    // NOT declared `async` — avoids creating a JSAsyncGeneratorObject + implicit Promise wrapper on
+    // every invocation.  Cleanup is handled via .then(onFulfilled, onRejected) so the behaviour is
+    // identical to a try/finally but without the async machinery overhead.
+    _resolveTransientDynamicAsyncFromContext(binding, resolutionPath, resolutionStack) {
+        // ── Shallow async path (depth < RESOLUTION_SET_THRESHOLD) ─────────────────────────────
+        // For the common case of a sequential async chain (each factory awaits one dependency at a
+        // time), all levels share the same resolutionPath/resolutionStack arrays.  A single
+        // DefaultResolutionContext can therefore serve the entire chain:
+        //   • levels 2-N of the owning chain: zero allocation, zero reset writes
+        //   • concurrent chains (Promise.all roots): detected by path-identity mismatch → fallback
+        //     to a fresh DefaultResolutionContext for that level only
+        // resolutionStack is NOT pushed here — see class-level comment for the trade-off.
+        if (resolutionPath.length < RESOLUTION_SET_THRESHOLD) {
+            const tokenDisplayName = tokenName(binding.token);
+            if (resolutionPath.includes(tokenDisplayName)) {
+                return Promise.reject(new CircularDependencyError([...resolutionPath, tokenDisplayName]));
+            }
+            resolutionPath.push(tokenDisplayName);
+            // Determine which context to use and whether this level owns the shared context.
+            let ctx;
+            let isOwnerLevel;
+            if (this._deepAsyncCtxPath === resolutionPath) {
+                // Inner level of the owning chain — reuse the shared context with NO setup overhead.
+                ctx = this._deepAsyncCtx;
+                isOwnerLevel = true;
+            }
+            else if (this._deepAsyncCtxPath === undefined) {
+                // Root of a new chain — take ownership and initialise (or reset) the shared context.
+                const existing = this._deepAsyncCtx;
+                if (existing === undefined) {
+                    ctx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+                    this._deepAsyncCtx = ctx;
+                }
+                else {
+                    existing.reset(this, resolutionPath, resolutionStack, undefined);
+                    ctx = existing;
+                }
+                this._deepAsyncCtxPath = resolutionPath;
+                isOwnerLevel = true;
+            }
+            else {
+                // Concurrent chain (e.g. Promise.all) — allocate a dedicated context and do NOT
+                // interfere with the owning chain's state.
+                ctx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+                isOwnerLevel = false;
+            }
+            if (isOwnerLevel) {
+                this._deepAsyncActiveLevels++;
+            }
+            // Invoke the factory synchronously to get its Promise (or a resolved value for "dynamic").
+            let factoryPromise;
+            try {
+                if (binding.kind === "dynamic-async") {
+                    factoryPromise = binding.factory(ctx);
+                }
+                else {
+                    const factoryResult = binding.factory(ctx);
+                    factoryPromise =
+                        factoryResult instanceof Promise ? factoryResult : Promise.resolve(factoryResult);
+                }
+            }
+            catch (err) {
+                // Synchronous throw from the factory (rare) — clean up immediately.
+                resolutionPath.pop();
+                if (isOwnerLevel && --this._deepAsyncActiveLevels === 0) {
+                    this._deepAsyncCtxPath = undefined;
+                }
+                return Promise.reject(err);
+            }
+            // Chain cleanup onto the Promise so it runs whether the factory resolves or rejects.
+            return factoryPromise.then((value) => {
+                resolutionPath.pop();
+                if (isOwnerLevel && --this._deepAsyncActiveLevels === 0) {
+                    this._deepAsyncCtxPath = undefined;
+                }
+                return value;
+            }, (err) => {
+                resolutionPath.pop();
+                if (isOwnerLevel && --this._deepAsyncActiveLevels === 0) {
+                    this._deepAsyncCtxPath = undefined;
+                }
+                // Re-throw as the rejected value; the `never` cast suppresses the TS return-type
+                // mismatch that arises because `throw` has type `never` in an expression context.
+                throw err;
+            });
+        }
+        // ── Deep async path (depth ≥ RESOLUTION_SET_THRESHOLD) ────────────────────────────────
+        // Fall back to the fully-correct slow implementation.
+        return this._resolveTransientDynamicAsyncSlow(binding, resolutionPath, resolutionStack);
+    }
+    async _resolveTransientDynamicAsyncSlow(binding, resolutionPath, resolutionStack) {
+        const frame = this._getResolutionFrame(binding);
+        const tokenDisplayName = frame.tokenName;
+        const pathWithSet = resolutionPath;
+        let resolutionSet = pathWithSet[RESOLUTION_SET_KEY];
+        if (resolutionSet === undefined) {
+            resolutionSet = new Set(resolutionPath);
+            pathWithSet[RESOLUTION_SET_KEY] = resolutionSet;
+        }
+        if (resolutionSet.has(tokenDisplayName)) {
+            throw new CircularDependencyError([...resolutionPath, tokenDisplayName]);
+        }
+        resolutionPath.push(tokenDisplayName);
+        resolutionSet.add(tokenDisplayName);
+        resolutionStack.push(frame);
+        const resolutionCtx = new DefaultResolutionContext(this, resolutionPath, resolutionStack, undefined);
+        try {
+            if (binding.kind === "dynamic-async") {
+                return await binding.factory(resolutionCtx);
+            }
+            const dynamicResult = binding.factory(resolutionCtx);
+            return dynamicResult instanceof Promise ? await dynamicResult : dynamicResult;
+        }
+        finally {
+            resolutionStack.pop();
+            resolutionPath.pop();
+            resolutionSet.delete(tokenDisplayName);
+        }
+    }
+    _resolveCandidateSync(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            !this._lifecycle.hasActivationHandlers(binding.token)) {
+            return binding.value;
+        }
+        if (binding.kind === "alias") {
+            return this.resolve(binding.target, options, resolutionPath, resolutionStack);
+        }
+        const scope = binding.scope ?? "transient";
+        if (scope === "singleton" && this._scope.hasSingleton(binding.id)) {
+            return this._scope.getSingleton(binding.id);
+        }
+        if (scope === "scoped") {
+            if (!this._scope.isChild) {
+                throw new MissingScopeContextError(this._getTokenName(binding.token));
+            }
+            if (this._scope.hasScoped(binding.id)) {
+                return this._scope.getScoped(binding.id);
+            }
+        }
+        return this._resolveBinding(binding, options, resolutionPath, resolutionStack);
+    }
+    _resolveCandidateAsync(binding, options, resolutionPath, resolutionStack) {
+        if (binding.kind === "constant" &&
+            binding.onActivation === undefined &&
+            !this._lifecycle.hasActivationHandlers(binding.token)) {
+            return Promise.resolve(binding.value);
+        }
+        const isolatedPath = [...resolutionPath];
+        const isolatedStack = [...resolutionStack];
+        if (binding.kind === "alias") {
+            return this.resolveAsync(binding.target, options, isolatedPath, isolatedStack);
+        }
+        const scope = binding.scope ?? "transient";
+        if (scope === "singleton" && this._scope.hasSingleton(binding.id)) {
+            return Promise.resolve(this._scope.getSingleton(binding.id));
+        }
+        if (scope === "scoped") {
+            if (!this._scope.isChild) {
+                return Promise.reject(new MissingScopeContextError(this._getTokenName(binding.token)));
+            }
+            if (this._scope.hasScoped(binding.id)) {
+                return Promise.resolve(this._scope.getScoped(binding.id));
+            }
+        }
+        return this._resolveBindingAsync(binding, options, isolatedPath, isolatedStack);
+    }
+    _getResolutionFrame(binding) {
+        const existing = this._frameByBindingId.get(binding.id);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const scope = binding.scope ?? "transient";
+        const frame = buildResolutionFrame(tokenName(binding.token), scope, binding.id, binding.kind, binding.slot);
+        this._frameByBindingId.set(binding.id, frame);
+        return frame;
+    }
+    _needsActivation(binding) {
+        const lifecycleVersion = this._lifecycle.activationVersion;
+        if (lifecycleVersion === 0 &&
+            binding.kind !== "class" &&
+            binding.kind !== "alias" &&
+            binding.onActivation === undefined) {
+            return false;
+        }
+        if (this._activationCacheVersion !== lifecycleVersion) {
+            this._activationNeedByBindingId.clear();
+            this._activationCacheVersion = lifecycleVersion;
+        }
+        const cached = this._activationNeedByBindingId.get(binding.id);
+        if (cached !== undefined) {
+            return cached;
+        }
+        if (binding.kind === "class") {
+            let hasActivation = this._lifecycle.hasActivationHandlers(binding.token) || binding.onActivation !== undefined;
+            const cachedPostConstruct = this._classHasPostConstruct.get(binding.target);
+            // Unknown class lifecycle metadata: activate once, then cache after first instantiation.
+            if (cachedPostConstruct === undefined) {
+                hasActivation = true;
+            }
+            else if (cachedPostConstruct) {
+                hasActivation = true;
+            }
+            this._activationNeedByBindingId.set(binding.id, hasActivation);
+            return hasActivation;
+        }
+        let hasActivation = false;
+        if (binding.kind !== "alias" && binding.onActivation !== undefined) {
+            hasActivation = true;
+        }
+        else if (this._lifecycle.hasActivationHandlers(binding.token)) {
+            hasActivation = true;
+        }
+        this._activationNeedByBindingId.set(binding.id, hasActivation);
+        return hasActivation;
+    }
+    _refreshClassPostConstructCache(target) {
+        const lifecycle = this._metadataReader.getLifecycleMetadata(target);
+        const hasPostConstruct = lifecycle !== undefined && lifecycle.postConstruct !== undefined && lifecycle.postConstruct.length > 0;
+        this._classHasPostConstruct.set(target, hasPostConstruct);
+    }
+    /**
+     * Refreshes the post-construct cache for class bindings on first instantiation and
+     * returns the (possibly updated) shouldActivate flag.
+     */
+    _refreshActivationCacheIfNeeded(binding, needsActivation) {
+        if (binding.kind === "class" && this._classHasPostConstruct.get(binding.target) === undefined) {
+            this._refreshClassPostConstructCache(binding.target);
+            this._activationNeedByBindingId.delete(binding.id);
+            return this._needsActivation(binding);
+        }
+        return needsActivation;
+    }
+    _requiresResolutionContext(binding) {
+        return binding.kind === "dynamic" || binding.kind === "dynamic-async";
+    }
+    _acquireSyncResolutionContext(resolutionPath, resolutionStack, options) {
+        const depth = resolutionStack.length;
+        const existing = this._syncResolutionContextPool[depth];
+        if (existing !== undefined) {
+            existing.reset(this, resolutionPath, resolutionStack, options);
+            return existing;
+        }
+        const created = new DefaultResolutionContext(this, resolutionPath, resolutionStack, options);
+        this._syncResolutionContextPool[depth] = created;
+        return created;
+    }
+}
+//# sourceMappingURL=resolver.js.map