@tetsujs/openapi 0.4.1 → 0.5.0

package/dist/src/index.js

@@ -102,6 +102,164 @@ function failureName(status, error) {
   return name || `Failure${status}`;
 }
 
+// packages/openapi/src/envelopes.ts
+function envelopes(components, format) {
+  const declared = new Map;
+  const defined = new Map;
+  const refs = new Map;
+  const codes = new Map;
+  const names = new Map;
+  const reported = new Set;
+  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);
+    }
+  };
+  function nameOf(status, code) {
+    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}`;
+  }
+}
+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(within);
+  }
+  if (Array.isArray(schema.oneOf)) {
+    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;
+    }
+  }
+  return [schema];
+}
+function keyOf(status, code) {
+  return `${status} ${code}`;
+}
+function differenceOf(kept, other) {
+  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";
+}
+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
+import { errorBody } from "@tetsujs/core";
+
 // packages/openapi/src/emit.ts
 import { toJsonSchema } from "@tetsujs/core";
 var target = { target: "draft-2020-12" };
@@ -192,7 +350,7 @@ function objectProperties(schema, where, warn) {
 }
 
 // packages/openapi/src/operation.ts
-function operationOf(entry, options, components, ids, warn) {
+function operationOf(entry, options, components, envelopes, ids, warn) {
   const schema = entry.def.schema;
   const parameters = [
     ...pathParameters(entry.path, schema?.params, warn),
@@ -211,9 +369,37 @@ function operationOf(entry, options, components, ids, warn) {
     ...parameters.length > 0 ? { parameters } : {},
     ...body ? { requestBody: body } : {},
     ...contributed.security.length > 0 ? { security: securityOf(contributed.conditions) } : {},
-    responses: responses(entry, options, contributed, components, warn)
+    responses: responses(entry, options, contributed, components, envelopes, warn)
   };
 }
+function declareEnvelopes(entry, envelopes) {
+  for (const [status, schema] of declaredResponses(entry)) {
+    const described = schema === null ? undefined : emitted(schema, "", () => {});
+    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);
+      }
+    }
+  }
+}
+function declaredResponses(entry) {
+  const response = entry.def.schema?.response;
+  if (!response) {
+    return [];
+  }
+  if ("~standard" in response) {
+    return [["200", response]];
+  }
+  return Object.entries(response);
+}
+function branchesFor(schema, status, envelopes, warn) {
+  return branchesOf(schema, envelopes.format.code).map((branch) => {
+    const code = envelopes.format.code(branch);
+    return code === undefined ? branch : envelopes.ref(status, code, branch, warn);
+  });
+}
 function securityOf(conditions) {
   let combinations = [{}];
   for (const alternatives of conditions) {
@@ -317,94 +503,161 @@ function carriesBinary(root) {
   }
   return false;
 }
-function responses(entry, options, contributed, components, warn) {
-  const declared = {};
-  const response = entry.def.schema?.response;
-  if (response && "~standard" in response) {
-    declared["200"] = jsonResponse(response, "Successful response", warn);
-  } else if (response) {
-    for (const [status, schema] of Object.entries(response)) {
-      declared[status] = schema === null ? { description: describeStatus(status) } : jsonResponse(schema, describeStatus(status), warn);
-    }
+function responses(entry, options, contributed, components, envelopes, warn) {
+  const answers = new Map;
+  const add = (status, answer) => {
+    answers.set(status, [...answers.get(status) ?? [], answer]);
+  };
+  for (const [status, schema] of declaredResponses(entry)) {
+    const described = schema === null ? undefined : emitted(schema, "a response", warn);
+    add(status, {
+      description: describeStatus(status),
+      placeholder: true,
+      schemas: described ? branchesFor(described, Number(status), envelopes, warn) : []
+    });
   }
-  if (!declared["200"] && !hasSuccess(declared)) {
-    declared["200"] = { description: "Successful response" };
+  if (![...answers.keys()].some((status) => status.startsWith("2"))) {
+    add("200", {
+      description: "Successful response",
+      placeholder: true,
+      schemas: []
+    });
   }
-  return {
-    ...declared,
-    ...frameworkFailures(entry, options, contributed, declared, components, warn)
-  };
+  for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
+    add(String(status), answer);
+  }
+  const described = {};
+  for (const [status, list] of answers) {
+    described[status] = merge(list, envelopes);
+  }
+  return described;
 }
-function frameworkFailures(entry, options, contributed, declared, components, warn) {
+function failures(entry, options, contributed, components, envelopes, warn) {
   const schema = entry.def.schema;
-  const failures = new Map;
-  const add = (status, failure) => {
-    const key = String(status);
-    failures.set(key, [...failures.get(key) ?? [], failure]);
+  const found = [];
+  const envelopeRef = (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;
   };
-  const envelopeRef = (status, error, message) => components.ref(failureName(status, error), envelope(status, error, message));
   if (schema?.params || schema?.query || schema?.headers || schema?.body) {
-    add(options.validationStatus, {
-      description: "Request failed schema validation",
-      schema: components.ref(failureName(options.validationStatus, "VALIDATION_FAILED"), validationFailed(options.validationStatus))
-    });
+    found.push([
+      options.validationStatus,
+      {
+        description: "Request failed schema validation",
+        schemas: [
+          envelopes.ref(options.validationStatus, "VALIDATION_FAILED", envelopes.format.describe({
+            status: options.validationStatus,
+            error: "VALIDATION_FAILED",
+            message: "Validation failed",
+            fields: { issues }
+          }), warn)
+        ]
+      }
+    ]);
   }
   for (const requirement of contributed.security) {
     const status = requirement.status ?? 401;
-    add(status, {
-      description: requirement.description ?? `Request did not satisfy ${requirement.name}`,
-      schema: envelopeRef(status, requirement.error, requirement.message)
-    });
+    found.push([
+      status,
+      {
+        description: requirement.description ?? `Request did not satisfy ${requirement.name}`,
+        schemas: [envelopeRef(status, requirement.error, requirement.message)]
+      }
+    ]);
   }
   for (const response of contributed.responses) {
     const described = response.schema ? emitted(response.schema, "a hook's response", warn) : undefined;
-    add(response.status, {
-      description: response.description,
-      schema: described ?? envelopeRef(response.status, response.error, response.message)
-    });
+    found.push([
+      response.status,
+      {
+        description: response.description,
+        schemas: described ? branchesFor(described, response.status, envelopes, warn) : [
+          envelopeRef(response.status, response.error, response.message, response.fields)
+        ],
+        ...response.headers ? { headers: response.headers } : {}
+      }
+    ]);
   }
   if (schema?.body || entry.def.bodyType) {
     const unparsable = parseFailure(entry.def.bodyType);
     if (unparsable) {
-      add(400, {
-        description: "Body could not be parsed in the declared shape",
-        schema: envelopeRef(400, unparsable.error, unparsable.message)
-      });
+      found.push([
+        400,
+        {
+          description: "Body could not be parsed in the declared shape",
+          schemas: [envelopeRef(400, unparsable.error, unparsable.message)]
+        }
+      ]);
+    }
+    found.push([
+      413,
+      {
+        description: "Body exceeded the configured size limit",
+        schemas: [
+          envelopeRef(413, "BODY_TOO_LARGE", "Body exceeds the configured limit")
+        ]
+      }
+    ]);
+  }
+  found.push([
+    500,
+    {
+      description: "The request failed and nothing mapped the failure",
+      schemas: [
+        envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error")
+      ]
+    }
+  ]);
+  return found;
+}
+function merge(list, envelopes) {
+  const schemas = distinct(list.flatMap((answer) => answer.schemas));
+  const worded = list.filter((answer) => !answer.placeholder);
+  const headers = {};
+  for (const answer of list) {
+    for (const [name, header] of Object.entries(answer.headers ?? {})) {
+      headers[name] ??= header;
     }
-    add(413, {
-      description: "Body exceeded the configured size limit",
-      schema: envelopeRef(413, "BODY_TOO_LARGE", "Body exceeds the configured limit")
-    });
-  }
-  add(500, {
-    description: "The request failed and nothing mapped the failure",
-    schema: envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error")
-  });
-  const responses = {};
-  for (const [status, list] of failures) {
-    responses[status] = merge(declared[status], list);
   }
-  return responses;
+  return {
+    description: (worded.length > 0 ? worded : list).map((answer) => answer.description).join("; "),
+    ...Object.keys(headers).length > 0 ? { headers } : {},
+    ...schemas.length > 0 ? {
+      content: {
+        "application/json": { schema: unionOf(schemas, envelopes) }
+      }
+    } : {}
+  };
 }
-function merge(declared, list) {
-  const descriptions = [
-    ...declared ? [declared.description] : [],
-    ...list.map((failure) => failure.description)
-  ];
-  const schemas = distinct([
-    ...declaredSchemas(declared),
-    ...list.map((failure) => failure.schema)
-  ]);
+function unionOf(schemas, envelopes) {
   const [only] = schemas;
+  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;
+    const code = typeof ref === "string" ? envelopes.codeOf(ref) : undefined;
+    if (typeof ref !== "string" || code === undefined) {
+      return { anyOf: schemas };
+    }
+    mapping[code] = ref;
+  }
   return {
-    description: descriptions.join("; "),
-    ...schemas.length === 1 && only ? { content: { "application/json": { schema: only } } } : { content: { "application/json": { schema: { anyOf: schemas } } } }
+    anyOf: schemas,
+    discriminator: { propertyName, mapping }
   };
 }
-function declaredSchemas(declared) {
-  const schema = declared?.content?.["application/json"]?.schema;
-  return schema ? [schema] : [];
-}
 function distinct(schemas) {
   const seen = new Set;
   return schemas.filter((schema) => {
@@ -416,57 +669,23 @@ function distinct(schemas) {
     return true;
   });
 }
-function jsonResponse(schema, description, warn) {
-  const described = emitted(schema, "a response", warn);
-  if (!described) {
-    return { description };
-  }
-  return {
-    description,
-    content: { "application/json": { schema: described } }
-  };
-}
-function hasSuccess(declared) {
-  return Object.keys(declared).some((status) => status.startsWith("2"));
-}
 function describeStatus(status) {
   if (status === "204") {
     return "No content";
   }
-  return status.startsWith("2") ? "Successful response" : `Response ${status}`;
+  return status.startsWith("2") ? "Successful response" : errorBody(Number(status)).message;
 }
-function envelope(status, error, message) {
-  return {
+var issues = {
+  type: "array",
+  items: {
     type: "object",
-    required: ["status", "message", "error"],
+    required: ["message", "path"],
     properties: {
-      status: { type: "integer", const: status },
-      message: message ? { type: "string", examples: [message] } : { type: "string" },
-      error: error ? { type: "string", const: error } : { type: "string" }
-    }
-  };
-}
-function validationFailed(status) {
-  const base = envelope(status, "VALIDATION_FAILED", "Validation failed");
-  return {
-    ...base,
-    required: ["status", "message", "error", "issues"],
-    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;
@@ -485,14 +704,24 @@ import { onMount, route } from "@tetsujs/core";
 // packages/openapi/src/page.ts
 var defaults = {
   scalar: {
-    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.72.1/dist/browser/standalone.js",
+    integrity: {
+      script: "sha384-U11tb2XnKvmwt8RlTvnwUnYgrN+ur4Xyh9htLhjajWNR/Oyl5AX5DEz00qRmlrmK"
+    }
   },
   "swagger-ui": {
-    script: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
-    style: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css"
+    script: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.0/swagger-ui-bundle.js",
+    style: "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5.33.0/swagger-ui.css",
+    integrity: {
+      script: "sha384-YDALVcy8kj8yltLBVi1vBiBAUqdxvus673gM8XKwiy6aDUJFXivF/KCufekjYbVf",
+      style: "sha384-Ov4/wv3j2bmct8cDc5X4ngJZohVPzEmc6uDPH8WeljUxO5vtoykvMEfbu9Vh6RaW"
+    }
   },
   redoc: {
-    script: "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"
+    script: "https://cdn.jsdelivr.net/npm/redoc@2.5.4/bundles/redoc.standalone.js",
+    integrity: {
+      script: "sha384-w447zOpYfw/1Tv/5AK9NfHTlQIqE3RVR6KY62jCyy9zNDgO64cMwGGP1Fj0zJVf5"
+    }
   }
 };
 function docsPage(options) {
@@ -506,11 +735,11 @@ function docsPage(options) {
     '<meta charset="utf-8" />',
     '<meta name="viewport" content="width=device-width, initial-scale=1" />',
     `<title>${title}</title>`,
-    assets.style ? `<link rel="stylesheet" href="${escapeHtml(assets.style)}" />` : "",
+    assets.style ? `<link rel="stylesheet" href="${escapeHtml(assets.style)}"${verified(assets.integrity?.style)} />` : "",
     "</head>",
     "<body>",
     body(options.ui, url),
-    `<script src="${escapeHtml(assets.script)}"></script>`,
+    `<script src="${escapeHtml(assets.script)}"${verified(assets.integrity?.script)}></script>`,
     bootstrap(options.ui, url),
     "</body>",
     "</html>"
@@ -537,6 +766,9 @@ function bootstrap(ui, url) {
   ].join(`
 `);
 }
+function verified(integrity) {
+  return integrity ? ` integrity="${escapeHtml(integrity)}" crossorigin="anonymous"` : "";
+}
 function escapeHtml(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
 }
@@ -547,7 +779,8 @@ class DocsController {
   json;
   ui;
   document;
-  constructor(options, documentPath, uiPath, page) {
+  page;
+  constructor(options, documentPath, uiPath) {
     this.options = options;
     const hidden = !options.documentSelf;
     const json = route({
@@ -560,19 +793,31 @@ class DocsController {
       method: "GET",
       path: "/docs",
       docs: { summary: "Rendered documentation", tags: ["docs"], hidden },
-      handler: () => new Response(page, {
+      handler: () => new Response(this.page, {
         headers: { "content-type": "text/html; charset=utf-8" }
       })
     });
     this.json = { ...json, path: documentPath };
-    this.ui = { ...ui, path: uiPath };
+    this.ui = options.ui === false ? undefined : { ...ui, path: uiPath };
   }
   [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";
+    const json = this.json;
+    const served = app.entries.find((entry) => entry.def === json);
+    if (ui !== false && served) {
+      this.page = docsPage({
+        ui,
+        documentUrl: served.path,
+        title: this.options.title ?? this.options.info.title,
+        ...this.options.assets ? { assets: this.options.assets } : {}
+      });
+    }
     const report = this.options.onWarning ?? warn;
     for (const warning of generated.warnings) {
       report(warning);
@@ -580,15 +825,7 @@ class DocsController {
   }
 }
 function docs(options) {
-  const documentPath = options.path ?? "/openapi.json";
-  const uiPath = options.uiPath ?? "/docs";
-  const page = docsPage({
-    ui: options.ui ?? "scalar",
-    documentUrl: documentPath,
-    title: options.title ?? options.info.title,
-    ...options.assets ? { assets: options.assets } : {}
-  });
-  return new DocsController(options, documentPath, uiPath, page);
+  return new DocsController(options, options.path ?? "/openapi.json", options.uiPath ?? "/docs");
 }
 function warn(warning) {
   console.warn(`[openapi] ${warning.route}: ${warning.message}`);
@@ -600,15 +837,17 @@ function openapi(app, options) {
   const warnings = [];
   const schemes = {};
   const components = schemaComponents();
+  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) {
+    declareEnvelopes(entry, envelopes2);
+  }
   const occupied = new Map;
-  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}`;
-    const operation = operationOf(entry, app.options, components, ids, (message) => {
+    const operation = operationOf(entry, app.options, components, envelopes2, ids, (message) => {
       warnings.push({ route, message });
     });
     for (const requirement of contributionsOf(entry.hooks).security) {
@@ -665,5 +904,5 @@ export {
   secured
 };
 
-//# debugId=AFF7EFC95370A0C664756E2164756E21
+//# debugId=B1D856E7F5B6819164756E2164756E21
 //# sourceMappingURL=index.js.map