typespec-hono 0.22.0 → 0.23.0

package/README.md

@@ -58,10 +58,16 @@ model Widget {
   name: string;
 }
 
+@error
+model NotFound {
+  @statusCode statusCode: 404;
+  message: string;
+}
+
 @route("/widgets")
 interface WidgetRoutes {
   @get list(@query limit?: int32): Widget[];
-  @get read(@path id: string): Widget;
+  @get read(@path id: string): Widget | NotFound;
 }
 ```
 
@@ -71,79 +77,108 @@ pnpm exec tsp compile .
 
 ### `src/index.ts`
 
-`input` and the return type are both known from the spec, so a handler that does not match the
-contract does not compile:
+A handler returns `{ status, body }` for any response its operation declares, the failures included.
+`input` and every declared response are known from the spec, so a handler returning a status the spec
+does not declare, or the wrong body for a status, does not compile:
 
 ```ts
 import { Hono } from "hono";
-import { registerRoutes } from "./generated/app.gen.js";
-import { deps } from "./deps.js";
-
-const handlersFor = () => ({
-	WidgetRoutes_list: (ctx, input) => widgets.slice(0, input.limit ?? 20),
-	WidgetRoutes_read: (ctx, input) => widgets.find((w) => w.id === input.id),
-});
+import { registerRoutes, type Operations } from "./generated/app.gen.js";
+import { deps, type Caller } from "./deps.js";
+
+const handlers = {
+	WidgetRoutes_list: (ctx, input) => ({ status: 200, body: widgets.slice(0, input.limit ?? 20) }),
+	WidgetRoutes_read: (ctx, input) => {
+		const widget = widgets.find((w) => w.id === input.id);
+		return widget === undefined
+			? { status: 404, body: { message: `no widget ${input.id}` } }
+			: { status: 200, body: widget };
+	},
+} satisfies Operations<Caller>;
 
-export default registerRoutes(new Hono(), handlersFor, deps);
+export default registerRoutes(new Hono(), () => handlers, deps);
 ```
 
-Leave `handlersFor` unannotated: annotating it widens the value and disables the check that catches a
-handler for an operation the spec no longer declares. It is a factory rather than an object because a
-Workers service binding lives on `c.env` and exists only for the duration of a request.
+`satisfies` keeps each `status` a literal, which is what selects the response it belongs to. Without
+it, `status: 404` widens to `number`, which no declared response admits.
+
+The generated route serves each response with the Hono call for it - `c.json(body, 404)` for the
+failure above - after checking the body against the schema the document publishes for that status. So
+Hono's RPC client narrows a response body by its status, and a body the document does not permit
+reaches `app.onError` as a `ResponseContractError` rather than a caller.
+
+Leave the factory passed to `registerRoutes` unannotated: annotating it widens the value and disables
+the check that catches a handler for an operation the spec no longer declares. It is a factory rather
+than an object because a Workers service binding lives on `c.env` and exists only for the duration of
+a request.
 
 ### `src/deps.ts`
 
-Six hooks, each answering something the spec does not contain:
+Five hooks, each answering something the spec does not contain:
 
-| hook            | the spec says                               | you say                              |
-| --------------- | ------------------------------------------- | ------------------------------------ |
-| `authorize`     | which schemes and scopes an operation needs | whether this caller satisfies them   |
-| `context`       | whether a caller is required                | who the caller is                    |
-| `noContext`     |                                             | what to answer when there is not one |
-| `notAcceptable` | which media types are offered               | what to answer when none match       |
-| `invalid`       | the schema                                  | what a validation failure looks like |
-| `respond`       | every status arm and its schema             | which arm this result is             |
+| hook            | the spec says                                  | you say                              |
+| --------------- | ---------------------------------------------- | ------------------------------------ |
+| `authorize`     | which schemes and scopes an operation needs    | whether this caller satisfies them   |
+| `context`       | whether a caller is none, optional or required | who the caller is                    |
+| `noContext`     |                                                | what to answer when there is not one |
+| `notAcceptable` | which media types are offered                  | what to answer when none match       |
+| `invalid`       | the schema                                     | what a validation failure looks like |
 
 ```ts
-import type { RouteDeps } from "./generated/runtime.gen.js";
+import type { AppEnv, RouteDeps } from "./generated/runtime.gen.js";
 
