@tetsujs/openapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tetsuodev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,146 @@
+# @tetsujs/openapi
+
+An OpenAPI 3.1 document and a docs page, generated from the routes you
+already declared.
+
+```bash
+bun add @tetsujs/openapi
+```
+
+## Usage
+
+Mount the `docs()` controller next to your own:
+
+```ts
+import { docs } from "@tetsujs/openapi";
+
+createApp({
+  routes: [
+    group("/api", { children: [new UsersController(users)] }),
+    docs({ info: { title: "Users API", version: "1.0.0" } }),
+  ],
+});
+```
+
+`/openapi.json` serves the document and `/docs` renders it. The document
+is built once, at startup, so anything that cannot be described is
+reported before the first request.
+
+`docs()` is an ordinary controller: put it in a group to move it under a
+prefix, guard it with hooks, or leave it out in production. Its own two
+routes are left out of the document.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `info` | — | the document's `info`: title, version, description |
+| `servers` | — | where the API is reachable |
+| `path` | `/openapi.json` | where the document is served |
+| `uiPath` | `/docs` | where the page is served |
+| `ui` | `"scalar"` | `"scalar"`, `"swagger-ui"` or `"redoc"` |
+| `title` | the document's title | the page's title |
+| `assets` | the renderer's CDN | pinned or self-hosted renderer URLs |
+| `documentSelf` | `false` | include `/openapi.json` and `/docs` in the document |
+| `onWarning` | `console.warn` | receives what could not be described |
+
+## What goes into the document
+
+| From the route | Becomes |
+| --- | --- |
+| `path` | the path: `/users/:id` → `/users/{id}` |
+| `schema.params`, `query`, `headers`, `cookies` | parameters, required as the schema says |
+| `schema.body` and `bodyType` | the request body and its media types |
+| `schema.response` | responses — one, or one per status of a map; `null` is a status without a body |
+| `docs` | `summary`, `description`, `tags`, `deprecated` |
+| the controller and field | `operationId`: `setAvatar` on `UsersController` → `usersSetAvatar` |
+
+`docs: { hidden: true }` leaves a route out of the document; it is served
+as before.
+
+```ts
+route({
+  method: "POST",
+  path: "/internal/drain",
+  docs: { summary: "Drain the queue", hidden: true },
+  handler: () => queue.drain(),
+});
+```
+
+Schemas are described through Standard Schema's JSON Schema support: Zod,
+Valibot, ArkType and [`@tetsujs/typebox`](../typebox) provide it.
+
+## Responses the framework adds
+
+Failures the framework answers by itself are documented on every route
+where they can happen, in the same error envelope the server sends:
+
+| Status | `error` | When |
+| --- | --- | --- |
+| `422` (or the configured validation status) | `VALIDATION_FAILED` | a request part failed its schema |
+| `400` | `MALFORMED_JSON` / `MALFORMED_FORM` | the body could not be parsed |
+| `413` | `BODY_TOO_LARGE` | the body exceeded `maxBodySize` |
+| `500` | `INTERNAL_SERVER_ERROR` | any unhandled failure |
+
+The `error` code is a constant in each schema, so a generated client can
+tell failures apart by it. A status the route declares itself is kept, and
+the framework's failures for the same status are listed next to it.
+
+## Documenting hooks
+
+A hook that answers by itself — an auth check, a limiter — can say so, and
+every route it guards is documented accordingly. `secured()` adds a
+security scheme, `documented()` adds responses:
+
+```ts
+import { documented, secured } from "@tetsujs/openapi";
+
+export const auth = secured(
+  hook.beforeParse((ctx) => {
+    const user = verify(ctx.req.headers.get("authorization"));
+
+    if (!user) throw new HttpError(401);
+
+    return { user };
+  }),
+  { name: "bearerAuth", scheme: { type: "http", scheme: "bearer", bearerFormat: "JWT" } },
+);
+
+export const guard = documented(hook.beforeParse(check), {
+  responses: [{ status: 429, description: "Rate limit exceeded", error: "RATE_LIMITED" }],
+});
+```
+
+Hooks from `@tetsujs/rate-limit` are already documented this way. A scheme
+is identified by its `name`: the same one mounted twice is one
+requirement, and two different schemes under one name are reported.
+
+## Using the document directly
+
+When the document itself is the output — written to a file in CI, fed to a
+client generator — call the generator:
+
+```ts
+import { openapi } from "@tetsujs/openapi";
+
+const { document, warnings } = openapi(app, {
+  info: { title: "Users API", version: "1.0.0" },
+});
+
+await Bun.write("openapi.json", JSON.stringify(document, null, 2));
+```
+
+`docsPage()` renders the page on its own, for serving it elsewhere.
+
+## Warnings
+
+A route is still documented when part of it cannot be described, and the
+gap is reported instead of failing the startup:
+
+```
+[openapi] POST /api/users: the body schema does not emit JSON Schema
+```
+
+This happens with a validator that does not emit JSON Schema, a schema
+whose conversion throws, and two routes that map to the same OpenAPI path
+(`/files/*` and `/files/:wildcard` are both `/files/{wildcard}`).

