@tetsujs/openapi 0.4.2 → 0.5.1

package/README.md

@@ -75,6 +75,7 @@ the hash, to be prefixed with `sha384-`.
 | `assets` | the renderer on jsDelivr, pinned | your own renderer URLs, with `integrity` hashes |
 | `documentSelf` | `false` | include `/openapi.json` and `/docs` in the document |
 | `onWarning` | `console.warn` | receives what could not be described |
+| `errors` | the framework's envelope | an error format of your own — see [below](#an-error-format-of-your-own) |
 
 ## What goes into the document
 
@@ -151,6 +152,99 @@ When every alternative of a status is an envelope, the union carries a
 `discriminator` on `error`, with the mapping from each code to its
 definition, and a generated client narrows on the code.
 
+A status is described by what answers with it. The route's part is the
+`description` of the schema it declares — `.describe()` in Zod and
+ArkType, `v.description()` in Valibot, `{ description }` in TypeBox — for
+any status, a `200` as much as a `404`; a union described as a whole is
+one description, one described branch by branch is one per branch. A
+hook's part is its `documented()` description, the framework's its own.
+One description is the status's description; several are a list, each
+led by its code:
+
+```md
+- `ACCOUNT_DISABLED`: this account is disabled
+- `CAPTCHA_FAILED`: the captcha token is missing or did not pass
+```
+
+A status nothing describes keeps its reason phrase — `Not Found`,
+`Successful response`.
+
+## An error format of your own
+
+Every failure reaches the application's `onError` hooks — a thrown
+`HttpError`, a validation or body failure, a `404`, a `405`, a rate limit's
+refusal — so one hook answers all of them in your format:
+
+```ts
+const inOurFormat = hook.onError(({ error }) => {
+  if (!(error instanceof HttpError)) return undefined;
+
+  const { status, error: code, ...rest } = error.body as ErrorBody;
+
+  return Response.json({ code, ...rest }, { status });
+});
+```
+
+The document is generated from the routes, not from that hook, so it is
+told the same format with `errors`:
+
+```ts
+const errors: ErrorFormat = {
+  schema: ({ error, message, fields }) => ({
+    type: "object",
+    required: ["code", "message", ...Object.keys(fields)],
+    properties: {
+      code: error ? { type: "string", const: error } : { type: "string" },
+      message: { type: "string", ...(message ? { examples: [message] } : {}) },
+      ...fields,
+    },
+  }),
+  discriminator: "code",
+};
+
+createApp({
+  hooks: { onError: [inOurFormat] },
+  routes: [api, docs({ info, errors })],
+});
+```
+
+`schema` describes one failure from what the generator knows of it: its
+status, its code when known, an example message, and in `fields` what it
+carries besides — `issues` for a validation failure, `retryAfter` for a
+rate limit, a hook's own `fields`. It is used for the framework's failures
+and the hooks' refusals alike.
+
+`discriminator` names the top-level field that holds the code. Statuses of
+envelopes are then discriminated on it, and a route's own envelope is
+recognized by it — a `{ code: "ITEM_NOT_FOUND", … }` the route declares is
+the same definition as a hook's. A format that nests its code has no
+top-level field to name; it gives `code` instead, reading the code from a
+route's schema:
+
+```ts
+code: (schema) => {
+  const error = schema.properties?.error;
+  const code = typeof error === "object" ? error.properties?.code : undefined;
+
+  return typeof code === "object" && typeof code.const === "string" ? code.const : undefined;
+},
+```
+
+The hook and `errors` describe one format in two places — the core knows
+nothing about documents, and a function cannot be read for the shape it
+returns — so keep a test that holds them together: provoke a failure and
+check its body against the document, with the JSON Schema validator of
+your choice.
+
+```ts
+test("a validation failure is what the document says", async () => {
+  const res = await request("/items", { method: "POST", body: "{}" });
+  const schema = document.components?.schemas?.ValidationFailed;
+
+  expect(validator.validate(schema, await res.json())).toBe(true);
+});
+```
+
 ## Documenting hooks
 
 A hook that answers by itself — an auth check, a limiter — can say so, and

package/dist/src/controller.d.ts

@@ -15,6 +15,7 @@
 import type { App, RouteDef, SchemaConfig, ValidatePath } from "@tetsujs/core";
 import { onMount } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
+import type { ErrorFormat } from "./errors.ts";
 import type { GeneratorWarning } from "./index.ts";
 import type { DocsAssets, DocsUi } from "./page.ts";
 /** What the documentation controller serves, and from where. */
@@ -23,6 +24,11 @@ export interface DocsOptions<Path extends string, UiPath extends string, Ui exte
     readonly info: OpenApiDocument["info"];
     /** Servers the API is reachable at. */
     readonly servers?: OpenApiDocument["servers"];
