alloy-di 0.1.0

package/dist/lib/decorators.js

@@ -0,0 +1,126 @@
+import { ServiceScope } from "./scope.js";
+
+//#region src/lib/decorators.ts
+/**
+* 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
+*/
+const dependenciesRegistry = /* @__PURE__ */ new Map();
+/**
+* Create the underlying decorator implementation for both `@Injectable` and `@Singleton`.
+*
+* - Normalizes `dependencies` to a function so the container can evaluate lazily/memoize.
+* - Registers the class metadata in {@link dependenciesRegistry}.
+* - Preserves strict tuple inference through the call-site overloads of the public decorators.
+*
+* @param scope - The requested lifetime: `singleton` or `transient`.
+* @param dependencies - Optional dependency list (array or factory returning an array).
+* @returns A class decorator that records the metadata into the registry.
+* @internal
+*/
+function createDecoratorWithDeps(scope, depsOpt) {
+	if (typeof depsOpt === "function") {
+		const depsFn$1 = depsOpt;
+		return (target) => {
+			dependenciesRegistry.set(target, {
+				scope,
+				dependencies: depsFn$1
+			});
+		};
+	}
+	const deps$1 = depsOpt;
+	const depsFn = () => deps$1;
+	return (target) => {
+		dependenciesRegistry.set(target, {
+			scope,
+			dependencies: depsFn
+		});
+	};
+}
+/**
+* Register scope metadata for services that declare no dependencies.
+*
+* @param scope - Lifetime associated with the decorated service.
+* @returns A class decorator that records only the scope in {@link dependenciesRegistry}.
+* @internal
+*/
+function createDecoratorWithoutDeps(scope) {
+	return (target) => {
+		dependenciesRegistry.set(target, { scope });
+	};
+}
+/**
+* Determine whether a decorator argument represents dependency metadata.
+*
+* @param value - The argument supplied to `@Injectable`/`@Singleton`.
+* @returns True if the argument is an array or factory of dependencies.
+* @internal
+*/
+function isDependenciesArg(value) {
+	return typeof value === "function" || Array.isArray(value);
+}
+function Injectable(depsOrScope, scopeOverride) {
+	if (isDependenciesArg(depsOrScope)) return createDecoratorWithDeps(scopeOverride ?? ServiceScope.TRANSIENT, depsOrScope);
+	return createDecoratorWithoutDeps((typeof depsOrScope === "string" ? depsOrScope : void 0) ?? scopeOverride ?? ServiceScope.TRANSIENT);
+}
+function Singleton(dependencies) {
+	if (isDependenciesArg(dependencies)) return createDecoratorWithDeps(ServiceScope.SINGLETON, dependencies);
+	return createDecoratorWithoutDeps(ServiceScope.SINGLETON);
+}
+/**
+* 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) {} }
+* ```
+*/
+function deps(...items) {
+	return () => items;
+}
+/**
+* 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);
+* ```
+*/
+function assertDeps(depsFn, klass) {
+	return klass;
+}
+
+//#endregion
+export { Injectable, Singleton, assertDeps, dependenciesRegistry, deps };

package/dist/lib/dependency-error.js

@@ -0,0 +1,31 @@
+import { isConstructor, isToken } from "./types.js";
+import { isLazy } from "./lazy.js";
+
+//#region src/lib/dependency-error.ts
+function describeDependency(value) {
+	if (isConstructor(value)) return `constructor ${value.name || "<anonymous>"}`;
+	if (isToken(value)) return `token(${value.description ?? value.id.toString()})`;
+	if (isLazy(value)) return "Lazy(import)";
+	if (typeof value === "function") return value.name || "<anonymous function>";
+	return String(value);
+}
+var DependencyResolutionError = class extends Error {
+	target;
+	resolutionStack;
+	failedDependency;
+	constructor(message, params) {
+		super(message, params.cause ? { cause: params.cause } : void 0);
+		this.name = "DependencyResolutionError";
+		this.target = params.target;
+		this.resolutionStack = params.resolutionStack;
+		this.failedDependency = params.failedDependency;
+	}
+	toDetailedString() {
+		const stackPath = [...this.resolutionStack.map((c) => c.name), this.target.name].filter(Boolean).join(" -> ");
+		const dependencyInfo = this.failedDependency ? `\nFailed dependency: ${describeDependency(this.failedDependency)}` : "";
+		return `${this.message}\nResolution path: ${stackPath}${dependencyInfo}`;
+	}
+};
+
+//#endregion
+export { DependencyResolutionError };

