@tetsujs/openapi 0.6.1 → 0.6.3

package/README.md

@@ -17,7 +17,14 @@ createApp({
 });
 ```
 
-Options, details and recipes: **[tetsujs.com/docs/packages/openapi](https://tetsujs.com/docs/packages/openapi/)**
+## Documentation
+
+- [tetsujs.com/docs/packages/openapi](https://tetsujs.com/docs/packages/openapi/): options, details
+  and recipes, also [as Markdown](https://tetsujs.com/docs/packages/openapi.md)
+- [llms-full.txt](https://tetsujs.com/llms-full.txt): the whole documentation in one
+  file, for tools and AI assistants
+- every export and option is also documented in the package's type
+  definitions, which editors and tools read from `node_modules`
 
 ## License
 

package/dist/index-f49v8ege.js

@@ -0,0 +1,28 @@
+// @bun
+// packages/openapi/src/media.ts
+var part = /^[!#$%&'+.^_`|~0-9a-z-]+$/i;
+function isMediaType(value) {
+  if (typeof value !== "string") {
+    return false;
+  }
+  const [type, subtype, ...rest] = value.split("/");
+  if (type === undefined || subtype === undefined || rest.length > 0) {
+    return false;
+  }
+  if (type === "*") {
+    return subtype === "*";
+  }
+  return part.test(type) && (subtype === "*" || part.test(subtype));
+}
+function isJson(type) {
+  return type.toLowerCase() === "application/json";
+}
+function parsesAsJson(type) {
+  const lower = type.toLowerCase();
+  return lower === "application/json" || lower.endsWith("+json");
+}
+
+export { isMediaType, isJson, parsesAsJson };
+
+//# debugId=E3642FF098E4375B64756E2164756E21
+//# sourceMappingURL=index-f49v8ege.js.map

package/dist/index-f49v8ege.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/media.ts"],
+  "sourcesContent": [
+    "/**\n * Media types, as the document's `content` keys them.\n *\n * The core checks a route's `contentType` when the route is declared; a\n * response annotated with `documented()` reaches the document without the\n * core seeing it, so the same rule is applied here, when it is annotated.\n *\n * @module\n */\n\n/** One part of a media type: HTTP's token characters, a range's star aside. */\nconst part = /^[!#$%&'+.^_`|~0-9a-z-]+$/i;\n\n/**\n * Whether a value is a media type or a range of them, as a document's\n * `content` names it: `text/csv`, `image/*`, the range of every type — and\n * no parameters, which a key would carry into every comparison with what a\n * response says.\n */\nexport function isMediaType(value: unknown): value is string {\n  if (typeof value !== \"string\") {\n    return false;\n  }\n\n  const [type, subtype, ...rest] = value.split(\"/\");\n\n  if (type === undefined || subtype === undefined || rest.length > 0) {\n    return false;\n  }\n\n  if (type === \"*\") {\n    return subtype === \"*\";\n  }\n\n  return part.test(type) && (subtype === \"*\" || part.test(subtype));\n}\n\n/**\n * Whether a media type is the one a body is described as by default, and\n * the framework sends a returned value with. Compared without regard to\n * case, as media types are.\n */\nexport function isJson(type: string): boolean {\n  return type.toLowerCase() === \"application/json\";\n}\n\n/**\n * Whether a body under this key is JSON to parse: `application/json`, or\n * a type with the `+json` suffix. A range is not — its schema describes\n * the bytes of whatever type answers — and neither is `x-ndjson`, which\n * is lines of JSON, not one value.\n */\nexport function parsesAsJson(type: string): boolean {\n  const lower = type.toLowerCase();\n\n  return lower === \"application/json\" || lower.endsWith(\"+json\");\n}\n"
+  ],
+  "mappings": ";;AAWA,IAAM,OAAO;AAQN,SAAS,WAAW,CAAC,OAAiC;AAAA,EAC3D,IAAI,OAAO,UAAU,UAAU;AAAA,IAC7B,OAAO;AAAA,EACT;AAAA,EAEA,OAAO,MAAM,YAAY,QAAQ,MAAM,MAAM,GAAG;AAAA,EAEhD,IAAI,SAAS,aAAa,YAAY,aAAa,KAAK,SAAS,GAAG;AAAA,IAClE,OAAO;AAAA,EACT;AAAA,EAEA,IAAI,SAAS,KAAK;AAAA,IAChB,OAAO,YAAY;AAAA,EACrB;AAAA,EAEA,OAAO,KAAK,KAAK,IAAI,MAAM,YAAY,OAAO,KAAK,KAAK,OAAO;AAAA;AAQ1D,SAAS,MAAM,CAAC,MAAuB;AAAA,EAC5C,OAAO,KAAK,YAAY,MAAM;AAAA;AASzB,SAAS,YAAY,CAAC,MAAuB;AAAA,EAClD,MAAM,QAAQ,KAAK,YAAY;AAAA,EAE/B,OAAO,UAAU,sBAAsB,MAAM,SAAS,OAAO;AAAA;",
+  "debugId": "E3642FF098E4375B64756E2164756E21",
+  "names": []
+}

