@znight/http 0.1.2 → 0.1.4

package/dist/compiler.mjs

@@ -514,6 +514,38 @@ function routeMeta(ctx, cls, decorators, target) {
 	}
 	return entries;
 }
+/**
+* The route metadata entries of a class (`method` omitted) or of one of its methods: the route
+* decorators (`createRouteDecorator` consts) applied to that target, in source order, read exactly
+* as the http extension reads controllers and routes (keys, statically evaluated values, groups,
+* `required`). Problems are reported as ZNIGHT005 through `ctx`, once per call: read each target
+* once. Decorators that are not route decorators are ignored.
+*
+* Works with the analysis context of any extension. The entries of a target are its own: combine a
+* class and a method with {@link effectiveRouteMeta}.
+*
+* ```ts
+* analyzeClass(cls, ctx) {
+*   const classMeta = readRouteMeta(ctx, cls)
+*   for (const method of cls.methods) {
+*     const meta = effectiveRouteMeta(classMeta, readRouteMeta(ctx, cls, method))
+*   }
+* }
+* ```
+*/
+function readRouteMeta(ctx, cls, method) {
+	return method === void 0 ? routeMeta(ctx, cls, cls.decorators, cls.displayName) : routeMeta(ctx, cls, method.decorators, `${cls.displayName}.${method.name}`);
+}
+/**
+* The effective metadata of a method from the entries of its class and its own (RFC 0001 §5.1):
+* the class entries, except those of a group the method decides itself, then the method entries.
+* The same rule as `ctx.route.meta` at runtime.
+*/
+function effectiveRouteMeta(classMeta, methodMeta) {
+	if (methodMeta.length === 0) return [...classMeta];
+	const decided = new Set(methodMeta.map((entry) => entry.group));
+	return [...classMeta.filter((entry) => !decided.has(entry.group)), ...methodMeta];
+}
 /** `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";
@@ -661,7 +693,7 @@ function analyzeHttpClass(cls, ctx) {
 	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 meta = readRouteMeta(ctx, cls);
 	const bodyLimit = bodyLimitOf(ctx, cls.decorators);
 	const routes = [];
 	for (const method of cls.methods) routes.push(...analyzeMethod(ctx, cls, method, basePath, bodyLimit));
@@ -796,7 +828,7 @@ function analyzeMethod(ctx, cls, method, basePath, controllerBodyLimit) {
 	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 meta = readRouteMeta(ctx, cls, method);
 	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;
@@ -1695,6 +1727,7 @@ function groupsNode(ctx, controllers) {
 function createHelpers(ctx) {
 	let coerce;
 	let validate;
+	let isThenable;
 	let uploads;
 	let context;
 	return {
@@ -1706,6 +1739,10 @@ function createHelpers(ctx) {
 			validate ??= ctx.importFrom(HTTP_PACKAGE, "validate");
 			return validate;
 		},
+		isThenable: () => {
+			isThenable ??= ctx.importFrom(HTTP_PACKAGE, "isThenable");
+			return isThenable;
+		},
 		uploads: () => {
 			uploads ??= ctx.importFrom(HTTP_PACKAGE, "uploads");
 			return uploads;
@@ -1778,22 +1815,86 @@ 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.
+* `(c: Controller, ctx: HttpContext) => c.handler(...args)`, synchronous when no argument is
+* validated with a schema. A route validating arguments gets a block that stays synchronous as long
+* as every `validate()` returns a value (see {@link validatingBlock}). `@Validate(S)` without
+* `@Body()` parameter reads the body in `invoke`: that arrow is `async` and `await`s every
+* `validate()`.
 */
 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 slots = [];
