@znight/http 0.0.0-stage → 0.1.1

package/dist/compiler.mjs

@@ -0,0 +1,2180 @@
+import { a as isMediaTypePattern, n as parseByteSize } from "./size-D8rsQcV0.mjs";
+import { checkRoutePath, compareStrings, joinPaths, normalizePath, parseRoutePath } from "./path.mjs";
+// src/compiler/ast.ts
+/** `true` for an object shaped like an AST node. */
+function isNode(value) {
+	return typeof value === "object" && value !== null && typeof value.type === "string" && typeof value.start === "number";
+}
+/** The child node stored under `key`, when it is a node. */
+function child(node, key) {
+	const value = node[key];
+	return isNode(value) ? value : void 0;
+}
+/** The child nodes stored under `key`, when it is an array. */
+function children(node, key) {
+	const value = node[key];
+	return Array.isArray(value) ? value.filter(isNode) : [];
+}
+const WRAPPERS = /* @__PURE__ */ new Set([
+	"ParenthesizedExpression",
+	"TSAsExpression",
+	"TSSatisfiesExpression",
+	"TSNonNullExpression",
+	"TSTypeAssertion",
+	"TSInstantiationExpression"
+]);
+/** Removes parentheses and type-only wrappers (`x as T`, `x satisfies T`, `x!`, `<T>x`). */
+function unwrap(node) {
+	let current = node;
+	while (WRAPPERS.has(current.type)) {
+		const inner = child(current, "expression");
+		if (!inner) return current;
+		current = inner;
+	}
+	return current;
+}
+/**
+* The default value expression of a method parameter (`page = 1` → `1`), found in the class
+* declaration by the location of the method key.
+*/
+function defaultValueOf(cls, method, param) {
+	const classNode = cls.declaration.node;
+	if (!isNode(classNode)) return;
+	const body = child(classNode, "body");
+	if (!body) return;
+	for (const member of children(body, "body")) {
+		const key = child(member, "key");
+		if (!key || key.start !== method.location.start) continue;
+		const fn = child(member, "value");
+		if (!fn) return;
+		let pattern = children(fn, "params").filter((node) => !(node.type === "Identifier" && node["name"] === "this"))[param.index];
+		if (pattern?.type === "TSParameterProperty") pattern = child(pattern, "parameter");
+		return pattern?.type === "AssignmentPattern" ? child(pattern, "right") : void 0;
+	}
+}
+// src/compiler/coercion.ts
+const DATE_IDENTITY = "globalThis#Date";
+const STRING = {
+	kind: "primitive",
+	name: "string"
+};
+const NUMBER = {
+	kind: "primitive",
+	name: "number"
+};
+const BOOLEAN = {
+	kind: "primitive",
+	name: "boolean"
+};
+const BIGINT = {
+	kind: "primitive",
+	name: "bigint"
+};
+const DATE = {
+	kind: "reference",
+	identity: DATE_IDENTITY,
+	name: "Date",
+	typeArgs: []
+};
+/** Annotated or inferred type of a parameter. */
+function parameterType(ctx, cls, method, param) {
+	let type = param.type;
+	if (param.type.kind === "opaque" && param.type.reason === "missing-annotation") type = param.hasDefault ? inferFromDefault(ctx, cls, method, param) : void 0;
+	const nullish = type !== void 0 && hasNullish(type);
+	return {
+		type,
+		optional: param.optional || param.hasDefault || nullish
+	};
+}
+/**
+* Plans the coercion of a raw value to `type`. `required` is set for route parameters, which are
+* always present (no `coerce.optional`).
+*/
+function planCoercion(ctx, declared, param, required) {
+	const type = declared.type;
+	if (type === void 0) return {
+		ok: false,
+		reason: `the type of parameter '${param.name}' is unknown`,
+		hints: [`Annotate the parameter: ${param.name}: string`]
+	};
+	const { type: base } = ctx.types.stripNullish(type);
+	if (isRaw(base)) return {
+		ok: true,
+		coercion: {
+			plan: { kind: "raw" },
+			cast: false
+		}
+	};
+	const scalar = scalarPlan(ctx, base);
+	let plan;
+	let cast;
+	if ("reason" in scalar) {
+		if (base.kind !== "array") return failure(ctx, type, scalar.reason);
+		const item = scalarPlan(ctx, base.element);
+		if ("reason" in item) return failure(ctx, type, item.reason);
+		plan = {
+			kind: "array",
+			item: item.plan
+		};
+		cast = item.cast;
+	} else {
+		plan = scalar.plan;
+		cast = scalar.cast;
+	}
+	if (!required && declared.optional) {
+		plan = {
+			kind: "optional",
+			item: plan
+		};
+		cast ||= !(param.optional || param.hasDefault || acceptsUndefined(type));
+	}
+	return {
+		ok: true,
+		coercion: {
+			plan,
+			cast
+		}
+	};
+}
+/** `unknown` and `any`: the raw value is passed as is. */
+function isRaw(type) {
+	return type.kind === "primitive" && (type.name === "unknown" || type.name === "any");
+}
+function scalarPlan(ctx, type) {
+	switch (type.kind) {
+		case "primitive": {
+			const kind = primitiveCoercion(type.name);
+			return kind ? {
+				plan: { kind },
+				cast: false
+			} : { reason: `'${type.name}' values cannot be read from a request` };
+		}
+		case "literal": return typeof type.value === "bigint" ? { reason: "bigint literal types are not supported" } : {
+			plan: {
+				kind: "enum",
+				values: [type.value]
+			},
+			cast: false
+		};
+		case "union": {
+			const values = [];
+			for (const member of type.types) if (member.kind === "literal" && typeof member.value !== "bigint") values.push(member.value);
+			else if (member.kind === "primitive" && member.name === "boolean") values.push(false, true);
+			else return { reason: "only unions of literal types can be coerced" };
+			return {
+				plan: {
+					kind: "enum",
+					values
+				},
+				cast: false
+			};
+		}
+		case "reference": {
+			if (type.identity === DATE_IDENTITY) return {
+				plan: { kind: "date" },
+				cast: false
+			};
+			const values = enumValues(ctx, type.identity);
+			if (values) return values.length === 0 ? { reason: `the enum ${type.name} has no member` } : {
+				plan: {
+					kind: "enum",
+					values
+				},
+				cast: true
+			};
+			return { reason: "objects cannot be read from a single request value" };
+		}
+		case "intersection": {
+			const primitives = type.types.filter((member) => member.kind === "primitive" || member.kind === "literal");
+			const [primitive] = primitives;
+			if (primitives.length === 1 && primitive !== void 0) {
+				const inner = scalarPlan(ctx, primitive);
+				return "reason" in inner ? inner : {
+					plan: inner.plan,
+					cast: true
+				};
+			}
+			return { reason: "only branded primitives (`string & { ... }`) can be coerced" };
+		}
+		case "array": return { reason: "nested arrays cannot be coerced" };
+		default: return { reason: "this type cannot be read from a request value" };
+	}
+}
+function primitiveCoercion(name) {
+	switch (name) {
+		case "string":
+		case "number":
+		case "boolean":
+		case "bigint": return name;
+		default: return;
+	}
+}
+function failure(ctx, type, reason) {
+	return {
+		ok: false,
+		reason: `type '${ctx.types.format(type)}' cannot be coerced (${reason})`,
+		hints: ["Supported types: string, number, boolean, bigint, Date, literal unions, enums, branded primitives and arrays of them", "Or validate the value with a Standard Schema"]
+	};
+}
+/** Member values of a TypeScript enum, `undefined` when `identity` is not an evaluable enum. */
+function enumValues(ctx, identity) {
+	const symbol = ctx.project.lookupIdentity(identity);
+	if (symbol.kind !== "declaration" || symbol.declaration.kind !== "enum") return;
+	const declaration = symbol.declaration;
+	const node = declaration.node;
+	const id = isNode(node) ? child(node, "id") : void 0;
+	const file = ctx.project.getFile(declaration.file);
+	if (!id || !file) return;
+	const scope = {
+		file,
+		namespace: declaration.namespace
+	};
+	const result = ctx.project.evaluate(scope, id, { refs: "none" });
+	if (result.kind !== "value" || typeof result.value !== "object" || result.value === null) return;
+	return Object.values(result.value).filter((value) => typeof value === "string" || typeof value === "number");
+}
+function inferFromDefault(ctx, cls, method, param) {
+	const node = defaultValueOf(cls, method, param);
+	if (!node) return;
+	const inner = unwrap(node);
+	if (inner.type === "NewExpression") {
+		const callee = child(inner, "callee");
+		if (callee?.type === "Identifier") return ctx.project.resolveIdentifier(cls.file, callee, "value").identity?.identity === DATE_IDENTITY ? DATE : void 0;
+		return;
+	}
+	const result = ctx.project.evaluate(cls.file, node, { refs: "none" });
+	return result.kind === "value" ? typeOfValue(result.value) : void 0;
+}
+function typeOfValue(value) {
+	switch (typeof value) {
+		case "string": return STRING;
+		case "number": return NUMBER;
+		case "boolean": return BOOLEAN;
+		case "bigint": return BIGINT;
+		default: {
+			if (!Array.isArray(value) || value.length === 0) return;
+			const items = value.map(typeOfValue);
+			const [first] = items;
+			if (first === void 0 || first.kind !== "primitive" || items.some((item) => item !== first)) return;
+			return {
+				kind: "array",
+				element: first
+			};
+		}
+	}
+}
+function hasNullish(type) {
+	return type.kind === "union" && type.types.some(isNullish);
+}
+/** Whether a union accepts `undefined` (`T | undefined`, `T | void`). */
+function acceptsUndefined(type) {
+	return type.kind === "union" && type.types.some((member) => member.kind === "primitive" && (member.name === "undefined" || member.name === "void"));
+}
+function isNullish(type) {
+	return type.kind === "primitive" && (type.name === "undefined" || type.name === "null" || type.name === "void");
+}
+// src/compiler/model.ts
+/** Package name (prefix of every decorator identity). */
+const HTTP_PACKAGE = "@znight/http";
+/** Canonical identities of the decorators of `@znight/http`. */
+const Ids = Object.freeze({
+	Controller: "@znight/http#Controller",
+	Param: "@znight/http#Param",
+	Query: "@znight/http#Query",
+	Body: "@znight/http#Body",
+	Headers: "@znight/http#Headers",
+	Req: "@znight/http#Req",
+	Res: "@znight/http#Res",
+	Ctx: "@znight/http#Ctx",
+	HttpCode: "@znight/http#HttpCode",
+	Header: "@znight/http#Header",
+	UseGuard: "@znight/http#UseGuard",
+	UseInterceptor: "@znight/http#UseInterceptor",
+	Validate: "@znight/http#Validate",
+	UploadedFile: "@znight/http#UploadedFile",
+	UploadedFiles: "@znight/http#UploadedFiles",
+	BodyLimit: "@znight/http#BodyLimit",
+	Cookie: "@znight/http#Cookie",
+	SignedCookie: "@znight/http#SignedCookie",
+	Sse: "@znight/http#Sse",
+	createRouteDecorator: "@znight/http#createRouteDecorator",
+	RouteDecorator: "@znight/http#RouteDecorator"
+});
+/** Route method decorators → HTTP method (`@Sse` declares a `GET` route). */
+const ROUTE_METHODS = /* @__PURE__ */ new Map([
+	["@znight/http#Get", "GET"],
+	["@znight/http#Post", "POST"],
+	["@znight/http#Put", "PUT"],
+	["@znight/http#Patch", "PATCH"],
+	["@znight/http#Delete", "DELETE"],
+	["@znight/http#Head", "HEAD"],
+	["@znight/http#Options", "OPTIONS"],
+	["@znight/http#All", "ALL"],
+	["@znight/http#Sse", "GET"]
+]);
+/** Parameter decorators → parameter source. */
+const PARAM_SOURCES = /* @__PURE__ */ new Map([
+	[Ids.Param, "param"],
+	[Ids.Query, "query"],
+	[Ids.Body, "body"],
+	[Ids.Headers, "headers"],
+	[Ids.Req, "request"],
+	[Ids.Res, "response"],
+	[Ids.Ctx, "context"],
+	[Ids.UploadedFile, "file"],
+	[Ids.UploadedFiles, "files"],
+	[Ids.Cookie, "cookie"],
+	[Ids.SignedCookie, "signedCookie"]
+]);
+/** Error codes used by the extension (see `ErrorCode` in `@znight/core`). */
+const Codes = Object.freeze({
+	MissingProvider: "ZNIGHT001",
+	InvalidDecorator: "ZNIGHT005",
+	InvalidRoute: "ZNIGHT007",
+	UnvalidatedInput: "ZNIGHT017",
+	MissingRouteDecision: "ZNIGHT023"
+});
+/**
+* Grammar of an explicit route decorator group name (same as the runtime `createRouteDecorator`).
+* A decorator without `group` is its own group, named after its key (any non-empty key).
+*/
+const GROUP_NAME = /^[A-Za-z][\w.-]*$/;
+// src/compiler/route-decorators.ts
+const OTHER = Object.freeze({ kind: "other" });
+/** Resolutions per analysis context (one context per compile). */
+const caches = /* @__PURE__ */ new WeakMap();
+/** Resolves a decorator identity to a route decorator definition (memoized per compile). */
+function resolveRouteDecorator(ctx, identity) {
+	let cache = caches.get(ctx);
+	if (!cache) {
+		cache = /* @__PURE__ */ new Map();
+		caches.set(ctx, cache);
+	}
+	let resolution = cache.get(identity);
+	if (!resolution) {
+		resolution = resolve(ctx, identity);
+		cache.set(identity, resolution);
+	}
+	return resolution;
+}
+function resolve(ctx, identity) {
+	if (identity.startsWith("globalThis#")) return OTHER;
+	const symbol = ctx.project.lookupIdentity(identity);
+	if (symbol.kind !== "declaration") return OTHER;
+	const declaration = symbol.declarations.find((candidate) => candidate.kind === "const");
+	const node = declaration?.node;
+	const file = declaration ? ctx.project.getFile(declaration.file) : void 0;
+	if (!declaration || !isNode(node) || !file) return OTHER;
+	const scope = {
+		file,
+		namespace: declaration.namespace
+	};
+	const init = child(node, "init");
+	if (!init) {
+		const annotation = child(child(node, "id") ?? node, "typeAnnotation");
+		const type = annotation ? ctx.project.resolveType(scope, annotation) : void 0;
+		if (type?.kind === "reference" && type.identity === Ids.RouteDecorator) return {
+			kind: "invalid",
+			message: `the key of the route decorator ${declaration.name} cannot be read: it is declared without initializer`,
+			hints: ["Route decorators must be declared in analysed sources: `export const X = createRouteDecorator(key)`", "For a provider library, publish its sources (\"znight\": { \"library\": \"source\" })"]
+		};
+		return OTHER;
+	}
+	const call = unwrap(init);
+	const callee = call.type === "CallExpression" ? child(call, "callee") : void 0;
+	if (!callee || !isEntityName(unwrap(callee))) return OTHER;
+	if (ctx.project.resolveIdentifier(scope, unwrap(callee), "value").identity?.identity !== Ids.createRouteDecorator) return OTHER;
+	const definition = file.location(declaration.span);
+	const [keyNode, optionsNode, ...extra] = children(call, "arguments");
+	if (!keyNode || keyNode.type === "SpreadElement") return {
+		kind: "invalid",
+		message: `createRouteDecorator() requires a key (${declaration.name})`,
+		hints: [`export const ${declaration.name} = createRouteDecorator('${declaration.name.toLowerCase()}')`],
+		definition
+	};
+	const key = ctx.project.evaluate(scope, keyNode, { refs: "none" });
+	if (key.kind !== "value" || typeof key.value !== "string" || key.value === "") return {
+		kind: "invalid",
+		message: `the key of the route decorator ${declaration.name} must be a statically evaluable non-empty string`,
+		hints: ["Use a string literal or a `const` string: createRouteDecorator('roles')"],
+		definition
+	};
+	const optionsHints = [`export const ${declaration.name} = createRouteDecorator('${key.value}', { group: 'access', required: true })`];
+	if (extra.length > 0 || optionsNode?.type === "SpreadElement") return {
+		kind: "invalid",
+		message: `createRouteDecorator() takes a key and an optional { group?, required? } object (${declaration.name})`,
+		hints: optionsHints,
+		definition
+	};
+	let options;
+	if (optionsNode !== void 0) {
+		const evaluated = ctx.project.evaluate(scope, optionsNode, { refs: "none" });
+		if (evaluated.kind !== "value") return {
+			kind: "invalid",
+			message: `the options of the route decorator ${declaration.name} must be statically evaluable (literals and \`const\` references)`,
+			hints: optionsHints,
+			definition
+		};
+		options = evaluated.value;
+	}
+	const parsed = parseRouteDecoratorOptions(key.value, options);
+	if ("error" in parsed) return {
+		kind: "invalid",
+		message: `the options of the route decorator ${declaration.name} ${parsed.error}`,
+		hints: optionsHints,
+		definition
+	};
+	return {
+		kind: "route",
+		key: key.value,
+		...parsed,
+		name: declaration.name,
+		definition
+	};
+}
+/**
+* The group and `required` of a route decorator from its evaluated options (`undefined`: the
+* defaults), or why the options are invalid.
+*/
+function parseRouteDecoratorOptions(key, options) {
+	if (options === void 0) return {
+		group: key,
+		required: false
+	};
+	if (!isPlainObject$1(options)) return { error: "must be an object { group?, required? }" };
+	const unknown = Object.keys(options).find((name) => name !== "group" && name !== "required");
+	if (unknown !== void 0) return { error: `have an unknown property "${unknown}" (expected group and required)` };
+	const group = options["group"] ?? key;
+	if (typeof group !== "string" || group !== key && !GROUP_NAME.test(group)) return { error: `have an invalid group ${typeof group === "object" && group !== null ? "a reference" : JSON.stringify(group)}: a letter followed by letters, digits, _ . or -` };
+	const required = options["required"] ?? false;
+	if (typeof required !== "boolean") return { error: "have a non-boolean \"required\"" };
+	return {
+		group,
+		required
+	};
+}
+function isPlainObject$1(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+function isEntityName(node) {
+	if (node.type === "Identifier") return true;
+	if (node.type === "MemberExpression" && node["computed"] !== true) {
+		const object = child(node, "object");
+		return child(node, "property")?.type === "Identifier" && object !== void 0 && isEntityName(object);
+	}
+	return false;
+}
+/**
+* Metadata entries of the route decorators applied to a class or a method (source order).
+* `target` names the class or the handler (`BookController`, `BookController.remove`). Problems are
+* reported as ZNIGHT005: two decisions of one group on the same target included.
+*/
+function routeMeta(ctx, cls, decorators, target) {
+	const entries = [];
+	for (const decorator of decorators) {
+		if (decorator.owner !== void 0 || decorator.identity === void 0) continue;
+		const resolution = resolveRouteDecorator(ctx, decorator.identity);
+		if (resolution.kind === "other") continue;
+		if (resolution.kind === "invalid") {
+			report(ctx, decorator, `Invalid route decorator @${decorator.name}: ${resolution.message}`, resolution.hints, resolution.definition === void 0 ? void 0 : {
+				message: "The route decorator is defined here",
+				location: resolution.definition
+			});
+			continue;
+		}
+		const value = metaValue(ctx, cls, decorator);
+		if (value === INVALID) continue;
+		const previous = entries.find((entry) => entry.group === resolution.group);
+		if (previous) {
+			if (previous.key === resolution.key && resolution.group === resolution.key) report(ctx, decorator, `@${decorator.name} sets the route metadata '${resolution.key}', already set on the same target`, ["Apply each route decorator once per controller or route"], {
+				message: "First applied here",
+				location: previous.location
+			});
+			else {
+				const alternatives = previous.decorator === resolution.name ? `@${resolution.name} once` : `one of @${previous.decorator}, @${resolution.name}`;
+				report(ctx, decorator, `@${resolution.name} sets the "${resolution.group}" decision of ${target}, already set by @${previous.decorator} on the same target`, [`Keep ${alternatives}: the decorators of the "${resolution.group}" group are alternatives`], {
+					message: "First applied here",
+					location: previous.location
+				});
+			}
+			continue;
+		}
+		entries.push({
+			key: resolution.key,
+			value,
+			location: decorator.location,
+			group: resolution.group,
+			required: resolution.required,
+			decorator: resolution.name,
+			identity: decorator.identity,
+			definition: resolution.definition
+		});
+	}
+	return entries;
+}
+/** `true` when the decorator is a route metadata decorator. */
+function isRouteMetaDecorator(ctx, decorator) {
+	return decorator.owner === void 0 && decorator.identity !== void 0 && resolveRouteDecorator(ctx, decorator.identity).kind !== "other";
+}
+const INVALID = Symbol("invalid");
+function metaValue(ctx, cls, decorator) {
+	if (!decorator.called) {
+		report(ctx, decorator, `@${decorator.name} must be called: @${decorator.name}()`, [`Write @${decorator.name}(${decorator.args.length > 0 ? "..." : ""})`]);
+		return INVALID;
+	}
+	const [arg, ...extra] = decorator.args;
+	if (arg === void 0) return true;
+	if (extra.length > 0) {
+		report(ctx, decorator, `@${decorator.name} takes at most one argument`, ["Pass a single value (an array or an object)"]);
+		return INVALID;
+	}
+	if (arg.text.startsWith("...")) {
+		report(ctx, decorator, `@${decorator.name} does not accept spread arguments`, ["Pass the value directly"]);
+		return INVALID;
+	}
+	const evaluation = ctx.project.evaluate(cls.file, arg.node, { refs: "nested" });
+	switch (evaluation.kind) {
+		case "value": return checkRefs(ctx, decorator, evaluation.value) ? evaluation.value : INVALID;
+		case "ref": return checkRefs(ctx, decorator, evaluation.ref) ? evaluation.ref : INVALID;
+		case "error":
+			ctx.report({
+				code: Codes.InvalidDecorator,
+				severity: "error",
+				message: `Invalid argument of @${decorator.name}: ${evaluation.error.message}`,
+				location: evaluation.error.location,
+				hints: [evaluation.error.hint ?? "Extract the value to `export const X = ...` and reference it"]
+			});
+			return INVALID;
+	}
+}
+/** Checks that every reference of a value can be imported by the generated module. */
+function checkRefs(ctx, decorator, value) {
+	let ok = true;
+	const visit = (current) => {
+		if (isValueRef(current)) {
+			const route = ctx.project.importRoute(current.symbol);
+			if (!route.ok) {
+				ok = false;
+				ctx.report({
+					code: Codes.InvalidDecorator,
+					severity: "error",
+					message: `Invalid argument of @${decorator.name}: '${current.text}' cannot be imported by the generated module (${route.error.message})`,
+					location: current.location,
+					hints: route.error.hints.length > 0 ? [...route.error.hints] : ["Export it from its module"]
+				});
+			}
+			return;
+		}
+		if (Array.isArray(current)) for (const item of current) visit(item);
+		else if (typeof current === "object" && current !== null) for (const item of Object.values(current)) visit(item);
+	};
+	visit(value);
+	return ok;
+}
+/** `true` for a {@link ValueRef} (the only non-plain object a static value can hold). */
+function isValueRef(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype !== Object.prototype && prototype !== null && value.kind === "ref";
+}
+function report(ctx, decorator, message, hints, related) {
+	ctx.report({
+		code: Codes.InvalidDecorator,
+		severity: "error",
+		message,
+		location: decorator.location,
+		hints,
+		...related?.location ? { related: [{
+			message: related.message,
+			location: related.location
+		}] } : {}
+	});
+}
+// src/compiler/analyze.ts
+/** Name of the extension (owner of the decorators in `DecoratorInfo.owner`). */
+const EXTENSION_NAME = "http";
+const SCOPES = [
+	"singleton",
+	"request",
+	"transient"
+];
+/** RFC 9110 token (header names). */
+const TOKEN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Types an upload parameter may have (`File`, `Blob`, arrays of them for `@UploadedFiles`); `true`: cast needed. */
+const FILE_TYPES = /* @__PURE__ */ new Map([
+	["globalThis#File", false],
+	["globalThis#Blob", false],
+	["node:buffer#File", true],
+	["node:buffer#Blob", true]
+]);
+/** Methods whose requests usually have no body (upload parameters there are a warning). */
+const BODYLESS_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"DELETE",
+	"OPTIONS"
+]);
+const UPLOAD_OPTIONS = [
+	"required",
+	"maxSize",
+	"maxFiles",
+	"mimeTypes"
+];
+/** Smallest `@Sse` heartbeat and `maxDuration` (ms). */
+const MIN_SSE_INTERVAL_MS = 1e3;
+/** Longest `@Sse` heartbeat and `maxDuration` (ms): the longest `setTimeout` delay. */
+const MAX_SSE_TIMER_MS = 2147483647;
+/** Primitive return types an `@Sse` handler cannot return (`any`, `unknown`, `object`, `never` are accepted). */
+const NOT_SSE_SOURCES = /* @__PURE__ */ new Set([
+	"string",
+	"number",
+	"boolean",
+	"bigint",
+	"symbol",
+	"undefined",
+	"null",
+	"void"
+]);
+/** Values that are fine without schema (`@Body() body: string`, `@Body() bytes: Uint8Array`...). */
+const UNVALIDATED_REFERENCES = /* @__PURE__ */ new Set([
+	"globalThis#Uint8Array",
+	"globalThis#ArrayBuffer",
+	"globalThis#Buffer",
+	"globalThis#Blob",
+	"globalThis#FormData",
+	"node:buffer#Buffer",
+	"@znight/http#QueryRecord"
+]);
+/** Analyses a class carrying at least one `@znight/http` decorator. */
+function analyzeHttpClass(cls, ctx) {
+	const controllers = cls.decorators.filter((decorator) => decorator.identity === Ids.Controller);
+	const [controller] = controllers;
+	if (controller === void 0) {
+		reportOutsideController(cls, ctx);
+		return;
+	}
+	for (const duplicate of controllers.slice(1)) error(ctx, duplicate.location, `@Controller is applied several times to ${cls.displayName}`, ["Keep a single @Controller()"]);
+	const options = controllerOptions(ctx, controller);
+	const token = ctx.registerProvider(cls, { scope: options.scope });
+	const basePath = normalizePath(options.path);
+	const guards = classRefs(ctx, cls, cls.decorators, Ids.UseGuard, "guard");
+	const interceptors = classRefs(ctx, cls, cls.decorators, Ids.UseInterceptor, "interceptor");
+	const meta = routeMeta(ctx, cls, cls.decorators, cls.displayName);
+	const bodyLimit = bodyLimitOf(ctx, cls.decorators);
+	const routes = [];
+	for (const method of cls.methods) routes.push(...analyzeMethod(ctx, cls, method, basePath, bodyLimit));
+	ctx.store({
+		token,
+		identity: cls.identity,
+		displayName: cls.displayName,
+		rawBasePath: options.path,
+		basePath,
+		guards,
+		interceptors,
+		meta,
+		routes,
+		location: controller.location,
+		pathLocation: options.pathLocation
+	});
+}
+function controllerOptions(ctx, decorator) {
+	const [arg] = decorator.args;
+	const defaults = {
+		path: "",
+		pathLocation: decorator.location,
+		scope: "singleton"
+	};
+	if (arg === void 0 || !arg.evaluated) return defaults;
+	const value = arg.value;
+	if (typeof value === "string") return {
+		...defaults,
+		path: value,
+		pathLocation: arg.location
+	};
+	if (!isPlainObject(value)) {
+		error(ctx, arg.location, `@Controller expects a path or { path?, scope? }, got ${describe(value)}`, ["@Controller('/users') or @Controller({ path: '/users', scope: 'request' })"]);
+		return defaults;
+	}
+	let { path, scope } = defaults;
+	for (const [key, option] of Object.entries(value)) if (key === "path") {
+		if (typeof option === "string") path = option;
+		else if (option !== void 0) error(ctx, arg.location, `@Controller: "path" must be a string, got ${describe(option)}`);
+	} else if (key === "scope") {
+		if (SCOPES.includes(option)) scope = option;
+		else if (option !== void 0) error(ctx, arg.location, `@Controller: invalid scope ${describe(option)}`, [`Use one of ${SCOPES.map((candidate) => `'${candidate}'`).join(", ")}`]);
+	} else error(ctx, arg.location, `@Controller: unknown option "${key}"`, ["Options: { path?, scope? }"]);
+	return {
+		path,
+		pathLocation: arg.location,
+		scope
+	};
+}
+/**
+* HTTP decorators on a class that is not a controller have no effect. On a class another extension
+* owns (a `@Consumer` of `@znight/messaging`...), adding `@Controller()` is no fix: a class is the
+* provider of a single extension.
+*/
+function reportOutsideController(cls, ctx) {
+	const owner = foreignOwner(cls);
+	const hint = owner === void 0 ? [`Add @Controller() to ${cls.displayName} (routes are not inherited from base classes)`] : [`${cls.displayName} is a @${owner.name} class of '${owner.module}': HTTP decorators only apply to @Controller() classes`];
+	const decorators = [...cls.decorators];
+	for (const method of cls.methods) {
+		decorators.push(...method.decorators);
+		const handler = owner === void 0 ? void 0 : method.decorators.find((decorator) => decorator.owner === owner.decorator.owner);
+		if (owner !== void 0 && handler !== void 0) {
+			reportHandlerParams(ctx, cls, method, owner, handler);
+			continue;
+		}
+		for (const param of method.params) decorators.push(...unique(param.decorators));
+	}
+	for (const decorator of decorators) if (decorator.owner === "http" && validTarget(decorator)) error(ctx, decorator.location, `@${decorator.name} has no effect: ${cls.displayName} is not a controller`, hint);
+}
+/**
+* HTTP decorators on the parameters of a handler of the extension owning the class (an `@OnMessage`
+* handler...). That extension reads its handlers' parameters and reports those it cannot read
+* (`Headers` imported from `@znight/http` instead of `@znight/messaging`...): an HTTP decorator is
+* only reported here when the parameter is read through a decorator of that extension, or is
+* optional (left undefined without a word).
+*/
+function reportHandlerParams(ctx, cls, method, owner, handler) {
+	for (const param of method.params) {
+		if (!param.decorators.some((decorator) => decorator.owner === owner.decorator.owner) && !param.optional && !param.hasDefault && !param.rest) continue;
+		for (const decorator of unique(param.decorators)) if (decorator.owner === "http" && validTarget(decorator)) error(ctx, decorator.location, `@${decorator.name} has no effect on parameter '${param.name}' of ${cls.displayName}.${method.name}: it is an @${handler.name} handler of '${owner.module}'`, [`Use the parameter decorators of '${owner.module}', or remove it`]);
+	}
+}
+function qualify(decorator) {
+	const identity = decorator.identity;
+	const separator = identity?.lastIndexOf("#") ?? -1;
+	if (identity === void 0 || separator <= 0) return;
+	return {
+		decorator,
+		module: identity.slice(0, separator),
+		name: identity.slice(separator + 1)
+	};
+}
+/** The class decorator through which another extension owns the class (`@Consumer`...). */
+function foreignOwner(cls) {
+	for (const decorator of cls.decorators) {
+		const owner = decorator.owner;
+		if (owner === void 0 || owner === "http" || owner === "core" || owner === "manifest") continue;
+		const qualified = qualify(decorator);
+		if (qualified !== void 0) return qualified;
+	}
+}
+/**
+* A parameter decorator named like an HTTP one but imported from another package (`Headers` and
+* `Ctx` of `@znight/messaging`, typically auto-imported).
+*/
+function foreignParameterDecorator(param) {
+	for (const decorator of unique(param.decorators)) {
+		const qualified = qualify(decorator);
+		if (qualified !== void 0 && qualified.module !== "@znight/http" && PARAM_SOURCES.has(`@znight/http#${qualified.name}`)) return qualified;
+	}
+}
+function analyzeMethod(ctx, cls, method, basePath, controllerBodyLimit) {
+	const where = `${cls.displayName}.${method.name}`;
+	let routeDecorators = method.decorators.filter((decorator) => ROUTE_METHODS.has(decorator.identity ?? ""));
+	if (routeDecorators.length === 0) {
+		reportNotARoute(ctx, method, where);
+		return [];
+	}
+	if (!checkHandler(ctx, method, where, routeDecorators[0])) return [];
+	const sseDecorator = routeDecorators.find((decorator) => decorator.identity === Ids.Sse);
+	if (sseDecorator !== void 0) {
+		for (const other of routeDecorators) {
+			if (other === sseDecorator) continue;
+			error(ctx, other.location, other.identity === Ids.Sse ? `@Sse is applied several times to ${where}` : `@${other.name} cannot be combined with @Sse on ${where}`, ["One handler per event stream: declare other routes on other methods (HttpResponse.sse() serves an event stream from any route)"]);
+		}
+		routeDecorators = [sseDecorator];
+	}
+	const decorators = method.decorators;
+	const bodyValidation = validateSchema(ctx, decorators);
+	const { params, complete } = analyzeParams(ctx, cls, method, where, bodyValidation);
+	let status = httpCode(ctx, decorators);
+	let headers = responseHeaders(ctx, decorators);
+	const guards = classRefs(ctx, cls, decorators, Ids.UseGuard, "guard");
+	const interceptors = classRefs(ctx, cls, decorators, Ids.UseInterceptor, "interceptor");
+	const meta = routeMeta(ctx, cls, decorators, where);
+	const bodySchema = bodyValidation !== void 0 && !params.some((param) => param.source === "body") ? bodyValidation.schema : void 0;
+	let rawResponse = params.some((param) => param.source === "response");
+	const bodyLimit = bodyLimitOf(ctx, decorators) ?? controllerBodyLimit;
+	const uploads = checkUploads(ctx, params, where);
+	if (sseDecorator !== void 0) {
+		checkSseHandler(ctx, method, params, where, bodyValidation);
+		status = void 0;
+		headers = headers.filter(([name]) => name !== "content-type");
+		rawResponse = false;
+	}
+	const routes = [];
+	for (const decorator of routeDecorators) {
+		const httpMethod = ROUTE_METHODS.get(decorator.identity ?? "");
+		const target = decorator === sseDecorator ? sseArgs(ctx, decorator) : routePath(ctx, decorator);
+		if (target === void 0) continue;
+		const { rawPath, arg } = target;
+		const path = normalizePath(rawPath);
+		if (uploads && BODYLESS_METHODS.has(httpMethod)) ctx.report({
+			code: Codes.InvalidDecorator,
+			severity: "warning",
+			message: `${where} reads uploaded files but is a ${httpMethod} route: ${httpMethod} requests usually have no body`,
+			location: decorator.location,
+			hints: ["Upload files with @Post(), @Put() or @Patch()"]
+		});
+		routes.push({
+			method: httpMethod,
+			rawPath,
+			path,
+			fullPath: joinPaths(basePath, path),
+			handler: method.name,
+			status,
+			headers,
+			meta,
+			guards,
+			interceptors,
+			params,
+			complete,
+			bodySchema,
+			bodyLimit,
+			rawResponse,
+			...target.sse === void 0 ? {} : { sse: target.sse },
+			location: decorator.location,
+			pathLocation: arg?.location ?? decorator.location
+		});
+	}
+	return routes;
+}
+/** The path argument of a route decorator (`undefined` after an error). */
+function routePath(ctx, decorator) {
+	const [arg] = decorator.args;
+	if (arg === void 0) return {
+		rawPath: "",
+		arg
+	};
+	if (!arg.evaluated) return;
+	if (typeof arg.value !== "string") {
+		error(ctx, arg.location, `@${decorator.name} expects a path (string), got ${describe(arg.value)}`, [`@${decorator.name}('/:id')`]);
+		return;
+	}
+	return {
+		rawPath: arg.value,
+		arg
+	};
+}
+/** `@Sse(path?, options?)` / `@Sse(options)`: the path and the options (`undefined` after an error). */
+function sseArgs(ctx, decorator) {
+	const [first, second] = decorator.args;
+	let pathArg;
+	let options;
+	if (first !== void 0) {
+		if (!first.evaluated) return;
+		if (typeof first.value === "string") {
+			pathArg = first;
+			options = second;
+		} else if (first.value === void 0) options = second;
+		else if (isPlainObject(first.value)) {
+			if (second !== void 0) {
+				error(ctx, second.location, "@Sse(options) takes a single argument", ["Put the path first: @Sse('/events', { retry: 5000 })"]);
+				return;
+			}
+			options = first;
+		} else {
+			error(ctx, first.location, `@Sse expects a path (string) or options, got ${describe(first.value)}`, ["@Sse('/events'), @Sse('/events', { heartbeat: 15_000 }) or @Sse({ retry: 5000 })"]);
+			return;
+		}
+	}
+	const sse = sseOptions(ctx, options);
+	if (sse === void 0) return;
+	return {
+		rawPath: typeof pathArg?.value === "string" ? pathArg.value : "",
+		arg: pathArg,
+		sse
+	};
+}
+/** The static `{ heartbeat?, retry?, maxDuration? }` of `@Sse` (`undefined` after an error). */
+function sseOptions(ctx, arg) {
+	if (arg === void 0) return {};
+	if (!arg.evaluated) return;
+	const shape = "{ heartbeat?: number | false, retry?: number, maxDuration?: number }";
+	if (arg.value === void 0) return {};
+	if (!isPlainObject(arg.value)) {
+		error(ctx, arg.location, `@Sse options must be an object ${shape}, got ${describe(arg.value)}`);
+		return;
+	}
+	const result = {};
+	let ok = true;
+	const invalid = (message, hints = []) => {
+		ok = false;
+		error(ctx, arg.location, `@Sse: ${message}`, hints);
+	};
+	const integer = (value, min, max = Number.MAX_SAFE_INTEGER) => typeof value === "number" && Number.isSafeInteger(value) && value >= min && value <= max;
+	for (const [key, value] of Object.entries(arg.value)) {
+		if (value === void 0) continue;
+		switch (key) {
+			case "heartbeat":
+				if (value === false) result.heartbeat = 0;
+				else if (integer(value, MIN_SSE_INTERVAL_MS, MAX_SSE_TIMER_MS)) result.heartbeat = value;
+				else invalid(`"heartbeat" must be an integer number of ms from ${MIN_SSE_INTERVAL_MS} to ${MAX_SSE_TIMER_MS}, or false, got ${describe(value)}`, ["Keep it below the idle timeouts of the proxies and of Bun.serve() (10 s): the default is 8 000"]);
+				break;
+			case "retry":
+				if (integer(value, 0)) result.retry = value;
+				else invalid(`"retry" must be an integer number of ms ≥ 0, got ${describe(value)}`);
+				break;
+			case "maxDuration":
+				if (integer(value, MIN_SSE_INTERVAL_MS, MAX_SSE_TIMER_MS)) result.maxDuration = value;
+				else invalid(`"maxDuration" must be an integer number of ms from ${MIN_SSE_INTERVAL_MS} to ${MAX_SSE_TIMER_MS} (about 24.8 days), got ${describe(value)}`);
+				break;
+			default: invalid(`unknown option "${key}"`, [`Options: ${shape}`]);
+		}
+	}
+	return ok ? result : void 0;
+}
+/**
+* `@Sse` handlers: the plugin writes the stream with status 200 and its own content type, so
+* `@HttpCode`, `@Header('content-type')` and `@Res()` are errors; a body is a warning (EventSource
+* sends `GET` without body); a primitive return type is an error.
+*/
+function checkSseHandler(ctx, method, params, where, bodyValidation) {
+	for (const decorator of method.decorators) if (decorator.identity === Ids.HttpCode) error(ctx, decorator.location, `@HttpCode has no effect on @Sse route ${where}: an event stream answers 200`, ["Throw an HttpException or return an HttpResponse from the handler for other statuses"]);
+	else if (decorator.identity === Ids.Header) {
+		const [name] = decorator.args;
+		if (name?.evaluated === true && typeof name.value === "string" && name.value.toLowerCase() === "content-type") error(ctx, decorator.location, `@Header('content-type') has no effect on @Sse route ${where}`, ["An event stream is always sent as text/event-stream; charset=utf-8"]);
+	}
+	for (const param of params) if (param.source === "response") error(ctx, param.location, `@Res() cannot be used on @Sse route ${where}: the plugin writes the event stream`, ["Return an AsyncIterable of SseEvent, or use a plain route to write the response yourself"]);
+	const bodyLocation = params.find((param) => param.source === "body" || param.upload !== void 0)?.location ?? bodyValidation?.decorator.location;
+	if (bodyLocation !== void 0) ctx.report({
+		code: Codes.InvalidDecorator,
+		severity: "warning",
+		message: `@Sse route ${where} reads a request body: EventSource sends GET requests without body`,
+		location: bodyLocation,
+		hints: ["For fetch() clients streaming a POST, use @Post() and return HttpResponse.sse(source)"]
+	});
+	const returned = method.returnType === void 0 ? void 0 : ctx.types.awaited(method.returnType);
+	if (returned !== void 0 && !method.generator) {
+		if ((returned.kind === "union" ? returned.types : [returned]).some((member) => member.kind === "literal" || member.kind === "primitive" && NOT_SSE_SOURCES.has(member.name))) error(ctx, method.location, `@Sse handler ${where} returns ${ctx.types.format(returned)}: return an AsyncIterable, an Iterable or a ReadableStream of SseEvent (or an HttpResponse)`, ["async events(): Promise<AsyncIterable<SseEvent<T>>> { ...; return channel }"]);
+	}
+}
+/** `@BodyLimit(size)` of a class or method, in bytes. */
+function bodyLimitOf(ctx, decorators) {
+	const [decorator, ...duplicates] = decorators.filter((candidate) => candidate.identity === Ids.BodyLimit);
+	for (const duplicate of duplicates) error(ctx, duplicate.location, "@BodyLimit is applied several times", ["Keep a single @BodyLimit(size)"]);
+	if (decorator === void 0) return;
+	const [arg] = decorator.args;
+	if (arg === void 0) {
+		error(ctx, decorator.location, "@BodyLimit requires a size", ["@BodyLimit('10mb') or @BodyLimit(10_485_760)"]);
+		return;
+	}
+	if (!arg.evaluated) return;
+	const size = parseByteSize(arg.value);
+	if (size === void 0) error(ctx, arg.location, `@BodyLimit expects a size in bytes, got ${describe(arg.value)}`, ["A non-negative integer (10_485_760), a size with a unit ('10mb', '512kb'; kb = 1024 bytes) or Infinity"]);
+	return size;
+}
+/**
+* Checks the upload parameters of a handler together (one parameter per field; a parameter without
+* field takes every file and stands alone). Returns whether the handler reads uploaded files.
+*/
+function checkUploads(ctx, params, where) {
+	const uploads = params.filter((param) => param.upload !== void 0);
+	uploads.forEach((param, index) => {
+		const field = param.upload?.field;
+		const previous = uploads.slice(0, index).find((other) => field === void 0 || other.upload?.field === void 0 || other.upload.field === field);
+		if (previous === void 0) return;
+		ctx.report({
+			code: Codes.InvalidDecorator,
+			severity: "error",
+			message: field !== void 0 && previous.upload?.field === field ? `The field "${field}" of ${where} is read by several upload parameters` : `${where}: an upload parameter without field receives every file of the body and cannot be combined with other upload parameters`,
+			location: param.location,
+			hints: ["Give each @UploadedFile / @UploadedFiles parameter its own field"],
+			related: [{
+				message: "Other upload parameter",
+				location: previous.location
+			}]
+		});
+	});
+	return uploads.length > 0;
+}
+/** HTTP method decorators (and parameter decorators) on a method without route decorator. */
+function reportNotARoute(ctx, method, where) {
+	const hint = [`Add a route decorator to ${where}: @Get(), @Post(), @Put(), @Patch(), @Delete()...`];
+	for (const decorator of method.decorators) if (decorator.owner === "http" && validTarget(decorator)) error(ctx, decorator.location, `@${decorator.name} has no effect: ${where} is not a route`, hint);
+	else if (isRouteMetaDecorator(ctx, decorator)) ctx.report({
+		code: Codes.InvalidDecorator,
+		severity: "warning",
+		message: `@${decorator.name} has no effect: ${where} is not a route`,
+		location: decorator.location,
+		hints: hint
+	});
+	for (const param of method.params) for (const decorator of unique(param.decorators)) if (decorator.owner === "http" && validTarget(decorator)) error(ctx, decorator.location, `@${decorator.name} has no effect: ${where} is not a route`, hint);
+}
+/** A route handler must be a public, non-static method with a plain name. */
+function checkHandler(ctx, method, where, decorator) {
+	let problem;
+	let hint = "Route handlers are public instance methods";
+	if (method.static) problem = `Static method ${where} cannot be a route handler`;
+	else if (method.privateName) {
+		problem = `#private method ${where} cannot be a route handler`;
+		hint = "Use a public method (the generated code calls it from outside the class)";
+	} else if (method.visibility !== "public") {
+		problem = `${method.visibility === "protected" ? "Protected" : "Private"} method ${where} cannot be a route handler`;
+		hint = "Make the method public (the generated code calls it from outside the class)";
+	} else if (method.kind !== "method") problem = `Accessor ${where} cannot be a route handler`;
+	else if (method.computed) problem = `${where} cannot be a route handler: handlers need a plain name (no computed key)`;
+	if (problem !== void 0) {
+		error(ctx, decorator.location, problem, [hint]);
+		return false;
+	}
+	return true;
+}
+function httpCode(ctx, decorators) {
+	const [decorator, ...duplicates] = decorators.filter((candidate) => candidate.identity === Ids.HttpCode);
+	for (const duplicate of duplicates) error(ctx, duplicate.location, "@HttpCode is applied several times", ["Keep a single @HttpCode(status)"]);
+	if (decorator === void 0) return;
+	const [arg] = decorator.args;
+	if (arg === void 0) {
+		error(ctx, decorator.location, "@HttpCode requires a status", ["@HttpCode(202)"]);
+		return;
+	}
+	if (!arg.evaluated) return;
+	const status = arg.value;
+	if (typeof status !== "number" || !Number.isInteger(status) || status < 100 || status > 599) {
+		error(ctx, arg.location, `@HttpCode expects an integer status between 100 and 599, got ${describe(status)}`);
+		return;
+	}
+	return status;
+}
+function responseHeaders(ctx, decorators) {
+	const headers = [];
+	const seen = /* @__PURE__ */ new Map();
+	for (const decorator of decorators) {
+		if (decorator.identity !== Ids.Header) continue;
+		const [name, value] = decorator.args;
+		if (name === void 0 || value === void 0) {
+			error(ctx, decorator.location, "@Header requires a name and a value", ["@Header('cache-control', 'no-store')"]);
+			continue;
+		}
+		if (!name.evaluated || !value.evaluated) continue;
+		if (typeof name.value !== "string" || !TOKEN.test(name.value)) {
+			error(ctx, name.location, `@Header: invalid header name ${describe(name.value)}`, ["Header names are tokens: letters, digits and ! # $ % & ' * + - . ^ _ ` | ~"]);
+			continue;
+		}
+		if (typeof value.value !== "string" || /[\r\n\0]/.test(value.value)) {
+			error(ctx, value.location, `@Header: the value of "${name.value}" must be a string without line breaks`);
+			continue;
+		}
+		const lower = name.value.toLowerCase();
+		const previous = seen.get(lower);
+		if (previous) {
+			ctx.report({
+				code: Codes.InvalidDecorator,
+				severity: "error",
+				message: `@Header: "${lower}" is set several times`,
+				location: decorator.location,
+				hints: ["Set each response header once (or use ctx.appendHeader() in the handler)"],
+				related: [{
+					message: "First set here",
+					location: previous
+				}]
+			});
+			continue;
+		}
+		seen.set(lower, decorator.location);
+		headers.push([lower, value.value]);
+	}
+	return headers;
+}
+/** `@Validate(schema)` of a handler. */
+function validateSchema(ctx, decorators) {
+	const [decorator, ...duplicates] = decorators.filter((candidate) => candidate.identity === Ids.Validate);
+	for (const duplicate of duplicates) error(ctx, duplicate.location, "@Validate is applied several times", ["Keep a single @Validate(schema): compose the validation in the schema"]);
+	if (decorator === void 0) return;
+	const [arg] = decorator.args;
+	if (arg === void 0) {
+		error(ctx, decorator.location, "@Validate requires a schema", ["@Validate(CreateUser)"]);
+		return;
+	}
+	const schema = schemaRef(ctx, arg, "@Validate");
+	return schema ? {
+		schema,
+		decorator
+	} : void 0;
+}
+/** Guard / interceptor references of a class or method, bound to provider tokens (in order). */
+function classRefs(ctx, cls, decorators, identity, role) {
+	const refs = [];
+	for (const decorator of decorators) {
+		if (decorator.identity !== identity) continue;
+		if (decorator.called && decorator.args.length === 0) error(ctx, decorator.location, `@${decorator.name} requires at least one ${role}`, [`@${decorator.name}(My${role === "guard" ? "Guard" : "Interceptor"})`]);
+		for (const arg of decorator.args) {
+			const ref = ctx.resolveClassRef(arg, {
+				from: cls,
+				role
+			});
+			if (ref) refs.push(ref);
+		}
+	}
+	return refs;
+}
+function analyzeParams(ctx, cls, method, where, bodyValidation) {
+	const params = [];
+	let complete = true;
+	for (const param of method.params) {
+		const [decorator, ...extra] = unique(param.decorators).filter((decorator) => decorator.owner === "http" && PARAM_SOURCES.has(decorator.identity ?? ""));
+		const foreign = decorator === void 0 ? foreignParameterDecorator(param) : void 0;
+		if (foreign !== void 0) {
+			error(ctx, foreign.decorator.location, `@${foreign.decorator.name} on parameter '${param.name}' of ${where} is imported from '${foreign.module}': route parameters use ${foreign.name} from '${HTTP_PACKAGE}'`, [`Import it from '${HTTP_PACKAGE}': import { ${foreign.name} } from '${HTTP_PACKAGE}'`]);
+			complete = false;
+			continue;
+		}
+		if (decorator === void 0) {
+			error(ctx, param.location, `Parameter '${param.name}' of ${where} has no HTTP decorator`, ["Decorate it with @Param(), @Query(), @Body(), @Headers(), @Cookie(), @SignedCookie(), @UploadedFile(), @UploadedFiles(), @Ctx(), @Req() or @Res()"]);
+			complete = false;
+			continue;
+		}
+		for (const other of extra) error(ctx, other.location, `Parameter '${param.name}' of ${where} has several HTTP decorators`, ["Keep a single parameter decorator"]);
+		if (param.rest) {
+			error(ctx, decorator.location, `Rest parameter '${param.name}' of ${where} cannot be injected`);
+			complete = false;
+			continue;
+		}
+		const data = analyzeParam(ctx, cls, method, param, decorator, where, bodyValidation);
+		if (data) params.push(data);
+		else complete = false;
+	}
+	return {
+		params,
+		complete
+	};
+}
+function analyzeParam(ctx, cls, method, param, decorator, where, bodyValidation) {
+	const source = PARAM_SOURCES.get(decorator.identity ?? "");
+	if (source === void 0) return;
+	const declared = parameterType(ctx, cls, method, param);
+	const defaultValue = staticDefault(param);
+	const base = {
+		index: param.index,
+		name: param.name,
+		source,
+		type: void 0,
+		...defaultValue === void 0 ? {} : { defaultValue: defaultValue.value },
+		location: decorator.location
+	};
+	const type = declared.type === void 0 ? void 0 : ctx.types.format(declared.type);
+	const plain = () => ({
+		...base,
+		key: void 0,
+		optional: false,
+		schema: void 0,
+		coercion: void 0
+	});
+	switch (source) {
+		case "request":
+		case "context": return plain();
+		case "response":
+			ctx.report({
+				code: Codes.InvalidDecorator,
+				severity: "warning",
+				message: `@Res() makes ${where} adapter-specific: the handler writes the native response itself`,
+				location: decorator.location,
+				hints: ["Prefer returning a value, an HttpResponse or a Web Response (portable across adapters)"]
+			});
+			return plain();
+		case "body": {
+			const [arg] = decorator.args;
+			let schema;
+			if (arg !== void 0) {
+				schema = schemaRef(ctx, arg, "@Body");
+				if (schema === void 0) return;
+			}
+			if (bodyValidation !== void 0) {
+				if (schema !== void 0) {
+					ctx.report({
+						code: Codes.InvalidDecorator,
+						severity: "error",
+						message: `The body of ${where} is validated twice: @Validate(${bodyValidation.schema.text}) and @Body(${schema.text})`,
+						location: bodyValidation.decorator.location,
+						hints: ["Keep one of them: @Validate(S) on the method is the same as @Body(S) on the parameter"],
+						related: [{
+							message: "@Body schema",
+							location: decorator.location
+						}]
+					});
+					return;
+				}
+				schema = bodyValidation.schema;
+			}
+			if (schema === void 0) checkUnvalidated(ctx, declared.type, decorator, param, where, "body");
+			return {
+				...base,
+				key: void 0,
+				optional: declared.optional,
+				schema,
+				coercion: void 0
+			};
+		}
+		case "file":
+		case "files": {
+			const upload = uploadOf(ctx, decorator, param, declared, where, source === "files");
+			return upload === void 0 ? void 0 : {
+				...base,
+				key: upload.field,
+				optional: !upload.required,
+				schema: void 0,
+				coercion: void 0,
+				upload
+			};
+		}
+		case "headers": {
+			const [arg] = decorator.args;
+			if (arg === void 0) return plain();
+			if (!arg.evaluated) return;
+			if (typeof arg.value !== "string" || !TOKEN.test(arg.value)) {
+				error(ctx, arg.location, `@Headers: invalid header name ${describe(arg.value)}`, ["@Headers('x-api-key'), or @Headers() for every header"]);
+				return;
+			}
+			const key = arg.value.toLowerCase();
+			const coercion = coercionOf(ctx, declared, param, decorator, where, "headers", key);
+			return coercion ? {
+				...base,
+				key,
+				type,
+				optional: declared.optional,
+				schema: void 0,
+				coercion
+			} : void 0;
+		}
+		case "param":
+		case "query": {
+			const parsed = nameAndSchema(ctx, decorator);
+			if (!parsed.ok) return;
+			const { key, schema } = parsed;
+			const optional = source === "query" && declared.optional;
+			if (schema !== void 0) return {
+				...base,
+				key,
+				optional,
+				schema,
+				coercion: void 0
+			};
+			if (key === void 0) {
+				if (source === "query") checkUnvalidated(ctx, declared.type, decorator, param, where, "query");
+				return {
+					...base,
+					key,
+					optional: false,
+					schema: void 0,
+					coercion: void 0
+				};
+			}
+			const coercion = coercionOf(ctx, declared, param, decorator, where, source, key);
+			return coercion ? {
+				...base,
+				key,
+				type,
+				optional,
+				schema: void 0,
+				coercion
+			} : void 0;
+		}
+		case "cookie":
+		case "signedCookie": return cookieParam(ctx, param, decorator, declared, where, base, type);
+	}
+}
+/** `@Cookie(name?, schema?)` / `@SignedCookie(name, schema?)`. */
+function cookieParam(ctx, param, decorator, declared, where, base, type) {
+	const parsed = nameAndSchema(ctx, decorator);
+	if (!parsed.ok) return;
+	const { key, schema } = parsed;
+	const name = `@${decorator.name}`;
+	if (key !== void 0 && !TOKEN.test(key)) {
+		error(ctx, decorator.args[0]?.location ?? decorator.location, `${name}: invalid cookie name ${describe(key)}`, [`Cookie names are tokens (letters, digits and ! # $ % & ' * + - . ^ _ \` | ~): ${name}('session_id')`]);
+		return;
+	}
+	if (decorator.identity === Ids.SignedCookie && key === void 0) {
+		error(ctx, decorator.location, "@SignedCookie requires a cookie name", ["@SignedCookie('session_id')"]);
+		return;
+	}
+	const optional = declared.optional;
+	if (schema !== void 0) return {
+		...base,
+		key,
+		optional,
+		schema,
+		coercion: void 0
+	};
+	if (key === void 0) {
+		checkUnvalidated(ctx, declared.type, decorator, param, where, "cookies");
+		return {
+			...base,
+			key,
+			optional: false,
+			schema: void 0,
+			coercion: void 0
+		};
+	}
+	const coercion = coercionOf(ctx, declared, param, decorator, where, "cookie", key);
+	return coercion ? {
+		...base,
+		key,
+		type,
+		optional,
+		schema: void 0,
+		coercion
+	} : void 0;
+}
+/**
+* The statically evaluable default value of a parameter (`page = 1`), without references to
+* exported bindings. `ParameterInfo.initializer` is read defensively (compilers before RFC 0002 C4
+* do not provide it).
+*/
+function staticDefault(param) {
+	const initializer = param.initializer;
+	if (initializer === void 0 || !initializer.evaluated || initializer.ref !== void 0) return;
+	const value = initializer.value;
+	if (value === void 0 || hasRef(value)) return;
+	return { value };
+}
+function hasRef(value) {
+	if (isValueRef(value)) return true;
+	if (Array.isArray(value)) return value.some(hasRef);
+	if (typeof value === "object" && value !== null) return Object.values(value).some(hasRef);
+	return false;
+}
+/** `@UploadedFile(field?, options?)` / `@UploadedFiles(field?, options?)`: field, options and type. */
+function uploadOf(ctx, decorator, param, declared, where, multiple) {
+	const name = `@${decorator.name}`;
+	const [first, second] = decorator.args;
+	let field;
+	let options;
+	if (first !== void 0) {
+		if (!first.evaluated) return;
+		if (typeof first.value === "string") {
+			if (first.value === "") {
+				error(ctx, first.location, `${name} expects a non-empty field name`, [`${name}('avatar')`]);
+				return;
+			}
+			field = first.value;
+			options = second;
+		} else if (first.value === void 0) options = second;
+		else if (isPlainObject(first.value)) {
+			if (second !== void 0) {
+				error(ctx, second.location, `${name}(options) takes a single argument`, [`Put the field first: ${name}('field', { ... })`]);
+				return;
+			}
+			options = first;
+		} else {
+			error(ctx, first.location, `${name} expects a field name (string) or options, got ${describe(first.value)}`, [`${name}('avatar'), ${name}('avatar', { maxSize: '5mb' }) or ${name}({ maxSize: '5mb' })`]);
+			return;
+		}
+	}
+	const parsed = uploadOptions(ctx, name, options, multiple);
+	if (parsed === void 0) return;
+	const type = uploadType(ctx, declared.type, multiple);
+	if (!type.ok) {
+		error(ctx, param.typeLocation, `${name} parameter '${param.name}' of ${where} must be typed ${multiple ? "File[]" : "File"}, got ${type.got}`, [multiple ? `${param.name}: File[]` : `${param.name}: File (or ${param.name}?: File when optional)`]);
+		return;
+	}
+	const required = parsed.required ?? !declared.optional;
+	let cast = type.cast;
+	if (!multiple && !required) {
+		const acceptsMissing = declared.type === void 0 || param.optional || param.hasDefault || acceptsUndefined(declared.type) || isRaw(ctx.types.stripNullish(declared.type).type);
+		if (!acceptsMissing && !declared.optional) {
+			error(ctx, options?.location ?? decorator.location, `${name}: '${param.name}' of ${where} is optional ({ required: false }) but typed ${ctx.types.format(declared.type)}`, [`Type it ${param.name}?: File (undefined when no file is sent)`]);
+			return;
+		}
+		cast ||= !acceptsMissing;
+	}
+	return {
+		field,
+		multiple,
+		required,
+		maxSize: parsed.maxSize,
+		maxFiles: parsed.maxFiles,
+		mimeTypes: parsed.mimeTypes,
+		cast
+	};
+}
+/** The options object of an upload decorator (`undefined` after an error). */
+function uploadOptions(ctx, name, arg, multiple) {
+	const result = {
+		required: void 0,
+		maxSize: void 0,
+		maxFiles: void 0,
+		mimeTypes: void 0
+	};
+	if (arg === void 0) return result;
+	if (!arg.evaluated) return;
+	if (arg.value === void 0) return result;
+	const shape = `{ ${(multiple ? UPLOAD_OPTIONS : UPLOAD_OPTIONS.filter((option) => option !== "maxFiles")).map((option) => `${option}?`).join(", ")} }`;
+	if (!isPlainObject(arg.value)) {
+		error(ctx, arg.location, `${name} options must be an object ${shape}, got ${describe(arg.value)}`);
+		return;
+	}
+	let ok = true;
+	const invalid = (message, hints = []) => {
+		ok = false;
+		error(ctx, arg.location, `${name}: ${message}`, hints);
+	};
+	for (const [key, value] of Object.entries(arg.value)) {
+		if (value === void 0) continue;
+		switch (key) {
+			case "required":
+				if (typeof value === "boolean") result.required = value;
+				else invalid(`"required" must be a boolean, got ${describe(value)}`);
+				break;
+			case "maxSize": {
+				const size = parseByteSize(value);
+				if (size === void 0) invalid(`"maxSize" must be a size in bytes, got ${describe(value)}`, ["A non-negative integer (5_242_880), a size with a unit ('5mb', '512kb'; kb = 1024 bytes) or Infinity"]);
+				else result.maxSize = size;
+				break;
+			}
+			case "maxFiles":
+				if (!multiple) invalid("\"maxFiles\" only applies to @UploadedFiles (a single file is expected here)", ["Use @UploadedFiles() to receive several files"]);
+				else if (value === Number.POSITIVE_INFINITY || Number.isSafeInteger(value) && value >= 1) result.maxFiles = value;
+				else invalid(`"maxFiles" must be a positive integer, got ${describe(value)}`);
+				break;
+			case "mimeTypes": {
+				const patterns = Array.isArray(value) ? value : void 0;
+				const wrong = patterns?.filter((pattern) => typeof pattern !== "string" || !isMediaTypePattern(pattern)) ?? [];
+				if (patterns === void 0 || patterns.length === 0) invalid(`"mimeTypes" must be a non-empty array of media types, got ${describe(value)}`, ["mimeTypes: ['image/png', 'image/*']"]);
+				else if (wrong.length > 0) invalid(`invalid media type ${wrong.map(describe).join(", ")} in "mimeTypes"`, ["Use type/subtype, type/* or */* without parameters: 'image/png', 'image/*'"]);
+				else result.mimeTypes = patterns;
+				break;
+			}
+			default: invalid(`unknown option "${key}"`, [`Options: ${shape}`]);
+		}
+	}
+	return ok ? result : void 0;
+}
+/** Whether a parameter type can receive uploaded files (and whether the value must be cast). */
+function uploadType(ctx, type, multiple) {
+	if (type === void 0) return {
+		ok: true,
+		cast: false
+	};
+	const { type: base } = ctx.types.stripNullish(type);
+	if (isRaw(base)) return {
+		ok: true,
+		cast: false
+	};
+	let target = base;
+	if (multiple) target = base.kind === "array" ? base.element : void 0;
+	if (target !== void 0 && isRaw(target)) return {
+		ok: true,
+		cast: false
+	};
+	const cast = target?.kind === "reference" ? FILE_TYPES.get(target.identity) : void 0;
+	return cast === void 0 ? {
+		ok: false,
+		got: ctx.types.format(type)
+	} : {
+		ok: true,
+		cast
+	};
+}
+/** Name and/or schema of `@Param(name?, schema?)` / `@Query(name?, schema?)`. */
+function nameAndSchema(ctx, decorator) {
+	const [first, second] = decorator.args;
+	if (first === void 0) return {
+		ok: true,
+		key: void 0,
+		schema: void 0
+	};
+	if (first.error !== void 0) return { ok: false };
+	if (first.ref !== void 0) {
+		if (second !== void 0) {
+			error(ctx, second.location, `@${decorator.name}(schema) takes a single argument`, [`Put the name first: @${decorator.name}('name', Schema)`]);
+			return { ok: false };
+		}
+		return {
+			ok: true,
+			key: void 0,
+			schema: first.ref
+		};
+	}
+	if (typeof first.value !== "string" || first.value === "") {
+		error(ctx, first.location, `@${decorator.name} expects a name (non-empty string) or a schema, got ${describe(first.value)}`, [`@${decorator.name}('id'), @${decorator.name}('id', Schema) or @${decorator.name}(Schema)`]);
+		return { ok: false };
+	}
+	if (second === void 0) return {
+		ok: true,
+		key: first.value,
+		schema: void 0
+	};
+	const schema = schemaRef(ctx, second, `@${decorator.name}`);
+	return schema ? {
+		ok: true,
+		key: first.value,
+		schema
+	} : { ok: false };
+}
+/** A schema argument: a reference to an exported binding. */
+function schemaRef(ctx, arg, what) {
+	if (arg.error !== void 0) return;
+	if (arg.ref === void 0) {
+		error(ctx, arg.location, `${what} expects a Standard Schema, got ${describe(arg.value)}`, ["Pass a schema declared with `export const Schema = z.object({ ... })` (Zod, Valibot, ArkType...)"]);
+		return;
+	}
+	const symbol = arg.ref.symbol;
+	if (symbol.kind === "declaration" && symbol.declaration.kind === "class" && !hasStandardSchema(ctx, arg.ref)) ctx.report({
+		code: Codes.InvalidDecorator,
+		severity: "warning",
+		message: `${what}(${arg.ref.text}): ${arg.ref.name} is a class, not a Standard Schema; the validation fails at runtime`,
+		location: arg.location,
+		hints: ["Pass a Standard Schema object (Zod, Valibot, ArkType...): classes are not validators"]
+	});
+	return arg.ref;
+}
+function hasStandardSchema(ctx, ref) {
+	const info = ref.identity === void 0 ? void 0 : ctx.classInfo(ref.identity);
+	return info === void 0 || info.superClass !== void 0 || info.properties.some((property) => property.static && property.name === "~standard") || info.methods.some((member) => member.static && member.name === "~standard");
+}
+/** Coercion of a named parameter / query value / header without schema. */
+function coercionOf(ctx, declared, param, decorator, where, source, key) {
+	const result = planCoercion(ctx, declared, param, source === "param");
+	const label = `${source === "headers" ? "header" : source} "${key}"`;
+	if (result.ok) {
+		if (source === "query" && declared.type !== void 0 && isAny(declared.type)) unvalidated(ctx, decorator, `${label} of ${where} is typed any`);
+		return result.coercion;
+	}
+	if (source === "query") {
+		unvalidated(ctx, decorator, `${label} of ${where}: ${result.reason}`, result.hints);
+		return {
+			plan: { kind: "raw" },
+			cast: false
+		};
+	}
+	ctx.report({
+		code: Codes.InvalidRoute,
+		severity: "error",
+		message: `Invalid ${label} of ${where}: ${result.reason}`,
+		location: param.typeLocation,
+		hints: [...result.hints]
+	});
+}
+/** ZNIGHT017 for a non-primitive `@Body()` / `@Query()` without schema. */
+function checkUnvalidated(ctx, type, decorator, param, where, what) {
+	if (type !== void 0 && acceptedWithoutSchema(ctx, type)) return;
+	const described = type === void 0 ? "untyped" : `typed ${ctx.types.format(type)}`;
+	unvalidated(ctx, decorator, `the ${what} of ${where} ('${param.name}', ${described}) has no schema`);
+}
+function unvalidated(ctx, decorator, detail, extraHints = []) {
+	ctx.report({
+		code: Codes.UnvalidatedInput,
+		severity: ctx.options.strictValidation ? "error" : "warning",
+		message: `Unvalidated input: ${detail}`,
+		location: decorator.location,
+		hints: [
+			...extraHints.filter((hint) => !hint.startsWith("Or validate")),
+			`Validate it with a Standard Schema: ${schemaHint(decorator.name)}`,
+			"Or type the parameter as unknown and check it yourself"
+		]
+	});
+}
+function schemaHint(decorator) {
+	if (decorator === "Body") return "@Body(Schema) or @Validate(Schema)";
+	if (decorator === "Cookie") return "@Cookie(Schema) for every cookie, or @Cookie('name', Schema)";
+	return `@${decorator}('name', Schema)`;
+}
+function acceptedWithoutSchema(ctx, type) {
+	const { type: base } = ctx.types.stripNullish(type);
+	switch (base.kind) {
+		case "primitive": return base.name !== "any" && base.name !== "object" && base.name !== "never" && base.name !== "symbol";
+		case "literal": return true;
+		case "reference":
+			if (UNVALIDATED_REFERENCES.has(base.identity)) return true;
+			return base.identity === "globalThis#Record" && base.typeArgs.length === 2 && isStringLike(base.typeArgs[1]);
+		default: return false;
+	}
+}
+function isStringLike(type) {
+	switch (type.kind) {
+		case "primitive": return type.name === "string" || type.name === "undefined" || type.name === "unknown";
+		case "array": return type.element.kind === "primitive" && type.element.name === "string";
+		case "union": return type.types.every(isStringLike);
+		default: return false;
+	}
+}
+function isAny(type) {
+	return isRaw(type) && type.kind === "primitive" && type.name === "any";
+}
+/**
+* Decorators of a parameter without duplicates (a parameter with a default value may list its
+* decorators twice).
+*/
+function unique(decorators) {
+	const seen = /* @__PURE__ */ new Set();
+	return decorators.filter((decorator) => {
+		if (seen.has(decorator.location.start)) return false;
+		seen.add(decorator.location.start);
+		return true;
+	});
+}
+/** `false` when the decorator is applied to a target it does not support (reported by the core). */
+function validTarget(decorator) {
+	const identity = decorator.identity ?? "";
+	if (ROUTE_METHODS.has(identity)) return decorator.target === "method";
+	if (PARAM_SOURCES.has(identity)) return decorator.target === "parameter";
+	switch (identity) {
+		case Ids.Controller: return decorator.target === "class";
+		case Ids.UseGuard:
+		case Ids.UseInterceptor:
+		case Ids.BodyLimit: return decorator.target === "class" || decorator.target === "method";
+		default: return decorator.target === "method";
+	}
+}
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && !isValueRef(value);
+}
+function describe(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (isValueRef(value)) return `a reference to '${value.text}'`;
+	if (typeof value === "object") return "an object";
+	if (typeof value === "string") return JSON.stringify(value);
+	return typeof value === "bigint" ? `${value}n` : String(value);
+}
+function error(ctx, location, message, hints) {
+	ctx.report({
+		code: Codes.InvalidDecorator,
+		severity: "error",
+		message,
+		location,
+		...hints ? { hints } : {}
+	});
+}
+// src/compiler/generate.ts
+/** `uploads` helper by kind and presence (`@UploadedFile` / `@UploadedFiles`, required or not). */
+const UPLOAD_HELPERS = {
+	file: {
+		required: "file",
+		optional: "optionalFile"
+	},
+	files: {
+		required: "files",
+		optional: "optionalFiles"
+	}
+};
+/** Generates `metadata.extensions.http` (`undefined` when the application has no controller). */
+function generateHttp(ctx) {
+	if (ctx.stored.length === 0) return;
+	const controllers = [...ctx.stored].sort((a, b) => compareStrings(a.token, b.token));
+	const helpers = createHelpers(ctx);
+	const entries = [["controllers", ctx.arr(controllers.map((controller) => controllerNode(ctx, helpers, controller)))]];
+	const groups = groupsNode(ctx, controllers);
+	if (groups !== void 0) entries.push(["groups", groups]);
+	return ctx.obj(entries);
+}
+/**
+* `groups`: the route decorator groups the runtime needs (required, holding several keys, or named
+* differently from their key), sorted, with sorted keys; `undefined` when there is none, so that
+* applications without groups keep a byte-identical output.
+*/
+function groupsNode(ctx, controllers) {
+	const groups = /* @__PURE__ */ new Map();
+	const visit = (entries) => {
+		for (const entry of entries) {
+			const group = groups.get(entry.group);
+			if (group === void 0) groups.set(entry.group, {
+				keys: /* @__PURE__ */ new Set([entry.key]),
+				required: entry.required
+			});
+			else {
+				group.keys.add(entry.key);
+				group.required ||= entry.required;
+			}
+		}
+	};
+	for (const controller of controllers) {
+		visit(controller.meta);
+		for (const route of controller.routes) visit(route.meta);
+	}
+	const needed = [...groups].filter(([name, group]) => group.required || group.keys.size > 1 || !group.keys.has(name)).sort(([a], [b]) => compareStrings(a, b));
+	if (needed.length === 0) return;
+	return ctx.obj(needed.map(([name, group]) => [name, ctx.obj([["keys", ctx.lit([...group.keys].sort(compareStrings))], ["required", group.required]])]));
+}
+function createHelpers(ctx) {
+	let coerce;
+	let validate;
+	let uploads;
+	let context;
+	return {
+		coerce: () => {
+			coerce ??= ctx.importFrom(HTTP_PACKAGE, "coerce");
+			return coerce;
+		},
+		validate: () => {
+			validate ??= ctx.importFrom(HTTP_PACKAGE, "validate");
+			return validate;
+		},
+		uploads: () => {
+			uploads ??= ctx.importFrom(HTTP_PACKAGE, "uploads");
+			return uploads;
+		},
+		context: () => {
+			context ??= ctx.importFrom(HTTP_PACKAGE, "HttpContext", { type: true });
+			return context;
+		}
+	};
+}
+function controllerNode(ctx, helpers, controller) {
+	return ctx.obj([
+		["token", controller.token],
+		["basePath", controller.basePath],
+		["guards", tokens(ctx, controller.guards)],
+		["interceptors", tokens(ctx, controller.interceptors)],
+		["meta", metaNode(ctx, controller.meta)],
+		["routes", ctx.arr(controller.routes.map((route) => routeNode(ctx, helpers, controller, route)))]
+	]);
+}
+function routeNode(ctx, helpers, controller, route) {
+	const entries = [
+		["method", route.method],
+		["path", route.path],
+		["fullPath", route.fullPath],
+		["handler", route.handler]
+	];
+	if (route.status !== void 0) entries.push(["status", route.status]);
+	if (route.headers.length > 0) entries.push(["headers", ctx.obj(route.headers.map(([name, value]) => [name, value]))]);
+	entries.push(["meta", metaNode(ctx, route.meta)], ["guards", tokens(ctx, route.guards)], ["interceptors", tokens(ctx, route.interceptors)], ["params", ctx.arr(route.params.map((param) => paramNode(ctx, param)))]);
+	if (route.bodyLimit !== void 0) entries.push(["bodyLimit", route.bodyLimit]);
+	const uploads = route.params.flatMap((param) => param.upload === void 0 ? [] : [param.upload]);
+	if (uploads.length > 0) entries.push(["uploads", ctx.arr(uploads.map((upload) => uploadNode(ctx, upload)))]);
+	if (route.rawResponse) entries.push(["rawResponse", true]);
+	if (route.sse !== void 0) entries.push(["sse", sseNode(ctx, route.sse)]);
+	entries.push(["invoke", invokeNode(ctx, helpers, controller, route)]);
+	return ctx.obj(entries);
+}
+/** `{ heartbeat?, retry?, maxDuration? }` (`{}` without options). */
+function sseNode(ctx, sse) {
+	const entries = [];
+	if (sse.heartbeat !== void 0) entries.push(["heartbeat", sse.heartbeat]);
+	if (sse.retry !== void 0) entries.push(["retry", sse.retry]);
+	if (sse.maxDuration !== void 0) entries.push(["maxDuration", sse.maxDuration]);
+	return ctx.obj(entries);
+}
+function paramNode(ctx, param) {
+	const entries = [["index", param.index], ["source", param.source]];
+	if (param.key !== void 0) entries.push(["name", param.key]);
+	if (param.type !== void 0) entries.push(["type", param.type]);
+	if (param.optional) entries.push(["optional", true]);
+	if (param.schema !== void 0) entries.push(["schema", true]);
+	return ctx.obj(entries);
+}
+/** `{ field?, multiple?, required?, maxSize?, maxFiles?, mimeTypes? }` (absent values omitted). */
+function uploadNode(ctx, upload) {
+	const entries = [];
+	if (upload.field !== void 0) entries.push(["field", upload.field]);
+	if (upload.multiple) entries.push(["multiple", true]);
+	if (upload.required) entries.push(["required", true]);
+	if (upload.maxSize !== void 0) entries.push(["maxSize", upload.maxSize]);
+	if (upload.maxFiles !== void 0) entries.push(["maxFiles", upload.maxFiles]);
+	if (upload.mimeTypes !== void 0) entries.push(["mimeTypes", ctx.lit(upload.mimeTypes)]);
+	return ctx.obj(entries);
+}
+function metaNode(ctx, meta) {
+	return ctx.obj(meta.map((entry) => [entry.key, ctx.lit(entry.value)]));
+}
+function tokens(ctx, refs) {
+	return ctx.arr(refs.map((ref) => ctx.tokenOf(ref) ?? ref.token));
+}
+/**
+* `(c: Controller, ctx: HttpContext) => c.handler(...args)`: `async` (awaiting every `validate()`)
+* when the route validates something with a schema, synchronous otherwise.
+*/
+function invokeNode(ctx, helpers, controller, route) {
+	const async = route.bodySchema !== void 0 || route.params.some((param) => param.schema !== void 0);
+	const params = [["c", ctx.importType(controller.identity)]];
+	if (route.params.length > 0 || route.bodySchema !== void 0) params.push(["ctx", helpers.context()]);
+	return ctx.arrow(params, (c, http) => {
+		const args = [];
+		for (const param of route.params) args[param.index] = argumentNode(ctx, helpers, http, param);
+		const call = ctx.call(ctx.member(c, route.handler), Array.from(args, (arg) => arg ?? ctx.lit(void 0)));
+		if (route.bodySchema === void 0) return call;
+		const body = ctx.code`await ${ctx.call(ctx.member(http, "parseBody"))}`;
+		const check = validation(ctx, helpers, route.bodySchema, body, "body");
+		return ctx.code`{ ${check}; return ${call} }`;
+	}, { async });
+}
+/** The expression passed to the handler for one parameter. */
+function argumentNode(ctx, helpers, http, param) {
+	switch (param.source) {
+		case "context": return http;
+		case "request": return ctx.code`${ctx.member(http, "request")} as never`;
+		case "response": return ctx.code`${ctx.member(http, "response")} as never`;
+		case "body": {
+			const body = ctx.member(http, "body");
+			return param.schema === void 0 ? ctx.code`${body} as never` : validation(ctx, helpers, param.schema, body, "body");
+		}
+		case "file":
+		case "files": {
+			const upload = param.upload;
+			const helper = UPLOAD_HELPERS[upload.multiple ? "files" : "file"][upload.required ? "required" : "optional"];
+			const call = ctx.call(ctx.member(helpers.uploads(), helper), [http, ctx.lit(upload.field)]);
+			return upload.cast ? ctx.code`${call} as never` : call;
+		}
+		case "headers":
+		case "param":
+		case "query": {
+			const record = ctx.member(http, param.source === "param" ? "params" : param.source);
+			if (param.key === void 0) {
+				const location = param.source === "param" ? "params" : param.source;
+				return param.schema === void 0 ? ctx.code`${record} as never` : validation(ctx, helpers, param.schema, record, location);
+			}
+			const value = ctx.code`${record}[${param.key}]`;
+			const label = `${param.source === "headers" ? "header" : param.source} "${param.key}"`;
+			if (param.schema !== void 0) return validation(ctx, helpers, param.schema, value, label);
+			return coercion(ctx, helpers, param.coercion ?? {
+				plan: { kind: "raw" },
+				cast: false
+			}, value, label);
+		}
+		case "cookie":
+		case "signedCookie": {
+			if (param.key === void 0) {
+				const cookies = ctx.member(http, "cookies");
+				return param.schema === void 0 ? ctx.code`${cookies} as never` : validation(ctx, helpers, param.schema, cookies, "cookies");
+			}
+			const value = param.source === "cookie" ? ctx.code`${ctx.member(http, "cookies")}[${param.key}]` : ctx.call(ctx.member(http, "signedCookie"), [param.key]);
+			const label = `cookie "${param.key}"`;
+			if (param.schema !== void 0) return validation(ctx, helpers, param.schema, value, label);
+			return coercion(ctx, helpers, param.coercion ?? {
+				plan: { kind: "raw" },
+				cast: false
+			}, value, label);
+		}
+	}
+}
+/** `await validate(schema, value, location)`. */
+function validation(ctx, helpers, schema, value, location) {
+	return ctx.code`await ${ctx.call(helpers.validate(), [
+		ctx.ref(schema),
+		value,
+		location
+	])}`;
+}
+/** `coerce.X(value, label, ...)`, cast with `as never` when the result does not have the declared type. */
+function coercion(ctx, helpers, coercion, value, label) {
+	const node = coerceCall(ctx, helpers, coercion.plan, value, label);
+	return coercion.cast ? ctx.code`${node} as never` : node;
+}
+function coerceCall(ctx, helpers, plan, value, label) {
+	const helper = (name) => ctx.member(helpers.coerce(), name);
+	switch (plan.kind) {
+		case "raw": return ctx.code`${value} as never`;
+		case "enum": return ctx.call(helper("enum"), [
+			value,
+			label,
+			ctx.lit(plan.values)
+		]);
+		case "array":
+		case "optional": return ctx.call(helper(plan.kind), [
+			value,
+			label,
+			itemCoercer(ctx, helpers, plan.item)
+		]);
+		default: return ctx.call(helper(plan.kind), [value, label]);
+	}
+}
+/** A `Coercer` value: `coerce.number`, or `(v, l) => coerce.enum(v, l, [...])`. */
+function itemCoercer(ctx, helpers, plan) {
+	switch (plan.kind) {
+		case "enum":
+		case "array":
+		case "optional": return ctx.arrow(["v", "l"], (v, l) => coerceCall(ctx, helpers, plan, v, l));
+		case "raw": return ctx.arrow(["v"], (v) => v);
+		default: return ctx.member(helpers.coerce(), plan.kind);
+	}
+}
+// src/compiler/validate.ts
+/** Validates the routes of every controller. */
+function validateHttp(ctx) {
+	const controllers = [...ctx.stored].sort((a, b) => compareStrings(a.token, b.token));
+	const registered = /* @__PURE__ */ new Map();
+	for (const controller of controllers) {
+		const baseIssue = checkRoutePath(controller.rawBasePath);
+		if (baseIssue !== void 0) {
+			invalidRoute(ctx, controller.pathLocation, `Invalid base path ${JSON.stringify(controller.rawBasePath)} of ${controller.displayName}: ${baseIssue.message}`, GRAMMAR_HINTS);
+			continue;
+		}
+		for (const route of controller.routes) {
+			const where = `${controller.displayName}.${route.handler}`;
+			const ownIssue = checkRoutePath(route.rawPath);
+			const issue = ownIssue ?? checkRoutePath(route.fullPath);
+			if (issue !== void 0) {
+				const path = ownIssue === void 0 ? route.fullPath : route.rawPath;
+				invalidRoute(ctx, route.pathLocation, `Invalid route path ${JSON.stringify(path)} of ${where}: ${issue.message}`, GRAMMAR_HINTS);
+				continue;
+			}
+			const parsed = parseRoutePath(route.fullPath);
+			checkParams(ctx, route, parsed, where);
+			const key = `${route.method} ${parsed.shape}`;
+			const previous = registered.get(key);
+			if (previous === void 0) {
+				registered.set(key, {
+					where,
+					route
+				});
+				continue;
+			}
+			ctx.report({
+				code: Codes.InvalidRoute,
+				severity: "error",
+				message: `Duplicate route ${route.method} ${route.fullPath}: ${where} conflicts with ${previous.where} (${previous.route.method} ${previous.route.fullPath})`,
+				location: route.location,
+				hints: ["Two routes with the same method and the same path shape (parameter names aside) cannot coexist"],
+				related: [{
+					message: `${previous.where} is declared here`,
+					location: previous.route.location
+				}]
+			});
+		}
+	}
+	validateDecisions(ctx, controllers);
+}
+/**
+* Every route decorator definition, sorted by identity: the applied ones (first usage) and, when
+* the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are left to the
+* usages, which report them).
+*/
+function routeDecoratorDefinitions(ctx, controllers) {
+	const definitions = /* @__PURE__ */ new Map();
+	const visit = (entries) => {
+		for (const entry of entries) {
+			const known = definitions.get(entry.identity);
+			if (known === void 0) definitions.set(entry.identity, {
+				identity: entry.identity,
+				name: entry.decorator,
+				key: entry.key,
+				group: entry.group,
+				required: entry.required,
+				definition: entry.definition,
+				flag: entry.value === true
+			});
+			else if (entry.value !== true) known.flag = false;
+		}
+	};
+	for (const controller of controllers) {
+		visit(controller.meta);
+		for (const route of controller.routes) visit(route.meta);
+	}
+	const all = typeof ctx.definitionsOf === "function" ? ctx.definitionsOf(Ids.createRouteDecorator) : [];
+	for (const found of all) {
+		const [keyArg, optionsArg, ...extra] = found.args;
+		const key = keyArg?.evaluated === true ? keyArg.value : void 0;
+		if (typeof key !== "string" || key === "" || extra.length > 0 || optionsArg !== void 0 && !optionsArg.evaluated) continue;
+		const parsed = parseRouteDecoratorOptions(key, optionsArg?.value);
+		if ("error" in parsed) continue;
+		const flag = found.typeArgs.length === 0;
+		const known = definitions.get(found.identity);
+		if (known !== void 0) {
+			known.flag &&= flag;
+			continue;
+		}
+		definitions.set(found.identity, {
+			identity: found.identity,
+			name: found.name,
+			key,
+			...parsed,
+			definition: found.location,
+			flag
+		});
+	}
+	return [...definitions.values()].sort((a, b) => compareStrings(a.identity, b.identity));
+}
+/**
+* Route decorator groups (RFC 0001 §5.1): every definition of a key uses the same options and the
+* decorators of a group agree on `required` (ZNIGHT005, at the second definition); every route has
+* a decision of every required group, its own or its controller's (ZNIGHT023).
+*/
+function validateDecisions(ctx, controllers) {
+	const definitions = routeDecoratorDefinitions(ctx, controllers);
+	if (definitions.length === 0) return;
+	const byKey = /* @__PURE__ */ new Map();
+	const byGroup = /* @__PURE__ */ new Map();
+	const members = /* @__PURE__ */ new Map();
+	for (const definition of definitions) {
+		const sameKey = byKey.get(definition.key);
+		if (sameKey !== void 0 && (sameKey.group !== definition.group || sameKey.required !== definition.required)) {
+			ctx.report({
+				code: Codes.InvalidDecorator,
+				severity: "error",
+				message: `The route decorator ${definition.name} defines the key "${definition.key}" with ${describeOptions(definition)}, but ${sameKey.name} defines it with ${describeOptions(sameKey)}`,
+				location: definition.definition,
+				hints: ["Every definition of a key must use the same options: share one definition"],
+				related: [{
+					message: `${sameKey.name} is defined here`,
+					location: sameKey.definition
+				}]
+			});
+			continue;
+		}
+		const sameGroup = byGroup.get(definition.group);
+		if (sameGroup !== void 0 && sameGroup.required !== definition.required) {
+			ctx.report({
+				code: Codes.InvalidDecorator,
+				severity: "error",
+				message: `The "${definition.group}" group is ${definition.required ? "" : "not "}required for ${definition.name} but ${sameGroup.required ? "" : "not "}required for ${sameGroup.name}`,
+				location: definition.definition,
+				hints: [`All the decorators of the "${definition.group}" group must agree on required`],
+				related: [{
+					message: `${sameGroup.name} is defined here`,
+					location: sameGroup.definition
+				}]
+			});
+			continue;
+		}
+		byKey.set(definition.key, sameKey ?? definition);
+		byGroup.set(definition.group, sameGroup ?? definition);
+		const list = members.get(definition.group) ?? [];
+		list.push(definition);
+		members.set(definition.group, list);
+	}
+	const required = [...byGroup.values()].filter((definition) => definition.required);
+	if (required.length === 0) return;
+	for (const controller of controllers) {
+		const controllerGroups = new Set(controller.meta.map((entry) => entry.group));
+		for (const route of controller.routes) {
+			const decided = /* @__PURE__ */ new Set([...controllerGroups, ...route.meta.map((entry) => entry.group)]);
+			for (const group of required) {
+				if (decided.has(group.group)) continue;
+				const inOrder = [...members.get(group.group) ?? [group]].sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start);
+				const decorators = inOrder.map((definition) => `@${definition.name}(${definition.flag ? "" : "..."})`);
+				const listed = decorators.length === 1 ? decorators[0] : `${decorators.slice(0, -1).join(", ")} or ${decorators.at(-1)}`;
+				ctx.report({
+					code: Codes.MissingRouteDecision,
+					severity: "error",
+					message: `Route ${route.method} ${route.fullPath} (${controller.displayName}.${route.handler}) has no "${group.group}" decision`,
+					location: route.location,
+					hints: [`Add ${listed} to the route or to ${controller.displayName}`],
+					related: [{
+						message: `The "${group.group}" group is required`,
+						location: (inOrder[0] ?? group).definition
+					}, {
+						message: `${controller.displayName} is declared here`,
+						location: controller.location
+					}]
+				});
+			}
+		}
+	}
+}
+function describeOptions(entry) {
+	const group = entry.group === entry.key ? "no group" : `group "${entry.group}"`;
+	return entry.required ? `${group}, required` : group;
+}
+const GRAMMAR_HINTS = ["Paths are made of static segments (letters, digits and - . _ ~ ! $ & ' + , ; = @), :name parameters and a trailing * wildcard"];
+/** `:param` of the path ↔ `@Param('name')` parameters of the handler. */
+function checkParams(ctx, route, path, where) {
+	const declared = new Set(path.params);
+	const consumed = /* @__PURE__ */ new Set();
+	let everything = false;
+	for (const param of route.params) {
+		if (param.source === "context" || param.source === "request") {
+			everything = true;
+			continue;
+		}
+		if (param.source !== "param") continue;
+		if (param.key === void 0) {
+			everything = true;
+			continue;
+		}
+		if (declared.has(param.key)) {
+			consumed.add(param.key);
+			continue;
+		}
+		const available = path.params.filter((name) => name !== "*").map((name) => `:${name}`);
+		invalidRoute(ctx, param.location, `@Param('${param.key}') of ${where}: the route ${route.method} ${route.fullPath} has no ${param.key === "*" ? "wildcard" : `":${param.key}" parameter`}`, [available.length > 0 ? `Parameters of the route: ${available.join(", ")}` : `Add ":${param.key}" to the route path`]);
+	}
+	if (everything || !route.complete) return;
+	for (const name of path.params) if (name !== "*" && !consumed.has(name)) invalidRoute(ctx, route.pathLocation, `Route ${route.method} ${route.fullPath} declares ":${name}" but ${where} has no @Param('${name}') parameter`, [`Add a parameter: @Param('${name}') ${name}: string`]);
+}
+function invalidRoute(ctx, location, message, hints) {
+	ctx.report({
+		code: Codes.InvalidRoute,
+		severity: "error",
+		message,
+		location,
+		hints
+	});
+}
+// src/compiler/index.ts
+const ROUTE = {
+	targets: ["method"],
+	params: ["static"]
+};
+const NAME_OR_SCHEMA = {
+	targets: ["parameter"],
+	params: ["value", "value"]
+};
+const NO_ARGUMENT = {
+	targets: ["parameter"],
+	params: []
+};
+const CLASS_REFS = {
+	targets: ["class", "method"],
+	params: [],
+	rest: "value"
+};
+const UPLOAD = {
+	targets: ["parameter"],
+	params: ["static", "static"]
+};
+/** Decorators owned by the extension, by canonical identity (static / value arguments, §4.6). */
+const decorators = Object.freeze({
+	[Ids.Controller]: {
+		targets: ["class"],
+		params: ["static"]
+	},
+	...Object.fromEntries([...ROUTE_METHODS.keys()].map((identity) => [identity, ROUTE])),
+	[Ids.Param]: NAME_OR_SCHEMA,
+	[Ids.Query]: NAME_OR_SCHEMA,
+	[Ids.Body]: {
+		targets: ["parameter"],
+		params: ["value"]
+	},
+	[Ids.Headers]: {
+		targets: ["parameter"],
+		params: ["static"]
+	},
+	[Ids.Req]: NO_ARGUMENT,
+	[Ids.Res]: NO_ARGUMENT,
+	[Ids.Ctx]: NO_ARGUMENT,
+	[Ids.HttpCode]: {
+		targets: ["method"],
+		params: ["static"]
+	},
+	[Ids.Header]: {
+		targets: ["method"],
+		params: ["static", "static"]
+	},
+	[Ids.UseGuard]: CLASS_REFS,
+	[Ids.UseInterceptor]: CLASS_REFS,
+	[Ids.Validate]: {
+		targets: ["method"],
+		params: ["value"]
+	},
+	[Ids.UploadedFile]: UPLOAD,
+	[Ids.UploadedFiles]: UPLOAD,
+	[Ids.BodyLimit]: {
+		targets: ["class", "method"],
+		params: ["static"]
+	},
+	[Ids.Cookie]: NAME_OR_SCHEMA,
+	[Ids.SignedCookie]: NAME_OR_SCHEMA,
+	[Ids.Sse]: {
+		targets: ["method"],
+		params: ["static", "static"]
+	}
+});
+/** The `@znight/http` compiler extension. */
+const http = Object.freeze({
+	apiVersion: 1,
+	name: EXTENSION_NAME,
+	decorators,
+	analyzeClass: analyzeHttpClass,
+	validate: validateHttp,
+	generate: generateHttp
+});
+export { http as default };
+
+//# sourceMappingURL=compiler.mjs.map