# @svelte-lean/query

> Root entry: defineQuery, defineMutation, the client, createQuery, createMutation, invalidate, patch, send, defineModule, QueryError and the public types.

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

Definitions, the client, the reactive bindings, the three ways to change cached values (invalidate, patch, optimistic) and errors: everything a screen needs, and the public types.

## Import

`import`

```ts
import { defineQuery, defineMutation, createQuery, createMutation, createClient, tag, type, page } from '@svelte-lean/query';
```

## Size

Production Vite builds of a small consumer entry, Svelte external. A marginal row is the bytes the entry adds over the row it names.

| Build | Over | gzip | brotli | Budget (gzip) |
| --- | --- | --- | --- | --- |
| `query` | – | 11787 B | 10839 B | 11800 B |
| `query+mutation` | – | 15409 B | 14167 B | 15500 B |
| `root (every export)` | – | 16134 B | 14844 B | 16200 B |

Read from `packages/query/artifacts/size.json`. Every entry and its method: [Performance](https://svelte-lean.vercel.app/query/performance.md).

## Definitions

Endpoints are values made once in a feature module. Builders are free of side effects, so an endpoint nobody imports is removed from the bundle.

### Functions

Builders of endpoints, schemas, tags and access rules.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `defineQuery` | `(init: QueryInit) => QueryEndpoint<P, R>` | – | A read endpoint: method and path, params, result, tags and policies. Path params are inferred from \`{name}\` segments. |
| # `defineMutation` | `(init: MutationInit) => MutationEndpoint<I, R, B>` | – | A write endpoint: method and path, body, result, the tags it invalidates and its access rule. |
| # `type` | `<T>() => StandardSchemaV1<T, T>` | – | A type-only schema: the value is typed as T and not validated. |
| # `page` | `<T>(row?: StandardSchemaV1<unknown, T>) => StandardSchemaV1<unknown, Page<T>>` | – | A paged result read through the profile's paginator; with a row schema, each row is validated. |
| # `file` | `() => StandardSchemaV1<FileResult, FileResult>` | – | A file result: the body is read as a Blob with its file name (downloads). |
| # `tag` | `<K extends TagName>(name: K, ...id: TagIdArgs<K>) => Tag` | – | A typed tag value. The id is required, optional or absent as the Tags registry declares it. |
| # `all` | `(...checks: Check<P>[]) => Rule<P>` | – | An access rule that holds when every check holds. |
| # `any` | `(...checks: Check<P>[]) => Rule<P>` | – | An access rule that holds when one of the checks holds. |
| # `not` | `(check: Check<P>) => Rule<P>` | – | The negation of an access check. |

### defineQuery options

The object passed to defineQuery(). Exactly one of get and post.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `get` | `string` | – | Path of a GET read, with \`{name}\` params (\`api/members/{id}\`); \`{+name}\` is sent unencoded (an address the server handed over, a full URL). |
| # `post` | `string` | – | Path of a read sent as POST; its params become the JSON body and stay part of the key. |
| # `params` | `StandardSchemaV1<unknown, Q>` | – | Search params (GET) or body (POST reads); path params come from the path. |
| # `result` required | `StandardSchemaV1<unknown, R>` | – | The result schema: type\<T\>(), page\<T\>(), file() or any Standard Schema. |
| # `id` | `string` | `METHOD path` | Unique endpoint id; needed when one URL is read two ways. |
| # `map` | `(raw, helpers: { page, params }) => unknown` | – | Reshape the unwrapped server value once per commit (params: the params the entry was asked with); replaces page normalization when given. |
| # `search` | `true \| (keyof P)[]` | – | Params sent in the query string whatever the method: all of them (a POST read with no body) or these keys. |
| # `priority` | `'high' \| 'low'` | `by cause` | Its automatic fetches as foreground or background work: 'low' queues behind the reads a page waits for and never takes the last slot. |
| # `pageParams` | `(page, perPage) => object` | `the profile's` | The page params createPaged and createInfinite add, instead of the profile's: rename them or leave them out. |
| # `entity` | `TagName` | – | Rows (or the value) are entities of this tag: each carries tag(entity, rowId(row)). |
| # `tags` | `TagTarget[] \| ((result, params) => TagTarget[])` | – | Tags the entry provides; invalidating one of them refetches or marks the entry. |
| # `fresh` | `Duration` | `client default (0)` | How long a value counts as fresh. |
| # `keep` | `Duration` | `'5m'` | How long an unobserved entry stays cached. |
| # `access` | `Access<P>` | – | Who may read it: a permission, a function, a rule or an array of them (all). false sends nothing and removes cached data; undefined waits. |
| # `scope` | `false` | – | Leave the client scope out of the key (public endpoints only). |
| # `retry` | `number \| false` | `client default (2); 0 on the server` | Attempts after the first for network, timeout, 408, 429 and 5xx failures. |
| # `poll` | `Duration \| ((value) => Duration \| false) \| PollInit<R>` | – | Definition-level polling; PollInit adds until, invalidates, background and reason (jobs). |
| # `persist` | `boolean \| { maxAge?: Duration }` | – | Opt in to ./persist for this endpoint. |
| # `share` | `false` | – | Opt out of row identity reuse on refetch. |
| # `rowId` | `(row) => string \| number` | `the profile's (id)` | Row identity for reuse, entities and patches. |
| # `orphan` | `'abort' \| 'finish'` | `'abort'` | What happens to a request whose last observer left. |
| # `maxEntries` | `number` | `20 for page() results` | Cap on inactive entries of this endpoint. |
| # `transport` | `TransportOverrides` | – | Per-endpoint transport options. |

### defineMutation options

The object passed to defineMutation(). Exactly one method key.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `post` | `string` | – | Path of a POST write, with \`{name}\` params. |
| # `put` | `string` | – | Path of a PUT write. |
| # `patch` | `string` | – | Path of a PATCH write. |
| # `delete` | `string` | – | Path of a DELETE write. |
| # `get` | `string` | – | Path of a GET that changes server state (rare). |
| # `id` | `string` | `METHOD path` | Unique endpoint id. |
| # `body` | `StandardSchemaV1<unknown, B>` | – | The body schema; the input is body plus path params. |
| # `result` | `StandardSchemaV1<unknown, R>` | `void` | The result schema. |
| # `map` | `(raw, helpers: { input }) => unknown` | – | Reshape the unwrapped server value; input is the run's input. |
| # `search` | `true \| (keyof B)[]` | – | Input fields sent in the query string: all of them (no body) or these keys; path params stay in the path. |
| # `invalidates` | `TagTarget[] \| ((result, input) => TagTarget[])` | – | Tags invalidated after success: observed entries refetch once, the others are marked stale. |
| # `access` | `Access<I>` | – | Who may run it; a run without access sends nothing. |
| # `queue` | `(input) => string` | – | Serialize runs that share a key (one write per entity at a time, in order). |
| # `encode` | `'json' \| 'multipart' \| 'auto' \| ((input) => 'json' \| 'multipart')` | `'auto'` | Body encoding; auto sends multipart when the body holds a File or Blob and no body when only path params remain; json and multipart always send one ({} or an empty form). A FormData input is sent as it is. |
| # `retry` | `number \| false` | `false` | Retries for this write. |
| # `transport` | `TransportOverrides` | – | Per-endpoint transport options. |

### Query endpoint

The value defineQuery() returns. Its methods act on the active client unless options.client is given.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `kind` | `'query'` | – | Discriminant. |
| # `id` | `string` | – | The endpoint id; a segment of every cache key. |
| # `fetch` | `(params, options?: FetchOptions) => Promise<R>` | – | A fresh cached value, else one request (cause user); rejects with QueryError. |
| # `prefetch` | `(params, options?: { client? }) => void` | – | A low-priority fetch; errors are stored on the entry, never thrown. |
| # `get` | `(params) => R \| undefined` | – | Synchronous read of the cached value, optimistic layers applied. |
| # `set` | `(params, data: R \| ((previous) => R)) => void` | – | A permanent local write; replayed over an older response in flight. |
| # `invalidate` | `(params?: Partial<P>, call?: FetchCall) => void` | – | Mark matching entries stale; observed ones refetch. |
| # `allowed` | `(params?) => Verdict` | – | The access verdict for these params, without fetching. |

### Mutation endpoint

The value defineMutation() returns.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `kind` | `'mutation'` | – | Discriminant. |
| # `id` | `string` | – | The endpoint id. |
| # `run` | `(input, options?: RunOptions) => Promise<R>` | – | An imperative run on the active client: the createMutation pipeline without reactive state. |

## Client

One client per application in the browser, one per request on the server. It owns the cache, the scheduler, the modules and the engine parts.

### Functions

Creating the client and reaching it.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `createClient` | `(init: ClientInit) => Client` | – | Creates a client. In the browser the first client becomes the realm client. |
| # `setClient` | `(client: Client) => void` | – | Sets the client for this component subtree (context) and, in the browser, as the realm client, which code after an await reaches. Outside a component (a test's beforeEach) it only sets the realm client; disposing it hands the realm back. |
| # `getClient` | `() => Client` | – | The active client: the context client during component initialisation, else the realm client. |
| # `invalidate` | `(targets: InvalidateTarget \| InvalidateTarget[], call?: FetchCall) => void` | – | Refetch: tags, endpoints or \[endpoint, partial params\]; observed entries refetch, the others are marked stale. |
| # `patch` | `(target: Tag \| QueryEndpoint \| [QueryEndpoint, params] \| TagName, update, options?: PatchOptions) => void` | – | Change cached values now. On an entity tag, every cached row or detail carrying it; update returns the new value, undefined (no change) or null (removed). Inside optimistic, a layer undone if the run fails. |
| # `send` | `<R>(request: SendRequest, client?: Client) => Promise<R>` | – | Escape hatch: one request through the transport, no cache, no tags. |
| # `defineModule` | `<M extends Module>(module: M) => M` | – | Makes a module for createClient({ modules }); it brings the hook set, so a client without modules carries none of it. |

### createClient options

ClientInit, the object passed to createClient().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `transport` required | `Transport` | – | The function that performs requests, usually http(). |
| # `scope` | `() => Scope` | – | Reactive. Its canonical string prefixes every key (operator, tenant, region). |
| # `onScopeChange` | `'drop' \| 'keep' \| ((from, to) => 'drop' \| 'keep')` | `'drop'` | What happens to entries of the previous scope. |
| # `can` | `(permission: Permission) => Verdict` | – | Resolves permission strings in access rules; undefined means not known yet. |
| # `access` | `(endpoint, input) => Verdict` | – | A rule for every endpoint, combined with each endpoint's access. |
| # `defaults` | `{ fresh?, keep?, retry?, slowAfter?, loadingDelay?, focus? }` | `fresh 0, keep '5m', retry 2, slowAfter '8s', loadingDelay 0, focus true` | Client-wide defaults. |
| # `presets` | `{ [name in PresetName]?: Duration }` | – | Named durations (the Presets registry) usable wherever a Duration is. |
| # `limits` | `{ concurrency?: number \| 'auto', inactiveBytes?, inactiveEntries? }` | `6, 32 MiB, 2000` | Requests per origin (auto: 24 once an answer reports HTTP/2 or HTTP/3, which a cross-origin API shows only with Timing-Allow-Origin) and the memory budget of unobserved entries. |
| # `modules` | `Module[]` | – | Optional behavior set up with the client (live, persist, devtools), made with defineModule(). |
| # `parts` | `EnginePart[]` | `none: each loads on first use` | Engine parts from ./parts included up front (allParts for a large app); parts not listed load on first use. |
| # `clock` | `Clock` | – | Time source and timers; the test client passes a virtual one. |
| # `environment` | `Environment` | – | Visibility and lifecycle events; the browser one by default. |

### Client

Properties and methods of the value createClient() returns.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `scopeKey` | `string` | – | The current canonical scope string. |
| # `online` | `boolean` | – | Reactive; false while requests fail with network. |
| # `invalidate` | `(targets, call?: FetchCall) => void` | – | Invalidate tags, endpoints or \[endpoint, params\], coalesced per microtask. |
| # `cancel` | `(filter?: { cause? }) => void` | – | Abort requests in flight, all or those of one cause. |
| # `clear` | `() => void` | – | Abort everything and drop every entry and optimistic layer (sign-out). |
| # `dispose` | `() => void` | – | Stop timers and listeners and abort everything (end of a server request, tests). |
| # `stats` | `() => ClientStats` | – | Counters of the cache, the queue and the totals. |
| # `recheck` | `() => void` | – | Re-evaluate access rules, for a can() that reads non-reactive state. |

### ClientStats

What client.stats() returns.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `entries` | `number` | – | Cached entries. |
| # `observed` | `number` | – | Entries read by a binding. |
| # `inactiveBytes` | `number` | – | Approximate size of unobserved entries. |
| # `fetching` | `number` | – | Requests in flight. |
| # `queued` | `number` | – | Requests waiting for a connection. |
| # `mutating` | `number` | – | Mutation runs not settled. |
| # `optimistic` | `number` | – | Active optimistic layers. |
| # `timers` | `number` | – | Items in the scheduler (one platform timer serves them). |
| # `totals` | `{ requests, joins, aborts, retries, invalidations, evictions }` | – | Counters since the client was created. |

## Bindings

Reactive results for components and classes. Call them during initialisation; every field is its own signal, written only when its value changes.

### Functions

createQuery and createMutation.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `createQuery` | `(endpoint, params?: () => P \| undefined \| null, options?: QueryOptions) => QueryResult<R, P>` | – | A query read where it is used: nothing is requested until a field is read in a reactive context. undefined (or null) from params means not ready: no key, no request. |
| # `createQuery (without params)` | `(endpoint, options: QueryOptions) => QueryResult<R, P>` | – | For an endpoint without params, or with when: false and load(params) for a binding started by hand. |
| # `createMutation` | `(endpoint, options?: MutationOptions) => MutationResult<I, R, B>` | – | A write with run(), busy, data and typed field errors. |

### createQuery options

QueryOptions, the last argument of createQuery().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `when` | `boolean \| (() => boolean)` | `true` | A state condition at the call site (dialog open, tab active); false pauses automatic fetching and keeps data. load() still starts it. |
| # `keepPrevious` | `boolean` | `false` | Show the previous key's data while a new key loads. |
| # `placeholder` | `R \| (() => R \| undefined)` | – | Shown while pending, never cached. |
| # `poll` | `PollOption \| (() => PollOption)` | – | Runtime polling control; the shortest active interval wins. |
| # `fresh` | `Duration` | – | Per-use freshness; the shortest of the active uses wins. |
| # `priority` | `'high' \| 'low'` | `the endpoint's` | This use's automatic fetches as foreground or background work. |

### QueryState

The everyday fields of every query-shaped result (createQuery, createPaged). Each is its own signal.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `data` | `R \| undefined` | – | The server value with optimistic layers applied. |
| # `error` | `QueryError \| undefined` | – | The last error; data is kept (except forbidden). |
| # `loading` | `boolean` | – | A fetch the user waits for: cause user, or nothing of this key is shown yet. |
| # `refreshing` | `boolean` | – | A quiet fetch while data is shown: poll, focus, invalidation, live. |
| # `busy` | `boolean` | – | loading or refreshing. |
| # `blocked` | `Blocked \| undefined` | – | Why nothing is fetched: 'access', 'waiting' or 'when' (when is false, or the params are not ready). |
| # `info` | `QueryInfo` | – | The less frequent fields: status, placeholder, stale, slow, updatedAt, fetch. |
| # `refetch` | `(call?: FetchCall) => Promise<void>` | – | Refetch the current key now (cause user); sends nothing while blocked. |

### QueryResult

What createQuery() returns: QueryState and load().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `load` | `(params?: P, call?: FetchCall) => Promise<R>` | – | Start the binding by hand (cause user, always a request), also while when is false. With params, the binding shows those from now on. |

### QueryInfo

result.info: the less frequent fields, each its own signal.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `status` | `'idle' \| 'pending' \| 'success' \| 'error'` | – | pending means there is no data yet. |
| # `placeholder` | `boolean` | – | data belongs to the previous key or to placeholder. |
| # `stale` | `boolean` | – | The value is older than fresh. |
| # `slow` | `boolean` | – | The current fetch exceeded slowAfter. |
| # `updatedAt` | `number` | – | Time of the last success; 0 before it. |
| # `fetch` | `FetchInfo \| undefined` | – | The running fetch, else the last one: cause, reason, source, start, attempt. |

### createMutation options

MutationOptions, the second argument of createMutation().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `optimistic` | `(input) => void` | – | Called when run() starts; every patch() it makes is a layer shown until the server confirms, removed if the run fails. |
| # `settle` | `'response' \| 'refetched'` | `'response'` | When run() resolves: on the answer, or after the invalidated observed entries refetched (busy and onSuccess wait too). |
| # `exclusive` | `boolean` | `true` | A second run() while one is busy returns its promise (the double-submit guard), whatever the body; false runs them side by side. |
| # `onSuccess` | `(result, input) => void` | – | A reaction bound to the run that triggered it (close a dialog, show a message); patch() and invalidate() in it act on the mutation's client. |

### MutationResult

What createMutation() returns.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `run` | `(input: I, options?: RunOptions) => Promise<R>` | – | Send the write; also writes status, data and error, so markup needs no try/catch. |
| # `status` | `'idle' \| 'queued' \| 'running' \| 'success' \| 'error'` | – | queued means waiting behind a run with the same queue key. |
| # `busy` | `boolean` | – | queued or running: disable the button on this. |
| # `data` | `R \| undefined` | – | The result of the last successful run. |
| # `error` | `QueryError<B> \| undefined` | – | The last error, with field errors typed by the body. |
| # `slow` | `boolean` | – | The run exceeded slowAfter. |
| # `progress` | `{ loaded, total } \| undefined` | – | Upload progress of a run with transport.progress. |
| # `allowed` | `(input?: I) => boolean` | – | Access: without input for a button, with input for one row. |
| # `reset` | `() => void` | – | Back to idle; clears data and error. |

### run options

RunOptions, the second argument of run().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `optimistic` | `(input) => void` | – | Patches of this run, after the mutation's own optimistic. |
| # `signal` | `AbortSignal` | – | Cancel an upload or a long write. |
| # `progress` | `(loaded, total) => void` | – | Upload progress callback for an imperative endpoint.run(). |
| # `reason` | `Reason` | – | Carried by the refetches this run's invalidates start. |
| # `loading` | `boolean` | – | Show those refetches as loading (true) or refreshing (false). |
| # `priority` | `'high' \| 'low'` | – | Run those refetches as foreground or background work. |

## Errors

Errors are values. The package never shows one; kind, status and code give the application what it needs to word it.

### QueryError

The error every failed request and run reports. Custom profiles and transports throw it.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `QueryError` | `class QueryError<B> extends Error` | – | new QueryError(init: QueryErrorInit); the fields below. |

### QueryError fields

Only network, timeout and HTTP 408, 429 and 5xx failures are retried.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `kind` | `ErrorKind` | – | 'network', 'timeout', 'http', 'refused', 'validation', 'forbidden' or 'parse'. |
| # `status` | `number` | – | 0 for network and timeout; 200 for a refusal inside a 2xx. |
| # `code` | `string \| number \| undefined` | – | The server code. |
| # `message` | `string` | – | The server's text when present, else an empty string. |
| # `fields` | `FieldErrors<B> \| undefined` | – | Field errors of a 422 or a refusal with a field map. |
| # `issues` | `Issue[] \| undefined` | – | Schema failures (kind parse). |
| # `details` | `unknown` | – | Anything else the server sent. |
| # `requestId` | `string \| undefined` | – | The request id, when the server sends one. |
| # `retryAfter` | `number \| undefined` | – | Milliseconds, from Retry-After. |
| # `method` | `string` | – | The request method. |
| # `url` | `string` | – | The request URL. |

### QueryErrorInit

The constructor argument, for custom transports and profiles.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `kind` required | `ErrorKind` | – | The error kind. |
| # `status` | `number` | `0` | HTTP status. |
| # `code` | `string \| number` | – | Server code. |
| # `message` | `string` | – | Server text. |
| # `fields` | `{ [path]: string \| string[] }` | – | Raw field map ('lines.0.sku'); strings are wrapped in arrays. |
| # `issues` | `Issue[]` | – | Schema issues. |
| # `details` | `unknown` | – | Anything else. |
| # `requestId` | `string` | – | Request id. |
| # `retryAfter` | `number` | – | Milliseconds. |
| # `method` | `string` | – | Request method. |
| # `url` | `string` | – | Request URL. |
| # `cause` | `unknown` | – | The underlying error. |

### FieldErrors

error.fields: field messages typed by the request body.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `fields` | `{ [K in keyof B]?: string[] }` | – | Top-level keys: exactly the body's fields. |
| # `at` | `(k1, index?, k2?) => string[] \| undefined` | – | Nested keys ('lines.0.sku'), typed step by step. |
| # `raw` | `{ [path]: string[] }` | – | Every server key, also ones the body type does not know. |

## Registries

Interfaces an application augments with declare module '@svelte-lean/query'. An empty registry accepts any string.

### Registry interfaces

Augment them once per feature module.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `Tags` | `interface Tags { Name: IdType }` | – | Tag name to id type; void for a tag without id. A typo in a tag is a compile error. |
| # `Permissions` | `interface Permissions { 'slug': true }` | – | Permission strings accepted by access rules and can(). |
| # `Presets` | `interface Presets { name: true }` | – | Duration preset names; values live in createClient({ presets }). |
| # `Reasons` | `interface Reasons { name: true }` | – | Application fetch reasons. |
| # `TransportOverrides` | `interface TransportOverrides` | – | Per-endpoint transport options; applications may add fields. |

### TransportOverrides

The transport option of a definition.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `headers` | `HeadersInit` | – | Extra headers for this endpoint. |
| # `envelope` | `'unwrap' \| 'keep' \| 'raw'` | – | How the profile treats the platform's envelope. |
| # `accept` | `(envelope: Envelope) => boolean` | – | Accept a success: false envelope as a success (info codes). |
| # `responseType` | `'json' \| 'text' \| 'blob'` | `'json'` | How the body is read. |
| # `progress` | `boolean` | – | Upload progress (sent over XHR). |
| # `multipart` | `FormDataOptions` | – | Multipart encoding options. |
| # `timeout` | `Duration` | – | Timeout per attempt. |
| # `methodSpoof` | `boolean` | `the profile's` | true sends this endpoint's PUT, PATCH and DELETE as POST with \_method, JSON bodies too; false never. |

## Types

The other public types, for annotations and custom transports.

### Values and unions

Type names exported by the root entry.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `Duration` | ``number \| `${number}${'ms' \| 's' \| 'm' \| 'h'}` \| 'never' \| PresetName`` | – | Milliseconds, a string with a unit, never, or a preset name. |
| # `Cause` | `'mount' \| 'params' \| 'user' \| 'poll' \| 'focus' \| 'reconnect' \| 'invalidate' \| 'live' \| 'prefetch' \| 'retry'` | – | Why a request ran; decides priority and whether it shows loading. |
| # `Blocked` | `'access' \| 'waiting' \| 'when'` | – | Why a binding fetches nothing. |
| # `Verdict` | `boolean \| undefined` | – | An access verdict; undefined means not known yet (wait, keep data). |
| # `Access` | `Check<P> \| Check<P>[]` | – | A permission, a function, a rule, or an array meaning all of them. |
| # `Scope` | `(string \| number \| null)[]` | – | The client scope. |
| # `Tag` | `opaque` | – | A tag value made by tag(). |
| # `TagTarget` | `Tag \| TagName` | – | A tag, or a bare name meaning every id. |
| # `InvalidateTarget` | `TagTarget \| QueryEndpoint \| [QueryEndpoint, object]` | – | What invalidate() accepts. |
| # `PollOption` | `Duration \| false \| { on, every, background?, reason? }` | – | The poll option of a binding, or what its function returns. |
| # `EnginePart` | `opaque` | – | An optional engine part from ./parts. |
| # `ErrorKind` | `'network' \| 'timeout' \| 'http' \| 'refused' \| 'validation' \| 'forbidden' \| 'parse'` | – | The kinds of QueryError. |
| # `QueryPolicy, MutationPolicy` | `interface` | – | The options a separate policy module may set (codegen). |

### Page

The value of a page() result.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `rows` | `T[]` | – | The rows of this page. |
| # `total` | `number` | – | Rows on every page. |
| # `page` | `number` | – | Page number, 1-based. |
| # `perPage` | `number` | – | Page size. |
| # `lastPage` | `number` | – | The last page number. |
| # `estimated` | `true` | – | Read from a bare list: lastPage and total are derived. |

### PatchOptions

The third argument of patch().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `until` | `(value: T) => boolean` | – | Inside optimistic only: after the run succeeded, the layer stays until the server value satisfies until. |

### FetchInfo

One request as a binding reports it (info.fetch).

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `cause` | `Cause` | – | Engine category. |
| # `reason` | `Reason \| undefined` | – | Application label. |
| # `source` | `string \| undefined` | – | What triggered it: a mutation id, a live rule, a tag. |
| # `loading` | `boolean \| undefined` | – | The call's hint: true shows it as loading, false as refreshing. |
| # `startedAt` | `number` | – | Start time. |
| # `attempt` | `number` | – | 1, then retries. |

### FetchCall

Options of every call that starts fetches: refetch, load, invalidate, ep.fetch, ep.invalidate and run.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `reason` | `Reason` | – | Application label carried by the fetches (info.fetch.reason). |
| # `loading` | `boolean` | – | Show the fetch as loading (true) or refreshing (false) instead of the cause's default. |
| # `priority` | `'high' \| 'low'` | – | Run the fetches this call starts as foreground or background work. |

### FetchOptions

Options of endpoint.fetch().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `from` | `'cache' \| 'network'` | `'cache'` | cache returns fresh cached data or fetches; network always fetches. |
| # `reason` | `Reason` | – | Application label. |
| # `loading` | `boolean` | – | Show the fetch as loading or refreshing. |
| # `priority` | `'high' \| 'low'` | – | Foreground or background work. |
| # `signal` | `AbortSignal` | – | Abort the wait. |
| # `client` | `Client` | – | The client to use (a SvelteKit load on the server). |

### TransportRequest

What a transport receives. Write one to answer from anything other than HTTP.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `endpoint` | `QueryEndpoint \| MutationEndpoint \| undefined` | – | The endpoint; undefined for send(). |
| # `method` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'` | – | HTTP method. |
| # `path` | `string` | – | Path with params substituted and URL-encoded ({+name}: unencoded). |
| # `search` | `object \| undefined` | – | Search params. |
| # `body` | `unknown` | – | The body. |
| # `scope` | `Scope` | – | The scope captured with the key. |
| # `signal` | `AbortSignal` | – | Aborted when nobody waits for the answer. |
| # `priority` | `'high' \| 'auto' \| 'low'` | – | Fetch priority from the cause. |
| # `cause` | `Cause \| 'mutation'` | – | Why it was sent. |
| # `progress` | `(loaded, total) => void` | – | Upload progress callback. |
| # `overrides` | `TransportOverrides` | – | The endpoint's transport options. |

### TransportResponse

What a transport resolves with.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `data` | `unknown` | – | The unwrapped value. |
| # `bytes` | `number` | – | Approximate size; 0 when unknown. |
| # `text` | `string` | – | Raw text, when the body was text. |
| # `meta` | `ResponseMeta` | – | Request id, code, invalidation hints, refreshed values. |
| # `protocol` | `string` | – | The answer's protocol (h2, h3, http/1.1) when known. |

### Profile

A platform's conventions, passed to http({ profile }). laravel() is one.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `search` | `(params) => string` | – | Params to a query string. |
| # `body` | `(request) => { body, headers?, method? }` | – | Encode a write body. |
| # `read` | `(response, parsed, request) => unknown` | – | Unwrap the envelope or throw a QueryError. |
| # `meta` | `(response, parsed, request) => ResponseMeta \| undefined` | – | Request id, info code, freshness hints. |
| # `page` | `(value) => Page` | – | Read a paginator into a Page. |
| # `pageParams` | `(page, perPage) => object` | – | Page params sent by createPaged and createInfinite. |
| # `rowId` | `(row) => string \| number \| undefined` | – | Default row identity. |
| # `respond` | `(value, init?) => Response` | – | Inverse of read, for mocks and MSW handlers. |

### Module

An opt-in entry point attached to the client through modules; made with defineModule().

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `name` | `string` | – | Module name. |
| # `setup` | `(client, hooks: ModuleHooks) => void \| (() => void)` | – | Called once with the client; returns its teardown. |

### ModuleHooks

The hook set a module receives. Every act goes through the core pipeline.

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| # `onEntry` | `(listener) => off` | – | An entry was created. |
| # `onObserved` | `(listener) => off` | – | An entry gained its first or lost its last observer. |
| # `onRequest` | `(listener) => off` | – | A request was sent, with its cause. |
| # `onCommit` | `(listener) => off` | – | A response's value or a final error was written. |
| # `onRemove` | `(listener) => off` | – | An entry was removed, with the reason. |
| # `onInvalidate` | `(listener) => off` | – | Targets were invalidated, locally or from another tab. |
| # `onMutation` | `(listener) => off` | – | A mutation started or settled. |
| # `onLifecycle` | `(listener) => off` | – | Visibility, network and page lifecycle events. |
| # `entries` | `(target) => Iterable<EntryHandle>` | – | The entries a target matches. |
| # `write` | `(entry, update, source) => void` | – | A local write through the pipeline. |
| # `hydrate` | `(entry, record) => boolean` | – | Commit an outside value only when it is newer. |
| # `invalidate` | `(targets, cause, source?) => void` | – | Invalidate with a cause. |
| # `schedule` | `(at, run) => cancel` | – | The shared scheduler. |
| # `lead` | `(role, run) => release` | – | Run while this tab leads the role. |
| # `provideLead` | `(impl: LeadProvider) => void` | – | Install a browser-wide election (./tabs). |
| # `dev` | `(listener) => off` | – | Development diagnostic events; absent in production. |

## Guide

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