@codefast/di 0.3.14-canary.0 → 0.3.14-canary.2

package/dist/resolver.d.mts

@@ -1,197 +1,74 @@
+import { Constructor } from "./constructor-type.mjs";
 import { Token } from "./token.mjs";
-import { RegistryKey } from "./registry.mjs";
-import { Binding, Constructor, ResolveHint } from "./binding.mjs";
-import { MetadataReader } from "./metadata/metadata-types.mjs";
+import { MaterializationFrame, ResolveOptions } from "./types.mjs";
+import { BindingRegistry } from "./registry.mjs";
 import { ScopeManager } from "./scope.mjs";
+import { MetadataReader } from "./metadata/metadata-types.mjs";
+import { Container } from "./container.mjs";
+import { LifecycleManager } from "./lifecycle.mjs";
 
 //#region src/resolver.d.ts
-/**
- * Dependencies injected into {@link DependencyResolver} at construction time.
- */
-type ResolverDependencies = {
-  /**
-   * Looks up all bindings registered for a given registry key (own + parent containers).
-   */
-  readonly lookup: (key: RegistryKey) => readonly Binding<unknown>[] | undefined;
-  /**
-   * Manages singleton/scoped instance caches and deactivation.
-   */
-  readonly scopeManager: ScopeManager;
-  /**
-   * Reads `@injectable()` and lifecycle metadata from constructors. Omit to disable decorator support.
-   */
-  readonly metadataReader?: MetadataReader;
-};
-/**
- * Stateless graph walker: selects a binding, checks for cycles and scope violations,
- * delegates instance caching to `ScopeManager`, and runs lifecycle hooks.
- *
- * Resolution algorithm (per token):
- * 1. Lookup all bindings for the registry key.
- * 2. Apply name/tag hint and `when()` constraint filtering.
- * 3. Circular-dependency check via a mutable `visiting` set (per call tree).
- * 4. Captive-dependency check via the `materializationStack`.
- * 5. Scope-cache hit → return cached instance.
- * 6. Scope-cache miss → `materialize` → `@postConstruct` → `onActivation` → cache.
- *
- * Used exclusively by `DefaultContainer`; not part of the public API.
- */
 declare class DependencyResolver {
-  private readonly deps;
-  constructor(deps: ResolverDependencies);
-  /**
-   * Entry point for synchronous single-binding resolution.
-   *
-   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
-   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
-   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
-   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
-   * @throws {@link AsyncResolutionError} — an `async-dynamic` binding or async lifecycle/activation on the sync path.
-   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
-   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
-   */
-  resolveRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
-  /**
-   * Entry point for async single-binding resolution. Awaits `async-dynamic` factories
-   * and async lifecycle hooks that would cause {@link AsyncResolutionError} on the sync path.
-   *
-   * @throws {@link TokenNotBoundError} — no binding registered for `key`, or a nested dependency is unbound.
-   * @throws {@link NoMatchingBindingError} — a name/tag `hint` was given for `key` but no binding matched it.
-   * @throws {@link InternalError} — multiple bindings matched for `key` after applying the hint (ambiguous).
-   * @throws {@link CircularDependencyError} — `key` or a nested token appears twice on the resolution stack.
-   * @throws {@link ScopeViolationError} — captive dependency (singleton → scoped/transient).
-   * @throws {@link MissingMetadataError} — `class` binding lacks injectable metadata when the reader requires it.
-   */
-  resolveAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value>;
-  /**
-   * Optional resolution for the **requested key only**: returns `undefined` when that key has no
-   * bindings or every candidate is filtered out **without** a name/tag hint — without throwing
-   * {@link TokenNotBoundError} for those cases. Instantiating the selected binding still runs the
-   * normal sync resolution path for nested dependencies; an unregistered transitive dependency
-   * throws {@link TokenNotBoundError} as usual.
-   *
-   * Behavioral rules:
-   * 1. If the registry key is completely unbound → returns `undefined`.
-   * 2. If no candidate survives constraint filtering (without a hint) → returns `undefined`.
-   * 3. If a name/tag hint was provided but no binding matches it → throws {@link NoMatchingBindingError}.
-   * 4. Still throws on: circular dependencies, async operations on the sync path,
-   *    scope violations, ambiguous multi-binding matches, and {@link TokenNotBoundError} when a
-   *    required nested dependency is unbound.
-   */
-  resolveOptionalRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
-  /**
-   * Resolves every matching binding for `key` synchronously into an array.
-   * Returns an empty array when no bindings exist (does not throw).
-   *
-   * @throws {@link AsyncResolutionError} — any candidate is `async-dynamic`.
-   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
-   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveRoot}).
-   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
-   * @throws {@link ScopeViolationError} — captive dependency during materialization.
-   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
-   */
-  resolveAllRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
-  /**
-   * Async counterpart of {@link resolveAllRoot}: resolves every matching binding for `key`,
-   * awaiting `async-dynamic` factories. Returns an empty array when no bindings exist.
-   *
-   * @throws {@link NoMatchingBindingError} — hint was specified but no binding matched it.
-   * @throws {@link TokenNotBoundError} — nested dependency unbound (same as {@link resolveAsyncRoot}).
-   * @throws {@link CircularDependencyError} — cycle while materializing a candidate.
-   * @throws {@link ScopeViolationError} — captive dependency during materialization.
-   * @throws {@link MissingMetadataError} — class binding lacks injectable metadata when required.
-   */
-  resolveAllAsyncRoot<Value>(key: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
-  /**
-   * Context-aware sync `resolveAll`: extends the current resolution path and preserves
-   * visiting/materialization stacks so nested multi-resolution participates in cycle and
-   * captive-dependency checks exactly like single-value {@link resolve}.
-   */
-  private resolveAll;
-  /**
-   * Async counterpart of {@link resolveAll}: keeps the current path and materialization stack
-   * so `when()` constraints and scope validation behave consistently for nested multi-resolution.
-   */
-  private resolveAllAsync;
-  /**
-   * Assembles the read-only {@link ConstraintContext} snapshot passed to `when()` predicates.
-   * Extracts the top-of-stack frame as `parent` and the rest as `ancestors`.
-   */
-  private buildConstraintContext;
-  /**
-   * Throws {@link ScopeViolationError} when the immediate consumer on the stack is a singleton
-   * and the dependency has `"scoped"` or `"transient"` lifetime (captive dependency).
-   * Constants are exempt — they have no scope cache.
-   */
-  private assertDependencyScopeAllowed;
-  /**
-   * Builds a {@link ResolutionContext} for use inside factories and lifecycle hooks.
-   * The `resolve` / `resolveAsync` / `resolveOptional` closures carry the current path and
-   * materialization stack forward so nested calls inherit captive-dependency checks.
-   */
-  private createContext;
-  /**
-   * Core synchronous resolution: lookup → filter → cycle check → scope check → instantiate.
-   * Called recursively when a binding's dependencies need resolution.
-   *
-   * @param key - Token or constructor being resolved.
-   * @param hint - Optional name/tag filter for multi-binding selection.
-   * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
-   * @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
-   * @param materializationStack - Bindings along the current construction chain; used to block singleton→scoped/transient.
-   */
-  private resolve;
-  /**
-   * Core async resolution: same pipeline as {@link resolve} but awaits `async-dynamic`
-   * factories and async lifecycle hooks instead of throwing {@link AsyncResolutionError}.
-   *
-   * @param key - Token or constructor being resolved.
-   * @param hint - Optional name/tag filter for multi-binding selection.
-   * @param pathLabels - Mutable label path accumulated during graph walk; extended in place.
-   * @param visiting - Registry keys currently on the call stack; used for circular-dependency detection.
-   * @param materializationStack - Same captive-dependency chain as {@link resolve}.
-   */
-  private resolveAsync;
-  /**
-   * Handles scope-cache lookup / storage and lifecycle hooks (`@postConstruct`, `onActivation`)
-   * around a synchronous call to {@link materialize}.
-   */
-  private instantiateBinding;
-  /**
-   * Async counterpart of {@link instantiateBinding}: delegates to {@link materializeAsync}
-   * and awaits `@postConstruct` and `onActivation` hooks.
-   */
-  private instantiateBindingAsync;
-  /**
-   * Duplicate captive-dependency guard applied at instantiation time (after scope-cache miss),
-   * checking the top of the materialization stack rather than the raw `ConstraintContext`.
-   */
-  private assertCaptiveDependencyFromMaterializationStack;
-  /**
-   * Synchronously produces the raw instance for a binding **without** touching the scope cache
-   * or running lifecycle hooks. The caller ({@link instantiateBinding}) wraps this with
-   * cache logic and post-construction hooks.
-   *
-   * Dispatches on `binding.kind`; throws {@link AsyncResolutionError} if the binding is
-   * `async-dynamic` or if a `dynamic` / `resolved` factory returns a Promise.
-   */
-  private materialize;
-  /**
-   * Async counterpart of {@link materialize}; awaits `async-dynamic` factories and
-   * recursively resolves `resolved`-binding dependencies with {@link resolveAsync}.
-   */
-  private materializeAsync;
-  /**
-   * Reads `@injectable()` constructor metadata and synchronously resolves each parameter,
-   * then calls `new ImplementationClass(...deps)`. Throws {@link MissingMetadataError} when
-   * the class has constructor parameters but no metadata.
-   */
-  private instantiateClassBinding;
-  /**
-   * Async counterpart of {@link instantiateClassBinding}: resolves constructor dependencies
-   * with {@link resolveAsync} so `async-dynamic` parameters are awaited in order.
-   */
-  private instantiateClassBindingAsync;
+  private readonly _registry;
+  private readonly _scope;
+  private readonly _lifecycle;
+  private readonly _metadataReader;
+  private readonly _container;
+  private readonly _parent;
+  private readonly _frameByBindingId;
+  private readonly _syncResolutionContextPool;
+  private readonly _deepCycleMarks;
+  private _deepCycleGen;
+  private _deepActiveLevels;
+  private _deepSyncCtx;
+  private _deepSyncCtxPath;
+  private _deepAsyncCtx;
+  private _deepAsyncCtxPath;
+  private _deepAsyncActiveLevels;
+  private readonly _classHasPostConstruct;
+  private readonly _classNeedsActiveContainer;
+  private readonly _classConstructorMetadata;
+  private readonly _activationNeedByBindingId;
+  private _activationCacheVersion;
+  constructor(_registry: BindingRegistry, _scope: ScopeManager, _lifecycle: LifecycleManager, _metadataReader: MetadataReader, _container: Container, _parent: DependencyResolver | undefined);
+  private _findBinding;
+  resolveFromContext<const Value>(token: Token<Value> | Constructor<Value>, resolutionPath: string[], materializationStack: MaterializationFrame[]): Value;
+  resolve<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Value;
+  private _resolveBinding;
+  private _instantiateSync;
+  private _resolveClassDeps;
+  private _resolveDescriptorDeps;
+  resolveOptional<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Value | undefined;
+  resolveAll<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Value[];
+  resolveAsyncFromContext<const Value>(token: Token<Value> | Constructor<Value>, resolutionPath: string[], materializationStack: MaterializationFrame[]): Promise<Value>;
+  resolveAsync<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Promise<Value>;
+  private _resolveBindingAsync;
+  private _instantiateAsync;
+  private _resolveClassDepsAsync;
+  private _resolveDescriptorDepsAsync;
+  resolveOptionalAsync<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Promise<Value | undefined>;
+  resolveAllAsync<const Value>(token: Token<Value> | Constructor<Value>, hint: ResolveOptions | undefined, resolutionPath: string[], materializationStack: MaterializationFrame[]): Promise<Value[]>;
+  private _getAllBindingsFromChain;
+  private _getSimpleNamedBindingsFromChain;
+  private _getAvailableSlots;
+  private _makeConstraintContext;
+  private _matchesBindingFast;
+  private _matchesSlotFast;
+  private _getTokenName;
+  private _getConstructorMetadata;
+  private _instantiateClass;
+  private _matchesHintTag;
+  private _resolveTransientDynamicSyncFromContext;
+  private _resolveTransientDynamicSyncSlow;
+  private _resolveTransientDynamicAsyncFromContext;
+  private _resolveTransientDynamicAsyncSlow;
+  private _resolveCandidateSync;
+  private _resolveCandidateAsync;
+  private _getMaterializationFrame;
+  private _needsActivation;
+  private _refreshClassPostConstructCache;
+  private _requiresResolutionContext;
+  private _acquireSyncResolutionContext;
 }
 //#endregion
-export { DependencyResolver, ResolverDependencies };
+export { DependencyResolver };