package/dist/lib/env-detection.js

@@ -0,0 +1,44 @@
+//#region src/lib/env-detection.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function readImportMetaEnvFromRuntime() {
+	if (typeof import.meta === "undefined") return;
+	const candidate = import.meta;
+	if (!isRecord(candidate) || !("env" in candidate)) return;
+	const envValue = candidate.env;
+	if (!isRecord(envValue)) return;
+	const env = {};
+	if (typeof envValue.MODE === "string") env.MODE = envValue.MODE;
+	if (typeof envValue.PROD === "boolean") env.PROD = envValue.PROD;
+	if (typeof envValue.NODE_ENV === "string") env.NODE_ENV = envValue.NODE_ENV;
+	return env;
+}
+function readProcessNodeEnv() {
+	if (typeof process === "undefined") return;
+	const nodeEnv = "development";
+	return typeof nodeEnv === "string" ? nodeEnv : void 0;
+}
+function getImportMetaEnv(overrides) {
+	if (overrides?.importMetaEnv === null) return;
+	if (overrides?.importMetaEnv) return overrides.importMetaEnv;
+	return readImportMetaEnvFromRuntime();
+}
+function getNodeEnv(overrides) {
+	if (typeof overrides?.nodeEnv === "string") return overrides.nodeEnv;
+	if (overrides?.nodeEnv === null) return;
+	return readProcessNodeEnv();
+}
+function isDevEnvironment(overrides) {
+	if (typeof overrides?.isDev === "boolean") return overrides.isDev;
+	const nodeEnv = getNodeEnv(overrides);
+	if (typeof nodeEnv === "string") return nodeEnv !== "production";
+	const importMetaEnv = getImportMetaEnv(overrides);
+	if (typeof importMetaEnv?.PROD === "boolean") return !importMetaEnv.PROD;
+	if (typeof importMetaEnv?.MODE === "string") return importMetaEnv.MODE !== "production";
+	if (typeof importMetaEnv?.NODE_ENV === "string") return importMetaEnv.NODE_ENV !== "production";
+	return true;
+}
+
+//#endregion
+export { isDevEnvironment };

package/dist/lib/lazy.d.ts

@@ -0,0 +1,39 @@
+import { Newable } from "./types.js";
+
+//#region src/lib/lazy.d.ts
+declare const LAZY_IDENTIFIER: unique symbol;
+type Importer<T> = () => Promise<{
+  default: Newable<T>;
+} | Newable<T>>;
+interface Lazy<T> {
+  [LAZY_IDENTIFIER]: true;
+  importer: Importer<T>;
+  retry?: {
+    retries: number;
+    backoffMs?: number;
+    factor?: number;
+  };
+}
+/**
+ * Helper type to extract the instance type from a Newable constructor.
+ */
+type ExtractInstanceType<T> = T extends Newable<infer I> ? I : never;
+/**
+ * Infers the type T from an Importer function's return type.
+ * Handles both default exports and named exports.
+ */
+type InferLazyType<F> = F extends (() => Promise<infer R>) ? R extends {
+  default: infer D;
+} ? ExtractInstanceType<D> : ExtractInstanceType<R> : never;
+/**
+ * Wraps a dynamic import of a service to mark it for lazy loading.
+ * When called without a type parameter, the type is automatically inferred.
+ * When called with a type parameter, that type is used explicitly.
+ * @param importer A function that returns a dynamic import, e.g., `() => import('./my.service').then(m => m.MyService)`
+ */
+declare function Lazy<F extends () => Promise<Newable<any> | {
+  default: Newable<any>;
+}>>(importer: F, retry?: Lazy<any>["retry"]): Lazy<InferLazyType<F>>;
+declare function Lazy<T>(importer: Importer<T>, retry?: Lazy<T>["retry"]): Lazy<T>;
+//#endregion
+export { LAZY_IDENTIFIER, Lazy };

package/dist/lib/lazy.js