+	for (const param of route.params) slots[param.index] = param;
+	const bodySchema = route.bodySchema;
+	if (bodySchema !== void 0) return ctx.arrow(params, (c, http) => {
+		const call = handlerCall(ctx, c, route, Array.from(slots, (param) => awaitedArgument(ctx, helpers, http, param)));
 		const body = ctx.code`await ${ctx.call(ctx.member(http, "parseBody"))}`;
-		const check = validation(ctx, helpers, route.bodySchema, body, "body");
+		const check = ctx.code`await ${validation(ctx, helpers, bodySchema, body, "body")}`;
 		return ctx.code`{ ${check}; return ${call} }`;
-	}, { async });
+	}, { async: true });
+	const last = slots.findLastIndex((param) => param?.schema !== void 0);
+	return ctx.arrow(params, (c, http) => last === -1 ? handlerCall(ctx, c, route, Array.from(slots, (param) => plainArgument(ctx, helpers, http, param))) : validatingBlock(ctx, helpers, route, slots, last, c, http));
+}
+/** `c.handler(args)`. */
+function handlerCall(ctx, c, route, args) {
+	return ctx.call(ctx.member(c, route.handler), args);
+}
+/**
+* The body of the `invoke` of a route validating arguments with schemas: the arguments up to the
+* last validated one are evaluated in order into `const`s (`a<index>`), the handler is called with
+* them. `validate()` returns the value when the schema validates synchronously (Zod, Valibot and
+* ArkType without async refinements), so the request needs no promise; when one returns a
+* thenable, the rest runs in an `async` arrow that awaits it, then evaluates the remaining arguments
+* (`await`ing their validations) and calls the handler: the order of evaluation, the error reported
+* when several arguments are invalid and the value received by the handler are those of an `async`
+* `invoke` awaiting every `validate()`.
+*
+* ```ts
+* (c: UserController, ctx: HttpContext) => {
+*   const a0 = coerce.number(ctx.params['id'], 'param "id"')
+*   const a1 = validate(UpdateUser, ctx.body, 'body')
+*   if (isThenable(a1)) return (async () => c.update(a0, await a1, ctx))()
+*   return c.update(a0, a1, ctx)
+* }
+* ```
+*/
+function validatingBlock(ctx, helpers, route, slots, last, c, http) {
+	const bound = [];
+	for (let index = 0; index <= last; index++) {
+		const param = slots[index];
+		if (param !== void 0 && param.source !== "context") bound.push(index);
+	}
+	return ctx.block(bound.map((index) => `a${index}`), (...locals) => {
+		const local = new Map(bound.map((index, position) => [index, locals[position]]));
+		const evaluated = (index) => local.get(index) ?? plainArgument(ctx, helpers, http, slots[index]);
+		const statements = [];
+		for (const index of bound) {
+			const param = slots[index];
+			const name = local.get(index);
+			statements.push(ctx.code`const ${name} = ${plainArgument(ctx, helpers, http, param)}`);
+			if (param.schema !== void 0) {
+				const rest = Array.from(slots, (other, position) => {
+					if (position < index) return evaluated(position);
+					return position === index ? ctx.code`await ${name}` : awaitedArgument(ctx, helpers, http, other);
+				});
+				const resume = ctx.arrow([], () => handlerCall(ctx, c, route, rest), { async: true });
+				statements.push(ctx.code`if (${ctx.call(helpers.isThenable(), [name])}) return (${resume})()`);
+			}
+		}
+		const args = Array.from(slots, (param, position) => position <= last ? evaluated(position) : plainArgument(ctx, helpers, http, param));
+		statements.push(ctx.code`return ${handlerCall(ctx, c, route, args)}`);
+		return statements;
+	});
+}
+/** An argument evaluated in an `async` arrow: its validation, if any, is `await`ed. */
+function awaitedArgument(ctx, helpers, http, param) {
+	const node = plainArgument(ctx, helpers, http, param);
+	return param?.schema === void 0 ? node : ctx.code`await ${node}`;
+}
+/** An argument as an expression (`validate()` not awaited); `undefined` for a hole. */
+function plainArgument(ctx, helpers, http, param) {
+	return param === void 0 ? ctx.lit(void 0) : argumentNode(ctx, helpers, http, param);
 }
 /** The expression passed to the handler for one parameter. */
 function argumentNode(ctx, helpers, http, param) {
@@ -1844,13 +1945,13 @@ function argumentNode(ctx, helpers, http, param) {
 		}
 	}
 }
