@codefast/di 0.3.13-canary.4

package/dist/binding-select.mjs

@@ -0,0 +1,50 @@
+import { InternalError, NoMatchingBindingError, TokenNotBoundError } from "./errors.mjs";
+//#region src/binding-select.ts
+/** Returns a human-readable label for a token or constructor (used in error messages and graph output). */
+function registryKeyLabel(key) {
+	if (typeof key === "function") return key.name.length > 0 ? key.name : "(anonymous class)";
+	return key.name.trim().length > 0 ? key.name : "(anonymous token)";
+}
+/**
+* Applies resolve hints and optional constraint predicates to a binding list.
+*/
+function filterMatchingBindings(bindings, hint, constraintCtx) {
+	let candidates = [...bindings];
+	if (hint?.name !== void 0) candidates = candidates.filter((binding) => binding.bindingName === hint.name);
+	if (hint?.tag !== void 0) {
+		const [tagKey, tagValue] = hint.tag;
+		candidates = candidates.filter((binding) => Object.is(binding.tags.get(tagKey), tagValue));
+	}
+	if (constraintCtx !== void 0) candidates = candidates.filter((binding) => binding.constraint === void 0 || binding.constraint(constraintCtx));
+	return candidates;
+}
+/**
+* Picks the binding that would be used for resolution with the given hint (same rules as {@link DependencyResolver}).
+* When `constraintCtx` is set, bindings with a {@link BindingBuilder.when} predicate must pass it.
+*/
+function selectBindingForRegistry(bindings, hint, tokenLabel, pathLabels, constraintCtx) {
+	if (bindings.length === 0) throw new TokenNotBoundError(tokenLabel, [...pathLabels]);
+	const candidates = filterMatchingBindings(bindings, hint, constraintCtx);
+	if (candidates.length === 1) {
+		const [only] = candidates;
+		if (only === void 0) throw new InternalError(`Internal: expected binding candidate for "${tokenLabel}" (resolution path: ${pathLabels.join(" -> ")})`);
+		return only;
+	}
+	if (candidates.length === 0) {
+		if (hint !== void 0 && (hint.name !== void 0 || hint.tag !== void 0)) throw new NoMatchingBindingError(tokenLabel, hint, [...pathLabels]);
+		throw new TokenNotBoundError(tokenLabel, [...pathLabels]);
+	}
+	throw new InternalError(`Ambiguous binding for "${tokenLabel}": ${String(candidates.length)} candidates matched after applying ResolveHint (resolution path: ${pathLabels.join(" -> ")})`);
+}
+/**
+* Resolves the effective binding for a registry key using the default (no-hint) selection rules.
+*/
+function selectDefaultBindingForKey(lookup, key, pathPrefix) {
+	const label = registryKeyLabel(key);
+	const nextPath = [...pathPrefix, label];
+	const bindings = lookup(key);
+	if (bindings === void 0 || bindings.length === 0) throw new TokenNotBoundError(label, nextPath);
+	return selectBindingForRegistry(bindings, void 0, label, nextPath, void 0);
+}
+//#endregion
+export { filterMatchingBindings, registryKeyLabel, selectBindingForRegistry, selectDefaultBindingForKey };

package/dist/binding.d.mts

