@znight/testing 0.0.0-stage → 0.1.0

package/dist/index.mjs

@@ -0,0 +1,1561 @@
+import { createRequire } from "node:module";
+import { Application, Container, ErrorCode, InstantiationError, METADATA_VERSION, ZnightError, applyInterceptors, createConsoleLogger, describeToken, displayName, formatPath, isProviderDefinition } from "@znight/core";
+// src/utils.ts
+/** Internal helpers. */
+/**
+* Materialises a `Map`, an iterable of `[key, value]` pairs or a record into an array of pairs (an
+* iterable such as a generator can only be read once).
+*/
+function entriesOf(values) {
+	if (typeof values[Symbol.iterator] === "function") {
+		const entries = [];
+		for (const entry of values) {
+			if (!Array.isArray(entry) || entry.length !== 2) throw new TypeError("[znight] Expected [key, value] pairs (a Map, an array of pairs or a record)");
+			entries.push(entry);
+		}
+		return entries;
+	}
+	return Object.entries(values);
+}
+/** Whether `value` is a promise-like object (has a callable `then`). */
+function isThenable(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
+}
+/** Describes a provider key (class, token...) for messages. */
+function describeKey(key) {
+	if (typeof key === "function") return `class ${key.name || "<anonymous>"}`;
+	if (typeof key === "string") return `"${key}"`;
+	return String(key);
+}
+// src/define-metadata.ts
+/**
+* Hand-written metadata with the exact shape the compiler generates (version, resolution order...),
+* for tests that do not run the compiler (plugins, libraries, edge cases).
+*
+* ```ts
+* const metadata = createMetadata({
+*   'src/clock.ts#Clock': { scope: 'singleton', class: Clock, deps: [], factory: () => new Clock() },
+* })
+* ```
+*
+* @throws ZnightError ZNIGHT005 for a malformed provider definition.
+*/
+function createMetadata(providers, options = {}) {
+	if (providers === null || typeof providers !== "object") throw new TypeError("[znight] createMetadata() expects a record of provider definitions");
+	for (const [token, definition] of Object.entries(providers)) if (!isProviderDefinition(definition)) throw new ZnightError(ErrorCode.InvalidDecorator, `Invalid provider definition for ${describeToken(token)}: expected { scope, deps, factory }`);
+	const externals = options.externals?.map((external) => typeof external === "string" ? { token: external } : external);
+	return {
+		version: METADATA_VERSION,
+		providers,
+		resolutionOrder: options.resolutionOrder ?? topologicalOrder(providers),
+		...options.aliases === void 0 ? {} : { aliases: options.aliases },
+		...externals === void 0 ? {} : { externals },
+		...options.extensions === void 0 ? {} : { extensions: options.extensions }
+	};
+}
+const DEFAULT_PREFIX = "test";
+/** The token {@link defineTestMetadata} derives from a class: `<prefix>#<ClassName>`. */
+function testToken(cls, prefix = DEFAULT_PREFIX) {
+	const name = typeof cls === "function" ? cls.name : void 0;
+	if (typeof name !== "string" || name === "") throw new TypeError("[znight] testToken(): expected a named class");
+	return `${prefix}#${name}`;
+}
+/**
+* Class-first hand-written metadata: tokens are derived from class names (`test#UserService`),
+* dependencies may be classes, factories default to `new Class(...deps)` and the resolution order
+* is computed.
+*
+* ```ts
+* const metadata = defineTestMetadata({
+*   providers: [
+*     PgUserRepository,
+*     { class: UserService, deps: [PgUserRepository, '@znight/observability#Logger'] },
+*   ],
+*   aliases: [[UserRepository, PgUserRepository]],
+*   externals: ['@znight/observability#Logger'],
+* })
+* ```
+*
+* @throws ZnightError ZNIGHT004 for duplicate tokens; TypeError for a provider without class nor
+*   token/factory.
+*/
+function defineTestMetadata(spec = {}) {
+	const prefix = spec.tokenPrefix ?? DEFAULT_PREFIX;
+	const providers = (spec.providers ?? []).map((entry) => typeof entry === "function" ? { class: entry } : entry);
+	const classTokens = /* @__PURE__ */ new Map();
+	const tokens = providers.map((provider) => {
+		if (provider === null || typeof provider !== "object") throw new TypeError("[znight] defineTestMetadata(): a provider must be a class or { class?, token?, deps?, factory? }");
+		const token = provider.token ?? (provider.class === void 0 ? void 0 : testToken(provider.class, prefix));
+		if (token === void 0) throw new TypeError("[znight] defineTestMetadata(): a provider needs a class or a token");
+		if (provider.class !== void 0 && !classTokens.has(provider.class)) classTokens.set(provider.class, token);
+		return token;
+	});
+	const toToken = (key) => {
+		if (typeof key === "string") return key;
+		return classTokens.get(key) ?? testToken(key, prefix);
+	};
+	const definitions = /* @__PURE__ */ new Map();
+	providers.forEach((provider, position) => {
+		const token = tokens[position];
+		if (definitions.has(token)) throw new ZnightError(ErrorCode.DuplicateProvider, `defineTestMetadata(): duplicate provider ${describeToken(token)}`, { hints: ["Give one of them an explicit token"] });
+		definitions.set(token, toDefinition(token, provider, toToken));
+	});
+	let aliases;
+	if (spec.aliases !== void 0) {
+		const pairs = entriesOf(spec.aliases).map(([alias, target]) => [toToken(alias), toToken(target)]);
+		aliases = Object.fromEntries(pairs);
+	}
+	return createMetadata(Object.fromEntries(definitions), {
+		...aliases === void 0 ? {} : { aliases },
+		...spec.externals === void 0 ? {} : { externals: spec.externals },
+		...spec.extensions === void 0 ? {} : { extensions: spec.extensions },
+		...spec.resolutionOrder === void 0 ? {} : { resolutionOrder: spec.resolutionOrder }
+	});
+}
+function toDefinition(token, provider, toToken) {
+	const cls = provider.class;
+	let factory = provider.factory;
+	if (factory === void 0) {
+		if (cls === void 0) throw new TypeError(`[znight] defineTestMetadata(): ${token} needs a class or a factory`);
+		const constructible = cls;
+		factory = (deps) => new constructible(...deps);
+	}
+	const deps = (provider.deps ?? []).map((dep) => toDependency(dep, toToken));
+	return {
+		scope: provider.scope ?? "singleton",
+		deps,
+		factory,
+		...cls === void 0 ? {} : { class: cls },
+		...provider.async === void 0 ? {} : { async: provider.async },
+		...provider.interceptors === void 0 ? {} : { interceptors: provider.interceptors },
+		...provider.dispose === void 0 ? {} : { dispose: provider.dispose },
+		...provider.name === void 0 ? {} : { name: provider.name },
+		...provider.primary === void 0 ? {} : { primary: provider.primary },
+		...provider.source === void 0 ? {} : { source: provider.source }
+	};
+}
+function toDependency(dep, toToken) {
+	if (typeof dep === "string" || typeof dep === "function") return toToken(dep);
+	if (dep !== null && typeof dep === "object") {
+		if ("multi" in dep && Array.isArray(dep.multi)) return { multi: dep.multi.map(toToken) };
+		if ("lazy" in dep && dep.lazy !== void 0) return { lazy: toToken(dep.lazy) };
+		if ("token" in dep && dep.optional === true) return {
+			token: toToken(dep.token),
+			optional: true
+		};
+		if ("prototype" in dep) return toToken(dep);
+	}
+	throw new TypeError(`[znight] defineTestMetadata(): invalid dependency ${String(dep)}`);
+}
+/** Hard dependencies of a definition (lazy ones excluded: they never constrain the order). */
+function hardDependencies(definition) {
+	const tokens = [];
+	for (const ref of definition.deps) if (typeof ref === "string") tokens.push(ref);
+	else if ("multi" in ref) tokens.push(...ref.multi);
+	else if ("token" in ref) tokens.push(ref.token);
+	return tokens;
+}
+/** Deterministic topological order (dependencies first). Cycles are left for the container to report. */
+function topologicalOrder(providers) {
+	const order = [];
+	const state = /* @__PURE__ */ new Map();
+	const visit = (token) => {
+		if (state.has(token) || !Object.hasOwn(providers, token)) return;
+		state.set(token, "visiting");
+		for (const dep of hardDependencies(providers[token])) visit(dep);
+		state.set(token, "done");
+		order.push(token);
+	};
+	for (const token of Object.keys(providers)) visit(token);
+	return order;
+}
+// src/spy.ts
+const DEFAULT_NAME = "spy";
+/** Global call counter shared by every built-in spy (`mock.invocationCallOrder`). */
+let callOrder = 0;
+const internalsBySpy = /* @__PURE__ */ new WeakMap();
+function internalsOf(spy) {
+	const internals = typeof spy === "function" ? internalsBySpy.get(spy) : void 0;
+	if (internals === void 0) throw new TypeError("[znight] Not a spy created by createSpy()");
+	return internals;
+}
+function createState() {
+	const calls = [];
+	return {
+		calls,
+		results: [],
+		instances: [],
+		contexts: [],
+		invocationCallOrder: [],
+		get lastCall() {
+			return calls[calls.length - 1];
+		}
+	};
+}
+function clearState(state) {
+	state.calls.length = 0;
+	state.results.length = 0;
+	state.instances.length = 0;
+	state.contexts.length = 0;
+	state.invocationCallOrder.length = 0;
+}
+function isObjectLike$1(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function");
+}
+function invoke(internals, self, args, isNew) {
+	const state = internals.state;
+	state.calls.push(args);
+	state.contexts.push(self);
+	state.instances.push(self);
+	state.invocationCallOrder.push(++callOrder);
+	const result = {
+		type: "incomplete",
+		value: void 0
+	};
+	state.results.push(result);
+	const implementation = internals.once.shift() ?? internals.implementation;
+	try {
+		const value = implementation === void 0 ? void 0 : implementation.apply(self, args);
+		const returned = isNew && !isObjectLike$1(value) ? self : value;
+		result.type = "return";
+		result.value = returned;
+		return returned;
+	} catch (error) {
+		result.type = "throw";
+		result.value = error;
+		throw error;
+	}
+}
+function returning(value) {
+	return () => value;
+}
+function resolving(value) {
+	return () => Promise.resolve(value);
+}
+function rejecting(error) {
+	return () => Promise.reject(error);
+}
+function returnThis() {
+	return this;
+}
+/** Methods shared by every built-in spy (the prototype of the spy functions). */
+const spyPrototype = Object.create(Function.prototype, {
+	_isMockFunction: { value: true },
+	mock: { get() {
+		return internalsOf(this).state;
+	} },
+	mockImplementation: { value(implementation) {
+		internalsOf(this).implementation = implementation;
+		return this;
+	} },
+	mockImplementationOnce: { value(implementation) {
+		internalsOf(this).once.push(implementation);
+		return this;
+	} },
+	mockReturnValue: { value(value) {
+		internalsOf(this).implementation = returning(value);
+		return this;
+	} },
+	mockReturnValueOnce: { value(value) {
+		internalsOf(this).once.push(returning(value));
+		return this;
+	} },
+	mockResolvedValue: { value(value) {
+		internalsOf(this).implementation = resolving(value);
+		return this;
+	} },
+	mockResolvedValueOnce: { value(value) {
+		internalsOf(this).once.push(resolving(value));
+		return this;
+	} },
+	mockRejectedValue: { value(error) {
+		internalsOf(this).implementation = rejecting(error);
+		return this;
+	} },
+	mockRejectedValueOnce: { value(error) {
+		internalsOf(this).once.push(rejecting(error));
+		return this;
+	} },
+	mockReturnThis: { value() {
+		internalsOf(this).implementation = returnThis;
+		return this;
+	} },
+	mockName: { value(name) {
+		internalsOf(this).name = String(name);
+		return this;
+	} },
+	getMockName: { value() {
+		return internalsOf(this).name;
+	} },
+	getMockImplementation: { value() {
+		return internalsOf(this).implementation;
+	} },
+	mockClear: { value() {
+		clearState(internalsOf(this).state);
+		return this;
+	} },
+	mockReset: { value() {
+		const internals = internalsOf(this);
+		clearState(internals.state);
+		internals.once.length = 0;
+		internals.implementation = internals.initial;
+		return this;
+	} },
+	mockRestore: { value() {
+		const internals = internalsOf(this);
+		clearState(internals.state);
+		internals.once.length = 0;
+		internals.implementation = internals.initial;
+	} }
+});
+/**
+* Creates the built-in, dependency-free, Jest-compatible spy. It records `mock.calls`,
+* `mock.results`, `mock.instances`, `mock.contexts`, `mock.invocationCallOrder` and `mock.lastCall`,
+* supports `mockReturnValue(Once)`, `mockResolvedValue(Once)`, `mockRejectedValue(Once)`,
+* `mockImplementation(Once)`, `mockReturnThis`, `mockName`, `mockClear`, `mockReset` and
+* `mockRestore`, and is recognised by Jest's and Vitest's `expect` (`_isMockFunction`).
+*
+* `mockReset()` restores the implementation given to `createSpy()` (Vitest semantics).
+*
+* ```ts
+* const find = createSpy((id: string) => ({ id }))
+* find.mockReturnValueOnce({ id: 'x' })
+* find('1')
+* find.mock.calls // [['1']]
+* ```
+*/
+function createSpy(implementation) {
+	if (implementation !== void 0 && typeof implementation !== "function") throw new TypeError("[znight] createSpy() expects a function implementation");
+	const initial = implementation;
+	const internals = {
+		name: DEFAULT_NAME,
+		implementation: initial,
+		initial,
+		once: [],
+		state: createState()
+	};
+	const spy = function(...args) {
+		return invoke(internals, this, args, new.target !== void 0);
+	};
+	Object.setPrototypeOf(spy, spyPrototype);
+	internalsBySpy.set(spy, internals);
+	return spy;
+}
+/** Whether `value` is a spy created by {@link createSpy}. */
+function isBuiltinSpy(value) {
+	return typeof value === "function" && internalsBySpy.has(value);
+}
+// src/mock-fn.ts
+const BUILTIN = Object.freeze({
+	source: "builtin",
+	create: createSpy
+});
+let defaultOption = "auto";
+/** `mock` of `bun:test`: `undefined` until probed, `null` when unavailable. */
+let bunMock;
+function assertOption(option, where) {
+	if (typeof option === "function" || option === "auto" || option === "builtin") return;
+	throw new TypeError(`[znight] ${where}: mockFn must be 'auto', 'builtin' or a function such as vi.fn`);
+}
+/**
+* Sets the spy factory used when `mockFn` is not passed explicitly (e.g. in a Vitest setup file:
+* `setDefaultMockFn(vi.fn)`). Without argument, restores auto-detection.
+*/
+function setDefaultMockFn(option = "auto") {
+	assertOption(option, "setDefaultMockFn()");
+	defaultOption = option;
+}
+/**
+* Resolves a {@link MockFnOption} (default: the option set with {@link setDefaultMockFn}, `'auto'`
+* initially) to a spy factory.
+*/
+function resolveMockFn(option) {
+	const effective = option ?? defaultOption;
+	assertOption(effective, "resolveMockFn()");
+	if (typeof effective === "function") return {
+		source: "custom",
+		create: effective
+	};
+	if (effective === "builtin") return BUILTIN;
+	return detectMockFn();
+}
+/**
+* Auto-detects the spy factory of the running test framework: Vitest (`globalThis.vi.fn`, with
+* `globals: true`), Jest (`globalThis.jest.fn`), `bun:test` (`mock`, loaded only when running on
+* Bun), otherwise the built-in spy ({@link createSpy}).
+*/
+function detectMockFn() {
+	const scope = globalThis;
+	const vitest = scope.vi?.fn;
+	if (typeof vitest === "function") return {
+		source: "vitest",
+		create: vitest
+	};
+	const jest = scope.jest?.fn;
+	if (typeof jest === "function") return {
+		source: "jest",
+		create: jest
+	};
+	const bun = loadBunMock();
+	if (bun !== void 0) return {
+		source: "bun",
+		create: bun
+	};
+	return BUILTIN;
+}
+/** Whether the code runs on Bun. */
+function isBunRuntime() {
+	return typeof globalThis.Bun !== "undefined";
+}
+function loadBunMock() {
+	bunMock ??= isBunRuntime() ? requireBunMock() : null;
+	return bunMock ?? void 0;
+}
+function requireBunMock() {
+	try {
+		const specifier = ["bun", "test"].join(":");
+		const bunTest = createRequire(import.meta.url)(specifier);
+		return typeof bunTest.mock === "function" ? bunTest.mock : null;
+	} catch {
+		return null;
+	}
+}
+// src/mock.ts
+/**
+* Property names never auto-mocked (they read as `undefined` unless set explicitly). Libraries probe
+* them to detect promises (`then`), JSON values (`toJSON`), asymmetric matchers (`asymmetricMatch`),
+* React elements (`$$typeof`), DOM nodes (`nodeType`, `tagName`), ES module namespaces
+* (`__esModule`) or mock functions (`_isMockFunction`). Names starting with `@@` (Immutable.js
+* sentinels) are reserved too. Symbol-keyed properties are never auto-mocked.
+*/
+const RESERVED = /* @__PURE__ */ new Set([
+	"then",
+	"toJSON",
+	"asymmetricMatch",
+	"$$typeof",
+	"nodeType",
+	"tagName",
+	"__esModule",
+	"_isMockFunction"
+]);
+const TREE = Symbol("znight.mock");
+const mocks = /* @__PURE__ */ new WeakSet();
+function isReserved(key) {
+	return RESERVED.has(key) || key.startsWith("@@");
+}
+function createMock(first, second, third) {
+	if (typeof first === "function") return mockObject(first, second, third);
+	return mockObject(void 0, first, second);
+}
+/** {@link createMock} with an optional class (internal). */
+function mockObject(cls, partial, options = {}) {
+	if (partial !== void 0 && (partial === null || typeof partial !== "object")) throw new TypeError("[znight] createMock(): the partial implementation must be an object");
+	const tree = {
+		create: resolveMockFn(options.mockFn).create,
+		deep: options.deep === true,
+		spies: []
+	};
+	const className = typeof cls === "function" ? cls.name : void 0;
+	return createNode(options.name ?? (typeof className === "string" && className !== "" ? className : "mock"), tree, cls, partial);
+}
+/** Whether `value` is a mock (or one of its spies) created by {@link createMock}. */
+function isMock(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function") && mocks.has(value);
+}
+/** Forgets the calls recorded by every spy of `mock` (`mockClear()`); implementations are kept. */
+function clearMock(mock) {
+	for (const { spy } of treeOf(mock, "clearMock").spies) spy.mockClear?.();
+}
+/**
+* Resets every spy of `mock` to its initial state: recorded calls and programmed implementations
+* are forgotten, implementations given to {@link createMock} (and deep returns) are restored.
+*/
+function resetMock(mock) {
+	for (const { spy, implementation } of treeOf(mock, "resetMock").spies) {
+		spy.mockReset?.();
+		if (implementation !== void 0) spy.mockImplementation?.(implementation);
+	}
+}
+function treeOf(mock, where) {
+	const tree = isMock(mock) ? mock[TREE] : void 0;
+	if (tree === void 0) throw new TypeError(`[znight] ${where}(): expected a mock created by createMock()`);
+	return tree;
+}
+/** An object mock (the root of a mock, or the value returned by a deep spy). */
+function createNode(name, tree, cls, partial) {
+	const target = Object.create(typeof cls === "function" && isObjectLike(cls.prototype) ? cls.prototype : Object.prototype);
+	const accessors = typeof cls === "function" ? accessorKeys(cls.prototype) : void 0;
+	const children = /* @__PURE__ */ new Map();
+	if (partial !== void 0) for (const key of Reflect.ownKeys(partial)) {
+		const value = partial[key];
+		if (typeof key === "string" && typeof value === "function") children.set(key, createSpyNode(`${name}.${key}`, tree, value));
+		else defineValue(target, key, value);
+	}
+	const proxy = new Proxy(target, {
+		get(object, key, receiver) {
+			if (typeof key === "symbol") {
+				if (key === TREE) return tree;
+				return Object.hasOwn(object, key) ? object[key] : void 0;
+			}
+			if (Object.hasOwn(object, key)) return object[key];
+			if (key === "constructor") return Reflect.get(object, key, receiver);
+			if (isReserved(key)) return void 0;
+			if (Object.hasOwn(Object.prototype, key)) return Reflect.get(Object.prototype, key, receiver);
+			if (accessors?.has(key) === true) return void 0;
+			let child = children.get(key);
+			if (child === void 0) {
+				child = createSpyNode(`${name}.${key}`, tree, void 0);
+				children.set(key, child);
+			}
+			return child;
+		},
+		set(object, key, value) {
+			defineValue(object, key, value);
+			return true;
+		},
+		deleteProperty(object, key) {
+			if (typeof key === "string") children.delete(key);
+			return Reflect.deleteProperty(object, key);
+		}
+	});
+	mocks.add(proxy);
+	return proxy;
+}
+/** A spy whose unknown properties are deep spies (`spy.nested.method`). */
+function createSpyNode(path, tree, implementation) {
+	const effective = implementation ?? (tree.deep ? deepReturn(path, tree) : void 0);
+	const spy = tree.create(effective);
+	if (typeof spy !== "function") throw new TypeError(`[znight] The mockFn factory returned ${typeof spy} instead of a function`);
+	if (typeof spy.mockName === "function") spy.mockName(path);
+	makeDeep(spy, path, tree);
+	tree.spies.push({
+		spy,
+		implementation: effective
+	});
+	mocks.add(spy);
+	return spy;
+}
+/** The implementation of a deep spy: returns the same deep mock on every call. */
+function deepReturn(path, tree) {
+	let result;
+	return () => {
+		result ??= createNode(`${path}()`, tree, void 0, void 0);
+		return result;
+	};
+}
+/**
+* Inserts a proxy between `spy` and its prototype: reading a property the spy does not have (own or
+* inherited) creates a child spy. The spy itself stays a genuine spy of its framework, which
+* `bun:test`'s `expect` requires (it rejects proxies).
+*/
+function makeDeep(spy, path, tree) {
+	const original = Object.getPrototypeOf(spy);
+	if (!isObjectLike(original)) return;
+	const children = /* @__PURE__ */ new Map();
+	const prototype = new Proxy(original, { get(object, key, receiver) {
+		if (typeof key === "symbol" || key in object || isReserved(key)) return Reflect.get(object, key, receiver);
+		let child = children.get(key);
+		if (child === void 0) {
+			child = createSpyNode(`${path}.${key}`, tree, void 0);
+			children.set(key, child);
+		}
+		return child;
+	} });
+	try {
+		Object.setPrototypeOf(spy, prototype);
+	} catch {}
+}
+function defineValue(object, key, value) {
+	Object.defineProperty(object, key, {
+		value,
+		writable: true,
+		enumerable: true,
+		configurable: true
+	});
+}
+/** Names of the accessors (getters/setters) declared along a prototype chain, `Object.prototype` excluded. */
+function accessorKeys(prototype) {
+	const keys = /* @__PURE__ */ new Set();
+	let current = prototype;
+	while (isObjectLike(current) && current !== Object.prototype && current !== Function.prototype) {
+		for (const key of Object.getOwnPropertyNames(current)) {
+			const descriptor = Object.getOwnPropertyDescriptor(current, key);
+			if (descriptor !== void 0 && (descriptor.get !== void 0 || descriptor.set !== void 0)) keys.add(key);
+		}
+		current = Object.getPrototypeOf(current);
+	}
+	return keys;
+}
+function isObjectLike(value) {
+	return value !== null && (typeof value === "object" || typeof value === "function");
+}
+// src/overrides.ts
+/**
+* A type-checked override: the value must match the type designated by the class or typed token.
+*
+* ```ts
+* await TestApp.create({ metadata, overrides: [override(UserRepository, new InMemoryUserRepository())] })
+* ```
+*/
+function override(key, value) {
+	return [key, value];
+}
+/**
+* Replaces a provider with a factory whose dependencies are resolved by the container (or, in
+* `TestBed`, like the target's dependencies).
+*
+* ```ts
+* overrideFactory(UserRepository, ([db]) => new InMemoryUserRepository(db), { deps: ['src/db.ts#Database'] })
+* ```
+*/
+function overrideFactory(key, factory, options = {}) {
+	if (typeof factory !== "function") throw new TypeError("[znight] overrideFactory() expects a factory function");
+	return [key, {
+		scope: options.scope ?? "singleton",
+		deps: options.deps ?? [],
+		factory,
+		...options.async === void 0 ? {} : { async: options.async },
+		...options.dispose === void 0 ? {} : { dispose: options.dispose }
+	}];
+}
+// src/extensions.ts
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
+function arrayOf(value) {
+	return Array.isArray(value) ? value : [];
+}
+function extension(metadata, name) {
+	if (!isRecord(metadata)) return void 0;
+	const extensions = metadata.extensions;
+	if (!isRecord(extensions)) return void 0;
+	const value = extensions[name];
+	return isRecord(value) ? value : void 0;
+}
+function tokensOf(value) {
+	return arrayOf(value).filter((token) => typeof token === "string");
+}
+/** Configuration classes declared by `@znight/config` (`extensions.config.configs`), by token. */
+function readConfigClasses(metadata) {
+	const result = /* @__PURE__ */ new Map();
+	for (const entry of arrayOf(extension(metadata, "config")?.["configs"])) {
+		if (!isRecord(entry) || typeof entry["token"] !== "string") continue;
+		const fields = [];
+		for (const field of arrayOf(entry["fields"])) {
+			if (!isRecord(field) || typeof field["property"] !== "string") continue;
+			fields.push({
+				property: field["property"],
+				env: typeof field["env"] === "string" ? field["env"] : void 0,
+				type: typeof field["type"] === "string" ? field["type"] : void 0,
+				hasDefault: Object.hasOwn(field, "default") && field["default"] !== void 0,
+				default: field["default"],
+				required: field["required"] === true
+			});
+		}
+		const prefix = entry["prefix"];
+		result.set(entry["token"], {
+			token: entry["token"],
+			prefix: typeof prefix === "string" && prefix !== "" ? prefix : void 0,
+			fields
+		});
+	}
+	return result;
+}
+/**
+* Tokens an HTTP application needs at boot: controllers (`extensions.http.controllers[].token`) and
+* the guards and interceptors they and their routes reference.
+*/
+function readHttpRoots(metadata) {
+	const roots = [];
+	for (const controller of arrayOf(extension(metadata, "http")?.["controllers"])) {
+		if (!isRecord(controller)) continue;
+		if (typeof controller["token"] === "string") roots.push(controller["token"]);
+		roots.push(...tokensOf(controller["guards"]), ...tokensOf(controller["interceptors"]));
+		for (const route of arrayOf(controller["routes"])) if (isRecord(route)) roots.push(...tokensOf(route["guards"]), ...tokensOf(route["interceptors"]));
+	}
+	return roots;
+}
+/** Message consumers (`extensions.messaging.consumers[].token`). */
+function readMessagingRoots(metadata) {
+	const roots = [];
+	for (const consumer of arrayOf(extension(metadata, "messaging")?.["consumers"])) if (isRecord(consumer) && typeof consumer["token"] === "string") roots.push(consumer["token"]);
+	return roots;
+}
+/** Hosts of scheduled jobs (`extensions.schedule.jobs[].token`), disabled jobs included (they can be triggered). */
+function readScheduleRoots(metadata) {
+	const roots = [];
+	for (const job of arrayOf(extension(metadata, "schedule")?.["jobs"])) if (isRecord(job) && typeof job["token"] === "string") roots.push(job["token"]);
+	return roots;
+}
+// src/metadata-index.ts
+/**
+* Read-only index over compiled metadata: provider definitions, aliases, externals and the key
+* lookups shared by `TestBed`, `mocks.get()` and the testing helpers (class, token, alias or display
+* name → canonical token). Internal.
+*/
+var MetadataIndex = class {
+	metadata;
+	#providers = /* @__PURE__ */ new Map();
+	#aliases = /* @__PURE__ */ new Map();
+	#externals = /* @__PURE__ */ new Map();
+	constructor(metadata) {
+		assertMetadata(metadata);
+		this.metadata = metadata;
+		for (const [token, definition] of Object.entries(metadata.providers)) this.#providers.set(token, definition);
+		for (const [alias, target] of Object.entries(metadata.aliases ?? {})) this.#aliases.set(alias, target);
+		for (const external of metadata.externals ?? []) if (typeof external?.token === "string") this.#externals.set(external.token, external);
+	}
+	/** Every provider token, in declaration order. */
+	providerTokens() {
+		return this.#providers.keys();
+	}
+	definition(token) {
+		return this.#providers.get(token);
+	}
+	isProvider(token) {
+		return this.#providers.has(token);
+	}
+	external(token) {
+		return this.#externals.get(token);
+	}
+	/** Whether `token` is a provider, an alias or an external of the metadata. */
+	isKnown(token) {
+		return this.#providers.has(token) || this.#aliases.has(token) || this.#externals.has(token);
+	}
+	/** Provider, alias and external tokens. */
+	knownTokens() {
+		return /* @__PURE__ */ new Set([
+			...this.#providers.keys(),
+			...this.#aliases.keys(),
+			...this.#externals.keys()
+		]);
+	}
+	/** The class of a provider, when it is a class provider. */
+	classOf(token) {
+		return this.#providers.get(token)?.class;
+	}
+	/** Follows aliases (cycle-guarded) until a provider token; returns `token` itself otherwise. */
+	canonical(token) {
+		let current = token;
+		const seen = /* @__PURE__ */ new Set();
+		while (!this.#providers.has(current) && this.#aliases.has(current) && !seen.has(current)) {
+			seen.add(current);
+			current = this.#aliases.get(current);
+		}
+		return current;
+	}
+	/** Alias entries (alias → target), for filtering and display. */
+	aliases() {
+		return this.#aliases.entries();
+	}
+	/**
+	* Finds the canonical token designated by `key` among `universe`:
+	* - a string: a token of `universe`, an alias resolving into it, or a unique display name
+	*   (`'UserService'`) of a token or alias;
+	* - a class: the token whose provider class is `key`, else the unique token whose class extends
+	*   it, else a unique display name equal to the class name (externals, interfaces).
+	*
+	* @throws ZnightError ZNIGHT008 when a display name is ambiguous.
+	*/
+	find(key, universe) {
+		if (typeof key === "string") {
+			if (universe.has(key)) return key;
+			const canonical = this.canonical(key);
+			if (universe.has(canonical)) return canonical;
+			return this.#findByName(key, universe, void 0);
+		}
+		if (typeof key !== "function") return void 0;
+		const cls = key;
+		const exact = [...universe].filter((token) => this.classOf(token) === cls);
+		if (exact.length > 0) return exact[0];
+		const derived = [...universe].filter((token) => extendsClass(this.classOf(token), cls));
+		if (derived.length === 1) return derived[0];
+		if (derived.length > 1) throw ambiguousError(cls.name, derived);
+		const name = cls.name;
+		return typeof name === "string" && name !== "" ? this.#findByName(name, universe, cls) : void 0;
+	}
+	#findByName(name, universe, cls) {
+		const matches = /* @__PURE__ */ new Set();
+		const add = (token) => {
+			const canonical = this.canonical(token);
+			if (universe.has(canonical)) matches.add(canonical);
+			else if (universe.has(token)) matches.add(token);
+		};
+		for (const token of universe) if (displayName(token) === name) add(token);
+		for (const [alias] of this.#aliases) if (displayName(alias) === name) add(alias);
+		const candidates = [...matches].filter((token) => {
+			if (cls === void 0) return true;
+			const own = this.classOf(token);
+			return own === void 0 || own === cls || extendsClass(own, cls);
+		});
+		if (candidates.length === 1) return candidates[0];
+		if (candidates.length > 1) throw ambiguousError(name, candidates);
+	}
+};
+function extendsClass(candidate, base) {
+	if (candidate === void 0 || candidate === base) return false;
+	const prototype = base.prototype;
+	return typeof prototype === "object" && prototype !== null && candidate.prototype instanceof base;
+}
+function ambiguousError(name, tokens) {
+	return new ZnightError(ErrorCode.AmbiguousInjection, `"${name}" is ambiguous: it matches ${tokens.map(describeToken).join(", ")}`, { hints: ["Use the full token (or the class) instead of the display name"] });
+}
+function assertMetadata(metadata) {
+	if (metadata === null || typeof metadata !== "object" || metadata.providers === null || typeof metadata.providers !== "object") throw new ZnightError(ErrorCode.MissingProvider, "No compiled metadata: expected the generated __ZNIGHT_METADATA__", { hints: ["Pass { metadata: __ZNIGHT_METADATA__ } imported from src/.znight/container.generated.ts", "Generate it before running tests: `znight generate`, the Bun preload `@znight/compiler/bun` or the Vite plugin under Vitest"] });
+	if (metadata.version !== METADATA_VERSION) throw new ZnightError(ErrorCode.VersionMismatch, `Unsupported metadata version ${String(metadata.version)} (expected ${METADATA_VERSION})`, { hints: ["Regenerate the metadata with the @znight/compiler version matching @znight/testing"] });
+}
+// src/test-app.ts
+/** Name of the HTTP plugin `TestApp.inject()` delegates to (`HttpPlugin.configure()` from `@znight/http`). */
+const HTTP_PLUGIN_NAME = "http";
+/**
+* End-to-end harness: a started {@link Application} without signal handlers, overrides applied last
+* and only what the tested entry points need instantiated.
+*
+* ```ts
+* await using app = await TestApp.create({
+*   metadata: __ZNIGHT_METADATA__,
+*   plugins: [HttpPlugin.configure({ adapter: fastify() })],
+*   overrides: [[UserRepository, fakeRepository]],
+* })
+* const response = await app.inject({ method: 'GET', url: '/users/1' })
+* expect(response.status).toBe(200)
+* expect(response.json()).toEqual({ id: '1' })
+* ```
+*/
+var TestApp = class TestApp {
+	/** The application under test. */
+	app;
+	#closed = false;
+	constructor(app) {
+		this.app = app;
+	}
+	/**
+	* Creates and (by default) starts the application.
+	*
+	* Plugins are used as configured: give the servers they start a free port or none in tests
+	* (`HttpPlugin.configure({ port: 0 })`, `ObservabilityPlugin.configure({ metrics: { server: false } })`);
+	* a start failing on a port already in use (`EADDRINUSE`) gets a hint saying so.
+	*
+	* @throws the error of `Application.create()` / `app.start()` (everything is rolled back).
+	*/
+	static async create(options) {
+		if (options === null || typeof options !== "object") throw new TypeError("[znight] TestApp.create({ metadata }) requires options with the generated metadata");
+		const index = new MetadataIndex(options.metadata);
+		const providers = resolveKeys(options.providers, index);
+		const overrides = resolveKeys(options.overrides, index);
+		const init = initOptions(options, index, overrides);
+		try {
+			const app = await Application.create({
+				metadata: options.metadata,
+				plugins: options.plugins ?? [],
+				...providers === void 0 ? {} : { providers },
+				...overrides === void 0 ? {} : { overrides },
+				logger: options.logger ?? createConsoleLogger({ level: "warn" }),
+				shutdown: {
+					...options.shutdown,
+					signals: false
+				},
+				init
+			});
+			if (options.start !== false) await app.start();
+			return new TestApp(app);
+		} catch (error) {
+			addHints(error, init.only !== void 0);
+			throw error;
+		}
+	}
+	/** The application container. */
+	get container() {
+		return this.app.container;
+	}
+	get(key) {
+		return this.app.container.get(key);
+	}
+	/**
+	* Dispatches a request in memory through the HTTP plugin (`HttpPlugin`): routing, guards,
+	* interceptors, validation, serialisation, without opening a socket. Send uploads as a
+	* `FormData` body; read downloads from `response.bytes`. Send cookies with `cookies` (and
+	* `signedCookies`), read those the response sets from `response.cookies`.
+	*
+	* @throws ZnightError ZNIGHT001 when the application has no HTTP plugin, ZNIGHT021 once closed.
+	*/
+	inject(request) {
+		try {
+			if (this.#closed) throw new ZnightError(ErrorCode.LifecycleFailed, "TestApp.inject(): the application is closed");
+			if (request === null || typeof request !== "object" || typeof request.url !== "string") throw new TypeError("[znight] TestApp.inject() expects { method?, url, headers?, body?, query?, cookies?, signedCookies? }");
+			const plugin = this.app.getPlugin(HTTP_PLUGIN_NAME);
+			if (plugin === void 0 || typeof plugin.inject !== "function") throw new ZnightError(ErrorCode.MissingProvider, "TestApp.inject() requires the HTTP plugin", { hints: ["Add HttpPlugin.configure({ adapter }) from @znight/http to TestApp.create({ plugins })"] });
+			const method = (request.method ?? "GET").toUpperCase();
+			return Promise.resolve(plugin.inject({
+				...request,
+				method
+			})).then(complete);
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	/**
+	* Dispatches a request in memory and resolves at the response headers; the body is read as it is
+	* produced (`response.body`). Cancelling the body (or aborting `signal`) disconnects the client.
+	*
+	* @throws ZnightError ZNIGHT001 when the HTTP plugin does not support streaming, ZNIGHT021 once closed.
+	*/
+	injectStream(request) {
+		return this.#stream("injectStream", request);
+	}
+	/**
+	* Opens an event stream (Server-Sent Events) in memory and reads it like `EventSource`:
+	*
+	* ```ts
+	* await using stream = await app.injectSse({ url: '/orders/o-1/events' })
+	* const event = await stream.next() // rejects after 2 000 ms
+	* expect(event.json()).toMatchObject({ status: 'paid' })
+	* const resumed = await stream.reconnect() // last-event-id, like EventSource
+	* ```
+	*
+	* Leaving the `await using` block (or `close()`) disconnects: the server sees `ctx.signal` abort.
+	*
+	* @throws ZnightError ZNIGHT001 when the HTTP plugin does not support event streams, ZNIGHT021 once closed.
+	*/
+	injectSse(request) {
+		return this.#stream("injectSse", request);
+	}
+	#stream(method, request) {
+		try {
+			if (this.#closed) throw new ZnightError(ErrorCode.LifecycleFailed, `TestApp.${method}(): the application is closed`);
+			if (request === null || typeof request !== "object" || typeof request.url !== "string") throw new TypeError(`[znight] TestApp.${method}() expects { method?, url, headers?, body?, query?, cookies?, signedCookies?, signal? }`);
+			const plugin = this.app.getPlugin(HTTP_PLUGIN_NAME);
+			const dispatch = plugin?.[method];
+			if (typeof dispatch !== "function") throw new ZnightError(ErrorCode.MissingProvider, `TestApp.${method}() requires the HTTP plugin with streaming support`, { hints: [plugin === void 0 ? "Add HttpPlugin.configure({ adapter }) from @znight/http to TestApp.create({ plugins })" : `The plugin named 'http' does not implement ${method}(): register HttpPlugin.configure({ adapter }) from @znight/http ≥ 0.1.0 (the same release as @znight/testing)`] });
+			const sent = {
+				...request,
+				method: (request.method ?? "GET").toUpperCase()
+			};
+			return Promise.resolve(dispatch.call(plugin, sent));
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+	/** Stops the application (idempotent): plugins `onStop`, providers `onStop` and disposal, plugins `onDispose`. */
+	close() {
+		this.#closed = true;
+		return this.app.stop();
+	}
+	/** {@link close}, for `await using app = await TestApp.create(...)`. */
+	[Symbol.asyncDispose]() {
+		return this.close();
+	}
+};
+const ENCODER = new TextEncoder();
+const NO_COOKIES = Object.freeze({});
+/**
+* The plugin response, as is when it is complete; otherwise with `bytes` derived from `body` and
+* no `cookies` when the plugin did not provide them.
+*/
+function complete(response) {
+	const hasBytes = response.bytes instanceof Uint8Array;
+	const hasCookies = response.cookies !== null && typeof response.cookies === "object";
+	if (hasBytes && hasCookies) return response;
+	return {
+		status: response.status,
+		headers: response.headers,
+		body: response.body,
+		bytes: hasBytes ? response.bytes : ENCODER.encode(response.body),
+		cookies: hasCookies ? response.cookies : NO_COOKIES,
+		json: () => response.json()
+	};
+}
+/**
+* Materialises `providers`/`overrides` and maps string keys that are not tokens of the metadata to
+* the token they designate (alias or unique display name: `'UserRepository'`), like `TestBed` does.
+* Unknown strings are kept (tokens registered at runtime by plugins); classes are resolved by the
+* container.
+*/
+function resolveKeys(values, index) {
+	if (values === void 0) return void 0;
+	const known = index.knownTokens();
+	return entriesOf(values).map(([key, value]) => {
+		if (typeof key !== "string" || known.has(key)) return [key, value];
+		return [index.find(key, known) ?? key, value];
+	});
+}
+function initOptions(options, index, overrides) {
+	const only = options.only;
+	if (only === "all") return {};
+	let roots;
+	if (only === void 0) {
+		const metadata = options.metadata;
+		roots = [
+			...readHttpRoots(metadata),
+			...readMessagingRoots(metadata),
+			...readScheduleRoots(metadata)
+		].filter((token) => index.isProvider(token));
+		if (roots.length === 0) return {};
+	} else {
+		if (!Array.isArray(only)) throw new TypeError("[znight] TestApp.create(): only must be 'all' or an array of keys");
+		roots = only;
+	}
+	const extra = (overrides ?? []).map(([key]) => key);
+	const plugins = pluginRoots(options.plugins ?? [], { metadata: options.metadata }, index);
+	return { only: unique([
+		...roots,
+		...plugins,
+		...extra
+	]) };
+}
+/**
+* Providers the plugins need at boot (`Plugin.initRoots()`, {@link PluginInitRoots}), as provider
+* tokens of the metadata. Other keys (classes without provider, unknown or ambiguous names) are
+* left to the plugin, which reports them with its own message.
+*/
+function pluginRoots(plugins, context, index) {
+	const providers = new Set(index.providerTokens());
+	const roots = [];
+	const frozen = Object.freeze({ metadata: context.metadata });
+	for (const plugin of plugins) {
+		const initRoots = plugin?.initRoots;
+		if (typeof initRoots !== "function") continue;
+		const keys = initRoots.call(plugin, frozen);
+		if (!Array.isArray(keys)) throw new TypeError(`[znight] TestApp.create(): initRoots() of the plugin "${String(plugin.name)}" must return an array of classes or tokens`);
+		for (const key of keys) {
+			const token = findProvider(key, providers, index);
+			if (token !== void 0) roots.push(token);
+		}
+	}
+	return roots;
+}
+function findProvider(key, providers, index) {
+	try {
+		return index.find(key, providers);
+	} catch {
+		return;
+	}
+}
+const ONLY_HINT = "With TestApp: list it in TestApp.create({ only: [...] }) (or pass only: 'all') to create it at boot";
+/** Hint added to start failures caused by a port already in use (`EADDRINUSE`). */
+const PORT_IN_USE_HINT = "With TestApp, servers need no fixed port (inject() sends requests in memory): configure HttpPlugin with { port: 0 } and ObservabilityPlugin with { metrics: { server: false } } (or server: { port: 0 }) in tests";
+/**
+* Adds TestApp hints to a failed `TestApp.create()`, along the `cause` chain:
+* - the TestApp form of the container hint to "cannot create on demand: its factory is async"
+*   errors (ZNIGHT015, hint `init({ only })`) of a restricted boot, which `TestApp` exposes as its
+*   `only` option;
+* - when a server could not listen because its port is taken (`EADDRINUSE`: a fixed port, such as
+*   the default `9464` of the observability metrics server, shared by test files running in
+*   parallel or by `znight dev`), the options giving it a free port or none, on the outermost error
+*   carrying hints (the `ZnightError` the application wraps plugin failures in).
+*/
+function addHints(error, restricted) {
+	const chain = [];
+	let current = error;
+	while (current !== null && typeof current === "object" && !chain.includes(current)) {
+		chain.push(current);
+		current = current.cause;
+	}
+	if (restricted) {
+		for (const item of chain) if (item.code === ErrorCode.InstantiationFailed && Array.isArray(item.hints) && item.hints.some((hint) => typeof hint === "string" && hint.includes("init({ only })"))) addHint(item, ONLY_HINT);
+	}
+	if (chain.some((item) => item.code === "EADDRINUSE")) {
+		const outermost = chain.find((item) => Array.isArray(item.hints));
+		if (outermost !== void 0) addHint(outermost, PORT_IN_USE_HINT);
+	}
+}
+function addHint(error, hint) {
+	const hints = error.hints;
+	if (!hints.includes(hint)) Reflect.set(error, "hints", [...hints, hint]);
+}
+function unique(values) {
+	return [...new Set(values)];
+}
+// src/config.ts
+/**
+* Resolves {@link ConfigValues} to per-token values, validating class keys and property names.
+*
+* @throws ZnightError ZNIGHT012 for an unknown configuration class or property.
+*/
+function normalizeConfigValues(values, index, configs) {
+	const result = /* @__PURE__ */ new Map();
+	if (values === void 0) return result;
+	const universe = new Set(configs.keys());
+	for (const [key, properties] of entriesOf(values)) {
+		const token = index.find(key, universe) ?? findByPrefix(key, configs);
+		if (token === void 0) {
+			const available = [...configs.values()].map(describeConfig);
+			throw new ZnightError(ErrorCode.InvalidConfig, `config: ${describeKey(key)} is not a configuration class`, { hints: [available.length === 0 ? "The metadata declares no configuration class (extensions.config.configs)" : `Configuration classes: ${available.join(", ")}`] });
+		}
+		const info = configs.get(token);
+		if (properties === null || typeof properties !== "object") throw new ZnightError(ErrorCode.InvalidConfig, `config: the values of ${displayName(token)} must be an object`);
+		const known = new Set(info.fields.map((field) => field.property));
+		for (const property of Object.keys(properties)) if (!known.has(property)) throw new ZnightError(ErrorCode.InvalidConfig, `config: ${displayName(token)} has no configuration property "${property}"`, { hints: [`Properties: ${[...known].join(", ") || "(none)"}`] });
+		result.set(token, {
+			...result.get(token),
+			...properties
+		});
+	}
+	return result;
+}
+/**
+* Builds a real configuration instance like `@znight/config` without any source would:
+* `new ConfigClass()` (field initializers run), then the declared `@Default` values (which win over
+* initializers, as at runtime, converted to the field type, see {@link convertDefault}), then
+* `values` (as given). Required fields without value stay `undefined`.
+*/
+function buildConfigInstance(info, cls, values) {
+	let instance;
+	try {
+		instance = cls === void 0 ? {} : new cls();
+	} catch (error) {
+		throw new InstantiationError(info.token, [info.token], error);
+	}
+	for (const field of info.fields) if (values !== void 0 && Object.hasOwn(values, field.property)) instance[field.property] = values[field.property];
+	else if (field.hasDefault) instance[field.property] = convertDefault(field.default, field.type);
+	return instance;
+}
+function findByPrefix(key, configs) {
+	if (typeof key !== "string") return void 0;
+	const matches = [...configs.values()].filter((info) => info.prefix === key);
+	return matches.length === 1 ? matches[0]?.token : void 0;
+}
+function describeConfig(info) {
+	const name = displayName(info.token);
+	return info.prefix === void 0 ? name : `${name} (prefix "${info.prefix}")`;
+}
+const INVALID = Symbol("invalid");
+/** Strict decimal numbers, as accepted by `@znight/config` (`42`, `-1.5`, `1e3`; not `0x10`). */
+const DECIMAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/;
+const TRUE = /* @__PURE__ */ new Set([
+	"true",
+	"1",
+	"yes",
+	"on"
+]);
+const FALSE = /* @__PURE__ */ new Set([
+	"false",
+	"0",
+	"no",
+	"off"
+]);
+/**
+* A declared default converted to the field type the way `@znight/config` converts it at runtime
+* (`loadConfig`), so the instance has the same shape in tests as in the application: `'8080'` → `8080`
+* (`number`), `'yes'` → `true`, `'a, b'` → `['a', 'b']` (lists), an absolute URL string → a `URL`
+* (`url`), a JSON string → its value (`json`). `@znight/testing` does not depend on `@znight/config`,
+* hence this small mirror of its coercion rules. A value that does not convert (the compiler already
+* rejects invalid defaults) or an unknown type is kept as is (copied).
+*/
+function convertDefault(value, type) {
+	const converted = convert(value, type);
+	return converted === INVALID ? copy(value) : converted;
+}
+function convert(value, type) {
+	switch (type) {
+		case "string": return toText(value);
+		case "number": return toNumber(value);
+		case "boolean": return toBoolean(value);
+		case "string[]": return toList(value, toText);
+		case "number[]": return toList(value, toNumber);
+		case "url": return toUrl(value);
+		case "json": return toJson(value);
+		default: return INVALID;
+	}
+}
+function toText(value) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	return INVALID;
+}
+function toNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : INVALID;
+	if (typeof value !== "string" || !DECIMAL.test(value.trim())) return INVALID;
+	const number = Number(value.trim());
+	return Number.isFinite(number) ? number : INVALID;
+}
+function toBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === 1 || value === 0) return value === 1;
+	if (typeof value !== "string") return INVALID;
+	const text = value.trim().toLowerCase();
+	if (TRUE.has(text)) return true;
+	return FALSE.has(text) ? false : INVALID;
+}
+function toList(value, item) {
+	let items;
+	if (Array.isArray(value)) items = value;
+	else if (typeof value === "string") items = value.split(",").map((part) => part.trim()).filter((part) => part !== "");
+	else return INVALID;
+	const result = [];
+	for (const entry of items) {
+		const converted = item(entry);
+		if (converted === INVALID) return INVALID;
+		result.push(converted);
+	}
+	return result;
+}
+function toUrl(value) {
+	if (value instanceof URL) return new URL(value.href);
+	return typeof value === "string" && URL.canParse(value.trim()) ? new URL(value.trim()) : INVALID;
+}
+function toJson(value) {
+	if (typeof value !== "string") return copy(value);
+	try {
+		return JSON.parse(value);
+	} catch {
+		return INVALID;
+	}
+}
+/** Defaults are static values: copy them so that tests never share mutable defaults. */
+function copy(value) {
+	if (value === null || typeof value !== "object") return value;
+	try {
+		return structuredClone(value);
+	} catch {
+		return value;
+	}
+}
+// src/mock-registry.ts
+const REASONS = {
+	provided: "its value was passed with `provide`",
+	override: "it was replaced with `overrides`",
+	config: "it is a configuration class (a real instance is injected; set values with `config`)",
+	optional: "it is an optional dependency (`undefined` is injected unless provided)",
+	interceptor: "it is an interceptor (not applied unless `aop: \"real\"`)",
+	real: "it was built for real (aop: \"real\")"
+};
+/** Default {@link MockRegistry} implementation (internal). */
+var TestMocks = class {
+	#mocks;
+	#others;
+	#index;
+	#owner;
+	constructor(mocks, others, index, owner) {
+		this.#mocks = mocks;
+		this.#others = others;
+		this.#index = index;
+		this.#owner = owner;
+	}
+	get(key) {
+		const token = this.#index.find(key, new Set(this.#mocks.keys()));
+		if (token !== void 0) return this.#mocks.get(token);
+		throw this.#notMockedError(key);
+	}
+	has(key) {
+		return this.#index.find(key, new Set(this.#mocks.keys())) !== void 0;
+	}
+	tokens() {
+		return [...this.#mocks.keys()];
+	}
+	clearAll() {
+		for (const mock of this.#mocks.values()) clearMock(mock);
+	}
+	resetAll() {
+		for (const mock of this.#mocks.values()) resetMock(mock);
+	}
+	#notMockedError(key) {
+		const owner = displayName(this.#owner);
+		let other;
+		try {
+			other = this.#index.find(key, new Set(this.#others.keys()));
+		} catch {
+			other = void 0;
+		}
+		if (other !== void 0) {
+			const kind = this.#others.get(other);
+			return new ZnightError(ErrorCode.MissingProvider, `${describeToken(other)} is not mocked: ${REASONS[kind]}`);
+		}
+		const mocked = [...this.#mocks.keys()].map(displayName);
+		return new ZnightError(ErrorCode.MissingProvider, `No mock for ${describeKey(key)}: it is not a direct dependency of ${owner}`, { hints: [mocked.length === 0 ? `${owner} has no auto-mocked dependency` : `Auto-mocked: ${mocked.join(", ")}`, "TestBed only mocks direct dependencies; regenerate the metadata if the constructor changed"] });
+	}
+};
+// src/testbed-builder.ts
+const AOP_MODES = /* @__PURE__ */ new Set([
+	void 0,
+	"none",
+	"real"
+]);
+/**
+* Builds the target of `TestBed.create()`: resolves keys, injects auto-mocks / provided values /
+* configuration instances, runs the factory and assembles the result container. Internal.
+*/
+var Builder = class {
+	#index;
+	#options;
+	#mockFn;
+	#configs;
+	#configValues;
+	#provided;
+	#overrides;
+	/** Values injected into the target (and into built dependencies), by canonical token. */
+	#values = /* @__PURE__ */ new Map();
+	/** Real interceptors (aop: 'real'), by canonical token. */
+	#interceptors = /* @__PURE__ */ new Map();
+	#kinds = /* @__PURE__ */ new Map();
+	#mocks = /* @__PURE__ */ new Map();
+	/** Providers being built (cycle guard). */
+	#building = /* @__PURE__ */ new Set();
+	#known;
+	constructor(options) {
+		if (options === null || typeof options !== "object") throw new TypeError("[znight] TestBed.create(target, { metadata }) requires options with the generated metadata");
+		if (!AOP_MODES.has(options.aop)) throw new TypeError(`[znight] TestBed.create(): aop must be 'none' or 'real', got ${String(options.aop)}`);
+		this.#options = options;
+		this.#index = new MetadataIndex(options.metadata);
+		this.#mockFn = resolveMockFn(options.mockFn).create;
+		this.#configs = readConfigClasses(options.metadata);
+		this.#configValues = normalizeConfigValues(options.config, this.#index, this.#configs);
+		this.#provided = this.#normalize(options.provide, "provide");
+		this.#overrides = this.#normalize(options.overrides, "overrides");
+	}
+	async build(target) {
+		const token = this.#resolveTarget(target);
+		let definition = this.#index.definition(token);
+		if (this.#overrides.has(token)) {
+			const replacement = this.#overrides.get(token);
+			if (!isProviderDefinition(replacement)) throw new ZnightError(ErrorCode.InvalidDecorator, `overrides: the target ${displayName(token)} can only be replaced by a provider definition { scope, deps, factory }`);
+			definition = replacement;
+		}
+		const instance = await this.#construct(token, definition, [token]);
+		const container = await this.#createContainer(token, definition, instance);
+		const others = new Map(this.#kinds);
+		return {
+			instance,
+			mocks: new TestMocks(this.#mocks, others, this.#index, token),
+			container
+		};
+	}
+	#resolveTarget(target) {
+		const token = this.#index.find(target, new Set(this.#index.providerTokens()));
+		if (token !== void 0) return token;
+		throw new ZnightError(ErrorCode.MissingProvider, `TestBed: ${describeKey(target)} is not a provider of the metadata`, { hints: ["Check that the class is decorated (@Injectable(), @Controller()...) and exported", "Regenerate the metadata before running tests: `znight generate`, the Bun preload `@znight/compiler/bun` or the Vite plugin"] });
+	}
+	/** Every token a `provide`/`overrides` key may designate (canonical). */
+	#knownTokens() {
+		if (this.#known !== void 0) return this.#known;
+		const index = this.#index;
+		const known = /* @__PURE__ */ new Set();
+		const add = (token) => {
+			if (typeof token === "string") known.add(index.canonical(token));
+		};
+		for (const token of index.providerTokens()) {
+			known.add(token);
+			for (const ref of index.definition(token).deps) for (const dep of tokensOfRef(ref)) add(dep);
+		}
+		for (const external of index.metadata.externals ?? []) add(external?.token);
+		for (const [alias] of index.aliases()) add(alias);
+		this.#known = known;
+		return known;
+	}
+	#normalize(values, option) {
+		const result = /* @__PURE__ */ new Map();
+		if (values === void 0) return result;
+		const known = this.#knownTokens();
+		for (const [key, value] of entriesOf(values)) {
+			const token = this.#index.find(key, known);
+			if (token === void 0) throw new ZnightError(ErrorCode.MissingProvider, `${option}: ${describeKey(key)} matches no provider, external or dependency of the metadata`, { hints: ["Use a class, a token, an alias or a unique display name (e.g. \"UserRepository\")"] });
+			if (result.has(token)) throw new ZnightError(ErrorCode.DuplicateProvider, `${option}: several values for ${describeToken(token)}`);
+			result.set(token, value);
+		}
+		return result;
+	}
+	#isExplicit(token) {
+		const canonical = this.#index.canonical(token);
+		return this.#overrides.has(canonical) || this.#provided.has(canonical);
+	}
+	async #construct(token, definition, path) {
+		if (this.#building.has(token)) throw new ZnightError(ErrorCode.CircularDependency, `Circular dependency: ${formatPath([...path])}`);
+		this.#building.add(token);
+		try {
+			const interceptorDeps = interceptorIndices(definition);
+			const deps = new Array(definition.deps.length);
+			for (let index = 0; index < definition.deps.length; index++) {
+				const ref = definition.deps[index];
+				if (!interceptorDeps.has(index)) deps[index] = await this.#resolve(ref, path);
+				else if (this.#options.aop === "real") deps[index] = await this.#interceptor(ref, path);
+				else for (const dep of tokensOfRef(ref)) this.#record(this.#index.canonical(dep), "interceptor");
+			}
+			let instance;
+			try {
+				instance = definition.factory(deps);
+				if (isThenable(instance)) instance = await instance;
+			} catch (error) {
+				throw new InstantiationError(token, path, error, definition.source);
+			}
+			if (this.#options.aop === "real" && definition.interceptors !== void 0) try {
+				applyInterceptors(instance, definition.interceptors, deps, displayName(token));
+			} catch (error) {
+				throw new InstantiationError(token, path, error, definition.source);
+			}
+			return instance;
+		} finally {
+			this.#building.delete(token);
+		}
+	}
+	async #resolve(ref, path) {
+		if (typeof ref === "string") return this.#value(ref, path);
+		if (ref !== null && typeof ref === "object") {
+			if ("multi" in ref && Array.isArray(ref.multi)) {
+				const values = [];
+				for (const token of ref.multi) if (this.#isExplicit(token)) values.push(await this.#value(token, path));
+				return values;
+			}
+			if ("lazy" in ref && typeof ref.lazy === "string") {
+				const value = await this.#value(ref.lazy, path);
+				return { get: () => value };
+			}
+			if ("token" in ref && typeof ref.token === "string") {
+				if (this.#isExplicit(ref.token)) return this.#value(ref.token, path);
+				this.#record(this.#index.canonical(ref.token), "optional");
+				return;
+			}
+		}
+		throw new ZnightError(ErrorCode.InvalidDecorator, `Invalid dependency of ${displayName(path[path.length - 1])}: ${safeJson(ref)}`, { hints: ["Expected a token, { token, optional: true }, { multi: [...] } or { lazy: token }"] });
+	}
+	/** The value injected for `token` (cached: the same dependency always gets the same value). */
+	async #value(token, path) {
+		const canonical = this.#index.canonical(token);
+		if (this.#values.has(canonical)) return this.#values.get(canonical);
+		let value;
+		if (this.#overrides.has(canonical)) {
+			value = await this.#explicit(canonical, this.#overrides.get(canonical), path);
+			this.#record(canonical, "override");
+		} else if (this.#provided.has(canonical)) {
+			value = this.#provided.get(canonical);
+			this.#record(canonical, "provided");
+		} else if (this.#configs.has(canonical)) {
+			value = buildConfigInstance(this.#configs.get(canonical), this.#index.classOf(canonical), this.#configValues.get(canonical));
+			this.#record(canonical, "config");
+		} else value = this.#autoMock(canonical, path);
+		this.#values.set(canonical, value);
+		return value;
+	}
+	/** An override (a value, or a definition built with its dependencies resolved like the target's). */
+	#explicit(token, value, path) {
+		return isProviderDefinition(value) ? this.#construct(token, value, [...path, token]) : value;
+	}
+	#autoMock(token, path) {
+		const definition = this.#index.definition(token);
+		if (definition !== void 0 && definition.class === void 0 && definition.name !== void 0) throw qualifiedValueError(token, definition.name, path);
+		const mock = mockObject(definition?.class, void 0, {
+			name: displayName(token),
+			deep: this.#options.deep === true,
+			mockFn: this.#mockFn
+		});
+		this.#mocks.set(token, mock);
+		this.#kinds.delete(token);
+		return mock;
+	}
+	/** A real interceptor (aop: 'real'): explicit value, or built from its compiled definition. */
+	async #interceptor(ref, path) {
+		if (typeof ref !== "string") return this.#resolve(ref, path);
+		const token = this.#index.canonical(ref);
+		if (this.#interceptors.has(token)) return this.#interceptors.get(token);
+		let value;
+		if (this.#overrides.has(token)) {
+			value = await this.#explicit(token, this.#overrides.get(token), path);
+			this.#record(token, "override");
+		} else if (this.#provided.has(token)) {
+			value = this.#provided.get(token);
+			this.#record(token, "provided");
+		} else {
+			const definition = this.#index.definition(token);
+			if (definition === void 0) {
+				const providedBy = this.#index.external(token)?.providedBy;
+				throw new ZnightError(ErrorCode.MissingProvider, `aop: 'real' needs the interceptor ${describeToken(token)}, supplied at runtime by ${providedBy ?? "a plugin"}`, { hints: [`Pass an instance: provide: [[${JSON.stringify(token)}, interceptor]]`] });
+			}
+			value = await this.#construct(token, definition, [...path, token]);
+			this.#record(token, "real");
+		}
+		this.#interceptors.set(token, value);
+		return value;
+	}
+	#record(token, kind) {
+		if (!this.#mocks.has(token)) this.#kinds.set(token, kind);
+	}
+	async #createContainer(target, definition, instance) {
+		const bound = /* @__PURE__ */ new Map([[target, instance]]);
+		for (const [token, value] of this.#values) if (value !== void 0 && !bound.has(token)) bound.set(token, value);
+		for (const [token, value] of this.#interceptors) if (value !== void 0 && !bound.has(token)) bound.set(token, value);
+		const providers = [...bound.keys()].map((token) => {
+			const cls = token === target ? definition.class ?? this.#index.classOf(token) : this.#index.classOf(token);
+			return [token, {
+				scope: "singleton",
+				deps: [],
+				factory: () => void 0,
+				...cls === void 0 ? {} : { class: cls }
+			}];
+		});
+		const aliases = [];
+		for (const [alias] of this.#index.aliases()) {
+			const canonical = this.#index.canonical(alias);
+			if (bound.has(canonical) && !bound.has(alias)) aliases.push([alias, canonical]);
+		}
+		const metadata = {
+			version: METADATA_VERSION,
+			providers: Object.fromEntries(providers),
+			resolutionOrder: [...bound.keys()],
+			aliases: Object.fromEntries(aliases)
+		};
+		const container = Container.create(metadata);
+		for (const [token, value] of bound) container.provide(token, value);
+		await container.init();
+		return container;
+	}
+};
+/** Indices of `definition.deps` used only by interceptor chains. */
+function interceptorIndices(definition) {
+	const indices = /* @__PURE__ */ new Set();
+	for (const interception of Object.values(definition.interceptors ?? {})) for (const binding of interception.chain) indices.add(binding.dep);
+	return indices;
+}
+function tokensOfRef(ref) {
+	if (typeof ref === "string") return [ref];
+	if (ref === null || typeof ref !== "object") return [];
+	if ("multi" in ref && Array.isArray(ref.multi)) return ref.multi;
+	if ("lazy" in ref && typeof ref.lazy === "string") return [ref.lazy];
+	if ("token" in ref && typeof ref.token === "string") return [ref.token];
+	return [];
+}
+function qualifiedValueError(token, name, path) {
+	const owner = displayName(path[path.length - 1]);
+	const key = displayName(token);
+	return new ZnightError(ErrorCode.MissingProvider, `TestBed cannot auto-mock ${describeToken(token)}, the value named "${name}" injected into ${owner}: qualified values may be primitives, provide one`, { hints: [`TestBed.create(${owner}, { metadata, provide: { ${JSON.stringify(key)}: value } })`] });
+}
+function safeJson(value) {
+	try {
+		return JSON.stringify(value) ?? String(value);
+	} catch {
+		return String(value);
+	}
+}
+// src/testbed.ts
+/**
+* Unit-test harness: builds one provider with its real factory and auto-mocks its **direct**
+* dependencies, by kind:
+*
+* | Dependency                                   | Injected                                            |
+* | -------------------------------------------- | --------------------------------------------------- |
+* | class / interface / `@Provides` / external   | deep auto-mock                                      |
+* | configuration class (`@Config`)              | real instance: defaults + `config` values           |
+* | qualified value (`@Inject('x')`, primitives) | the `provide` value (an error otherwise)            |
+* | optional (`@Optional()`, `T \| undefined`)   | `undefined` (or the `provide` value)                |
+* | multi (`T[]`)                                | `[]` (or the provided members)                      |
+* | `Lazy<T>`                                    | `{ get: () => mock }`                               |
+* | interceptor (`@Intercept`)                   | nothing, not applied (unless `aop: 'real'`)         |
+*
+* ```ts
+* const { instance, mocks } = await TestBed.create(UserService, { metadata: __ZNIGHT_METADATA__ })
+* mocks.get(UserRepository).findById.mockResolvedValue({ id: '1' })
+* await instance.findById('1')
+* expect(mocks.get(UserRepository).findById).toHaveBeenCalledWith('1')
+* ```
+*/
+var TestBed = class {
+	constructor() {}
+	static create(target, options) {
+		try {
+			return new Builder(options).build(target);
+		} catch (error) {
+			return Promise.reject(error);
+		}
+	}
+};
+export { HTTP_PLUGIN_NAME, TestApp, TestBed, clearMock, createMetadata, createMock, createSpy, defineTestMetadata, detectMockFn, isBuiltinSpy, isMock, override, overrideFactory, resetMock, resolveMockFn, setDefaultMockFn, testToken };
+
+//# sourceMappingURL=index.mjs.map