package/dist/src/annotations.d.ts

@@ -0,0 +1,141 @@
+/**
+ * What hooks contribute to the documentation.
+ *
+ * What a route is protected by, or answers with when a guard refuses, is
+ * not in its config: a hook is a function in a slot, and the route that
+ * mounts it says nothing about tokens or rate limits. The contribution is
+ * therefore annotated onto the hook — from this package, not from
+ * `hook.*` — so the core keeps knowing nothing about OpenAPI and the
+ * factories stay free of documentation options.
+ *
+ * A hook annotated once is documented everywhere it runs: application and
+ * group chains are merged into every route's chains at startup, so a guard
+ * mounted on a zone documents the zone's operations without repeating
+ * itself.
+ *
+ * @module
+ */
+import type { AnyHook, AnySchema } from "@tetsujs/core";
+/**
+ * The definition of a scheme, as OpenAPI spells it.
+ *
+ * Typed as loosely as the spec is wide — `http`, `apiKey`, `oauth2` and
+ * `openIdConnect` carry different fields, and narrowing them here would
+ * be a second, poorer copy of the specification.
+ */
+export interface SecurityScheme {
+    readonly type: "http" | "apiKey" | "oauth2" | "openIdConnect";
+    readonly [key: string]: unknown;
+}
+/** What a hook demands of a request, and what it answers when refused. */
+export interface SecurityRequirement {
+    /** The name the scheme is registered under in `components`. */
+    readonly name: string;
+    /** The scheme itself, registered once per name. */
+    readonly scheme: SecurityScheme;
+    /** OAuth2 scopes; empty for every other type. */
+    readonly scopes?: readonly string[];
+    /** The status an unauthenticated request gets. Defaults to `401`. */
+    readonly status?: number;
+    /** How the refusal is described in the document. */
+    readonly description?: string;
+    /**
+     * The `error` code the refusal carries, when the guard answers with the
+     * framework's envelope — `"UNAUTHORIZED"`, `"SESSION_EXPIRED"`.
+     *
+     * Documented as a `const` for the same reason as on a
+     * {@link DocumentedResponse}: only the guard knows its own code.
+     */
+    readonly error?: string;
+    /** An example of the refusal's `message`, for the same reason. */
+    readonly message?: string;
+}
+/**
+ * One response a hook can produce, which the route's own schema knows
+ * nothing about — a rate limiter's `429`, a guard's `401`.
+ */
+export interface DocumentedResponse {
+    readonly status: number;
+    readonly description: string;
+    /** The body, when the hook answers with one. */
+    readonly schema?: AnySchema;
+    /**
+     * The `error` code of the failure envelope, when the hook answers with
+     * the framework's shape — `"RATE_LIMITED"`, `"SESSION_EXPIRED"`.
+     *
+     * Documented as a `const`, so a client can discriminate on it. Only the
+     * hook knows its own code; without one the document says the field is a
+     * string and no more.
+     */
+    readonly error?: string;
+    /** An example of the envelope's `message`, for the same reason. */
+    readonly message?: string;
+}
+/** Everything a hook tells the generator about itself. */
+export interface HookDocs {
+    /** What the hook demands of a request. */
+    readonly security?: SecurityRequirement;
+    /** What the hook can answer with. */
+    readonly responses?: readonly DocumentedResponse[];
+}
+/**
+ * Annotates a hook with what it contributes to the documentation.
+ *
+ * Returns a copy: what the caller exports is what carries the annotation,
+ * and a hook used elsewhere is not changed behind its author's back. The
+ * type is preserved exactly, so an annotated hook goes into a stack like
+ * any other.
+ *
+ * @example
+ * ```ts
+ * export const limiter = documented(hook.beforeParse(check), {
+ *   responses: [
+ *     { status: 429, description: "Rate limit exceeded", schema: TooMany },
+ *   ],
+ * });
+ * ```
+ */
+export declare function documented<H extends AnyHook>(hook: H, docs: HookDocs): H;
+/**
+ * Annotates a hook with the security it enforces — {@link documented} for
+ * the case that comes up most.
+ *
+ * @example
+ * ```ts
+ * export const auth = secured(
+ *   hook.beforeParse((ctx) => {
+ *     const user = verify(ctx.req.headers.get("authorization"));
+ *     if (!user) throw new HttpError(401);
+ *     return { user };
+ *   }),
+ *   {
+ *     name: "bearerAuth",
+ *     scheme: { type: "http", scheme: "bearer", bearerFormat: "JWT" },
+ *   },
+ * );
+ * ```
+ */
+export declare function secured<H extends AnyHook>(hook: H, requirement: SecurityRequirement): H;
+/** Reads everything a hook was annotated with. */
+export declare function docsOf(hook: AnyHook): HookDocs | undefined;
+/** Reads the security requirement a hook carries, if it carries one. */
+export declare function securityOf(hook: AnyHook): SecurityRequirement | undefined;
+/** What the hooks of one route contribute, in execution order. */
+export interface HookContributions {
+    readonly security: readonly SecurityRequirement[];
+    readonly responses: readonly DocumentedResponse[];
+}
+/**
+ * Collects the contributions of a route's chains.
+ *
+ * A scheme is registered once per name and a response once per status and
+ * description: the same guard on the application and on a group is one
+ * requirement, not two.
+ *
+ * Deduplicating by name means two hooks claiming one name with different
+ * schemes lose one of them, and that is not a duplicate being collapsed —
+ * it is a requirement the route really has going undescribed. Passing
+ * `warn` is how the caller hears about it; the generator does.
+ */
+export declare function contributionsOf(chains: Record<string, readonly AnyHook[]>, warn?: (message: string) => void): HookContributions;
+//# sourceMappingURL=annotations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,CAAC;IAC9D,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,mDAAmD;IACnD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC,iDAAiD;IACjD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEzB,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gDAAgD;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;IAE5B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAExC,qCAAqC;IACrC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,CAAC,CASxE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,IAAI,EAAE,CAAC,EACP,WAAW,EAAE,mBAAmB,GAC/B,CAAC,CAEH;AAED,kDAAkD;AAClD,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAE1D;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAEzE;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC,EAC1C,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC/B,iBAAiB,CAyCnB"}

