typespec-hono 0.18.1 → 0.19.0

package/dist/src/app.js

@@ -181,10 +181,31 @@ function bodyValidationFor(contentTypes) {
  * `isRawBinaryMediaType` is the library's own rule for telling them apart, already applied on the
  * response side; importing it rather than re-deriving it is what keeps the two halves from disagreeing
  * again.
+ *
+ * **A binary body is handed over as the UNREAD stream, not as an `ArrayBuffer`.** `arrayBuffer()`
+ * materialises the whole payload in the isolate, and a Worker gets 128 MB against a request-body
+ * limit of 100 MB, so an upload at the documented maximum cannot be served at all. The document
+ * publishes only `contentMediaType` for such a body - **nothing a validator can check** - so
+ * materialising it produced a value nothing validates, at the cost of the one thing a gateway
+ * actually wants to do with it: pipe it somewhere without touching it.
+ *
+ * Handing over the stream is strictly more capable. A handler wanting the bytes writes
+ * `await new Response(input.body).arrayBuffer()`; a handler wanting to stream into R2 pipes it. The
+ * reverse was not possible.
+ *
+ * **It costs no ambient dependency, which was assumed to be a trade and then measured.**
+ * `ReadableStream` needs `lib.dom`, `@cloudflare/workers-types` or `@types/node` - and the generated
+ * server has needed exactly the same lib since it was first emitted, because it names `Response`.
+ * Whatever a project already supplies to satisfy that declares `ReadableStream` too, so there is no
+ * project that could build the old output and cannot build this. `test/streambody/` asserts both
+ * halves; `test/compiles.test.ts` cannot, because it sets `target` without `lib` and TypeScript then
+ * defaults to the `.full` variant, which includes DOM.
+ *
+ * `null` because a request may carry no body at all, which is what the platform reports.
  */
 function rawBodyReaderFor(contentTypes) {
     return isRawBinaryMediaType(contentTypes)
-        ? { call: "await c.req.arrayBuffer()", type: "ArrayBuffer" }
+        ? { call: "c.req.raw.body", type: "ReadableStream<Uint8Array> | null" }
         : { call: "await c.req.text()", type: "string" };
 }
 /**
@@ -195,6 +216,20 @@ function rawBodyReaderFor(contentTypes) {
  * deriving the type from the same consts is what makes the call site check itself. A restated
  * interface would be a second source of truth that drifts.
  */
+/**
+ * The validators whose fields are INTERSECTED into the input, as opposed to named beside it.
+ *
+ * Shared with the decision to emit `Fields<>` at all, so "is this helper used" is answered by the
+ * same code that uses it rather than by searching the rendered output - an unused type declaration
+ * fails `noUnusedLocals`, which a generated file has to pass like any other.
+ */
+function intersectedValidatorsOf(entry) {
+    const bodyProperty = entry.route.bodyProperty;
+    const bodyName = entry.names.body;
+    return entry.validators
+        .filter(([, name]) => bodyProperty === undefined || name !== bodyName)
+        .map(([, name]) => name);
+}
 function inputTypeOf(entry) {
     /**
      * **A body the document says must not be flattened is NAMED, not intersected.**
@@ -215,11 +250,30 @@ function inputTypeOf(entry) {
      * identifier is the same fact whichever parser reads it.
      */
     const bodyName = entry.names.body;
-    const parts = entry.validators
-        .filter(([, name]) => bodyProperty === undefined || name !== bodyName)
-        .map(([, name]) => `z.infer<typeof ${name}>`);
+    /**
+     * **`Fields<>` is what stops an EMPTY validator poisoning the intersection.**
+     *
+     * Zod 4 infers `Record<string, never>` for `z.object({})` - "no string key may exist" - which is
+     * a correct reading of an empty object on its own and lethal in an intersection: `{ id: string }
+     * & Record<string, never>` makes `id` into `string & never`, so the input type is uninhabitable
+     * and the generated call site fails `tsc` inside `app.gen.ts` itself. Measured on
+     * `model Empty {}` as an optional body: `TS2345: Argument of type '{ id: string; }' is not
+     * assignable to parameter of type '{ id: string; } & Record<string, never>'`.
+     *
+     * The emitted server not compiling is the worst shape available to this emitter, and no arm saw
+     * it because no fixture declared an empty model.
+     */
+    const parts = intersectedValidatorsOf(entry).map((name) => `Fields<z.infer<typeof ${name}>>`);
     if (bodyProperty !== undefined && bodyName !== undefined) {
-        parts.push(`{ ${objectKey(bodyProperty)}: z.infer<typeof ${bodyName}> }`);
+        /**
+         * **Optional on the input when the document says the body is optional**, which is the whole
+         * reason such a body is named rather than merged: `c.req.valid(...)` reads `undefined` when
+         * none arrived, and a merge has no way to say that. Spelled `| undefined` as every other
+         * optional here is, because `exactOptionalPropertyTypes` is on.
+         */
+        const optionalMark = entry.route.optionalBody ? "?" : "";
+        const optionalValue = entry.route.optionalBody ? " | undefined" : "";
+        parts.push(`{ ${objectKey(bodyProperty)}${optionalMark}: z.infer<typeof ${bodyName}>${optionalValue} }`);
     }
     if (entry.route.rawBodyProperty !== undefined) {
         const reader = rawBodyReaderFor(entry.route.requestContentTypes);
@@ -310,6 +364,7 @@ securityFor) {
         if (names === undefined)
             return [];
         const validators = [];
+        let optional;
         for (const location of ["path", "query", "header", "body"]) {
             const identifier = names[location];
             if (identifier === undefined)
@@ -330,6 +385,35 @@ securityFor) {
                 continue;
             const targets = [...new Set(body.byType.map(([, target]) => target))];
             if (targets.length === 1) {
+                /**
+                 * **An optional body is mounted by `optionalBody`, not `zValidator`**, so a request
+                 * carrying none is let through instead of refused - see the runtime's docblock for the
+                 * 400 that produced. It publishes under the canonical body slot whichever parser read
+                 * it, exactly as `byContentType` does, so the handler reads it the same way everywhere.
+                 */
+                if (route.optionalBody) {
+                    validators.push([VALIDATOR_TARGET.body, identifier]);
+                    optional = { target: targets[0], identifier };
+                    continue;
+                }
+                /**
+                 * **A required body keeps `zValidator`, and unifying it was tried and reverted.**
+                 *
+                 * `zValidator` raises `HTTPException` on a body that is not the JSON its content type
+                 * claims, BEFORE `deps.invalid` runs, so that 400 is `text/plain` and escapes the app's
+                 * error envelope. Routing every body through `byContentType` fixes it and is the obvious
+                 * move - one code path, one place the rejection is decided.
+                 *
+                 * **It is a breaking change to the RUNTIME CONTRACT, not just to emitted output.** An app
+                 * that points `runtime-module` at its own module would have to export `byContentType`,
+                 * which today it needs only if some operation declares several request media types - rare
+                 * enough that no consumer exports it. Measured: 15 arms red, every one of them an app
+                 * whose substituted module has no such export.
+                 *
+                 * The envelope gap is real and stays open for a required single-media-type body. Closing
+                 * it wants a form that adds no export to the runtime contract - most likely emitting the
+                 * middleware into `app.gen.ts` itself - and that is its own change, not a line here.
+                 */
                 validators.push([targets[0], identifier]);
                 continue;
             }
@@ -343,7 +427,7 @@ securityFor) {
             validators.push([VALIDATOR_TARGET.body, identifier]);
             dispatched = { byType: body.byType, identifier };
         }
-        return [{ route, names, validators, dispatched }];
+        return [{ route, names, validators, dispatched, optional }];
     });
     const entries = mounted;
     /**
@@ -376,6 +460,29 @@ securityFor) {
      * which is the opposite of the claim being made.
      */
     const EMPTY_INPUT = "Record<string, never>";
+    /**
+     * Emitted only where an operation INTERSECTS a validator's fields, which is what names it.
+     *
+     * Decided from the routes rather than by searching the rendered text - the mistake that once
+     * dropped the `byContentType` import when a call gained an argument.
+     */
+    const usesFields = entries.some((entry) => intersectedValidatorsOf(entry).length > 0);
+    const fieldsHelper = usesFields
+        ? `/**
+ * A validator's fields, or nothing at all when it declares none.
+ *
+ * **Zod 4 infers \`Record<string, never>\` for \`z.object({})\`.** That is a fair reading on its own -
+ * no string key may exist - and lethal in an intersection: \`{ id: string } & Record<string, never>\`
+ * makes \`id\` into \`string & never\`, so the input type is uninhabitable and the call site below
+ * cannot compile. An empty model contributes nothing to an operation's input, and \`unknown\` is the
+ * identity of \`&\`, so that is what it becomes.
+ *
+ * A DICTIONARY body is not this: \`Record<unknown>\` has a value type, so it survives untouched.
+ */
+type Fields<T> = string extends keyof T ? ([T[string]] extends [never] ? unknown : T) : T;
+
+`
+        : "";
     const methods = entries.map((entry) => {
         const { route, names } = entry;
         /**
@@ -419,6 +526,7 @@ securityFor) {
      * mentions a name is how this package lost the `byContentType` import: the call gained an argument
      * and the substring stopped matching, so a module referenced a function it no longer imported.
      */
+    const mountsOptionalBody = entries.some((entry) => entry.optional !== undefined);
     const returnsAnything = entries.some((entry) => entry.names.response !== undefined);
     const declaredHelper = returnsAnything
         ? `/**
@@ -600,10 +708,17 @@ type Produced<T> = T extends (...args: never[]) => unknown
             ...gate,
             ...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)
+                // the body twice and reject every media type but one. An optional body is the same
+                // story with `optionalBody`, which additionally lets a bodyless request through.
+                .filter(([target]) => (entry.dispatched === undefined && entry.optional === undefined) ||
+                target !== VALIDATOR_TARGET.body)
                 .map(([target, name]) => `\t\tzValidator(${JSON.stringify(target)}, ${name}, deps.invalid),`),
             ...dispatch,
+            ...(entry.optional === undefined
+                ? []
+                : [
+                    `\t\toptionalBody(${entry.optional.identifier}, deps.invalid, ${JSON.stringify(entry.optional.target)}),`,
+                ]),
         ];
         /**
          * Whether the operation requires a caller, and NOTHING else about the caller.
@@ -898,7 +1013,7 @@ type Produced<T> = T extends (...args: never[]) => unknown
     const needsHonoValue = subApps.size > 0 || usesBasePath;
     return `${generatedBanner(emitted.options.regenerateHint)}
 ${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
-${usesZod ? 'import { z } from "zod";\n' : ""}import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}
+${usesZod ? 'import { z } from "zod";\n' : ""}import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}${mountsOptionalBody ? `\nimport { optionalBody } from ${runtimeModule};` : ""}
 ${imports}
 /**
  * One method per operation, each concretely typed from the schemas it validates against.
@@ -906,7 +1021,7 @@ ${imports}
  * There is no cast anywhere in this file, and no dynamic lookup: the generated call sites name the
  * method, so an implementation whose input or output does not match the contract fails to compile.
  */
-${declaredHelper}export interface Operations {
+${fieldsHelper}${declaredHelper}export interface Operations {
 ${methods.join("\n")}
 }
 

package/dist/src/runtime.d.ts

@@ -205,6 +205,32 @@ branches: readonly [
         json: output<S>;
     };
 }>;
+/**
+ * Validate a body the document says is OPTIONAL, and let a request carrying none through.
+ *
+ * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
+ * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
+ * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
+ * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
+ * entirely. A service refusing what its own document allows, in a shape that document forbids.
+ *
+ * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
+ * handler is told the truth. That is why an optional body is a NAMED property on the input rather
+ * than merged into it: a merge has no way to say "these are here only sometimes" without making
+ * every one of them optional, which is a weaker and different claim about the body that IS sent.
+ *
+ * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
+ */
+export declare function optionalBody<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, target: BodyTarget): MiddlewareHandler<E, string, {
+    in: {
+        json: input<S> | undefined;
+    };
+    out: {
+        json: output<S> | undefined;
+    };
+}>;
 /**
  * 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,4 +1,3 @@
-import { HTTPException } from "hono/http-exception";
 /**
  * The arm that applies to a status, preferring an exact code, then its `NXX` range, then `default`.
  *
@@ -111,6 +110,7 @@ export const headOnly = async (c, next) => c.req.method === "HEAD" ? next() : c.
  * 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.
  */
+const UNREADABLE = Symbol("a body that is not what its content type claims");
 async function readBody(c, target) {
     if (target === "form")
         return c.req.parseBody({ all: true });
@@ -118,9 +118,26 @@ async function readBody(c, target) {
         return await c.req.json();
     }
     catch {
-        throw new HTTPException(400, { message: "Malformed JSON in request body" });
+        return UNREADABLE;
     }
 }
+/**
+ * The failure a malformed body produces, reported through the app's `invalid` hook like any other.
+ *
+ * **It used to `throw new HTTPException(400)`, which never reaches that hook.** The response was
+ * `text/plain` with a bare message, so an API whose document declares a JSON error envelope answered
+ * a shape its own contract forbids - and the app had no way to intervene, because the throw happened
+ * before its code ran.
+ *
+ * Parsing `undefined` against the body's own schema is what produces a real Zod failure, so
+ * `deps.invalid` receives the shape it receives for every other rejection rather than a special case
+ * it has to know about. A schema that somehow accepts `undefined` still fails here: a body that
+ * could not be read is not a body that validated.
+ */
+async function unreadableResult(schema) {
+    const parsed = await schema.safeParseAsync(undefined);
+    return parsed.success ? { success: false } : parsed;
+}
 /**
  * The slot a validated request body is published under, whichever parser produced it.
  *
@@ -189,7 +206,8 @@ branches) {
          * `Input`. Same reason `RouteDeps` is parameterised.
          */
         const parse = async (ctx, proceed) => {
-            const result = await schema.safeParseAsync(await readBody(ctx, target));
+            const raw = await readBody(ctx, target);
+            const result = raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
             const response = invalid(result, ctx);
             if (response !== undefined)
                 return response;
@@ -197,10 +215,56 @@ branches) {
             // 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 ?? {});
+            ctx.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
             await proceed();
             return undefined;
         };
         return parse(c, next);
     };
 }
