typespec-hono 0.14.0 → 0.16.0

package/dist/src/app.js

@@ -375,11 +375,68 @@ securityFor) {
             : validated === undefined
                 ? negotiated
                 : `${validated} & ${negotiated}`;
-        const output = names.response === undefined ? "void" : `z.infer<typeof ${names.response}>`;
+        /**
+         * **The RETURN type drops index signatures; the input type keeps them.**
+         *
+         * A handler receives whatever the validator let through, and an open model's validator really
+         * does pass unknown keys along - so the input saying `[key: string]: unknown` describes the
+         * value in hand. Returning is the opposite direction: the handler supplies a value the
+         * application already holds, and an index signature there is an obligation rather than a
+         * description. TypeScript gives an interface no implicit index signature, so a domain type
+         * could not satisfy it without a spread at every level of the tree.
+         *
+         * `typespec-http-zod@0.17.0` took the catchall off the contract types for this reason. It did
+         * not reach here, because this signature is derived from `z.infer` rather than from those
+         * types - which is exactly the half-fix `test/openmodel/` now guards against.
+         */
+        const output = names.response === undefined ? "void" : `Declared<z.infer<typeof ${names.response}>>`;
         const signature = input === undefined ? "ctx: Ctx" : `ctx: Ctx, input: ${input}`;
         const doc = route.summary === undefined ? "" : `\t/** ${route.summary} */\n`;
         return `${doc}\t${route.operationId}(${signature}): Awaitable<Result<${output}>>;`;
     });
+    /**
+     * Emitted only when an operation actually returns something, because a generated file has to pass
+     * `noUnusedLocals` like any other - the lint that has already failed this emitter twice over an
+     * import written for a construct the service did not use.
+     *
+     * **Decided from the routes, not by searching the rendered text.** Asking whether the output
+     * 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 returnsAnything = entries.some((entry) => entry.names.response !== undefined);
+    const declaredHelper = returnsAnything
+        ? `/**
+ * A shape with its index signatures removed, at every depth.
+ *
+ * An open model - one declared with \`...Record<T>\` - infers \`[key: string]: unknown\`, because its
+ * validator really does pass unknown keys through. That is true of what a handler RECEIVES, so the
+ * input types above keep it. It is not true of what a handler must SUPPLY: TypeScript gives an
+ * interface no implicit index signature, so a domain type could not be returned without spreading
+ * every level of the tree, which on one real service meant a structural deep copy per response.
+ *
+ * Returning extra properties still works - excess-property checks apply to object literals, not to
+ * a value the application already holds.
+ */
+type Declared<T> = T extends (...args: never[]) => unknown
+	? T
+	: T extends readonly (infer Element)[]
+		? T extends Element[]
+			? Declared<Element>[]
+			: readonly Declared<Element>[]
+		: T extends object
+			? {
+					[K in keyof T as string extends K
+						? never
+						: number extends K
+							? never
+							: symbol extends K
+								? never
+								: K]: Declared<T[K]>;
+				}
+			: T;
+
+`
+        : "";
     const aliases = entries.map((entry) => `export type ${capitaliseId(entry.route.operationId)}Handler = Operations[${JSON.stringify(entry.route.operationId)}];`);
     /**
      * **Which resources get a sub-app, and which routes stay on the root.**
@@ -808,7 +865,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.
  */
-export interface Operations {
+${declaredHelper}export interface Operations {
 ${methods.join("\n")}
 }
 

package/dist/src/runtime.d.ts

@@ -108,13 +108,23 @@ export type Awaitable<T> = T | Promise<T>;
  *
  * The rules that matter, and that a naive `includes()` gets wrong:
  * - **absent or empty `Accept` means anything is acceptable**, serve the first offer;
- * - **`q=0` is a REFUSAL**, not a weak preference, so a range scoring zero can never be chosen;
- * - **specificity breaks ties before quality does**: an exact type beats a subtype wildcard
- *   (`text/*`), which beats the fully wildcard range, at equal `q`. That is why the score is a
- *   pair rather than a number. The fully wildcard range is not written literally here because it
- *   would close this comment;
+ * - **specificity SELECTS which rule applies, before quality is read at all.** For each offered
+ *   type, the most specific range that matches it decides its quality: an exact type beats a
+ *   subtype wildcard (`text/*`), which beats the fully wildcard range. The fully wildcard range is
+ *   not written literally here because it would close this comment;
+ * - **`q=0` is a REFUSAL**, not a weak preference, so a type whose applicable rule scores zero is
+ *   never chosen;
+ * - equal quality keeps the order the document offers, so nothing in the header displaces it;
+ * - a malformed `q` is IGNORED rather than read as zero - a typo should not turn into a 406;
  * - parameters after the media range (`;charset=utf-8`) are not part of the match.
  *
+ * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
+ * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
+ * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
+ * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
+ * right rules the whole time; nothing compared it to the code.
+ *
  * Returns `undefined` when nothing offered is acceptable. The caller answers 406, and the
  * difference between "no preference" and "no acceptable option" is exactly what that turns on.
  */