package/dist/src/components.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The document's `components/schemas` section.
+ *
+ * The failures the framework fills in repeat across every operation — a
+ * `500` on all of them, a `413` on every route with a body — and inlining
+ * the same envelope each time makes a document that is mostly boilerplate.
+ * They are defined once here and referenced with `$ref`, which is also how
+ * a client generator ends up with one `MalformedJson` type instead of one
+ * per endpoint.
+ *
+ * Only the framework's own shapes go here. A schema that came from a
+ * validator is still inlined: it is the author's, it has no name the
+ * generator could give it, and `$ref` would invent one.
+ *
+ * @module
+ */
+/** A reference to a definition in `components/schemas`. */
+export interface SchemaRef {
+    readonly $ref: string;
+}
+/** The definitions collected while generating a document. */
+export interface SchemaComponents {
+    /**
+     * Registers a schema and returns the reference to it.
+     *
+     * Identical schemas share one definition, whatever name each caller
+     * asked for; different schemas that want the same name get a numbered
+     * one, so a document is never silently wrong about what a `$ref` points
+     * at.
+     */
+    ref(preferred: string, schema: Record<string, unknown>): SchemaRef;
+    /** What was registered, in registration order. */
+    readonly schemas: Record<string, unknown>;
+}
+export declare function schemaComponents(): SchemaComponents;
+/**
+ * The name a failure is defined under: its `error` code in PascalCase —
+ * `MALFORMED_JSON` becomes `MalformedJson` — so the definition and the code
+ * a client branches on read as the same thing.
+ *
+ * A failure whose code only the hook knows, and which the hook did not
+ * declare, is named after its status instead.
+ */
+export declare function failureName(status: number, error?: string): string;
+//# sourceMappingURL=components.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../../src/components.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IAEnE,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,wBAAgB,gBAAgB,IAAI,gBAAgB,CA2BnD;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAclE"}