+/**
+ * Validate a body the document says is OPTIONAL, and let a request carrying none through.
+ *
+ * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
+ * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
+ * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
+ * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
+ * entirely. A service refusing what its own document allows, in a shape that document forbids.
+ *
+ * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
+ * handler is told the truth. That is why an optional body is a NAMED property on the input rather
+ * than merged into it: a merge has no way to say "these are here only sometimes" without making
+ * every one of them optional, which is a weaker and different claim about the body that IS sent.
+ *
+ * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
+ */
+export function optionalBody(schema, invalid, target) {
+    return async (c, next) => {
+        if (!hasBody(c)) {
+            await next();
+            return undefined;
+        }
+        const raw = await readBody(c, target);
+        const result = raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
+        const response = invalid(result, c);
+        if (response !== undefined)
+            return response;
+        if (!result.success)
+            return c.json(result, 400);
+        c.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
+        await next();
+        return undefined;
+    };
+}
+/**
+ * Whether the request carries a body at all.
+ *
+ * Both halves are load-bearing. The platform reports `null` for a request sent without one, and a
+ * caller may instead send `content-length: 0`, which is a body of no bytes and reads the same way to
+ * anything downstream. Neither alone covers what arrives.
+ */
+function hasBody(c) {
+    if (c.req.raw.body === null)
+        return false;
+    return (c.req.header("content-length") ?? "").trim() !== "0";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.18.1",
+  "version": "0.19.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.19.1"
+    "typespec-http-zod": "^0.20.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",

package/src/runtime.ts

@@ -1,4 +1,3 @@
-import { HTTPException } from "hono/http-exception";
 import type { Context, Env, Input, MiddlewareHandler } from "hono";
 import type { input, output, ZodType } from "zod";
 
@@ -219,15 +218,35 @@ export type BodyTarget = "json" | "form";
  * 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.
  */
+const UNREADABLE = Symbol("a body that is not what its content type claims");
+
 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" });
+		return UNREADABLE;
 	}
 }
 