+    /**
+     * How the application's errors look, when not like the framework's
+     * envelope — see `errors` on {@link openapi}.
+     */
+    readonly errors?: ErrorFormat;
     /** Where the document is served. Defaults to `/openapi.json`. */
     readonly path?: Path & ValidatePath<Path>;
     /** Where the page is served. Defaults to `/docs`. */

package/dist/src/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAC1B,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK;IAE1C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IAEjB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CACzB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,IAAI,SAAS,OAAO,GAAG,IAAI;IAezB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAb1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,IAAI,SAAS,IAAI,GAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,GACvD,SAAS,CAAC;IAEd,OAAO,CAAC,QAAQ,CAA8B;IAE9C,OAAO,CAAC,IAAI,CAAqB;IAEjC,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EAkCf;IAED;;;;;;;;OAQG;IACH,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CA0BxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,QAAQ,EAE1C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,GACrC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,CAM/D"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAC1B,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK;IAE1C,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;IAEjB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CACzB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,EACrB,IAAI,SAAS,OAAO,GAAG,IAAI;IAezB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAb1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,IAAI,SAAS,IAAI,GAC1B,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,GACvD,SAAS,CAAC;IAEd,OAAO,CAAC,QAAQ,CAA8B;IAE9C,OAAO,CAAC,IAAI,CAAqB;IAEjC,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EAkCf;IAED;;;;;;;;OAQG;IACH,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CA2BxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,KAAK,CAAC,EAAE,SAAS,MAAM,GAAG,KAAK,GAAG,QAAQ,EAE1C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,GACrC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC,CAM/D"}

package/dist/src/emit.d.ts

@@ -15,6 +15,7 @@ export interface JsonSchemaObject {
     required?: unknown;
     anyOf?: unknown;
     oneOf?: unknown;
+    description?: unknown;
     [keyword: string]: unknown;
 }
 /** Which shape of a schema to describe: what arrives, or what leaves. */

package/dist/src/emit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}

package/dist/src/envelopes.d.ts

@@ -20,14 +20,21 @@
  * read first, before any operation is built, so the winner does not depend
  * on which route happens to come first in the table.
  *
+ * What an envelope looks like — how one is described, where its code is,
+ * what a client discriminates on — is the document's error format, which
+ * the registry carries for everything that builds or reads one.
+ *
  * Internal to the package.
  *
  * @module
  */
 import type { SchemaComponents, SchemaRef } from "./components.ts";
 import type { JsonSchemaObject } from "./emit.ts";
+import type { ResolvedFormat } from "./errors.ts";
 /** The definitions of every envelope of one document. */
 export interface Envelopes {
+    /** The document's error format. */
+    readonly format: ResolvedFormat;
     /**
      * Records a route's definition, before anything is referenced. The first
      * route to declare a status and code defines it.
@@ -48,16 +55,7 @@ export interface Envelopes {
      */
     codeOf(ref: string): string | undefined;
 }
-export declare function envelopes(components: SchemaComponents): Envelopes;
-/**
- * The error code of a schema that is an envelope: an object whose `error`
- * is required and holds one string — a `const`, or an `enum` of one value.
- *
- * Read off what the validator emitted, not off a declaration: the route
- * has no other way to say which of its responses is an envelope, and the
- * shape is what a client would branch on anyway.
- */
-export declare function envelopeCode(schema: JsonSchemaObject): string | undefined;
+export declare function envelopes(components: SchemaComponents, format: ResolvedFormat): Envelopes;
 /**
  * The alternatives a schema stands for, as a list the status's own union
  * can take in.
@@ -70,5 +68,5 @@ export declare function envelopeCode(schema: JsonSchemaObject): string | undefin
  * beside its union, a `title` or a `$defs`, is left whole: those keywords
  * belong to the union, and would be lost with it.
  */
-export declare function branchesOf(schema: JsonSchemaObject): JsonSchemaObject[];
+export declare function branchesOf(schema: JsonSchemaObject, code: (schema: JsonSchemaObject) => string | undefined): JsonSchemaObject[];
 //# sourceMappingURL=envelopes.d.ts.map

package/dist/src/envelopes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CAAC,UAAU,EAAE,gBAAgB,GAAG,SAAS,CAoEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CA0BzE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAwBvE"}
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CACvB,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,cAAc,GACrB,SAAS,CAsEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GACrD,gBAAgB,EAAE,CA0BpB"}