-/** `await validate(schema, value, location)`. */
+/** `validate(schema, value, location)` (the value, or a promise when the schema validates asynchronously). */
 function validation(ctx, helpers, schema, value, location) {
-	return ctx.code`await ${ctx.call(helpers.validate(), [
+	return 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) {
@@ -1885,77 +1986,26 @@ function itemCoercer(ctx, helpers, plan) {
 		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);
-}
+// src/compiler/route-groups.ts
 /**
-* 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).
+* Every route decorator definition, sorted by identity: the applied ones (`applied`, first usage
+* wins) and, when the compiler provides `definitionsOf`, the ones applied nowhere (invalid ones are
+* left to the usages, which report them).
 */
-function routeDecoratorDefinitions(ctx, controllers) {
+function routeDecoratorDefinitions(ctx, applied) {
 	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);
+	for (const entry of applied) {
+		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;
 	}
 	const all = typeof ctx.definitionsOf === "function" ? ctx.definitionsOf(Ids.createRouteDecorator) : [];
 	for (const found of all) {
@@ -1982,20 +2032,26 @@ function routeDecoratorDefinitions(ctx, controllers) {
 	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).
+* The route decorator groups of the application (RFC 0001 §5.1): every definition of a key must use
+* the same options and the decorators of a group must agree on `required` (a conflict is returned
+* at the second definition, which is then ignored); the required groups with their decorators.
+* `applied` are the entries of the targets the caller analysed (their first usage of a decorator
+* wins over its `definitionsOf` entry).
 */
-function validateDecisions(ctx, controllers) {
-	const definitions = routeDecoratorDefinitions(ctx, controllers);
-	if (definitions.length === 0) return;
+function analyzeRouteGroups(ctx, applied) {
+	const definitions = routeDecoratorDefinitions(ctx, applied);
+	if (definitions.length === 0) return {
+		conflicts: [],
+		required: []
+	};
+	const conflicts = [];
 	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({
+			conflicts.push({
 				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)}`,
@@ -2010,7 +2066,7 @@ function validateDecisions(ctx, controllers) {
 		}
 		const sameGroup = byGroup.get(definition.group);
 		if (sameGroup !== void 0 && sameGroup.required !== definition.required) {
-			ctx.report({
+			conflicts.push({
 				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}`,
@@ -2029,7 +2085,112 @@ function validateDecisions(ctx, controllers) {
 		list.push(definition);
 		members.set(definition.group, list);
 	}
-	const required = [...byGroup.values()].filter((definition) => definition.required);
+	const required = [];
+	for (const first of byGroup.values()) {
+		if (!first.required) continue;
+		const decorators = [...members.get(first.group) ?? [first]].sort((a, b) => compareStrings(a.definition.file, b.definition.file) || a.definition.start - b.definition.start).map((member) => Object.freeze({ ...member }));
+		const usages = decorators.map((member) => `@${member.name}(${member.flag ? "" : "..."})`);
+		const suggestion = usages.length === 1 ? usages[0] : `${usages.slice(0, -1).join(", ")} or ${usages.at(-1)}`;
+		required.push(Object.freeze({
+			group: first.group,
+			decorators: Object.freeze(decorators),
+			suggestion
+		}));
+	}
+	return {
+		conflicts,
+		required
+	};
+}
+/**
+* The required route decorator groups of the application (RFC 0001): what every route-like target
+* of another extension (a gateway, a GraphQL root field) must decide, exactly as HTTP routes must.
+* A target without a decision of a returned group is **ZNIGHT023**, reported by the caller.
+*
+* `applied` are the route metadata entries the caller read on its own targets
+* ({@link readRouteMeta}): they make decorators known even when the compiler has no
+* `definitionsOf`, and refine how flags are suggested. Inconsistent definitions are left out and
+* not reported here: the http extension reports them (ZNIGHT005) once.
+*
+* ```ts
+* validate(ctx) {
+*   const required = requiredRouteGroups(ctx, ctx.stored.flatMap(gateway => gateway.meta))
+*   for (const gateway of ctx.stored)
+*     for (const group of required)
+*       if (!gateway.meta.some(entry => entry.group === group.group))
+*         ctx.report({ code: 'ZNIGHT023', severity: 'error', message: `${gateway.name} has no "${group.group}" decision`,
+*           location: gateway.location, hints: [`Add ${group.suggestion} to ${gateway.name}`] })
+* }
+* ```
+*/
+function requiredRouteGroups(ctx, applied = []) {
+	return analyzeRouteGroups(ctx, applied).required;
+}
+function describeOptions(entry) {
+	const group = entry.group === entry.key ? "no group" : `group "${entry.group}"`;
+	return entry.required ? `${group}, required` : group;
+}
+// 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 metadata entry of the controllers: controller entries, then route entries. */
+function* appliedEntries(controllers) {
+	for (const controller of controllers) {
+		yield* controller.meta;
+		for (const route of controller.routes) yield* route.meta;
+	}
+}
+/**
+* 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 { conflicts, required } = analyzeRouteGroups(ctx, appliedEntries(controllers));
+	for (const conflict of conflicts) ctx.report(conflict);
 	if (required.length === 0) return;
 	for (const controller of controllers) {
 		const controllerGroups = new Set(controller.meta.map((entry) => entry.group));
@@ -2037,18 +2198,15 @@ function validateDecisions(ctx, controllers) {
 			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}`],
+					hints: [`Add ${group.suggestion} to the route or to ${controller.displayName}`],
 					related: [{
 						message: `The "${group.group}" group is required`,
-						location: (inOrder[0] ?? group).definition
+						location: firstDefinition(group)
 					}, {
 						message: `${controller.displayName} is declared here`,
 						location: controller.location
@@ -2058,9 +2216,9 @@ function validateDecisions(ctx, controllers) {
 		}
 	}
 }
-function describeOptions(entry) {
-	const group = entry.group === entry.key ? "no group" : `group "${entry.group}"`;
-	return entry.required ? `${group}, required` : group;
+/** Where the first decorator of a group (source order) is defined. */
+function firstDefinition(group) {
+	return group.decorators[0].definition;
 }
 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. */
@@ -2175,6 +2333,6 @@ const http = Object.freeze({
 	validate: validateHttp,
 	generate: generateHttp
 });
-export { http as default };
+export { http as default, effectiveRouteMeta, readRouteMeta, requiredRouteGroups };
 
 //# sourceMappingURL=compiler.mjs.map