# @svelte-lean/query-codegen

> The slq-codegen command, its flags, defineConfig() options, what each OpenAPI construct generates and the policy module types.

Page: https://svelte-lean.vercel.app/query/api/codegen · Markdown: https://svelte-lean.vercel.app/query/api/codegen.md · Index: https://svelte-lean.vercel.app/llms.txt

A development tool: the slq-codegen command writes one module of defineQuery and defineMutation definitions per OpenAPI tag, typed from openapi-typescript output. Nothing of it ships to a browser.

> **Note** `@svelte-lean/query-codegen` is experimental: the API can still change in a minor release. Stability per entry point: [Entry points](https://svelte-lean.vercel.app/query.md#entry-points).

## Import

`import`

```ts
import { defineConfig, kebab } from '@svelte-lean/query-codegen';
```

## Size

A development tool: nothing of it ships to a browser bundle.

## Command

slq-codegen reads the document once, writes only the files whose content changed and reports the rest as unchanged.

### Flags

Every flag falls back to the configuration file.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `--spec` | `path` | `config.spec` | OpenAPI 3.0 or 3.1 JSON document; local $ref only. |
| # `--types` | `path` | `config.types` | openapi-typescript output for the same document. |
| # `--config` | `path` | `slq.codegen.ts, .mjs or .js` | The configuration module. |
| # `--check` | `boolean` | – | Write nothing; exit 1 when a file would change (CI). |
| # `--prune` | `boolean` | – | Delete generated modules the document no longer produces. |

## Configuration

The default export of slq.codegen.ts, typed by defineConfig().

### Config

out is required.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `out` required | `(tag: string) => string` | – | Path of a tag's module; must end in .gen.ts. Two tags may not share a file. |
| # `untagged` | `string` | – | Module of operations without a tag; without it they are an error. |
| # `envelope` | `string \| false` | `false` | Property unwrapped from documented 2xx JSON responses; must match what the profile unwraps. |
| # `names` | `Record<string, string>` | `{}` | Export names by operationId or METHOD path. |
| # `entities` | `Record<string, { one, many }>` | `{}` | Entity tag names of a path segment where the English rules are wrong. |
| # `exclude` | `string[]` | `[]` | Operations written by hand instead. |
| # `tags` | `{ defaults?: boolean }` | `{ defaults: true }` | Default entity, tags and invalidates from paths. |
| # `spec` | `string` | – | The OpenAPI document; --spec wins. |
| # `types` | `string` | – | The openapi-typescript output; --types wins. |
| # `typesImport` | `string` | `a relative path` | Import specifier of the types file in generated modules. |
| # `importExtension` | `string` | `''` | Appended to relative specifiers ('.js' for node16 resolution). |
| # `package` | `string` | `'@svelte-lean/query'` | Import specifier of the query package. |

## Output

Per tag, \<tag\>.gen.ts with the endpoints and the registry augmentation, and \<tag\>.types.gen.ts with the types and one interface per operation for policy modules.

### What each construct becomes

From the OpenAPI document to definitions.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `GET, or POST with x-slq-read` | `defineQuery` | – | A read with get: or post:. |
| # `POST, PUT, PATCH, DELETE` | `defineMutation` | – | A write with the method key. |
| # `path /api/domains/{domain}` | `'api/domains/{domain}'` | – | The parameter typed by its schema. |
| # `query parameters` | `params / input` | – | params of a read; part of the input of a write. |
| # `JSON request body` | `body: type<Input>()` | – | The body type. |
| # `multipart/form-data body` | `encode: 'multipart'` | – | Binary fields typed Blob. |
| # `2xx JSON response` | `result: type<R>()` | – | Unwrapped by envelope; a component schema becomes a named alias. |
| # `Laravel paginator` | `result: page<Row>()` | – | A data array with total and last\_page beside it or in meta. |
| # `binary response` | `result: file()` | – | A FileResult. |
| # `text/* response` | `result: type<string>()` | – | With transport: { responseType: 'text' }. |
| # `204 no content` | `no result` | – | R is void. |
| # `x-permission` | `access: 'slug'` | – | An array means all of them; the Permissions registry is augmented. |
| # `422 responses` | `nothing` | – | FieldErrors are typed by the body. |

### Default tags

With tags.defaults, from the last static path segment (call-requests: CallRequest, CallRequests).

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `GET /x (a page or an array of objects with id)` | `entity: 'X', tags: ['Xs']` | – | A list. |
| # `GET /x/{id}` | `entity: 'X'` | – | A detail. |
| # `POST /x` | `invalidates: ['Xs']` | – | Where GET /x is such a list. |
| # `PUT, PATCH, DELETE /x/{id}` | `invalidates: (_, input) => [tag('X', input.id), 'Xs']` | – | Where /x or /x/{id} is known. |
| # `anything else` | `none` | – | The policy module decides. |

## Programmatic API

The functions behind the command, for build scripts and tests.

### Exports

Runtime exports of the package.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `defineConfig` | `(config: Config) => Config` | – | Identity: gives slq.codegen.ts its types. |
| # `run` | `(options: RunOptions) => RunResult` | – | What the command does: read, generate, write or check. |
| # `generate` | `(input: GenerateInput) => GenerateResult` | – | Generate in memory from a parsed document and the types text. |
| # `build` | `(document, config, options) => BuildResult` | – | The intermediate model of every module. |
| # `emitModule` | `(module: ModuleIR) => string` | – | The text of a \<tag\>.gen.ts module. |
| # `emitTypes` | `(module: ModuleIR) => string` | – | The text of a \<tag\>.types.gen.ts module. |
| # `indexSchema` | `(text: string) => SchemaIndex` | – | The declared names of an openapi-typescript file. |
| # `exportsOf` | `(text: string) => Map<string, Set<string> \| null>` | – | A policy module's exports and the members each sets. |
| # `kebab` | `(value: string) => string` | – | kebab-case, for out paths. |
| # `plural` | `(value: string) => string` | – | The plural of the last word. |
| # `singular` | `(value: string) => string` | – | The singular of the last word. |
| # `CodegenError` | `class CodegenError extends Error` | – | A generation error with an slq/codegen-\* code. |

### RunOptions

The argument of run().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `spec` | `string` | `config.spec` | The OpenAPI JSON document. |
| # `types` | `string` | `config.types` | The openapi-typescript output. |
| # `config` required | `Config` | – | The configuration. |
| # `cwd` | `string` | `process.cwd()` | Resolves relative paths. |
| # `check` | `boolean` | – | Write nothing; report what would change. |
| # `prune` | `boolean` | – | Delete generated modules this run no longer produces. |

## Guide

How to use it, with examples: [Codegen](https://svelte-lean.vercel.app/query/codegen.md). All entry points: [Svelte Lean Query](https://svelte-lean.vercel.app/query.md).