package/dist/src/annotations.d.ts

@@ -1,12 +1,14 @@
 /**
- * What hooks contribute to the documentation.
+ * What hooks, and the handlers packages hand out, 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.
+ * factories stay free of documentation options. A package's handler is
+ * annotated the same way, for the routes that mount it.
  *
  * 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
@@ -53,13 +55,34 @@ export interface SecurityRequirement {
 }
 /**
  * One response a hook can produce, which the route's own schema knows
- * nothing about — a rate limiter's `429`, a guard's `401`.
+ * nothing about — a rate limiter's `429`, a guard's `401` — or one a
+ * package's handler answers with, for the routes that mount it: a file,
+ * a `304`.
  */
 export interface DocumentedResponse {
     readonly status: number;
     readonly description: string;
-    /** The body, when the hook answers with one. */
+    /**
+     * The body, when it is described: JSON, or the content under
+     * `contentType` when there is one.
+     *
+     * Without `schema` or `contentType`, an error status — `400` and above —
+     * answers with the framework's envelope, which `error`, `message` and
+     * `fields` describe, and any other status carries no body: a `304`, a
+     * redirect.
+     */
     readonly schema?: AnySchema;
+    /**
+     * The media type of the body when it is not JSON — `"text/html"`, or a
+     * range such as `"image/*"` or the range of every type for a file whose
+     * type is not known in advance. Without a `schema`, the body is
+     * described by its type alone.
+     *
+     * Two responses of one status with different types are both in the
+     * document, each under its own: the site's `404.html` next to the
+     * envelope an API client gets.
+     */
+    readonly contentType?: string;
     /**
      * The `error` code of the failure envelope, when the hook answers with
      * the framework's shape — `"RATE_LIMITED"`, `"SESSION_EXPIRED"`.
@@ -134,14 +157,58 @@ export interface HookDocs {
     readonly responses?: readonly DocumentedResponse[];
 }
 /**
- * Annotates a hook with what it contributes to the documentation.
+ * Everything a handler tells the generator about the route it answers
+ * for.
+ *
+ * A handler a package hands out — a directory of files, say — knows what
+ * it answers with better than the route it is mounted on, whose author
+ * wrote one line: annotated once, it describes every route that mounts it.
+ */
+export interface HandlerDocs {
+    /**
+     * Keeps the route out of the document unless the route says
+     * `docs: { hidden: false }`.
+     *
+     * For a handler whose routes are rarely anyone's API — the files of a
+     * site — and which a generated client could not call anyway. The route's
+     * own word wins either way: `docs: { hidden: true }` hides it whatever
+     * the handler says.
+     */
+    readonly hidden?: boolean;
+    /**
+     * What the handler answers with, as the route's own responses: a status
+     * the route's response map declares too is described by both, and a
+     * route that says nothing gets no placeholder `200` in their place.
+     */
+    readonly responses?: readonly DocumentedResponse[];
+}
+/** Any handler a route can take; the context is the route's to type. */
+type AnyHandler = (ctx: never) => unknown;
+/**
+ * Annotates a hook, or a handler, 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.
+ * and a hook or a handler used elsewhere is not changed behind its
+ * author's back. A handler's copy calls the handler it was made from. The
+ * type is preserved exactly, so an annotated hook goes into a stack, and an
+ * annotated handler onto a route, like any other.
  *
- * @example
+ * Annotating a handler is for one whose type is already settled — a
+ * package's, typed by its own context. An arrow written inside
+ * `documented()` on a route does not get the route's context, which
+ * `route()` would have given it, and does not compile; its statuses belong
+ * in the route's response map.
+ *
+ * One signature, for a hook and a handler alike, and one shape of what is
+ * said about either. An overload for each would keep `hidden` off a hook
+ * and `security` off a handler in the types, but TypeScript before 7
+ * reports a call no overload matches on the whole call, and a misspelled
+ * keyword deep in a response would no longer be pointed at. Those two are
+ * refused here instead, when `documented()` is called — as a module loads,
+ * before anything is served.
+ *
+ * @example A hook
  * ```ts
  * export const limiter = documented(hook.beforeParse(check), {
  *   responses: [
@@ -149,8 +216,19 @@ export interface HookDocs {
  *   ],
  * });
  * ```
+ *
+ * @example A package's handler, out of the document until a route asks
+ * ```ts
+ * return documented(serveFile, {
+ *   hidden: true,
+ *   responses: [
+ *     { status: 200, description: "The file", contentType: "image/*" },
+ *     { status: 304, description: "Not modified" },
+ *   ],
+ * });
+ * ```
  */
-export declare function documented<H extends AnyHook>(hook: H, docs: HookDocs): H;
+export declare function documented<T extends AnyHook | AnyHandler>(target: T, docs: HookDocs & HandlerDocs): T;
 /**
  * Annotates a hook with the security it enforces — {@link documented} for
  * the case that comes up most.
@@ -189,6 +267,8 @@ export declare function documented<H extends AnyHook>(hook: H, docs: HookDocs):
 export declare function secured<H extends AnyHook>(hook: H, requirement: SecurityRequirement | SecurityAlternatives): H;
 /** Reads everything a hook was annotated with. */
 export declare function docsOf(hook: AnyHook): HookDocs | undefined;
+/** Reads everything a handler was annotated with. */
+export declare function handlerDocsOf(handler: unknown): HandlerDocs | undefined;
 /** Reads the security a hook was annotated with, if it was. */
 export declare function securityOf(hook: AnyHook): SecurityRequirement | SecurityAlternatives | undefined;
 /** What the hooks of one route contribute, in execution order. */
@@ -209,11 +289,12 @@ export interface HookContributions {
 /**
  * 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. Two hooks of one scheme asking for different
- * scopes both run, so the requirement asks for the scopes of both — each
- * once, in the order they were first asked for.
+ * A scheme is registered once per name: two hooks of one scheme asking for
+ * different scopes both run, so the requirement asks for the scopes of
+ * both — each once, in the order they were first asked for. Responses are
+ * kept as the hooks give them. Two guards may answer one status with one
+ * description and different codes, and both are what the route sends;
+ * answers that say the same are folded when the document is written.
  *
  * Deduplicating by name means two hooks claiming one name with different
  * schemes lose one of them, and that is not a duplicate being collapsed —
@@ -221,4 +302,5 @@ export interface HookContributions {
  * `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;
+export {};
 //# sourceMappingURL=annotations.d.ts.map

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

@@ -1 +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;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,eAAe,GAAG,WAAW,CAAC;IAC5E,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;IAE1B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC;IAEvD;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;CAC/D;AAED,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAChD;AAED,0DAA0D;AAC1D,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,oBAAoB,CAAC;IAE/D,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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,OAAO,EACvC,IAAI,EAAE,CAAC,EACP,WAAW,EAAE,mBAAmB,GAAG,oBAAoB,GACtD,CAAC,CAEH;AAED,kDAAkD;AAClD,wBAAgB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAE1D;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,GACZ,mBAAmB,GAAG,oBAAoB,GAAG,SAAS,CAExD;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC,SAAS,mBAAmB,EAAE,CAAC,EAAE,CAAC;IAEjE,QAAQ,CAAC,SAAS,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACnD;AAED;;;;;;;;;;;;;GAaG;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,CAsDnB"}
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/annotations.ts"],"names":[],"mappings":"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"}

package/dist/src/envelopes.d.ts

@@ -1,9 +1,10 @@
 /**
  * Error envelopes, one definition per status and code.
  *
- * An envelope reaches a document from four directions: a route's response
- * map, a hook's annotation, a guard's security requirement, and the
- * framework's own failures. Each used to be described where it arrived —
+ * An envelope reaches a document from five directions: a route's response
+ * map, its handler's annotation, a hook's annotation, a guard's security
+ * requirement, and the framework's own failures. Each used to be described
+ * where it arrived —
  * a route's inline, the rest by reference — so one `UNAUTHORIZED` could be
  * listed twice under one status, once as a `$ref` and once as the same
  * shape without a name, and a generated client got a named type next to an
@@ -14,11 +15,12 @@
  * discriminable: a client can branch on `error` only if every code under
  * the status has exactly one shape.
  *
- * The route's definition wins. It is the author's own contract — usually
- * the stricter one, a validator's `additionalProperties: false` — where a
- * hook's is the framework's generic envelope. The routes are therefore
- * read first, before any operation is built, so the winner does not depend
- * on which route happens to come first in the table.
+ * The route's definition wins, its handler's annotation counting as the
+ * route's own. It is the author's own contract — usually the stricter one,
+ * a validator's `additionalProperties: false` — where a hook's is the
+ * framework's generic envelope. The routes are therefore read first,
+ * before any operation is built, so the winner does not depend on which
+ * route happens to come first in the table.
  *
  * What an envelope looks like — how one is described, where its code is,
  * what a client discriminates on — is the document's error format, which

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

@@ -1 +1 @@
-{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CACvB,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,cAAc,GACrB,SAAS,CAsEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GACrD,gBAAgB,EAAE,CA0BpB"}
+{"version":3,"file":"envelopes.d.ts","sourceRoot":"","sources":["../../src/envelopes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAEhC;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAEtE;;;;;;;OAOG;IACH,GAAG,CACD,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAC9B,SAAS,CAAC;IAEb;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,SAAS,CACvB,UAAU,EAAE,gBAAgB,EAC5B,MAAM,EAAE,cAAc,GACrB,SAAS,CAsEX;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,GACrD,gBAAgB,EAAE,CA0BpB"}

package/dist/src/index.d.ts

@@ -21,7 +21,7 @@
 import type { App } from "@tetsujs/core";
 import type { OpenApiDocument } from "./document.ts";
 import type { ErrorFormat } from "./errors.ts";
-export type { DocumentedHeader, DocumentedResponse, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
+export type { DocumentedHeader, DocumentedResponse, HandlerDocs, HookContributions, HookDocs, SecurityAlternatives, SecurityRequirement, SecurityScheme, } from "./annotations.ts";
 export { documented, secured } from "./annotations.ts";
 export type { DocsOptions } from "./controller.ts";
 export { DocsController, docs } from "./controller.ts";
@@ -118,7 +118,9 @@ export interface GeneratorResult {
  *
  * 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.
+ * requires has nothing left to describe. A route that says nothing either
+ * way is hidden when its handler was annotated so — see {@link documented}
+ * — and `docs: { hidden: false }` shows it all the same.
  *
  * Every route of the table becomes an operation under its path template,
  * with the parameters, body and responses its schemas describe. What the

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

@@ -1 +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,EAA6B,MAAM,eAAe,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,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,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,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;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,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,CA2G1E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAmB,MAAM,eAAe,CAAC;AAG1D,OAAO,KAAK,EAAE,eAAe,EAA6B,MAAM,eAAe,CAAC;AAEhF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAM/C,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,QAAQ,EACR,oBAAoB,EACpB,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,YAAY,EACZ,eAAe,EACf,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAClE,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,cAAc,GACf,MAAM,kBAAkB,CAAC;AAC1B,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;IAE9C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAE9B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAClD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,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;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,cAAc,GAAG,eAAe,CAyG1E"}

package/dist/src/index.js

@@ -1,7 +1,35 @@
 // @bun
+import {
+  isMediaType,
+  isJson
+} from "../index-f49v8ege.js";
+
 // packages/openapi/src/annotations.ts
 var docsKey = "~tetsu/hook-docs";
-function documented(hook, docs) {
+var handlerDocsKey = "~tetsu/handler-docs";
+function documented(target, docs) {
+  const handled = typeof target === "function";
+  if (handled && docs.security !== undefined) {
+    throw new Error("documented() was given security for a handler \u2014 security is stated on the hook that enforces it, with secured()");
+  }
+  if (!handled && docs.hidden !== undefined) {
+    throw new Error("documented() was given hidden for a hook \u2014 a route is hidden by its own docs, or by its handler's annotation, not by a hook it mounts");
+  }
+  for (const response of docs.responses ?? []) {
+    if (response.contentType !== undefined && !isMediaType(response.contentType)) {
+      throw new Error(`The ${response.status} response given to documented() has the content type ${JSON.stringify(response.contentType)}, which is not a type such as text/html or a range such as image/* \u2014 the type alone, without parameters: the charset belongs on the response`);
+    }
+  }
+  if (handled) {
+    const handler = target;
+    const copy = (ctx) => handler(ctx);
+    Object.defineProperty(copy, handlerDocsKey, {
+      enumerable: false,
+      value: { ...handlerDocsOf(handler), ...docs }
+    });
+    return copy;
+  }
+  const hook = target;
   const annotated = { ...hook };
   Object.defineProperty(annotated, docsKey, {
     enumerable: false,
@@ -15,10 +43,13 @@ function secured(hook, requirement) {
 function docsOf(hook) {
   return hook[docsKey];
 }
+function handlerDocsOf(handler) {
+  return typeof handler === "function" ? handler[handlerDocsKey] : undefined;
+}
 function contributionsOf(chains, warn) {
   const security = new Map;
   const conditions = new Map;
-  const responses = new Map;
+  const responses = [];
   for (const slot of Object.values(chains)) {
     for (const hook of slot) {
       const docs = docsOf(hook);
@@ -42,18 +73,13 @@ function contributionsOf(chains, warn) {
           }
         }
       }
-      for (const response of docs.responses ?? []) {
-        const key = `${response.status} ${response.description}`;
-        if (!responses.has(key)) {
-          responses.set(key, response);
-        }
-      }
+      responses.push(...docs.responses ?? []);
     }
   }
   return {
     security: [...security.values()],
     conditions: [...conditions.values()],
-    responses: [...responses.values()]
+    responses
   };
 }
 function alternativesOf(security) {
@@ -373,13 +399,25 @@ function operationOf(entry, options, components, envelopes, ids, warn) {
   };
 }
 function declareEnvelopes(entry, envelopes) {
-  for (const [status, { body }] of declaredResponses(entry)) {
-    const described = body === null ? undefined : emitted(body, "", () => {});
-    const code = envelopes.format.code;
+  const own = [];
+  for (const [status, { body, contentType }] of declaredResponses(entry)) {
+    if (body !== null && (contentType === undefined || isJson(contentType))) {
+      own.push([Number(status), body]);
+    }
+  }
+  for (const response of handlerDocsOf(entry.def.handler)?.responses ?? []) {
+    const { contentType, schema, status } = response;
+    if (schema && (contentType === undefined || isJson(contentType))) {
+      own.push([status, schema]);
+    }
+  }
+  const code = envelopes.format.code;
+  for (const [status, body] of own) {
+    const described = emitted(body, "", () => {});
     for (const branch of described ? branchesOf(described, code) : []) {
       const found = code(branch);
       if (found !== undefined) {
-        envelopes.declare(Number(status), found, branch);
+        envelopes.declare(status, found, branch);
       }
     }
   }
@@ -404,7 +442,8 @@ function asDeclared(value) {
   return {
     body: value.body ?? null,
     ...value.headers === undefined ? {} : { headers: value.headers },
-    ...value.cookies === undefined ? {} : { cookies: value.cookies }
+    ...value.cookies === undefined ? {} : { cookies: value.cookies },
+    ...value.contentType === undefined ? {} : { contentType: value.contentType }
   };
 }
 function declaredHeaders(declared, warn) {
@@ -562,17 +601,24 @@ function responses(entry, options, contributed, components, envelopes, warn) {
     answers.set(status, [...answers.get(status) ?? [], answer]);
   };
   const declared = declaredResponses(entry);
-  for (const [status, { body, ...rest }] of declared) {
+  for (const [status, { body, contentType, ...rest }] of declared) {
     const described = body === null ? undefined : emitted(body, "a response", warn);
     const headers = declaredHeaders({ body, ...rest }, warn);
+    const own = contentType !== undefined && !isJson(contentType);
     add(status, {
       placeholder: describeStatus(status),
       said: described ? wordsOf(described, envelopes) : [],
-      schemas: described ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : [],
+      schemas: described && !own ? branchesFor(unionOnly(described), Number(status), envelopes, warn) : [],
+      ...own ? { media: [mediaOf(contentType, described)] } : {},
       ...headers === undefined ? {} : { headers }
     });
   }
-  if (declared.length === 0) {
+  const handled = handlerDocsOf(entry.def.handler)?.responses ?? [];
+  const envelopeRef = envelopeRefs(components, envelopes, warn);
+  for (const response of handled) {
+    add(String(response.status), documentedAnswer(response, "a handler's response", envelopeRef, envelopes, warn));
+  }
+  if (declared.length === 0 && handled.length === 0) {
     add("200", { placeholder: "Successful response", said: [], schemas: [] });
   }
   for (const [status, answer] of failures(entry, options, contributed, components, envelopes, warn)) {
@@ -587,16 +633,7 @@ function responses(entry, options, contributed, components, envelopes, warn) {
 function failures(entry, options, contributed, components, envelopes, warn) {
   const schema = entry.def.schema;
   const found = [];
-  const envelopeRef = (status, error, message, fields) => {
-    const described = envelopes.format.describe({
-      status,
-      ...error === undefined ? {} : { error },
-      ...message === undefined ? {} : { message },
-      fields: fields ?? {}
-    });
-    const ref = error === undefined ? components.ref(failureName(status), described) : envelopes.ref(status, error, described, warn);
-    return ref;
-  };
+  const envelopeRef = envelopeRefs(components, envelopes, warn);
   if (schema?.params || schema?.query || schema?.headers || schema?.cookies || schema?.body) {
     found.push([
       options.validationStatus,
@@ -626,21 +663,14 @@ function failures(entry, options, contributed, components, envelopes, warn) {
         said: [
           said(requirement.error, requirement.description ?? `Request did not satisfy ${requirement.name}`)
         ],
-        schemas: [envelopeRef(status, requirement.error, requirement.message)]
+        schemas: status >= 400 ? [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;
     found.push([
       response.status,
-      {
-        said: [said(response.error, response.description)],
-        schemas: described ? branchesFor(described, response.status, envelopes, warn) : [
-          envelopeRef(response.status, response.error, response.message, response.fields)
-        ],
-        ...response.headers ? { headers: response.headers } : {}
-      }
+      documentedAnswer(response, "a hook's response", envelopeRef, envelopes, warn)
     ]);
   }
   if (schema?.body || entry.def.bodyType || entry.def.rawBody) {
@@ -681,6 +711,47 @@ function failures(entry, options, contributed, components, envelopes, warn) {
   ]);
   return found;
 }
+function envelopeRefs(components, envelopes, warn) {
+  return (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;
+  };
+}
+function documentedAnswer(response, subject, envelopeRef, envelopes, warn) {
+  const described = response.schema ? emitted(response.schema, subject, warn) : undefined;
+  const answer = {
+    said: [said(response.error, response.description)],
+    ...response.headers ? { headers: response.headers } : {}
+  };
+  if (response.contentType !== undefined && !isJson(response.contentType)) {
+    return {
+      ...answer,
+      schemas: [],
+      media: [mediaOf(response.contentType, described)]
+    };
+  }
+  if (described) {
+    return {
+      ...answer,
+      schemas: branchesFor(described, response.status, envelopes, warn)
+    };
+  }
+  return {
+    ...answer,
+    schemas: response.status >= 400 ? [
+      envelopeRef(response.status, response.error, response.message, response.fields)
+    ] : []
+  };
+}
+function mediaOf(type, schema) {
+  return schema === undefined ? { type } : { type, schema };
+}
 function said(code, text) {
   return code === undefined ? { text } : { code, text };
 }
@@ -700,19 +771,33 @@ function unionOnly(schema) {
 function merge(list, envelopes) {
   const schemas = distinct(list.flatMap((answer) => answer.schemas));
   const headers = {};
+  const media = new Map;
+  const unconstrained = new Set;
   for (const answer of list) {
     for (const [name, header] of Object.entries(answer.headers ?? {})) {
       headers[name] ??= header;
     }
+    for (const { type, schema } of answer.media ?? []) {
+      const key = type.toLowerCase();
+      const alternatives = media.get(key) ?? [];
+      media.set(key, schema ? [...alternatives, schema] : alternatives);
+      if (!schema) {
+        unconstrained.add(key);
+      }
+    }
+  }
+  const content = {};
+  if (schemas.length > 0) {
+    content["application/json"] = { schema: unionOf(schemas, envelopes) };
+  }
+  for (const [type, alternatives] of media) {
+    const [only, ...others] = distinct(alternatives);
+    content[type] = only === undefined || unconstrained.has(type) ? {} : { schema: others.length === 0 ? only : { anyOf: [only, ...others] } };
   }
   return {
     description: wording(list),
     ...Object.keys(headers).length > 0 ? { headers } : {},
-    ...schemas.length > 0 ? {
-      content: {
-        "application/json": { schema: unionOf(schemas, envelopes) }
-      }
-    } : {}
+    ...Object.keys(content).length > 0 ? { content } : {}
   };
 }
 function wording(list) {
@@ -728,12 +813,14 @@ ${item.text}`;
       }
     }
   }
-  const [only] = items;
-  if (items.length === 1 && only) {
+  const coded = new Set(items.flatMap((item) => item.code === undefined ? [] : [item.text]));
+  const said = items.filter((item) => item.code !== undefined || !coded.has(item.text));
+  const [only] = said;
+  if (said.length === 1 && only) {
     return only.text;
   }
-  if (items.length > 1) {
-    return items.map((item) => item.code === undefined ? `- ${item.text}` : `- \`${item.code}\`: ${item.text}`).join(`
+  if (said.length > 1) {
+    return said.map((item) => item.code === undefined ? `- ${item.text}` : `- \`${item.code}\`: ${item.text}`).join(`
 `);
   }
   return list.find((answer) => answer.placeholder)?.placeholder ?? "";
@@ -776,8 +863,22 @@ function describeStatus(status) {
   if (status === "204") {
     return "No content";
   }
+  if (status === "default") {
+    return "Any other response";
+  }
+  const range = ranges[status.toUpperCase()];
+  if (range !== undefined) {
+    return range;
+  }
   return status.startsWith("2") ? "Successful response" : errorBody(Number(status)).message;
 }
+var ranges = {
+  "1XX": "Informational response",
+  "2XX": "Successful response",
+  "3XX": "Redirection",
+  "4XX": "Client error",
+  "5XX": "Server error"
+};
 var issues = {
   type: "array",
   items: {
@@ -1007,7 +1108,7 @@ function openapi(app, options) {
   const components = schemaComponents();
   const envelopes2 = envelopes(components, resolveFormat(options.errors));
   const ids = operationIds();
-  const described = app.entries.filter((entry) => !entry.ws && !entry.def.docs?.hidden);
+  const described = app.entries.filter((entry) => !entry.ws && !hidden(entry));
   for (const entry of described) {
     declareEnvelopes(entry, envelopes2);
   }
@@ -1063,6 +1164,9 @@ function openapi(app, options) {
   refsOf(document, occupied, warnings);
   return { document, warnings };
 }
+function hidden(entry) {
+  return entry.def.docs?.hidden ?? handlerDocsOf(entry.def.handler)?.hidden ?? false;
+}
 function refsOf(document, routes, warnings) {
   const unresolved = (ref) => `refers to "${ref}", which is no schema in the document: references are embedded as they are, and resolve against the document's root`;
   for (const [template, item] of Object.entries(document.paths)) {
@@ -1121,5 +1225,5 @@ export {
   secured
 };
 
-//# debugId=A9BC9A29B6C6C1DA64756E2164756E21
+//# debugId=94105F31CF41593E64756E2164756E21
 //# sourceMappingURL=index.js.map