@tetsujs/openapi 0.4.2 → 0.5.1

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);
   });
 }
@@ -450,17 +511,13 @@ function responses(entry, options, contributed, components, envelopes, warn) {
   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) : []
+      placeholder: describeStatus(status),
+      said: described ? wordsOf(described, envelopes) : [],
+      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : []
     });
   }
   if (![...answers.keys()].some((status) => status.startsWith("2"))) {
-    add("200", {
-      description: "Successful response",
-      placeholder: true,
-      schemas: []
-    });
+    add("200", { placeholder: "Successful response", said: [], schemas: [] });
   }
   for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
     add(String(status), answer);
@@ -475,7 +532,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;
   };
@@ -483,9 +545,19 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     found.push([
       options.validationStatus,
       {
-        description: "Request failed schema validation",
+        said: [
+          {
+            code: "VALIDATION_FAILED",
+            text: "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)
         ]
       }
     ]);
@@ -495,7 +567,9 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     found.push([
       status,
       {
-        description: requirement.description ?? `Request did not satisfy ${requirement.name}`,
+        said: [
+          said(requirement.error, requirement.description ?? `Request did not satisfy ${requirement.name}`)
+        ],
         schemas: [envelopeRef(status, requirement.error, requirement.message)]
       }
     ]);
@@ -505,7 +579,7 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     found.push([
       response.status,
       {
-        description: response.description,
+        said: [said(response.error, response.description)],
         schemas: described ? branchesFor(described, response.status, envelopes, warn) : [
           envelopeRef(response.status, response.error, response.message, response.fields)
         ],
@@ -519,7 +593,9 @@ function failures(entry, options, contributed, components, envelopes, warn) {
       found.push([
         400,
         {
-          description: "Body could not be parsed in the declared shape",
+          said: [
+            said(unparsable.error, "Body could not be parsed in the declared shape")
+          ],
           schemas: [envelopeRef(400, unparsable.error, unparsable.message)]
         }
       ]);
@@ -527,7 +603,9 @@ function failures(entry, options, contributed, components, envelopes, warn) {
     found.push([
       413,
       {
-        description: "Body exceeded the configured size limit",
+        said: [
+          said("BODY_TOO_LARGE", "Body exceeded the configured size limit")
+        ],
         schemas: [
           envelopeRef(413, "BODY_TOO_LARGE", "Body exceeds the configured limit")
         ]
@@ -537,7 +615,9 @@ function failures(entry, options, contributed, components, envelopes, warn) {
   found.push([
     500,
     {
-      description: "The request failed and nothing mapped the failure",
+      said: [
+        said("INTERNAL_SERVER_ERROR", "The request failed and nothing mapped the failure")
+      ],
       schemas: [
         envelopeRef(500, "INTERNAL_SERVER_ERROR", "Internal Server Error")
       ]
@@ -545,9 +625,24 @@ function failures(entry, options, contributed, components, envelopes, warn) {
   ]);
   return found;
 }
+function said(code, text) {
+  return code === undefined ? { text } : { code, text };
+}
+function wordsOf(schema, envelopes) {
+  if (typeof schema.description === "string") {
+    return [said(envelopes.format.code(schema), schema.description)];
+  }
+  return branchesOf(unionOnly(schema), envelopes.format.code).flatMap((branch) => typeof branch.description === "string" ? [said(envelopes.format.code(branch), branch.description)] : []);
+}
+function unionOnly(schema) {
+  if (typeof schema.description !== "string" || !Array.isArray(schema.anyOf) && !Array.isArray(schema.oneOf)) {
+    return schema;
+  }
+  const { description: _, ...union } = schema;
+  return union;
+}
 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 ?? {})) {
@@ -555,7 +650,7 @@ function merge(list, envelopes) {
     }
   }
   return {
-    description: (worded.length > 0 ? worded : list).map((answer) => answer.description).join("; "),
+    description: wording(list),
     ...Object.keys(headers).length > 0 ? { headers } : {},
     ...schemas.length > 0 ? {
       content: {
@@ -564,11 +659,38 @@ function merge(list, envelopes) {
     } : {}
   };
 }
+function wording(list) {
+  const seen = new Set;
+  const items = [];
+  for (const answer of list) {
+    for (const item of answer.said) {
+      const key = `${item.code ?? ""}
+${item.text}`;
+      if (!seen.has(key)) {
+        seen.add(key);
+        items.push(item);
+      }
+    }
+  }
+  const [only] = items;
+  if (items.length === 1 && only) {
+    return only.text;
+  }
+  if (items.length > 1) {
+    return items.map((item) => item.code === undefined ? `- ${item.text}` : `- \`${item.code}\`: ${item.text}`).join(`
+`);
+  }
+  return list.find((answer) => answer.placeholder)?.placeholder ?? "";
+}
 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;
@@ -580,7 +702,7 @@ function unionOf(schemas, envelopes) {
   }
   return {
     anyOf: schemas,
-    discriminator: { propertyName: "error", mapping }
+    discriminator: { propertyName, mapping }
   };
 }
 function distinct(schemas) {
@@ -600,40 +722,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 +850,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 +884,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 +951,5 @@ export {
   secured
 };
 
-//# debugId=8D8E4C09AE6F825C64756E2164756E21
+//# debugId=4A68DE756C1883B864756E2164756E21
 //# sourceMappingURL=index.js.map