@zerolith/client 0.0.0-canary.20261102.g8292c77

package/src/generate.ts

@@ -0,0 +1,765 @@
+/**
+ * Generates the contract module from an OpenAPI 3.x document: one type per
+ * component schema, an `Api` interface with one entry per operation, and
+ * the `routes` table the client runs on. Pure string work, so it runs
+ * anywhere; the `zerolith-client` command wraps it for the shell.
+ */
+
+/** A JSON Schema object as OpenAPI 3.1 and later carry it (draft 2020-12 plus the OAS vocabulary). */
+export interface SchemaObject
+{
+    /** A reference to `#/components/schemas/<name>`, rendered as that component's generated type, intersected with the keywords beside it that shape a type, such as `properties`, as OpenAPI 3.1 allows; any other target fails generation. */
+    $ref?: string;
+    /** The JSON type, or since OpenAPI 3.1 an array of types rendered as a union; `integer` renders as `number`, and when it is absent the object or array keywords imply one, else the type is `unknown`. */
+    type?: string | string[];
+    /** The OpenAPI 3.0 flag that also allows `null`; when `true`, `null` joins the type. */
+    nullable?: boolean;
+    /** The allowed values, rendered as a union of their literal types; it takes precedence over `type`, and intersects with a composition keyword or `$ref` beside it. */
+    enum?: unknown[];
+    /** The single allowed value (OpenAPI 3.1 and later), rendered as its literal type; it takes precedence over `enum` and `type`, and intersects with a composition keyword or `$ref` beside it. */
+    const?: unknown;
+    /** The object's properties, each generated as a member that is optional unless `required` lists it, with the property's `description` as its doc comment. */
+    properties?: Record<string, SchemaObject>;
+    /** The names in `properties` that must be present; every other property is generated as optional. */
+    required?: string[];
+    /** The schema of keys beyond `properties`, rendered as a `Record<string, ...>` joined to them with `&`; `true` allows `unknown` values, and `false` makes an object without properties `Record<string, never>`. */
+    additionalProperties?: boolean | SchemaObject;
+    /** The schema of each array element, rendered as `T[]`, or `unknown[]` without it; beside `prefixItems` it types the elements after the tuple. */
+    items?: SchemaObject;
+    /** The schemas of the leading array elements by position (OpenAPI 3.1 and later), rendered as a tuple; without `items` the tuple has no rest element. */
+    prefixItems?: SchemaObject[];
+    /** Alternatives of which exactly one matches, rendered as a union; it takes precedence over `anyOf` and `allOf`, and the keywords beside it that shape a type, such as `properties`, intersect with it. */
+    oneOf?: SchemaObject[];
+    /** Alternatives of which at least one matches, rendered as a union unless `oneOf` is present; the keywords beside it that shape a type, such as `properties`, intersect with it. */
+    anyOf?: SchemaObject[];
+    /** Schemas that all match, rendered as an intersection unless `oneOf` or `anyOf` is present; the keywords beside it that shape a type, such as `properties`, join the intersection. */
+    allOf?: SchemaObject[];
+    /** Becomes the doc comment on a component schema's generated type, ahead of `title`, and on an object property's member. */
+    description?: string;
+    /** The doc comment on a component schema's generated type when `description` is absent; the type's name comes from the component's key, not from `title`. */
+    title?: string;
+}
+
+/** A Parameter Object or a reference to one. */
+export interface ParameterObject
+{
+    /** A reference to `#/components/parameters/<name>`, which replaces this object; any other target, or a missing one, fails generation. */
+    $ref?: string;
+    /** The member's key in the generated `params` or `query`, matching the `{name}` placeholder for a path parameter; a parameter without `name` or `in` fails generation. */
+    name?: string;
+    /** Where the parameter travels: `path` fills `params`, `query` adds a member to `query`, `querystring` (OpenAPI 3.2) lets `query` take any key, and `header` and `cookie` are left out. */
+    in?: "query" | "querystring" | "header" | "path" | "cookie";
+    /** Makes a query parameter's member, and the whole `query` input, required; path parameters are generated as required either way, since OpenAPI demands `true` for them. */
+    required?: boolean;
+    /** The doc comment on the parameter's generated member. */
+    description?: string;
+    /** The schema of the value, rendered as the member's type; without it or `content`, the type is `unknown`. */
+    schema?: SchemaObject;
+    /** The single media type entry OpenAPI allows in place of `schema`; when `schema` is absent, the entry's `schema` gives the member's type. */
+    content?: Record<string, MediaTypeObject>;
+}
+
+/** A Media Type Object. */
+export interface MediaTypeObject
+{
+    /** The content's schema, read for a JSON media type in a body and for any media type in a parameter's `content`; when absent, the type is `unknown`. */
+    schema?: SchemaObject;
+}
+
+/** A Request Body Object or a reference to one. */
+export interface RequestBodyObject
+{
+    /** A reference to `#/components/requestBodies/<name>`, which replaces this object; any other target, or a missing one, fails generation. */
+    $ref?: string;
+    /** A brief description of the body; the generator does not carry it into the output. */
+    description?: string;
+    /** Makes the generated `body` input required; OpenAPI's default is `false`, which generates it as optional. */
+    required?: boolean;
+    /** The body by media type, where a JSON type takes precedence and gives its schema's type; otherwise `multipart/form-data` gives `FormData`, `application/x-www-form-urlencoded` gives `URLSearchParams`, `text/*` gives `string`, and any other type gives `BodyInit`. */
+    content?: Record<string, MediaTypeObject>;
+}
+
+/** A Response Object or a reference to one. */
+export interface ResponseObject
+{
+    /** A reference to `#/components/responses/<name>`, which replaces this object; any other target, or a missing one, fails generation. */
+    $ref?: string;
+    /** A description of the response; the generator does not carry it into the output. */
+    description?: string;
+    /** The response body by media type: a JSON type, when present, gives its schema's type, `text/*` gives `string`, any other type gives `Blob`, as the client reads it, and no content gives `undefined`. */
+    content?: Record<string, MediaTypeObject>;
+}
+
+/** An Operation Object. */
+export interface OperationObject
+{
+    /** Names the operation's entry in `Api` and `routes`, in camelCase; without it the name comes from the method and path, such as `putNotesById` for `PUT /notes/{id}`, and two entries with one name fail generation. */
+    operationId?: string;
+    /** The first paragraph of the doc comment on the operation's entry in `Api`. */
+    summary?: string;
+    /** Follows `summary` in the doc comment on the operation's entry in `Api`. */
+    description?: string;
+    /** When `true`, the doc comment on the operation's entry ends with `@deprecated`. */
+    deprecated?: boolean;
+    /** The operation's parameters, merged with the path item's; one with the same `name` and `in` as a path item parameter replaces it. */
+    parameters?: ParameterObject[];
+    /** The request body, generated as the entry's `body` input; without it the entry has no `body`. */
+    requestBody?: RequestBodyObject;
+    /** The responses by status code; `output` is the union of every 2xx response, including `2XX`, or of `default` when there is none, and `unknown` without either. */
+    responses?: Record<string, ResponseObject>;
+}
+
+/** A Path Item Object. */
+export interface PathItemObject
+{
+    /** A reference to `#/components/pathItems/<name>`, which replaces this item; any other target, or a missing one, fails generation. */
+    $ref?: string;
+    /** A summary meant for every operation on the path; the generator does not carry it into the output. */
+    summary?: string;
+    /** A description meant for every operation on the path; the generator does not carry it into the output. */
+    description?: string;
+    /** Parameters shared by every operation on the path; an operation's own parameter with the same `name` and `in` replaces one. */
+    parameters?: ParameterObject[];
+    /** The `GET` operation on this path. */
+    get?: OperationObject;
+    /** The `PUT` operation on this path. */
+    put?: OperationObject;
+    /** The `POST` operation on this path. */
+    post?: OperationObject;
+    /** The `DELETE` operation on this path. */
+    delete?: OperationObject;
+    /** The `OPTIONS` operation on this path. */
+    options?: OperationObject;
+    /** The `HEAD` operation on this path. */
+    head?: OperationObject;
+    /** The `PATCH` operation on this path. */
+    patch?: OperationObject;
+    /** The `TRACE` operation on this path. */
+    trace?: OperationObject;
+    /** The `QUERY` operation on this path (OpenAPI 3.2): a safe, idempotent request that carries a body. */
+    query?: OperationObject;
+    /** Operations for other HTTP methods (OpenAPI 3.2), keyed by method name such as `COPY`; each key is lowercased, and one that is not a valid method token fails generation. */
+    additionalOperations?: Record<string, OperationObject>;
+}
+
+/** The parts of an OpenAPI document the generator reads. */
+export interface OpenApiDocument
+{
+    /** The OpenAPI version, such as `3.1.0`; a value that does not start with `3.` fails generation. */
+    openapi: string;
+    /** The API's title and version, which the generated file's header comment names as its source. */
+    info?: { title?: string; version?: string };
+    /** Path templates mapped to their items; every operation under them becomes an entry of `Api` and `routes`, sorted by path. */
+    paths?: Record<string, PathItemObject>;
+    /** Reusable objects: each entry of `schemas` becomes an exported type named after its key, and `$ref` values resolve into the other sections. */
+    components?: {
+        schemas?: Record<string, SchemaObject>;
+        parameters?: Record<string, ParameterObject>;
+        requestBodies?: Record<string, RequestBodyObject>;
+        responses?: Record<string, ResponseObject>;
+        pathItems?: Record<string, PathItemObject>;
+    };
+}
+
+/** Options for `generateClient`. */
+export interface GenerateOptions
+{
+    /** The module the generated file imports `RouteTable` from. Defaults to `@zerolith/client`. */
+    clientSpecifier?: string;
+    /** The name of the generated contract interface. Defaults to `Api`. */
+    apiName?: string;
+}
+
+/** The methods a Path Item names that the client can send; `trace` is left out, since `fetch` refuses TRACE. */
+const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "query"] as const;
+
+/** Methods `fetch` refuses to send, left out of `additionalOperations` too. */
+const FORBIDDEN_METHODS: ReadonlySet<string> = new Set(["connect", "trace", "track"]);
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+interface Context
+{
+    document: OpenApiDocument;
+    apiName: string;
+}
+
+function fail(message: string): never
+{
+    throw new Error(`zerolith/client: ${message}`);
+}
+
+function words(text: string): string[]
+{
+    return text.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/[^A-Za-z0-9]+/).filter((word) => word !== "");
+}
+
+function pascal(text: string): string
+{
+    return words(text).map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join("");
+}
+
+function camel(text: string): string
+{
+    const name = pascal(text);
+    return name.charAt(0).toLowerCase() + name.slice(1);
+}
+
+function typeName(text: string): string
+{
+    const name = pascal(text);
+    return /^[0-9]/.test(name) ? `_${name}` : name === "" ? "_" : name;
+}
+
+function key(name: string): string
+{
+    return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+
+/** Line breaks, CR LF counted once, which would end a `//` comment and turn the rest of its line into code. */
+const LINE_BREAKS = new RegExp(`${String.fromCodePoint(13, 10)}|[${String.fromCodePoint(10, 13, 0x2028, 0x2029)}]`, "g");
+
+/** Text for a `//` comment, kept on one line, so it cannot end the comment. */
+function commentText(text: string): string
+{
+    return text.replace(LINE_BREAKS, " ");
+}
+
+function comment(text: string | undefined, indent: string): string
+{
+    if (text === undefined || text.trim() === "")
+    {
+        return "";
+    }
+    const lines = text.trim().replace(/\*\//g, "* /").split(/\r?\n/);
+    return lines.length === 1 ? `${indent}/** ${lines[0]} */\n` : `${indent}/**\n${lines.map((line) => `${indent} * ${line}`.trimEnd()).join("\n")}\n${indent} */\n`;
+}
+
+function indentLines(text: string, indent: string): string
+{
+    return text.split("\n").map((line, index) => (index === 0 ? line : `${indent}${line}`)).join("\n");
+}
+
+function resolveRef<T>(context: Context, ref: string, section: string): T
+{
+    const prefix = `#/components/${section}/`;
+    if (!ref.startsWith(prefix))
+    {
+        fail(`only local references into components are supported, found ${ref}`);
+    }
+    const name = decodeURIComponent(ref.slice(prefix.length).replace(/~1/g, "/").replace(/~0/g, "~"));
+    const table = (context.document.components as Record<string, Record<string, T> | undefined> | undefined)?.[section];
+    const found = table?.[name];
+    if (found === undefined)
+    {
+        fail(`${ref} does not exist`);
+    }
+    return found;
+}
+
+function deref<T extends { $ref?: string }>(context: Context, value: T, section: string): T
+{
+    let current = value;
+    for (let depth = 0; current.$ref !== undefined; depth++)
+    {
+        if (depth > 16)
+        {
+            fail(`reference loop at ${current.$ref}`);
+        }
+        current = resolveRef<T>(context, current.$ref, section);
+    }
+    return current;
+}
+
+/** The type name each schema of the document being generated is written under, by schema name, which a `$ref` to the schema uses; `writeModule` sets it before it writes a type. */
+let schemaTypes: ReadonlyMap<string, string> = new Map();
+
+/** The built-in type names the module being generated writes, as `Record` for an object of free keys or `Blob` for a binary response; `writeModule` empties it before it writes. */
+let builtInsUsed = new Set<string>();
+
+/** A built-in type name, recorded as written by the module being generated. */
+function builtIn(name: string): string
+{
+    builtInsUsed.add(name);
+    return name;
+}
+
+function schemaRefName(ref: string): string
+{
+    const prefix = "#/components/schemas/";
+    if (!ref.startsWith(prefix))
+    {
+        fail(`only local schema references are supported, found ${ref}`);
+    }
+    const name = decodeURIComponent(ref.slice(prefix.length));
+    return schemaTypes.get(name) ?? typeName(name);
+}
+
+function literal(value: unknown): string
+{
+    return value === undefined ? "undefined" : JSON.stringify(value);
+}
+
+/** Renders a schema as a TypeScript type. `indent` is the current indentation for nested object types. */
+/** The keywords that combine other schemas; the type they give is intersected with the schema's own keywords. */
+const COMPOSITION_KEYWORDS: ReadonlySet<string> = new Set(["$ref", "allOf", "oneOf", "anyOf"]);
+
+/** The keywords that shape a type on their own, beside a composition keyword. */
+const OWN_KEYWORDS: ReadonlySet<string> = new Set(["const", "enum", "type", "properties", "additionalProperties", "items", "prefixItems"]);
+
+function typeOf(schema: SchemaObject | undefined, indent: string): string
+{
+    if (schema === undefined)
+    {
+        return "unknown";
+    }
+    const keywords = Object.keys(schema);
+    if (keywords.some((keyword) => COMPOSITION_KEYWORDS.has(keyword)) && keywords.some((keyword) => OWN_KEYWORDS.has(keyword)))
+    {
+        const part = (keep: (keyword: string) => boolean): SchemaObject => Object.fromEntries(Object.entries(schema).filter(([keyword]) => keep(keyword))) as SchemaObject;
+        return `${wrap(typeOf(part((keyword) => !OWN_KEYWORDS.has(keyword)), indent))} & ${wrap(typeOf(part((keyword) => !COMPOSITION_KEYWORDS.has(keyword)), indent))}`;
+    }
+    if (schema.$ref !== undefined)
+    {
+        return schemaRefName(schema.$ref);
+    }
+    const parts: string[] = [];
+    if (schema.const !== undefined)
+    {
+        parts.push(literal(schema.const));
+    }
+    else if (schema.enum !== undefined)
+    {
+        parts.push(schema.enum.map(literal).join(" | "));
+    }
+    else if (schema.oneOf !== undefined || schema.anyOf !== undefined)
+    {
+        parts.push((schema.oneOf ?? schema.anyOf ?? []).map((option) => typeOf(option, indent)).join(" | "));
+    }
+    else if (schema.allOf !== undefined)
+    {
+        parts.push(schema.allOf.map((option) => wrap(typeOf(option, indent))).join(" & "));
+    }
+    else
+    {
+        const types = Array.isArray(schema.type) ? schema.type : schema.type === undefined ? [] : [schema.type];
+        if (types.length === 0 && (schema.properties !== undefined || schema.additionalProperties !== undefined))
+        {
+            types.push("object");
+        }
+        if (types.length === 0 && (schema.items !== undefined || schema.prefixItems !== undefined))
+        {
+            types.push("array");
+        }
+        if (types.length === 0)
+        {
+            parts.push("unknown");
+        }
+        for (const type of types)
+        {
+            parts.push(primitive(type, schema, indent));
+        }
+    }
+    if (schema.nullable === true && !parts.includes("null"))
+    {
+        parts.push("null");
+    }
+    return [...new Set(parts)].join(" | ");
+}
+
+function wrap(type: string): string
+{
+    return type.includes(" | ") ? `(${type})` : type;
+}
+
+function primitive(type: string, schema: SchemaObject, indent: string): string
+{
+    switch (type)
+    {
+        case "string":
+            return "string";
+        case "number":
+        case "integer":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "null":
+            return "null";
+        case "array":
+            if (schema.prefixItems !== undefined)
+            {
+                const rest = schema.items === undefined ? "" : `, ...${wrap(typeOf(schema.items, indent))}[]`;
+                return `[${schema.prefixItems.map((item) => typeOf(item, indent)).join(", ")}${rest}]`;
+            }
+            return `${wrap(typeOf(schema.items, indent))}[]`;
+        case "object":
+            return objectType(schema, indent);
+        default:
+            return "unknown";
+    }
+}
+
+function objectType(schema: SchemaObject, indent: string): string
+{
+    const properties = Object.entries(schema.properties ?? {});
+    const required = new Set(schema.required ?? []);
+    const extra = schema.additionalProperties;
+    const record = extra === undefined || extra === false ? undefined : `${builtIn("Record")}<string, ${extra === true ? "unknown" : typeOf(extra, indent)}>`;
+    if (properties.length === 0)
+    {
+        return record ?? `${builtIn("Record")}<string, ${extra === false ? "never" : "unknown"}>`;
+    }
+    const inner = `${indent}    `;
+    const lines = properties.map(([name, property]) =>
+    {
+        const optional = required.has(name) ? "" : "?";
+        return `${comment(property.description, inner)}${inner}${key(name)}${optional}: ${indentLines(typeOf(property, inner), "")};`;
+    });
+    const body = `{\n${lines.join("\n")}\n${indent}}`;
+    return record === undefined ? body : `${body} & ${record}`;
+}
+
+function jsonSchemaOf(content: Record<string, MediaTypeObject> | undefined): { kind: "json"; schema: SchemaObject | undefined } | { kind: "form" } | { kind: "urlencoded" } | { kind: "text" } | { kind: "none" } | { kind: "other" }
+{
+    if (content === undefined || Object.keys(content).length === 0)
+    {
+        return { kind: "none" };
+    }
+    for (const [type, media] of Object.entries(content))
+    {
+        const bare = type.split(";")[0]?.trim().toLowerCase() ?? "";
+        if (bare === "application/json" || bare.endsWith("+json"))
+        {
+            return { kind: "json", schema: media.schema };
+        }
+    }
+    const types = Object.keys(content).map((type) => type.split(";")[0]?.trim().toLowerCase() ?? "");
+    if (types.includes("multipart/form-data"))
+    {
+        return { kind: "form" };
+    }
+    if (types.includes("application/x-www-form-urlencoded"))
+    {
+        return { kind: "urlencoded" };
+    }
+    if (types.some((type) => type.startsWith("text/")))
+    {
+        return { kind: "text" };
+    }
+    return { kind: "other" };
+}
+
+interface Entry
+{
+    name: string;
+    method: string;
+    path: string;
+    lines: string[];
+    doc: string | undefined;
+}
+
+function operationName(operation: OperationObject, method: string, path: string): string
+{
+    if (operation.operationId !== undefined && operation.operationId.trim() !== "")
+    {
+        return camel(operation.operationId);
+    }
+    const segments = path.split("/").filter((segment) => segment !== "").map((segment) =>
+    {
+        const match = /^\{(.+)\}$/.exec(segment);
+        return match === null ? pascal(segment) : `By${pascal(match[1] ?? "")}`;
+    });
+    return camel(`${method} ${segments.join(" ")}`);
+}
+
+function parameterGroups(context: Context, item: PathItemObject, operation: OperationObject): { params: string[]; query: string[]; queryRequired: boolean }
+{
+    const merged = new Map<string, ParameterObject>();
+    for (const list of [item.parameters ?? [], operation.parameters ?? []])
+    {
+        for (const raw of list)
+        {
+            const parameter = deref(context, raw, "parameters");
+            if (parameter.name === undefined || parameter.in === undefined)
+            {
+                fail(`a parameter needs a name and a location`);
+            }
+            merged.set(`${parameter.in}:${parameter.name}`, parameter);
+        }
+    }
+    const params: string[] = [];
+    const query: string[] = [];
+    let queryRequired = false;
+    for (const parameter of merged.values())
+    {
+        const name = parameter.name ?? "";
+        const schema = parameter.schema ?? (parameter.content === undefined ? undefined : Object.values(parameter.content)[0]?.schema);
+        const type = typeOf(schema, "            ");
+        const doc = comment(parameter.description, "            ");
+        if (parameter.in === "path")
+        {
+            params.push(`${doc}            ${key(name)}: ${type};`);
+        }
+        else if (parameter.in === "query")
+        {
+            const required = parameter.required === true;
+            queryRequired ||= required;
+            query.push(`${doc}            ${key(name)}${required ? "" : "?"}: ${type}${required ? "" : " | undefined"};`);
+        }
+        else if (parameter.in === "querystring")
+        {
+            queryRequired ||= parameter.required === true;
+            query.push(`${doc}            [name: string]: unknown;`);
+        }
+    }
+    return { params, query, queryRequired };
+}
+
+function bodyType(context: Context, operation: OperationObject): { type: string; required: boolean } | undefined
+{
+    if (operation.requestBody === undefined)
+    {
+        return undefined;
+    }
+    const body = deref(context, operation.requestBody, "requestBodies");
+    const content = jsonSchemaOf(body.content);
+    const required = body.required === true;
+    switch (content.kind)
+    {
+        case "json":
+            return { type: typeOf(content.schema, "        "), required };
+        case "form":
+            return { type: builtIn("FormData"), required };
+        case "urlencoded":
+            return { type: builtIn("URLSearchParams"), required };
+        case "text":
+            return { type: "string", required };
+        case "none":
+            return undefined;
+        default:
+            return { type: builtIn("BodyInit"), required };
+    }
+}
+
+function outputType(context: Context, operation: OperationObject): string
+{
+    const responses = Object.entries(operation.responses ?? {});
+    const successful = responses.filter(([status]) => /^2(\d\d|XX)$/.test(status)).toSorted(([a], [b]) => a.localeCompare(b));
+    const chosen = successful.length > 0 ? successful : responses.filter(([status]) => status === "default");
+    if (chosen.length === 0)
+    {
+        return "unknown";
+    }
+    const types = new Set<string>();
+    for (const [, raw] of chosen)
+    {
+        const response = deref(context, raw, "responses");
+        const content = jsonSchemaOf(response.content);
+        switch (content.kind)
+        {
+            case "json":
+                types.add(typeOf(content.schema, "        "));
+                break;
+            case "text":
+                types.add("string");
+                break;
+            case "none":
+                types.add("undefined");
+                break;
+            default:
+                types.add(builtIn("Blob"));
+        }
+    }
+    return [...types].join(" | ");
+}
+
+function entryOf(context: Context, path: string, item: PathItemObject, method: string, operation: OperationObject): Entry
+{
+    const { params, query, queryRequired } = parameterGroups(context, item, operation);
+    const lines = [`        method: ${JSON.stringify(method)};`, `        path: ${JSON.stringify(path)};`];
+    if (params.length > 0)
+    {
+        lines.push(`        params: {\n${params.join("\n")}\n        };`);
+    }
+    if (query.length > 0)
+    {
+        lines.push(`        query${queryRequired ? "" : "?"}: {\n${query.join("\n")}\n        };`);
+    }
+    const body = bodyType(context, operation);
+    if (body !== undefined)
+    {
+        lines.push(`        body${body.required ? "" : "?"}: ${body.type}${body.required ? "" : " | undefined"};`);
+    }
+    lines.push(`        output: ${outputType(context, operation)};`);
+    const doc = [operation.summary, operation.description, operation.deprecated === true ? "@deprecated" : undefined].filter((part) => part !== undefined && part !== "").join("\n\n");
+    return { name: operationName(operation, method, path), method, path, lines, doc: doc === "" ? undefined : doc };
+}
+
+/** The built-in types a generated module may write, with what each is. */
+const BUILT_INS: ReadonlyMap<string, string> = new Map([
+    ["Record", "TypeScript's Record type"],
+    ["Blob", "the global Blob type"],
+    ["FormData", "the global FormData type"],
+    ["URLSearchParams", "the global URLSearchParams type"],
+    ["BodyInit", "the global BodyInit type"]
+]);
+
+/** The type names no schema can take in a module, with what each is: the interface of the operations, the `RouteTable` the module imports, and the built-in types in `used`, which the module writes. A built-in the module does not write is left to a schema of that name. */
+function reservedTypeNames(apiName: string, used: ReadonlySet<string>): Map<string, string>
+{
+    const reserved = new Map([
+        ["RouteTable", "the RouteTable type the module imports"],
+        [apiName, "the interface of the operations, which apiName renames"]
+    ]);
+    for (const [name, what] of BUILT_INS)
+    {
+        if (used.has(name))
+        {
+            reserved.set(name, `${what}, which this module uses`);
+        }
+    }
+    return reserved;
+}
+
+/**
+ * The type name every schema is written under, by schema name, with the
+ * reason for a name that is not the schema's own. A schema keeps its own
+ * name, as `note-item` gives `NoteItem`, unless `reserved` holds it or a
+ * schema earlier in sorted order takes it; then it gets the first free
+ * name with a number added, as `Record2`.
+ */
+function schemaTypeNames(names: readonly string[], reserved: ReadonlyMap<string, string>): Map<string, { type: string; reason?: string }>
+{
+    const holders = new Map(reserved);
+    const assigned = new Map<string, { type: string; reason?: string }>();
+    for (const name of names)
+    {
+        const type = typeName(name);
+        if (!holders.has(type))
+        {
+            holders.set(type, `the type of the schema ${JSON.stringify(name)}`);
+            assigned.set(name, { type });
+        }
+    }
+    for (const name of names)
+    {
+        if (assigned.has(name))
+        {
+            continue;
+        }
+        const base = typeName(name);
+        let suffix = 2;
+        while (holders.has(`${base}${suffix}`))
+        {
+            suffix++;
+        }
+        const type = `${base}${suffix}`;
+        assigned.set(name, { type, reason: `named ${type} because ${base} is already ${holders.get(base) ?? "taken"}` });
+        holders.set(type, `the type of the schema ${JSON.stringify(name)}`);
+    }
+    return assigned;
+}
+
+/**
+ * Generates the contract module for an OpenAPI 3.x document given as a
+ * parsed object (JSON; convert YAML first). Schemas under
+ * `components.schemas` become exported types, every operation becomes an
+ * entry of the `Api` interface named by its `operationId` (or by its
+ * method and path), and `routes` carries the method and path of each.
+ * Header and cookie parameters, security, and non-local references are
+ * left out; the client sends headers through its options. A schema whose
+ * type name would clash is written under the first free name with a
+ * number added, as `Record2`, with a comment that says why, and every
+ * `$ref` to it uses that name: one that another schema takes first, as
+ * `note-item` and `note_item` both give `NoteItem`, one named like the
+ * interface of the operations or the `RouteTable` the module imports, and
+ * one named like a built-in type the module writes, such as `Record` for
+ * an object of free keys or `Blob` for a binary response. A schema named
+ * like a built-in the module does not write keeps its name.
+ */
+export function generateClient(document: OpenApiDocument, options: GenerateOptions = {}): string
+{
+    if (typeof document.openapi !== "string" || !document.openapi.startsWith("3."))
+    {
+        fail(`expected an OpenAPI 3.x document, found openapi: ${JSON.stringify(document.openapi)}`);
+    }
+    const context: Context = { document, apiName: options.apiName ?? "Api" };
+    const specifier = options.clientSpecifier ?? "@zerolith/client";
+    const names = Object.keys(document.components?.schemas ?? {}).toSorted((a, b) => a.localeCompare(b));
+    const first = writeModule(context, specifier, schemaTypeNames(names, reservedTypeNames(context.apiName, new Set())));
+    if (![...first.types.values()].some(({ type }) => first.used.has(type)))
+    {
+        return first.code;
+    }
+    return writeModule(context, specifier, schemaTypeNames(names, reservedTypeNames(context.apiName, first.used))).code;
+}
+
+/** The module text for the given schema type names, with the built-in types it writes, which a second pass reserves when a schema took one of their names. */
+function writeModule(context: Context, specifier: string, types: Map<string, { type: string; reason?: string }>): { code: string; used: ReadonlySet<string>; types: Map<string, { type: string; reason?: string }> }
+{
+    const { document } = context;
+    builtInsUsed = new Set();
+    const out: string[] = [];
+    const title = document.info?.title === undefined ? "an OpenAPI document" : `${document.info.title}${document.info.version === undefined ? "" : ` ${document.info.version}`}`;
+    out.push(`// Generated by @zerolith/client from ${commentText(title)}. Do not edit; regenerate instead.`);
+    out.push(`import type { RouteTable } from ${JSON.stringify(specifier)};`);
+    out.push("");
+
+    const schemas = Object.entries(document.components?.schemas ?? {}).toSorted(([a], [b]) => a.localeCompare(b));
+    schemaTypes = new Map(Array.from(types, ([name, { type }]) => [name, type]));
+    for (const [name, schema] of schemas)
+    {
+        const { type, reason } = types.get(name) ?? { type: typeName(name) };
+        const note = reason === undefined ? undefined : `The schema ${JSON.stringify(name)}, ${reason}.`;
+        const text = [schema.description ?? schema.title, note].filter((part) => part !== undefined && part.trim() !== "").join("\n\n");
+        out.push(`${comment(text, "")}export type ${type} = ${typeOf(schema, "")};`);
+        out.push("");
+    }
+
+    const entries: Entry[] = [];
+    const seen = new Set<string>();
+    for (const [path, rawItem] of Object.entries(document.paths ?? {}).toSorted(([a], [b]) => a.localeCompare(b)))
+    {
+        const item = deref(context, rawItem, "pathItems");
+        const operations: [string, OperationObject][] = [];
+        for (const method of METHODS)
+        {
+            const operation = item[method];
+            if (operation !== undefined)
+            {
+                operations.push([method, operation]);
+            }
+        }
+        for (const [method, operation] of Object.entries(item.additionalOperations ?? {}))
+        {
+            if (!/^[a-z0-9!#$%&'*+.^_`|~-]+$/i.test(method))
+            {
+                fail(`${JSON.stringify(path)} has the additional operation ${JSON.stringify(method)}, which is not an HTTP method name`);
+            }
+            if (FORBIDDEN_METHODS.has(method.toLowerCase()))
+            {
+                continue;
+            }
+            operations.push([method.toLowerCase(), operation]);
+        }
+        for (const [method, operation] of operations)
+        {
+            const entry = entryOf(context, path, item, method, operation);
+            if (seen.has(entry.name))
+            {
+                fail(`two operations resolve to the name "${entry.name}"; give them distinct operationId values`);
+            }
+            seen.add(entry.name);
+            entries.push(entry);
+        }
+    }
+
+    out.push(`export interface ${context.apiName}\n{`);
+    out.push(entries.map((entry) => `${comment(entry.doc, "    ")}    ${key(entry.name)}: {\n${entry.lines.join("\n")}\n    };`).join("\n"));
+    out.push("}");
+    out.push("");
+    out.push("export const routes = {");
+    out.push(entries.map((entry) => `    ${key(entry.name)}: { method: ${JSON.stringify(entry.method)}, path: ${JSON.stringify(entry.path)} }`).join(",\n"));
+    out.push(`} as const satisfies RouteTable<${context.apiName}>;`);
+    out.push("");
+    return { code: out.join("\n"), used: builtInsUsed, types };
+}