@nxgt/openapi-hono 0.1.0

package/docs/guide.md

@@ -0,0 +1,324 @@
+# Typed Hono routes
+
+With the `hono` option, [`@nxgt/openapi-codegen`](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/README.md)
+also writes `hono.ts`: the routes of the spec, typed for a Hono app and
+validated with the generated validators. `@nxgt/openapi-hono` is the runtime
+it binds to the spec.
+
+- A handler gets its parameters and body already validated.
+- A request the spec refuses is answered with a 400 that lists every issue.
+- A handler that returns a reply the spec does not declare does not compile.
+
+## Setup
+
+`hono.ts` imports `@nxgt/openapi-hono` at runtime and `hono`'s types,
+`operations.ts` imports `zod`, and your app builds its own `Hono`, so all
+three are dependencies of your app.
+The generator stays a dev dependency:
+
+```sh
+bun add @nxgt/openapi-hono hono zod
+bun add -d @nxgt/openapi-codegen
+```
+
+```ts
+// openapi-codegen.config.ts
+import { defineConfig } from '@nxgt/openapi-codegen';
+
+export default defineConfig({
+	input: 'openapi/openapi.yaml',
+	output: 'src/generated',
+	hono: true,
+});
+```
+
+## Register routes
+
+```ts
+import { Hono } from 'hono';
+import { createRoutes } from './generated/hono.js';
+
+const app = new Hono();
+const routes = createRoutes(app);
+
+routes.put('/employees/{id}', auth, async (c) => {
+	const { id } = c.req.valid('param');
+	const employee = await employees.update(id, c.req.valid('json'));
+	if (!employee) return c.json({ message: 'errors.not-found' }, 404);
+	return c.json(employee, 200);
+});
+
+routes.operation('deleteEmployee', auth, async (c) => {
+	await employees.remove(c.req.valid('param').id);
+	return c.body(null, 204);
+});
+```
+
+- **Paths are written as the spec writes them**, `{id}` and not `:id`.
+  Each method offers only the paths that have an operation for it.
+- **`routes.operation(id, …)`** registers an operation by its `operationId`.
+- **Middlewares come first, then the handler.**
+- **`c.req.valid()`** holds what was validated: `param`, `query`, `header`,
+  and `json` or `form` for a body. Numbers are numbers and defaults are
+  filled in. Header names are lowercased. A text body is validated too, but
+  Hono has no target for it: read it with `c.req.text()`.
+- **The handler returns one of the declared replies:**
+
+  | Declared | Return |
+  | --- | --- |
+  | a JSON body | `c.json(body, status)` |
+  | a text body | `c.text(text, status)` |
+  | no content | `c.body(null, status)`; for a 3xx other than 304, also `c.redirect(url, status)` |
+  | a binary body | `c.body(data, status, headers)` |
+
+## What happens to a request
+
+A route runs as `[...middlewares, validator, handler]`, so `auth` answers
+401 before the body is even read.
+
+1. **The validator reads every target**, then answers:
+   - **Path, query and headers** are read as text. A query list is every
+     value of a repeated key (`?ids=1&ids=2`), or one value split on commas
+     with `explode: false`. Any other query key sent twice is refused, since
+     the handler would see one value and `c.req.queries()` another. A header
+     list is split on commas.
+   - **The body** is read by its `Content-Type`: the media type itself, then
+     `type/*`, then `*/*`. A required body sent empty is missing.
+     - JSON is parsed and validated.
+     - A form (`multipart/form-data`, `application/x-www-form-urlencoded`)
+       whose schema is a [flat object](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/schema-mapping.md#form-bodies) has
+       each field read from text, and a field sent once is taken as a list
+       of one where the schema expects a list.
+     - Text is validated as a string.
+     - Binary content passes through unread, for the handler to stream. It
+       is missing only when its `Content-Length` is 0.
+2. **Hono caches the body**, so a middleware that read it and the handler
+   can both read it again.
+3. **Every issue of every target** goes into one failure: one 400, not the
+   first mistake only.
+
+When a middleware needs validated input, `routes.validate` marks where
+validation runs:
+
+```ts
+// 401 from auth, then 400 from validation, then 403 from ownership
+routes.put('/employees/{id}', auth, routes.validate, ownsEmployee, handler);
+```
+
+## Validation errors
+
+By default, a refused request gets:
+
+```json
+{
+	"status": 400,
+	"message": "errors.validation-failed",
+	"timestamp": "2024-05-01T10:00:00.000Z",
+	"issues": [
+		{
+			"target": "json",
+			"path": ["email"],
+			"code": "invalid_format",
+			"message": "Invalid email address"
+		}
+	]
+}
+```
+
+- **`target`** is `param`, `query`, `header`, `json`, `form`, or `body` for
+  a text body.
+- **`code`** is Zod's issue code, or one of these:
+
+  | Code | When |
+  | --- | --- |
+  | `invalid_json` | the body is not JSON |
+  | `invalid_form` | the body is not the form its `Content-Type` says: a bad multipart boundary… |
+  | `invalid_content_type` | no declared media type matches, or a body came without a `Content-Type` |
+  | `missing_body` | a required body is missing, or empty |
+  | `repeated_parameter` | a query key that takes one value was sent more than once |
+
+To answer differently, pass `onValidationError`:
+
+```ts
+const routes = createRoutes(app, {
+	onValidationError: (failure, c) => {
+		throw new CustomException(400, 'errors.validation-failed', {
+			issues: failure.issues,
+		});
+	},
+});
+```
+
+The hook can do three things:
+- **return a `Response`** to send it;
+- **throw**, to hand the failure to `app.onError`, which is where an app
+  translates its messages;
+- **return nothing**, to send the default.
+
+`routes.with({ onValidationError })` sets it for the routes registered
+through it, and leaves the others alone.
+
+## Checking replies
+
+```ts
+const routes = createRoutes(app, {
+	validateResponses: process.env.NODE_ENV !== 'production',
+});
+```
+
+With `validateResponses`, every reply is checked against the spec:
+- its status must be declared, or the issue is `undeclared_status`;
+- its `Content-Type` must be one of the status's media types, when the
+  status declares any. What `c.json()` sends, `application/json`, stands
+  for a declared `+json` type such as `application/problem+json`; what
+  `c.text()` sends, `text/plain`, for any declared text type;
+- a JSON or text body is validated, except a stream: `text/event-stream`
+  and the JSON line formats are never read, since they may never end.
+  `streamEvents()` and `streamLines()` check each item instead, as it is
+  written ([Streams](#streams)).
+
+A reply that fails goes through `onValidationError` as a `response`
+failure. By default it is a 500 with no `issues`, since they would show the
+client what the reply held; they go to `console.error` instead. Checking
+reads every reply body twice: keep it for development and tests.
+
+Only exact statuses are declared. `default` and `4XX` responses are dropped
+with an `ignored` warning, so an operation that declares only those has its
+replies typed `Response`: any reply compiles. And with `validateResponses`,
+every reply it sends fails as `undeclared_status`. Give each operation its
+exact statuses.
+
+## Streams
+
+A reply of server-sent events or JSON Lines that the spec describes an item
+at a time, with OpenAPI 3.2's `itemSchema`, is written from the handler with
+the helpers `hono.ts` exports when the spec has such an operation:
+
+```ts
+import { createRoutes, streamEvents, streamLines } from './generated/hono.js';
+
+createRoutes(app, { validateResponses: true })
+	.get('/feed', (c) =>
+		streamEvents(c, 'watchFeed', async (stream) => {
+			stream.onAbort(() => unsubscribe());
+			await stream.write({ event: 'update', id: '7', data: item });
+			await stream.write({ event: 'ping', data: 'still here' });
+		}),
+	)
+	.post('/export', (c) =>
+		streamLines(c, 'exportItems', async (stream) => {
+			for await (const item of cursor) {
+				if (stream.aborted) break;
+				await stream.write(item);
+			}
+		}),
+	);
+```
+
+`streamEvents(c, id, write)`:
+- takes only an operation whose 2xx reply is `text/event-stream`, and types
+  each event by its name: `{ event, data, id?, retry? }`;
+- sends the data as JSON when the spec declares it JSON
+  (`contentMediaType: application/json`), and as text otherwise, a `data:`
+  line per line;
+- throws for an event name the spec does not declare. With no `itemSchema`,
+  any event goes, its data as text, `event` optional.
+
+`streamLines(c, id, write)` sends each item as a line of JSON, as the media
+type the spec declares: `application/jsonl`, `application/x-ndjson`, or
+`application/json-seq`, which puts a record separator before each one.
+
+Both reply with the status the stream is declared under, and end when
+`write` returns. The writer's `sleep(ms)` pauses between items. `aborted`
+and `onAbort()` tell when the client went away.
+
+With `validateResponses`, each item is checked before it is sent. The
+status went out with the first one, so a failing item cannot turn into a
+500. Instead it is not sent, `onValidationError` receives the `response`
+failure for its side effects (a log, a metric), and the stream ends with
+an error logged by `console.error`. A throw inside `write` ends the stream
+the same way.
+
+A handler may only stream its own operation's reply: `streamEvents(c, id)`
+throws when `id` is not the running route's.
+
+## Modules
+
+`createApi()` holds one registry for the whole spec. Each module registers
+its routes on its own sub-app:
+
+```ts
+import { createApi } from './generated/hono.js';
+
+export const api = createApi();
+
+// employees.routes.ts
+const employees = new Hono();
+api
+	.routes(employees, { prefix: '/employees', tag: 'employees' })
+	.get('/employees', listEmployees)
+	.get('/employees/{id}', getEmployee);
+
+// app.ts
+app.route('/employees', employees);
+api.assertComplete(); // throws, listing every operation without a route
+```
+
+- **`prefix`** is where the sub-app is mounted, as the spec writes it.
+  Routes are registered relative to it. Only paths under it are offered,
+  and one outside it fails at startup.
+- **`tag`** offers only the operations with that tag, by path and by
+  `operationId`.
+- **`api.missing(tag?)`** lists the operations without a route, of one tag
+  or of all. **`api.assertComplete(tag?)`** throws when there is one.
+
+`createRoutes(app, options)` is `createApi(options).routes(app, options)`:
+a registry for that app alone.
+
+## Mistakes caught at startup
+
+Registering a route throws when:
+- **the operation already has a route**;
+- **an earlier route would always answer first.** Hono tries routes in the
+  order they were registered, so `/users/{id}` registered before
+  `/users/me` answers for it. Register the static path first;
+- **the operation is outside the `prefix` or the `tag`**;
+- **the last argument is not the handler**, or `routes.validate` appears
+  twice;
+- **Hono cannot serve the operation.** Hono answers `HEAD` with the `GET`
+  route of the same path, so a `head` handler would never run: register the
+  `GET`. And a path parameter must fill its whole segment, so
+  `/files/{name}.json` and `/v1/{name}:cancel` cannot be routed: serve them
+  with `app.on()`. Generating with `hono` warns about both (`ignored`), and
+  `missing()` leaves them out.
+
+## Traps
+
+- **With `dates: 'date'`, a handler gets `Date`s and can reply with them.**
+  `c.req.valid()` holds decoded dates. `c.json()` sends a `Date` as its
+  ISO string, and `Replies` types replies as JSON carries them (`Wire<T>`),
+  so both a `Date` and its string compile.
+- **Give `c.json()` a status.** Without one, Hono types the reply with any
+  contentful status, and it matches no declared reply.
+- **Reply with plain objects.** A Mongoose document is not the JSON it
+  serializes to, and its type does not match the schema's. Return `.lean()`
+  results, or `toJSON()`.
+- **A body declared as both JSON and a form** types `c.req.valid('json')`
+  and `c.req.valid('form')` as both present. Only the one the request sent
+  is filled in.
+- **Keep form schemas flat.** Only a form whose schema is a
+  [flat object](https://github.com/softistx/nxgt-http/blob/develop/packages/openapi-codegen/docs/guide/schema-mapping.md#form-bodies) is read from text. Any other
+  form is validated by its own `z<Name>`, so `copies=2` arrives as the
+  string `'2'` and fails an integer.
+- **`security` is not enforced.** The spec's security requirements are not
+  turned into middlewares; register your own.
+- **Limit the body size yourself.** The validator reads a JSON, form or text
+  body whole, and the spec's `maxLength` applies only once it is read. Put
+  Hono's `bodyLimit` middleware first.
+- **Read the body through `c.req`, never `c.req.raw`.** Hono caches what
+  `c.req.json()`, `c.req.text()` and `c.req.arrayBuffer()` read, so the
+  validator can read it again; a middleware that drains `c.req.raw` leaves
+  it nothing, and the request fails with an error that says so.
+- **A `pattern` runs on what the client sends.** A pattern with nested
+  repetition, such as `^(a+)+$`, can take seconds on a crafted value. Give
+  such strings a `maxLength`, which Zod checks first.

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "@nxgt/openapi-hono",
+	"version": "0.1.0",
+	"license": "UNLICENSED",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"docs",
+		"README.md",
+		"package.json"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/softistx/nxgt-http.git",
+		"directory": "packages/openapi-hono"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "bun run ../../build.ts",
+		"fixtures": "bun run test/generate.ts",
+		"test": "bun run fixtures && bun test src",
+		"typecheck": "bun run fixtures && tsc --noEmit"
+	},
+	"devDependencies": {
+		"@nxgt/openapi-codegen": "^0.1.0",
+		"@types/bun": "^1.4.0",
+		"hono": "^4.13.4",
+		"zod": "^4.5.4"
+	},
+	"peerDependencies": {
+		"hono": "^4.13.4",
+		"typescript": "^6.0.3"
+	}
+}