alloy-di 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# alloy-di
+
+`alloy-di` is a compile-time dependency injection toolkit for Vite. It scans your TypeScript during build, generates a static container, and ships a tiny runtime so you get dependency injection without reflection overhead.
+
+## Highlights
+
+- **Build-time graph** – services, scopes, and dependencies are resolved while bundling, so runtime work stays minimal.
+- **First-class lazy loading** – use `Lazy()` or provider-based lazy registrations to keep optional features in separate chunks.
+- **Framework agnostic** – works anywhere Vite runs: React, Vue, Svelte, SSR, libraries, and plain TS apps.
+- **Type safe** – generates `serviceIdentifiers` and manifest declarations for precise inference.
+
+## Install
+
+```bash
+pnpm add -D alloy-di
+```
+
+## 30‑second setup
+
+1. **Add the Vite plugin**
+
+   ```ts
+   import { defineConfig } from "vite";
+   import alloy from "alloy-di/vite";
+
+   export default defineConfig({
+     plugins: [alloy()],
+   });
+   ```
+
+2. **Annotate services**
+
+   ```ts
+   import { Injectable, Singleton, deps } from "alloy-di/runtime";
+
+   @Singleton()
+   export class ServiceA {}
+
+   @Injectable(deps(ServiceA))
+   export class AppService {
+     constructor(private readonly serviceA: ServiceA) {}
+   }
+   ```
+
+3. **Resolve from the virtual container**
+
+   ```ts
+   import container, { serviceIdentifiers } from "virtual:alloy-container";
+
+   const app = await container.get(serviceIdentifiers.AppService);
+   ```
+
+Need manifests, providers, or testing utilities? See the docs site for complete guides.
+
+## Documentation
+
+- **Website**: https://alloy-di.dev (generated from `/docs`)
+- **Develop locally**: `pnpm docs:dev`
+- **Build static site**: `pnpm docs:build`
+
+The site covers getting started, plugin options, manifest authoring, lazy loading, testing helpers, and architecture deep dives.
+
+## Examples in this repo
+
+- `packages/examples/app` – React + Vite app consuming decorated services, manifests, and providers.
+- `packages/examples/library-internal` – monorepo library that emits `alloy.manifest.mjs` via the Rolldown plugin.
+- `packages/examples/library-external` – plain classes registered through providers.
+
+Clone the repo, run `pnpm install`, then `pnpm --filter @alloy-di/example-app dev` to explore.

package/dist/lib/container.d.ts

