@lovrozagar/honey 0.7.3 → 1.0.0-rc.1

package/dist/openapi/register.js

@@ -1,20 +1,13 @@
-import { generateManifest, generateOpenApi } from "../codegen.js";
-import { toYaml } from "../yaml.js";
-import { scalar } from "./scalar.js";
-import { artifactResponse, toServedArtifact } from "./serve.js";
-import { swagger } from "./swagger.js";
-import { registerOpenApiRuntime } from "./spec-factory.js";
-export function enableOpenApi() {
-    registerOpenApiRuntime({
-        artifactResponse,
-        docsUi: (kind, specUrl) => (kind === "swagger" ? swagger({ url: specUrl }) : scalar({ url: specUrl })),
-        /* served artifacts follow the document's visibility policy and never fail on one schema */
-        generateManifest: (app, options) => Promise.resolve(generateManifest(app, { visibility: "published", ...options })),
-        generateOpenApi: (app, options) => generateOpenApi(app, { onSchemaError: "warn", ...options }),
-        toServedArtifact,
-        toYaml,
-    });
-}
-enableOpenApi();
-export { spec } from "./spec.js";
-//# sourceMappingURL=register.js.map
+/**
+ * `@lovrozagar/honey/openapi`: the app's OpenAPI 3.1 document and route manifest, generated or
+ * served, and the docs pages. A plain subpath: nothing registers itself, and an app that never
+ * imports it carries none of it.
+ */
+export { SERVED } from "../routing/register.js";
+export { generateOpenApi, } from "./generate.js";
+export { generateManifest, } from "./manifest.js";
+export { inlineJson } from "./docs-page.js";
+export { scalar } from "./scalar.js";
+export { serveManifest, serveOpenApi } from "./serve.js";
+export { swagger } from "./swagger.js";
+export { toYaml } from "./yaml.js";

package/dist/openapi/responses.d.ts

@@ -0,0 +1,44 @@
+import type { JsonSchema } from "../schema/to-json-schema.ts";
+import type { ErrorFormat } from "../errors/problem-json.ts";
+import type { OutputSchemas } from "../routing/output-types.ts";
+import type { CollectedError } from "./collect.ts";
+export type MediaObject = {
+    schema?: JsonSchema;
+};
+export type HeaderObject = {
+    description?: string;
+    required?: boolean;
+    schema: JsonSchema;
+};
+export type ResponseObject = {
+    content?: Record<string, MediaObject>;
+    description: string;
+    headers?: Record<string, HeaderObject>;
+    /** set on every response the route's declared errors produce, so a reader tells it from a declared output */
+    "x-honey-error"?: true;
+};
+/** One declared error key as an operation's `x-honey-errors` carries it: its status (null: none) and own schema. */
+export type DeclaredError = {
+    schema?: JsonSchema;
+    status: number | null;
+};
+/** A schema converted for this operation: `hint` names a component it lifts. */
+export type Convert = (schema: unknown, io: "input" | "output", hint: string) => JsonSchema;
+/** The app's error settings, their schemas already converted. */
+export type ErrorSettings = {
+    readonly customErrorSchema: JsonSchema | null;
+    readonly errorFormat: ErrorFormat;
+    readonly errorSchema: JsonSchema | null;
+};
+/** Every answer `output` declares, with its headers and redirects. */
+export declare function successResponses(output: OutputSchemas | null, convert: Convert, hint: (code: number) => string): Record<string, ResponseObject>;
+/** honey's envelope, as every standard error answers by default. */
+export declare function defaultEnvelope(): JsonSchema;
+/**
+ * Add the errors `errorMeta` names to `responses`, one response per status, each status left to an
+ * answer the route declares there itself. A key with no status is not documented as a response.
+ * Returns every declared key with its status and own schema: the operation's `x-honey-errors`.
+ */
+export declare function addErrorResponses(responses: Record<string, ResponseObject>, errorMeta: Readonly<Record<string, CollectedError>>, settings: ErrorSettings, convert: (schema: unknown, hint: string) => JsonSchema): Record<string, DeclaredError>;
+/** `responses` keyed in ascending status order: the same bytes however they were declared. */
+export declare function ordered(responses: Record<string, ResponseObject>): Record<string, ResponseObject>;

package/dist/openapi/responses.js