@@ -0,0 +1,18 @@
+//#region src/lib/lazy.ts
+const LAZY_IDENTIFIER = Symbol("lazy");
+/**
+* Narrow an unknown value to a `Lazy` wrapper based on the hidden identifier symbol.
+*/
+function isLazy(value) {
+	return typeof value === "object" && value !== null && LAZY_IDENTIFIER in value;
+}
+function Lazy(importer, retry) {
+	return {
+		[LAZY_IDENTIFIER]: true,
+		importer,
+		retry
+	};
+}
+
+//#endregion
+export { LAZY_IDENTIFIER, Lazy, isLazy };

package/dist/lib/providers.d.ts

@@ -0,0 +1,112 @@
+import { Newable, Token } from "./types.js";
+import { Container } from "./container.js";
+import { Lazy } from "./lazy.js";
+import { ServiceScope } from "./scope.js";
+
+//#region src/lib/providers.d.ts
+
+/**
+ * Explicit lifecycle choices for providers. Mirrors decorator scopes but externalized.
+ */
+type ProviderLifecycle = ServiceScope;
+/**
+ * A single dependency item can be:
+ * - A constructor (class) registered or discoverable by the container.
+ * - A Lazy<T> wrapper for deferred resolution of another service.
+ * - A Token<T> representing a value provider.
+ */
+type DependencyItem = Newable<unknown> | Lazy<unknown> | Token<unknown>;
+/** Readonly list of dependency items describing a constructor's injection points. */
+type DependencyList = readonly DependencyItem[];
+/**
+ * Dependencies can be provided directly or via a thunk to support ordering / circular cases.
+ */
+type DependenciesOption = DependencyList | (() => DependencyList);
+/**
+ * Hidden symbol used to attach lazy provider metadata to its placeholder constructor.
+ */
+declare const LAZY_PROVIDER_DESCRIPTOR: unique symbol;
+/**
+ * Placeholder constructor type for a lazily imported class.
+ * It masquerades as `Newable<T>` for dependency declaration and typing, while hosting
+ * a private descriptor used during provider application.
+ */
+type LazyPlaceholder<T = unknown> = Newable<T> & {
+  [LAZY_PROVIDER_DESCRIPTOR]: LazyServiceProviderDescriptor<T>;
+};
+/** Descriptor for a token-value binding. */
+interface ValueProviderDescriptor<T = unknown> {
+  kind: "value";
+  token: Token<T>;
+  value: T;
+}
+/** Descriptor for a concrete class provider with lifecycle and optional dependencies. */
+interface ServiceProviderDescriptor<T extends Newable<unknown> = Newable<unknown>> {
+  kind: "service";
+  useClass: T;
+  lifecycle: ProviderLifecycle;
+  deps?: DependenciesOption;
+}
+/**
+ * Internal descriptor capturing lazy service metadata.
+ * Not exposed directly to consumers; attached via symbol on the placeholder.
+ */
+interface LazyServiceProviderDescriptor<T = unknown> {
+  placeholder: LazyPlaceholder<T>;
+  factory: Lazy<Newable<T>>;
+  lifecycle: ProviderLifecycle;
+  deps?: DependenciesOption;
+}
+/** Aggregate provider definitions for batch application. */
+interface ProviderDefinitions {
+  values?: ValueProviderDescriptor[];
+  services?: ServiceProviderDescriptor[];
+  lazyServices?: LazyPlaceholder[];
+}
+/**
+ * Identity helper for provider definition blocks.
+ * Enables better type inference in user code without changing runtime behavior.
+ */
+declare function defineProviders(defs: ProviderDefinitions): ProviderDefinitions;
+/** Create a value provider for a given token. */
+declare function asValue<T>(token: Token<T>, value: T): ValueProviderDescriptor<T>;
+/**
+ * Create a class (service) provider with explicit lifecycle and optional dependencies.
+ */
+declare function asClass<T extends Newable<unknown>>(useClass: T, options: {
+  lifecycle: ProviderLifecycle;
+  deps?: DependenciesOption;
+}): ServiceProviderDescriptor<T>;
+/**
+ * Convenience lifecycle helpers for fluent provider creation.
+ */
+declare const lifecycle: {
+  readonly singleton: () => ProviderLifecycle;
+  readonly transient: () => ProviderLifecycle;
+};
+/**
+ * Define a lazily imported class provider.
+ *
+ * Creates a placeholder constructor that stands in for the eventual imported class.
+ * Dependencies can be declared immediately against this placeholder. When the container
+ * resolves the service, it will invoke the attached lazy factory to perform the dynamic import.
+ *
+ * @param importer Dynamic import function returning the service constructor.
+ * @param options.lifecycle Lifecycle scope (singleton or transient).
+ * @param options.deps Optional dependencies (array or thunk) for the service.
+ * @param options.label Optional display name overriding the placeholder's constructor name.
+ */
+declare function asLazyClass<T, const TDeps extends DependenciesOption>(importer: () => Promise<Newable<T>>, options: {
+  lifecycle: ProviderLifecycle;
+  deps?: TDeps;
+  label?: string;
+}): LazyPlaceholder<T>;
+/**
+ * Apply one or more provider definition blocks to a container.
+ *
+ * For each service / lazy service, a registration entry is written into `dependenciesRegistry`.
+ * Value providers are passed directly to the container for immediate binding.
+ */
+declare function applyProviders(container: Container, definitions: ProviderDefinitions | ProviderDefinitions[]): void;
+//#endregion
+export { ProviderDefinitions, applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle };

package/dist/lib/providers.js

@@ -0,0 +1,166 @@
+import { ServiceScope } from "./scope.js";
+import { isConstructor } from "./types.js";
+import { Lazy } from "./lazy.js";
+import { dependenciesRegistry } from "./decorators.js";
+
+//#region src/lib/providers.ts
+/**
+* Hidden symbol used to attach lazy provider metadata to its placeholder constructor.
+*/
+const LAZY_PROVIDER_DESCRIPTOR = Symbol("alloy.lazy-provider-descriptor");
+/**
+* Identity helper for provider definition blocks.
+* Enables better type inference in user code without changing runtime behavior.
+*/
+function defineProviders(defs) {
+	return defs;
+}
+/** Create a value provider for a given token. */
+function asValue(token, value) {
+	return {
+		kind: "value",
+		token,
+		value
+	};
+}
+/**
+* Create a class (service) provider with explicit lifecycle and optional dependencies.
+*/
+function asClass(useClass, options) {
+	return {
+		kind: "service",
+		useClass,
+		lifecycle: options.lifecycle,
+		deps: options.deps
+	};
+}
+/**
+* Convenience lifecycle helpers for fluent provider creation.
+*/
+const lifecycle = {
+	singleton() {
+		return ServiceScope.SINGLETON;
+	},
+	transient() {
+		return ServiceScope.TRANSIENT;
+	}
+};
+/**
+* Define a lazily imported class provider.
+*
+* Creates a placeholder constructor that stands in for the eventual imported class.
+* Dependencies can be declared immediately against this placeholder. When the container
+* resolves the service, it will invoke the attached lazy factory to perform the dynamic import.
+*
+* @param importer Dynamic import function returning the service constructor.
+* @param options.lifecycle Lifecycle scope (singleton or transient).
+* @param options.deps Optional dependencies (array or thunk) for the service.
+* @param options.label Optional display name overriding the placeholder's constructor name.
+*/
+function asLazyClass(importer, options) {
+	class AlloyLazyProvider {
+		static __alloyLazy = true;
+		constructor() {
+			throw new Error("Lazy provider placeholders cannot be instantiated directly. Use container.get instead.");
+		}
+	}
+	const placeholder = AlloyLazyProvider;
+	if (options.label) Object.defineProperty(placeholder, "name", { value: options.label });
+	const factory = Lazy(async () => {
+		return await importer();
+	});
+	Object.defineProperty(placeholder, LAZY_PROVIDER_DESCRIPTOR, { value: {
+		placeholder,
+		factory,
+		lifecycle: options.lifecycle,
+		deps: options.deps
+	} });
+	return placeholder;
+}
+/**
+* Normalizes dependencies option into a consistent thunk form.
+*/
+function normalizeDependencies(option) {
+	if (!option) return () => [];
+	if (typeof option === "function") return option;
+	return () => option;
+}
+function detectProviderCycles(entries) {
+	if (entries.length === 0) return;
+	const providerMap = /* @__PURE__ */ new Map();
+	for (const entry of entries) providerMap.set(entry.ctor, entry.deps);
+	if (providerMap.size <= 1) return;
+	const adjacency = /* @__PURE__ */ new Map();
+	for (const [ctor, depsOption] of providerMap.entries()) {
+		if (typeof depsOption === "function") {
+			adjacency.set(ctor, []);
+			continue;
+		}
+		const deps = depsOption ?? [];
+		const neighbors = [];
+		for (const dep of deps) if (isConstructor(dep) && providerMap.has(dep)) neighbors.push(dep);
+		adjacency.set(ctor, neighbors);
+	}
+	const visiting = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const path = [];
+	const dfs = (node) => {
+		if (visiting.has(node)) {
+			const cycleStart = path.indexOf(node);
+			const cyclePath = [...path.slice(cycleStart), node].map((ctor) => ctor.name || "<anonymous>").join(" -> ");
+			throw new Error(`[alloy] Circular provider dependency detected: ${cyclePath}`);
+		}
+		if (visited.has(node)) return;
+		visiting.add(node);
+		path.push(node);
+		for (const dep of adjacency.get(node) ?? []) dfs(dep);
+		path.pop();
+		visiting.delete(node);
+		visited.add(node);
+	};
+	for (const node of providerMap.keys()) dfs(node);
+}
+/**
+* Apply one or more provider definition blocks to a container.
+*
+* For each service / lazy service, a registration entry is written into `dependenciesRegistry`.
+* Value providers are passed directly to the container for immediate binding.
+*/
+function applyProviders(container, definitions) {
+	const list = Array.isArray(definitions) ? definitions : [definitions];
+	const planEntries = [];
+	for (const definition of list) {
+		for (const service of definition.services ?? []) planEntries.push({
+			ctor: service.useClass,
+			deps: service.deps
+		});
+		for (const placeholder of definition.lazyServices ?? []) {
+			const descriptor = placeholder[LAZY_PROVIDER_DESCRIPTOR];
+			if (!descriptor) continue;
+			planEntries.push({
+				ctor: descriptor.placeholder,
+				deps: descriptor.deps
+			});
+		}
+	}
+	detectProviderCycles(planEntries);
+	for (const definition of list) {
+		for (const valueProvider of definition.values ?? []) container.provideValue(valueProvider.token, valueProvider.value);
+		const registerService = (ctor, lifecycle$1, deps, factory) => {
+			dependenciesRegistry.set(ctor, {
+				scope: lifecycle$1,
+				dependencies: normalizeDependencies(deps),
+				factory
+			});
+		};
+		for (const service of definition.services ?? []) registerService(service.useClass, service.lifecycle, service.deps);
+		for (const placeholder of definition.lazyServices ?? []) {
+			const descriptor = placeholder[LAZY_PROVIDER_DESCRIPTOR];
+			if (!descriptor) continue;
+			registerService(descriptor.placeholder, descriptor.lifecycle, descriptor.deps, descriptor.factory);
+		}
+	}
+}
+
+//#endregion
+export { applyProviders, asClass, asLazyClass, asValue, defineProviders, lifecycle };