@@ -0,0 +1,219 @@
+import { Token, TokenValue } from "./token.mjs";
+import { RegistryKey } from "./registry.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 = {
+  readonly name?: string;
+  readonly tag?: readonly [tag: string, value: unknown];
+};
+type ResolveOptions = ResolveHint;
+/**
+ * Snapshot of a binding on the materialization stack (for {@link ConstraintContext}).
+ */
+type ConstraintBindingKind = "constant" | "class" | "dynamic" | "async-dynamic" | "resolved" | "alias";
+type ConstraintParentFrame = {
+  readonly registryKey: RegistryKey;
+  readonly bindingId: BindingIdentifier;
+  readonly bindingKind: ConstraintBindingKind;
+  readonly tags: ReadonlyMap<string, unknown>;
+  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 = {
+  readonly resolutionPath: readonly string[];
+  readonly materializationStack: readonly ConstraintParentFrame[];
+  readonly parent: ConstraintParentFrame | undefined;
+  readonly ancestors: readonly ConstraintParentFrame[];
+  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 = {
+  readonly resolve: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value;
+  readonly resolveAsync: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Promise<Value>;
+  readonly resolveOptional: <Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveOptions) => Value | undefined; /** Dependency-graph navigation context — path, materialization stack, parent/ancestor frames. */
+  readonly graph: ConstraintContext;
+};
+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 & {
+  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 kind: "class";
+  readonly implementationClass: Constructor<Value>;
+};
+/** Binding backed by a synchronous factory that receives a {@link ResolutionContext}. */
+type DynamicBinding<Value> = BindingBase & {
+  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 factory: (ctx: ResolutionContext) => Promise<Value>;
+};
+/** Binding whose dependencies are declared statically and pre-resolved before the factory is called. */
+type ResolvedBinding<Value> = BindingBase & {
+  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 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;
+};
+declare class BindingBuilder<Value> {
+  protected readonly bindingKey: Token<Value> | Constructor<Value>;
+  private strategy;
+  private scope;
+  private isScopeExplicit;
+  private explicitId;
+  private bindingName;
+  private readonly tags;
+  private readonly constraintPredicates;
+  private onActivationHandler;
+  private onDeactivationHandler;
+  private readonly moduleId;
+  private currentBinding;
+  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`. */
+  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. */
+  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.
+   */
+  id(): BindingIdentifier;
+  id(identifier: BindingIdentifier): BindingIdentifier;
+  private registerWithStrategy;
+  private refreshRegisteredBinding;
+  private assertScopeMutable;
+  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 };

package/dist/binding.mjs

@@ -0,0 +1,240 @@
+import { InternalError } from "./errors.mjs";
+//#region src/binding.ts
+/**
+* Allocates a new opaque binding identifier (used when `.id(...)` is not supplied).
+*/
+function createBindingIdentifier() {
+	return globalThis.crypto.randomUUID();
+}
+var BindingBuilder = class {
+	strategy = { type: "unset" };
+	scope = "transient";
+	isScopeExplicit = false;
+	explicitId;
+	bindingName;
+	tags = /* @__PURE__ */ new Map();
+	constraintPredicates = [];
+	onActivationHandler;
+	onDeactivationHandler;
+	moduleId;
+	currentBinding;
+	callbacks;
+	constructor(bindingKey, moduleId, callbacks) {
+		this.bindingKey = bindingKey;
+		this.moduleId = moduleId;
+		this.callbacks = callbacks ?? {};
+	}
+	/** Binds the token to a concrete implementation class; the container constructs it on demand. */
+	to(implementationClass) {
+		this.registerWithStrategy({
+			type: "class",
+			implementationClass
+		});
+		return this;
+	}
+	/** Binds the class key to itself — only valid when the key is a constructor. */
+	toSelf() {
+		if (typeof this.bindingKey !== "function") throw new InternalError("toSelf() requires the binding key to be a constructor; use bind(SomeClass) or call to(Class) instead.");
+		this.registerWithStrategy({
+			type: "class",
+			implementationClass: this.bindingKey
+		});
+		return this;
+	}
+	/** Binds the token to a pre-existing value; always resolved as singleton, no construction. */
+	toConstantValue(value) {
+		this.scope = "singleton";
+		this.registerWithStrategy({
+			type: "constant",
+			value
+		});
+		return this;
+	}
+	/** Binds to a synchronous factory; `ctx` provides nested resolution within the same path. */
+	toDynamic(factory) {
+		this.registerWithStrategy({
+			type: "dynamic",
+			factory
+		});
+		return this;
+	}
+	/** Binds to an async factory; must be resolved via `resolveAsync` / `resolveAllAsync`. */
+	toDynamicAsync(factory) {
+		this.registerWithStrategy({
+			type: "async-dynamic",
+			factory
+		});
+		return this;
+	}
+	/**
+	* 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(factory, deps) {
+		this.registerWithStrategy({
+			type: "resolved",
+			factory,
+			dependencyTokens: deps
+		});
+		return this;
+	}
+	/** Redirects resolution to `targetToken`; the container resolves whatever is bound there. */
+	toAlias(targetToken) {
+		this.registerWithStrategy({
+			type: "alias",
+			targetToken
+		});
+		return this;
+	}
+	/** One instance per container; supports `onDeactivation`. */
+	singleton() {
+		this.assertScopeMutable();
+		this.scope = "singleton";
+		this.isScopeExplicit = true;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** New instance on every resolution (default scope). */
+	transient() {
+		this.assertScopeMutable();
+		this.scope = "transient";
+		this.isScopeExplicit = true;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** One instance per child container scope. */
+	scoped() {
+		this.assertScopeMutable();
+		this.scope = "scoped";
+		this.isScopeExplicit = true;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** Called with the resolved instance after construction; the return value replaces the instance. */
+	onActivation(handler) {
+		this.onActivationHandler = handler;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** @internal Keep public for runtime correctness; hidden from transient/scoped builders via type aliases. */
+	onDeactivation(handler) {
+		this.onDeactivationHandler = handler;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** This binding only resolves when the caller passes `{ name }` as the resolve hint. */
+	whenNamed(name) {
+		this.bindingName = name;
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** This binding only resolves when the caller passes `{ tag: [tag, tagValue] }` as the resolve hint. */
+	whenTagged(tag, tagValue) {
+		this.tags.set(tag, tagValue);
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	/** Adds a custom predicate; all predicates must pass for the binding to be selected. */
+	when(constraint) {
+		this.constraintPredicates.push(constraint);
+		this.refreshRegisteredBinding();
+		return this;
+	}
+	id(identifier) {
+		if (this.currentBinding !== void 0) {
+			if (identifier !== void 0 && identifier !== this.currentBinding.id) throw new InternalError("Cannot change binding identifier after registration.");
+			return this.currentBinding.id;
+		}
+		if (identifier !== void 0) {
+			this.explicitId = identifier;
+			return this.explicitId;
+		}
+		this.explicitId = this.explicitId ?? createBindingIdentifier();
+		return this.explicitId;
+	}
+	registerWithStrategy(next) {
+		if (this.strategy.type !== "unset") throw new InternalError("A binding strategy was already selected; only one to*(...) chain is allowed per builder.");
+		this.strategy = next;
+		const bindingId = this.id();
+		const binding = this.createBinding(bindingId, next);
+		this.currentBinding = binding;
+		this.callbacks.register?.(binding);
+	}
+	refreshRegisteredBinding() {
+		if (this.currentBinding === void 0 || this.strategy.type === "unset") return;
+		const next = this.createBinding(this.currentBinding.id, this.strategy);
+		this.currentBinding = next;
+		this.callbacks.update?.(next);
+	}
+	assertScopeMutable() {
+		if (this.strategy.type === "constant") throw new InternalError("Constant bindings are always singleton and do not support scope changes.");
+	}
+	createBinding(id, strategy) {
+		const constraint = this.constraintPredicates.length === 0 ? void 0 : (ctx) => this.constraintPredicates.every((predicate) => predicate(ctx));
+		const lifecycle = {
+			bindingName: this.bindingName,
+			tags: new Map(this.tags),
+			onActivation: this.onActivationHandler,
+			onDeactivation: this.onDeactivationHandler,
+			constraint
+		};
+		const moduleFields = this.moduleId === void 0 ? {} : { moduleId: this.moduleId };
+		switch (strategy.type) {
+			case "constant": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: "singleton",
+				kind: "constant",
+				value: strategy.value
+			};
+			case "class": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: this.scope,
+				kind: "class",
+				implementationClass: strategy.implementationClass
+			};
+			case "dynamic": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: this.scope,
+				kind: "dynamic",
+				factory: strategy.factory
+			};
+			case "async-dynamic": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: this.scope,
+				kind: "async-dynamic",
+				factory: strategy.factory
+			};
+			case "resolved": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: this.scope,
+				kind: "resolved",
+				dependencyTokens: strategy.dependencyTokens,
+				factory: strategy.factory
+			};
+			case "alias": return {
+				...lifecycle,
+				...moduleFields,
+				id,
+				scope: this.scope,
+				kind: "alias",
+				targetToken: strategy.targetToken
+			};
+			default: return strategy;
+		}
+	}
+};
+function bind(key) {
+	return new BindingBuilder(key, void 0);
+}
+//#endregion
+export { BindingBuilder, bind, createBindingIdentifier };

package/dist/constraints.d.mts

@@ -0,0 +1,18 @@
+import { Token } from "./token.mjs";
+import { ConstraintContext, Constructor } from "./binding.mjs";
+
+//#region src/constraints.d.ts
+/**
+ * Matches when the direct parent materialization was registered for `registryKey`.
+ */
+declare function whenParentIs(registryKey: Token<unknown> | Constructor<unknown>): (ctx: ConstraintContext) => boolean;
+/**
+ * Matches when any ancestor on the materialization stack was registered for `registryKey`.
+ */
+declare function whenAnyAncestorIs(registryKey: Token<unknown> | Constructor<unknown>): (ctx: ConstraintContext) => boolean;
+/**
+ * Matches when the immediate parent binding carries `tag` with `tagValue` (same metadata as {@link BindingBuilder.whenTagged} on the parent).
+ */
+declare function whenTargetTagged(tag: string, tagValue: unknown): (ctx: ConstraintContext) => boolean;
+//#endregion
+export { whenAnyAncestorIs, whenParentIs, whenTargetTagged };

package/dist/constraints.mjs

@@ -0,0 +1,24 @@
+//#region src/constraints.ts
+/**
+* Matches when the direct parent materialization was registered for `registryKey`.
+*/
+function whenParentIs(registryKey) {
+	return (ctx) => ctx.parent?.registryKey === registryKey;
+}
+/**
+* Matches when any ancestor on the materialization stack was registered for `registryKey`.
+*/
+function whenAnyAncestorIs(registryKey) {
+	return (ctx) => ctx.materializationStack.some((frame) => frame.registryKey === registryKey);
+}
+/**
+* Matches when the immediate parent binding carries `tag` with `tagValue` (same metadata as {@link BindingBuilder.whenTagged} on the parent).
+*/
+function whenTargetTagged(tag, tagValue) {
+	return (ctx) => {
+		if (ctx.parent === void 0) return false;
+		return Object.is(ctx.parent.tags.get(tag), tagValue);
+	};
+}
+//#endregion
+export { whenAnyAncestorIs, whenParentIs, whenTargetTagged };

package/dist/container.d.mts

@@ -0,0 +1,82 @@
+import { Token } from "./token.mjs";
+import { RegistryKey } from "./registry.mjs";
+import { Binding, BindingBuilder, BindingIdentifier, Constructor, ResolveHint, ResolveOptions } from "./binding.mjs";
+import { ContainerGraphJson, ContainerSnapshot, DotGraphOptions } from "./inspector.mjs";
+import { AsyncModule, Module } from "./module.mjs";
+
+//#region src/container.d.ts
+type ModuleLike = Module | AsyncModule;
+/**
+ * Public contract for an IoC container (registry, modules, resolution, lifecycle).
+ * Construct instances with {@link Container.create} or {@link Container.fromModules}.
+ *
+ * Implements {@link AsyncDisposable} so `await using container = Container.create()` runs
+ * {@link Container.dispose} automatically at scope exit (TC39 Explicit Resource Management).
+ */
+interface Container extends AsyncDisposable {
+  /** Starts a fluent binding builder for the given token or constructor. */
+  bind<Value>(token: Token<Value> | Constructor<Value>): BindingBuilder<Value>;
+  /** Removes all existing bindings for the token (with sync deactivation) then starts a fresh builder. */
+  rebind<Value>(token: Token<Value> | Constructor<Value>): BindingBuilder<Value>;
+  /** Removes all bindings for a token or a single binding by its {@link BindingIdentifier}; runs sync deactivation. */
+  unbind(tokenOrId: RegistryKey | BindingIdentifier): void;
+  /** Same as {@link unbind} but awaits async `onDeactivation` handlers before removing. */
+  unbindAsync(tokenOrId: RegistryKey | BindingIdentifier): Promise<void>;
+  /** Returns `true` if at least one binding exists for `token`, optionally filtered by `hint`. */
+  has(token: RegistryKey, hint?: ResolveHint): boolean;
+  /** Resolves the token synchronously. Throws {@link AsyncResolutionError} if any binding in the chain is async. */
+  resolve<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value;
+  /** Resolves the token, awaiting any async factory in the chain. Safe for both sync and async bindings. */
+  resolveAsync<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value>;
+  /** Resolves all bindings registered for the token (multi-binding). Throws {@link AsyncResolutionError} if any is async. */
+  resolveAll<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value[];
+  /** Async variant of {@link resolveAll} — safe when the multi-binding set contains async factories. */
+  resolveAllAsync<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Promise<Value[]>;
+  /** Resolves the token or returns `undefined` if no binding is registered (never throws on missing). */
+  resolveOptional<Value>(token: Token<Value> | Constructor<Value>, hint?: ResolveHint): Value | undefined;
+  /** Registers bindings from one or more synchronous modules. Re-loading a module already present is a no-op. */
+  load(...modules: Module[]): void;
+  /** Registers bindings from sync and/or async modules, awaiting each async setup in sequence. */
+  loadAsync(...modules: ModuleLike[]): Promise<void>;
+  /** Removes all bindings contributed by the given modules; runs sync deactivation on released singletons. */
+  unload(...modules: ModuleLike[]): void;
+  /** Same as {@link unload} but awaits async `onDeactivation` handlers. */
+  unloadAsync(...modules: ModuleLike[]): Promise<void>;
+  /** Eagerly constructs every singleton binding so the first request is never cold. */
+  initializeAsync(): Promise<void>;
+  /** Scans {@link getAutoRegistered} entries and binds each to its declared scope. Returns the count added. */
+  loadAutoRegistered(): number;
+  /** Checks for scope violations (captive dependencies). Throws {@link ScopeViolationError} on the first violation found. */
+  validate(): void;
+  /** Returns a debug snapshot of all registered bindings and their activation state. */
+  inspect(): ContainerSnapshot;
+  /** Renders the dependency graph as a Graphviz DOT string (default) or a typed JSON object. */
+  generateDependencyGraph(options?: DotGraphOptions & {
+    format?: "dot";
+  }): string;
+  generateDependencyGraph(options: DotGraphOptions & {
+    format: "json";
+  }): ContainerGraphJson;
+  /** Creates a child container that inherits bindings from this container without polluting its registry. */
+  createChild(): Container;
+  /** @throws Always — container disposal is async; use `await using` or `await container.dispose()`. */
+  [Symbol.dispose](): never;
+  /** Returns the raw binding list for a token without triggering resolution. `undefined` means no binding. */
+  lookupBindings(token: RegistryKey): readonly Binding<unknown>[] | undefined;
+  /** Runs all `onDeactivation` hooks on active singletons and releases all caches. */
+  dispose(): Promise<void>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/**
+ * Factory functions for {@link Container} instances (interface + namespace merge).
+ */
+declare namespace Container {
+  /** Creates an empty container with no bindings. */
+  function create(): Container;
+  /** Creates a container and immediately loads the given sync modules. */
+  function fromModules(...modules: Module[]): Container;
+  /** Creates a container and awaits loading of sync and/or async modules. */
+  function fromModulesAsync(...modules: (Module | AsyncModule)[]): Promise<Container>;
+}
+//#endregion
+export { type BindingIdentifier, Container, type ContainerGraphJson, type ContainerSnapshot, type ResolveOptions };