@tetsujs/openapi 0.4.1 → 0.5.0

package/src/envelopes.ts

@@ -0,0 +1,268 @@
+/**
+ * Error envelopes, one definition per status and code.
+ *
+ * An envelope reaches a document from four directions: a route's response
+ * map, a hook's annotation, a guard's security requirement, and the
+ * framework's own failures. Each used to be described where it arrived —
+ * a route's inline, the rest by reference — so one `UNAUTHORIZED` could be
+ * listed twice under one status, once as a `$ref` and once as the same
+ * shape without a name, and a generated client got a named type next to an
+ * anonymous twin.
+ *
+ * Here every envelope, whoever declared it, becomes a reference to the
+ * one definition of its status and code. That is also what makes a status
+ * discriminable: a client can branch on `error` only if every code under
+ * the status has exactly one shape.
+ *
+ * The route's definition wins. It is the author's own contract — usually
+ * the stricter one, a validator's `additionalProperties: false` — where a
+ * hook's is the framework's generic envelope. The routes are therefore
+ * 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 { 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.
+   */
+  declare(status: number, code: string, schema: JsonSchemaObject): void;
+
+  /**
+   * The reference to the definition of a status and code.
+   *
+   * `schema` is how the caller describes it. When a definition already
+   * exists, that is what is referenced; if the caller's differs from it
+   * in fields, `warn` hears about it — once per document, not once per
+   * operation the hook runs on.
+   */
+  ref(
+    status: number,
+    code: string,
+    schema: JsonSchemaObject,
+    warn: (message: string) => void,
+  ): SchemaRef;
+
+  /**
+   * The code a reference stands for, when it is one this handed out — what
+   * a discriminator maps back from.
+   */
+  codeOf(ref: string): string | undefined;
+}
+
+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>();
+  const codes = new Map<string, string>();
+  const names = new Map<string, string>();
+  const reported = new Set<string>();
+
+  return {
+    format,
+
+    declare(status, code, schema) {
+      const key = keyOf(status, code);
+
+      if (!declared.has(key)) {
+        declared.set(key, schema);
+      }
+    },
+
+    ref(status, code, schema, warn) {
+      const key = keyOf(status, code);
+      const definition = declared.get(key) ?? defined.get(key) ?? schema;
+
+      defined.set(key, definition);
+
+      const difference = differenceOf(definition, schema);
+
+      if (difference && !reported.has(`${key} ${difference}`)) {
+        reported.add(`${key} ${difference}`);
+        warn(
+          `the ${status} "${code}" is described by one definition in the document, and a definition that differs from it in ${difference} is not described`,
+        );
+      }
+
+      const existing = refs.get(key);
+
+      if (existing) {
+        return existing;
+      }
+
+      const created = components.ref(nameOf(status, code), definition);
+
+      refs.set(key, created);
+      codes.set(created.$ref, code);
+
+      return created;
+    },
+
+    codeOf(ref) {
+      return codes.get(ref);
+    },
+  };
+
+  /**
+   * The name a status and code are defined under: the code's, unless the
+   * same code under another status has it already, in which case the
+   * status tells the two apart — `Invalid` and `Invalid409`.
+   */
+  function nameOf(status: number, code: string): string {
+    const name = failureName(status, code);
+    const holder = names.get(name);
+
+    if (holder === undefined || holder === keyOf(status, code)) {
+      names.set(name, keyOf(status, code));
+
+      return name;
+    }
+
+    return `${name}${status}`;
+  }
+}
+
+/**
+ * The alternatives a schema stands for, as a list the status's own union
+ * can take in.
+ *
+ * `anyOf` nested in `anyOf` says nothing its branches do not say side by
+ * side, so a schema that is only an `anyOf` is replaced by its branches.
+ * A `oneOf` is different — "exactly one" of two overlapping shapes refuses
+ * what both accept — and is taken apart only when its branches cannot
+ * overlap: envelopes with a different code each. A schema with anything
+ * 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,
+  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(within);
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    const branches = (schema.oneOf as JsonSchemaObject[]).flatMap(within);
+    const codes = branches.map(code);
+
+    if (
+      codes.every((code) => code !== undefined) &&
+      new Set(codes).size === codes.length
+    ) {
+      return branches;
+    }
+  }
+
+  return [schema];
+}
+
+function keyOf(status: number, code: string): string {
+  return `${status} ${code}`;
+}
+
+/**
+ * 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 —
+ * 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 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(", ")}`;
+  }
+
+  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

@@ -23,10 +23,14 @@ import type { App } from "@tetsujs/core";
 import { contributionsOf } from "./annotations.ts";
 import { schemaComponents } from "./components.ts";
 import type { OpenApiDocument, PathItemObject } from "./document.ts";
-import { operationIds, operationOf } from "./operation.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";
 
 export type {
+  DocumentedHeader,
   DocumentedResponse,
   HookContributions,
   HookDocs,
@@ -41,12 +45,19 @@ 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";
 
@@ -59,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;
 }
 
 /**
@@ -103,7 +141,18 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   const warnings: GeneratorWarning[] = [];
   const schemes: Record<string, unknown> = {};
   const components = schemaComponents();
+  const envelopes = envelopeDefinitions(
+    components,
+    resolveFormat(options.errors),
+  );
   const ids = operationIds();
+  const described = app.entries.filter(
+    (entry) => !entry.ws && !entry.def.docs?.hidden,
+  );
+
+  for (const entry of described) {
+    declareEnvelopes(entry, envelopes);
+  }
 
   // Which route already occupies each slot of the document. Two routes the
   // router keeps apart can still meet here, because a template says less
@@ -114,11 +163,7 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
   // that works. It still loses it; it no longer does so without saying.
   const occupied = new Map<string, string>();
 
-  for (const entry of app.entries) {
-    if (entry.ws || entry.def.docs?.hidden) {
-      continue;
-    }
-
+  for (const entry of described) {
     const template = toTemplate(entry.path);
     const route = `${entry.method} ${entry.path}`;
 
@@ -126,6 +171,7 @@ export function openapi(app: App, options: OpenApiOptions): GeneratorResult {
       entry,
       app.options,
       components,
+      envelopes,
       ids,
       (message) => {
         warnings.push({ route, message });

package/src/json-schema.ts

@@ -0,0 +1,108 @@
+/**
+ * JSON Schema 2020-12, as written by hand.
+ *
+ * Every other schema in a document comes from a validator, which describes
+ * itself. What a hook adds to its answer — a field next to the envelope, a
+ * header — has no validator behind it, and is written as JSON Schema
+ * directly. Typed closed, keyword by keyword, so that an editor offers the
+ * keywords and a misspelled one is an error: an open record would take
+ * `minimun` and `{ type: "int" }` and put them in the document as they are.
+ *
+ * Closed on purpose, not by omission. The generator asks every schema for
+ * the 2020-12 dialect, and a dialect's keywords are a fixed list. The one
+ * open door is what OpenAPI itself allows in a schema — extensions, named
+ * `x-` — and no misspelling of a keyword starts with it.
+ *
+ * @module
+ */
+
+/** A primitive type name of JSON Schema. */
+export type JsonSchemaType =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "object"
+  | "array"
+  | "null";
+
+/**
+ * A schema: an object of keywords, or `true` and `false` — the schemas
+ * everything and nothing satisfy.
+ *
+ * @example
+ * ```ts
+ * const retryAfter: JsonSchema = { type: "integer", minimum: 0 };
+ * ```
+ */
+export type JsonSchema = JsonSchemaKeywords | boolean;
+
+/** The keywords of JSON Schema 2020-12. */
+export interface JsonSchemaKeywords {
+  readonly $schema?: string;
+  readonly $id?: string;
+  readonly $ref?: string;
+  readonly $anchor?: string;
+  readonly $dynamicRef?: string;
+  readonly $dynamicAnchor?: string;
+  readonly $vocabulary?: Readonly<Record<string, boolean>>;
+  readonly $comment?: string;
+  readonly $defs?: Readonly<Record<string, JsonSchema>>;
+
+  readonly type?: JsonSchemaType | readonly JsonSchemaType[];
+  readonly enum?: readonly unknown[];
+  readonly const?: unknown;
+
+  readonly multipleOf?: number;
+  readonly maximum?: number;
+  readonly exclusiveMaximum?: number;
+  readonly minimum?: number;
+  readonly exclusiveMinimum?: number;
+
+  readonly maxLength?: number;
+  readonly minLength?: number;
+  readonly pattern?: string;
+  readonly format?: string;
+  readonly contentEncoding?: string;
+  readonly contentMediaType?: string;
+  readonly contentSchema?: JsonSchema;
+
+  readonly prefixItems?: readonly JsonSchema[];
+  readonly items?: JsonSchema;
+  readonly contains?: JsonSchema;
+  readonly maxItems?: number;
+  readonly minItems?: number;
+  readonly uniqueItems?: boolean;
+  readonly maxContains?: number;
+  readonly minContains?: number;
+  readonly unevaluatedItems?: JsonSchema;
+
+  readonly properties?: Readonly<Record<string, JsonSchema>>;
+  readonly patternProperties?: Readonly<Record<string, JsonSchema>>;
+  readonly additionalProperties?: JsonSchema;
+  readonly unevaluatedProperties?: JsonSchema;
+  readonly propertyNames?: JsonSchema;
+  readonly required?: readonly string[];
+  readonly dependentRequired?: Readonly<Record<string, readonly string[]>>;
+  readonly dependentSchemas?: Readonly<Record<string, JsonSchema>>;
+  readonly maxProperties?: number;
+  readonly minProperties?: number;
+
+  readonly allOf?: readonly JsonSchema[];
+  readonly anyOf?: readonly JsonSchema[];
+  readonly oneOf?: readonly JsonSchema[];
+  readonly not?: JsonSchema;
+  readonly if?: JsonSchema;
+  readonly then?: JsonSchema;
+  readonly else?: JsonSchema;
+
+  readonly title?: string;
+  readonly description?: string;
+  readonly default?: unknown;
+  readonly deprecated?: boolean;
+  readonly readOnly?: boolean;
+  readonly writeOnly?: boolean;
+  readonly examples?: readonly unknown[];
+
+  readonly [extension: `x-${string}`]: unknown;
+}