@tetsujs/openapi 0.4.2 → 0.5.1

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,