package/dist/src/errors.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The shape the document gives an error.
+ *
+ * Every failure an application answers with reaches its `onError` hooks,
+ * so one hook sets the format of all of them. The document is generated
+ * from the routes, not from that hook, and cannot see what it does: an
+ * application with a format of its own says so here too, and the framework's
+ * failures, the hooks' refusals and the routes' own envelopes are described
+ * in it. Keeping the two in step is the application's to do — the core knows
+ * nothing about documents, and a function cannot be read for the shape it
+ * returns.
+ *
+ * Without it the format is the framework's envelope,
+ * `{ status, message, error }`.
+ *
+ * @module
+ */
+import type { JsonSchemaObject } from "./emit.ts";
+import type { JsonSchema, JsonSchemaKeywords } from "./json-schema.ts";
+/**
+ * One failure the document describes, as the generator knows it.
+ *
+ * This is everything known about a failure before it is answered: its
+ * status, its code when the framework or the hook knows it, an example of
+ * its message, and what else it carries — the `issues` of a validation
+ * failure, the `retryAfter` of a rate limit. Where each goes in the body
+ * is the format's to decide.
+ */
+export interface DocumentedFailure {
+    readonly status: number;
+    /** The code a client branches on, when it is known. */
+    readonly error?: string;
+    /** An example of the message; wording, never a contract. */
+    readonly message?: string;
+    /** What the failure carries besides, as JSON Schema by name. */
+    readonly fields: Readonly<Record<string, JsonSchema>>;
+}
+/** How the application's errors look, for the document to describe them. */
+export interface ErrorFormat {
+    /** The body of one failure. */
+    readonly schema: (failure: DocumentedFailure) => JsonSchemaKeywords;
+    /**
+     * The top-level field that holds the code, for a client to discriminate
+     * on — `"code"` in `{ code, message }`. A status whose alternatives are
+     * all envelopes then carries a `discriminator` on it.
+     *
+     * None unless named: OpenAPI discriminates on a top-level field only, and
+     * a format that nests its code — `{ error: { code } }` — has none to
+     * name.
+     */
+    readonly discriminator?: string;
+    /**
+     * The code of a schema a route or a hook declared, when it is an
+     * envelope in this format — how the document knows a route's own `404`
+     * is the same failure as a hook's, and gives both one definition.
+     *
+     * Read off the JSON Schema the validator emitted. By default, the
+     * `const` of the discriminator's field, when there is one; a nested
+     * format says where its code is.
+     */
+    readonly code?: (schema: JsonSchemaKeywords) => string | undefined;
+}
+/** What the generator works with: every part of a format, filled in. */
+export interface ResolvedFormat {
+    describe(failure: DocumentedFailure): JsonSchemaObject;
+    code(schema: JsonSchemaObject): string | undefined;
+    readonly discriminator: string | undefined;
+}
+/**
+ * A format as the generator uses it. Absent, the framework's envelope,
+ * discriminated on `error`.
+ */
+export declare function resolveFormat(format: ErrorFormat | undefined): ResolvedFormat;
+//# sourceMappingURL=errors.d.ts.map

package/dist/src/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAEvE;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B,gEAAgE;IAChE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;CACvD;AAED,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,kBAAkB,CAAC;IAEpE;;;;;;;;OAQG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,MAAM,GAAG,SAAS,CAAC;CACpE;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAAC;IACvD,IAAI,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,cAAc,CAqB7E"}

package/dist/src/index.d.ts

@@ -20,11 +20,13 @@
  */
 import type { App } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
+import type { ErrorFormat } from "./errors.ts";
 export type { DocumentedHeader, DocumentedResponse, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
 export { documented, secured } from "./annotations.ts";
 export type { DocsOptions } from "./controller.ts";
 export { DocsController, docs } from "./controller.ts";
 export type { ContentMap, DocumentInfo, DocumentServer, HeaderObject, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { DocumentedFailure, ErrorFormat } from "./errors.ts";
 export type { JsonSchema, JsonSchemaKeywords, JsonSchemaType, } from "./json-schema.ts";
 export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
 export { docsPage } from "./page.ts";
@@ -36,6 +38,32 @@ export interface OpenApiOptions {
     readonly info: OpenApiDocument["info"];
     /** Servers the API is reachable at. */
     readonly servers?: OpenApiDocument["servers"];
+    /**
+     * How the application's errors look, when not like the framework's
+     * envelope — for an application whose `onError` hook answers in a format
+     * of its own. The framework's failures, the hooks' refusals and the
+     * routes' own envelopes are then described in it.
+     *
+     * @example `{ code, message }`, discriminated on `code`
+     * ```ts
+     * openapi(app, {
+     *   info,
+     *   errors: {
+     *     schema: ({ error, message, fields }) => ({
+     *       type: "object",
+     *       required: ["code", "message", ...Object.keys(fields)],
+     *       properties: {
+     *         code: error ? { type: "string", const: error } : { type: "string" },
+     *         message: { type: "string", ...(message ? { examples: [message] } : {}) },
+     *         ...fields,
+     *       },
+     *     }),
+     *     discriminator: "code",
+     *   },
+     * });
+     * ```
+     */
+    readonly errors?: ErrorFormat;
 }
 /**
  * What the generator could not describe faithfully.

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAKrE,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA2F1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAErE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CA8F1E"}