package/dist/lib/scope.d.ts

@@ -0,0 +1,8 @@
+//#region src/lib/scope.d.ts
+declare const ServiceScope: {
+  readonly SINGLETON: "singleton";
+  readonly TRANSIENT: "transient";
+};
+type ServiceScope = (typeof ServiceScope)[keyof typeof ServiceScope];
+//#endregion
+export { ServiceScope };

package/dist/lib/scope.js

@@ -0,0 +1,8 @@
+//#region src/lib/scope.ts
+const ServiceScope = {
+	SINGLETON: "singleton",
+	TRANSIENT: "transient"
+};
+
+//#endregion
+export { ServiceScope };

package/dist/lib/service-identifiers.d.ts

@@ -0,0 +1,34 @@
+import { Constructor } from "./types.js";
+
+//#region src/lib/service-identifiers.d.ts
+
+/**
+ * Symbol-based identifier used to resolve services in a minifier-safe way.
+ * These identifiers never collide with minified constructor names and can be
+ * shared between runtime and generated modules.
+ */
+type ServiceIdentifier<T = unknown> = symbol & {
+  readonly __serviceIdentifierBrand: unique symbol;
+  readonly __type?: T;
+};
+/**
+ * Associates a constructor with a stable identifier. When an explicit identifier
+ * is provided (e.g., by generated metadata), it becomes canonical for the
+ * constructor. Attempting to reuse an identifier with a different constructor
+ * throws to surface manifest/config mismatches early.
+ */
+declare function registerServiceIdentifier<T>(ctor: Constructor, explicitIdentifier?: ServiceIdentifier<T>): ServiceIdentifier<T>;
+/**
+ * Retrieves the identifier for a constructor, creating one lazily when absent.
+ */
+declare function getServiceIdentifier<T>(ctor: Constructor): ServiceIdentifier<T>;
+/**
+ * Reverse lookup used by the container to go from identifier -> constructor.
+ */
+declare function getConstructorByIdentifier(identifier: ServiceIdentifier): Constructor | undefined;
+/**
+ * Removes all identifier associations. Useful for tests and tooling hooks that need a clean slate.
+ */
+declare function clearServiceIdentifierRegistry(): void;
+//#endregion
+export { ServiceIdentifier, clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier };

package/dist/lib/service-identifiers.js

@@ -0,0 +1,54 @@
+//#region src/lib/service-identifiers.ts
+let ctorToIdentifier = /* @__PURE__ */ new WeakMap();
+const identifierToCtor = /* @__PURE__ */ new Map();
+function formatIdentifierDescription(ctor) {
+	const name = ctor?.name?.trim();
+	return name ? `Service(${name})` : "Service(<anonymous>)";
+}
+function createServiceIdentifier(ctor) {
+	return Symbol(formatIdentifierDescription(ctor));
+}
+/**
+* Associates a constructor with a stable identifier. When an explicit identifier
+* is provided (e.g., by generated metadata), it becomes canonical for the
+* constructor. Attempting to reuse an identifier with a different constructor
+* throws to surface manifest/config mismatches early.
+*/
+function registerServiceIdentifier(ctor, explicitIdentifier) {
+	const current = ctorToIdentifier.get(ctor);
+	if (current) {
+		if (explicitIdentifier && explicitIdentifier !== current) {
+			const owner = identifierToCtor.get(explicitIdentifier);
+			if (owner && owner !== ctor) throw new Error("Attempted to reassign an existing ServiceIdentifier to a different constructor.");
+		}
+		return current;
+	}
+	const identifier = explicitIdentifier ?? createServiceIdentifier(ctor);
+	const existingOwner = identifierToCtor.get(identifier);
+	if (existingOwner && existingOwner !== ctor) throw new Error("ServiceIdentifier is already associated with a different constructor.");
+	ctorToIdentifier.set(ctor, identifier);
+	identifierToCtor.set(identifier, ctor);
+	return identifier;
+}
+/**
+* Retrieves the identifier for a constructor, creating one lazily when absent.
+*/
+function getServiceIdentifier(ctor) {
+	return registerServiceIdentifier(ctor);
+}
+/**
+* Reverse lookup used by the container to go from identifier -> constructor.
+*/
+function getConstructorByIdentifier(identifier) {
+	return identifierToCtor.get(identifier);
+}
+/**
+* Removes all identifier associations. Useful for tests and tooling hooks that need a clean slate.
+*/
+function clearServiceIdentifierRegistry() {
+	ctorToIdentifier = /* @__PURE__ */ new WeakMap();
+	identifierToCtor.clear();
+}
+
+//#endregion
+export { clearServiceIdentifierRegistry, getConstructorByIdentifier, getServiceIdentifier, registerServiceIdentifier };

package/dist/lib/testing/mocking.d.ts

@@ -0,0 +1,14 @@
+import { Newable } from "../types.js";
+import { vi } from "vitest";
+
+//#region src/lib/testing/mocking.d.ts
+type MethodKeys<T> = { [K in keyof T]: T[K] extends ((...args: any[]) => any) ? K : never }[keyof T];
+/** Typed mock shape returned for class auto-mocking. */
+type MockOf<T> = Partial<T> & {
+  /** Map of method name -> vi spy function */
+  spies: Record<Extract<MethodKeys<T>, string>, ReturnType<typeof vi.fn>>;
+  /** Original constructor reference for introspection */
+  __target: Newable<T>;
+};
+//#endregion
+export { MockOf };