package/dist/src/controller.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The documentation endpoints as a mountable controller.
+ *
+ * `openapi()` returns data and mounts nothing, which is the right default
+ * for a generator but a chore in the ordinary case: every application ends
+ * up writing the same controller, holding the same application, to serve
+ * the same two routes. {@link docs} is that controller, written once.
+ *
+ * It is a controller like any other — mounted in `routes`, groupable,
+ * hookable — that receives the application through `onMount` and generates
+ * the document from it at startup.
+ *
+ * @module
+ */
+import type { App, RouteDef, SchemaConfig, ValidatePath } from "@tetsujs/core";
+import { onMount } from "@tetsujs/core";
+import type { OpenApiDocument } from "./document.ts";
+import type { GeneratorWarning } from "./index.ts";
+import type { DocsAssets, DocsUi } from "./page.ts";
+/** What the documentation controller serves, and from where. */
+export interface DocsOptions<Path extends string, UiPath extends string> {
+    /** Title, version and the rest of the document's `info` block. */
+    readonly info: OpenApiDocument["info"];
+    /** Servers the API is reachable at. */
+    readonly servers?: OpenApiDocument["servers"];
+    /** Where the document is served. Defaults to `/openapi.json`. */
+    readonly path?: Path & ValidatePath<Path>;
+    /** Where the page is served. Defaults to `/docs`. */
+    readonly uiPath?: UiPath & ValidatePath<UiPath>;
+    /** Which renderer the page bootstraps. Defaults to `"scalar"`. */
+    readonly ui?: DocsUi;
+    /** Browser title of the page. Defaults to the document's own title. */
+    readonly title?: string;
+    /** Overrides the renderer's CDN URLs, for a pinned or self-hosted copy. */
+    readonly assets?: DocsAssets;
+    /**
+     * Documents the two endpoints this controller serves.
+     *
+     * Off by default: a reader who is looking at the document has already
+     * found the document, and an operation for "the page you are reading"
+     * is one a generated client would happily produce a method for.
+     */
+    readonly documentSelf?: boolean;
+    /**
+     * What to do with what the generator could not describe.
+     *
+     * Defaults to one `console.warn` per warning, at startup — a document
+     * that silently omits a body is worse than a noisy one.
+     */
+    readonly onWarning?: (warning: GeneratorWarning) => void;
+}
+/**
+ * The controller {@link docs} returns: two routes and the `onMount` that
+ * fills them.
+ *
+ * Instantiated through the factory, never directly — the routes carry the
+ * configured paths in their types, which only the factory can infer.
+ */
+export declare class DocsController<Path extends string, UiPath extends string> {
+    private readonly options;
+    /** The document itself, as `application/json`. */
+    readonly json: RouteDef<Path, SchemaConfig, never, undefined, "GET">;
+    /** The page that renders it. */
+    readonly ui: RouteDef<UiPath, SchemaConfig, never, undefined, "GET">;
+    private document;
+    constructor(options: DocsOptions<Path, UiPath>, documentPath: string, uiPath: string, page: string);
+    /** Generates the document of the application this was mounted in. */
+    [onMount](app: App): void;
+}
+/**
+ * The documentation of an application, as a controller to mount.
+ *
+ * @example
+ * ```ts
+ * createApp({
+ *   routes: [
+ *     group("/api", { children: [new UsersController(users)] }),
+ *     docs({ info: { title: "Users API", version: "1.0.0" } }),
+ *   ],
+ * });
+ * ```
+ *
+ * The document is generated once, at startup, from the application the
+ * controller was mounted in. Its own two routes stay out of it — pass
+ * `documentSelf` to put them in.
+ *
+ * The page loads its renderer from a CDN; see {@link docsPage} for the
+ * trade and for how to point it at a self-hosted copy.
+ */
+export declare function docs<const Path extends string = "/openapi.json", const UiPath extends string = "/docs">(options: DocsOptions<Path, UiPath>): DocsController<Path, UiPath>;
+//# sourceMappingURL=controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/controller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAS,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAGpD,gEAAgE;AAChE,MAAM,WAAW,WAAW,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IACrE,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IAEvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,CAAC,CAAC;IAE9C,iEAAiE;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE1C,qDAAqD;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IAEhD,kEAAkE;IAClE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IAErB,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAEhC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,qBAAa,cAAc,CAAC,IAAI,SAAS,MAAM,EAAE,MAAM,SAAS,MAAM;IAUlE,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,gCAAgC;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;IAErE,OAAO,CAAC,QAAQ,CAA8B;IAE9C,YACmB,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EACnD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAgCb;IAED,qEAAqE;IACrE,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAaxB;CACF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,IAAI,CAClB,KAAK,CAAC,IAAI,SAAS,MAAM,GAAG,eAAe,EAC3C,KAAK,CAAC,MAAM,SAAS,MAAM,GAAG,OAAO,EACrC,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,CAYlE"}

