@codefast/di 0.3.14-canary.1 → 0.3.14

package/dist/binding.d.mts

@@ -1,352 +1,124 @@
-import { Token, TokenValue } from "./token.mjs";
-import { RegistryKey } from "./registry.mjs";
+import { Constructor } from "./constructor-type.mjs";
+import { Token } from "./token.mjs";
+import { ActivationHandler, BindingIdentifier, BindingScope, ConstraintContext, DeactivationHandler, DependencyKey, ResolutionContext, TokenValue } from "./types.mjs";
+import { InjectionDescriptor } from "./decorators/inject.mjs";
 
 //#region src/binding.d.ts
-declare const bindingIdentifierBrand: unique symbol;
-/**
- * Stable, opaque identifier for a single binding entry inside the registry.
- */
-type BindingIdentifier = string & {
-  readonly [bindingIdentifierBrand]: void;
-};
-/**
- * Allocates a new opaque binding identifier (used when `.id(...)` is not supplied).
- */
-declare function createBindingIdentifier(): BindingIdentifier;
-/**
- * Runtime constructor token used as a registry key (no reflection metadata).
- */
-type Constructor<Value> = abstract new (...args: never[]) => Value;
-/**
- * Lifetime strategy for a resolved instance.
- */
-type BindingScope = "singleton" | "transient" | "scoped";
-/**
- * Hint for disambiguating multi-bindings registered against the same token or constructor.
- */
-type ResolveHint = {
-  /** Matches bindings configured with `.whenNamed(name)`. */readonly name?: string; /** Matches bindings configured with `.whenTagged(tagKey, value)`. */
-  readonly tag?: readonly [tag: string, value: unknown];
-};
-/**
- * Public alias for {@link ResolveHint} — the `hint` parameter accepted by
- * `Container.resolve`, `Container.resolveAsync`, and related methods.
- * Passes `name` and/or `tag` to select among multi-bindings.
- */
-type ResolveOptions = ResolveHint;
-/**
- * Snapshot of a binding on the materialization stack (for {@link ConstraintContext}).
- */
-type ConstraintBindingKind = "constant" | "class" | "dynamic" | "async-dynamic" | "resolved" | "alias";
-/**
- * Snapshot of a single binding on the materialization stack during resolution.
- * Each frame captures enough identity to implement contextual constraints
- * ({@link whenParentIs}, {@link whenAnyAncestorIs}) and captive-dependency detection.
- */
-type ConstraintParentFrame = {
-  /** Registry key (token/constructor) that selected this binding. */readonly registryKey: RegistryKey; /** Stable identifier of the materialized binding. */
-  readonly bindingId: BindingIdentifier; /** Discriminant of the selected binding strategy. */
-  readonly bindingKind: ConstraintBindingKind; /** Immutable tag map present on the selected binding. */
-  readonly tags: ReadonlyMap<string, unknown>; /** Effective scope of the selected binding. */
-  readonly scope: BindingScope;
-};
-/**
- * @alias {@link ConstraintParentFrame} — frame on the materialization stack during resolution.
- */
-type MaterializationFrame = ConstraintParentFrame;
-/**
- * Context for {@link BindingBuilder.when} predicates: path, ancestor metadata, and the current resolve hint.
- */
-type ConstraintContext = {
-  /** Resolution labels from root request to current key. */readonly resolutionPath: readonly string[]; /** Full chain of materialized parent frames (oldest → newest). */
-  readonly materializationStack: readonly ConstraintParentFrame[]; /** Immediate parent frame, if the current resolution has one. */
-  readonly parent: ConstraintParentFrame | undefined; /** Parent chain excluding the immediate parent frame. */
-  readonly ancestors: readonly ConstraintParentFrame[]; /** Name/tag hint used for the current lookup, if provided. */
-  readonly currentResolveHint: ResolveHint | undefined;
-};
-/**
- * Context passed to factories and lifecycle hooks so nested dependencies resolve with the same path rules.
- *
- * `graph` exposes the current position in the dependency graph (resolution path, materialization
- * stack, parent/ancestor frames) — used by {@link BindingBuilder.when} predicates to implement
- * context-sensitive bindings such as `whenParentIs` or `whenAnyAncestorIs`.
- */
-type ResolutionContext = {
-  /** Resolves one binding synchronously using current path/stack context. */readonly resolve: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value; /** Async variant of {@link ResolutionContext.resolve}. */
-  readonly resolveAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value>; /** Returns `undefined` when the requested root key is unbound. */
-  readonly resolveOptional: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value | undefined; /** Resolves every binding registered for `token` (multi-binding). */
-  readonly resolveAll: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value[]; /** Async variant of {@link ResolutionContext.resolveAll}. */
-  readonly resolveAllAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value[]>;
-  /**
-   * Dependency-graph navigation context — path, materialization stack, parent/ancestor frames.
-   */
-  readonly graph: ConstraintContext;
-};
-/**
- * Lifecycle and constraint fields shared by every concrete {@link Binding} variant.
- * Separated from {@link BindingBase} so the builder can accumulate them independently of `id` / `scope`.
- */
-type BindingLifecycle = {
-  readonly bindingName?: string;
-  readonly tags: ReadonlyMap<string, unknown>;
-  readonly onActivation?: ActivationHandler<unknown>;
-  readonly onDeactivation?: DeactivationHandler<unknown>;
-  readonly constraint?: (ctx: ConstraintContext) => boolean;
-};
-/**
- * Called after an instance is constructed (and after `@postConstruct`).
- * The return value replaces the instance in the scope cache — use this to wrap with a proxy or
- * apply post-processing. May be async; async handlers require `resolveAsync`.
- */
-type ActivationHandler<Value> = (ctx: ResolutionContext, instance: Value) => Value | Promise<Value>;
-/**
- * Called before a singleton/scoped instance is evicted from the scope cache.
- * Runs after `@preDestroy`. May be async; async deactivation requires `disposeAsync` / `unloadAsync`.
- */
-type DeactivationHandler<Value> = (instance: Value) => void | Promise<void>;
-type BindingBase = BindingLifecycle & {
+interface SlotKey {
+  readonly name: string | undefined;
+  readonly tags: ReadonlyArray<readonly [tag: string, value: unknown]>;
+}
+declare function slotKeyEquals(a: SlotKey, b: SlotKey): boolean;
+declare const DEFAULT_SLOT: SlotKey;
+declare function slotKeyToString(slot: SlotKey): string;
+interface BindingBase<Value> {
   readonly id: BindingIdentifier;
-  readonly scope: BindingScope;
-  /**
-   * Set when the binding was registered from {@link Module} / {@link AsyncModule} setup.
-   */
-  readonly moduleId?: string;
-};
-/**
- * Binding backed by a pre-existing constant value; always singleton, no construction cost.
- */
-type ConstantBinding<Value> = BindingBase & {
-  readonly kind: "constant";
-  readonly value: Value;
-};
-/**
- * Binding that constructs `implementationClass` via the container's metadata-driven instantiation.
- */
-type ClassBinding<Value> = BindingBase & {
+  readonly token: Token<Value> | Constructor<Value>;
+  readonly slot: SlotKey;
+  readonly predicate?: (ctx: ConstraintContext) => boolean;
+}
+interface ClassBinding<Value> extends BindingBase<Value> {
   readonly kind: "class";
-  readonly implementationClass: Constructor<Value>;
-};
-/**
- * Binding backed by a synchronous factory that receives a {@link ResolutionContext}.
- */
-type DynamicBinding<Value> = BindingBase & {
+  readonly target: Constructor<Value>;
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface DynamicBinding<Value> extends BindingBase<Value> {
   readonly kind: "dynamic";
   readonly factory: (ctx: ResolutionContext) => Value;
-};
-/**
- * Binding backed by an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`.
- */
-type AsyncDynamicBinding<Value> = BindingBase & {
-  readonly kind: "async-dynamic";
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface DynamicAsyncBinding<Value> extends BindingBase<Value> {
+  readonly kind: "dynamic-async";
   readonly factory: (ctx: ResolutionContext) => Promise<Value>;
-};
-/**
- * Binding whose dependencies are declared statically and pre-resolved before the factory is called.
- */
-type ResolvedBinding<Value> = BindingBase & {
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface ResolvedBinding<Value> extends BindingBase<Value> {
   readonly kind: "resolved";
-  readonly dependencyTokens: readonly (Token<unknown> | Constructor<unknown>)[];
   readonly factory: (...args: unknown[]) => Value;
-};
-/**
- * Binding that forwards resolution to `targetToken`; the container resolves whatever is bound there.
- */
-type AliasBinding<Value> = BindingBase & {
+  readonly deps: readonly InjectionDescriptor[];
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface ResolvedAsyncBinding<Value> extends BindingBase<Value> {
+  readonly kind: "resolved-async";
+  readonly factory: (...args: unknown[]) => Promise<Value>;
+  readonly deps: readonly InjectionDescriptor[];
+  readonly scope: BindingScope;
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface ConstantBinding<Value> extends BindingBase<Value> {
+  readonly kind: "constant";
+  readonly value: Value;
+  readonly scope: "singleton";
+  readonly onActivation?: ActivationHandler<Value>;
+  readonly onDeactivation?: DeactivationHandler<Value>;
+}
+interface AliasBinding<Value> extends BindingBase<Value> {
   readonly kind: "alias";
-  readonly targetToken: Token<Value>;
-};
-/**
- * Discriminated union of all binding strategies the container can resolve.
- */
-type Binding<Value> = ConstantBinding<Value> | ClassBinding<Value> | DynamicBinding<Value> | AsyncDynamicBinding<Value> | ResolvedBinding<Value> | AliasBinding<Value>;
-/**
- * Callbacks injected by the owning container to sync each builder mutation into the registry.
- * `register` fires once when a `to*(…)` strategy is selected; `update` fires on every
- * subsequent chain call (`.singleton()`, `.onActivation()`, …).
- */
-type RegistryCallbacks<Value> = {
-  readonly register?: (binding: Binding<Value>) => void;
-  readonly update?: (binding: Binding<Value>) => void;
-};
-/**
- * Fluent builder for registering a single binding against a {@link Token} or {@link Constructor}.
- *
- * A builder has two phases:
- * 1. **Strategy selection** — exactly one `to*()` call (`to`, `toSelf`, `toConstantValue`,
- *    `toDynamic`, `toDynamicAsync`, `toResolved`, `toAlias`) that determines how the value is produced.
- * 2. **Refinement chain** — optional calls to `singleton()`, `transient()`, `scoped()`,
- *    `onActivation()`, `onDeactivation()`, `whenNamed()`, `whenTagged()`, `when()`, and `id()`.
- *
- * Calling a second `to*()` method throws {@link InternalError}.
- *
- * The builder is created by {@link Container.bind} or by `bind` on {@link ModuleBuilder}.
- * The container injects {@link RegistryCallbacks} so that every strategy selection and
- * refinement is immediately reflected in the live registry.
- */
-declare class BindingBuilder<Value> {
-  protected readonly bindingKey: Token<Value> | Constructor<Value>;
-  /**
-   * Current resolution strategy; starts as `"unset"` until a `to*()` method is called.
-   */
-  private strategy;
-  /**
-   * Lifetime scope applied to the next binding snapshot; defaults to `"transient"`.
-   */
-  private scope;
-  /**
-   * True after an explicit `.singleton()` / `.transient()` / `.scoped()` call (prevents constant scope change).
-   */
-  private isScopeExplicit;
-  /**
-   * Pre-allocated binding ID set via `id(identifier)` before the first `to*()` call.
-   */
-  private explicitId;
-  /**
-   * Resolve-hint name filter set by `.whenNamed()`.
-   */
-  private bindingName;
-  /**
-   * Tag filters accumulated by successive `.whenTagged()` calls.
-   */
-  private readonly tags;
-  /**
-   * Custom constraint predicates accumulated by `.when()`; all must pass for this binding to be selected.
-   */
-  private readonly constraintPredicates;
-  /**
-   * Latest `onActivation` hook provided by `.onActivation(...)`.
-   * Applied to emitted binding snapshots until replaced.
-   */
-  private onActivationHandler;
-  /**
-   * Latest `onDeactivation` hook provided by `.onDeactivation(...)`.
-   * Emitted only on builder variants that expose deactivation support.
-   */
-  private onDeactivationHandler;
-  /**
-   * Set when this binding was created inside a {@link Module} / {@link AsyncModule} setup callback.
-   */
-  private readonly moduleId;
-  /**
-   * The most recently emitted {@link Binding} snapshot; `undefined` before the first `to*()` call.
-   */
-  private currentBinding;
-  /**
-   * Container-injected hooks that sync builder mutations into the live registry.
-   */
-  private readonly callbacks;
-  constructor(bindingKey: Token<Value> | Constructor<Value>, moduleId?: string, callbacks?: RegistryCallbacks<Value>);
-  /**
-   * Binds the token to a concrete implementation class; the container constructs it on demand.
-   */
-  to<C extends Constructor<Value>>(implementationClass: C): TransientBindingBuilder<Value>;
-  /**
-   * Binds the class key to itself — only valid when the key is a constructor.
-   */
-  toSelf(): TransientBindingBuilder<Value>;
-  /**
-   * Binds the token to a pre-existing value; always resolved as singleton, no construction.
-   */
-  toConstantValue<const ConcreteValue extends Value>(value: ConcreteValue): ConstantBindingBuilder<Value>;
-  /**
-   * Binds to a synchronous factory; `ctx` provides nested resolution within the same path.
-   */
-  toDynamic(factory: (ctx: ResolutionContext) => Value): TransientBindingBuilder<Value>;
-  /**
-   * Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`.
-   */
-  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): TransientBindingBuilder<Value>;
-  /**
-   * Binds to a factory whose dependencies are declared explicitly in `deps` and pre-resolved by
-   * the container before the factory is called — no `ResolutionContext` needed inside the factory.
-   */
-  toResolved<Deps extends readonly (Token<unknown> | Constructor<unknown>)[]>(factory: (...args: { [Index in keyof Deps]: TokenValue<Deps[Index]> }) => Value, deps: Deps): TransientBindingBuilder<Value>;
-  /**
-   * Redirects resolution to `targetToken`; the container resolves whatever is bound there.
-   */
-  toAlias(targetToken: Token<Value>): TransientBindingBuilder<Value>;
-  /**
-   * One instance per container; supports `onDeactivation`.
-   */
+  readonly target: Token<Value> | Constructor<Value>;
+}
+type Binding<Value = unknown> = ClassBinding<Value> | DynamicBinding<Value> | DynamicAsyncBinding<Value> | ResolvedBinding<Value> | ResolvedAsyncBinding<Value> | ConstantBinding<Value> | AliasBinding<Value>;
+/** Builder-only payload before `id`, `token`, `slot`, and `predicate` are applied. */
+type PartialBinding<Value> = Omit<ClassBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<DynamicBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<DynamicAsyncBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<ResolvedBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<ResolvedAsyncBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<ConstantBinding<Value>, "id" | "token" | "slot" | "predicate"> | Omit<AliasBinding<Value>, "id" | "token" | "slot" | "predicate">;
+declare function generateBindingId(): BindingIdentifier;
+interface BindToBuilder<Value> {
+  to(type: Constructor<Value>): BindingBuilder<Value>;
+  toSelf(): BindingBuilder<Value>;
+  toConstantValue(value: Value): ConstantBindingBuilder<Value>;
+  toDynamic(factory: (ctx: ResolutionContext) => Value): BindingBuilder<Value>;
+  toDynamicAsync(factory: (ctx: ResolutionContext) => Promise<Value>): BindingBuilder<Value>;
+  toResolved<const Deps extends readonly DependencyKey[]>(factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Value, deps: Deps): BindingBuilder<Value>;
+  toResolvedAsync<const Deps extends readonly DependencyKey[]>(factory: (...args: { [K in keyof Deps]: TokenValue<NoInfer<Deps>[K]> }) => Promise<Value>, deps: Deps): BindingBuilder<Value>;
+  toAlias(target: Token<Value> | Constructor<Value>): AliasBindingBuilder;
+}
+interface BindingBuilder<Value> {
+  when(predicate: (ctx: ConstraintContext) => boolean): this;
+  whenNamed(name: string): this;
+  whenTagged(tag: string, value: unknown): this;
+  whenDefault(): this;
   singleton(): SingletonBindingBuilder<Value>;
-  /**
-   * New instance on every resolution (default scope).
-   */
   transient(): TransientBindingBuilder<Value>;
-  /**
-   * One instance per child container scope.
-   */
   scoped(): ScopedBindingBuilder<Value>;
-  /**
-   * Called with the resolved instance after construction; the return value replaces the instance.
-   */
-  onActivation(handler: ActivationHandler<Value>): this;
-  /**
-   * @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases.
-   */
-  onDeactivation(handler: DeactivationHandler<Value>): this;
-  /**
-   * This binding only resolves when the caller passes `{ name }` as the resolve hint.
-   */
+  id(): BindingIdentifier;
+}
+interface ConstantBindingBuilder<Value> {
+  when(predicate: (ctx: ConstraintContext) => boolean): this;
+  whenNamed(name: string): this;
+  whenTagged(tag: string, value: unknown): this;
+  whenDefault(): this;
+  onActivation(fn: ActivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+  onDeactivation(fn: DeactivationHandler<Value>): SingletonLifecycleBuilder<Value>;
+  id(): BindingIdentifier;
+}
+interface AliasBindingBuilder {
+  when(predicate: (ctx: ConstraintContext) => boolean): this;
   whenNamed(name: string): this;
-  /**
-   * This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint.
-   */
-  whenTagged(tag: string, tagValue: unknown): this;
-  /**
-   * Adds a custom predicate; all predicates must pass for the binding to be selected.
-   */
-  when(constraint: (ctx: ConstraintContext) => boolean): this;
-  /**
-   * Returns the binding's stable ID, allocating one if needed.
-   * Passing an `identifier` pre-sets the ID before a `to*()` call — useful when modules need to
-   * reference a binding ID before it is registered.
-   */
+  whenTagged(tag: string, value: unknown): this;
+  whenDefault(): this;
+  id(): BindingIdentifier;
+}
+interface SingletonBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+interface TransientBindingBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  id(): BindingIdentifier;
+}
+interface ScopedBindingBuilder<Value> extends TransientBindingBuilder<Value> {}
+interface SingletonLifecycleBuilder<Value> {
+  onActivation(fn: ActivationHandler<Value>): this;
+  onDeactivation(fn: DeactivationHandler<Value>): this;
   id(): BindingIdentifier;
-  id(identifier: BindingIdentifier): BindingIdentifier;
-  /**
-   * Records the chosen strategy and emits the first {@link Binding} snapshot.
-   * Throws {@link InternalError} if a strategy was already selected (double `to*()` call).
-   */
-  private registerWithStrategy;
-  /**
-   * Re-creates the {@link Binding} snapshot from the current builder state and pushes
-   * the update to the registry. No-op if no strategy has been set yet.
-   */
-  private refreshRegisteredBinding;
-  /**
-   * Guards against calling `.singleton()` / `.transient()` / `.scoped()` on a constant binding,
-   * which is locked to `"singleton"` scope by invariant.
-   */
-  private assertScopeMutable;
-  /**
-   * Produces an immutable {@link Binding} snapshot from the current builder fields.
-   * Called by both {@link registerWithStrategy} and {@link refreshRegisteredBinding}.
-   */
-  private createBinding;
 }
-/**
- * Builder returned after calling `.singleton()` — exposes `onDeactivation`.
- */
-type SingletonBindingBuilder<Value> = BindingBuilder<Value>;
-/**
- * Builder returned after calling `.transient()`, or any strategy method before a scope is set.
- * Does NOT expose `onDeactivation` at the type level.
- */
-type TransientBindingBuilder<Value> = Omit<BindingBuilder<Value>, "onDeactivation">;
-/**
- * Builder returned after calling `.scoped()`.
- * Does NOT expose `onDeactivation` at the type level.
- */
-type ScopedBindingBuilder<Value> = Omit<BindingBuilder<Value>, "onDeactivation">;
-/**
- * Builder returned after calling `.toConstantValue()`.
- */
-type ConstantBindingBuilder<Value> = Omit<SingletonBindingBuilder<Value>, "singleton" | "transient" | "scoped">;
-/**
- * Starts a fluent binding for the given token or constructor key.
- */
-declare function bind<Value>(key: Token<Value>): BindingBuilder<Value>;
-declare function bind<Value>(key: Constructor<Value>): BindingBuilder<Value>;
 //#endregion
-export { ActivationHandler, AliasBinding, AsyncDynamicBinding, Binding, BindingBuilder, BindingIdentifier, BindingScope, ClassBinding, ConstantBinding, ConstantBindingBuilder, ConstraintBindingKind, ConstraintContext, ConstraintParentFrame, Constructor, DeactivationHandler, DynamicBinding, MaterializationFrame, ResolutionContext, ResolveHint, ResolveOptions, ResolvedBinding, ScopedBindingBuilder, SingletonBindingBuilder, TransientBindingBuilder, bind, createBindingIdentifier };
+export { AliasBinding, AliasBindingBuilder, BindToBuilder, Binding, BindingBuilder, ClassBinding, ConstantBinding, ConstantBindingBuilder, DEFAULT_SLOT, DynamicAsyncBinding, DynamicBinding, PartialBinding, ResolvedAsyncBinding, ResolvedBinding, ScopedBindingBuilder, SingletonBindingBuilder, SingletonLifecycleBuilder, SlotKey, TransientBindingBuilder, generateBindingId, slotKeyEquals, slotKeyToString };