@@ -0,0 +1,159 @@
+/**
+ * An operation's responses: each declared answer by status and media type, its redirects and the
+ * headers each status declares, then the errors the route may answer in the app's error format.
+ * honey's envelope names a status's keys and status as enums; Problem Details (RFC 9457) names the
+ * keys' type URIs. A schema error documents its own body, under JSON, in either format.
+ */
+import { compareCodeUnits } from "../schema/canonicalize.js";
+import { statusKeyToCode } from "../response/status.js";
+const NOT_MEDIA = ["headers", "redirect"];
+const LOCATION = { description: "Redirect target URL", schema: { format: "uri", type: "string" } };
+const STRING = { type: "string" };
+const describe = (statusKey) => statusKey.replaceAll("_", " ");
+/** The response at `code`, created with `description` when the route has none there yet. */
+function at(out, code, description) {
+    const key = String(code);
+    out[key] ??= { description };
+    return out[key];
+}
+/** The header objects of an object schema: one per property, required when the schema says. */
+function headersOf(schema) {
+    const properties = (schema.properties ?? {});
+    const required = (schema.required ?? []);
+    return Object.fromEntries(Object.entries(properties).map(([name, property]) => [
+        name,
+        { required: required.includes(name), schema: property },
+    ]));
+}
+/** Every answer `output` declares, with its headers and redirects. */
+export function successResponses(output, convert, hint) {
+    const out = {};
+    if (output === null)
+        return out;
+    for (const [media, statuses] of Object.entries(output)) {
+        if (NOT_MEDIA.includes(media))
+            continue;
+        for (const [statusKey, schema] of Object.entries(statuses)) {
+            const code = statusKeyToCode[statusKey];
+            const response = at(out, code, describe(statusKey));
+            response.content ??= {};
+            response.content[media] = schema === true ? {} : { schema: convert(schema, "output", hint(code)) };
+        }
+    }
+    for (const statusKey of Object.keys(output.redirect ?? {})) {
+        at(out, statusKeyToCode[statusKey], describe(statusKey)).headers = { Location: LOCATION };
+    }
+    for (const [statusKey, schema] of Object.entries(output.headers ?? {})) {
+        const code = statusKeyToCode[statusKey];
+        const declared = headersOf(convert(schema, "output", `${hint(code)}Headers`));
+        const response = at(out, code, describe(statusKey));
+        /* a declared location says more than the default */
+        const kept = Object.hasOwn(declared, "location") ? {} : (response.headers ?? {});
+        response.headers = { ...kept, ...declared };
+    }
+    return out;
+}
+const FIELD_ERRORS = {
+    additionalProperties: {
+        items: {
+            properties: { error_key: STRING, message: STRING, path: STRING },
+            required: ["error_key", "message", "path"],
+            type: "object",
+        },
+        type: "array",
+    },
+    type: "object",
+};
+/** honey's envelope, as every standard error answers by default. */
+export function defaultEnvelope() {
+    return {
+        properties: {
+            error_key: { ...STRING },
+            fields: structuredClone(FIELD_ERRORS),
+            message: { ...STRING },
+            status: { type: "integer" },
+            status_key: { ...STRING },
+            success: { const: false },
+        },
+        required: ["error_key", "fields", "message", "status", "status_key", "success"],
+        type: "object",
+    };
+}
+/** `schema` with `error_key` and `status` narrowed to `keys` and `code`, where it has them. */
+function narrowed(schema, keys, code) {
+    const out = structuredClone(schema);
+    const properties = out.properties;
+    if (properties?.error_key !== undefined)
+        properties.error_key = { enum: [...keys], type: "string" };
+    if (properties?.status !== undefined)
+        properties.status = { enum: [code], type: "integer" };
+    return out;
+}
+/** A Problem Details document for standard errors `keys` at `code`. */
+function problem(keys, code) {
+    return {
+        properties: {
+            detail: { ...STRING },
+            errors: structuredClone(FIELD_ERRORS),
+            instance: { ...STRING },
+            status: { enum: [code], type: "integer" },
+            title: { ...STRING },
+            type: { enum: keys.map((key) => `https://honey.dev/errors/${key}`), type: "string" },
+        },
+        required: ["detail", "status", "title", "type"],
+        type: "object",
+    };
+}
+const oneOrOneOf = (schemas) => schemas.length === 1 ? schemas[0] : { oneOf: [...schemas] };
+/** Every declared error key, code-unit ordered: its status (null when it has none) and its own schema, converted once. */
+function declaredErrors(errorMeta, convert) {
+    const declared = {};
+    for (const key of Object.keys(errorMeta).sort(compareCodeUnits)) {
+        const { schema, status } = errorMeta[key];
+        const entry = { status: status > 0 ? status : null };
+        /* a key with a schema always has a status: only an unknown key (no schema) has none */
+        if (schema !== null)
+            entry.schema = convert(schema, `Error${status}`);
+        declared[key] = entry;
+    }
+    return declared;
+}
+/**
+ * Add the errors `errorMeta` names to `responses`, one response per status, each status left to an
+ * answer the route declares there itself. A key with no status is not documented as a response.
+ * Returns every declared key with its status and own schema: the operation's `x-honey-errors`.
+ */
+export function addErrorResponses(responses, errorMeta, settings, convert) {
+    const declared = declaredErrors(errorMeta, convert);
+    const byStatus = new Map();
+    for (const [key, { schema, status }] of Object.entries(declared)) {
+        if (status === null || Object.hasOwn(responses, String(status)))
+            continue;
+        const group = byStatus.get(status) ?? { custom: [], keys: [], standard: [] };
+        byStatus.set(status, group);
+        group.keys.push(key);
+        if (schema === undefined)
+            group.standard.push(key);
+        else
+            group.custom.push(settings.customErrorSchema === null ? schema : { allOf: [schema, settings.customErrorSchema] });
+    }
+    for (const [code, { custom, keys, standard }] of byStatus) {
+        const content = {};
+        if (settings.errorFormat === "problem+json") {
+            if (standard.length > 0)
+                content["application/problem+json"] = { schema: problem(standard, code) };
+            if (custom.length > 0)
+                content["application/json"] = { schema: oneOrOneOf(custom) };
+        }
+        else {
+            const envelope = standard.length > 0 ? [narrowed(settings.errorSchema ?? defaultEnvelope(), standard, code)] : [];
+            content["application/json"] = { schema: oneOrOneOf([...envelope, ...custom]) };
+        }
+        responses[String(code)] = { content, description: keys.join(", "), "x-honey-error": true };
+    }
+    return declared;
+}
+/** `responses` keyed in ascending status order: the same bytes however they were declared. */
+export function ordered(responses) {
+    return Object.fromEntries(Object.entries(responses).sort(([a], [b]) => Number(a) - Number(b)));
+}

