@tetsujs/openapi 0.1.0

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,eAAe,CAAC;AAIrE,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,mBAAmB,EACnB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvD,YAAY,EACV,UAAU,EACV,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,GACf,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAsF1E"}

package/dist/src/index.js

@@ -0,0 +1,616 @@
+// @bun
+// packages/openapi/src/annotations.ts
+var docsKey = "~tetsu/hook-docs";
+function documented(hook, docs) {
+  const annotated = { ...hook };
+  Object.defineProperty(annotated, docsKey, {
+    enumerable: false,
+    value: { ...docsOf(hook), ...docs }
+  });
+  return annotated;
+}
+function secured(hook, requirement) {
+  return documented(hook, { security: requirement });
+}
+function docsOf(hook) {
+  return hook[docsKey];
+}
+function contributionsOf(chains, warn) {
+  const security = new Map;
+  const responses = new Map;
+  for (const slot of Object.values(chains)) {
+    for (const hook of slot) {
+      const docs = docsOf(hook);
+      if (!docs) {
+        continue;
+      }
+      if (docs.security) {
+        const claimed = security.get(docs.security.name);
+        if (!claimed) {
+          security.set(docs.security.name, docs.security);
+        } else if (JSON.stringify(claimed.scheme) !== JSON.stringify(docs.security.scheme)) {
+          warn?.(`two hooks claim the security scheme "${docs.security.name}" with different definitions; one of them is not described`);
+        }
+      }
+      for (const response of docs.responses ?? []) {
+        const key = `${response.status} ${response.description}`;
+        if (!responses.has(key)) {
+          responses.set(key, response);
+        }
+      }
+    }
+  }
+  return {
+    security: [...security.values()],
+    responses: [...responses.values()]
+  };
+}
+
+// packages/openapi/src/components.ts
+function schemaComponents() {
+  const schemas = {};
+  const registered = new Map;
+  return {
+    schemas,
+    ref(preferred, schema) {
+      const fingerprint = JSON.stringify(schema);
+      const already = registered.get(fingerprint);
+      if (already) {
+        return { $ref: `#/components/schemas/${already}` };
+      }
+      let name = preferred;
+      for (let attempt = 2;name in schemas; attempt += 1) {
+        name = `${preferred}${attempt}`;
+      }
+      schemas[name] = schema;
+      registered.set(fingerprint, name);
+      return { $ref: `#/components/schemas/${name}` };
+    }
+  };
+}
+function failureName(status, error) {
+  const name = (error ?? "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+  return name || `Failure${status}`;
+}
+
+// packages/openapi/src/emit.ts
+import { toJsonSchema } from "@tetsujs/core";
+var target = { target: "draft-2020-12" };
+function emitted(schema, subject, warn, direction = "output") {
+  let described;
+  try {
+    described = toJsonSchema(schema, target, direction);
+  } catch (error) {
+    warn(`${subject} schema failed to emit JSON Schema: ${reason(error)}`);
+    return;
+  }
+  if (!described) {
+    warn(`${subject} schema does not emit JSON Schema`);
+    return;
+  }
+  return withoutDialect(described);
+}
+function withoutDialect(schema) {
+  if (!("$schema" in schema)) {
+    return schema;
+  }
+  const { $schema: _, ...rest } = schema;
+  return rest;
+}
+function reason(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// packages/openapi/src/parameters.ts
+var wildcardName = "wildcard";
+function toTemplate(path) {
+  return path.split("/").map((segment) => {
+    if (segment.startsWith(":")) {
+      return `{${segment.slice(1)}}`;
+    }
+    return segment === "*" ? `{${wildcardName}}` : segment;
+  }).join("/");
+}
+function templateNames(path) {
+  const names = [];
+  for (const segment of path.split("/")) {
+    if (segment.startsWith(":")) {
+      names.push(segment.slice(1));
+    } else if (segment === "*") {
+      names.push(wildcardName);
+    }
+  }
+  return names;
+}
+function pathParameters(path, schema, warn) {
+  const properties = objectProperties(schema, "params", warn);
+  return templateNames(path).map((name) => ({
+    name,
+    in: "path",
+    required: true,
+    ...name === wildcardName ? {
+      description: "Matches the rest of the path, including further segments."
+    } : {},
+    schema: properties[name] ?? { type: "string" }
+  }));
+}
+function partParameters(schema, where, warn) {
+  if (!schema) {
+    return [];
+  }
+  const described = emitted(schema, `the ${where}`, warn, "input");
+  if (!described) {
+    return [];
+  }
+  const properties = described.properties ?? {};
+  const required = new Set(Array.isArray(described.required) ? described.required : []);
+  return Object.entries(properties).map(([name, property]) => ({
+    name,
+    in: where,
+    required: required.has(name),
+    schema: property
+  }));
+}
+function objectProperties(schema, where, warn) {
+  if (!schema) {
+    return {};
+  }
+  const described = emitted(schema, `the ${where}`, warn, "input");
+  if (!described) {
+    return {};
+  }
+  return described.properties ?? {};
+}
+
+// packages/openapi/src/operation.ts
+function operationOf(entry, options, components, ids, warn) {
+  const schema = entry.def.schema;
+  const parameters = [
+    ...pathParameters(entry.path, schema?.params, warn),
+    ...partParameters(schema?.query, "query", warn),
+    ...partParameters(schema?.headers, "header", warn),
+    ...partParameters(schema?.cookies, "cookie", warn)
+  ];
+  const body = requestBody(entry, warn);
+  const contributed = contributionsOf(entry.hooks, warn);
+  return {
+    operationId: ids.take(entry),
+    ...entry.def.docs?.summary === undefined ? {} : { summary: entry.def.docs.summary },
+    ...entry.def.docs?.description === undefined ? {} : { description: entry.def.docs.description },
+    ...entry.def.docs?.tags === undefined ? {} : { tags: entry.def.docs.tags },
+    ...entry.def.docs?.deprecated === undefined ? {} : { deprecated: entry.def.docs.deprecated },
+    ...parameters.length > 0 ? { parameters } : {},
+    ...body ? { requestBody: body } : {},
+    ...contributed.security.length > 0 ? {
+      security: contributed.security.map((requirement) => ({
+        [requirement.name]: requirement.scopes ?? []
+      }))
+    } : {},
+    responses: responses(entry, options, contributed, components, warn)
+  };
+}
+function operationIds() {
+  const taken = new Set;
+  return {
+    take(entry) {
+      const preferred = declaredId(entry) ?? derivedId(entry);
+      if (!taken.has(preferred)) {
+        taken.add(preferred);
+        return preferred;
+      }
+      const derived = derivedId(entry);
+      if (!taken.has(derived)) {
+        taken.add(derived);
+        return derived;
+      }
+      let name = derived;
+      for (let attempt = 2;taken.has(name); attempt += 1) {
+        name = `${derived}${attempt}`;
+      }
+      taken.add(name);
+      return name;
+    }
+  };
+}
+function declaredId(entry) {
+  if (entry.name === undefined) {
+    return;
+  }
+  const controller = entry.controller.replace(/Controller$/, "");
+  return `${lowerFirst(controller)}${capitalize(entry.name)}`;
+}
+function derivedId(entry) {
+  return `${entry.method.toLowerCase()}${entry.path.split(/[/:*]/).filter(Boolean).map(capitalize).join("")}`;
+}
+function requestBody(entry, warn) {
+  const declared = entry.def.schema?.body;
+  const bodyType = entry.def.bodyType ?? (declared ? "json" : undefined);
+  if (!bodyType) {
+    return;
+  }
+  const described = declared ? emitted(declared, "the body", warn, "input") : undefined;
+  const schema = described ? { schema: described } : {};
+  const required = bodyType !== "text" && bodyType !== "stream";
+  if (bodyType === "stream") {
+    return { required, content: { "application/octet-stream": {} } };
+  }
+  if (bodyType === "text") {
+    return { required, content: { "text/plain": schema } };
+  }
+  if (bodyType === "json") {
+    return { required, content: { "application/json": schema } };
+  }
+  const content = { "multipart/form-data": schema };
+  if (!described || !carriesBinary(described)) {
+    content["application/x-www-form-urlencoded"] = schema;
+  }
+  return { required, content };
+}
+function carriesBinary(root) {
+  const pending = [root];
+  const seen = new Set;
+  while (pending.length > 0) {
+    const node = pending.pop();
+    if (node === null || typeof node !== "object" || seen.has(node)) {
+      continue;
+    }
+    seen.add(node);
+    if (node.contentEncoding === "binary") {
+      return true;
+    }
+    for (const value of Object.values(node)) {
+      pending.push(value);
+    }
+  }
+  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);
+    }
+  }
+  if (!declared["200"] && !hasSuccess(declared)) {
+    declared["200"] = { description: "Successful response" };
+  }
+  return {
+    ...declared,
+    ...frameworkFailures(entry, options, contributed, declared, components, warn)
+  };
+}
+function frameworkFailures(entry, options, contributed, declared, components, 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 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))
+    });
+  }
+  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)
+    });
+  }
+  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)
+    });
+  }
+  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)
+      });
+    }
+    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;
+}
+function merge(declared, list) {
+  const descriptions = [
+    ...declared ? [declared.description] : [],
+    ...list.map((failure) => failure.description)
+  ];
+  const schemas = distinct([
+    ...declaredSchemas(declared),
+    ...list.map((failure) => failure.schema)
+  ]);
+  const [only] = schemas;
+  return {
+    description: descriptions.join("; "),
+    ...schemas.length === 1 && only ? { content: { "application/json": { schema: only } } } : { content: { "application/json": { schema: { anyOf: schemas } } } }
+  };
+}
+function declaredSchemas(declared) {
+  const schema = declared?.content?.["application/json"]?.schema;
+  return schema ? [schema] : [];
+}
+function distinct(schemas) {
+  const seen = new Set;
+  return schemas.filter((schema) => {
+    const fingerprint = JSON.stringify(schema);
+    if (seen.has(fingerprint)) {
+      return false;
+    }
+    seen.add(fingerprint);
+    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}`;
+}
+function envelope(status, error, message) {
+  return {
+    type: "object",
+    required: ["status", "message", "error"],
+    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"] } }
+          }
+        }
+      }
+    }
+  };
+}
+function parseFailure(bodyType) {
+  if (bodyType === "text" || bodyType === "stream") {
+    return;
+  }
+  return bodyType === "form" ? { error: "MALFORMED_FORM", message: "Body is not a valid form" } : { error: "MALFORMED_JSON", message: "Body is not valid JSON" };
+}
+function capitalize(value) {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+function lowerFirst(value) {
+  return value.charAt(0).toLowerCase() + value.slice(1);
+}
+// packages/openapi/src/controller.ts
+import { onMount, route } from "@tetsujs/core";
+
+// packages/openapi/src/page.ts
+var defaults = {
+  scalar: {
+    script: "https://cdn.jsdelivr.net/npm/@scalar/api-reference"
+  },
+  "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"
+  },
+  redoc: {
+    script: "https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js"
+  }
+};
+function docsPage(options) {
+  const assets = options.assets ?? defaults[options.ui];
+  const title = escapeHtml(options.title ?? "API documentation");
+  const url = escapeHtml(options.documentUrl);
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<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)}" />` : "",
+    "</head>",
+    "<body>",
+    body(options.ui, url),
+    `<script src="${escapeHtml(assets.script)}"></script>`,
+    bootstrap(options.ui, url),
+    "</body>",
+    "</html>"
+  ].filter(Boolean).join(`
+`);
+}
+function body(ui, url) {
+  if (ui === "scalar") {
+    return `<script id="api-reference" data-url="${url}"></script>`;
+  }
+  if (ui === "redoc") {
+    return `<redoc spec-url="${url}"></redoc>`;
+  }
+  return '<div id="swagger-ui"></div>';
+}
+function bootstrap(ui, url) {
+  if (ui !== "swagger-ui") {
+    return "";
+  }
+  return [
+    "<script>",
+    `SwaggerUIBundle({ url: "${url}", dom_id: "#swagger-ui" });`,
+    "</script>"
+  ].join(`
+`);
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&#39;");
+}
+
+// packages/openapi/src/controller.ts
+class DocsController {
+  options;
+  json;
+  ui;
+  document;
+  constructor(options, documentPath, uiPath, page) {
+    this.options = options;
+    const hidden = !options.documentSelf;
+    const json = route({
+      method: "GET",
+      path: "/openapi.json",
+      docs: { summary: "This document", tags: ["docs"], hidden },
+      handler: () => this.document
+    });
+    const ui = route({
+      method: "GET",
+      path: "/docs",
+      docs: { summary: "Rendered documentation", tags: ["docs"], hidden },
+      handler: () => new Response(page, {
+        headers: { "content-type": "text/html; charset=utf-8" }
+      })
+    });
+    this.json = { ...json, path: documentPath };
+    this.ui = { ...ui, path: uiPath };
+  }
+  [onMount](app) {
+    const generated = openapi(app, {
+      info: this.options.info,
+      ...this.options.servers ? { servers: this.options.servers } : {}
+    });
+    this.document = generated.document;
+    const report = this.options.onWarning ?? warn;
+    for (const warning of generated.warnings) {
+      report(warning);
+    }
+  }
+}
+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);
+}
+function warn(warning) {
+  console.warn(`[openapi] ${warning.route}: ${warning.message}`);
+}
+
+// packages/openapi/src/index.ts
+function openapi(app, options) {
+  const paths = {};
+  const warnings = [];
+  const schemes = {};
+  const components = schemaComponents();
+  const ids = operationIds();
+  const occupied = new Map;
+  for (const entry of app.entries) {
+    if (entry.ws || entry.def.docs?.hidden) {
+      continue;
+    }
+    const template = toTemplate(entry.path);
+    const route = `${entry.method} ${entry.path}`;
+    const operation = operationOf(entry, app.options, components, ids, (message) => {
+      warnings.push({ route, message });
+    });
+    for (const requirement of contributionsOf(entry.hooks).security) {
+      const defined = schemes[requirement.name];
+      if (defined === undefined) {
+        schemes[requirement.name] = requirement.scheme;
+        continue;
+      }
+      if (JSON.stringify(defined) !== JSON.stringify(requirement.scheme)) {
+        warnings.push({
+          route,
+          message: `the security scheme "${requirement.name}" is already defined differently; this definition is ignored`
+        });
+      }
+    }
+    const slot = `${entry.method.toLowerCase()} ${template}`;
+    const taken = occupied.get(slot);
+    if (taken) {
+      warnings.push({
+        route,
+        message: `${template} is already described by ${taken}, whose operation this replaces`
+      });
+    }
+    occupied.set(slot, route);
+    paths[template] = {
+      ...paths[template],
+      [entry.method.toLowerCase()]: operation
+    };
+  }
+  return {
+    document: {
+      openapi: "3.1.0",
+      info: options.info,
+      ...options.servers ? { servers: options.servers } : {},
+      paths,
+      ...componentsOf(schemes, components.schemas)
+    },
+    warnings
+  };
+}
+function componentsOf(securitySchemes, schemas) {
+  const components = {
+    ...Object.keys(securitySchemes).length > 0 ? { securitySchemes } : {},
+    ...Object.keys(schemas).length > 0 ? { schemas } : {}
+  };
+  return Object.keys(components).length > 0 ? { components } : {};
+}
+export {
+  DocsController,
+  docs,
+  docsPage,
+  documented,
+  openapi,
+  secured
+};
+
+//# debugId=698CDE5A6513C23964756E2164756E21
+//# sourceMappingURL=index.js.map