@@ -0,0 +1,117 @@
+import { Constructor, Newable, Token } from "./types.js";
+import { ServiceIdentifier } from "./service-identifiers.js";
+
+//#region src/lib/container.d.ts
+
+/**
+ * Runtime dependency injection container used by generated modules and tests.
+ *
+ * It stores metadata discovered at build time, resolves constructor dependencies,
+ * performs singleton caching, and supports token-based value providers.
+ */
+declare class Container {
+  private singletons;
+  private pendingSingletons;
+  private instanceOverrides;
+  private metadataCache;
+  private valueProviders;
+  private factoryWarningCache;
+  /**
+   * Resolve (and construct) the requested service.
+   *
+   * @param target - Class constructor that was decorated with `@Injectable`/`@Singleton`.
+   * @returns A promise that resolves to the instantiated service.
+   */
+  get<T>(target: Newable<T>): Promise<T>;
+  get<T>(identifier: ServiceIdentifier<T>): Promise<T>;
+  /**
+   * Provide a concrete instance override for a class constructor.
+   * Used by test utilities to inject mocks/stubs without altering global metadata.
+   */
+  overrideInstance<T>(target: Newable<T>, instance: T): void;
+  /**
+   * Retrieve the stable identifier associated with a constructor.
+   * Consumers can cache this and later call {@link getByIdentifier}.
+   */
+  getIdentifier<T>(target: Constructor): ServiceIdentifier<T>;
+  /**
+   * Resolve a service using its stable identifier.
+   * Identifiers remain safe across minification and code splitting.
+   */
+  getByIdentifier<T = unknown>(identifier: ServiceIdentifier<T>): Promise<T>;
+  /**
+   * Register a concrete value for an injection token at runtime.
+   *
+   * @param token - The token created via `createToken`.
+   * @param value - The value that should be injected when the token is requested.
+   */
+  provideValue<T>(token: Token<T>, value: T): void;
+  /**
+   * Retrieve a provided value for a token from this container.
+   * Throws if no provider is registered for the token.
+   */
+  getToken<T>(token: Token<T>): T;
+  private getByConstructor;
+  private maybeWarnFactoryLazyConstructorUsage;
+  /**
+   * Resolve a constructor, managing singleton lifetimes and detecting circular dependencies.
+   * This is the core resolution logic that orchestrates caching, coalescing, and instantiation.
+   *
+   * @param target - Service constructor to resolve
+   * @param resolutionStack - Chain of services currently being resolved (for cycle detection)
+   * @returns Promise resolving to the service instance
+   * @throws Error if a circular dependency is detected
+   */
+  private resolve;
+  /**
+   * Resolve a singleton service with caching and in-flight creation coalescing.
+   */
+  private resolveSingleton;
+  /**
+   * Instantiate a class by resolving and injecting all declared dependencies.
+   * Handles factory-lazy services by importing the real class before instantiation.
+   *
+   * @param target - Service constructor (may be a stub class if factory provided)
+   * @param dependencies - Array of dependency items to resolve and inject
+   * @param resolutionStack - Current resolution chain
+   * @param factory - Optional lazy factory to import the real class
+   * @returns Promise resolving to the instantiated service
+   */
+  private createInstance;
+  /**
+   * Resolve a single dependency entry, handling lazies, tokens, and constructors.
+   * This is called for each parameter in a service's dependency array.
+   *
+   * @param param - Dependency item (can be Lazy, Token, or Constructor)
+   * @param target - Service being constructed (for error messages)
+   * @param resolutionStack - Current resolution chain
+   * @returns Promise resolving to the dependency instance
+   * @throws Error if dependency type is invalid
+   */
+  private resolveParam;
+  /**
+   * Execute a lazy importer with optional retry/backoff semantics.
+   * Implements exponential backoff for transient network failures.
+   *
+   * @param lazyDep - Lazy dependency wrapper with importer function and retry config
+   * @param target - Service being resolved (for error messages)
+   * @param resolutionStack - Current resolution chain (for cycle detection and error context)
+   * @returns The imported class constructor
+   * @throws Error if all retry attempts exhausted or import returns non-constructor
+   */
+  private importWithRetry;
+  /**
+   * Resolve a token dependency via registered value providers.
+   */
+  private resolveTokenLike;
+  /**
+   * Format a readable representation of the resolution stack for error messages.
+   */
+  private formatStackPath;
+  /**
+   * Retrieve (and memoize) the DI metadata for a service from the registry.
+   */
+  private getServiceMetadata;
+}
+//#endregion
+export { Container };

package/dist/lib/container.js

