@tetsujs/openapi 0.4.2 → 0.5.0

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,82 @@ 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.
 
+## 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":"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"}

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"}

package/dist/src/index.js

@@ -103,7 +103,7 @@ function failureName(status, error) {
 }
 
 // packages/openapi/src/envelopes.ts
-function envelopes(components) {
+function envelopes(components, format) {
   const declared = new Map;
   const defined = new Map;
   const refs = new Map;
@@ -111,6 +111,7 @@ function envelopes(components) {
   const names = new Map;
   const reported = new Set;
   return {
+    format,
     declare(status, code, schema) {
       const key = keyOf(status, code);
       if (!declared.has(key)) {
@@ -149,31 +150,18 @@ function envelopes(components) {
     return `${name}${status}`;
   }
 }
-function envelopeCode(schema) {
-  const required = Array.isArray(schema.required) ? schema.required : [];
-  if (!required.includes("error")) {
-    return;
-  }
-  const error = schema.properties?.error;
-  if (typeof error?.const === "string") {
-    return error.const;
-  }
-  if (Array.isArray(error?.enum) && error.enum.length === 1 && typeof error.enum[0] === "string") {
-    return error.enum[0];
-  }
-  return;
-}
-function branchesOf(schema) {
+function branchesOf(schema, code) {
   const keys = Object.keys(schema);
   if (keys.length !== 1) {
     return [schema];
   }
+  const within = (branch) => branchesOf(branch, code);
   if (Array.isArray(schema.anyOf)) {
-    return schema.anyOf.flatMap(branchesOf);
+    return schema.anyOf.flatMap(within);
   }
   if (Array.isArray(schema.oneOf)) {
-    const branches = schema.oneOf.flatMap(branchesOf);
-    const codes = branches.map(envelopeCode);
+    const branches = schema.oneOf.flatMap(within);
+    const codes = branches.map(code);
     if (codes.every((code) => code !== undefined) && new Set(codes).size === codes.length) {
       return branches;
     }
@@ -184,17 +172,89 @@ function keyOf(status, code) {
   return `${status} ${code}`;
 }
 function differenceOf(kept, other) {
-  const fields = (schema) => Object.keys(schema.properties ?? {});
-  const keptFields = fields(kept);
-  const otherFields = fields(other);
-  const missing = otherFields.filter((name) => !keptFields.includes(name));
-  const extra = keptFields.filter((name) => !otherFields.includes(name));
-  const changed = [...missing, ...extra];
+  const keptShape = shapeOf(kept);
+  const otherShape = shapeOf(other);
+  const changed = [
+    ...otherShape.fields.filter((path) => !keptShape.fields.includes(path)),
+    ...keptShape.fields.filter((path) => !otherShape.fields.includes(path))
+  ];
   if (changed.length > 0) {
     return `fields: ${changed.join(", ")}`;
   }
-  const required = (schema) => JSON.stringify([...Array.isArray(schema.required) ? schema.required : []].sort());
-  return required(kept) === required(other) ? undefined : "which fields are required";
+  return JSON.stringify(keptShape.required) === JSON.stringify(otherShape.required) ? undefined : "which fields are required";
+}
+var shapeDepth = 8;
+function shapeOf(schema) {
+  const fields = [];
+  const required = [];
+  const walk = (node, prefix, depth) => {
+    const properties = node.properties;
+    if (depth > shapeDepth || properties === null || typeof properties !== "object") {
+      return;
+    }
+    const requiredHere = Array.isArray(node.required) ? node.required : [];
+    for (const [name, child] of Object.entries(properties)) {
+      const path = `${prefix}${name}`;
+      fields.push(path);
+      if (requiredHere.includes(name)) {
+        required.push(path);
+      }
+      if (child !== null && typeof child === "object") {
+        walk(child, `${path}.`, depth + 1);
+      }
+    }
+  };
+  walk(schema, "", 0);
+  return { fields: fields.sort(), required: required.sort() };
+}
+
+// packages/openapi/src/errors.ts
+function resolveFormat(format) {
+  if (format === undefined) {
+    return {
+      describe: envelope,
+      code: codeIn("error"),
+      discriminator: "error"
+    };
+  }
+  const discriminator = format.discriminator;
+  const read = format.code;
+  return {
+    describe: (failure) => format.schema(failure),
+    code: read ? (schema) => read(schema) : discriminator === undefined ? () => {
+      return;
+    } : codeIn(discriminator),
+    discriminator
+  };
+}
+function envelope(failure) {
+  const own = {
+    status: { type: "integer", const: failure.status },
+    message: failure.message ? { type: "string", examples: [failure.message] } : { type: "string" },
+    error: failure.error ? { type: "string", const: failure.error } : { type: "string" }
+  };
+  const added = Object.keys(failure.fields).filter((name) => !Object.hasOwn(own, name));
+  return {
+    type: "object",
+    required: ["status", "message", "error", ...added],
+    properties: { ...failure.fields, ...own }
+  };
+}
+function codeIn(field) {
+  return (schema) => {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    if (!required.includes(field)) {
+      return;
+    }
+    const value = schema.properties?.[field];
+    if (typeof value?.const === "string") {
+      return value.const;
+    }
+    if (Array.isArray(value?.enum) && value.enum.length === 1 && typeof value.enum[0] === "string") {
+      return value.enum[0];
+    }
+    return;
+  };
 }
 
 // packages/openapi/src/operation.ts
@@ -315,10 +375,11 @@ function operationOf(entry, options, components, envelopes, ids, warn) {
 function declareEnvelopes(entry, envelopes) {
   for (const [status, schema] of declaredResponses(entry)) {
     const described = schema === null ? undefined : emitted(schema, "", () => {});
-    for (const branch of described ? branchesOf(described) : []) {
-      const code = envelopeCode(branch);
-      if (code !== undefined) {
-        envelopes.declare(Number(status), code, branch);
+    const code = envelopes.format.code;
+    for (const branch of described ? branchesOf(described, code) : []) {
+      const found = code(branch);
+      if (found !== undefined) {
+        envelopes.declare(Number(status), found, branch);
       }
     }
   }
@@ -334,8 +395,8 @@ function declaredResponses(entry) {
   return Object.entries(response);
 }
 function branchesFor(schema, status, envelopes, warn) {
-  return branchesOf(schema).map((branch) => {
-    const code = envelopeCode(branch);
+  return branchesOf(schema, envelopes.format.code).map((branch) => {
+    const code = envelopes.format.code(branch);
     return code === undefined ? branch : envelopes.ref(status, code, branch, warn);
   });
 }
@@ -475,7 +536,12 @@ function failures(entry, options, contributed, components, envelopes, warn) {
   const schema = entry.def.schema;
   const found = [];
   const envelopeRef = (status, error, message, fields) => {
-    const described = envelope(status, error, message, fields);
+    const described = envelopes.format.describe({
+      status,
+      ...error === undefined ? {} : { error },
+      ...message === undefined ? {} : { message },
+      fields: fields ?? {}
+    });
     const ref = error === undefined ? components.ref(failureName(status), described) : envelopes.ref(status, error, described, warn);
     return ref;
   };
@@ -485,7 +551,12 @@ function failures(entry, options, contributed, components, envelopes, warn) {
       {
         description: "Request failed schema validation",
         schemas: [
-          envelopes.ref(options.validationStatus, "VALIDATION_FAILED", validationFailed(options.validationStatus), warn)
+          envelopes.ref(options.validationStatus, "VALIDATION_FAILED", envelopes.format.describe({
+            status: options.validationStatus,
+            error: "VALIDATION_FAILED",
+            message: "Validation failed",
+            fields: { issues }
+          }), warn)
         ]
       }
     ]);
@@ -569,6 +640,10 @@ function unionOf(schemas, envelopes) {
   if (schemas.length === 1 && only) {
     return only;
   }
+  const propertyName = envelopes.format.discriminator;
+  if (propertyName === undefined) {
+    return { anyOf: schemas };
+  }
   const mapping = {};
   for (const schema of schemas) {
     const ref = schema.$ref;
@@ -580,7 +655,7 @@ function unionOf(schemas, envelopes) {
   }
   return {
     anyOf: schemas,
-    discriminator: { propertyName: "error", mapping }
+    discriminator: { propertyName, mapping }
   };
 }
 function distinct(schemas) {
@@ -600,40 +675,17 @@ function describeStatus(status) {
   }
   return status.startsWith("2") ? "Successful response" : errorBody(Number(status)).message;
 }
-function envelope(status, error, message, fields = {}) {
-  const own = {
-    status: { type: "integer", const: status },
-    message: message ? { type: "string", examples: [message] } : { type: "string" },
-    error: error ? { type: "string", const: error } : { type: "string" }
-  };
-  const added = Object.keys(fields).filter((name) => !Object.hasOwn(own, name));
-  return {
+var issues = {
+  type: "array",
+  items: {
     type: "object",
-    required: ["status", "message", "error", ...added],
-    properties: { ...fields, ...own }
-  };
-}
-function validationFailed(status) {
-  const base = envelope(status, "VALIDATION_FAILED", "Validation failed");
-  return {
-    ...base,
-    required: ["status", "message", "error", "issues"],
+    required: ["message", "path"],
     properties: {
-      ...base.properties,
-      issues: {
-        type: "array",
-        items: {
-          type: "object",
-          required: ["message", "path"],
-          properties: {
-            message: { type: "string" },
-            path: { type: "array", items: { type: ["string", "number"] } }
-          }
-        }
-      }
+      message: { type: "string" },
+      path: { type: "array", items: { type: ["string", "number"] } }
     }
-  };
-}
+  }
+};
 function parseFailure(bodyType) {
   if (bodyType === "text" || bodyType === "stream") {
     return;
@@ -751,7 +803,8 @@ class DocsController {
   [onMount](app) {
     const generated = openapi(app, {
       info: this.options.info,
-      ...this.options.servers ? { servers: this.options.servers } : {}
+      ...this.options.servers ? { servers: this.options.servers } : {},
+      ...this.options.errors ? { errors: this.options.errors } : {}
     });
     this.document = generated.document;
     const ui = this.options.ui ?? "scalar";
@@ -784,7 +837,7 @@ function openapi(app, options) {
   const warnings = [];
   const schemes = {};
   const components = schemaComponents();
-  const envelopes2 = envelopes(components);
+  const envelopes2 = envelopes(components, resolveFormat(options.errors));
   const ids = operationIds();
   const described = app.entries.filter((entry) => !entry.ws && !entry.def.docs?.hidden);
   for (const entry of described) {
@@ -851,5 +904,5 @@ export {
   secured
 };
 
-//# debugId=8D8E4C09AE6F825C64756E2164756E21
+//# debugId=B1D856E7F5B6819164756E2164756E21
 //# sourceMappingURL=index.js.map