package/dist/src/document.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The shape of the documents this package produces.
+ *
+ * Typed only as far as the generator fills it in: an OpenAPI document is
+ * far larger than what a route table can honestly describe, and declaring
+ * the rest would promise support that does not exist. Everything typed
+ * here is emitted; everything a caller adds by hand passes through the
+ * index signatures.
+ *
+ * OpenAPI 3.1 only. It is JSON Schema 2020-12 verbatim, which is what
+ * validators emit through Standard Schema — 3.0 would mean converting the
+ * dialect and being subtly wrong about `nullable`, `examples` and binary
+ * payloads.
+ *
+ * @module
+ */
+/** Metadata every OpenAPI document must carry. */
+export interface DocumentInfo {
+    readonly title: string;
+    readonly version: string;
+    readonly description?: string;
+    readonly [key: string]: unknown;
+}
+/** A server the API is reachable at. */
+export interface DocumentServer {
+    readonly url: string;
+    readonly description?: string;
+}
+/** One request parameter: a path segment, a query key or a header. */
+export interface ParameterObject {
+    readonly name: string;
+    readonly in: "path" | "query" | "header" | "cookie";
+    readonly required: boolean;
+    readonly description?: string;
+    readonly schema?: Record<string, unknown>;
+}
+/** A body or response payload, keyed by media type. */
+export type ContentMap = Record<string, {
+    readonly schema?: Record<string, unknown>;
+}>;
+/** One response of an operation. */
+export interface ResponseObject {
+    readonly description: string;
+    readonly content?: ContentMap;
+}
+/** One endpoint: a method on a path. */
+export interface OperationObject {
+    readonly operationId: string;
+    readonly summary?: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    readonly parameters?: readonly ParameterObject[];
+    readonly requestBody?: {
+        readonly required: boolean;
+        readonly content: ContentMap;
+    };
+    readonly security?: readonly Record<string, readonly string[]>[];
+    readonly responses: Record<string, ResponseObject>;
+}
+/** Every operation declared on one path template. */
+export type PathItemObject = Record<string, OperationObject>;
+/** The generated document. */
+export interface OpenApiDocument {
+    readonly openapi: "3.1.0";
+    readonly info: DocumentInfo;
+    readonly servers?: readonly DocumentServer[];
+    readonly paths: Record<string, PathItemObject>;
+    /**
+     * What the operations refer to rather than repeat: the security schemes
+     * the guards registered, and the failure envelopes the framework fills
+     * in. Absent when neither has anything to say.
+     */
+    readonly components?: {
+        readonly securitySchemes?: Record<string, unknown>;
+        readonly schemas?: Record<string, unknown>;
+    };
+    readonly [key: string]: unknown;
+}
+//# sourceMappingURL=document.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,MAAM,CAC7B,MAAM,EACN;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAC9C,CAAC;AAEF,oCAAoC;AACpC,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;CAC/B;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;KAC9B,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACpD;AAED,qDAAqD;AACrD,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAE7D,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAE/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE;QACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IAEF,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC"}