@@ -0,0 +1,266 @@
+import { ServiceScope } from "./scope.js";
+import { isConstructor, isToken } from "./types.js";
+import { isLazy } from "./lazy.js";
+import { dependenciesRegistry } from "./decorators.js";
+import { DependencyResolutionError } from "./dependency-error.js";
+import { getConstructorByIdentifier, getServiceIdentifier } from "./service-identifiers.js";
+import { isDevEnvironment } from "./env-detection.js";
+
+//#region src/lib/container.ts
+function classifyDependency(value) {
+	if (isLazy(value)) return {
+		kind: "lazy",
+		lazy: value
+	};
+	if (isToken(value)) return {
+		kind: "token",
+		token: value
+	};
+	if (isConstructor(value)) return {
+		kind: "constructor",
+		ctor: value
+	};
+	return null;
+}
+function hasFactory(metadata) {
+	return Boolean(metadata?.factory);
+}
+function isProviderPlaceholder(target) {
+	return Boolean(typeof target === "function" && "__alloyLazy" in target && target.__alloyLazy === true);
+}
+function formatFactoryLazyWarning(target) {
+	return `[alloy] container.get(${target.name || "<anonymous>"}) resolved a factory-lazy service via constructor. Use container.get(${target.name ? `serviceIdentifiers.${target.name}` : "serviceIdentifiers.<Service>"}) or cache const id = ${target.name ? `container.getIdentifier(${target.name})` : `container.getIdentifier(<Service>)`}; container.get(id) to preserve lazy loading.`;
+}
+/**
+* Runtime dependency injection container used by generated modules and tests.
+*
+* It stores metadata discovered at build time, resolves constructor dependencies,
+* performs singleton caching, and supports token-based value providers.
+*/
+var Container = class {
+	singletons = /* @__PURE__ */ new Map();
+	pendingSingletons = /* @__PURE__ */ new Map();
+	instanceOverrides = /* @__PURE__ */ new Map();
+	metadataCache = /* @__PURE__ */ new Map();
+	valueProviders = /* @__PURE__ */ new Map();
+	factoryWarningCache = /* @__PURE__ */ new WeakSet();
+	async get(targetOrIdentifier) {
+		if (typeof targetOrIdentifier === "symbol") return this.getByIdentifier(targetOrIdentifier);
+		return this.getByConstructor(targetOrIdentifier);
+	}
+	/**
+	* Provide a concrete instance override for a class constructor.
+	* Used by test utilities to inject mocks/stubs without altering global metadata.
+	*/
+	overrideInstance(target, instance) {
+		this.instanceOverrides.set(target, instance);
+		this.singletons.set(target, instance);
+	}
+	/**
+	* Retrieve the stable identifier associated with a constructor.
+	* Consumers can cache this and later call {@link getByIdentifier}.
+	*/
+	getIdentifier(target) {
+		return getServiceIdentifier(target);
+	}
+	/**
+	* Resolve a service using its stable identifier.
+	* Identifiers remain safe across minification and code splitting.
+	*/
+	async getByIdentifier(identifier) {
+		const ctor = getConstructorByIdentifier(identifier);
+		if (!ctor) throw new Error(`No service registered for identifier ${identifier.description ?? identifier.toString()}`);
+		return this.getByConstructor(ctor, { skipFactoryWarning: true });
+	}
+	/**
+	* Register a concrete value for an injection token at runtime.
+	*
+	* @param token - The token created via `createToken`.
+	* @param value - The value that should be injected when the token is requested.
+	*/
+	provideValue(token, value) {
+		this.valueProviders.set(token.id, value);
+	}
+	/**
+	* Retrieve a provided value for a token from this container.
+	* Throws if no provider is registered for the token.
+	*/
+	getToken(token) {
+		if (!this.valueProviders.has(token.id)) throw new Error(`No provider registered for token ${token.description ?? String(token.id)}`);
+		return this.valueProviders.get(token.id);
+	}
+	async getByConstructor(target, options) {
+		if (!options?.skipFactoryWarning) this.maybeWarnFactoryLazyConstructorUsage(target);
+		return this.resolve(target, []);
+	}
+	maybeWarnFactoryLazyConstructorUsage(target) {
+		if (!isDevEnvironment()) return;
+		if (!hasFactory(this.metadataCache.get(target) ?? this.getServiceMetadata(target)) || this.factoryWarningCache.has(target) || isProviderPlaceholder(target)) return;
+		this.factoryWarningCache.add(target);
+		if (typeof console !== "undefined" && typeof console.warn === "function") console.warn(formatFactoryLazyWarning(target));
+	}
+	/**
+	* Resolve a constructor, managing singleton lifetimes and detecting circular dependencies.
+	* This is the core resolution logic that orchestrates caching, coalescing, and instantiation.
+	*
+	* @param target - Service constructor to resolve
+	* @param resolutionStack - Chain of services currently being resolved (for cycle detection)
+	* @returns Promise resolving to the service instance
+	* @throws Error if a circular dependency is detected
+	*/
+	async resolve(target, resolutionStack) {
+		const overridden = this.instanceOverrides.get(target);
+		if (overridden) return overridden;
+		if (resolutionStack.includes(target)) throw new DependencyResolutionError(`Circular dependency detected: ${[...resolutionStack.map((t) => t.name), target.name].join(" -> ")}`, {
+			target,
+			resolutionStack,
+			failedDependency: target
+		});
+		const metadata = this.getServiceMetadata(target);
+		const nextStack = [...resolutionStack, target];
+		if (metadata.scope === ServiceScope.SINGLETON) return this.resolveSingleton(target, metadata, nextStack);
+		return this.createInstance(target, metadata.dependencies, nextStack, metadata.factory);
+	}
+	/**
+	* Resolve a singleton service with caching and in-flight creation coalescing.
+	*/
+	async resolveSingleton(target, metadata, resolutionStack) {
+		const cached = this.singletons.get(target);
+		if (cached) return cached;
+		const pending = this.pendingSingletons.get(target);
+		if (pending) return await pending;
+		const creation = this.createInstance(target, metadata.dependencies, resolutionStack, metadata.factory).then((instance) => {
+			this.singletons.set(target, instance);
+			return instance;
+		});
+		this.pendingSingletons.set(target, creation);
+		try {
+			return await creation;
+		} finally {
+			this.pendingSingletons.delete(target);
+		}
+	}
+	/**
+	* Instantiate a class by resolving and injecting all declared dependencies.
+	* Handles factory-lazy services by importing the real class before instantiation.
+	*
+	* @param target - Service constructor (may be a stub class if factory provided)
+	* @param dependencies - Array of dependency items to resolve and inject
+	* @param resolutionStack - Current resolution chain
+	* @param factory - Optional lazy factory to import the real class
+	* @returns Promise resolving to the instantiated service
+	*/
+	async createInstance(target, dependencies, resolutionStack, factory) {
+		const ctor = factory ? await this.importWithRetry(factory, target, resolutionStack) : target;
+		return new ctor(...await Promise.all(dependencies.map((param) => this.resolveParam(param, ctor, resolutionStack))));
+	}
+	/**
+	* Resolve a single dependency entry, handling lazies, tokens, and constructors.
+	* This is called for each parameter in a service's dependency array.
+	*
+	* @param param - Dependency item (can be Lazy, Token, or Constructor)
+	* @param target - Service being constructed (for error messages)
+	* @param resolutionStack - Current resolution chain
+	* @returns Promise resolving to the dependency instance
+	* @throws Error if dependency type is invalid
+	*/
+	async resolveParam(param, target, resolutionStack) {
+		const classification = classifyDependency(param);
+		if (!classification) {
+			const stackPath = this.formatStackPath(target, resolutionStack);
+			throw new DependencyResolutionError(`Invalid dependency type while resolving ${target.name}. Resolution stack: ${stackPath}. Received type: ${typeof param}`, {
+				target,
+				resolutionStack,
+				failedDependency: param
+			});
+		}
+		switch (classification.kind) {
+			case "lazy": {
+				const depClass = await this.importWithRetry(classification.lazy, target, resolutionStack);
+				return this.resolve(depClass, resolutionStack);
+			}
+			case "token": return this.resolveTokenLike(classification.token, target, resolutionStack);
+			case "constructor": return this.resolve(classification.ctor, resolutionStack);
+		}
+		return classification;
+	}
+	/**
+	* Execute a lazy importer with optional retry/backoff semantics.
+	* Implements exponential backoff for transient network failures.
+	*
+	* @param lazyDep - Lazy dependency wrapper with importer function and retry config
+	* @param target - Service being resolved (for error messages)
+	* @param resolutionStack - Current resolution chain (for cycle detection and error context)
+	* @returns The imported class constructor
+	* @throws Error if all retry attempts exhausted or import returns non-constructor
+	*/
+	async importWithRetry(lazyDep, target, resolutionStack) {
+		const runImport = async () => await lazyDep.importer();
+		const retries = lazyDep.retry?.retries ?? 0;
+		const baseDelay = lazyDep.retry?.backoffMs ?? 0;
+		const factor = lazyDep.retry?.factor ?? 2;
+		let attempt = 0;
+		while (true) try {
+			const module = await runImport();
+			const depClass = typeof module === "object" && module !== null && "default" in module ? module.default : module;
+			if (!isConstructor(depClass)) {
+				const stackPath = this.formatStackPath(target, resolutionStack);
+				throw new DependencyResolutionError(`Lazy importer did not return a class for dependency while resolving ${target.name}. Resolution stack: ${stackPath}. Received type: ${typeof depClass}`, {
+					target,
+					resolutionStack,
+					failedDependency: depClass
+				});
+			}
+			return depClass;
+		} catch (err) {
+			if (attempt >= retries) {
+				const stackPath = this.formatStackPath(target, resolutionStack);
+				throw new DependencyResolutionError(`Failed to import lazy dependency while resolving ${target.name}. Resolution stack: ${stackPath}. Original error: ${err instanceof Error ? err.message : String(err)}`, {
+					target,
+					resolutionStack,
+					failedDependency: lazyDep,
+					cause: err
+				});
+			}
+			const delay = baseDelay * Math.pow(factor, attempt);
+			if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+			attempt++;
+		}
+	}
+	/**
+	* Resolve a token dependency via registered value providers.
+	*/
+	resolveTokenLike(tok, target, resolutionStack) {
+		if (this.valueProviders.has(tok.id)) return this.valueProviders.get(tok.id);
+		const stackPath = this.formatStackPath(target, resolutionStack);
+		throw new DependencyResolutionError(`No provider registered for token ${tok.description ?? String(tok.id)} while resolving ${target.name}. Resolution stack: ${stackPath}`, {
+			target,
+			resolutionStack,
+			failedDependency: tok
+		});
+	}
+	/**
+	* Format a readable representation of the resolution stack for error messages.
+	*/
+	formatStackPath(target, resolutionStack) {
+		return [...resolutionStack.map((t) => t.name), target.name].join(" -> ");
+	}
+	/**
+	* Retrieve (and memoize) the DI metadata for a service from the registry.
+	*/
+	getServiceMetadata(target) {
+		const cached = this.metadataCache.get(target);
+		if (cached) return cached;
+		const registryEntry = dependenciesRegistry.get(target);
+		const metadata = {
+			scope: registryEntry?.scope ?? ServiceScope.TRANSIENT,
+			dependencies: (registryEntry?.dependencies ?? (() => []))(),
+			factory: registryEntry?.factory
+		};
+		this.metadataCache.set(target, metadata);
+		return metadata;
+	}
+};
+
+//#endregion
+export { Container };