package/dist/openapi/scalar.d.ts

@@ -1,14 +1,4 @@
-import type { TypedResponse } from "../response.ts";
-type ScalarOptions = {
-    url: string;
-    [key: string]: unknown;
-};
-export declare function scalar(options: ScalarOptions): (ctx: {
-    res: {
-        html(sk: "ok", body: string, opts?: {
-            headers?: Record<string, string>;
-        }): TypedResponse;
-    };
-}) => TypedResponse;
-export {};
-//# sourceMappingURL=scalar.d.ts.map
+/** `scalar(config)`: the Scalar API reference page for the document at `config.url`. */
+import type { TypedResponse } from "../response/response.ts";
+import { type DocsConfig, type DocsContext } from "./docs-page.ts";
+export declare function scalar(config: DocsConfig): (ctx: DocsContext) => TypedResponse;

package/dist/openapi/scalar.js

@@ -1,7 +1,6 @@
-import { docsPage, escapeAttribute, inlineJson, SCALAR } from "./docs-page.js";
-export function scalar(options) {
-    const { url, ...rest } = options;
-    const config = inlineJson({ url, ...rest });
+import { docsPage, inlineJson, SCALAR } from "./docs-page.js";
+export function scalar(config) {
+    const inline = inlineJson(config);
     return docsPage((nonce) => `<!DOCTYPE html>
 <html>
 <head>
@@ -12,10 +11,9 @@ export function scalar(options) {
 <body>
   <div id="app"></div>
   <script src="${SCALAR.js.url}" integrity="${SCALAR.js.integrity}" crossorigin="anonymous"></script>
-  <script nonce="${escapeAttribute(nonce)}">
-    Scalar.createApiReference(document.getElementById("app"), ${config})
+  <script nonce="${nonce}">
+    Scalar.createApiReference(document.getElementById("app"), ${inline})
   </script>
 </body>
 </html>`);
 }
-//# sourceMappingURL=scalar.js.map

package/dist/openapi/security.d.ts

@@ -0,0 +1,4 @@
+import type { EmittedOperation } from "./paths.ts";
+export type SecurityReport = (level: "error" | "warn", message: string) => void;
+/** Report each scheme an operation names that `schemes` does not declare. */
+export declare function checkSecurity(operations: readonly EmittedOperation[], schemes: Readonly<Record<string, unknown>> | undefined, report: SecurityReport): void;

package/dist/openapi/security.js

@@ -0,0 +1,25 @@
+/**
+ * The document's security: the schemes the caller declares, and the check that every scheme an
+ * operation's `security` names is among them. Naming an undeclared scheme is an error once schemes
+ * are declared; with none declared at all it is only said, since the document may be partial.
+ */
+import { securitySchemeNames } from "../meta/meta-spec.js";
+/** Report each scheme an operation names that `schemes` does not declare. */
+export function checkSecurity(operations, schemes, report) {
+    const said = new Set();
+    for (const { method, operation, path } of operations) {
+        for (const name of securitySchemeNames(operation.security)) {
+            if (schemes !== undefined && Object.hasOwn(schemes, name))
+                continue;
+            const where = `${method.toUpperCase()} ${path}`;
+            if (schemes === undefined) {
+                if (said.has(name))
+                    continue;
+                said.add(name);
+                report("warn", `security scheme "${name}" (first used by ${where}) is not declared — pass securitySchemes`);
+            }
+            else
+                report("error", `${where}: security names "${name}", which is not in securitySchemes`);
+        }
+    }
+}

package/dist/openapi/serve.d.ts

@@ -1,9 +1,25 @@
-import type { ServedArtifact } from "./spec-factory.ts";
-/** Serialize `value` once; the result is cached per route epoch by the caller. */
-export declare function toServedArtifact(body: string, contentType: string): Promise<ServedArtifact>;
-/**
- * The response for a served artifact. Clients revalidate (`no-cache`) rather than reuse a stale
- * document after a deploy; an unchanged document costs a 304.
- */
-export declare function artifactResponse(request: Request, artifact: ServedArtifact): Response;
-//# sourceMappingURL=serve.d.ts.map
+import { type GenerateOpenApiOptions } from "./generate.ts";
+import { type GenerateManifestOptions } from "./manifest.ts";
+export type ServeOpenApiOptions = Omit<GenerateOpenApiOptions, "info" | "invalidate" | "onSchemaError"> & {
+    readonly description?: string;
+    /** a docs page for the document, at `docsPath` */
+    readonly docs?: "scalar" | "swagger";
+    /** `"/docs"` by default */
+    readonly docsPath?: string;
+    /** `false` mounts nothing */
+    readonly enabled?: boolean;
+    /** the stem the document is served at, `"/openapi"` by default: `.json`, `.yaml` and `.yml` follow */
+    readonly path?: string;
+    readonly title: string;
+    readonly version: string;
+};
+export type ServeManifestOptions = Omit<GenerateManifestOptions, "visibility"> & {
+    /** `false` mounts nothing */
+    readonly enabled?: boolean;
+    /** `"/manifest.json"` by default */
+    readonly path?: string;
+};
+/** Serve the app's OpenAPI document, and a docs page for it when asked, from `app`; returns `app`. */
+export declare function serveOpenApi<A>(app: A, options: ServeOpenApiOptions): A;
+/** Serve the app's published manifest from `app`; returns `app`. */
+export declare function serveManifest<A>(app: A, options?: ServeManifestOptions): A;

package/dist/openapi/serve.js

@@ -1,36 +1,115 @@
 /**
- * Serving side of `app.openapi()` and `app.manifest()`: serialize a document once, tag it, and
- * answer conditional requests. Part of the lazily loaded OpenAPI feature, so none of this sits
- * in the core bundle.
+ * `serveOpenApi(app, options)` and `serveManifest(app, options?)`: an app serving its own document
+ * (JSON at `${path}.json`, the same document as YAML at `.yaml` and `.yml`, and a docs page when
+ * asked) and its published manifest. Each is a plain internal GET on the handle it is called on,
+ * so the handle's basePath and middleware apply, marked SERVED so it stays with this app. A call
+ * mounts all its routes or, when any path is taken, none. Each artifact is built once per route
+ * change, a failed build kept for its routes too, and answered with a strong ETag, `no-cache` and a
+ * 304 for a matching `If-None-Match`. A served document never runs the invalidate check and
+ * documents a schema it cannot convert unconstrained, with a warning.
  */
-import { ifNoneMatchHits } from "../etag.js";
-const encoder = new TextEncoder();
-/** Base64url of the first 16 bytes of SHA-256, quoted: a strong validator for the exact bytes. */
-async function entityTag(body) {
-    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(body))).subarray(0, 16);
-    let binary = "";
-    for (let i = 0; i < hash.length; i++)
-        binary += String.fromCharCode(hash[i]);
-    return `"${btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")}"`;
+import { ifNoneMatchHits } from "../response/etag.js";
+import { isStaticPattern, joinPatterns, parsePattern } from "../routing/pattern.js";
+import { assertRouteFree, GRAPH, SERVED, VIEW } from "../routing/register.js";
+import { generateOpenApi } from "./generate.js";
+import { generateManifest } from "./manifest.js";
+import { scalar } from "./scalar.js";
+import { swagger } from "./swagger.js";
+import { toYaml } from "./yaml.js";
+const JSON_TYPE = "application/json; charset=utf-8";
+const YAML_TYPE = "application/yaml; charset=utf-8";
+/** What `build` gives for the graph's routes as they are, built again only once they change; a throw is kept too. */
+function perEpoch(g, build) {
+    let cached = null;
+    return () => {
+        if (cached === null || cached.epoch !== g.epoch) {
+            try {
+                cached = { epoch: g.epoch, failed: false, value: build() };
+            }
+            catch (error) {
+                /* kept for these routes and thrown on every read below: the boundary answers it */
+                cached = { epoch: g.epoch, failed: true, value: error };
+            }
+        }
+        if (cached.failed)
+            throw cached.value;
+        return cached.value;
+    };
 }