-export const deps: RouteDeps = {
+export interface Caller {
+	readonly userId: string;
+}
+
+export const deps: RouteDeps<AppEnv, Caller> = {
 	authorize: (requirements) => async (c, next) => {
 		await next();
 	},
-	context: (c) => ({ userId: c.req.header("x-user") }),
+	context: (c) => {
+		const userId = c.req.header("x-user");
+		return userId === undefined ? null : { userId };
+	},
 	noContext: (c) => c.json({ error: "unauthorized" }, 401),
 	notAcceptable: (c, offered) => c.json({ error: "not_acceptable", offered }, 406),
 	invalid: (result, c) => (result.success ? undefined : c.json({ error: "invalid" }, 400)),
-	respond: (c, arms, result) => c.json(result as never, 200),
 };
 ```
 
-Routing, request validation and the handler types come from the spec. What is left is the four files
-above.
+`context` is told `"none"` (the operation needs nobody), `"optional"` (anonymous access is one
+alternative, so read a credential if one was presented) or `"required"`. Whatever it returns is what
+every handler receives as `ctx`. Your Hono environment - bindings
+and variables - is an augmentation of the emitted `AppEnv`:
+
+```ts
+declare module "./generated/runtime.gen.js" {
+	interface AppEnv {
+		Bindings: { DB: D1Database };
+		Variables: { requestId: string };
+	}
+}
+```
+
+Routing, request validation, the handler types and how each declared response is served come from the
+spec. What is left is the four files above.
 
 ## What it emits
 
 Into your output directory:
 
-| file                   | what it is                                                                     |
-| ---------------------- | ------------------------------------------------------------------------------ |
-| `app.gen.ts`           | the server: routes, validators, and the handler interface you implement        |
-| `runtime.gen.ts`       | the types your `deps` implements against, and the helpers the server calls     |
-| `schemas.gen.ts`       | a Zod schema for every request and response, and the status arms each declares |
-| `vocabularies.gen.ts`  | shared enums, where the spec declares them                                     |
-| `requests.gen.ts`      | request types, when `contracts-output-dir` is set                              |
-| `wire-contract.gen.ts` | assertions that the schemas and the types agree, with the same option          |
+| file                   | what it is                                                                       |
+| ---------------------- | -------------------------------------------------------------------------------- |
+| `app.gen.ts`           | the server: routes, validators, what each operation may answer, and the handlers |
+| `runtime.gen.ts`       | the types your `deps` implements against, and the helpers the server calls       |
+| `schemas.gen.ts`       | a Zod schema for every request and response, and the status arms each declares   |
+| `vocabularies.gen.ts`  | shared enums, where the spec declares them                                       |
+| `requests.gen.ts`      | request types, when `contracts-output-dir` is set                                |
+| `wire-contract.gen.ts` | assertions that the schemas and the types agree, with the same option            |
 
 The last four are `typespec-http-zod`'s; see its README for what they contain.
 
-Your own code imports from `runtime.gen.ts`:
-
-```ts
-import type { Ctx, RouteDeps } from "./generated/runtime.gen.js";
-```
-
-Setting `runtime-module` replaces it with a module of your own, and it is then not written.
+`runtime.gen.ts` is written on every compile. Your own code imports from it and augments `AppEnv` in
+it, and nothing replaces it.
 
 Routes are grouped into a sub-app per resource and mounted with `app.route()`, following
 [Hono's best-practices guide](https://hono.dev/docs/guides/best-practices). Handlers are written
@@ -152,27 +187,15 @@ handler in another file cannot infer its path parameters. A resource with a sing
 sub-app.
 
 The output is plain `Hono` and `@hono/zod-validator`, not `@hono/zod-openapi`. That package generates
-a document from the code, which would compete with the one openapi3 publishes from the spec.
-
-```ts
-import { Hono } from "hono";
-import { registerRoutes } from "./generated/app.gen.js";
-
-// Leave handlersFor unannotated. Annotating it widens the value and disables the
-// exhaustiveness check that catches a handler for an operation the spec no longer declares.
-const handlersFor = (c) => backendFor(c.env);
-const routes = registerRoutes(new Hono<AppEnv>(), handlersFor, deps);
-
-export default routes;
-```
-
-`handlersFor` is a factory rather than an object because a Workers service binding lives on `c.env`
-and exists only for the duration of a request.
+a document from the code, which would compete with the one openapi3 publishes from the spec. The
+responses a route serves are the ones `@hono/zod-openapi` would require of it: across the conformance
+corpus, what Hono's RPC client infers for 619 routes is compared with what `RouteConfigToTypedResponse`
+derives from the published document.
 
 ## Docs
 
-- [Guides](docs/guides.md): middleware, the RPC client, authentication, base paths, HEAD operations,
-  request bodies, streaming, observability
+- [Guides](docs/guides.md): declared failures, middleware, the RPC client, authentication, base
+  paths, HEAD operations, request bodies, streaming, observability, upgrading
 - [Cloudflare Workers](docs/cloudflare-workers.md): which router to pick, and what the bundle costs
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits
 - [Releasing](docs/releasing.md): rehearsing a two-package release against a local registry,

package/dist/src/app.d.ts

@@ -1,5 +1,45 @@
-import { type SecurityRequirement } from "./security.js";
-import { type EmittedRoute, type EmittedService } from "typespec-http-zod";
+import { type EmittedPathSegment, type EmittedRoute, type EmittedService, type StatusKey } from "typespec-http-zod";
+/**
+ * Hono's status codes, group by group, exactly as `hono/utils/http-status` declares them.
+ *
+ * **The generated route needs the LITERALS, not only the type.** A range arm is served from a
+ * `switch` on the result's status, and TypeScript narrows the result to one member only through a
+ * `case` label per literal: a type guard narrows the status and leaves the result a union, and
+ * merging the range into `default` pairs every body with every status. Both measured on hono 4.13.1.
+ *
+ * `test/status-codes.test.ts` holds these equal to Hono's own unions, so a status Hono adds fails a
+ * test rather than silently falling out of a range.
+ */
+export declare const STATUS_GROUPS: {
+    readonly 1: {
+        readonly type: "InfoStatusCode";
+        readonly codes: readonly [100, 101, 102, 103];
+    };
+    readonly 2: {
+        readonly type: "SuccessStatusCode";
+        readonly codes: readonly [200, 201, 202, 203, 204, 205, 206, 207, 208, 226];
+    };
+    readonly 3: {
+        readonly type: "RedirectStatusCode";
+        readonly codes: readonly [300, 301, 302, 303, 304, 305, 306, 307, 308];
+    };
+    readonly 4: {
+        readonly type: "ClientErrorStatusCode";
+        readonly codes: readonly [400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 418, 421, 422, 423, 424, 425, 426, 428, 429, 431, 451];
+    };
+    readonly 5: {
+        readonly type: "ServerErrorStatusCode";
+        readonly codes: readonly [500, 501, 502, 503, 504, 505, 506, 507, 508, 510, 511];
+    };
+};
+/**
+ * Where every generated file imports its runtime from: the copy this package writes beside them.
+ *
+ * Declared here, where the import is rendered, and re-exported by the emitter that writes the file.
+ */
+export declare const DEFAULT_RUNTIME_MODULE = "./runtime.gen.js";
+/** Hono's `ContentlessStatusCode`: a status that cannot carry a body, so `c.json` refuses it. */
+export declare const CONTENTLESS_STATUS_CODES: readonly [101, 204, 205, 304];
 /**
  * The header every emitted file carries.
  *
@@ -10,46 +50,35 @@ import { type EmittedRoute, type EmittedService } from "typespec-http-zod";
  */
 export declare function generatedBanner(hint: string | undefined): string;
 /**
- * TypeSpec publishes `/widgets/{widget-id}`; Hono routes on `/widgets/:widget-id`.
+ * The Hono route for a route template, from the segments `typespec-http-zod` reads out of the
+ * operation's RFC 6570 `uriTemplate`.
  *
- * **This used to match `\w+`, so any parameter carrying a hyphen was left ALONE.**
- * `@path("thing-id")` produced the literal route `/things/{thing-id}`, mounted, counted by every arm
- * that counts routes, and reachable by nobody. It answered 404 to the only requests it was for. Hono
- * handles `:thing-id` and `:x.y` perfectly well; the narrow character class was ours.
+ * **This used to convert `route.path`, which has every operator stripped**, so `array{.param*}`,
+ * `array{;param}` and `optional{/name}` were mounted as `array:param` and `optional:name`, which Hono
+ * does not match at all. Measured by request: 31 of the URIs `@typespec/http-specs` `routes` and
+ * `parameters/path` declare answered 404 from a server generated from them.
  *
- * A name that is not plain is REFUSED rather than approximated, and the route stays at the literal
- * template so it matches nothing rather than matching the wrong thing.
+ * - A whole-segment expression is `:name`; a reserved or exploding `/` one crosses `/`, so it is
+ *   `:name{.+}` (Hono's spelling of greedy); an optional last segment is `:name?`.
+ * - An expression written beside literal text, or with a label or matrix operator, is a pattern
+ *   parameter matching the whole segment: `:param{array\.[^\x2F]*}`. The captured text is the
+ *   segment, and the path validator undoes the expansion. `\x2F` rather than `/`, so the mounted
+ *   path still splits into its segments on `/` for the ordering and sub-app rules below.
  *
- * **This is about the NAME, not about RFC 6570 operators.** An earlier version of this comment
- * claimed `{+path}` or `{tag*}` would survive into the name and that `*` would become Hono's
- * wildcard. Measured, that is false: `@typespec/http` resolves the operator before this emitter sees
- * the path, and `@typespec/openapi3` strips it from the published document too, so both artefacts say
- * `/files{path}` and agree. What actually reaches here is a wire name from `@path("...")`, and the
- * forms that fail are a space, `+` and `!`. `*` is rejected by `@typespec/http` before it arrives.
+ * **A name Hono cannot carry is REFUSED rather than approximated**, and so is a segment holding two
+ * expressions, which no segment router can split. The segment stays literal, so it matches nothing
+ * rather than the wrong thing. A space, `+` and `!` are the characters that fail; a hyphen, a dot and
+ * a tilde do not.
  *
- * **This runs at RENDER time, not during collection.** It used to run inside `collectRoutes`, which
- * put one framework's spelling into the shared intermediate representation and refused the whole
- * operation (validators included) over a template no router could mount. What a request body must
- * look like does not depend on that.
+ * **This runs at RENDER time, not during collection**, so what a request body must look like never
+ * depends on whether one framework's router can express the path.
  */
-export declare function toHonoPath(template: string, refuse: (template: string, name: string) => void, 
-/**
- * Wire names the document says carry RFC 6570 reserved expansion, so their value may contain `/`.
- *
- * **A hierarchical identifier is ONE value, not several segments.** An Obsidian note is
- * `areas/health.md`; an S3 key and a GitHub file path are the same shape. A router that stops at
- * the first `/` binds `areas` and 404s the rest. Hono spells the greedy form `:name{.+}`.
- *
- * Read from `EmittedRoute.reservedPathParameters`, which the library resolves from `allowReserved`
- * on the parameter. **Never from the template**: the operator does not survive to `route.path`,
- * `@typespec/http` strips it, and it can also be set with no operator in the template at all, so
- * the template is a derived artefact rather than the source of truth.
- */
-reserved?: ReadonlySet<string>): string;
+export declare function toHonoPath(segments: readonly EmittedPathSegment[], refuse: (template: string, name: string) => void): string;
 /** The one thing a Hono server cannot express, handed back rather than thrown. */
 export interface RenderRefusals {
     readonly unsupportedPathTemplate: (route: EmittedRoute, template: string, name: string) => void;
     readonly unvalidatableMediaType: (route: EmittedRoute, types: readonly string[]) => void;
+    readonly unvalidatedResponseMediaType: (route: EmittedRoute, status: StatusKey, types: readonly string[]) => void;
 }
 /**
  * The generated Hono server.
@@ -77,13 +106,4 @@ export declare function renderApp(emitted: EmittedService, refuse: RenderRefusal
  * the document publishes `/api/v1/accounts`. Mounting at the root made every client generated from
  * the document, and every "try it" in a rendered document, 404.
  */
-basePaths?: readonly string[], 
-/**
- * What the DOCUMENT says a caller must satisfy, per operation id.
- *
- * **Resolved by the caller rather than read off `EmittedRoute`**, because which schemes an
- * operation accepts is a fact about the HTTP program and not part of the validator IR the library
- * publishes. Keeping it out of that IR is what stops a Hono concern leaking into a package whose
- * audience is wider.
- */
-securityFor?: (verb: string, path: string) => readonly SecurityRequirement[]): string;
+basePaths?: readonly string[]): string;