package/dist/src/emit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Asking a schema to describe itself, without letting it stop the document.
+ *
+ * Internal to the package.
+ *
+ * @module
+ */
+/**
+ * A JSON Schema as the generator reads it: any keyword, with the two it
+ * looks into named, so reading them does not depend on the reader's
+ * `noPropertyAccessFromIndexSignature`.
+ */
+export interface JsonSchemaObject {
+    properties?: unknown;
+    required?: unknown;
+    [keyword: string]: unknown;
+}
+/** Which shape of a schema to describe: what arrives, or what leaves. */
+type Direction = "input" | "output";
+/**
+ * The JSON Schema of a declaration, or `undefined` and a warning saying why.
+ *
+ * A schema can fail to describe itself in two ways, and the generator owes
+ * the same answer to both: an adapter without JSON Schema support returns
+ * nothing, and an adapter that has it can still throw — a converter meeting
+ * a shape it cannot express, a structure too deep to walk, a `$ref` that
+ * leads back to where it started.
+ *
+ * Only the first was handled, and the difference between them is not the
+ * document: it is whether the application starts at all. `docs()` builds
+ * the document from `onMount`, which `createApp` calls while it is still
+ * assembling itself, so an escaping error is not a gap in a description —
+ * it is a server that never listens, over a route that would have worked.
+ *
+ * `subject` names the declaration for the message, as the reader of a
+ * warning would name it: `"the body"`, `"a response"`.
+ */
+export declare function emitted(schema: unknown, subject: string, warn: (message: string) => void, direction?: Direction): JsonSchemaObject | undefined;
+export {};
+//# sourceMappingURL=emit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAeH;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5B;AAED,yEAAyE;AACzE,KAAK,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,OAAO,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,EAC/B,SAAS,GAAE,SAAoB,GAC9B,gBAAgB,GAAG,SAAS,CAkB9B"}

package/dist/src/index.d.ts

@@ -0,0 +1,75 @@
+/**
+ * OpenAPI generation for the framework.
+ *
+ * Reads a compiled application — `app.entries` and the options it actually
+ * runs with — and returns an OpenAPI 3.1 document. Nothing is registered,
+ * served or mutated: the document is data, and serving it is a route the
+ * application declares like any other.
+ *
+ * Serving it is a route the application declares — or `docs()`, the
+ * controller that declares those routes for you.
+ *
+ * @example
+ * ```ts
+ * const { document, warnings } = openapi(app, {
+ *   info: { title: "Users API", version: "1.0.0" },
+ * });
+ * ```
+ *
+ * @module
+ */
+import type { App } from "@tetsujs/core";
+import type { OpenApiDocument } from "./document.ts";
+export type { DocumentedResponse, HookContributions, HookDocs, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
+export { documented, secured } from "./annotations.ts";
+export type { DocsOptions } from "./controller.ts";
+export { DocsController, docs } from "./controller.ts";
+export type { ContentMap, DocumentInfo, DocumentServer, OpenApiDocument, OperationObject, ParameterObject, PathItemObject, ResponseObject, } from "./document.ts";
+export type { DocsAssets, DocsPageOptions, DocsUi } from "./page.ts";
+export { docsPage } from "./page.ts";
+/**
+ * What the generator cannot read off the application.
+ */
+export interface OpenApiOptions {
+    /** Title, version and the rest of the document's `info` block. */
+    readonly info: OpenApiDocument["info"];
+    /** Servers the API is reachable at. */
+    readonly servers?: OpenApiDocument["servers"];
+}
+/**
+ * What the generator could not describe faithfully.
+ *
+ * Each entry names a route and what was missing — almost always a schema
+ * from a validator that emits no JSON Schema. Documentation that silently
+ * omits a body is worse than documentation that says it does not know, so
+ * these are returned rather than swallowed.
+ */
+export interface GeneratorWarning {
+    readonly route: string;
+    readonly message: string;
+}
+/** A generated document together with what could not be described. */
+export interface GeneratorResult {
+    readonly document: OpenApiDocument;
+    readonly warnings: readonly GeneratorWarning[];
+}
+/**
+ * Generates the OpenAPI document of an application.
+ *
+ * Socket endpoints are skipped: a handshake is a `GET` in the table, but
+ * OpenAPI has no way to describe what happens after it, and documenting
+ * the upgrade as an ordinary operation would describe a request that
+ * clients must not make. AsyncAPI is that format, and a separate document.
+ *
+ * So are routes marked `docs: { hidden: true }`, and everything they would
+ * have contributed with them: a security scheme only a hidden route
+ * requires has nothing left to describe.
+ *
+ * Every route of the table becomes an operation under its path template,
+ * with the parameters, body and responses its schemas describe. What the
+ * framework itself can answer — a validation failure, an unparsable body,
+ * a body over the limit — is filled in from the options the application
+ * runs with, so the document states the status actually configured.
+ */
+export declare function openapi(app: App, options: OpenApiOptions): GeneratorResult;
+//# sourceMappingURL=index.d.ts.map