package/dist/lib/decorators.d.ts

@@ -0,0 +1,177 @@
+import { Newable, Token } from "./types.js";
+import { Lazy } from "./lazy.js";
+import { ServiceScope } from "./scope.js";
+
+//#region src/lib/decorators.d.ts
+
+/**
+ * Resolve a declared dependency to the constructor parameter type expected by the service.
+ *
+ * - If the dependency is a `Lazy<T>`, this resolves to `T` (the eagerly-constructed type).
+ * - If the dependency is a `Newable<T>` (a class constructor), this resolves to `T`.
+ * - If the dependency is a `Token<T>`, this resolves to the provided value type `T`.
+ * - Otherwise, resolves to `never`.
+ *
+ * This is used to map the `dependencies` tuple into the service constructor parameter list.
+ *
+ * @typeParam D - A single declared dependency item.
+ */
+type ResolveDep<D> = D extends Lazy<infer L> ? L : D extends Newable<infer I> ? I : D extends Token<infer V> ? V : never;
+/**
+ * Tuple-map a declared dependencies list to the constructor parameter types.
+ *
+ * Given a tuple of constructors and/or `Lazy<...>` wrappers, produces a tuple of the
+ * instance types the class constructor should accept.
+ *
+ * Example:
+ * - `[Logger, Metrics]`        -> `[Logger, Metrics]` (instances)
+ * - `[Lazy(() => Logger)]`     -> `[Logger]`
+ *
+ * @typeParam TDeps - A readonly tuple of declared dependencies.
+ */
+type DepInstances<TDeps extends readonly unknown[]> = { [K in keyof TDeps]: ResolveDep<TDeps[K]> };
+/**
+ * Allowed shapes for the `dependencies` option.
+ *
+ * - A readonly tuple/array of constructors and/or `Lazy<...>` wrappers.
+ * - Or a function returning such a tuple (recommended to break circular refs in the same file).
+ */
+type DependencyItem = Newable<unknown> | Lazy<unknown> | Token<unknown>;
+/**
+ * Strongly-typed decorator function signature used by overloads when dependencies are known.
+ *
+ * @typeParam TDeps - A readonly tuple of declared dependencies.
+ * @internal
+ */
+type TypedClassDecorator<TDeps extends readonly DependencyItem[]> = (target: new (...args: DepInstances<TDeps>) => unknown) => void;
+/**
+ * Global registry for service metadata used by the runtime container.
+ *
+ * Keys are service constructors; values include the configured scope and a
+ * normalized dependency function that returns the declared dependencies as a readonly tuple.
+ *
+ * The Vite plugin populates this from source decorators at build time, but you can also
+ * register programmatically via the decorators in tests or non-plugin setups.
+ *
+ * @internal
+ */
+declare const dependenciesRegistry: Map<Newable<unknown>, {
+  dependencies?: () => readonly (Newable<unknown> | Lazy<unknown> | Token<unknown>)[];
+  scope?: ServiceScope;
+  factory?: Lazy<Newable<unknown>>;
+}>;
+/**
+ * Class decorator for declaring a DI-managed service and its dependencies.
+ *
+ * Overloads preserve tuple inference for both array and function dependency forms, enabling
+ * strict alignment between the declared dependencies and the class constructor parameter list.
+ *
+ * Notes:
+ * - Order matters: dependencies map positionally to constructor parameters.
+ * - For circular dependencies in the same file, use the function form: `@Injectable(() => [B])`.
+ * - When using `Lazy(...)`, the constructor expects the resolved type, not `Lazy<T>`.
+ * - Due to TypeScript limitations, decorator position may not always surface target mismatches;
+ *   use {@link assertDeps} for zero-cost compile-time assertions when needed.
+ *
+ * @typeParam TDeps - A readonly tuple of declared dependencies.
+ * @param depsOrScope - Optional dependency declaration followed by an optional scope string.
+ *
+ * @example Transient with a direct dependency
+ * ```ts
+ * @Injectable(deps(Logger))
+ * class AppService {
+ *   constructor(private logger: Logger) {}
+ * }
+ * ```
+ *
+ * @example Singleton shorthand via scope
+ * ```ts
+ * @Injectable('singleton')
+ * class AppState {}
+ * ```
+ *
+ * @example Circular dependency in the same file
+ * ```ts
+ * @Injectable(() => [CircularB])
+ * class CircularA { constructor(private b: CircularB) {} }
+ * ```
+ *
+ * @example Lazy dependency resolves to the underlying type
+ * ```ts
+ * @Injectable([Lazy(() => Promise.resolve(Logger))])
+ * class NeedsLogger { constructor(private logger: Logger) {} }
+ * ```
+ */
+declare function Injectable(): ClassDecorator;
+declare function Injectable(scope: ServiceScope): ClassDecorator;
+declare function Injectable<const TDeps extends readonly DependencyItem[]>(dependencies: () => TDeps, scope?: ServiceScope): TypedClassDecorator<TDeps>;
+declare function Injectable<const TDeps extends readonly DependencyItem[]>(dependencies: TDeps, scope?: ServiceScope): TypedClassDecorator<TDeps>;
+/**
+ * Shorthand decorator for singleton services.
+ *
+ * Equivalent to `@Injectable(dependencies?, 'singleton')` with the same strict typing
+ * and overload behaviors as {@link Injectable}.
+ *
+ * @typeParam TDeps - A readonly tuple of declared dependencies.
+ * @param options - Singleton configuration and dependencies (array or function form).
+ *
+ * @example No dependencies
+ * ```ts
+ * @Singleton()
+ * class GlobalLogger {}
+ * ```
+ *
+ * @example With dependencies (array form)
+ * ```ts
+ * @Singleton(deps(Config))
+ * class Metrics { constructor(private cfg: Config) {} }
+ * ```
+ */
+declare function Singleton(): ClassDecorator;
+declare function Singleton<const TDeps extends readonly DependencyItem[]>(dependencies: () => TDeps): TypedClassDecorator<TDeps>;
+declare function Singleton<const TDeps extends readonly DependencyItem[]>(dependencies: TDeps): TypedClassDecorator<TDeps>;
+/**
+ * Declare dependencies as a strongly-typed readonly tuple without `as const`.
+ *
+ * This helper preserves tuple inference for strict constructor checking while keeping callsites
+ * concise. It returns a function so it can be used directly as `dependencies` in the decorator.
+ *
+ * @typeParam T - A readonly tuple of constructors and/or `Lazy<...>` wrappers.
+ * @param items - Variadic dependency list.
+ * @returns A function returning the same tuple (suitable for `dependencies`).
+ *
+ * @example
+ * ```ts
+ * @Injectable(deps(Logger, Metrics))
+ * class AppService { constructor(l: Logger, m: Metrics) {} }
+ * ```
+ */
+declare function deps<T extends readonly (Newable<unknown> | Lazy<unknown> | Token<unknown>)[]>(...items: T): () => T;
+/**
+ * Compile-time assertion: ensure constructor parameters match the resolved dependency tuple.
+ *
+ * This function has zero runtime cost and simply returns the class unchanged. It exists solely
+ * to force a TypeScript evaluation that surfaces mismatches (number, order, or type), including
+ * cases where decorator position alone may not report errors due to compiler limitations.
+ *
+ * @typeParam TDeps - Declared dependency tuple.
+ * @typeParam TClass - Class type with a constructor that must accept `DepInstances<TDeps>`.
+ * @param depsFn - A function returning the declared dependency tuple (e.g., from {@link deps}).
+ * @param klass - The class constructor to validate.
+ * @returns The same class constructor, unchanged.
+ *
+ * @example Negative test in code
+ * ```ts
+ * class Dep {}
+ * class Wrong {}
+ *
+ * @Injectable(deps(Dep))
+ * class UsesWrong { constructor(_: Wrong) {} }
+ *
+ * // @ts-expect-error mismatch detected at compile time
+ * assertDeps(deps(Dep), UsesWrong);
+ * ```
+ */
+declare function assertDeps<TDeps extends readonly (Newable<unknown> | Lazy<unknown> | Token<unknown>)[], TClass extends new (...args: DepInstances<TDeps>) => unknown>(depsFn: () => TDeps, klass: TClass): TClass;
+//#endregion
+export { Injectable, Singleton, assertDeps, dependenciesRegistry, deps };