-/** Serialize `value` once; the result is cached per route epoch by the caller. */
-export async function toServedArtifact(body, contentType) {
-    return { body, contentType, etag: await entityTag(body) };
+/** `body` with its strong validator: base64url of the first 16 bytes of its SHA-256, quoted. */
+async function artifact(body, contentType) {
+    const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(body)), 0, 16);
+    let binary = "";
+    for (const byte of hash)
+        binary += String.fromCharCode(byte);
+    const tag = btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+    return { body, contentType, etag: `"${tag}"` };
 }
-/**
- * The response for a served artifact. Clients revalidate (`no-cache`) rather than reuse a stale
- * document after a deploy; an unchanged document costs a 304.
- */
-export function artifactResponse(request, artifact) {
-    const headers = {
-        "cache-control": "no-cache",
-        "content-type": artifact.contentType,
-        etag: artifact.etag,
-        "x-content-type-options": "nosniff",
+/** The answer for `served`: revalidated on every use (`no-cache`), an unchanged one a 304. */
+function answering(served) {
+    return async (ctx) => {
+        const { body, contentType, etag } = await served();
+        const headers = {
+            "cache-control": "no-cache",
+            "content-type": contentType,
+            etag,
+            "x-content-type-options": "nosniff",
+        };
+        const hit = ifNoneMatchHits(ctx.req.headers.get("if-none-match"), etag);
+        return ctx.res.raw(hit ? new Response(null, { headers, status: 304 }) : new Response(body, { headers }));
     };
-    if (ifNoneMatchHits(request.headers.get("if-none-match"), artifact.etag)) {
-        return new Response(null, { headers, status: 304 });
+}
+/** `path` under the handle's basePath. */
+const under = (app, path) => joinPatterns(app[VIEW].basePath, path);
+/** Mount every route, or none: each path is checked fixed and free before any is registered. */
+function mountAll(app, routes) {
+    const ids = new Set();
+    for (const [path] of routes) {
+        const segments = parsePattern(under(app, path));
+        if (!isStaticPattern(segments))
+            throw new Error(`cannot serve at ${path}: a served path is fixed, with no parameter`);
+        const id = assertRouteFree(app[GRAPH], "GET", segments);
+        if (ids.has(id))
+            throw new Error(`Duplicate route: ${id}`);
+        ids.add(id);
+    }
+    for (const [path, handler] of routes)
+        app
+            .get(path)
+            .meta({ internal: true, [SERVED]: true })
+            .handler(handler);
+}
+/** Serve the app's OpenAPI document, and a docs page for it when asked, from `app`; returns `app`. */
+export function serveOpenApi(app, options) {
+    const { description, docs, docsPath = "/docs", enabled = true, path = "/openapi", title, version, ...rest } = options;
+    if (!enabled)
+        return app;
+    const handle = app;
+    const g = handle[GRAPH];
+    const info = description === undefined ? { title, version } : { description, title, version };
+    const document = perEpoch(g, () => generateOpenApi(handle, { ...rest, info, invalidate: "off", onSchemaError: "warn" }));
+    const json = perEpoch(g, () => artifact(JSON.stringify(document()), JSON_TYPE));
+    const yaml = perEpoch(g, () => artifact(toYaml(document()), YAML_TYPE));
+    const routes = [
+        [`${path}.json`, answering(json)],
+        [`${path}.yaml`, answering(yaml)],
+        [`${path}.yml`, answering(yaml)],
+    ];
+    if (docs !== undefined) {
+        /* the URL the browser sees: the prefix the app strips, then the path it routes */
+        const url = `${g.settings.stripPrefix ?? ""}${under(handle, `${path}.json`)}`;
+        routes.push([docsPath, (docs === "scalar" ? scalar : swagger)({ url })]);
     }
-    return new Response(artifact.body, { headers });
+    mountAll(handle, routes);
+    return app;
+}
+/** Serve the app's published manifest from `app`; returns `app`. */
+export function serveManifest(app, options = {}) {
+    const { enabled = true, path = "/manifest.json", ...rest } = options;
+    if (!enabled)
+        return app;
+    const handle = app;
+    const manifest = perEpoch(handle[GRAPH], () => artifact(JSON.stringify(generateManifest(handle, { ...rest, visibility: "published" })), JSON_TYPE));
+    mountAll(handle, [[path, answering(manifest)]]);
+    return app;
 }
-//# sourceMappingURL=serve.js.map

package/dist/openapi/servers.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The document's servers. With no list, the stripped prefix is the one server (a client sends it,
+ * the app strips it). A caller's list replaces that default, the prefix appended to each URL;
+ * basePath is in the paths already. A server that cannot be served is refused: each `{var}` is
+ * declared and each declared variable used, a default is in its enum, a name is a plain word, and
+ * no text holds a stray control character (a URL or description lands verbatim in docs pages and SDKs).
+ */
+export type OpenApiServerVariable = {
+    readonly default: string;
+    readonly description?: string;
+    readonly enum?: readonly string[];
+};
+export type OpenApiServer = {
+    readonly description?: string;
+    readonly url: string;
+    readonly variables?: Readonly<Record<string, OpenApiServerVariable>>;
+};
+/** The servers the document lists, each refusal reported through `error`. */
+export declare function serversOf(servers: readonly OpenApiServer[] | undefined, stripPrefix: string | null, error: (message: string) => void): OpenApiServer[];

package/dist/openapi/servers.js

@@ -0,0 +1,72 @@
+/**
+ * The document's servers. With no list, the stripped prefix is the one server (a client sends it,
+ * the app strips it). A caller's list replaces that default, the prefix appended to each URL;
+ * basePath is in the paths already. A server that cannot be served is refused: each `{var}` is
+ * declared and each declared variable used, a default is in its enum, a name is a plain word, and
+ * no text holds a stray control character (a URL or description lands verbatim in docs pages and SDKs).
+ */
+/* C0, DEL and C1 */
+const CONTROL = /\p{Cc}/u;
+/* a description is CommonMark: tabs and line breaks are its own */
+const STRAY = /(?![\t\n\r])\p{Cc}/u;
+const NAME = /^[A-Za-z0-9_]+$/;
+const VARIABLE = /\{([^{}]*)\}/g;
+/** `url` with `prefix` after it, one slash between them. */
+const prefixed = (url, prefix) => (prefix === null ? url : `${url.replace(/\/+$/, "")}${prefix}`);
+/** Each reason `variable` cannot be served. */
+function variableErrors(name, variable) {
+    const errors = [];
+    if (!NAME.test(name))
+        errors.push("a name is letters, digits and _ only");
+    if (CONTROL.test(variable.default))
+        errors.push("its default holds a control character");
+    if (variable.description !== undefined && STRAY.test(variable.description))
+        errors.push("its description holds a control character");
+    const values = variable.enum;
+    if (values?.length === 0)
+        errors.push("an enum must list at least one value");
+    else if (values !== undefined && !values.includes(variable.default))
+        errors.push(`default "${variable.default}" is not in its enum`);
+    if (values?.some((value) => CONTROL.test(value)))
+        errors.push("its enum holds a control character");
+    return errors.map((reason) => `variable "${name}": ${reason}`);
+}
+/** Each reason `server` cannot be served. */
+function serverErrors(server) {
+    const errors = [];
+    if (CONTROL.test(server.url))
+        errors.push("the URL holds a control character");
+    if (server.description !== undefined && STRAY.test(server.description))
+        errors.push("the description holds a control character");
+    if (/[{}]/.test(server.url.replaceAll(VARIABLE, "")))
+        errors.push("the URL has an unmatched brace");
+    const used = new Set([...server.url.matchAll(VARIABLE)].map((match) => match[1]));
+    const variables = server.variables ?? {};
+    for (const name of used) {
+        if (!Object.hasOwn(variables, name))
+            errors.push(`{${name}} is not declared in variables`);
+    }
+    for (const [name, variable] of Object.entries(variables)) {
+        if (!used.has(name))
+            errors.push(`variable "${name}" is declared but not used in the URL`);
+        errors.push(...variableErrors(name, variable));
+    }
+    return errors;
+}
+/** The servers the document lists, each refusal reported through `error`. */
+export function serversOf(servers, stripPrefix, error) {
+    if (servers === undefined)
+        return stripPrefix === null ? [] : [{ url: stripPrefix }];
+    return servers.map((server, i) => {
+        for (const reason of serverErrors(server))
+            error(`server ${i + 1} (${JSON.stringify(server.url)}): ${reason}`);
+        const out = {
+            url: prefixed(server.url, stripPrefix),
+        };
+        if (server.description !== undefined)
+            out.description = server.description;
+        if (server.variables !== undefined)
+            out.variables = structuredClone(server.variables);
+        return out;
+    });
+}

package/dist/openapi/swagger.d.ts

@@ -1,14 +1,4 @@
-import type { TypedResponse } from "../response.ts";
-type SwaggerOptions = {
-    url: string;
-    [key: string]: unknown;
-};
-export declare function swagger(options: SwaggerOptions): (ctx: {
-    res: {
-        html(sk: "ok", body: string, opts?: {
-            headers?: Record<string, string>;
-        }): TypedResponse;
-    };
-}) => TypedResponse;
-export {};
-//# sourceMappingURL=swagger.d.ts.map
+/** `swagger(config)`: the Swagger UI page for the document at `config.url`. */
+import type { TypedResponse } from "../response/response.ts";
+import { type DocsConfig, type DocsContext } from "./docs-page.ts";
+export declare function swagger(config: DocsConfig): (ctx: DocsContext) => TypedResponse;

package/dist/openapi/swagger.js

@@ -1,7 +1,6 @@
-import { docsPage, escapeAttribute, inlineJson, SWAGGER_UI } from "./docs-page.js";
-export function swagger(options) {
-    const { url, ...rest } = options;
-    const config = inlineJson({ dom_id: "#swagger-ui", url, ...rest });
+import { docsPage, inlineJson, SWAGGER_UI } from "./docs-page.js";
+export function swagger(config) {
+    const inline = inlineJson({ dom_id: "#swagger-ui", ...config });
     return docsPage((nonce) => `<!DOCTYPE html>
 <html>
 <head>
@@ -13,10 +12,9 @@ export function swagger(options) {
 <body>
   <div id="swagger-ui"></div>
   <script src="${SWAGGER_UI.js.url}" integrity="${SWAGGER_UI.js.integrity}" crossorigin="anonymous"></script>
-  <script nonce="${escapeAttribute(nonce)}">
-    SwaggerUIBundle(${config})
+  <script nonce="${nonce}">
+    SwaggerUIBundle(${inline})
   </script>
 </body>
 </html>`);
 }
-//# sourceMappingURL=swagger.js.map