@tetsujs/openapi 0.4.2 → 0.5.0

package/src/envelopes.ts

@@ -20,6 +20,10 @@
  * 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
@@ -28,9 +32,13 @@
 import type { SchemaComponents, SchemaRef } from "./components.ts";
 import { failureName } 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.
@@ -59,7 +67,10 @@ export interface Envelopes {
   codeOf(ref: string): string | undefined;
 }
 
-export function envelopes(components: SchemaComponents): Envelopes {
+export function envelopes(
+  components: SchemaComponents,
+  format: ResolvedFormat,
+): Envelopes {
   const declared = new Map<string, JsonSchemaObject>();
   const defined = new Map<string, JsonSchemaObject>();
   const refs = new Map<string, SchemaRef>();
@@ -68,6 +79,8 @@ export function envelopes(components: SchemaComponents): Envelopes {
   const reported = new Set<string>();
 
   return {
+    format,
+
     declare(status, code, schema) {
       const key = keyOf(status, code);
 
@@ -129,42 +142,6 @@ export 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 function envelopeCode(schema: JsonSchemaObject): string | undefined {
-  const required = Array.isArray(schema.required) ? schema.required : [];
-
-  if (!required.includes("error")) {
-    return undefined;
-  }
-
-  const error = (
-    schema.properties as
-      | { error?: { const?: unknown; enum?: unknown } }
-      | undefined
-  )?.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 undefined;
-}
-
 /**
  * The alternatives a schema stands for, as a list the status's own union
  * can take in.
@@ -177,20 +154,25 @@ export function envelopeCode(schema: JsonSchemaObject): string | undefined {
  * beside its union, a `title` or a `$defs`, is left whole: those keywords
  * belong to the union, and would be lost with it.
  */
-export function branchesOf(schema: JsonSchemaObject): JsonSchemaObject[] {
+export function branchesOf(
+  schema: JsonSchemaObject,
+  code: (schema: JsonSchemaObject) => string | undefined,
+): JsonSchemaObject[] {
   const keys = Object.keys(schema);
 
   if (keys.length !== 1) {
     return [schema];
   }
 
+  const within = (branch: JsonSchemaObject) => branchesOf(branch, code);
+
   if (Array.isArray(schema.anyOf)) {
-    return (schema.anyOf as JsonSchemaObject[]).flatMap(branchesOf);
+    return (schema.anyOf as JsonSchemaObject[]).flatMap(within);
   }
 
   if (Array.isArray(schema.oneOf)) {
-    const branches = (schema.oneOf as JsonSchemaObject[]).flatMap(branchesOf);
-    const codes = branches.map(envelopeCode);
+    const branches = (schema.oneOf as JsonSchemaObject[]).flatMap(within);
+    const codes = branches.map(code);
 
     if (
       codes.every((code) => code !== undefined) &&
@@ -209,34 +191,78 @@ function keyOf(status: number, code: string): string {
 
 /**
  * How two definitions of one envelope differ in what a client reads: the
- * fields one has and the other does not, or which of them are required.
- * Wording — a `message` example, `number` against `integer` for the
- * status — is not a difference a client would notice, and is not one.
+ * fields one has and the other does not, or which of them are required —
+ * at any depth, by path, so a format that nests its fields
+ * (`error.retryAfter`) is compared as closely as a flat one. Wording — a
+ * `message` example, `number` against `integer` for the status — is not a
+ * difference a client would notice, and is not one.
  */
 function differenceOf(
   kept: JsonSchemaObject,
   other: JsonSchemaObject,
 ): string | undefined {
-  const fields = (schema: JsonSchemaObject): string[] =>
-    Object.keys((schema.properties as Record<string, unknown>) ?? {});
-
-  const keptFields = fields(kept);
-  const otherFields = fields(other);
+  const keptShape = shapeOf(kept);
+  const otherShape = shapeOf(other);
 
-  const missing = otherFields.filter((name) => !keptFields.includes(name));
-  const extra = keptFields.filter((name) => !otherFields.includes(name));
-  const changed = [...missing, ...extra];
+  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: JsonSchemaObject): string =>
-    JSON.stringify(
-      [...(Array.isArray(schema.required) ? schema.required : [])].sort(),
-    );
-
-  return required(kept) === required(other)
+  return JSON.stringify(keptShape.required) ===
+    JSON.stringify(otherShape.required)
     ? undefined
     : "which fields are required";
 }
+
+/** How deep {@link shapeOf} looks; an envelope is a few levels at most. */
+const shapeDepth = 8;
+
+/**
+ * The paths of an object schema's fields, and of the required ones among
+ * them, following `properties` down. Sorted, so two shapes compare as
+ * strings.
+ */
+function shapeOf(schema: JsonSchemaObject): {
+  fields: string[];
+  required: string[];
+} {
+  const fields: string[] = [];
+  const required: string[] = [];
+
+  const walk = (node: JsonSchemaObject, prefix: string, depth: number) => {
+    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 as JsonSchemaObject, `${path}.`, depth + 1);
+      }
+    }
+  };
+
+  walk(schema, "", 0);
+
+  return { fields: fields.sort(), required: required.sort() };
+}

package/src/errors.ts

@@ -0,0 +1,177 @@
+/**
+ * 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 function resolveFormat(format: ErrorFormat | undefined): ResolvedFormat {
+  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) as JsonSchemaObject,
+    code: read
+      ? (schema) => read(schema as JsonSchemaKeywords)
+      : discriminator === undefined
+        ? () => undefined
+        : codeIn(discriminator),
+    discriminator,
+  };
+}
+
+/**
+ * The body of one failure in the framework's envelope, as JSON Schema.
+ *
+ * The status is a `const`, and so is the code whenever it is known: a
+ * generated client can then discriminate on `error` instead of receiving
+ * "an object with three strings", and a reader of the document sees
+ * `"BODY_TOO_LARGE"` rather than `string`.
+ *
+ * The message is documented by example, never as a `const` — it is wording
+ * meant for a human, the one field a client must not match on, and the one
+ * this project reserves the right to reword.
+ *
+ * Fields a failure carries besides come after the three, and never in
+ * their place.
+ */
+function envelope(failure: DocumentedFailure): JsonSchemaObject {
+  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 },
+  };
+}
+
+/**
+ * Reads the code of an envelope from one top-level field: required, and
+ * holding one string — a `const`, or an `enum` of one value.
+ */
+function codeIn(
+  field: string,
+): (schema: JsonSchemaObject) => string | undefined {
+  return (schema) => {
+    const required = Array.isArray(schema.required) ? schema.required : [];
+
+    if (!required.includes(field)) {
+      return undefined;
+    }
+
+    const value = (
+      schema.properties as
+        | Record<string, { const?: unknown; enum?: unknown } | undefined>
+        | undefined
+    )?.[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 undefined;
+  };
+}

package/src/index.ts

@@ -24,6 +24,8 @@ import { contributionsOf } from "./annotations.ts";
 import { schemaComponents } from "./components.ts";
 import type { OpenApiDocument, PathItemObject } from "./document.ts";
 import { envelopes as envelopeDefinitions } from "./envelopes.ts";
+import type { ErrorFormat } from "./errors.ts";
+import { resolveFormat } from "./errors.ts";
 import { declareEnvelopes, operationIds, operationOf } from "./operation.ts";
 import { toTemplate } from "./parameters.ts";
 
@@ -50,6 +52,7 @@ export type {
   PathItemObject,
   ResponseObject,
 } from "./document.ts";
+export type { DocumentedFailure, ErrorFormat } from "./errors.ts";
 export type {
   JsonSchema,
   JsonSchemaKeywords,
@@ -67,6 +70,33 @@ export interface OpenApiOptions {
 
   /** 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;
 }
 
 /**
@@ -111,7 +141,10 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   const warnings: GeneratorWarning[] = [];
   const schemes: Record<string, unknown> = {};
   const components = schemaComponents();
-  const envelopes = envelopeDefinitions(components);
+  const envelopes = envelopeDefinitions(
+    components,
+    resolveFormat(options.errors),
+  );
   const ids = operationIds();
   const described = app.entries.filter(
     (entry) => !entry.ws && !entry.def.docs?.hidden,

package/src/operation.ts

@@ -34,7 +34,8 @@ import type {
 import type { JsonSchemaObject } from "./emit.ts";
 import { emitted } from "./emit.ts";
 import type { Envelopes } from "./envelopes.ts";
-import { branchesOf, envelopeCode } from "./envelopes.ts";
+import { branchesOf } from "./envelopes.ts";
+import type { JsonSchema } from "./json-schema.ts";
 import { partParameters, pathParameters } from "./parameters.ts";
 
 /** Describes one route. */
@@ -103,11 +104,13 @@ export function declareEnvelopes(
     const described =
       schema === null ? undefined : emitted(schema, "", () => {});
 
-    for (const branch of described ? branchesOf(described) : []) {
-      const code = envelopeCode(branch);
+    const code = envelopes.format.code;
 
-      if (code !== undefined) {
-        envelopes.declare(Number(status), code, branch);
+    for (const branch of described ? branchesOf(described, code) : []) {
+      const found = code(branch);
+
+      if (found !== undefined) {
+        envelopes.declare(Number(status), found, branch);
       }
     }
   }
@@ -142,8 +145,8 @@ function branchesFor(
   envelopes: Envelopes,
   warn: (message: string) => void,
 ): Record<string, unknown>[] {
-  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
@@ -492,7 +495,12 @@ function failures(
     message?: string,
     fields?: DocumentedResponse["fields"],
   ): Record<string, unknown> => {
-    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
@@ -511,7 +519,12 @@ function failures(
           envelopes.ref(
             options.validationStatus,
             "VALIDATION_FAILED",
-            validationFailed(options.validationStatus),
+            envelopes.format.describe({
+              status: options.validationStatus,
+              error: "VALIDATION_FAILED",
+              message: "Validation failed",
+              fields: { issues },
+            }),
             warn,
           ) as unknown as Record<string, unknown>,
         ],
@@ -670,7 +683,8 @@ function merge(list: readonly Answer[], envelopes: Envelopes): ResponseObject {
  * builds a tagged union and narrows on the code, instead of trying the
  * shapes in turn. The mapping is spelled out, because without it OpenAPI
  * matches the value against the component's name — `Unauthorized`, where
- * the body says `UNAUTHORIZED`.
+ * the body says `UNAUTHORIZED`. The field is the error format's; a format
+ * that names none — its code nested below the top — has no discriminator.
  */
 function unionOf(
   schemas: readonly Record<string, unknown>[],
@@ -682,6 +696,12 @@ function unionOf(
     return only;
   }
 
+  const propertyName = envelopes.format.discriminator;
+
+  if (propertyName === undefined) {
+    return { anyOf: schemas };
+  }
+
   const mapping: Record<string, string> = {};
 
   for (const schema of schemas) {
@@ -697,7 +717,7 @@ function unionOf(
 
   return {
     anyOf: schemas,
-    discriminator: { propertyName: "error", mapping },
+    discriminator: { propertyName, mapping },
   };
 }
 
@@ -730,65 +750,21 @@ function describeStatus(status: string): string {
 }
 
 /**
- * The body of one framework-produced failure, as JSON Schema.
- *
- * The status is a `const`, and so is the code whenever the framework knows
- * which one it will be: a generated client can then discriminate on
- * `error` instead of receiving "an object with three strings", and a
- * reader of the document sees `"BODY_TOO_LARGE"` rather than `string`.
- *
- * The message is documented by example, never as a `const` — it is wording
- * meant for a human, the one field a client must not match on, and the one
- * this project reserves the right to reword.
- *
- * Fields a hook adds come after the three, and never in their place.
+ * What a validation failure carries besides the code and the message: every
+ * issue, with where it is. Handed to the error format as a field, for the
+ * format to place.
  */
-function envelope(
-  status: number,
-  error?: string,
-  message?: string,
-  fields: DocumentedResponse["fields"] = {},
-): JsonSchemaObject {
-  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 {
+const issues: JsonSchema = {
+  type: "array",
+  items: {
     type: "object",
-    required: ["status", "message", "error", ...added],
-    properties: { ...fields, ...own },
-  };
-}
-
-/** The validation envelope: the standard three fields, plus the issues. */
-function validationFailed(status: number): Record<string, unknown> {
-  const base = envelope(status, "VALIDATION_FAILED", "Validation failed");
-
-  return {
-    ...base,
-    required: ["status", "message", "error", "issues"],
+    required: ["message", "path"],
     properties: {
-      ...(base.properties as Record<string, unknown>),
-      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"] } },
     },
-  };
-}
+  },
+};
 
 /**
  * How a body of this type fails to parse — or nothing, for a text or a