+/**
+ * The failure a malformed body produces, reported through the app's `invalid` hook like any other.
+ *
+ * **It used to `throw new HTTPException(400)`, which never reaches that hook.** The response was
+ * `text/plain` with a bare message, so an API whose document declares a JSON error envelope answered
+ * a shape its own contract forbids - and the app had no way to intervene, because the throw happened
+ * before its code ran.
+ *
+ * Parsing `undefined` against the body's own schema is what produces a real Zod failure, so
+ * `deps.invalid` receives the shape it receives for every other rejection rather than a special case
+ * it has to know about. A schema that somehow accepts `undefined` still fails here: a body that
+ * could not be read is not a body that validated.
+ */
+async function unreadableResult(schema: ZodType): Promise<{ readonly success: boolean }> {
+	const parsed = await schema.safeParseAsync(undefined);
+	return parsed.success ? { success: false } : parsed;
+}
+
 /**
  * The slot a validated request body is published under, whichever parser produced it.
  *
@@ -310,13 +329,15 @@ export function byContentType<E extends Env, S extends ZodType>(
 			string,
 			{ in: { json: input<S> }; out: { json: output<S> } }
 		> = async (ctx, proceed) => {
-			const result = await schema.safeParseAsync(await readBody(ctx, target));
+			const raw = await readBody(ctx, target);
+			const result =
+				raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
 			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 ?? {});
+			ctx.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
 			await proceed();
 			return undefined;
 		};
@@ -324,6 +345,63 @@ export function byContentType<E extends Env, S extends ZodType>(
 	};
 }
 
+/**
+ * Validate a body the document says is OPTIONAL, and let a request carrying none through.
+ *
+ * **`requestBody.required: false` means a request with no body is one the contract permits**, and a
+ * plain `zValidator` refused it. Measured against @hono/zod-validator 0.9.0 and hono 4.12.26: a
+ * `POST` with `content-type: application/json` and no body answered **400 `Malformed JSON in request
+ * body`** as `text/plain` - raised before the `invalid` hook, so outside the app's error envelope
+ * entirely. A service refusing what its own document allows, in a shape that document forbids.
+ *
+ * **Nothing is published when the body is absent**, so `c.req.valid(...)` reads `undefined` and the
+ * handler is told the truth. That is why an optional body is a NAMED property on the input rather
+ * than merged into it: a merge has no way to say "these are here only sometimes" without making
+ * every one of them optional, which is a weaker and different claim about the body that IS sent.
+ *
+ * A body that is present but unreadable still fails, through `invalid`, so the app's envelope holds.
+ */
+export function optionalBody<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,
+	target: BodyTarget,
+): MiddlewareHandler<
+	E,
+	string,
+	{ in: { json: input<S> | undefined }; out: { json: output<S> | undefined } }
+> {
+	return async (c, next) => {
+		if (!hasBody(c)) {
+			await next();
+			return undefined;
+		}
+		const raw = await readBody(c, target);
+		const result =
+			raw === UNREADABLE ? await unreadableResult(schema) : await schema.safeParseAsync(raw);
+		const response = invalid(result, c as never);
+		if (response !== undefined) return response;
+		if (!result.success) return c.json(result, 400);
+		c.req.addValidatedData(BODY_TARGET, ("data" in result ? result.data : undefined) ?? {});
+		await next();
+		return undefined;
+	};
+}
+
+/**
+ * Whether the request carries a body at all.
+ *
+ * Both halves are load-bearing. The platform reports `null` for a request sent without one, and a
+ * caller may instead send `content-length: 0`, which is a body of no bytes and reads the same way to
+ * anything downstream. Neither alone covers what arrives.
+ */
+function hasBody(c: Context): boolean {
+	if (c.req.raw.body === null) return false;
+	return (c.req.header("content-length") ?? "").trim() !== "0";
+}
+
 /**
  * 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