# @zerolith/client/generate Import from `@zerolith/client/generate`. Generated from the source; every signature below is what the published types declare. ## Functions ### generateClient ```ts function generateClient(document: OpenApiDocument, options?: GenerateOptions): string ``` 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. Source: `packages/client/src/generate.ts:669` ## Interfaces ### SchemaObject ```ts interface SchemaObject ``` A JSON Schema object as OpenAPI 3.1 and later carry it (draft 2020-12 plus the OAS vocabulary). - `$ref?: string`: A reference to `#/components/schemas/`, 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. - `type?: string | 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`. - `nullable?: boolean`: The OpenAPI 3.0 flag that also allows `null`; when `true`, `null` joins the type. - `enum?: unknown[]`: 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. - `const?: 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. - `properties?: Record`: 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. - `required?: string[]`: The names in `properties` that must be present; every other property is generated as optional. - `additionalProperties?: boolean | SchemaObject`: The schema of keys beyond `properties`, rendered as a `Record` joined to them with `&`; `true` allows `unknown` values, and `false` makes an object without properties `Record`. - `items?: SchemaObject`: The schema of each array element, rendered as `T[]`, or `unknown[]` without it; beside `prefixItems` it types the elements after the tuple. - `prefixItems?: 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. - `oneOf?: 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. - `anyOf?: 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. - `allOf?: 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. - `description?: string`: Becomes the doc comment on a component schema's generated type, ahead of `title`, and on an object property's member. - `title?: 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`. Source: `packages/client/src/generate.ts:8` ### ParameterObject ```ts interface ParameterObject ``` A Parameter Object or a reference to one. - `$ref?: string`: A reference to `#/components/parameters/`, which replaces this object; any other target, or a missing one, fails generation. - `name?: 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. - `in?: "query" | "querystring" | "header" | "path" | "cookie"`: 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. - `required?: boolean`: 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. - `description?: string`: The doc comment on the parameter's generated member. - `schema?: SchemaObject`: The schema of the value, rendered as the member's type; without it or `content`, the type is `unknown`. - `content?: Record`: The single media type entry OpenAPI allows in place of `schema`; when `schema` is absent, the entry's `schema` gives the member's type. Source: `packages/client/src/generate.ts:43` ### MediaTypeObject ```ts interface MediaTypeObject ``` A Media Type Object. - `schema?: SchemaObject`: 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`. Source: `packages/client/src/generate.ts:62` ### RequestBodyObject ```ts interface RequestBodyObject ``` A Request Body Object or a reference to one. - `$ref?: string`: A reference to `#/components/requestBodies/`, which replaces this object; any other target, or a missing one, fails generation. - `description?: string`: A brief description of the body; the generator does not carry it into the output. - `required?: boolean`: Makes the generated `body` input required; OpenAPI's default is `false`, which generates it as optional. - `content?: Record`: 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`. Source: `packages/client/src/generate.ts:69` ### ResponseObject ```ts interface ResponseObject ``` A Response Object or a reference to one. - `$ref?: string`: A reference to `#/components/responses/`, which replaces this object; any other target, or a missing one, fails generation. - `description?: string`: A description of the response; the generator does not carry it into the output. - `content?: Record`: 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`. Source: `packages/client/src/generate.ts:82` ### OperationObject ```ts interface OperationObject ``` An Operation Object. - `operationId?: string`: 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. - `summary?: string`: The first paragraph of the doc comment on the operation's entry in `Api`. - `description?: string`: Follows `summary` in the doc comment on the operation's entry in `Api`. - `deprecated?: boolean`: When `true`, the doc comment on the operation's entry ends with `@deprecated`. - `parameters?: ParameterObject[]`: The operation's parameters, merged with the path item's; one with the same `name` and `in` as a path item parameter replaces it. - `requestBody?: RequestBodyObject`: The request body, generated as the entry's `body` input; without it the entry has no `body`. - `responses?: Record`: 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. Source: `packages/client/src/generate.ts:93` ### PathItemObject ```ts interface PathItemObject ``` A Path Item Object. - `$ref?: string`: A reference to `#/components/pathItems/`, which replaces this item; any other target, or a missing one, fails generation. - `summary?: string`: A summary meant for every operation on the path; the generator does not carry it into the output. - `description?: string`: A description meant for every operation on the path; the generator does not carry it into the output. - `parameters?: ParameterObject[]`: Parameters shared by every operation on the path; an operation's own parameter with the same `name` and `in` replaces one. - `get?: OperationObject`: The `GET` operation on this path. - `put?: OperationObject`: The `PUT` operation on this path. - `post?: OperationObject`: The `POST` operation on this path. - `delete?: OperationObject`: The `DELETE` operation on this path. - `options?: OperationObject`: The `OPTIONS` operation on this path. - `head?: OperationObject`: The `HEAD` operation on this path. - `patch?: OperationObject`: The `PATCH` operation on this path. - `trace?: OperationObject`: The `TRACE` operation on this path. - `query?: OperationObject`: The `QUERY` operation on this path (OpenAPI 3.2): a safe, idempotent request that carries a body. - `additionalOperations?: Record`: 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. Source: `packages/client/src/generate.ts:112` ### OpenApiDocument ```ts interface OpenApiDocument ``` The parts of an OpenAPI document the generator reads. - `openapi: string`: The OpenAPI version, such as `3.1.0`; a value that does not start with `3.` fails generation. - `info?: { title?: string; version?: string }`: The API's title and version, which the generated file's header comment names as its source. - `paths?: Record`: Path templates mapped to their items; every operation under them becomes an entry of `Api` and `routes`, sorted by path. - `components?: { schemas?: Record; parameters?: Record; requestBodies?: Record; responses?: Record; pathItems?: Record }`: Reusable objects: each entry of `schemas` becomes an exported type named after its key, and `$ref` values resolve into the other sections. Source: `packages/client/src/generate.ts:145` ### GenerateOptions ```ts interface GenerateOptions ``` Options for `generateClient`. - `clientSpecifier?: string`: The module the generated file imports `RouteTable` from. Defaults to `@zerolith/client`. - `apiName?: string`: The name of the generated contract interface. Defaults to `Api`. Source: `packages/client/src/generate.ts:164`