@@ -177,7 +187,17 @@ export type BodyTarget = "json" | "form";
  */
 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, {
+}, c: Context<E, P, I>) => Response | undefined, 
+/**
+ * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
+ * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
+ * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
+ * declaring at least one request media type - and removes the cast rather than typing around it.
+ */
+branches: readonly [
+    readonly [mediaType: string, target: BodyTarget],
+    ...(readonly [mediaType: string, target: BodyTarget])[]
+]): MiddlewareHandler<E, string, {
     in: {
         json: input<S>;
     };

package/dist/src/runtime.js

@@ -22,13 +22,23 @@ export function armFor(arms, status) {
  *
  * The rules that matter, and that a naive `includes()` gets wrong:
  * - **absent or empty `Accept` means anything is acceptable**, serve the first offer;
- * - **`q=0` is a REFUSAL**, not a weak preference, so a range scoring zero can never be chosen;
- * - **specificity breaks ties before quality does**: an exact type beats a subtype wildcard
- *   (`text/*`), which beats the fully wildcard range, at equal `q`. That is why the score is a
- *   pair rather than a number. The fully wildcard range is not written literally here because it
- *   would close this comment;
+ * - **specificity SELECTS which rule applies, before quality is read at all.** For each offered
+ *   type, the most specific range that matches it decides its quality: an exact type beats a
+ *   subtype wildcard (`text/*`), which beats the fully wildcard range. The fully wildcard range is
+ *   not written literally here because it would close this comment;
+ * - **`q=0` is a REFUSAL**, not a weak preference, so a type whose applicable rule scores zero is
+ *   never chosen;
+ * - equal quality keeps the order the document offers, so nothing in the header displaces it;
+ * - a malformed `q` is IGNORED rather than read as zero - a typo should not turn into a 406;
  * - parameters after the media range (`;charset=utf-8`) are not part of the match.
  *
+ * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
+ * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
+ * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
+ * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
+ * right rules the whole time; nothing compared it to the code.
+ *
  * Returns `undefined` when nothing offered is acceptable. The caller answers 406, and the
  * difference between "no preference" and "no acceptable option" is exactly what that turns on.
  */
@@ -43,22 +53,35 @@ export function selectContentType(accept, offered) {
         const quality = parameters
             .map((parameter) => /^q=(?<value>[\d.]+)$/i.exec(parameter)?.groups?.value)
             .find((value) => value !== undefined);
-        return { range: range.toLowerCase(), q: quality === undefined ? 1 : Number(quality) };
+        const q = quality === undefined ? 1 : Number(quality);
+        // A malformed `q` is treated as unstated. Reading `q=1.2.3` as zero would 406 a typo.
+        return { range: range.toLowerCase(), q: Number.isFinite(q) ? q : 1 };
     });
     let best;
     for (const type of offered) {
-        const [group] = type.toLowerCase().split("/");
+        const lowered = type.toLowerCase();
+        const [group] = lowered.split("/");
+        /**
+         * **The most specific matching range decides this type's quality**, which is what makes an
+         * explicit `application/json;q=0` beat a wildcard that would otherwise accept it. Reading the
+         * best-scoring range instead lets a permissive rule override a precise one.
+         */
+        let applicable;
         for (const { range, q } of ranges) {
-            // `q=0` is "I will not accept this", so it never becomes a candidate.
-            if (!Number.isFinite(q) || q <= 0)
-                continue;
-            const specificity = range === type.toLowerCase() ? 2 : range === `${group}/*` ? 1 : range === "*/*" ? 0 : -1;
+            const specificity = range === lowered ? 2 : range === `${group}/*` ? 1 : range === "*/*" ? 0 : -1;
             if (specificity < 0)
                 continue;
-            if (best === undefined || q > best.q || (q === best.q && specificity > best.specificity)) {
-                best = { type, q, specificity };
+            // Strictly greater, so two rules of equal specificity leave the first one in force.
+            if (applicable === undefined || specificity > applicable.specificity) {
+                applicable = { q, specificity };
             }
         }
+        // `q=0` is "I will not accept this", so a type its own rule scores zero is never a candidate.
+        if (applicable === undefined || applicable.q <= 0)
+            continue;
+        // Strictly greater, so equal quality keeps the order the document offers.
+        if (best === undefined || applicable.q > best.q)
+            best = { type, q: applicable.q };
     }
     return best?.type;
 }
@@ -138,7 +161,14 @@ const BODY_TARGET = "json";
  * 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(schema, invalid, branches) {
+export function byContentType(schema, invalid, 
+/**
+ * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
+ * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
+ * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
+ * declaring at least one request media type - and removes the cast rather than typing around it.
+ */
+branches) {
     return async (c, next) => {
         const declared = (c.req.header("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
         const matched = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
@@ -149,14 +179,14 @@ export function byContentType(schema, invalid, branches) {
          * 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.
+         * **Hono's own `validator` is deliberately not called here.** Its target fixes the reader at
+         * registration time, and the whole point of this function is that the reader is chosen when the
+         * request arrives. What it does instead is reproduce `validator`'s observable behaviour for both
+         * targets: {@link readBody} performs the same two extractions and raises the same
+         * `HTTPException` on malformed JSON, and the rejection below is `zValidator`'s own.
          *
          * 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.
+         * `Input`. Same reason `RouteDeps` is parameterised.
          */
         const parse = async (ctx, proceed) => {
             const result = await schema.safeParseAsync(await readBody(ctx, target));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.14.0",
+  "version": "0.16.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.16.0"
+    "typespec-http-zod": "^0.17.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",

package/src/runtime.ts

@@ -120,13 +120,23 @@ export type Awaitable<T> = T | Promise<T>;
  *
  * The rules that matter, and that a naive `includes()` gets wrong:
  * - **absent or empty `Accept` means anything is acceptable**, serve the first offer;
- * - **`q=0` is a REFUSAL**, not a weak preference, so a range scoring zero can never be chosen;
- * - **specificity breaks ties before quality does**: an exact type beats a subtype wildcard
- *   (`text/*`), which beats the fully wildcard range, at equal `q`. That is why the score is a
- *   pair rather than a number. The fully wildcard range is not written literally here because it
- *   would close this comment;
+ * - **specificity SELECTS which rule applies, before quality is read at all.** For each offered
+ *   type, the most specific range that matches it decides its quality: an exact type beats a
+ *   subtype wildcard (`text/*`), which beats the fully wildcard range. The fully wildcard range is
+ *   not written literally here because it would close this comment;
+ * - **`q=0` is a REFUSAL**, not a weak preference, so a type whose applicable rule scores zero is
+ *   never chosen;
+ * - equal quality keeps the order the document offers, so nothing in the header displaces it;
+ * - a malformed `q` is IGNORED rather than read as zero - a typo should not turn into a 406;
  * - parameters after the media range (`;charset=utf-8`) are not part of the match.
  *
+ * **Specificity was implemented as a tie-break and that was wrong three ways at once**, all of them
+ * live in a published runtime until `test/negotiation.test.ts` was written. Scoring every matching
+ * range and keeping the best `(q, specificity)` pair lets a permissive wildcard out-vote the precise
+ * rule a caller wrote about that exact type - so `Accept: *​/*, application/json;q=0` was served
+ * JSON, which is the one outcome an explicit refusal must never produce. The prose above stated the
+ * right rules the whole time; nothing compared it to the code.
+ *
  * Returns `undefined` when nothing offered is acceptable. The caller answers 406, and the
  * difference between "no preference" and "no acceptable option" is exactly what that turns on.
  */
@@ -143,22 +153,34 @@ export function selectContentType(
 		const quality = parameters
 			.map((parameter) => /^q=(?<value>[\d.]+)$/i.exec(parameter)?.groups?.value)
 			.find((value) => value !== undefined);
-		return { range: range.toLowerCase(), q: quality === undefined ? 1 : Number(quality) };
+		const q = quality === undefined ? 1 : Number(quality);
+		// A malformed `q` is treated as unstated. Reading `q=1.2.3` as zero would 406 a typo.
+		return { range: range.toLowerCase(), q: Number.isFinite(q) ? q : 1 };
 	});
 
-	let best: { type: string; q: number; specificity: number } | undefined;
+	let best: { type: string; q: number } | undefined;
 	for (const type of offered) {
-		const [group] = type.toLowerCase().split("/");
+		const lowered = type.toLowerCase();
+		const [group] = lowered.split("/");
+		/**
+		 * **The most specific matching range decides this type's quality**, which is what makes an
+		 * explicit `application/json;q=0` beat a wildcard that would otherwise accept it. Reading the
+		 * best-scoring range instead lets a permissive rule override a precise one.
+		 */
+		let applicable: { q: number; specificity: number } | undefined;
 		for (const { range, q } of ranges) {
-			// `q=0` is "I will not accept this", so it never becomes a candidate.
-			if (!Number.isFinite(q) || q <= 0) continue;
 			const specificity =
-				range === type.toLowerCase() ? 2 : range === `${group}/*` ? 1 : range === "*/*" ? 0 : -1;
+				range === lowered ? 2 : range === `${group}/*` ? 1 : range === "*/*" ? 0 : -1;
 			if (specificity < 0) continue;
-			if (best === undefined || q > best.q || (q === best.q && specificity > best.specificity)) {
-				best = { type, q, specificity };
+			// Strictly greater, so two rules of equal specificity leave the first one in force.
+			if (applicable === undefined || specificity > applicable.specificity) {
+				applicable = { q, specificity };
 			}
 		}
+		// `q=0` is "I will not accept this", so a type its own rule scores zero is never a candidate.
+		if (applicable === undefined || applicable.q <= 0) continue;
+		// Strictly greater, so equal quality keeps the order the document offers.
+		if (best === undefined || applicable.q > best.q) best = { type, q: applicable.q };
 	}
 	return best?.type;
 }
@@ -253,26 +275,35 @@ export function byContentType<E extends Env, S extends ZodType>(
 		result: { readonly success: boolean },
 		c: Context<E, P, I>,
 	) => Response | undefined,
-	branches: readonly (readonly [mediaType: string, target: BodyTarget])[],
+	/**
+	 * **A NON-EMPTY list, stated in the type.** The fallback below reads the first branch, and
+	 * `branches[0]` on a plain array is `T | undefined`, which was silenced with a cast. A tuple says
+	 * the same thing the emitter already guarantees - this middleware is only ever emitted for a route
+	 * declaring at least one request media type - and removes the cast rather than typing around it.
+	 */
+	branches: readonly [
+		readonly [mediaType: string, target: BodyTarget],
+		...(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 = branches.find(([mediaType]) => mediaType.toLowerCase() === declared);
-		const [, target] = matched ?? (branches[0] as (typeof branches)[number]);
+		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.
+		 * **Hono's own `validator` is deliberately not called here.** Its target fixes the reader at
+		 * registration time, and the whole point of this function is that the reader is chosen when the
+		 * request arrives. What it does instead is reproduce `validator`'s observable behaviour for both
+		 * targets: {@link readBody} performs the same two extractions and raises the same
+		 * `HTTPException` on malformed JSON, and the rejection below is `zValidator`'s own.
 		 *
 		 * 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.
+		 * `Input`. Same reason `RouteDeps` is parameterised.
 		 */
 		const parse: MiddlewareHandler<
 			E,