typespec-hono 0.4.0 → 0.6.0

package/dist/src/app.js

@@ -279,6 +279,14 @@ securityFor) {
                 validators.push([targets[0], identifier]);
                 continue;
             }
+            /**
+             * **Recorded as an ordinary body validator as well**, because `byContentType` publishes what
+             * it validated under the body target whichever parser produced it. So a dispatched route is
+             * the same shape as every other one downstream: the handler's input type includes the body,
+             * and the handler reads it with one `c.req.valid` like anywhere else. What differs is only
+             * which middleware is emitted, below.
+             */
+            validators.push([VALIDATOR_TARGET.body, identifier]);
             dispatched = { byType: body.byType, identifier };
         }
         return [{ route, names, validators, dispatched }];
@@ -416,21 +424,33 @@ securityFor) {
          * from that type -- measured, `hc<typeof app>` resolved the wrapped route's body to `unknown`.
          */
         /**
-         * Where the document declares request media types needing different parsers, the validator
-         * is chosen from the request's `Content-Type`. `byContentType` is a plain middleware, so the
-         * final handler is untouched and Hono's RPC client still derives its surface from it.
+         * Where the document declares request media types needing different parsers, the parser is
+         * chosen from the request's `Content-Type`. `byContentType` takes the body's schema and
+         * `deps.invalid` and validates with them, so it stands in for that target's `zValidator`
+         * rather than wrapping one, and publishes under the body target either way.
+         *
+         * **It used to wrap pre-built `zValidator`s and publish under whichever one ran, and that
+         * emitted code a consumer could not compile.** A plain `MiddlewareHandler` contributes no
+         * `Input` to Hono's chain, so `c.req.valid("json")` in the handler below was
+         * `TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`, and
+         * the handler's declared input type omitted the body entirely because the body was not among
+         * the route's validators. One published slot removes both.
          */
         const dispatch = entry.dispatched === undefined
             ? []
             : [
-                "\t\tbyContentType([",
-                ...entry.dispatched.byType.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}, zValidator(${JSON.stringify(target)}, ${identifierOf(entry)}, deps.invalid)],`),
+                `\t\tbyContentType(${identifierOf(entry)}, deps.invalid, [`,
+                ...entry.dispatched.byType.map(([type, target]) => `\t\t\t[${JSON.stringify(type)}, ${JSON.stringify(target)}],`),
                 "\t\t]),",
             ];
         const middleware = [
             ...(headOnly ? ["\t\theadOnly,"] : []),
             ...gate,
-            ...validators.map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
+            ...validators
+                // The dispatched body's own `zValidator` is `byContentType`; emitting both would parse
+                // the body twice and reject every media type but one.
+                .filter(([target]) => entry.dispatched === undefined || target !== VALIDATOR_TARGET.body)
+                .map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
             ...dispatch,
         ];
         /**
@@ -467,15 +487,9 @@ securityFor) {
             body.push(`\t\t\tconst ctx = deps.context(c, "none");`);
             body.push("\t\t\tif (ctx === null) return deps.noContext(c);");
         }
+        // A dispatched body is in `validators` under the body target like any other, so there is
+        // nothing extra to spread: `byContentType` published it there whichever parser ran.
         const pieces = validators.map(([target]) => `...c.req.valid(${JSON.stringify(target)})`);
-        /**
-         * Only one dispatched branch runs, and `zValidator` writes under its own target. Spreading every
-         * possible target is how the handler reads whichever one it was: an unset target reads
-         * `undefined`, and spreading `undefined` into an object literal contributes nothing.
-         */
-        for (const target of new Set((entry.dispatched?.byType ?? []).map(([, name]) => name))) {
-            pieces.push(`...c.req.valid(${JSON.stringify(target)})`);
-        }
         if (route.rawBodyProperty !== undefined) {
             // The bytes ARE the contract: a signature covers exactly what arrived, so parsing and
             // re-serialising would verify a different string than the sender signed. WHICH reader
@@ -586,7 +600,7 @@ securityFor) {
             "\t\t\t},",
             "\t\t)",
         ].join("\n");
-        return { target, text };
+        return { target, text, headOnly };
     });
     /**
      * Every identifier this file names, imported from the module that declares it.
@@ -594,8 +608,21 @@ securityFor) {
      * **Derived from what the rendered text actually references, not from what was available.** An
      * unused import fails the lint a generated file has to pass like any other, and a missing one is a
      * file that does not compile. Both have happened.
+     *
+     * **The text is TOKENISED and compared by equality, never matched name by name.** It used to build
+     * `new RegExp("\\b" + identifier + "\\b")` per name, and that was wrong twice over for any
+     * identifier containing a `$`, which TypeSpec permits in a model or operation name: `$` is an
+     * anchor in a regular expression, and escaping it alone does not help because `\b` is a WORD
+     * boundary and `$` is not a word character, so `\b\$select\b` cannot match either. Measured on
+     * `op list$Items(...): Item$Ref[]`, every identifier reported ABSENT, the whole
+     * `./schemas.gen.js` import was dropped, and the emitted file failed with four
+     * `TS2304: Cannot find name`. No diagnostic anywhere.
+     *
+     * Splitting on the language's own identifier rule and testing membership has neither failure: no
+     * metacharacter can be misread, and `Foo` cannot match `FooExtra`.
      */
     const rendered = [...registrations.map((r) => r.text), ...methods, ...aliases].join("\n");
+    const mentioned = new Set(rendered.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []);
     const referenced = [
         ...new Set(entries.flatMap((entry) => [
             entry.names.path,
@@ -606,7 +633,7 @@ securityFor) {
             entry.names.responses,
         ].filter((name) => name !== undefined))),
     ]
-        .filter((identifier) => new RegExp(`\\b${identifier}\\b`).test(rendered))
+        .filter((identifier) => mentioned.has(identifier))
         .toSorted();
     const imports = referenced.length === 0
         ? ""
@@ -656,8 +683,26 @@ securityFor) {
     // Imported only where a route actually negotiates: an unused import fails the repo's own lint.
     const negotiates = [...grouped.values()].some((group) => group.length > 1);
     // Same rule: imported only where a HEAD operation stands alone on its path.
-    const guardsHead = registrations.some((registration) => registration.text.includes("headOnly,"));
-    const dispatchesBody = registrations.some((r) => r.text.includes("byContentType(["));
+    const guardsHead = registrations.some((registration) => registration.headOnly);
+    /**
+     * **Which runtime imports to write is read from the DATA, never from the rendered text.**
+     *
+     * Matching a substring of generated output is how one of these went missing already: it tested for
+     * `byContentType([`, the emitted call gained arguments before its bracket, the substring stopped
+     * matching, the import stopped being written, and the emitted module threw
+     * `ReferenceError: byContentType is not defined` at registration. Nothing in the emitter objected,
+     * because the check was a string about a string.
+     *
+     * `guardsHead` above had the same shape, and the sibling library had it in a worse place, deciding
+     * whether a parameter gets a wire decoder by `declared.startsWith("z.number()")`. A literal union
+     * (`@query size: 10 | 25 | 50`) begins with neither prefix, so every conformant caller of that
+     * parameter got a 400 that no document comparison could see.
+     *
+     * The rendered text is still read to decide which VALIDATOR identifiers to import, and that one is
+     * safe in a way these are not: an identifier absent from the text is genuinely not needed, so the
+     * check cannot be wrong in the direction that breaks a build.
+     */
+    const dispatchesBody = entries.some((entry) => entry.dispatched !== undefined);
     const runtimeModule = JSON.stringify(emitted.options.runtimeModule);
     /**
      * **One base sub-app, mounted with `app.route()`. Hono's own nesting, not a rewritten path on

package/dist/src/runtime.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { ZodType } from "zod";
+import type { input, output, ZodType } from "zod";
 /**
  * One arm of an operation's declared response set, as the document publishes it.
  *
@@ -116,6 +116,11 @@ export declare function selectContentType(accept: string | undefined, offered: r
  * type. Measured: `hc<typeof app>` resolved a wrapped route's body to `unknown`.
  */
 export declare const headOnly: MiddlewareHandler;
+/**
+ * The `zValidator` targets a request BODY can be read from. Hono extracts `"json"` with
+ * `c.req.json()` and `"form"` with `c.req.parseBody()`, and those are the only two that read a body.
+ */
+export type BodyTarget = "json" | "form";
 /**
  * Apply the validator that parses the media type the request actually carries.
  *
@@ -134,12 +139,30 @@ export declare const headOnly: MiddlewareHandler;
  * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
  * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
  * No status is invented here that the document does not describe.
+ *
+ * **The validated body is published under `"json"` whichever parser produced it**, and that is what
+ * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
+ * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
+ * slot this emitter reads a body from, and using it here means the handler spreads one
+ * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
+ *
+ * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
+ * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
+ * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
+ * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
+ * handler's declared input type omitted the body entirely because the body was not among the route's
+ * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
  */
-export declare function byContentType<E extends Env>(validators: readonly (readonly [
-    mediaType: string,
-    target: string,
-    validator: MiddlewareHandler<E>
-])[]): MiddlewareHandler<E>;
+export declare function byContentType<E extends Env, S extends ZodType>(schema: S, invalid: <P extends string, I extends Input>(result: {
+    readonly success: boolean;
+}, c: Context<E, P, I>) => Response | undefined, branches: readonly (readonly [mediaType: string, target: BodyTarget])[]): MiddlewareHandler<E, string, {
+    in: {
+        json: input<S>;
+    };
+    out: {
+        json: output<S>;
+    };
+}>;
 /**
  * What the app provides. One object, passed once, rather than a module the generated file imports by
  * path. A generated server that hard-codes `../../backend.js` is only usable by the project it was

package/dist/src/runtime.js

@@ -1,3 +1,4 @@
+import { HTTPException } from "hono/http-exception";
 /**
  * The arm that applies to a status, preferring an exact code, then its `NXX` range, then `default`.
  *
@@ -80,6 +81,31 @@ export function selectContentType(accept, offered) {
  * type. Measured: `hc<typeof app>` resolved a wrapped route's body to `unknown`.
  */
 export const headOnly = async (c, next) => c.req.method === "HEAD" ? next() : c.notFound();
+/**
+ * The request body, read the way the target says to read it.
+ *
+ * The same two readers Hono's own `validator` uses, and the same rejection for a body that is not
+ * the JSON it claims to be. `parseBody({ all: true })` builds the object Hono's `"form"` target
+ * builds: a repeated key and a `key[]` name both become an array, everything else stays a string.
+ */
+async function readBody(c, target) {
+    if (target === "form")
+        return c.req.parseBody({ all: true });
+    try {
+        return await c.req.json();
+    }
+    catch {
+        throw new HTTPException(400, { message: "Malformed JSON in request body" });
+    }
+}
+/**
+ * The slot a validated request body is published under, whichever parser produced it.
+ *
+ * `ValidationTargets` is a closed union in Hono, so a body cannot be given a name of its own. This
+ * is the slot the generated code already reads a body from when one media type is declared, so using
+ * it for a dispatched body is what keeps the two cases identical downstream.
+ */
+const BODY_TARGET = "json";
 /**
  * Apply the validator that parses the media type the request actually carries.
  *
@@ -98,12 +124,53 @@ export const headOnly = async (c, next) => c.req.method === "HEAD" ? next() : c.
  * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
  * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
  * No status is invented here that the document does not describe.
+ *
+ * **The validated body is published under `"json"` whichever parser produced it**, and that is what
+ * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
+ * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
+ * slot this emitter reads a body from, and using it here means the handler spreads one
+ * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
+ *
+ * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
+ * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
+ * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
+ * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
+ * handler's declared input type omitted the body entirely because the body was not among the route's
+ * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
  */
-export function byContentType(validators) {
+export function byContentType(schema, invalid, branches) {
     return async (c, next) => {
         const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
-        const matched = validators.find(([mediaType]) => mediaType.toLowerCase() === declared);
-        const [, , validator] = matched ?? validators[0];
-        return validator(c, next);
+        const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
+        const [, target] = matched ?? branches[0];
+        /**
+         * **Registered against the body slot whichever parser runs**, so the validated body is
+         * published under one target and the handler reads it exactly as it reads a single-media-type
+         * one. Hono's `validator` is what `@hono/zod-validator` is built on, so this is the same
+         * extraction, the same `HTTPException` on malformed JSON, and the same default rejection.
+         *
+         * `validator("json", ...)` hands over `{}` rather than throwing when the request is not JSON,
+         * because it checks the `Content-Type` before reading. That is what leaves room for the form
+         * branch to read the body itself with `c.req.parseBody({ all: true })`, which builds the same
+         * object hono's own `"form"` target builds: a repeated key and a `key[]` name both become an
+         * array, everything else stays a string.
+         *
+         * Annotated rather than inlined because `Context` is invariant in its environment and in its
+         * `Input`, and `validator` infers the first as `any`. Same reason `RouteDeps` is parameterised.
+         */
+        const parse = async (ctx, proceed) => {
+            const result = await schema.safeParseAsync(await readBody(ctx, target));
+            const response = invalid(result, ctx);
+            if (response !== undefined)
+                return response;
+            // `zValidator`'s own answer when a hook declines to, kept identical so a dispatched route
+            // and a single-media-type one reject a bad body the same way.
+            if (!result.success)
+                return ctx.json(result, 400);
+            ctx.req.addValidatedData(BODY_TARGET, result.data ?? {});
+            await proceed();
+            return undefined;
+        };
+        return parse(c, next);
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "TypeSpec emitter: generate a Hono server, and the Zod validators it enforces, from an HTTP service definition, agreeing with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "cloudflare-workers",
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.4.0"
+    "typespec-http-zod": "^0.6.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",

package/src/runtime.ts

@@ -1,5 +1,6 @@
+import { HTTPException } from "hono/http-exception";
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
-import type { ZodType } from "zod";
+import type { input, output, ZodType } from "zod";
 
 /**
  * One arm of an operation's declared response set, as the document publishes it.
@@ -164,6 +165,37 @@ export function selectContentType(
 export const headOnly: MiddlewareHandler = async (c, next) =>
 	c.req.method === "HEAD" ? next() : c.notFound();
 
+/**
+ * The `zValidator` targets a request BODY can be read from. Hono extracts `"json"` with
+ * `c.req.json()` and `"form"` with `c.req.parseBody()`, and those are the only two that read a body.
+ */
+export type BodyTarget = "json" | "form";
+
+/**
+ * The request body, read the way the target says to read it.
+ *
+ * The same two readers Hono's own `validator` uses, and the same rejection for a body that is not
+ * the JSON it claims to be. `parseBody({ all: true })` builds the object Hono's `"form"` target
+ * builds: a repeated key and a `key[]` name both become an array, everything else stays a string.
+ */
+async function readBody(c: Context, target: BodyTarget): Promise<unknown> {
+	if (target === "form") return c.req.parseBody({ all: true });
+	try {
+		return await c.req.json();
+	} catch {
+		throw new HTTPException(400, { message: "Malformed JSON in request body" });
+	}
+}
+
+/**
+ * The slot a validated request body is published under, whichever parser produced it.
+ *
+ * `ValidationTargets` is a closed union in Hono, so a body cannot be given a name of its own. This
+ * is the slot the generated code already reads a body from when one media type is declared, so using
+ * it for a dispatched body is what keeps the two cases identical downstream.
+ */
+const BODY_TARGET = "json";
+
 /**
  * Apply the validator that parses the media type the request actually carries.
  *
@@ -182,19 +214,63 @@ export const headOnly: MiddlewareHandler = async (c, next) =>
  * A `Content-Type` matching nothing declared falls through to the first validator, which reproduces
  * the previous behaviour exactly for that case: the body fails to parse and `deps.invalid` answers.
  * No status is invented here that the document does not describe.
+ *
+ * **The validated body is published under `"json"` whichever parser produced it**, and that is what
+ * makes a dispatched route the same shape as every other one downstream. `ValidationTargets` is a
+ * closed union in Hono, so there is no seventh name to coin for "the body"; `"json"` is already the
+ * slot this emitter reads a body from, and using it here means the handler spreads one
+ * `c.req.valid("json")` exactly as it does for a route declaring a single media type.
+ *
+ * **The alternative was a middleware that publishes under whichever target ran**, and it was worse
+ * in two ways that both shipped. `byContentType` was a bare `MiddlewareHandler`, which contributes no
+ * `Input` to the chain, so the generated `c.req.valid("json")` did not compile at all
+ * (`TS2345: Argument of type '"json"' is not assignable to parameter of type '"header"'`), and the
+ * handler's declared input type omitted the body entirely because the body was not among the route's
+ * ordinary validators. Publishing to one known slot removes both, rather than typing around them.
  */
-export function byContentType<E extends Env>(
-	validators: readonly (readonly [
-		mediaType: string,
-		target: string,
-		validator: MiddlewareHandler<E>,
-	])[],
-): MiddlewareHandler<E> {
+export function byContentType<E extends Env, S extends ZodType>(
+	schema: S,
+	invalid: <P extends string, I extends Input>(
+		result: { readonly success: boolean },
+		c: Context<E, P, I>,
+	) => Response | undefined,
+	branches: readonly (readonly [mediaType: string, target: BodyTarget])[],
+): MiddlewareHandler<E, string, { in: { json: input<S> }; out: { json: output<S> } }> {
 	return async (c, next) => {
 		const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
-		const matched = validators.find(([mediaType]) => mediaType.toLowerCase() === declared);
-		const [, , validator] = matched ?? (validators[0] as (typeof validators)[number]);
-		return validator(c, next);
+		const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
+		const [, target] = matched ?? (branches[0] as (typeof branches)[number]);
+		/**
+		 * **Registered against the body slot whichever parser runs**, so the validated body is
+		 * published under one target and the handler reads it exactly as it reads a single-media-type
+		 * one. Hono's `validator` is what `@hono/zod-validator` is built on, so this is the same
+		 * extraction, the same `HTTPException` on malformed JSON, and the same default rejection.
+		 *
+		 * `validator("json", ...)` hands over `{}` rather than throwing when the request is not JSON,
+		 * because it checks the `Content-Type` before reading. That is what leaves room for the form
+		 * branch to read the body itself with `c.req.parseBody({ all: true })`, which builds the same
+		 * object hono's own `"form"` target builds: a repeated key and a `key[]` name both become an
+		 * array, everything else stays a string.
+		 *
+		 * Annotated rather than inlined because `Context` is invariant in its environment and in its
+		 * `Input`, and `validator` infers the first as `any`. Same reason `RouteDeps` is parameterised.
+		 */
+		const parse: MiddlewareHandler<
+			E,
+			string,
+			{ in: { json: input<S> }; out: { json: output<S> } }
+		> = async (ctx, proceed) => {
+			const result = await schema.safeParseAsync(await readBody(ctx, target));
+			const response = invalid(result, ctx);
+			if (response !== undefined) return response;
+			// `zValidator`'s own answer when a hook declines to, kept identical so a dispatched route
+			// and a single-media-type one reject a bad body the same way.
+			if (!result.success) return ctx.json(result, 400);
+			ctx.req.addValidatedData(BODY_TARGET, result.data ?? {});
+			await proceed();
+			return undefined;
+		};
+		return parse(c, next);
 	};
 }