Query Reference

@svelte-lean/query-codegen

query-codegen experimental

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.

Markdown version of this page, for assistants (Markdown for AI)

Note @svelte-lean/query-codegen is experimental: the API can still change in a minor release. Stability per entry point: Entry points.

On this page

Import

import

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. All entry points: Svelte Lean Query.