liaise 5.0.1 → 5.0.3

package/README.md

@@ -2,271 +2,539 @@
 
 *lee-AYZ* — to act as the link between two parties.
 
-> Formerly published as `@iremlopsum/apify`. Same code, same API, full history — switching takes two steps, see [MIGRATION.md](./MIGRATION.md#upgrading-to-500).
+**Your API calls, minus the surprises.**
 
-Runtime-agnostic, type-safe HTTP client for REST and GraphQL. Built on standard `fetch`. Zero dependencies.
+Type-safe REST and GraphQL on plain fetch. Never throws. Zero dependencies. Works with any framework.
 
-- **Unified API** — REST and GraphQL share the same `Result<T>` shape, middleware stack, and error contract
-- **Never throws** — every call returns `{ data, error, response, retry }`, no try/catch required
-- **Composable middleware** — retry, cache, dedupe, auth, logging — applied at global, per-endpoint, or per-call level
-- **Types by inference** — declare params and response once on the endpoint definition; types flow to every call site automatically
-- **Runtime-agnostic** — Node.js 20+, browsers, Bun, Deno, Cloudflare Workers, React Native (its built-in `fetch`; not tested in CI) — any environment with `fetch`
-- **Tiny** — about **5.6 kB gzipped** for a REST-only import, 6.7 kB for the core entry, 7.8 kB with all middleware (measured by `npm run size`); tree-shaking drops what you do not import
+[![npm](https://img.shields.io/npm/v/liaise)](https://www.npmjs.com/package/liaise) [![CI](https://github.com/iremlopsum/liaise/actions/workflows/ci.yml/badge.svg)](https://github.com/iremlopsum/liaise/actions/workflows/ci.yml) ![5.8 kB gzipped](https://img.shields.io/badge/gzipped-5.8%20kB-blue) ![MIT](https://img.shields.io/badge/license-MIT-blue)
 
-```
+```bash
 npm install liaise
 ```
 
-## Table of Contents
+Formerly published as `@iremlopsum/apify`; switching takes two steps, see [MIGRATION.md](./MIGRATION.md#upgrading-to-500).
+
+**Contents**
 
-- [Getting Started](#getting-started)
-- [REST API](#rest-api)
-  - [Request](#request)
-  - [`defineRequest`](#definerequest)
-  - [Response validation](#response-validation)
+- [The problem it solves](#the-problem-it-solves)
+- [Quick start](#quick-start)
+- [How it fits together](#how-it-fits-together)
+- [Guide](#guide)
+  - [Defining endpoints](#defining-endpoints)
+  - [Handling errors](#handling-errors)
+  - [Sending data](#sending-data)
+  - [Reading responses](#reading-responses)
+  - [Validating responses](#validating-responses)
+  - [Cancelling, deadlines and stale requests](#cancelling-deadlines-and-stale-requests)
+  - [Sharing identical requests](#sharing-identical-requests)
+  - [Retries, caching and logging](#retries-caching-and-logging)
+  - [Writing middleware](#writing-middleware)
   - [Pagination](#pagination)
-  - [Query strings](#query-strings)
-  - [Result](#result)
-  - [Error handling with `onError`](#error-handling-with-onerror)
-  - [Middleware](#middleware)
-    - [Built-in middleware (retry, cache, log)](#built-in-middleware)
-  - [Content types](#content-types)
-  - [Response parsing](#response-parsing)
-  - [Cancellation](#cancellation)
-  - [Timeout](#timeout)
-  - [Sharing](#sharing)
-  - [TypeScript](#typescript)
-- [GraphQL Client](#graphql-client)
-  - [Queries and mutations](#queries-and-mutations)
-  - [GraphQL errors](#graphql-errors)
-  - [Middleware](#middleware-1)
-- [Testing](#testing)
-- [Philosophy](#philosophy)
-- [API Reference](#api-reference)
-- [Contributing](#contributing)
-
-## Getting Started
-
-Define your endpoints as `Request` instances, wire them into a client with `createApi`, and call them with full type safety.
+  - [GraphQL](#graphql)
+  - [Testing your code](#testing-your-code)
+- [Recipes](#recipes)
+  - [Add an auth header and refresh the token on a 401](#add-an-auth-header-and-refresh-the-token-on-a-401)
+  - [Search as you type](#search-as-you-type)
+  - [Use with TanStack Query](#use-with-tanstack-query)
+  - [Use with React](#use-with-react)
+  - [Load the current user into a store](#load-the-current-user-into-a-store)
+  - [One /me per page view on the server](#one-me-per-page-view-on-the-server)
+  - [Retry a flaky backend within one deadline](#retry-a-flaky-backend-within-one-deadline)
+  - [Give each attempt its own timeout](#give-each-attempt-its-own-timeout)
+  - [Report errors to Sentry](#report-errors-to-sentry)
+  - [Upload and download files](#upload-and-download-files)
+- [Choosing liaise](#choosing-liaise)
+  - [When it fits, and when it doesn't](#when-it-fits-and-when-it-doesnt)
+  - [How it compares](#how-it-compares)
+  - [Where it runs](#where-it-runs)
+- [Design principles](#design-principles)
+- [Reference](#reference)
+  - [createApi options](#createapi-options)
+  - [createGraphQL options](#creategraphql-options)
+  - [Endpoint options](#endpoint-options)
+  - [Operation options](#operation-options)
+  - [CallOptions](#calloptions)
+  - [Result and ApiError](#result-and-apierror)
+  - [MiddlewareContext](#middlewarecontext)
+  - [Built-in middleware options](#built-in-middleware-options)
+  - [liaise/testing](#liaisetesting)
+  - [Exports](#exports)
+  - [Behaviour in detail](#behaviour-in-detail)
+- [Upgrading, contributing, licence](#upgrading-contributing-licence)
+
+## The problem it solves
+
+`fetch` is a good building block. Every project still ends up writing the same few things around it, and they are easy to get subtly wrong.
+
+| With plain fetch | liaise | See |
+| ---------------- | ------ | --- |
+| Typing fast in a search box shows old results. A slow early search lands last. | `dedupe` cancels the older call. | [Stale requests](#drop-stale-calls-with-dedupe) |
+| Five components load the same data, or five 401s each refresh the token. That's five identical requests. | `share` sends one and hands everyone the answer. | [Sharing identical requests](#sharing-identical-requests) |
+| A 500 counts as success, offline throws, a hung server waits forever. | Every call returns `{ data, error }`, and `error.kind` names the failure. With `timeout` set, a hung server becomes an error too. | [Handling errors](#handling-errors) |
+| Retries run straight past your timeout. | `timeout` covers the whole operation, retries included. | [Deadlines](#set-a-deadline-with-timeout) |
+| The backend changes a field and the page crashes three components later. | A schema checks the response. A bad shape is an error you handle. | [Validating responses](#validating-responses) |
+
+### Before and after
+
+Here is one form submit, written both ways. `show` stands for whatever puts a message on screen.
+
+**With plain fetch**
 
 ```ts
-import { createApi, Request } from 'liaise'
+try {
+  const res = await fetch('/api/orders', { method: 'POST', body: JSON.stringify(order) })
+  show(`Order ${(await res.json()).id} confirmed`) // a 500 lands here too
+} catch {
+  show('Something went wrong') // offline? broken JSON? no way to tell
+}
+```
+
+**With liaise**
+
+<!-- tested: problem-after -->
+```ts
+async function submit(order: { items: string[] }) {
+  const { data, error } = await api.placeOrder(order)
+  if (!error) return show(`Order ${data.id} confirmed`)
 
-// 1. Define your endpoints
-interface User {
-  id: string
-  name: string
-  email: string
+  switch (error.kind) {
+    case 'http':    return show(`The server said no (${error.status})`)
+    case 'network': return show("You're offline. We'll try again.")
+    case 'timeout': return show('This is taking too long. Try again.')
+    case 'parse':   return show('The server sent something unexpected.')
+  }
 }
+```
 
-const getUser = new Request<{ id: string }, User>({
-  method: 'GET',
-  path: '/users/:id'
-})
+`api.placeOrder` is an endpoint defined like the ones in [Quick start](#quick-start), with `timeout: 5000` so a hung server gives up after five seconds.
+
+The `switch` leaves out `'abort'`, because nothing here cancels a call, and `'middleware'`, which points at a bug in your own code ([all six kinds](#handling-errors)).
+
+### Why another API client?
+
+Without it, you have two options. You can hand-roll a wrapper around fetch, which means writing the same boilerplate on every project: a typed function per endpoint, status checks, error handling, retries, cancellation.
 
-const createUser = new Request<{ name: string; email: string }, User>({
+Or you can reach for a large library like Apollo or urql. They're built for very large apps with complex data needs. For most products, that's bringing a tank to a chess match, and you spend hours on setup and configuration for features you never use.
+
+liaise sits in between. It's the wrapper you'd otherwise hand-roll, already written and tested. Your whole setup is a base URL and your endpoints.
+
+**The API client you'd build on your third project, with the edge cases already handled.**
+
+## Quick start
+
+Define two endpoints, create a client, and make a call.
+
+<!-- tested: quick-start -->
+```ts
+import { createApi, defineRequest } from 'liaise'
+
+type User = { id: string; name: string; email: string }
+
+// 1. Describe your endpoints. The path decides which params are required.
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+const createUser = defineRequest<User, { name: string; email: string }>()({
   method: 'POST',
-  path: '/users'
+  path: '/users',
 })
 
-// 2. Create the client
+// 2. Create the client.
 const api = createApi({
   baseUrl: 'https://api.example.com',
   requests: { getUser, createUser },
-  onError: (error) => console.error(`${error.request.method} ${error.request.url}`, error.status)
 })
 
-// 3. Make a call — params and response are fully typed
-const { data, error, retry } = await api.getUser({ id: '42' })
+// 3. Call it. This never throws: you always get { data, error }.
+const { data, error } = await api.getUser({ id: '42' })
 
 if (error) {
-  console.error(error.status, error.body)
-  return
+  // error.kind says what went wrong: 'http', 'network', 'timeout', ...
+  console.error(error.kind, error.status)
+} else {
+  console.log(data.name) // data is a User here
 }
+```
+
+### What you just got
+
+- The params are checked against the path, so `getUser({ userId: '42' })` is a compile error.
+- `data` is typed from `defineRequest<User>`.
+- Nothing throws, not even when you're offline.
+- Checking `error` first narrows `data` to `User`, so you never write `data!`.
+
+### Next
+
+- [Handling errors](#handling-errors)
+- [Add an auth header and refresh the token on a 401](#add-an-auth-header-and-refresh-the-token-on-a-401)
+- [Use with TanStack Query](#use-with-tanstack-query)
+- [Use with React](#use-with-react)
+
+## How it fits together
 
-// data is typed as User
-console.log(data.name)
+liaise has four pieces, and every call takes the same path through them. Middleware is a function that wraps a call, so it can add a header, retry or log.
+
+### Four pieces
+
+| Piece | What it is |
+| ----- | ---------- |
+| Endpoint definition (`defineRequest`) | A recipe for one endpoint: its method, its path and the types of its params and response. It does nothing on its own. |
+| Client (`createApi`) | Turns your recipes into typed functions, one per endpoint. |
+| Call | `api.getUser(params, options)`, where `options` can set `signal`, `timeout`, `headers` or `middleware` for this call only. |
+| `Result` | `{ data, error, response, retry }`, which is what every call returns. `data` and `error` are never both set. `retry()` runs the same call again. |
+
+Types flow from the endpoint definition through `createApi` to every call, so you never annotate a call. When you need a type by name, it is listed under [Exports](#exports).
+
+### The path of one call
+
+```text
+params → URL + body → your middleware → fetch → parse → validate → Result
 ```
 
-## REST API
+Any step can fail, and the failure lands in `error` instead of being thrown.
+
+### Three levels of settings
 
-### Request
+You can write a setting in three places: on the client, on the endpoint, or on one call. For headers, the most specific one wins. For middleware, every level runs, the client's first.
 
-Each API endpoint is represented by a `Request` instance. The class is a typed config container -- it stores the recipe for how an endpoint should be called, but does not execute anything on its own.
+| Level | Where you write it | `headers` | `middleware` |
+| ----- | ------------------ | --------- | ------------ |
+| Client | `createApi({ headers, middleware })` | Sent with every call | Runs first, around everything else |
+| Endpoint | `defineRequest<T>()({ headers, middleware })` | Replaces the client's value for the same header | Runs second |
+| Call | `api.getUser(params, { headers, middleware })` | Replaces the client's and the endpoint's value for the same header | Runs last, closest to `fetch` |
+
+Headers merge by name, so setting one header on a call keeps every other header from the client and the endpoint. A `Content-Type` you set at any level replaces the one liaise picks from the body.
 
 ```ts
-import { Request } from 'liaise'
+import { createApi, defineRequest } from 'liaise'
 
-const listItems = new Request<{ page: number; limit: number }, Item[]>({
-  method: 'GET',
-  path: '/items'
+type Report = { total: number }
+
+const api = createApi({
+  baseUrl: 'https://api.example.com',
+  headers: { 'x-api-version': '1' }, // every call
+  requests: {
+    getReport: defineRequest<Report>()({
+      method: 'GET',
+      path: '/report',
+      headers: { 'x-api-version': '2' }, // this endpoint: replaces the client's
+    }),
+  },
 })
+
+await api.getReport() // sends x-api-version: 2
+await api.getReport({}, { headers: { 'x-api-version': '3' } }) // sends x-api-version: 3
 ```
 
-The two type parameters drive the entire type system:
+## Guide
 
-- `TParams` -- the shape of the params object the caller must provide (path params, query params, and body params combined).
-- `TResponse` -- the shape of the successful response data. This becomes the type of `result.data`.
+Each section starts with the problem it solves, then shows the smallest example, then lists the rules.
 
-When an endpoint takes no params, use `Record<string, never>` and the generated method will accept an optional (or omitted) params argument:
+### Defining endpoints
+
+You describe each endpoint once, with its method, its path, and the types of its params and response. Every call to it is then checked against that description.
 
 ```ts
-const health = new Request<Record<string, never>, { status: string }>({
+import { createApi, defineRequest } from 'liaise'
+
+type Repo = { id: number; name: string }
+
+// The first type is the response. The second is the params the path doesn't name.
+const listRepos = defineRequest<Repo[], { page?: number }>()({
   method: 'GET',
-  path: '/health'
+  path: '/orgs/:org/repos',
 })
 
-// Both work:
-await api.health()
-await api.health({})
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { listRepos } })
+
+await api.listRepos({ org: 'acme' })           // GET /orgs/acme/repos
+await api.listRepos({ org: 'acme', page: 2 })  // GET /orgs/acme/repos?page=2
+await api.listRepos({ page: 2 })               // ✗ compile error: org is required
 ```
 
-#### Path parameters
+- **The path names the required params.** Each `:name` in the path becomes a required param of type `string | number`. Its value is filled into the URL and left out of the query string and the body.
+- **Every other param goes in the second type argument.** For `GET` and `DELETE`, these params go in the query string. For `POST`, `PUT` and `PATCH`, they go in a JSON body. [Sending data](#sending-data) covers what each one can hold.
+- **`bodyAs` flips that default.** Use it for an API that does it the other way round:
+
+  ```ts
+  type Job = { id: string }
+
+  // A DELETE that takes a JSON body
+  const bulkDelete = defineRequest<{ deleted: number }, { ids: string[] }>()({
+    method: 'DELETE',
+    path: '/items',
+    bodyAs: 'body',
+  })
 
-Use `:param` syntax in the path. Matching keys from the params object are substituted into the URL and excluded from the query string or body:
+  // A POST that sends its params in the query string
+  const triggerJob = defineRequest<Job, { priority: number }>()({
+    method: 'POST',
+    path: '/jobs/trigger',
+    bodyAs: 'query',
+  })
+  ```
+
+- **A path param must have a usable value.** It must be a non-empty string, a finite number, a bigint or a boolean. `undefined`, `null`, `''`, an object, an array, a `Date` and `NaN` are refused before anything is sent, with an error naming the param.
+- That catches the most common mistake, which is calling before an id has loaded. An `org` that is still `undefined` at runtime returns an error instead of fetching `/orgs/undefined/repos`.
+- **An endpoint with no params** is called with no arguments. With `defineRequest<{ status: string }>()({ method: 'GET', path: '/health' })`, both `api.health()` and `api.health({})` work.
+- **`responseType`** says how to read the response body. It defaults to `'json'`. The options are under [Reading responses](#reading-responses).
+- **`responseType: 'none'` needs the response type `undefined`.** Anything else is a compile error, because `data` is always `undefined` for an endpoint that sends no body:
+
+  ```ts
+  defineRequest<undefined>()({ method: 'POST', path: '/ping', responseType: 'none' })  // ✓
+  defineRequest<Repo>()({ method: 'POST', path: '/ping', responseType: 'none' })       // ✗
+  ```
+
+- **A `#` in the path is a compile error.** A URL fragment is never sent to the server, so `path: '/docs#section'` is refused where you write it. [URL fragments](#url-fragments) has the details.
+
+**Why two calls.** `defineRequest<Repo[]>()({ ... })` is two calls because TypeScript can't infer some type arguments while you write others. The first call takes the response type you write, and the second infers the params from the path. In a single call, writing the response type would quietly turn the path checking off.
+
+#### Without defineRequest
+
+`new Request<TParams, TResponse>(config)` is the class that `defineRequest` builds. You write the params type yourself, covering path, query and body params together, and nothing checks it against the path:
 
 ```ts
-const getItem = new Request<{ orgId: string; id: string }, Item>({
-  method: 'GET',
-  path: '/orgs/:orgId/items/:id'
-})
+import { createApi, Request } from 'liaise'
+
+type User = { id: string; name: string }
+
+const getUser = new Request<{ userId: string }, User>({ method: 'GET', path: '/users/:id' })
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getUser } })
 
-// Calls GET /orgs/acme/items/42
-await api.getItem({ orgId: 'acme', id: '42' })
+await api.getUser({ userId: '42' })
+// Compiles. The call then returns an error, because the path has no :userId and :id is never filled in.
 ```
 
-#### `responseType`
+Use `new Request` when the config isn't a literal, for example when you build it at runtime, or when you don't want the path checked. It is not deprecated. For an endpoint with no params, write `Record<string, never>` as `TParams`.
 
-Controls how the response body is parsed. Defaults to `'json'`.
+### Handling errors
+
+Plain fetch reports failures three different ways. A 500 resolves like a success, being offline throws, and a hung server never answers. In liaise every call returns `{ data, error }`, and `error.kind` names what went wrong.
 
 ```ts
-const downloadFile = new Request<{ id: string }, Blob>({
-  method: 'GET',
-  path: '/files/:id',
-  responseType: 'blob'
-})
+import { createApi, defineRequest } from 'liaise'
+
+type User = { id: string; name: string }
+
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id', timeout: 5000 })
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getUser } })
+
+async function loadUser(id: string) {
+  const { data, error } = await api.getUser({ id })
+
+  if (error) {
+    switch (error.kind) {
+      case 'http':       // the server answered with a non-2xx status
+        if (error.status === 401) redirectToLogin()
+        else show(`The server said no (${error.status})`)
+        break
+      case 'network':    // no response arrived
+        show("You're offline. Try again.")
+        break
+      case 'timeout':    // the 5 second deadline passed
+        show('This is taking too long.')
+        break
+      case 'abort':      // you cancelled the call, so there is nothing to show
+        break
+      case 'parse':      // a 2xx body that didn't parse or failed the schema
+      case 'middleware': // your own middleware threw
+        report(error)
+        break
+    }
+    return
+  }
+
+  show(`Hello, ${data.name}`) // data is a User here
+}
 ```
 
-See [Response parsing](#response-parsing) for all options.
+`show`, `redirectToLogin` and `report` stand for your own code.
 
-#### `dedupe`
+| `kind` | What happened | `status` | What you usually do | Reported to [`onError`](#reporting-errors-with-onerror)? |
+| ------ | ------------- | -------- | ------------------- | ---------------------- |
+| `'http'` | The server answered with a non-2xx status. | The response's status | Handle it by status, or show it | Yes |
+| `'network'` | No response arrived, because you're offline or DNS or CORS failed. Params liaise refuses before sending also land here. | `0` | Show an offline message, or retry | Yes |
+| `'timeout'` | Your [`timeout`](#set-a-deadline-with-timeout) passed. | `0` | Say it's slow | Yes |
+| `'abort'` | The call was cancelled by your signal, or replaced by a newer [`dedupe`](#drop-stale-calls-with-dedupe) call. | `0` | Ignore it | **No** |
+| `'parse'` | A 2xx body didn't parse as its `responseType`, or failed your [schema](#validating-responses). | The response's status | Report it | Yes |
+| `'middleware'` | Your middleware threw. | `0` | Fix your code | Yes |
 
-When `true`, firing a new call to this endpoint auto-cancels any previous in-flight call. Useful for search-as-you-type or rapidly changing filters:
+- **Check `error` first.** After `if (error) return`, `data` has your response type, so you never write `data!`.
+- For an endpoint that sends no body, declare `responseType: 'none'`. Widening the type to `| null` doesn't work, because an empty body is a `'parse'` error. See [Reading responses](#reading-responses).
+- **Branch on `error.kind`.** Four kinds share `status: 0`, and each needs different handling.
+- **A non-2xx response is always `'http'`**, even when its body doesn't parse. liaise checks the status before it reads the body, so a 500 with broken JSON is still a 500, and [`retryMiddleware`](#retry-failed-calls) still retries it.
+- **`response` is for the status and headers.** liaise has already read its body to produce `data` or `error.body`, so `response.json()` throws "Body has already been read". A `Response` you build yourself for `successResult()` in tests keeps its body.
+- Every field of `error` is listed under [`ApiError`](#result-and-apierror).
+
+#### Trying again with retry()
+
+Every `Result` carries `retry()`, which runs the same call again. It goes through all your middleware, so an auth header is set again and logging runs again:
 
 ```ts
-const searchUsers = new Request<{ q: string }, User[]>({
-  method: 'GET',
-  path: '/users/search',
-  dedupe: true
-})
+const { error, retry } = await api.getUser({ id: '42' })
 
-// If a second call starts before the first finishes, the first is aborted
-await api.searchUsers({ q: 'hel' })
-await api.searchUsers({ q: 'hello' }) // previous call is auto-cancelled
+if (error?.status === 401) {
+  await refreshToken()
+  const second = await retry() // a fresh call through every middleware
+  if (!second.error) show(second.data.name)
+}
 ```
 
-#### `share`
+`refreshToken` stands for your own token refresh.
 
-When `true`, identical concurrent calls to this endpoint join a single in-flight request instead of firing their own. See [Sharing](#sharing) for the full contract — including its mutual exclusion with `dedupe` and what disables it.
+#### Reporting errors with onError
+
+`onError` on `createApi` is one place to send every error to your tracker.
 
 ```ts
-const getProduct = new Request<{ id: string }, Product>({
-  method: 'GET',
-  path: '/products/:id',
-  share: true
+const api = createApi({
+  baseUrl: 'https://api.example.com',
+  requests: { getUser },
+  onError: (error) => logToTracker(error),
 })
-
-// Both calls join the same network request
-await Promise.all([
-  api.getProduct({ id: '42' }),
-  api.getProduct({ id: '42' })
-])
 ```
 
-#### `bodyAs`
+`logToTracker` stands for your error tracker, such as Sentry.
+
+- It runs once per call, after all your middleware has finished. A call that a retry middleware rescues from a 500 never reaches it.
+- It isn't called for `'abort'`, because a cancellation isn't a failure. A `'timeout'` is reported, because it's a deadline you missed.
+- It only watches. The caller gets the same `Result` either way.
 
-Overrides the default body serialization strategy. By default, GET/DELETE serialize params as query strings and POST/PUT/PATCH serialize params as a JSON body. Use `bodyAs` to invert that:
+### Sending data
+
+You pass one params object, and liaise puts each field where it belongs: in the path, the query string or the body. You never build a URL by hand.
 
 ```ts
-// DELETE endpoint that expects a JSON body
-const bulkDelete = new Request<{ ids: string[] }, { deleted: number }>({
-  method: 'DELETE',
-  path: '/items',
-  bodyAs: 'body'
-})
+import { createApi, defineRequest } from 'liaise'
 
-// POST endpoint that sends params as query string
-const triggerJob = new Request<{ priority: number }, Job>({
+type Item = { id: string; name: string }
+
+const listItems = defineRequest<Item[], { page: number; tags: string[] }>()({
+  method: 'GET',
+  path: '/orgs/:org/items',
+})
+const createItem = defineRequest<Item, { name: string }>()({
   method: 'POST',
-  path: '/jobs/trigger',
-  bodyAs: 'query'
+  path: '/orgs/:org/items',
 })
+
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { listItems, createItem } })
+
+await api.listItems({ org: 'acme', page: 2, tags: ['a', 'b'] })
+// GET /orgs/acme/items?page=2&tags=a&tags=b
+
+await api.createItem({ org: 'acme', name: 'Lamp' })
+// POST /orgs/acme/items, with the JSON body {"name":"Lamp"}
 ```
 
-### `defineRequest`
+Which params go in the query string and which in the body is set per endpoint, under [Defining endpoints](#defining-endpoints).
 
-`new Request<TParams, TResponse>` makes you restate what the path already says,
-and nothing checks the two against each other:
+#### Query strings
 
-```ts
-// The params are restated by hand, and nothing checks them against the path:
-const getUser = new Request<{ userId: string }, User>({ method: 'GET', path: '/users/:id' })
+| Params | Query string |
+| ------ | ------------ |
+| `{ page: 1, limit: 20 }` | `?page=1&limit=20` |
+| `{ tags: ['a', 'b'] }` | `?tags=a&tags=b` |
+| `{ filter: null }` | _(left out)_ |
+| `{ filter: undefined }` | _(left out)_ |
+| `{ meta: { nested: true } }` | Refused |
+| `{ since: new Date() }` | Refused |
 
-api.getUser({ userId: '42' })  // compiles — then fails at runtime: buildUrl finds
-                               // no `:userId` to substitute, `:id` survives, and
-                               // the unresolved-token check throws
-```
+- **Arrays** become repeated keys (`tags=a&tags=b`), the format most server frameworks read.
+- **`null` and `undefined`** are left out.
+- **A nested object is refused.** There is no standard way to put one in a query string (brackets, dots and JSON are all in use), so liaise doesn't guess. Flatten it first.
+- **A `Date` is refused too.** APIs expect ISO 8601 or epoch milliseconds, so convert it yourself with `date.toISOString()` or `date.getTime()`.
+- A refused param sends nothing. You get an error `Result` with `kind: 'network'` and a `TypeError` in `error.body` that names the param.
 
-`defineRequest` infers the params from the path literal instead:
+#### Request bodies
 
-```ts
-import { defineRequest } from 'liaise'
+liaise serializes the body from what you pass, and sets `Content-Type` for you unless you set one yourself.
 
-const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+| You pass | Body sent | Content-Type |
+| -------- | --------- | ------------ |
+| `null`/`undefined` | `null` | _(none)_ |
+| `string` | as-is | `text/plain` |
+| `FormData` | as-is | _(the browser sets the multipart boundary)_ |
+| `URLSearchParams` | as-is | `application/x-www-form-urlencoded` |
+| `Blob` | as-is | `application/octet-stream` |
+| `ArrayBuffer` | as-is | `application/octet-stream` |
+| Typed array, `DataView`, `Buffer` | as-is (sent as binary) | `application/octet-stream` |
+| `ReadableStream` | as-is (a streaming upload; `duplex: 'half'` is set for you) | `application/octet-stream` |
+| Plain object | `JSON.stringify()` | `application/json` |
 
-api.getUser({ id: '42' })      // ✓
-api.getUser({ id: 42 })        // ✓ — numbers are encoded
-api.getUser({ userId: '42' })  // ✗ Object literal may only specify known properties
-```
+A `ReadableStream` body can be sent only once. A retry, from middleware or from `result.retry()`, returns an error telling you to read the stream into a `Blob` or `ArrayBuffer` first ([details](#stream-bodies)).
+
+#### What params can be
 
-Params the path does not name — query or body fields — go in the second type
-argument:
+| You pass | What happens |
+| -------- | ------------ |
+| Plain object | Split into path params, query string and body |
+| `Map` with string keys | Same as the object it spells |
+| Class instance with fields | Same as a plain object (split by those fields even if the class also defines `toJSON()`; `toJSON()` is used only when there are no own fields) |
+| Class instance with only `toJSON()` | Sent as its JSON (body only; refused on a request whose params go in the query string) |
+| Typed array, `DataView`, `Buffer`, `ReadableStream` | Sent as the body, as in the table above (refused on a request whose params go in the query string) |
+| `Set`, a bare `Date`, a `Map` with non-string keys, a class with no fields | Refused: an error `Result` (`kind: 'network'`) naming the type. Nothing is sent. |
 
-```ts
-const listRepos = defineRequest<Repo[], { page?: number }>()({
-  method: 'GET',
-  path: '/orgs/:org/repos',
-})
+A `Map`, `Set` or class with private state nested inside a JSON body is sent as `{}`, because that is what `JSON.stringify` does. Convert it first.
 
-api.listRepos({ org: 'acme' })            // ✓ page is optional
-api.listRepos({ org: 'acme', page: 2 })   // ✓
-api.listRepos({ page: 2 })                // ✗ org is required
-```
+Headers, including your own `Content-Type`, follow the [three levels of settings](#three-levels-of-settings).
+
+### Reading responses
 
-It also enforces the `responseType: 'none'` convention that `new Request` can
-only document:
+A response can be JSON, text or a file. You say which with `responseType`, and liaise reads the body for you.
 
 ```ts
-defineRequest<undefined>()({ method: 'POST', path: '/ping', responseType: 'none' })  // ✓
-defineRequest<User>()({ method: 'POST', path: '/ping', responseType: 'none' })       // ✗
-```
+import { createApi, defineRequest } from 'liaise'
+
+type User = { id: string; name: string }
 
-**Why two calls.** TypeScript has no partial type-argument inference: if the response
-type and the config were arguments to one call, supplying the response type explicitly
-would stop the path from being inferred, and the checking would quietly do nothing.
-Splitting them keeps the response type explicit and the path inferred. Calling it
-wrong is a compile error, not a silent one.
+// JSON is the default.
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+
+// A file comes back as a Blob.
+const downloadFile = defineRequest<Blob>()({ method: 'GET', path: '/files/:id', responseType: 'blob' })
+
+// A 204 No Content has no body, so data is undefined.
+const deleteUser = defineRequest<undefined>()({
+  method: 'DELETE',
+  path: '/users/:id',
+  responseType: 'none',
+})
+
+const api = createApi({
+  baseUrl: 'https://api.example.com',
+  requests: { getUser, downloadFile, deleteUser },
+})
+```
 
-`new Request(...)` is unchanged and not deprecated — use it when the config is
-not a literal, or when you do not want the path checked.
+| `responseType` | How the body is read | `data` |
+| -------------- | -------------------- | ------ |
+| `'json'` (default) | `response.text()`, then `JSON.parse()` | the parsed value |
+| `'text'` | `response.text()` | `string` |
+| `'blob'` | `response.blob()` | `Blob` |
+| `'arrayBuffer'` | `response.arrayBuffer()` | `ArrayBuffer` |
+| `'formData'` | `response.formData()` | `FormData` |
+| `'none'` | not read (the stream is cancelled) | `undefined` |
+
+- **An empty body under `'json'` is a `'parse'` error.** You declared JSON and the server sent none, so no value could honestly match your type. The error has the response's own status (a 204 reports 204), the `response`, and `''` in `error.body`.
+- **A literal `null` body is not empty.** It is valid JSON, so the call succeeds with `data: null`.
+- **`'none'` is for an endpoint that sends no body on success**, such as a `DELETE` that answers 204, or 200 with an empty body. liaise reads nothing, `data` is `undefined`, and a body the server sends anyway is discarded. Its stream is cancelled, which frees the connection.
+- **Declare `'none'` with the response type `undefined`.** `defineRequest` enforces this ([Defining endpoints](#defining-endpoints)). [Without defineRequest](#without-definerequest) it is only a convention, and `data` is `undefined` at runtime whatever type you wrote.
+- **A non-2xx body is still read into `error.body`**, because an error body usually explains what went wrong. Under `'none'` it is read as JSON, and `error.body` is `null` when it isn't JSON:
+
+  ```ts
+  const { error } = await api.deleteUser({ id: '42' })
+  if (error) {
+    // A 409 { "error": "already deleted" } lands in error.body,
+    // even though deleteUser declares responseType: 'none'.
+    console.error(error.status, error.body)
+  }
+  ```
 
-### Response validation
+### Validating responses
 
-Pass any [Standard Schema](https://standardschema.dev) validator — Zod, Valibot,
-ArkType — and the response is checked before you see it. liaise takes no
-dependency on one; Standard Schema is an interface, not a package.
+TypeScript trusts the type you write, and nothing checks it at runtime. When the backend changes a field, the page crashes three components later. Give the endpoint a schema, and the response is checked before you see it.
 
 ```ts
+import { createApi, defineRequest } from 'liaise'
 import { z } from 'zod'
 
 const getUser = defineRequest()({
@@ -275,452 +543,401 @@ const getUser = defineRequest()({
   schema: z.object({ id: z.string(), name: z.string() }),
 })
 
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getUser } })
+
 const { data, error } = await api.getUser({ id: '42' })
 //      ^? { id: string; name: string } | null
 ```
 
-The schema supplies the response type, so there is no type argument to write —
-and no second place for it to drift out of date.
-
-**`data` is the schema's output.** A schema that transforms changes what you
-receive:
+Valibot and ArkType work the same way:
 
 ```ts
-const getUser = defineRequest()({
+import * as v from 'valibot'
+import { type } from 'arktype'
+
+const withValibot = defineRequest()({
   method: 'GET',
   path: '/users/:id',
-  schema: z.object({
-    id: z.string(),
-    createdAt: z.coerce.date(),        // the wire sends a string
-    role: z.string().default('user'),  // absent on the wire
-  }),
+  schema: v.object({ id: v.string(), name: v.string() }),
 })
 
-const { data } = await api.getUser({ id: '42' })
-data.createdAt   // a real Date
-data.role        // 'user' when the server omitted it
+const withArkType = defineRequest()({
+  method: 'GET',
+  path: '/users/:id',
+  schema: type({ id: 'string', name: 'string' }),
+})
 ```
 
-That is the point of validating through a schema rather than merely checking
-one — but it does mean `data` is no longer byte-identical to the response.
+- **Any [Standard Schema](https://standardschema.dev) validator works.** liaise doesn't depend on any of them. Standard Schema is only an interface, so you bring the validator you already use.
+- **The schema supplies the response type.** You write no type argument, so there's no second type to keep in sync.
+- **`data` is the schema's output.** A schema that transforms changes what you receive, so `data` can differ from the raw response:
 
-A response the schema refuses is an error `Result`, never a throw:
+  ```ts
+  const getUser = defineRequest()({
+    method: 'GET',
+    path: '/users/:id',
+    schema: z.object({
+      id: z.string(),
+      createdAt: z.coerce.date(),        // the wire sends a string
+      role: z.string().default('user'),  // absent on the wire
+    }),
+  })
 
-```ts
-const { error } = await api.getUser({ id: '42' })
-if (error?.kind === 'parse') {
-  console.error(error.body)  // the validator's issues
-  error.status               // the response's own status — the server was fine
-}
-```
+  const { data } = await api.getUser({ id: '42' })
+  data.createdAt   // a real Date
+  data.role        // 'user' when the server left it out
+  ```
 
-Only the **success** body is validated. A non-2xx body is diagnostic and often a
-different shape, so it is left alone.
+- **A response the schema refuses is a `'parse'` error.** Nothing is thrown. `error.body` holds the validator's issues, and `error.status` is the response's own status, since the server answered fine:
 
-Schemas work on the GraphQL client too, validating the response's `data`:
+  ```ts
+  const { error } = await api.getUser({ id: '42' })
+  if (error?.kind === 'parse') {
+    console.error(error.body)  // the validator's issues
+  }
+  ```
 
-```ts
-const me = new Operation<{}, User>({
-  operation: gql`query { me { id name } }`,
-  schema: UserSchema,
-})
-```
+- A validator that throws is a `'parse'` error too, with the thrown value in `error.body`.
+- **Only a 2xx body is validated.** A non-2xx body is diagnostic and often a different shape, so it is left alone.
+- **The GraphQL `Operation` ([GraphQL](#graphql)) takes `schema` too**, and validates the response's `data`. There the response type stays explicit, because only `defineRequest` infers it:
 
-There the response type stays explicit — only `defineRequest` infers it.
+  ```ts
+  import { Operation, gql } from 'liaise'
 
-### Pagination
+  const UserSchema = z.object({ id: z.string(), name: z.string() })
 
-`paginate` walks a paginated endpoint, yielding one `Result` per page:
+  const me = new Operation<Record<string, never>, z.infer<typeof UserSchema>>({
+    operation: gql`query { me { id name } }`,
+    schema: UserSchema,
+  })
+  ```
 
-```ts
-import { paginate } from 'liaise'
+### Cancelling, deadlines and stale requests
 
-for await (const page of paginate(api.listItems, { limit: 50 }, {
-  next: (p, prev) => p.data.cursor ? { ...prev, cursor: p.data.cursor } : undefined,
-})) {
-  if (page.error) break
-  render(page.data.items)
-}
-```
+Sometimes you no longer need a call, because the user left the page or typed a newer search. Sometimes a call takes too long. You can end a call with a signal, a deadline, or `dedupe`, and each one ends it with an error you can tell apart.
+
+#### Cancel with a signal
 
-**`next` returns the next params, not a cursor.** That is what keeps this
-library out of the business of guessing where a cursor goes — `cursor`?
-`page_token`? `after`? The previous params arrive as the second argument, so
-the common case is a spread, and the same shape covers every scheme:
+Pass an `AbortSignal` in the call options:
 
 ```ts
-// offset
-next: (p, prev) => p.data.items.length === prev.limit
-  ? { ...prev, offset: prev.offset + prev.limit }
-  : undefined
-
-// page number, driven by a Link header
-next: (p, prev) => p.response.headers.get('link')?.includes('rel="next"')
-  ? { ...prev, page: prev.page + 1 }
-  : undefined
-```
+import { createApi, defineRequest } from 'liaise'
+
+type User = { id: string; name: string }
 
-Return `undefined` or `null` to stop.
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getUser } })
 
-**An error page is yielded, then the walk ends.** There is no data to read the
-next cursor from, so there is nothing to continue with — and you see what
-failed rather than a loop that quietly stopped.
+const controller = new AbortController()
+const pending = api.getUser({ id: '42' }, { signal: controller.signal })
 
-**`maxPages` is optional and has no default.** A ceiling exists if you want one;
-the library will not invent a number, because a silent truncation at an
-arbitrary limit looks exactly like reaching the last page.
+controller.abort()
 
-```ts
-paginate(api.listItems, { limit: 50 }, { next, maxPages: 100 })
+const { error } = await pending
+// error.kind === 'abort', error.status === 0, error.body is a DOMException named 'AbortError'
 ```
 
-Any other [`CallOptions`](#calloptions) — `signal`, `timeout`, `headers` — apply
-to every request, so one signal cancels the whole crawl.
+A cancellation you asked for isn't reported to [`onError`](#reporting-errors-with-onerror). How liaise tells your cancellation apart from other failures is under [Abort classification](#abort-classification).
 
-`paginate` yields pages, not items. Flattening would mean deciding which field
-holds the array, which is the convention-guessing `next` exists to avoid.
+#### Set a deadline with timeout
 
-### Query strings
+`timeout` is in milliseconds, and you set it on the endpoint or on one call:
 
-For GET and DELETE requests (or any request with `bodyAs: 'query'`), params that are not consumed by path substitution are serialized as a query string using `URLSearchParams`.
+```ts
+import { createApi, defineRequest } from 'liaise'
+import { retryMiddleware } from 'liaise/middleware'
 
-A `baseUrl` may carry its own query string — a fixed API key, say. Its params
-are merged ahead of the call's:
+type Report = { total: number }
+
+const getReport = defineRequest<Report>()({ method: 'GET', path: '/report', timeout: 3000 })
 
-```ts
 const api = createApi({
-  baseUrl: 'https://api.example.com/v1?key=abc',
-  requests: { search: new Request<{ q: string }, Hit[]>({ method: 'GET', path: '/search' }) },
+  baseUrl: 'https://api.example.com',
+  requests: { getReport },
+  middleware: [retryMiddleware(3)],
 })
 
-await api.search({ q: 'hello' })
-// GET https://api.example.com/v1/search?key=abc&q=hello
+const { error } = await api.getReport()
+// If no answer arrives within 3 seconds, retries included: error.kind === 'timeout', error.status === 0
 ```
 
-Merging **accumulates**, it does not override: a call param whose key the base
-already used produces both, `?key=abc&key=xyz`, and which one wins is the
-server's decision. This differs from headers, where a per-call value replaces a
-global one — because array params already serialize as repeated keys
-(`tags=a&tags=b`), so collapsing duplicates would break them. If a base-level
-param needs to vary per call, set it from middleware rather than the `baseUrl`.
+- **`timeout` is one deadline for the whole call.** It covers every middleware, every retry and every wait between retries. `timeout: 3000` with three retries still answers within three seconds.
+- **A call's `timeout` replaces the endpoint's.** `timeout: 0` on a call turns the endpoint's deadline off. Zero, a negative number or no `timeout` at all means no deadline, which is the default.
+- **`result.retry()` starts a fresh deadline.** The retried call isn't charged for time the first one used.
+- If you want a separate limit for each attempt instead, see [Give each attempt its own timeout](#give-each-attempt-its-own-timeout).
+- Under [`share`](#sharing-identical-requests), the endpoint's `timeout` belongs to the one shared request, and a caller can't extend it.
 
-**A `#fragment` is refused.** A fragment is never sent to the server, so one in
-a `path` or `baseUrl` cannot do what it appears to — and before 4.2.1 it
-silently discarded the query string. It is now an error naming the offending
-value, rather than being stripped, so the dead code does not stay in your
-template.
+#### Drop stale calls with dedupe
 
-Since 4.4.0 a fragment in a [`defineRequest`](#definerequest) `path` **literal**
-is also a compile error, so the endpoint is rejected where it is declared rather
-than on every call:
+`dedupe: true` makes each new call to an endpoint cancel the one still running. Use it for search-as-you-type and fast-changing filters, where only the latest answer matters:
 
 ```ts
-defineRequest<Doc>()({ method: 'GET', path: '/docs#section' })
-//                                          ^ Property '__fragmentInPath' is missing:
-//                                            a URL fragment is never sent to the server
-```
+type User = { id: string; name: string }
 
-The check reads the literal, so a path assembled at runtime — or a
-`RequestConfig`-typed variable — still compiles and is caught by the runtime
-error instead. `new Request` takes no path literal, so it has no equivalent
-check; this is one of the things `defineRequest` buys you.
+const searchUsers = defineRequest<User[], { q: string }>()({
+  method: 'GET',
+  path: '/users/search',
+  dedupe: true,
+})
 
-**A `#` inside a param *value* is not a fragment** and is never refused — it is
-escaped to `%23` and sent as ordinary data:
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { searchUsers } })
 
-```ts
-await api.getDoc({ id: 'a#b' })   // → GET /docs/a%23b
-await api.search({ tag: 'a#b' })  // → GET /search?tag=a%23b
+// Typing fast: each call cancels the one before it.
+api.searchUsers({ q: 'h' })    // ends with kind 'abort'
+api.searchUsers({ q: 'he' })   // ends with kind 'abort'
+api.searchUsers({ q: 'hel' })  // this one completes
 ```
 
-Only a `#` written into a `path` or `baseUrl` is refused, because that one was
-never going to reach the server.
-
-| Input                          | Output                      |
-| ------------------------------ | --------------------------- |
-| `{ page: 1, limit: 20 }`      | `?page=1&limit=20`          |
-| `{ tags: ['a', 'b'] }`        | `?tags=a&tags=b`            |
-| `{ filter: null }`            | _(omitted)_                 |
-| `{ filter: undefined }`       | _(omitted)_                 |
-| `{ meta: { nested: true } }`  | **TypeError** (see below)   |
-| `{ since: new Date() }`       | **TypeError**: convert it first (`toISOString()` or `getTime()`) |
-
-**Arrays** use repeated keys (`tags=a&tags=b`), which is the most widely supported format across server frameworks.
+- **It works per endpoint.** A call to one endpoint never cancels a call to another.
+- **A replaced call ends with `kind: 'abort'`**, so your code can ignore it.
+- **It works together with your own signal and a `timeout`.** Whichever fires first ends the call.
+- It can't be combined with [`share`](#sharing-identical-requests), which does the opposite.
 
-**`null` and `undefined`** values are silently omitted from the query string.
+All three still end the call when a middleware is stuck on work of its own that ignores the signal, such as a token refresh that never settles. [Timeout backstop](#timeout-backstop) explains how.
 
-**Nested objects** throw a `TypeError` with a descriptive message. Flatten the structure before passing. This is intentional -- there is no universal standard for serializing nested objects in query strings (brackets, dots, JSON), so the library refuses to guess.
+### Sharing identical requests
 
-**A `Date`** is refused too, with a message that names it. ISO 8601 and epoch milliseconds are both common on real APIs, so convert it yourself: `since: date.toISOString()` or `since: date.getTime()`.
+Several parts of an app often ask for the same thing at the same moment. Five components load the current user, or five calls get a 401 and each one refreshes the token. `share: true` sends one request and gives every caller its answer.
 
-### Result
+```ts
+import { createApi, defineRequest } from 'liaise'
 
-Every API call returns a `Result<TResponse>` instead of throwing. It's a discriminated union on `error`, not a plain interface:
+type Product = { id: string; name: string }
 
-```ts
-interface SuccessResult<TResponse> {
-  data: TResponse                          // parsed response
-  error: null
-  response: Response                       // always present on success
-  retry: () => Promise<Result<TResponse>>
-}
+const getProduct = defineRequest<Product>()({
+  method: 'GET',
+  path: '/products/:id',
+  share: true,
+})
 
-interface ErrorResult<TResponse> {
-  data: null
-  error: ApiError                          // structured error, see below
-  response: Response | null                // present for HTTP/parse failures, null for network/abort/timeout
-  retry: () => Promise<Result<TResponse>>
-}
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getProduct } })
 
-type Result<TResponse> = SuccessResult<TResponse> | ErrorResult<TResponse>
+// One network request. Both callers get the same response.
+const [a, b] = await Promise.all([
+  api.getProduct({ id: '42' }),
+  api.getProduct({ id: '42' }),
+])
 ```
 
-Check `error` first, then use `data` with confidence: `if (error) return` (or any other narrowing check on `error`) narrows `data` to `TResponse` for the rest of the function -- no `data!` assertion needed. That narrowing is only as accurate as `TResponse` itself, though: an endpoint that answers `204` or an empty `200` (a `DELETE`, most commonly) doesn't return a body at all -- declare it with `responseType: 'none'` and `TResponse` of `undefined`, rather than widening `TResponse` to `| null`, which since 4.0.0 does not work
-at all -- an empty body under `'json'` is a `'parse'` error -- see [Response parsing](#response-parsing) below. Branch on `error.kind` rather than `error.status` — `'network'`, `'abort'` and `'timeout'` all carry `status: 0`, but they call for different handling:
+- **`share` joins the call already running. [`dedupe`](#drop-stale-calls-with-dedupe) cancels it.** Setting both on one endpoint throws when you create the client, so you find the mistake straight away.
+- **Identical means the same endpoint and the same params, compared by content.** Key order doesn't matter, and two `Date`s with the same time match. Different params or a different endpoint never share. [Share key and refcount](#share-key-and-refcount) has the full rules.
+- **A per-call `headers` or `middleware` turns sharing off for that call.** Either one can change what is requested, so that call gets a request of its own.
+- **Params that can't be compared safely, such as a `Blob` or a circular structure, turn sharing off** ([full list](#share-key-and-refcount)). That call gets its own request.
+- **A `Date`, `Map`, `Set`, typed array or string param shares normally.**
+- **A per-call `signal` or `timeout` only lets that caller leave.** The caller that gives up gets `kind: 'abort'` or `'timeout'`, reported to [`onError`](#reporting-errors-with-onerror) as an unshared call would be. The request keeps running for the others, and is cancelled once every caller has given up.
+- **The endpoint's own `timeout` bounds the shared request for everyone.** It counts from when the request started. A caller that joins late can't extend it, and `timeout: 0` on one call can't turn it off.
 
 ```ts
-const { data, error, response, retry } = await api.getUser({ id: '42' })
-
-if (error) {
-  switch (error.kind) {
-    case 'network':
-      // fetch itself failed -- user is probably offline
-      break
-    case 'timeout':
-      // the whole-operation deadline fired; report it
-      reportTimeout(error)
-      break
-    case 'abort':
-      // this call was cancelled (dedupe supersede, or your own signal) -- usually ignore it
-      break
-    case 'parse':
-      // a 2xx response arrived but its body didn't parse as `responseType`
-      console.error('unparseable response', error.status, error.body)
-      break
-    case 'middleware':
-      // a middleware threw -- a bug in your own pipeline, not a transient failure
-      console.error('middleware threw', error.body)
-      break
-    case 'http':
-      if (error.status === 401) redirectToLogin()
-      else console.error(error.status, error.body)
-      break
-  }
-  return
-}
+const impatient = api.getProduct({ id: '42' }, { timeout: 20 }) // gives up quickly
+const patient = api.getProduct({ id: '42' })                    // keeps waiting
 
-// error is null here, so `data` is narrowed to `User` -- no assertion needed
-// (this assumes getUser always answers with a body; an endpoint that
-// doesn't -- a DELETE returning 204, most commonly -- should use
-// responseType: 'none' instead, see the empty-body note above)
-console.log(data.name)
+// impatient's timeout doesn't cancel the shared request, so patient still gets the response.
 ```
 
-`response`'s body has already been consumed by the time you see it -- the library reads it to produce `data` (or `error.body`), so calling `response.json()` yourself throws "Body has already been read". Use `data`/`error.body`; `response` is for status, headers, and redirect metadata. (This applies only to results the library produces itself -- a `Response` you construct for `successResult()` in `testing.ts` still has a readable body.)
+Two rarer cases have their own notes: [`retry()` on a shared result](#retry-on-a-shared-result) and [middleware that replaces the signal](#signal-replacing-middleware).
 
-#### `retry()`
+#### On a server
 
-The `retry` function re-executes the exact same request through the full middleware chain. Auth tokens are re-injected, logging fires again, everything runs fresh. This is useful for retry-after-refresh patterns:
+Sharing is decided before middleware runs. A header that a middleware adds, such as the current user's token, is not part of the match. With one client serving every user, one user's call can join another user's call and receive that user's response.
 
-```ts
-const { data, error, retry } = await api.getUser({ id: '42' })
+Create one client per incoming request, as in [One /me per page view on the server](#one-me-per-page-view-on-the-server). Otherwise, don't set `share` on an endpoint whose answer depends on who is asking.
 
-if (error?.status === 401) {
-  await refreshToken()
-  const retried = await retry()
-  // retried goes through the full middleware chain again
-}
-```
+### Retries, caching and logging
 
-#### `ApiError`
+Some failures go away when you try again. Some reads repeat often enough to keep. And while you build, you want to see every call. liaise ships a middleware for each, in a separate entry point:
 
-The error object on failed calls. It is not a subclass of `Error` -- it is a structured container for API-level error details.
+```ts
+import { retryMiddleware, cacheMiddleware, logMiddleware } from 'liaise/middleware'
+```
 
-| Property     | Type      | Description                                                       |
-| ------------ | --------- | ----------------------------------------------------------------- |
-| `status`     | `number`  | HTTP status code (e.g., 404, 500). `0` for network errors, aborts, and timeouts. |
-| `kind`       | `'http' \| 'network' \| 'abort' \| 'timeout' \| 'parse' \| 'middleware'` | What category of failure this is. See below. Required -- constructing an `ApiError` yourself (e.g. in custom middleware) must supply it. |
-| `statusText` | `string`  | HTTP status text (e.g., 'Not Found'). `''` for network errors.    |
-| `body`       | `unknown` | Parsed response body -- but for `'parse'`, one of: the thrown exception (a malformed body), the raw response text (an empty body, or a GraphQL response carrying no data), a schema's issues array (the response failed validation), or a value a schema threw. The native Error for network failures. |
-| `headers`    | `Headers` | Response headers. Empty `Headers` for network errors.             |
-| `request`    | `object`  | `{ method, url, params }` -- metadata about the failed request; `url` is the resolved, path-substituted address, falling back to the route template only when it could not be built. |
-| `partialData` | `unknown` (optional) | GraphQL data returned alongside `{ errors }` (partial success). Lives here, not on `Result.data`, so the `Result` stays a clean union: `data` is non-null iff `error` is null. `undefined` for every REST error and for GraphQL responses carrying no data. |
+#### Retry failed calls
 
-`kind` exists because `status` alone cannot tell some outcomes apart: an HTTP error (`'http'`), a `fetch` failure with no response (`'network'`), a cancellation — your own signal, a dedupe supersede, or a whole-operation deadline firing — (`'abort'`/`'timeout'`), a 2xx (or non-2xx) body that failed to parse (`'parse'`), and a middleware that threw instead of the request itself failing (`'middleware'`) all need different handling, but `'network'`, `'abort'`, and `'timeout'` all carry `status: 0`.
+`retryMiddleware(2)` retries a failed call up to two more times, three attempts in all. By default it retries only 5xx responses. Any 4xx, including a 429, comes back as it is, and so does a network error. To retry 429s and network errors too, pass `retryOn`:
 
-`'parse'` is for a **2xx** response that arrived but whose body failed to parse according to `responseType` -- you get the real `status`, a non-null `response`, and `kind: 'parse'`. A **non-2xx** response with an unparseable body is unaffected and still reports `kind: 'http'` -- the status code is checked before the body is parsed, so a 500 with a broken JSON body is still a 500, and `retryMiddleware`'s default 5xx retry still applies to it. An **empty** body under `'json'` is also `'parse'` -- see [Response
-parsing](#response-parsing). GraphQL applies the same rule to a 2xx response
-carrying neither `data` nor `errors`. An optional [`schema`](#response-validation) on the request adds two more `'parse'` producers: a **2xx** body the schema refuses (`error.body` is its issues array) and a validator that throws (`error.body` is the thrown value) -- both only for the success body, never for a non-2xx one, which is never validated.
+```ts
+import { createApi, defineRequest } from 'liaise'
+import { retryMiddleware } from 'liaise/middleware'
 
-`'middleware'` means a middleware threw rather than the request itself failing -- a bug in your own pipeline you'd fix, not a transient failure you'd retry. A middleware that propagates the library's own abort/timeout signal (verbatim, or wrapped one level as `.cause`) is classified `'abort'`/`'timeout'` instead, by provenance rather than by the reason's name -- see [Cancellation](#cancellation).
+type Item = { id: string }
 
-You can use `instanceof` to check if a value is an `ApiError`:
+const getItems = defineRequest<Item[]>()({ method: 'GET', path: '/items' })
 
-```ts
-import { ApiError } from 'liaise'
+const api = createApi({
+  baseUrl: 'https://api.example.com',
+  requests: { getItems },
+  middleware: [retryMiddleware(2)], // 5xx only
+})
 
-if (error instanceof ApiError) {
-  // ...
-}
+// Also retry 429 and network errors. An abort has status 0 too, so check kind.
+const retryMore = retryMiddleware({
+  retryOn: (r) =>
+    (r.error?.status ?? 0) >= 500 || r.error?.status === 429 || r.error?.kind === 'network',
+})
 ```
 
-### Error handling with `onError`
-
-The `onError` callback in `createApi` fires after the full middleware chain completes whenever the final result has an error. If a retry middleware recovers a 5xx to a 200, `onError` does not fire.
+Pass an object to tune the waits between attempts:
 
 ```ts
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getUser, createUser },
-  onError: (error) => {
-    if (error.status === 401) redirectToLogin()
-    Sentry.captureException(error)
-  }
+const retry = retryMiddleware({
+  max: 5,               // up to 5 retries after the first attempt
+  delay: 'exponential', // 250 ms, 500 ms, 1 s, ... before jitter
+  onRetry: ({ attempt, max, delay }) => console.log(`retry ${attempt}/${max} in ${delay}ms`),
 })
 ```
 
-This fires for `kind: 'http'`, `'network'`, `'timeout'`, `'parse'`, and `'middleware'`. **It does not fire for `kind: 'abort'`** — a cancellation the library caused deliberately (your own `AbortSignal` firing, or a request superseded by `dedupe`) is not a failure worth reporting to an error tracker, unlike a `'timeout'`, which is a deadline you actually missed. The caller still gets the abort back in the `Result` either way; only the report to this callback is suppressed. It is a global hook for side effects (logging, telemetry, redirects) -- it does not change the result returned to the caller.
+- By default the waits grow exponentially with random jitter, and a `Retry-After` header from the server is honoured. Every option is in [RetryOptions](#retryoptions).
+- **A cancel or a deadline during a wait ends the call with that error.** If your `timeout`, your signal or a newer `dedupe` call fires between attempts, you get `kind: 'timeout'` or `'abort'`. The 503 that caused the retry is dropped.
 
-### Middleware
+#### Cache repeated reads
 
-Middleware follows the onion model (like Koa or Redux middleware). Each middleware wraps the next layer, can modify the request going in and the result coming out.
+`cacheMiddleware()` keeps successful responses in memory, so a repeated read within the time-to-live skips the network. Each `cacheMiddleware()` call makes its own store. Give it to the endpoints you want cached:
 
-```
-Request → [Global MW → [Per-request MW → [Per-call MW → [fetch]]]]
-```
+```ts
+import { createApi, defineRequest } from 'liaise'
+import { cacheMiddleware } from 'liaise/middleware'
 
-A middleware function receives a `context` and a `next` function:
+type User = { id: string; name: string }
 
-```ts
-import type { Middleware } from 'liaise'
+const getUserCache = cacheMiddleware({ ttl: 5 * 60_000, maxSize: 100 })
 
-const authMiddleware: Middleware = async (ctx, next) => {
-  // Before: modify the request
-  ctx.request.headers.set('Authorization', `Bearer ${getToken()}`)
+const getUser = defineRequest<User>()({
+  method: 'GET',
+  path: '/users/:id',
+  middleware: [getUserCache],
+})
 
-  // Call the next layer
-  const result = await next()
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { getUser } })
 
-  // After: inspect or transform the result
-  return result
-}
+// On logout, clear every cached entry:
+getUserCache.clear()
+
+// Skip the cache for one call:
+const { data } = await api.getUser({ id: '42' }, { skipMiddleware: [getUserCache] })
 ```
 
-#### What middleware can do
+- **Only successes are cached.** An error always goes to the network again.
+- **The key includes the URL, the params and the headers.** When your auth header is set before the cache runs, one user never sees another user's entry. [Cache key](#cache-key) has the details.
+- **Put a middleware that adds a unique header to each call after `cacheMiddleware`.** A request ID added before it makes every call look new, and nothing is ever cached. Client middleware always runs before endpoint middleware, so either list the request-ID middleware on the endpoint after the cache, or put the cache on the client before it.
+- The options are `ttl`, `maxSize` and `debug` ([Cache options](#cache-options)).
 
-- **Modify the request** -- set headers, change the body, rewrite the URL.
-- **Short-circuit** -- return early without calling `next()` (e.g., serve from cache).
-- **Retry** -- call `next()` multiple times in a loop (e.g., retry on 5xx).
-- **Inspect the result** -- log, report errors, transform response data.
+#### Log every call
 
-#### Three layers
+`logMiddleware` prints each call's start and end to the console, with its duration:
 
-Middleware is applied at three levels. The execution order is global first, per-request second, per-call third:
+```text
+[liaise] → GET getItems /api/items
+[liaise] ← getItems OK (142ms)
 
-```ts
-// Global -- applies to every endpoint
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getUser, createUser },
-  middleware: [authMiddleware, logMiddleware]
-})
+[liaise] → POST createUser /api/users
+[liaise] ← createUser ERROR 422 (89ms)
+```
 
-// Per-request -- applies only to this endpoint
-const getUser = new Request<{ id: string }, User>({
-  method: 'GET',
-  path: '/users/:id',
-  middleware: [cacheMiddleware]
-})
+```ts
+import { createApi, defineRequest } from 'liaise'
+import { logMiddleware } from 'liaise/middleware'
 
-// Per-call -- applies only to this single invocation
-await api.getUser({ id: '42' }, {
-  middleware: [customTraceMiddleware]
-})
+const getItems = defineRequest<{ id: string }[]>()({ method: 'GET', path: '/items' })
+
+const api = createApi({ baseUrl: '/api', requests: { getItems }, middleware: [logMiddleware] })
 ```
 
-#### `skipMiddleware`
+It is meant for development. In production, [write a middleware](#writing-middleware) that sends the same facts to your monitoring.
 
-Remove specific middleware for a single call by passing references to `skipMiddleware`:
+### Writing middleware
+
+Some things belong on every call, such as an auth header or tracing, and you don't want to repeat them at each call site. A middleware is a function that wraps a call. It sees the request before it is sent and the `Result` after.
 
 ```ts
-const retry = retryMiddleware(3)
+import { createApi, defineRequest, type Middleware } from 'liaise'
+
+type User = { id: string; name: string }
+
+const auth: Middleware = async (ctx, next) => {
+  // Before: change the request
+  ctx.request.headers.set('Authorization', `Bearer ${getToken()}`)
+
+  // Run the rest of the chain, ending in fetch
+  const result = await next()
+
+  // After: read or change the result
+  return result
+}
+
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
 
 const api = createApi({
-  baseUrl: '/api',
+  baseUrl: 'https://api.example.com',
   requests: { getUser },
-  middleware: [retry, logMiddleware]
+  middleware: [auth],
 })
+```
 
-// Skip retry for this one call
-await api.getUser({ id: '42' }, {
-  skipMiddleware: [retry]
-})
+`getToken` stands for wherever you keep the token.
+
+Each middleware wraps the next, like the layers of an onion. The request passes in through every layer to `fetch`, and the `Result` passes back out through the same layers:
+
+```text
+call → [client middleware → [endpoint middleware → [call middleware → [fetch]]]]
 ```
 
-Comparison is by reference (`===`). Factory-style middleware like `retryMiddleware(3)` must be stored in a variable first -- calling the factory again creates a new reference that will not match.
+A middleware can:
 
-#### `MiddlewareContext`
+- **Change the request.** Set headers, change the body, rewrite the URL.
+- **Answer early** without calling `next()`, for example from a cache.
+- **Call `next()` more than once**, for example to retry a 5xx.
+- **Read the result** to log it, report an error or transform `data`.
 
-The context object passed to each middleware:
+Middleware runs at three levels, the client's first and the call's last, as [Three levels of settings](#three-levels-of-settings) shows.
 
-| Property              | Type      | Description                                              |
-| --------------------- | --------- | -------------------------------------------------------- |
-| `request.method`      | `string`  | HTTP method (GET, POST, etc.)                            |
-| `request.url`         | `string`  | Fully resolved URL with path params and query string     |
-| `request.path`        | `string`  | Original path template (e.g., '/users/:id')              |
-| `request.params`      | `unknown` | Original params object from the caller                   |
-| `request.headers`     | `Headers` | Merged headers -- middleware can add/remove entries       |
-| `request.body`        | `unknown` | Serialized body, or null for GET/DELETE                  |
-| `request.signal`      | `AbortSignal \| undefined` | The signal handed to `fetch` -- replace it to impose your own cancellation policy |
-| `requestName`         | `string`  | Key name in the requests object (e.g., 'getUser')        |
+#### Skipping a middleware for one call
 
-`request.signal` holds the call's own signal: the caller's `options.signal` merged with any `timeout` (and, under `share: true`, with the refcount that aborts the shared request once every sharer has given up). It is `undefined` only when there is none of those. The core fetch reads the field at call time, so replacing it takes effect -- that is all a timeout middleware needs:
+Pass the middleware itself in `skipMiddleware`:
 
 ```ts
-const timeout = (ms: number): Middleware => async (ctx, next) => {
-  ctx.request.signal = AbortSignal.timeout(ms)
-  return next()
-}
+import { createApi, defineRequest } from 'liaise'
+import { retryMiddleware, logMiddleware } from 'liaise/middleware'
+
+type User = { id: string; name: string }
+
+const getUser = defineRequest<User>()({ method: 'GET', path: '/users/:id' })
+const retry = retryMiddleware(3)
 
 const api = createApi({
-  baseUrl: '/api',
+  baseUrl: 'https://api.example.com',
   requests: { getUser },
-  middleware: [timeout(5000)]
+  middleware: [retry, logMiddleware],
 })
-```
 
-Under `dedupe: true` your signal is merged rather than discarded: the request is cancelled by whichever fires first -- your signal, or a newer call superseding this one. The dedupe signal is installed by the core fetch, so middleware reading `ctx.request.signal` before `next()` sees the caller's signal, not the dedupe one.
+// No retries for this one call
+await api.getUser({ id: '42' }, { skipMiddleware: [retry] })
+```
 
-**Pass `ctx.request.signal` on to any async work your middleware does itself** -- a token refresh, a lookup, a queue. The library will not wait for that work past the call's deadline or the caller's abort either way (see [Timeout](#timeout)), but a promise cannot be cancelled from outside: handing it the signal is the only thing that actually *stops* the work, instead of leaving it running in the background with its result discarded.
+liaise compares by reference (`===`). Store what a factory such as `retryMiddleware(3)` returns in a variable first. Calling the factory again makes a new function, which won't match.
 
-#### Writing custom middleware
+#### What a middleware sees
 
-A cache middleware that short-circuits on cache hits:
+`ctx.requestName` is the endpoint's key, such as `'getUser'`. `ctx.request` holds the request as it will be sent, with the URL filled in and the body serialized. Every field is listed under [MiddlewareContext](#middlewarecontext).
 
-```ts
-const cacheMiddleware: Middleware = async (ctx, next) => {
-  const cached = cache.get(ctx.request.url)
-  if (cached) return cached
+#### Signals in middleware
 
-  const result = await next()
+`ctx.request.signal` combines the caller's `signal` with the call's `timeout`, and is `undefined` when there is neither. liaise reads it when it calls `fetch`, so a middleware can replace it. [Give each attempt its own timeout](#give-each-attempt-its-own-timeout) does this, and says what happens to a caller's cancel. How a replaced signal works with `share` and `dedupe` is under [Signal-replacing middleware](#signal-replacing-middleware).
 
-  if (result.data) {
-    cache.set(ctx.request.url, result)
-  }
+**Pass `ctx.request.signal` on to async work your middleware does itself**, such as a token refresh, a lookup or a queue. liaise won't wait for that work past the deadline or the caller's cancel ([Timeout backstop](#timeout-backstop)). A promise can't be stopped from outside, so passing the signal is the only way to end the work. Without it, the work keeps running and its result is thrown away.
 
-  return result
-}
-```
+#### Example: report server errors
 
-An error reporting middleware:
+This middleware sends every 5xx to Sentry, with the method and URL:
 
 ```ts
-const sentryMiddleware: Middleware = async (ctx, next) => {
+import type { Middleware } from 'liaise'
+import * as Sentry from '@sentry/browser'
+
+const reportServerErrors: Middleware = async (ctx, next) => {
   const result = await next()
 
   if (result.error && result.error.status >= 500) {
     Sentry.captureMessage(`API error: ${ctx.request.method} ${ctx.request.url}`, {
-      extra: { status: result.error.status, body: result.error.body }
+      extra: { status: result.error.status, body: result.error.body },
     })
   }
 
@@ -728,309 +945,455 @@ const sentryMiddleware: Middleware = async (ctx, next) => {
 }
 ```
 
-#### Built-in middleware
+### Pagination
 
-The library ships three optional middleware functions, importable from a separate entry point:
+Many list endpoints return one page at a time. `paginate` walks through the pages and gives you one `Result` per page:
 
 ```ts
-import { retryMiddleware, logMiddleware, cacheMiddleware } from 'liaise/middleware'
-```
+import { createApi, defineRequest, paginate } from 'liaise'
 
-**`retryMiddleware(options?: number | RetryOptions)`**
+type Item = { id: string; name: string }
+type Page = { items: Item[]; cursor?: string }
 
-Automatically retries requests that fail, with a real backoff policy — exponential (or linear, or custom) delay curves, full jitter, `Retry-After` support, a configurable retry predicate, and an observational `onRetry` hook.
+const listItems = defineRequest<Page, { limit: number; cursor?: string }>()({
+  method: 'GET',
+  path: '/items',
+})
 
-The numeric shorthand still works exactly as before — `retryMiddleware(2)` retries up to 2 additional times (3 total attempts) on a 5xx response:
+const api = createApi({ baseUrl: 'https://api.example.com', requests: { listItems } })
 
-```ts
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getItems },
-  middleware: [retryMiddleware(2)]
-})
+for await (const page of paginate(api.listItems, { limit: 50 }, {
+  next: (p, prev) => (p.data.cursor ? { ...prev, cursor: p.data.cursor } : undefined),
+})) {
+  if (page.error) break
+  render(page.data.items)
+}
 ```
 
-By default, only server errors (`status >= 500`) are retried. Client errors (4xx), 429, and network errors (`status: 0`) are not — see the opt-in recipes below.
+`render` stands for your own code.
+
+- **`next` returns the params for the next page.** It gets the page just loaded and the params that loaded it, so the usual case is a spread. liaise never has to guess whether your API calls it `cursor`, `page_token` or `after`, and the same shape covers every scheme:
+
+  ```ts
+  // offset
+  next: (p, prev) => p.data.items.length === prev.limit
+    ? { ...prev, offset: prev.offset + prev.limit }
+    : undefined
+
+  // page number, driven by a Link header
+  next: (p, prev) => p.response.headers.get('link')?.includes('rel="next"')
+    ? { ...prev, page: prev.page + 1 }
+    : undefined
+  ```
 
-**Retry policy**
+- **Return `undefined` or `null` to stop.**
+- **An error page ends the walk.** You get the error page, and then the loop ends, because there is no data to read the next cursor from. You see what failed. The loop never stops quietly.
+- **`maxPages` has no default.** Set it if you want a ceiling, as in `paginate(api.listItems, { limit: 50 }, { next, maxPages: 100 })`. liaise doesn't pick a number, because a silent cut-off at an arbitrary page looks exactly like reaching the last one.
+- **Every other option applies to every page.** Any of the [`CallOptions`](#calloptions), such as `signal`, `timeout` or `headers`, goes with each request, so one signal cancels the whole walk.
+- **`paginate` yields pages.** Read the items from each page yourself. Flattening them would mean guessing which field holds the array.
 
-Pass a `RetryOptions` object instead of a number for full control:
+### GraphQL
+
+`createGraphQL` is the client for a GraphQL backend. Its calls return the same `Result`, run the same middleware and report errors the same way. Every operation is sent as a POST with `{ query, variables }`.
 
 ```ts
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getItems },
-  middleware: [retryMiddleware({
-    max: 5,
-    delay: 'exponential',
-    baseDelay: 250,
-    maxDelay: 10_000,
-    jitter: true,
-    respectRetryAfter: true,
-    onRetry: ({ attempt, max, delay }) => console.log(`retry ${attempt}/${max} in ${delay}ms`),
-  })],
+import { createGraphQL, Operation, gql } from 'liaise'
+
+type Category = { id: string; name: string; status: string }
+
+const GET_CATEGORY = gql`
+  query GetCategory($id: String!) {
+    category(id: $id) {
+      id
+      name
+      status
+    }
+  }
+`
+
+const getCategory = new Operation<{ id: string }, Category>({
+  operation: GET_CATEGORY,
+})
+
+const graphql = createGraphQL({
+  endpoint: 'https://api.example.com/graphql',
+  operations: { getCategory },
+  onError: (error) => console.error(error.status, error.body),
 })
-```
 
-| Option              | Type                                              | Default          | Description |
-| -------------------- | -------------------------------------------------- | ----------------- | ----------- |
-| `max`                | `number`                                            | `3`               | Additional attempts after the first. `retryMiddleware({ max: 2 })` means up to 3 total calls. |
-| `delay`              | `'exponential' \| 'linear' \| (attempt: number) => number` | `'exponential'`   | The delay curve. Exponential is `baseDelay * 2^(attempt-1)`; linear is `baseDelay * attempt`; a function receives the 1-based attempt number and returns milliseconds. |
-| `baseDelay`          | `number`                                            | `250`             | The first delay, in milliseconds, before jitter and `Retry-After` are applied. |
-| `maxDelay`           | `number`                                            | `30000`           | Hard cap applied to every computed delay, including a `Retry-After` value. |
-| `jitter`             | `boolean`                                           | `true`            | Full jitter: the actual delay is `Math.random() * computed`, per AWS's recommendation for de-synchronizing a thundering herd. Never applied to a `Retry-After` value — a server telling you exactly when to come back should not be randomized. |
-| `respectRetryAfter`  | `boolean`                                           | `true`            | Honor a `Retry-After` response header (delta-seconds or an HTTP-date) when present, replacing the computed delay outright (still capped by `maxDelay`). |
-| `retryOn`            | `(result: Result<unknown>, attempt: number) => boolean` | `r => (r.error?.status ?? 0) >= 500` | Whether to retry. Called with the 1-based *candidate* attempt number, even once `max` is reached, so a predicate that counts attempts sees one call per result. |
-| `onRetry`            | `(info: RetryInfo) => void`                         | —                 | Observational hook fired before each retry's delay elapses. Its return value is ignored, and a throw cannot fail the request — this is the only way to observe an in-progress retry sequence, since the call site sees nothing until the final result. |
+const { data, error, response, retry } = await graphql.getCategory({ id: '123' })
+```
 
-`RetryInfo` (the argument to `onRetry`): `{ attempt, max, delay, result }` — `attempt` is 1-based (the first retry is `1`), `delay` is the actual delay about to elapse (after jitter and `Retry-After`), and `result` is the `Result` that triggered this retry.
+`Operation<TVariables, TData>` takes the variables type first and the response type second. `gql` marks the string as GraphQL for your editor.
 
-**429 and network-error opt-in.** Both are deliberately excluded from the default `retryOn` — retrying a rate limit or a network failure by default would change behavior under existing callers on upgrade. Opt in explicitly:
+An operation with no variables is called without arguments. Write `Record<string, never>` as its variables type:
 
 ```ts
-// Retry 429 in addition to 5xx
-retryMiddleware({
-  retryOn: r => r.error?.status === 429 || (r.error?.status ?? 0) >= 500
-})
+type Viewer = { id: string; name: string }
 
-// Retry network errors (status 0) too — but not aborts, which are also status 0
-retryMiddleware({
-  retryOn: r => (r.error?.status ?? 0) >= 500 || r.error?.kind === 'network'
+const getViewer = new Operation<Record<string, never>, Viewer>({
+  operation: gql`query { viewer { id name } }`,
 })
+
+const api = createGraphQL({ endpoint: 'https://api.example.com/graphql', operations: { getViewer } })
+
+const { data } = await api.getViewer() // no arguments
 ```
 
-**An abort during backoff surfaces as the abort, not the stale result it was retrying.** If the signal driving the request — a whole-operation `timeout`, a caller's own `AbortSignal`, or a dedupe supersede — fires while `retryMiddleware` is sleeping between attempts, the backoff sleep resolves immediately and the loop proceeds straight to the next attempt, which the core fetch rejects instantly (no network call) because the signal is already aborted. The caller receives **that abort** — `kind: 'timeout'` for a deadline, `kind: 'abort'` for a cancellation or a dedupe supersede — never the last real HTTP result (e.g. a stale `503`) that triggered the retry in the first place:
+#### Queries and mutations
+
+To keep queries and mutations apart, use the `queries` and `mutations` keys instead of `operations`. Each client uses one shape or the other, and TypeScript refuses both together.
 
 ```ts
-const api = createApi({
-  baseUrl: '/api',
-  requests: {
-    getItems: new Request<Record<string, never>, Item[]>({
-      method: 'GET',
-      path: '/items',
-      timeout: 2000, // whole-operation deadline
-    })
+const graphql = createGraphQL({
+  endpoint: 'https://api.example.com/graphql',
+  queries: {
+    getCategory: new Operation<{ id: string }, Category>({ operation: GET_CATEGORY }),
+  },
+  mutations: {
+    updateCategory: new Operation<{ id: string; name: string }, Category>({
+      operation: gql`
+        mutation UpdateCategory($id: String!, $name: String!) {
+          updateCategory(id: $id, name: $name) { id name status }
+        }
+      `,
+    }),
   },
-  middleware: [retryMiddleware({ max: 5, baseDelay: 1000 })], // long backoff
 })
 
-const { error } = await api.getItems()
-// If the 2s deadline fires while retryMiddleware is asleep between attempts:
-// error.status === 0, error.kind === 'timeout' -- not the 503 being retried
+graphql.query.getCategory({ id: '123' })
+graphql.mutation.updateCategory({ id: '123', name: 'New Name' })
 ```
 
-**`logMiddleware`**
+#### GraphQL errors
 
-Logs request start and completion to the console with timing:
+A 2xx response with `{ errors: [...] }` is an error. It has `kind: 'http'`, the response's own `status`, and the `GraphQLError[]` in `error.body`. The same `if (error)` check covers GraphQL errors, HTTP errors and network errors.
 
-```
-[liaise] → GET getItems /api/items
-[liaise] ← getItems OK (142ms)
+GraphQL allows partial success, where one field fails and the rest of the query resolves. That data is kept in `error.partialData`. `result.data` stays `null` whenever `error` is set, so `Result` keeps its two clean branches.
 
-[liaise] → POST createUser /api/users
-[liaise] ← createUser ERROR 422 (89ms)
+```ts
+const { error } = await graphql.getCategory({ id: '123' })
+if (error) {
+  console.log(error.body)        // GraphQLError[]
+  console.log(error.partialData) // the data the server sent with the errors, or undefined
+}
 ```
 
-Intended for development. In production, write a custom middleware that sends telemetry to your observability platform.
+- **A 2xx with neither `data` nor `errors` is a `'parse'` error**, the same rule as an empty body on REST. That covers an empty body, `{}`, `{"data": null}` and a JSON root that isn't an object. `error.body` holds the raw response text, such as `''` or `'{}'`.
+- **`{"data": null, "errors": [...]}` is still `kind: 'http'`**, because the errors are checked first. Any partial result is in `error.partialData`.
+
+#### Same as REST, and different
+
+Most of what the guide says about `createApi` holds for `createGraphQL`.
+
+**The same as REST**
+
+- **Every call returns a `Result`**, `{ data, error, response, retry }`, and `error.kind` names the failure.
+- **`middleware`** runs on the client, the `Operation` and the call, in the same order. The context has the same shape, so the [built-in middleware](#retries-caching-and-logging) and yours work unchanged.
+- **`headers`** go on the client, the `Operation` and the call, and merge by the [three levels](#three-levels-of-settings).
+- **`onError`** goes on `createGraphQL` and works as in [Reporting errors with onError](#reporting-errors-with-onerror).
+- **`retry()`** is on every `Result`.
+- **`dedupe`** goes on the `Operation`, as in [Drop stale calls with dedupe](#drop-stale-calls-with-dedupe).
+- **`timeout`** goes on the `Operation` or the call. It is one deadline for the whole call, retries included.
+- **`schema`** goes on the `Operation` and validates the response's `data`. The response type stays explicit ([Validating responses](#validating-responses)).
+- **`signal` and `skipMiddleware`** go on the call.
+
+**Different from REST**
+
+- **`endpoint`** is the full URL of the GraphQL endpoint. It takes the place of `baseUrl`.
+- **Variables always go in the JSON body.** There are no path params, no query strings and no `bodyAs`.
+- **Every operation is a `POST`**, with `Content-Type: application/json` unless you set your own.
+- **There is no `share`.** An `Operation` can't join identical calls.
+- **There is no `responseType`.** The response is always read as JSON.
+
+### Testing your code
+
+`liaise/testing` gives you a `fetch` stub that matches routes. Your tests then run the real pipeline, from URL building, headers and body to parsing and your own middleware. A stubbed API method that returns a canned `Result` drifts away from what liaise actually does. The stub needs no test runner, so it works in Vitest, Jest or anything else.
 
 ```ts
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getItems },
-  middleware: [logMiddleware]
+import { mockFetch, jsonResponse } from 'liaise/testing'
+
+const mock = mockFetch({
+  'GET /api/users/:id': ({ params }) => jsonResponse({ id: params.id, name: 'Ada' }),
+  'POST /api/users': jsonResponse({ id: 'new-user' }, { status: 201 }),
 })
+
+mock.install()   // replaces globalThis.fetch
+// ... exercise your code, which calls the real api.getUser(...) ...
+mock.restore()   // puts the original globalThis.fetch back
 ```
 
-**`cacheMiddleware(options?)`**
+- **Routes are keyed as `"METHOD /path"`.** Each `:token` segment is captured and passed to a route function as `{ params, request }`.
+- **A route value is a `Response`, a route function, or an array of either.** `jsonResponse` builds a `Response` with a JSON body, or you can build your own.
+- **An array is a sequence.** Each matching call takes the next entry, and the last entry repeats once the others are used up. That suits "fail twice, then succeed":
+
+  ```ts
+  const mock = mockFetch({
+    'GET /api/flaky': [jsonResponse(null, { status: 503 }), jsonResponse({ ok: true })],
+  })
+  ```
 
-Caches successful responses in memory, keyed by request name, method, the full URL, params and every request header except `Content-Type` (which is derived from the params). The URL's query string is part of the key with its pairs sorted by name, so `?a=1&b=2` and `?b=2&a=1` are one entry, while `?key=A` and `?key=B` (or a `?lang=de` appended by a middleware before the cache) are not. Calls that agree on all of those within the TTL window are served from cache without hitting the network. A different `Authorization` or any other header (except `Content-Type`), a different base URL, path or query value gets its own entry, so one user is never served another's response; the same query params in a different order share one. The query is sorted by raw (undecoded) name, keeping the order of repeated names. The trade-off: a middleware that adds a per-call unique header (a request ID, say) must come *after* `cacheMiddleware` in the middleware array; placed before it, every call carries a fresh header and nothing is ever cached. Each `cacheMiddleware()` call creates an isolated store — different endpoints never share entries.
+- **`mock.calls` records every request** as `{ method, url, headers, body }`. `mock.callCount('GET /api/users/:id')` and `mock.lastCall(...)` take the same `"METHOD /path"` keys as the routes.
 
-Params are keyed by content, at every depth: plain data as sorted JSON with `undefined` members dropped (so `{ a: undefined }` and `{}` are one key), anything with `toJSON` by what it returns (a `Date` is its ISO string), and `Map`, `Set` and typed arrays by their entries. A call whose params cannot be keyed soundly — a BigInt, an `ArrayBuffer`, `Blob`, `FormData` or `URLSearchParams`, or an object with no enumerable state such as a class instance holding private fields — is never cached and never served from cache. The rule is the same one `share` uses; see [Sharing](#sharing).
+#### Unmatched routes
+
+A request that matches no route makes the stub throw, so a typo in a path can't pass quietly. liaise catches every `fetch` rejection, so your code sees an ordinary `Result` with `kind: 'network'` and the `Error` in `error.body`. Its message names the method, the URL and every route you defined. Assert on the result, because the call itself never rejects.
 
 ```ts
-const getUserCache = cacheMiddleware({ ttl: 5 * 60_000, maxSize: 100 })
+const r = await api.getUser({ id: '42' })   // routes only define 'GET /api/user/:id'
+expect(r.error?.kind).toBe('network')
+expect(String(r.error?.body)).toMatch(/no route matched GET \/api\/users\/42/)
+```
 
-const getUser = new Request<{ id: string }, User>({
-  method: 'GET',
-  path: '/users/:id',
-  middleware: [getUserCache],
-})
+`api` is a client created with `baseUrl: '/api'`.
 
-// On logout — clear all cached entries:
-getUserCache.clear()
+An empty array for a route behaves the same way, with a descriptive `Error` in `error.body`.
 
-// Bypass cache for a single call:
-const { data } = await api.getUser({ id: '42' }, { skipMiddleware: [getUserCache] })
+#### Stubbing a Result directly
+
+To stub at the `Result` level instead of the `fetch` level, `successResult(data)` and `errorResult(status, body)` build a well-formed `Result`. This uses Vitest's `vi.spyOn`, and any runner's equivalent works the same way:
+
+```ts
+import { successResult, errorResult } from 'liaise/testing'
+
+vi.spyOn(api, 'getUser').mockResolvedValue(successResult({ id: '42', name: 'Ada' }))
+vi.spyOn(api, 'getUser').mockResolvedValue(errorResult(404, { message: 'not found' }))
 ```
 
-Options: `ttl` (milliseconds, default 5 min), `maxSize` (max entries, default 50), `debug` (log hits/misses to console, default false). Only successful results are cached — errors always hit the network again.
+More of the stub's behaviour, such as how it handles a signal, is under [liaise/testing](#liaisetesting).
 
-### Content types
+## Recipes
 
-Request bodies are automatically serialized based on the input type. The `Content-Type` header is set for you unless you explicitly provide one.
+Each recipe below is a complete example that runs against a test, so you can paste it as it is.
 
-| Input type        | Body output        | Content-Type                          |
-| ----------------- | ------------------ | ------------------------------------- |
-| `null`/`undefined` | `null`             | _(none)_                              |
-| `string`          | as-is              | `text/plain`                          |
-| `FormData`        | as-is              | _(browser sets multipart boundary)_   |
-| `URLSearchParams` | as-is              | `application/x-www-form-urlencoded`   |
-| `Blob`            | as-is              | `application/octet-stream`            |
-| `ArrayBuffer`     | as-is              | `application/octet-stream`            |
-| Typed array, `DataView`, `Buffer` | as-is (sent as binary) | `application/octet-stream` |
-| `ReadableStream`  | as-is (streaming upload; `duplex: 'half'` is set for you) | `application/octet-stream` |
-| Plain object      | `JSON.stringify()` | `application/json`                    |
+### Add an auth header and refresh the token on a 401
 
-A `ReadableStream` body can be sent once. A retry (`retryMiddleware`, `result.retry()`) returns an error Result telling you to read the stream into a `Blob` or `ArrayBuffer` first. Under `retryMiddleware` that is the Result you end up with: after a 5xx, the final Result is the "cannot resend" `TypeError` (status 0), so the original 503 is not in it.
+With rotating refresh tokens, five requests that all get a 401 at once must not refresh five times: the first refresh invalidates the token the other four send, and the user is logged out.
 
-#### What params can be
+<!-- tested: auth-refresh -->
+```ts
+import { createApi, defineRequest, type Middleware } from 'liaise'
 
-| You pass | What happens |
-| -------- | ------------ |
-| Plain object | Decomposed into path tokens, query string and body |
-| `Map` with string keys | Same as the object it spells |
-| Class instance with fields | Same as a plain object (decomposed by those fields even if the class also defines `toJSON()`; `toJSON()` is used only when there are no own fields) |
-| Class instance with only `toJSON()` | Sent as its JSON (body only; refused on a request whose params go in the query string) |
-| Typed array, `DataView`, `Buffer`, `ReadableStream` | Sent as the body, as in the table above (refused on a request whose params go in the query string) |
-| `Set`, a bare `Date`, a `Map` with non-string keys, a class with no fields | Refused: an error Result (`kind: 'network'`) naming the type. Nothing is sent. |
+type Tokens = { access: string; refresh: string }
+type Order = { id: string; total: number }
 
-A `Map`, `Set` or class with private state nested inside a JSON body is sent as `{}`, because that is what `JSON.stringify` does. Convert it first.
+let tokens: Tokens = { access: 'expired', refresh: 'r1' }
 
-Header merge precedence (most specific wins):
+const auth: Middleware = async (ctx, next) => {
+  if (ctx.requestName === 'refresh') return next()
 
-1. **Global headers** (from `createApi` config) -- lowest priority
-2. **Per-request headers** (from `Request` config) -- overrides global
-3. **Per-call headers** (from `CallOptions`) -- highest priority
+  const sentWith = tokens.access
+  ctx.request.headers.set('Authorization', `Bearer ${sentWith}`)
+  const result = await next()
+  if (result.error?.status !== 401) return result
+
+  // Refresh only if nobody has done it since this call was sent. Every call
+  // that gets here at the same moment joins one refresh request (share: true).
+  if (tokens.access === sentWith) {
+    const refreshed = await api.refresh({ token: tokens.refresh })
+    if (refreshed.error) return result // refresh failed: keep the 401
+    tokens = refreshed.data
+  }
+  ctx.request.headers.set('Authorization', `Bearer ${tokens.access}`)
+  return next() // send the call again with the new token
+}
 
-Explicitly set `Content-Type` headers at any level override the auto-detected value.
+const api = createApi({
+  baseUrl: '/api',
+  middleware: [auth],
+  requests: {
+    refresh: defineRequest<Tokens, { token: string }>()({
+      method: 'POST',
+      path: '/auth/refresh',
+      share: true,
+    }),
+    getOrders: defineRequest<Order[]>()({ method: 'GET', path: '/orders' }),
+  },
+})
+```
 
-### Response parsing
+`share: true` on `refresh` is what makes the five calls wait for one refresh. The `requestName` check stops the refresh call from passing through its own middleware.
 
-The `responseType` option on a `Request` determines how the response body is parsed:
+### Search as you type
 
-| `responseType`  | Method called          | Return type    |
-| --------------- | ---------------------- | -------------- |
-| `'json'`        | `response.text()` then `JSON.parse()` | parsed object  |
-| `'text'`        | `response.text()`      | `string`       |
-| `'blob'`        | `response.blob()`      | `Blob`         |
-| `'arrayBuffer'` | `response.arrayBuffer()` | `ArrayBuffer` |
-| `'formData'`    | `response.formData()`  | `FormData`     |
-| `'none'`        | *(not read -- stream cancelled)* | `undefined` |
+Each keystroke starts a request, and a slow answer to an early one can arrive after a fast answer to a later one. `dedupe` makes sure only the latest search is shown.
 
-The default is `'json'`. An **empty body under `'json'` is an error**, not a
-`null`: you declared JSON and the server sent none, so there is no value that
-could honestly satisfy `TResponse`. You get `kind: 'parse'` with the
-response's own status (a `204` reports `204`), a non-null `response`, and the
-raw body text -- always `''` for this case -- in `error.body`:
+`Repo` is your result type; `render` and `showError` stand for your UI code.
 
+<!-- tested: search-as-you-type -->
 ```ts
-const { data, error } = await api.deleteUser({ id: '42' })
-// 204 No Content, responseType left at the 'json' default:
-// error.kind === 'parse', error.status === 204, data === null
+import { createApi, defineRequest } from 'liaise'
+
+const search = defineRequest<Repo[], { q: string }>()({
+  method: 'GET',
+  path: '/search',
+  dedupe: true, // a new call cancels the one still in flight
+})
+const api = createApi({ baseUrl: '/api', requests: { search } })
+
+async function onInput(q: string) {
+  const { data, error } = await api.search({ q })
+  if (error?.kind === 'abort') return // a newer search replaced this one
+  if (error) return showError(error)
+  render(data)
+}
 ```
 
-A literal `null` body is **not** empty -- `JSON.parse("null")` is valid JSON,
-and that response still succeeds with `data: null`.
+The older call settles with an `abort` error, which you skip. Only the newest search reaches `render`.
+
+### Use with TanStack Query
 
-**`responseType: 'none'`** is the declaration for an endpoint that returns no
-body on success -- a `204`, or a `200` with an empty body, most commonly a
-`DELETE`:
+liaise never throws. TanStack Query expects a failing query function to throw, so `unwrap` converts at that one boundary. `api` is the client from [Quick start](#quick-start).
 
+<!-- tested: tanstack-query -->
 ```ts
-const deleteUser = new Request<{ id: string }, undefined>({
-  method: 'DELETE',
-  path: '/users/:id',
-  responseType: 'none',
+import type { Result } from 'liaise'
+
+// TanStack Query expects a failed query to throw. Do it here, at your edge.
+async function unwrap<T>(call: Promise<Result<T>>): Promise<T> {
+  const { data, error } = await call
+  if (error) throw error
+  return data
+}
+
+export const userQuery = (id: string) => ({
+  queryKey: ['user', id],
+  // TanStack's signal cancels the request when the query is no longer needed.
+  queryFn: ({ signal }: { signal: AbortSignal }) => unwrap(api.getUser({ id }, { signal })),
 })
+
+// React:  useQuery(userQuery(id))
+// Vue:    useQuery(computed(() => userQuery(id.value)))
+// Svelte: createQuery(() => userQuery(id))
+// Solid:  useQuery(() => userQuery(id()))
 ```
 
-No body is read on a successful (2xx) response: `data` is `undefined`, and any body the server sends anyway is discarded -- its stream is cancelled, so a keep-alive connection is released rather than held open by an unread body. Declare `TResponse` as `undefined` when using `responseType: 'none'` -- but this is a convention, not a compile-time guarantee: `new Request<{ id: string }, User>({ responseType: 'none' })` compiles clean, and if the two disagree, `data` is `undefined` at runtime behind whatever type you declared.
+The same options object works with every TanStack adapter; the comments show the call in each. These comment lines aren't executed by the test.
 
-`'none'` only describes the **success** shape. A non-2xx response is still read and parsed as JSON for `error.body` -- an error body is diagnostic (a message, a code) and worth reading even when the caller wants nothing back on success:
+`error` is the `ApiError` liaise returned, which isn't an `Error` subclass, so it has no `message`. Read `error.kind` and `error.status`. To type it, register `ApiError` as TanStack's `defaultError`.
 
+### Use with React
+
+This hook uses React's `useEffect` and `useState`, imported from `react`. `api` and `User` are from [Quick start](#quick-start).
+
+<!-- tested: react-effect -->
 ```ts
-const { error } = await api.deleteUser({ id: '42' })
-if (error) {
-  // A 409 { "error": "already deleted" } still lands in error.body here,
-  // even though deleteUser declares responseType: 'none'.
-  console.error(error.status, error.body)
+function useUser(id: string) {
+  const [state, setState] = useState<{ user?: User; failed?: boolean }>({})
+
+  useEffect(() => {
+    const controller = new AbortController()
+    api.getUser({ id }, { signal: controller.signal }).then(({ data, error }) => {
+      if (error?.kind === 'abort') return // unmounted, or id changed
+      setState(error ? { failed: true } : { user: data })
+    })
+    return () => controller.abort() // cancel when the component goes away
+  }, [id])
+
+  return state
 }
 ```
 
-(3.0.0's advice for this case was to widen the endpoint's `TResponse` to
-`| null`. That advice is superseded: `responseType: 'none'` declares "no body"
-rather than "body or null", and since 4.0.0 the `| null` workaround no longer
-works at all -- the empty body is an error before `TResponse` is ever
-consulted. See [MIGRATION.md](./MIGRATION.md#upgrading-to-400).)
-
-### Cancellation
+Aborting on cleanup means a fast navigation never writes stale data into a component that has moved on.
 
-#### Manual abort via `AbortSignal`
+### Load the current user into a store
 
-Pass an `AbortSignal` through `CallOptions` to cancel a request:
+The header, sidebar and avatar each check the store on first render, find it empty, and each ask for the user. `User` is your type.
 
+<!-- tested: store-me -->
 ```ts
-const controller = new AbortController()
+import { createApi, defineRequest } from 'liaise'
 
-const promise = api.getItems({ page: 1 }, {
-  signal: controller.signal
-})
+const me = defineRequest<User>()({ method: 'GET', path: '/me', share: true })
+const api = createApi({ baseUrl: '/api', requests: { me } })
 
-// Cancel the request
-controller.abort()
+// Any store works the same way: Zustand, Pinia, Redux or a plain object.
+const store = { user: null as User | null }
 
-const { error } = await promise
-// error.status === 0, error.kind === 'abort', error.body is a DOMException with name 'AbortError'
+async function loadUser() {
+  if (store.user) return // empty on first render, for every component
+  const { data } = await api.me() // callers at the same moment join one request
+  if (data) store.user = data
+}
 ```
 
-A cancellation you caused yourself is not reported to `onError` (`kind: 'abort'` is the one kind that's suppressed there) -- see [Error handling with `onError`](#error-handling-with-onerror). It is classified by **provenance**, not by sniffing the thrown value's shape: whatever a middleware or `fetch` actually throws, if it happened because *this request's own signal* aborted, the `Result` is `kind: 'abort'` (or `'timeout'` for a deadline) regardless of the reason's name or type -- a caller-supplied custom abort reason (`controller.abort(new Error('unmounted'))`, or a plain string) still classifies as `'abort'`, not `'network'`.
-
-Aborting settles the call even while a middleware is still awaiting work of its own that ignores the signal -- the same backstop that bounds `timeout`, described under [Timeout](#timeout).
+[TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview) dedupes this case too; this recipe is for apps using a plain store.
 
-#### Auto-cancel via `dedupe`
+### One /me per page view on the server
 
-When a `Request` has `dedupe: true`, each new call automatically aborts the previous in-flight call for that endpoint. Identity is per `Request` instance -- different endpoints do not interfere with each other.
+On the server there's no store. A page's loaders run in parallel and each one needs the current user. `User` and `IncomingRequest` stand for your types; `cookie` stands for however you pass the user's identity.
 
+<!-- tested: server-loaders -->
 ```ts
-const searchUsers = new Request<{ q: string }, User[]>({
-  method: 'GET',
-  path: '/users/search',
-  dedupe: true
-})
-
-const api = createApi({
-  baseUrl: '/api',
-  requests: { searchUsers }
-})
+import { createApi, defineRequest } from 'liaise'
+
+const me = defineRequest<User>()({ method: 'GET', path: '/me', share: true })
+
+// One client per incoming request: that page's loaders share one /me call,
+// and one user's call can never join another user's.
+function apiFor(req: IncomingRequest) {
+  return createApi({
+    baseUrl: 'https://users.internal',
+    headers: { cookie: req.headers.cookie ?? '' },
+    requests: { me },
+  })
+}
 
-// Rapid calls -- only the last one completes
-api.searchUsers({ q: 'h' })    // aborted by next call
-api.searchUsers({ q: 'he' })   // aborted by next call
-api.searchUsers({ q: 'hel' })  // this one completes
+async function renderPage(req: IncomingRequest) {
+  const api = apiFor(req)
+  const [header, cart] = await Promise.all([
+    api.me().then(r => r.data?.name),   // header loader
+    api.me().then(r => r.data?.cartId), // cart loader
+  ])
+  return { header, cart }
+}
 ```
 
-Dedupe and manual abort signals work together. If both are active, the request is cancelled if either fires.
+The client is created per request so that one user's call can never join another's; see [On a server](#on-a-server). Inside React Server Components, React's [`cache()`](https://react.dev/reference/react/cache) does this too.
 
-### Timeout
+### Retry a flaky backend within one deadline
 
-Set `timeout` (milliseconds) on a `Request` or per-call to abort a request that takes too long:
+Use this when a backend sometimes fails with a 5xx, a rate limit or a dropped connection, and you still want an answer within a fixed time.
 
+<!-- tested: flaky-backend -->
 ```ts
-const getUser = new Request<{ id: string }, User>({
-  method: 'GET',
-  path: '/users/:id',
-  timeout: 5000
+import { createApi, defineRequest } from 'liaise'
+import { retryMiddleware } from 'liaise/middleware'
+
+type Report = { rows: number }
+
+const retry = retryMiddleware({
+  max: 3,
+  // Retry server errors, rate limits and dropped connections. Not 4xx.
+  retryOn: r => {
+    const e = r.error
+    return !!e && (e.status >= 500 || e.status === 429 || e.kind === 'network')
+  },
 })
 
-const { error } = await api.getUser({ id: '42' })
-// error.status === 0, error.kind === 'timeout' if it fired
+const api = createApi({
+  baseUrl: '/api',
+  middleware: [retry],
+  requests: {
+    // timeout covers every attempt and every wait between them.
+    getReport: defineRequest<Report>()({ method: 'GET', path: '/report', timeout: 3000 }),
+  },
+})
 ```
 
-**`timeout` is a whole-operation deadline, not a per-attempt budget.** It covers the entire middleware chain, including every retry and every backoff delay. `timeout: 5000` combined with `retryMiddleware(3)` still means "an answer within 5 seconds" for the call as a whole — not five seconds for each individual attempt. This is a deliberate choice, and it **differs from axios, XHR, and `got`**, all of which apply a timeout per attempt and therefore let a retrying request run for a multiple of the configured timeout. Know which behavior you're assuming before you tune the number.
+With `timeout: 3000`, the caller gets an answer within three seconds however many retries are left. See [Set a deadline with timeout](#set-a-deadline-with-timeout).
 
-If you want a per-attempt budget instead — the axios-style behavior — write a small signal-replacing middleware and place it *inside* the retry middleware, so a fresh signal is installed on every attempt:
+### Give each attempt its own timeout
 
+liaise's `timeout` is one deadline for the whole call. If you want a limit per attempt instead, put a middleware *inside* the retry. `getUser` is the endpoint from [Quick start](#quick-start).
+
+<!-- tested: per-attempt-timeout -->
 ```ts
+import { createApi } from 'liaise'
+import type { Middleware } from 'liaise'
+import { retryMiddleware } from 'liaise/middleware'
+
+// A fresh time limit for each attempt, instead of one for the whole call.
 const perAttempt = (ms: number): Middleware => async (ctx, next) => {
   ctx.request.signal = AbortSignal.timeout(ms)
   return next()
@@ -1039,385 +1402,539 @@ const perAttempt = (ms: number): Middleware => async (ctx, next) => {
 const api = createApi({
   baseUrl: '/api',
   requests: { getUser },
-  middleware: [retryMiddleware(3), perAttempt(5000)]
+  // Order matters: retry wraps perAttempt, so every attempt gets its own 5 s.
+  middleware: [
+    retryMiddleware({ retryOn: r => r.error?.kind === 'timeout' || (r.error?.status ?? 0) >= 500 }),
+    perAttempt(5_000),
+  ],
 })
 ```
 
-Because middleware order is outermost-to-innermost, `retryMiddleware(3)` re-invokes everything below it — including `perAttempt(5000)` — on every retry, so each attempt gets its own fresh 5-second budget instead of sharing one.
+Timeouts aren't retried by default; the `retryOn` above opts in. Because the middleware replaces `ctx.request.signal`, a caller's own cancel still ends the call as `'abort'`, but the request itself keeps running until the per-attempt signal fires.
 
-A few more details:
+### Report errors to Sentry
 
-- `CallOptions.timeout` overrides `RequestConfig.timeout` for a single call; a per-call `timeout: 0` disables a per-request timeout rather than falling back to it.
-- A timeout produces an error with `status: 0` and `kind: 'timeout'` — distinguishable from a caller-initiated cancellation (`kind: 'abort'`) and from a genuine network failure (`kind: 'network'`).
-- `result.retry()` always starts a fresh deadline. A retried call is not charged against the original budget.
-- Non-positive or omitted `timeout` disables it entirely (the default).
-- `timeout` composes with `dedupe: true` — the deadline is merged with the dedupe signal rather than discarded by it.
-- Under `share: true` the two timeouts have different owners. `RequestConfig.timeout` belongs to the *operation*: it bounds the one shared request for every caller, measured from when that request started, so a single caller can neither extend it nor disable it with a per-call `timeout: 0`. `CallOptions.timeout` bounds only the caller that passed it — see [Sharing](#sharing).
-
-**The deadline bounds middleware that never looks at the signal, too.** A middleware that awaits something of its own before calling `next()` — a token refresh, say — cannot hold the call past its `timeout`, even if that work never settles:
+Send every unexpected failure to your error tracker from one place. `Sentry` stands for your error tracker; `getUser` is the [Quick start](#quick-start) endpoint.
 
+<!-- tested: report-errors -->
 ```ts
-const auth: Middleware = async (ctx, next) => {
-  const token = await user.getIdToken()   // stalls on a bad network
-  ctx.request.headers.set('Authorization', `Bearer ${token}`)
-  return next()
-}
-// With timeout: 45_000, the call still settles at ~45s: kind 'timeout', status 0.
+import { createApi } from 'liaise'
+
+const api = createApi({
+  baseUrl: '/api',
+  requests: { getUser },
+  // Called once per failed call, after retries. Never for 'abort': you cancelled it.
+  onError: error => {
+    if (error.kind === 'http' && error.status < 500) return // expected 4xx, not a bug
+    Sentry.captureException(error, {
+      extra: { kind: error.kind, url: error.request.url, status: error.status },
+    })
+  },
+})
 ```
 
-When the deadline passes, the chain gets one macrotask to answer by itself. That is enough for everything that already responds to the abort — `fetch` rejecting, a middleware rethrowing the reason, a fallback middleware that turns a timeout into a cached response — so all of those keep their own `Result` exactly as before. A chain still pending after that is waiting on something the signal does not reach, and the call settles with the same `Result` an aborted `fetch` would have produced: `kind: 'timeout'`, `status: 0`, reported to `onError` once. A caller's own `signal` works the same way, with `kind: 'abort'`, which is not reported.
+`ApiError` isn't an `Error`, so it carries no stack trace or `message` of its own. Pass the fields you want to see in `extra`, as above.
 
-A promise cannot be cancelled, so the stalled middleware keeps running. Whatever it eventually returns or throws is discarded — no second `Result`, no second `onError` — and if it calls `next()` after the call has settled, no request is sent: `next()` hands back the `Result` the caller already has. To stop the work itself, pass `ctx.request.signal` into it (see [`MiddlewareContext`](#middlewarecontext)).
+Use a middleware instead when you need timing, or the request before it's sent, or want to report for some endpoints only. [Example: report server errors](#example-report-server-errors) has the middleware version.
 
-### Sharing
+### Upload and download files
 
-Set `share: true` on a `Request` to coalesce identical concurrent calls onto a single in-flight request, instead of each caller firing its own:
+Send a file with `FormData` and read one back as a `Blob`.
 
+<!-- tested: files -->
 ```ts
-const getProduct = new Request<{ id: string }, Product>({
+import { createApi, defineRequest } from 'liaise'
+
+// Upload: pass FormData as the params. liaise sends it as-is, and the
+// runtime sets the multipart Content-Type with its boundary.
+const uploadAvatar = defineRequest<{ url: string }, FormData>()({
+  method: 'POST',
+  path: '/avatar',
+})
+
+// Download: ask for a Blob instead of JSON.
+const downloadFile = defineRequest<Blob>()({
   method: 'GET',
-  path: '/products/:id',
-  share: true
+  path: '/files/:id',
+  responseType: 'blob',
 })
 
-// Only one network request is made; both callers get the same response
-const [a, b] = await Promise.all([
-  api.getProduct({ id: '42' }),
-  api.getProduct({ id: '42' })
-])
+const api = createApi({ baseUrl: '/api', requests: { uploadAvatar, downloadFile } })
 ```
 
-`share` is the sibling of `dedupe`, with the opposite intent: **dedupe cancels** the older call in favor of the newer one, **share joins** the existing call instead of starting a new one. Because the two behaviors contradict each other, setting both on the same `Request` throws at `createApi(...)` time — not at call time — so the mistake surfaces immediately rather than the first time the endpoint is called.
+Call it with `api.uploadAvatar(form)` and `api.downloadFile({ id })`. Other body types (a `Blob`, a `ReadableStream`) are listed under [Sending data](#sending-data).
 
-**What counts as "identical":** the request name plus a content-based key of the params — object keys sorted, `undefined` members dropped (so `{ a: undefined }` and `{}` are one key), anything with `toJSON` keyed by what it returns (a `Date` is its ISO string), `Map`, `Set` and typed arrays keyed by their entries. Two calls with the same params to the same endpoint share; different params (or different endpoints) never do.
+## Choosing liaise
 
-**What disables sharing for a single call:**
+This section helps you decide whether liaise fits your project. It covers when to pick something else, how liaise compares with other fetch clients, and where it runs.
 
-- A per-call `headers` or `middleware` — these change *what* is requested, so handing that caller another caller's response would be a real bug, not just a missed optimization. A call carrying either always gets its own, unshared request.
-- Params that cannot be keyed soundly, at any depth: a BigInt, an `ArrayBuffer`, `Blob`, `FormData` or `URLSearchParams`, a circular structure, or an object with no enumerable state (a class instance keeping its state in private fields, an `Error`). Two different values of these kinds would otherwise risk one key, and one caller could receive the response meant for the other's payload. Declining to share is always safe; handing back the wrong response never is. A `Date`, `Map`, `Set` or typed array is keyed by its content and shares normally, and a raw `string` keys distinguishably, so a string-param endpoint is coalesced like any other.
+### When it fits, and when it doesn't
 
-**What does *not* disable sharing:** a per-call `signal` or `timeout`. These bound *who is still waiting*, not *what is being asked for*, so they're tracked with a per-caller refcount instead: each sharer's own signal/timeout only removes that caller from the wait list. The underlying request keeps running for everyone else, and is only aborted once every sharer — including the one that gave up — has stopped waiting. A sharer that gives up gets an error `Result` (`kind: 'timeout'` or `kind: 'abort'`), reported to `onError` exactly as the identical non-shared call would be — which means a `'timeout'` give-up reports and an `'abort'` give-up does not (see [Error handling with `onError`](#error-handling-with-onerror)).
+Need a normalized cache (update one user, and every screen showing that user updates), optimistic updates or subscriptions? Use Apollo or urql. Apollo's [caching overview](https://www.apollographql.com/docs/react/caching/overview) and urql's [Graphcache docs](https://nearform.com/open-source/urql/docs/graphcache/) explain how each one caches. [Why another API client?](#why-another-api-client) covers the trade-off.
 
-**A per-*request* `timeout` is different: it belongs to the operation.** `RequestConfig.timeout` bounds the single shared request itself, measured from when that request started — not from when each caller joined it. Every sharer is therefore bounded by it, a late joiner cannot extend it, and a caller passing `timeout: 0` cannot switch it off for everyone else. Without that, a steadily arriving stream of joiners would keep one socket open indefinitely against a deadline that was supposed to cap it.
+For UI caching and refetching, use TanStack Query *with* liaise; see the [recipe](#use-with-tanstack-query).
 
-```ts
-const impatient = api.getProduct({ id: '42' }, { timeout: 20 })   // gives up quickly
-const patient = api.getProduct({ id: '42' })                      // keeps waiting
+For two or three calls, plain fetch is fine.
 
-// impatient's early timeout does not cancel the shared request —
-// patient still gets a real response.
-```
+liaise is a good fit when you have:
 
-**`result.retry()` on a shared result** re-runs the pipeline using the *acquiring caller's* own per-call options (headers, signal, timeout) — that is, whichever call first started the shared request, not whichever caller happens to invoke `retry()`. This falls out of every non-aborting sharer receiving the literal same `Result` object; it's unavoidable given that design, but worth knowing before relying on it.
+- **Many endpoints with one auth setup.** Each endpoint is one [`defineRequest`](#defining-endpoints), and one [auth middleware](#add-an-auth-header-and-refresh-the-token-on-a-401) covers them all.
+- **Failure handling that matters**, such as a checkout or a form. Every failure comes back as a value with a [kind you can switch on](#handling-errors).
+- **One API layer shared across frameworks, servers and scripts.** See [Where it runs](#where-it-runs).
 
-**Signal-replacing middleware is safe under `share: true`.** A middleware that installs its own `ctx.request.signal` (a per-attempt timeout, say) does not detach the shared request from the refcount: the refcount signal is merged back in before `fetch`, so the request is still aborted once every sharer has given up.
+### How it compares
 
-### TypeScript
+[`compare/`](https://github.com/iremlopsum/liaise/blob/main/compare) runs fetch, axios, ky, ofetch and liaise through ten failure scenarios against a local server, and records what the calling code gets back. [compare/README.md](https://github.com/iremlopsum/liaise/blob/main/compare/README.md) explains the fairness rules. If you maintain one of these libraries and think its setup is unfair, a pull request is welcome.
 
-Type inference flows automatically from `Request` generics through `createApi` to the call site. You never annotate the API methods manually.
+<!-- compare:start -->
 
-```ts
-// 1. Types are declared on the Request
-const getUser = new Request<{ id: string }, User>({
-  method: 'GET',
-  path: '/users/:id'
-})
+Measured on 4 October 2026 against axios 1.20.0, ky 2.1.0 and ofetch 1.5.1. Other libraries change. Rerun it with `npm run build` in the repo root, then `npm install && npm run compare` in `compare/`. Run in Node 22.18.0 against a local server. In browsers axios uses XHR, so its results there can differ.
 
-// 2. createApi infers method signatures from the requests record
-const api = createApi({
-  baseUrl: '/api',
-  requests: { getUser }
-})
+| Scenario | fetch | axios | ky | ofetch | liaise |
+| --- | :-- | :-- | :-- | :-- | :-- |
+| Server answers 500 | throws Error* | throws AxiosError | throws HTTPError | throws FetchError | error result (http) |
+| Server unreachable | throws TypeError* | throws AxiosError (name: Error) | throws NetworkError | throws FetchError | error result (network) |
+| Server never answers | throws TimeoutError, 3002 ms* | throws AxiosError, 3005 ms | throws TimeoutError, 3005 ms | throws FetchError, 3003 ms | error result (timeout), 3003 ms |
+| 200 with broken JSON | throws SyntaxError* | throws AxiosError (name: SyntaxError) | throws SyntaxError | throws SyntaxError | error result (parse) |
+| 204 with no body, on a JSON call | resolves with undefined* | resolves with "" | resolves with undefined | resolves with undefined | resolves with undefined |
+| Search as you type: which results stay on screen | shows "rea"* | shows "rea"* | shows "rea"* | shows "rea"* | shows "rea" |
+| Five requests get a 401 at once | 1 refresh call, 5/5 succeed* | 1 refresh call, 5/5 succeed* | 1 refresh call, 5/5 succeed* | 1 refresh call, 5/5 succeed* | 1 refresh call, 5/5 succeed* |
+| Slow 503s, 3 s deadline, 3 retries: when does the caller hear back | after 3.0s: throws TimeoutError, 3 attempts* | after 3.0s: throws CanceledError, 3 attempts* | after 3.0s: throws TimeoutError, 3 attempts | after 3.0s: throws FetchError, 3 attempts* | after 3.0s: error result (timeout), 3 attempts |
+| Path param is undefined | requests /s/users/undefined | requests /s/users/undefined | requests /s/users/undefined | requests /s/users/undefined | refused before sending: error result (network) |
+| Response is missing a field the type promises | — | — | throws SchemaValidationError | — | error result (parse) |
 
-// 3. Call site is fully typed -- no annotations needed
-const { data, error } = await api.getUser({ id: '42' })
-//      ^? User | null
-```
+\* needed hand-written code, described in the [notes](https://github.com/iremlopsum/liaise/blob/main/compare/results.md#notes). — means the library has no built-in option.
 
-The inference chain works like this:
+Out of the box, liaise has no timeout (only ky has one by default) and treats a 204 on a JSON call as a parse error. See Table B in [compare/results.md](https://github.com/iremlopsum/liaise/blob/main/compare/results.md).
 
-- `Request<TParams, TResponse>` carries the type info.
-- `createApi` uses internal conditional types to pull the `TParams` and `TResponse` generics from each `Request` instance.
-- A mapped type transforms the requests record into callable methods: each key becomes `(params: TParams, options?: CallOptions) => Promise<Result<TResponse>>`.
-- When `TParams` is `Record<string, never>` (no params), the params argument becomes optional.
+| Library | gzip (kB) | brotli (kB) |
+| --- | :-- | :-- |
+| fetch | 0.1 | 0.1 |
+| axios | 19.1 | 17.3 |
+| ky | 9.6 | 8.5 |
+| ofetch | 4.0 | 3.6 |
+| liaise | 5.8 | 5.2 |
+| liaise + retryMiddleware | 6.3 | 5.7 |
 
-All exported types are available for annotation when needed:
+fetch is built into the runtime; its row is the call site only, the floor rather than a library.
 
-```ts
-import type {
-  Result,
-  CallOptions,
-  Middleware,
-  MiddlewareContext,
-  MiddlewareNext,
-  RequestConfig,
-  ApiConfig
-} from 'liaise'
-```
+Request overhead on localhost, sequential (median requests per second): fetch 16,797, axios 13,691, ky 13,742, ofetch 16,230, liaise 16,414.
 
-## GraphQL Client
+Out-of-the-box results, request overhead in full and the notes: [compare/results.md](https://github.com/iremlopsum/liaise/blob/main/compare/results.md).
 
-Use `createGraphQL` when your backend speaks GraphQL. **Everything in the REST API section applies here too** — `retryMiddleware`, `cacheMiddleware`, `logMiddleware`, `dedupe`, per-call `signal`, `onError`, `retry()`, `skipMiddleware`, header merging — all of it works identically for GraphQL operations. The only difference is transport: every operation is sent as an HTTP POST with `{ query, variables }`.
+<!-- compare:end -->
 
-Both clients return the same `Result<T>` shape — `result.data`, `result.error`, `result.response`, and `result.retry` work identically.
+With enough of your own code, every library gets the right result in almost every row. The difference is how much you write. Counting the cells marked `*`, fetch needs 8, axios 3, ofetch 3, ky 2 and liaise 1. liaise needs code only for the token refresh, and returns each failure as a value instead of throwing. It is the only one that refuses an undefined path param before sending the request.
 
-```ts
-import { createGraphQL, Operation, gql } from 'liaise'
+ky is the closest alternative. Apart from throwing instead of returning errors, it differs from liaise in two rows of the table. Its search as you type needs code, and it sends the undefined path param. Out of the box, ky is the only one that times out, and it retries, as ofetch does. In size, liaise is larger than ofetch and smaller than ky and axios.
 
-interface Category {
-  id: string
-  name: string
-  status: string
-}
+In request overhead, liaise ties fetch and ofetch. axios and ky handle about 16% fewer requests per second than liaise. Overhead is measured in microseconds; on a real network each request takes milliseconds.
 
-const GET_CATEGORY = gql`
-  query GetCategory($id: String!) {
-    category(id: $id) {
-      id
-      name
-      status
-    }
-  }
-`
+### Where it runs
 
-const getCategory = new Operation<{ id: string }, Category>({
-  operation: GET_CATEGORY,
-})
+| Runtime | Status |
+| ------- | ------ |
+| Node 20, 22, 24 | Tested in CI |
+| Browsers, Bun, Deno, Cloudflare Workers | Should work (standard `fetch`), not tested in CI |
+| React Native | Uses its built-in `fetch`, not tested in CI |
 
-const graphql = createGraphQL({
-  endpoint: 'https://api.example.com/graphql',
-  operations: { getCategory },
-  onError: (error) => console.error(error.status, error.body),
-})
+On React Native, where `AbortSignal.timeout` is missing, `timeout` falls back to a timer. If the runtime drops abort reasons, a timeout may report as `'abort'` instead of `'timeout'`.
 
-const { data, error, response, retry } = await graphql.getCategory({ id: '123' })
-```
+No hooks, no framework code: a client is a plain object of functions returning promises. It works in React, Vue, Svelte, Solid, Angular, server loaders, workers and scripts. The [recipes](#recipes) show it with TanStack Query, React and a store.
 
-Operations with no variables can be called without arguments. Use `Record<string, never>` as `TVariables` to mark an operation as variable-free:
+## Design principles
 
-```ts
-const getViewer = new Operation<Record<string, never>, ViewerData>({ operation: GET_VIEWER })
-const graphql = createGraphQL({ endpoint, operations: { getViewer } })
+### Never throws
 
-const { data } = await graphql.getViewer() // params argument is optional
-```
+A thrown error doesn't show up in a function's type, so nothing reminds you to catch it, and one missed `try` breaks the page. A returned error is part of the type. TypeScript makes you check `error` before you can read `data`, and every failure arrives in the same shape.
+
+### Zero dependencies
+
+Every dependency of liaise would also be a dependency of your app, with more to download, audit and update. liaise uses only what the runtime already has: `fetch`, `Headers`, `AbortController` and the other web types. Validators plug in through Standard Schema, which is only an interface, so schema support adds no package either. The size of each entry point is under [Exports](#exports).
+
+### Middleware over interceptors
+
+Separate request and response interceptors split one job in two. State both halves need rides on the request config, and resending means calling the client again from inside a hook. A middleware wraps the whole call, so one function can set a header, read the result, retry, or answer from a cache. The built-in retry, cache and log are ordinary middleware, so anything they do, yours can do too.
+
+### Types by inference
+
+Types you write at each call site drift away from the endpoint they describe. In liaise you write the types once, on the endpoint, and the path supplies the path params. `createApi` carries them to every call, so a renamed param or a changed response is a compile error where it is used.
+
+### Any runtime
+
+liaise needs only `fetch` and the standard web types, so one client works in a browser, on a server, in a worker or in a script. Code that moves between them needs no second client and no adapter. [Where it runs](#where-it-runs) lists what CI tests.
+
+### Any framework
+
+A client is a plain object of functions that return promises. That fits every UI framework, and code with no framework at all, and there is nothing to rewrite when you switch. Query libraries expect a failed call to throw, so you convert at that one edge, as the [TanStack Query recipe](#use-with-tanstack-query) does.
 
-### Queries and mutations
+## Reference
 
-When you want to distinguish queries from mutations in the client structure, use the `queries` and `mutations` keys instead of `operations`. The `operations` flat shape and the `queries`/`mutations` split are mutually exclusive — TypeScript enforces this at compile time.
+Every option, type and export, read from the source. The guide explains when to use each one.
+
+### createApi options
+
+`createApi(config)` takes an `ApiConfig`.
+
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `baseUrl` | `string` | required | Goes in front of every endpoint's path. It may carry a query string ([details](#baseurl-query-merging)). |
+| `requests` | an object of endpoints | required | Each key becomes a method on the client, such as `api.getUser`. |
+| `middleware` | `Middleware[]` | — | Runs on every call, before endpoint and call middleware. |
+| `headers` | `HeadersInit` | — | Sent with every call. An endpoint or a call can replace a header ([three levels](#three-levels-of-settings)). |
+| `onError` | `(error: ApiError) => void` | — | Called once per failed call, after all middleware. Never for `'abort'` ([details](#reporting-errors-with-onerror)). |
+
+### createGraphQL options
+
+`createGraphQL(config)` takes a `GraphQLBaseConfig`, plus either `operations` or `queries` and `mutations` ([Queries and mutations](#queries-and-mutations)).
+
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `endpoint` | `string` | required | The full URL of the GraphQL endpoint. |
+| `middleware` | `Middleware[]` | — | Runs on every operation, before operation and call middleware. |
+| `headers` | `HeadersInit` | — | Sent with every operation. An operation or a call can replace a header. |
+| `onError` | `(error: ApiError) => void` | — | Called once per failed call, GraphQL errors included. Never for `'abort'`. |
+
+### Endpoint options
+
+`defineRequest<T>()(config)` and `new Request(config)` take a `RequestConfig`.
+
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `method` | `'GET' \| 'POST' \| 'PUT' \| 'PATCH' \| 'DELETE'` | required | The HTTP method. |
+| `path` | `string` | required | The path after `baseUrl`. Each `:name` is filled from the params ([Defining endpoints](#defining-endpoints)). |
+| `middleware` | `Middleware[]` | — | Runs on every call to this endpoint, after client middleware. |
+| `headers` | `HeadersInit` | — | Sent with every call to this endpoint. Replaces the client's value for the same header. |
+| `responseType` | `'json' \| 'text' \| 'blob' \| 'arrayBuffer' \| 'formData' \| 'none'` | `'json'` | How the response body is read ([Reading responses](#reading-responses)). |
+| `schema` | `StandardSchemaV1` | — | Checks a 2xx body, and `data` becomes the schema's output ([Validating responses](#validating-responses)). |
+| `dedupe` | `boolean` | `false` | A new call cancels the one still running ([details](#drop-stale-calls-with-dedupe)). |
+| `share` | `boolean` | `false` | Identical calls join one request ([details](#sharing-identical-requests)). Can't be combined with `dedupe`. |
+| `bodyAs` | `'query' \| 'body'` | `'query'` for `GET` and `DELETE`, `'body'` for the rest | Where the params that aren't in the path go. |
+| `timeout` | `number` (ms) | no deadline | One deadline for the whole call, retries included ([details](#set-a-deadline-with-timeout)). |
+
+### Operation options
+
+`new Operation(config)` takes an `OperationConfig`.
+
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `operation` | `string` | required | The GraphQL document, sent as `query` in the body. |
+| `middleware` | `Middleware[]` | — | Runs on every call to this operation, after client middleware. |
+| `headers` | `HeadersInit` | — | Sent with every call to this operation. Replaces the client's value for the same header. |
+| `dedupe` | `boolean` | `false` | A new call cancels the one still running. |
+| `schema` | `StandardSchemaV1` | — | Checks the response's `data`. The response type stays explicit ([Validating responses](#validating-responses)). |
+| `timeout` | `number` (ms) | no deadline | One deadline for the whole call, retries included. |
+
+### CallOptions
+
+The second argument of every call, as in `api.getUser(params, options)`. [`paginate`](#pagination) takes the same options and applies them to every page.
+
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `middleware` | `Middleware[]` | — | Runs after the client's and the endpoint's middleware. Turns off `share` for this call. |
+| `skipMiddleware` | `Middleware[]` | — | Middleware to leave out of this call, matched by reference ([details](#skipping-a-middleware-for-one-call)). |
+| `headers` | `HeadersInit` | — | Replaces the client's and the endpoint's value for the same header. Turns off `share` for this call. |
+| `signal` | `AbortSignal` | — | Cancels the call, which ends with `kind: 'abort'` ([details](#cancel-with-a-signal)). |
+| `timeout` | `number` (ms) | the endpoint's `timeout` | Replaces the endpoint's deadline for this call. `0` turns it off. Under `share`, it bounds only this caller's wait ([details](#sharing-identical-requests)). |
+
+A fractional `timeout` is rounded down to whole milliseconds, with a minimum of 1 ms. A value above the timer limit of 2³¹ − 1 ms is capped there. Zero or a negative number means no deadline.
+
+### Result and ApiError
+
+Every call returns a `Result`. `data` and `error` are never both set, so checking `error` narrows `data`.
 
 ```ts
-const graphql = createGraphQL({
-  endpoint: 'https://api.example.com/graphql',
-  queries: {
-    getCategory: new Operation<{ id: string }, Category>({ operation: GET_CATEGORY }),
-  },
-  mutations: {
-    updateCategory: new Operation<{ id: string; name: string }, Category>({
-      operation: gql`
-        mutation UpdateCategory($id: String!, $name: String!) {
-          updateCategory(id: $id, name: $name) { id name status }
-        }
-      `,
-    }),
-  },
-})
+interface SuccessResult<TResponse> {
+  data: TResponse
+  error: null
+  response: Response                       // always present on success
+  retry: () => Promise<Result<TResponse>>
+}
 
-graphql.query.getCategory({ id: '123' })
-graphql.mutation.updateCategory({ id: '123', name: 'New Name' })
+interface ErrorResult<TResponse> {
+  data: null
+  error: ApiError
+  response: Response | null                // null when no response arrived
+  retry: () => Promise<Result<TResponse>>
+}
+
+type Result<TResponse> = SuccessResult<TResponse> | ErrorResult<TResponse>
 ```
 
-### GraphQL errors
+`response` is set for `'http'` and `'parse'` errors, where the server answered. It is `null` for `'network'`, `'abort'`, `'timeout'` and `'middleware'`.
 
-GraphQL errors (any 2xx with `{ errors: [...] }`) surface as `result.error` with the response's own `status` and `error.body` typed as `GraphQLError[]` — no special handling needed. The same `if (error) { ... }` check covers GraphQL errors, HTTP errors, and network errors uniformly.
+`ApiError` is the `error` of a failed call. It is a plain class and doesn't extend `Error`.
 
-GraphQL allows **partial success** -- a nullable field errors while the rest of the query resolves. That data is not discarded: it's available as `error.partialData`, never on `result.data` (which stays `null` whenever `error` is non-null, keeping `Result` a clean discriminated union):
+| Property | Type | What it holds |
+| -------- | ---- | ------------- |
+| `kind` | `ApiErrorKind` | What went wrong. The [kinds table](#handling-errors) says what each one means. If you build an `ApiError` yourself, for example in a middleware, `kind` is required. |
+| `status` | `number` | The response's status for `'http'` and `'parse'`. `0` for `'network'`, `'abort'`, `'timeout'` and `'middleware'`. |
+| `statusText` | `string` | The response's status text, `'GraphQL Error'` for a GraphQL error, and `''` when no response arrived. |
+| `body` | `unknown` | For `'http'`, the error body, or `null` when it is empty or doesn't parse. For `'parse'`, what the [Validating responses](#validating-responses) and [Reading responses](#reading-responses) rules say. Otherwise, the thrown value. |
+| `headers` | `Headers` | The response headers. Empty when no response arrived. |
+| `request` | `{ method, url, params }` | The failed request. `url` is the address with the params filled in. It is the path template only when the URL couldn't be built. |
+| `partialData` | `unknown` (optional) | For a GraphQL error, the data the server sent with the errors. `undefined` for every REST error. |
 
 ```ts
-const { error } = await graphql.getCategory({ id: '123' })
-if (error) {
-  console.log(error.body)          // GraphQLError[]
-  console.log(error.partialData)   // whatever `data` the server sent alongside the errors, or undefined
-}
+type ApiErrorKind = 'http' | 'network' | 'abort' | 'timeout' | 'parse' | 'middleware'
 ```
 
-GraphQL's own empty-success rule mirrors the REST client's: a 2xx response carrying neither `data` nor `errors` is `kind: 'parse'`, not a success with `data: null`. This covers an empty body, `{}`, a literal `{"data": null}`, and a non-object JSON root -- anything that reaches a 2xx without a `data` or `errors` key. `error.body` holds the raw response text, not a parsed value:
+You can check for an `ApiError` with `instanceof`:
 
 ```ts
-const { error } = await graphql.getCategory({ id: '123' })
-if (error) {
-  console.log(error.kind) // 'parse'
-  console.log(error.body) // raw response text, e.g. '' or '{}'
+import { ApiError } from 'liaise'
+
+if (error instanceof ApiError) {
+  console.error(error.kind, error.status)
 }
 ```
 
-A `{"data": null, "errors": [...]}` response is unchanged -- it's still `kind: 'http'`, with any partial result in `error.partialData`, since the GraphQL-errors branch runs first. See [MIGRATION.md](./MIGRATION.md#upgrading-to-400).
+### MiddlewareContext
 
-Operations support `dedupe: true` in the same way `Request` does — see [Auto-cancel via `dedupe`](#auto-cancel-via-dedupe).
+The first argument of every middleware, `ctx`:
 
-### Middleware
+| Property | Type | What it holds |
+| -------- | ---- | ------------- |
+| `request.method` | `string` | The HTTP method, such as `'GET'`. |
+| `request.url` | `string` | The full URL, with path params and query string filled in. |
+| `request.path` | `string` | The path template, such as `'/users/:id'`. |
+| `request.params` | `unknown` | The params as the caller passed them. |
+| `request.headers` | `Headers` | The merged headers. A middleware can add, change or remove them. |
+| `request.body` | `unknown` | The serialized body, or `null` when there is none. |
+| `request.signal` | `AbortSignal \| undefined` | The signal `fetch` receives. A middleware can replace it ([Signals in middleware](#signals-in-middleware)). |
+| `requestName` | `string` | The endpoint's key, such as `'getUser'`. |
 
-`createGraphQL` accepts the same middleware options as `createApi` — global, per-operation, and per-call — and the `MiddlewareContext` shape is identical, so middleware written for `createApi` works here too.
+How a replaced signal works with `share` and `dedupe` is under [Signal-replacing middleware](#signal-replacing-middleware).
 
-```ts
-const graphql = createGraphQL({
-  endpoint: 'https://api.example.com/graphql',
-  operations: { getCategory },
-  middleware: [authMiddleware],
-})
-```
+### Built-in middleware options
 
-### API Reference additions
+#### RetryOptions
 
-| Export              | Kind     | Description                                                            |
-| ------------------- | -------- | ---------------------------------------------------------------------- |
-| `createGraphQL`     | function | Creates a typed GraphQL client from a config of Operation definitions  |
-| `Operation`         | class    | Typed operation definition -- one instance per GraphQL operation       |
-| `gql`               | const    | Tagged template literal for GraphQL documents (editor tooling support) |
-| `OperationConfig`   | type     | Config object for the `Operation` constructor                          |
-| `GraphQLBaseConfig` | type     | Config object for `createGraphQL`                                      |
-| `GraphQLError`      | type     | Shape of a single GraphQL error from `{ errors: [...] }`               |
+`retryMiddleware(n)` is short for `retryMiddleware({ max: n })`, and `retryMiddleware()` means `{ max: 3 }`.
 
-## Testing
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `max` | `number` | `3` | Retries after the first attempt. `max: 2` means up to 3 calls in all. |
+| `delay` | `'exponential' \| 'linear' \| (attempt: number) => number` | `'exponential'` | The wait before each retry. Exponential is `baseDelay * 2^(attempt-1)` and linear is `baseDelay * attempt`. A function gets the 1-based attempt and returns milliseconds. |
+| `baseDelay` | `number` (ms) | `250` | The first wait, before jitter and `Retry-After`. |
+| `maxDelay` | `number` (ms) | `30000` | The longest any wait can be, a `Retry-After` value included. |
+| `jitter` | `boolean` | `true` | Waits a random time between 0 and the computed delay, so many clients don't retry at the same moment. Never applied to a `Retry-After` value. |
+| `respectRetryAfter` | `boolean` | `true` | Uses the server's `Retry-After` header, in seconds or as a date, in place of the computed wait. `maxDelay` still caps it. |
+| `retryOn` | `(result: Result<unknown>, attempt: number) => boolean` | `r => (r.error?.status ?? 0) >= 500` | Whether to retry. It gets the 1-based number of the attempt it would start, and is called even once `max` is reached. |
+| `onRetry` | `(info: RetryInfo) => void` | — | Called before each wait. Its return value is ignored, and if it throws, the call goes on. |
 
-`liaise/testing` is a separate, framework-agnostic entry point for testing consumers of this library — it has no test-runner dependency, so it works the same under Vitest, Jest, or anything else. It gives you a `fetch` stub with route matching, so your tests exercise the real pipeline — URL building, path substitution, header merging, body serialization, response parsing, your own middleware — rather than stubbing an API method to return a canned `Result` and silently drifting out of sync with what the library actually does.
+`RetryInfo`, the argument to `onRetry`:
 
-```ts
-import { mockFetch, jsonResponse } from 'liaise/testing'
+| Field | What it holds |
+| ----- | ------------- |
+| `attempt` | The retry about to run, counting from 1. |
+| `max` | The configured `max`. |
+| `delay` | The wait about to start, in milliseconds, after jitter and `Retry-After`. |
+| `result` | The `Result` that caused this retry. |
 
-const mock = mockFetch({
-  'GET /api/users/:id': ({ params }) => jsonResponse({ id: params.id, name: 'Ada' }),
-  'POST /api/users': jsonResponse({ id: 'new-user' }, { status: 201 }),
-})
+#### Cache options
 
-mock.install()   // replaces globalThis.fetch
-// ... exercise your code, which calls the real api.getUser(...) ...
-mock.restore()    // puts the original globalThis.fetch back
-```
+`cacheMiddleware(options)` returns a middleware with a `clear()` method, typed `CacheMiddleware`.
 
-Routes are keyed as `"METHOD /path"`, with `:token` segments captured and handed to a route function as `{ params, request }`. A route value can also be a plain `Response` (built with the `jsonResponse` helper, or your own), or an array of either — the array is consumed one response per matching call, and the final entry repeats once exhausted (handy for "fail twice, then succeed").
+| Option | Type | Default | What it does |
+| ------ | ---- | ------- | ------------ |
+| `ttl` | `number` (ms) | `300000` (5 minutes) | How long an entry is served. An expired entry is removed when it is next read. |
+| `maxSize` | `number` | `50` | How many entries the store keeps. When it is full, the oldest entry is dropped. |
+| `debug` | `boolean` | `false` | Logs `[liaise cache] HIT` or `MISS`, with the endpoint and its params, to the console. |
 
-```ts
-const mock = mockFetch({
-  'GET /api/flaky': [jsonResponse(null, { status: 503 }), jsonResponse({ ok: true })],
-})
+What goes into the key is under [Cache key](#cache-key).
+
+#### Log output
+
+`logMiddleware` logs one line when a call starts and one when it ends:
+
+```text
+[liaise] → <method> <endpoint> <url>
+[liaise] ← <endpoint> OK (<ms>ms)
+[liaise] ← <endpoint> ERROR <status> (<ms>ms)
 ```
 
-`mock.calls` records every request (`{ method, url, headers, body }`); `mock.callCount('GET /api/users/:id')` and `mock.lastCall(...)` key off the same `"METHOD /path"` strings as the routes object.
+The time covers everything that runs inside it: the middleware after it and the request. An error with no response logs status `0`.
+
+### liaise/testing
+
+| Export | Kind | What it is |
+| ------ | ---- | ---------- |
+| `mockFetch` | function | Builds a `fetch` stub that matches routes, with `install()`, `restore()`, call recording and response sequences. |
+| `jsonResponse` | function | Builds a `Response` with a JSON body and a `content-type` header. |
+| `successResult` | function | Builds a success `Result`, for stubbing at the `Result` level. |
+| `errorResult` | function | Builds an error `Result` with a given HTTP status, for stubbing at the `Result` level. |
+| `RouteContext` | type | `{ params, request }`, passed to a route function. |
+| `RouteHandler` | type | `(ctx: RouteContext) => Response \| Promise<Response>`, a route value that builds its response. |
+| `RouteValue` | type | `Response \| RouteHandler \| Array<Response \| RouteHandler>`, anything a route key can map to. |
+| `RecordedCall` | type | `{ method, url, headers, body }`, one entry in `mock.calls`. |
+
+How the stub behaves, beyond [Testing your code](#testing-your-code):
+
+- **It honours `init.signal`, like real `fetch`.** A signal that is already aborted, or aborts while a route function is still pending, rejects with its `reason`. So a route that never answers, `() => new Promise(() => {})`, lets you test your own `timeout` and cancel handling.
+- **An aborted call is still recorded** in `calls` and counted by `callCount`, but it doesn't use up a response from a sequence.
+- **`restore()` puts back whatever `globalThis.fetch` was when `install()` ran.** If it was `undefined`, `restore()` puts back `undefined`.
+- **A route key without a space**, such as `'/users'`, throws when you call `mockFetch`, and the message names the key.
+- **Routes are tried in the order you wrote them**, and the first match wins. Put the more specific route first when two could match the same path.
+- **Trailing and doubled slashes are ignored on both sides.** `/a/b/`, `/a//b` and `/a/b` all match the same route.
+
+### Exports
+
+Each entry point is a separate import, and your bundler leaves out what you don't import. Gzipped, as measured by `npm run size`: about 5.8 kB for a REST-only import, 6.9 kB for the whole core entry, and 8.0 kB with all the middleware.
+
+**`liaise`**
 
-An unmatched request makes the stub throw rather than invent a 404 — a mocked test should not quietly pass for a typo'd path. Note what your code actually sees, though: the library catches every `fetch` rejection by design, so that throw arrives as an ordinary `Result` with `error.kind === 'network'` and the `Error` itself as `error.body`, whose message names the method, the URL, and every route that was defined. Assert on the result (or read it in `onError`); do not expect the call to reject.
+| Export | Kind | What it is |
+| ------ | ---- | ---------- |
+| `createApi` | function | Creates a REST client from your endpoints. |
+| `defineRequest` | function | Defines an endpoint, with params checked against the path. |
+| `Request` | class | The endpoint class that `defineRequest` builds ([Without defineRequest](#without-definerequest)). |
+| `paginate` | function | Walks a paginated endpoint, one `Result` per page. |
+| `ApiError` | class | The `error` of a failed call. |
+| `createGraphQL` | function | Creates a GraphQL client from your operations. |
+| `Operation` | class | Defines one GraphQL operation. |
+| `gql` | function | Marks a template string as GraphQL for your editor, and returns it as a plain string. |
+| `Result`, `SuccessResult`, `ErrorResult` | type | What every call returns, and its two branches. |
+| `ApiErrorKind` | type | The union of `error.kind` values. |
+| `CallOptions` | type | The second argument of a call. |
+| `PaginateOptions` | type | `next`, `maxPages`, and any `CallOptions`. |
+| `ApiConfig`, `RequestConfig` | type | The configs of `createApi` and an endpoint. |
+| `GraphQLBaseConfig`, `OperationConfig` | type | The configs of `createGraphQL` and an `Operation`. |
+| `GraphQLError` | type | One entry of a GraphQL `errors` array. |
+| `Middleware`, `MiddlewareContext`, `MiddlewareNext` | type | A middleware, its `ctx`, and its `next`. |
+| `StandardSchemaV1`, `InferOutput`, `StandardIssue` | type | The Standard Schema interface, the type a schema produces, and one validation issue. |
+
+**`liaise/middleware`**
+
+| Export | Kind | What it is |
+| ------ | ---- | ---------- |
+| `retryMiddleware` | function | Returns a middleware that retries failed calls ([RetryOptions](#retryoptions)). |
+| `cacheMiddleware` | function | Returns a middleware that caches successes in memory ([Cache options](#cache-options)). |
+| `logMiddleware` | middleware | Logs each call to the console ([Log output](#log-output)). |
+| `RetryOptions`, `RetryInfo` | type | The options of `retryMiddleware`, and the argument to `onRetry`. |
+| `CacheMiddleware` | type | What `cacheMiddleware()` returns, a `Middleware` with `clear()`. |
+
+**`liaise/testing`** exports are listed under [liaise/testing](#liaisetesting).
+
+### Behaviour in detail
+
+Edge cases the guide links to.
+
+#### Cache key
+
+`cacheMiddleware` keys each entry on the endpoint name, the method, the full URL, the params and every request header except `Content-Type`. A different `Authorization`, base URL or query value gets its own entry.
+
+The query string is sorted by name before it goes in the key, so `?a=1&b=2` and `?b=2&a=1` are one entry. It is sorted by the raw, undecoded name, and repeated names keep their order. A query param that a middleware adds before the cache, such as `?lang=de`, is part of the key.
+
+Params are keyed by content, by the same rules as [`share`](#share-key-and-refcount). Params that `share` can't compare are never cached and never served from the cache. Each `cacheMiddleware()` call makes its own store, so two stores never share entries.
+
+#### Share key and refcount
+
+Two calls share when they go to the same endpoint and their params have the same key. The key is built from content. Object keys are sorted, and an `undefined` member is dropped, so `{ a: undefined }` and `{}` match. A value with a `toJSON` method is keyed by what it returns, so a `Date` is its ISO string. A `Map`, `Set` or typed array is keyed by its entries.
+
+A call can't share when its params hold any of these, at any depth:
+
+- a BigInt
+- a function or a symbol
+- an `ArrayBuffer`, `Blob`, `FormData` or `URLSearchParams`
+- a boxed primitive, such as `new String('a')`
+- a circular structure
+- an object with no enumerable keys that isn't a plain object, such as an `Error`, a `Promise`, or a class instance that keeps its state in private fields
+
+Per-call `headers: {}` and `middleware: []` are empty, so they don't turn sharing off. Only a header or a middleware that is actually there does.
+
+Each caller holds a place in the shared request, counted by a refcount. A caller whose own `signal` or `timeout` fires gives up its place. What happens when every caller has given up, and what the caller who leaves receives, is under [Sharing identical requests](#sharing-identical-requests).
+
+The endpoint's `timeout` counts from when the shared request started. If each new caller restarted it, a steady stream of callers could keep one request open forever.
+
+#### `retry()` on a shared result
+
+Every caller that waits to the end gets the same `Result` object. Its `retry()` uses the per-call options of the caller that started the shared request (its headers, signal and timeout), whoever calls it. A retry is never shared. It sends a request of its own.
+
+#### Signal-replacing middleware
+
+A middleware can replace `ctx.request.signal`, as [Give each attempt its own timeout](#give-each-attempt-its-own-timeout) shows. Under `share`, liaise merges the signal that tracks the callers back in before `fetch`. The shared request is still cancelled once every caller has given up.
+
+Under `dedupe`, liaise merges the dedupe signal into yours the same way, so the request ends when either one fires. The dedupe signal is added when `fetch` is called. A middleware that reads `ctx.request.signal` before `next()` sees only the caller's signal and the deadline.
+
+#### Timeout backstop
+
+A middleware may wait on work of its own before it calls `next()`, such as a token refresh. If that work never settles, the call still ends at its deadline. Here `user` stands for your auth client:
 
 ```ts
-const r = await api.getUser({ id: '42' })   // routes only define 'GET /api/user/:id'
-expect(r.error?.kind).toBe('network')
-expect(String(r.error?.body)).toMatch(/no route matched GET \/api\/users\/42/)
+const auth: Middleware = async (ctx, next) => {
+  const token = await user.getIdToken() // stalls on a bad network
+  ctx.request.headers.set('Authorization', `Bearer ${token}`)
+  return next()
+}
+// With timeout: 45_000, the call still settles after about 45 s: kind 'timeout', status 0.
 ```
 
-An empty response array for a route behaves the same way — a descriptive `Error` reaching you as `error.body`, not a bare `TypeError`.
+When the deadline passes, the chain gets one macrotask to answer on its own. That is enough for anything that already reacts to the abort: `fetch` rejecting, a middleware rethrowing the reason, or a fallback that turns a timeout into a cached response. Each of those keeps its own `Result`.
 
-For stubbing at the `Result` level instead of the `fetch` level, `successResult(data)` and `errorResult(status, body)` build a well-formed `Result` directly (shown here with Vitest's `vi.spyOn`, but any runner's equivalent works the same way):
+A chain still waiting after that is stuck on something the signal doesn't reach. The call then settles with `kind: 'timeout'` and `status: 0`, and `onError` is called once. A caller's `signal` works the same way, with `kind: 'abort'`, which `onError` never sees.
 
-```ts
-import { successResult, errorResult } from 'liaise/testing'
+The stuck middleware keeps running, because a promise can't be cancelled. Whatever it returns or throws later is discarded, with no second `Result` and no second `onError`. If it calls `next()` after the call has settled, nothing is sent, and `next()` returns the `Result` the caller already has.
 
-vi.spyOn(api, 'getUser').mockResolvedValue(successResult({ id: '42', name: 'Ada' }))
-vi.spyOn(api, 'getUser').mockResolvedValue(errorResult(404, { message: 'not found' }))
-```
+#### Abort classification
 
-A few behaviors worth knowing:
+liaise decides whether a failure is a cancellation by checking whether this call's own signal aborted. The thrown value's name and type don't matter. A custom reason, such as `controller.abort(new Error('unmounted'))` or a plain string, still gives `kind: 'abort'`, and a deadline gives `'timeout'`.
 
-- **`mock.fetch` honours `init.signal`, like real `fetch`.** An already-aborted signal rejects with its `reason`, and so does one that aborts while a route handler is still pending — so a stalled route (`() => new Promise(() => {})`) lets you test your own `timeout` and cancellation handling through the stub. An aborted call is still recorded in `calls` and counted by `callCount`, but does not use up a response from a sequence.
-- **`restore()` assumes `globalThis.fetch` was defined when `install()` ran** — true on Node 20+ (and in every browser), since `fetch` is a global there. If you somehow call `install()` in an environment where `globalThis.fetch` is `undefined` beforehand, `restore()` puts back that `undefined` rather than inventing a real `fetch`.
-- **A route key must be `"METHOD /path"`.** A key with no space (`'/users'`) throws at `mockFetch(...)` time, naming the offending key, rather than silently registering a route that can never match.
-- **Declaration order decides when two same-length routes could both match.** Routes are matched in the order they appear in the object you pass to `mockFetch`, and the first structural match wins — put more specific routes first if two patterns could both match the same path.
-- **Trailing and duplicate slashes are normalized away on both sides.** `/a/b/`, `/a//b`, and `/a/b` all match the same route, whether the extra slash is in the route key or in the URL the library actually built.
+A middleware that rethrows liaise's own abort or timeout reason, as it is or wrapped once as the `cause` of another error, gives `'abort'` or `'timeout'` too. Anything else a middleware throws is `'middleware'`.
 
-## Philosophy
+#### baseUrl query merging
 
-### Never throws
+A `baseUrl` can carry its own query string, such as a fixed `api-version`. Its params go in front of the call's:
 
-Every API call returns a `Result<T>`. HTTP errors, network failures, parse errors, and even synchronous exceptions during request setup are all captured and returned as structured `{ data, error, response, retry }` objects. No try/catch required at call sites.
+```ts
+import { createApi, defineRequest } from 'liaise'
 
-### Zero dependencies
+type Hit = { id: string }
 
-The library uses only the standard `fetch` API and built-in web platform types (`Headers`, `AbortController`, `FormData`, `URLSearchParams`, `Blob`, `ArrayBuffer`). There is nothing to install, audit, or bundle beyond the library itself.
+const search = defineRequest<Hit[], { q: string }>()({ method: 'GET', path: '/search' })
+const api = createApi({ baseUrl: 'https://api.example.com/v1?api-version=2', requests: { search } })
 
-### Middleware over interceptors
+await api.search({ q: 'hello' })
+// GET https://api.example.com/v1/search?api-version=2&q=hello
+```
 
-Instead of separate `onRequest`/`onResponse` interceptor hooks, the library uses a composable onion model where each middleware wraps the next. This means a single function can modify the request, inspect the response, retry on failure, or short-circuit entirely. Three layers (global, per-request, per-call) plus `skipMiddleware` give fine-grained control without configuration complexity.
+A key that appears in both is sent twice. A call param named `api-version` gives `?api-version=2&api-version=3`, and the server decides which one counts. Headers merge by name, but query params can't, because an array param is already sent as repeated keys (`tags=a&tags=b`). To change a base param on each call, set it in a middleware.
 
-### Typed dot-access
+The full URL, base query included, appears in `ctx.request.url`, `error.request.url` and `logMiddleware`'s output, so anything that logs or reports it sends that query too. Put a secret in a header instead.
 
-Type safety comes from inference, not annotation. Define `Request<TParams, TResponse>` once, and `createApi` infers everything downstream. The call site (`api.getUser(...)`) is fully typed with zero extra work.
+#### URL fragments
 
-### Runtime-agnostic
+A `#` written into a `path` or a `baseUrl` is refused, because a fragment is never sent to the server. The call returns an error with `kind: 'network'` and a `TypeError` in `error.body` that names the value. Nothing is sent. liaise refuses the fragment instead of stripping it, so the dead part doesn't stay in your code.
 
-No assumptions about Node.js, browsers, or any specific runtime. If your environment has `fetch`, the library works -- browsers, Node.js 20+, Bun, Deno, React Native (its built-in `fetch`; not tested in CI), Cloudflare Workers, edge runtimes. Where `AbortSignal.timeout` is missing (React Native's Hermes), `timeout` falls back to `AbortController` plus `setTimeout`; the failure is `kind: 'timeout'` where the runtime's `AbortController` carries abort reasons, and possibly `'abort'` where it does not. Not tested on a device.
+`defineRequest` also refuses a fragment in a `path` literal, at compile time:
 
-### Framework-agnostic
+```ts
+defineRequest<Doc>()({ method: 'GET', path: '/docs#section' })
+//                                          ^ Property '__fragmentInPath' is missing:
+//                                            a URL fragment is never sent to the server
+```
 
-The library has no opinion about your UI framework, or whether you have one. A client is a plain object of functions that return promises, so the same definitions work in React, Vue, Svelte, Solid or Angular, in server loaders and actions, in workers, scripts and CLIs — and keep working when you change frameworks. It also means there are no hooks out of the box: pair it with the state or query library you already use (TanStack Query, SWR, Pinia, a store of your own). Those libraries expect a failed request to throw, so the query function is the place to turn a `Result`'s `error` into a throw — at the edge of your code, not inside this library.
+The check reads the literal. A path built at runtime, or a variable typed as `RequestConfig`, still compiles and is refused when it is called. `new Request` has no compile-time check.
 
-## API Reference
+A `#` inside a param value is data. It is escaped to `%23` and sent:
 
-### Core (`liaise`)
+```ts
+await api.getDoc({ id: 'a#b' })   // GET /docs/a%23b
+await api.search({ tag: 'a#b' })  // GET /search?tag=a%23b
+```
 
-| Export          | Kind     | Description                                                        |
-| --------------- | -------- | ------------------------------------------------------------------ |
-| `createApi`     | function | Creates a typed API client from a config of Request definitions    |
-| `Request`       | class    | Typed endpoint definition -- one instance per endpoint             |
-| `defineRequest` | function | Typed factory — infers path params from the `path` literal, and enforces `responseType: 'none'`. |
-| `paginate` | function | Walks a paginated endpoint, yielding one `Result` per page. |
-| `PaginateOptions` | type | `next`, `maxPages`, and any `CallOptions`. |
-| `StandardSchemaV1` | type | The Standard Schema contract — for typing a helper that takes a validator. |
-| `InferOutput`      | type | The type a schema produces on success. |
-| `StandardIssue`    | type | One validation failure -- the shape of each entry in `error.body` when a schema refuses. |
-| `ApiError`      | class    | Structured error with status, kind, body, headers, and request metadata |
-| `ApiErrorKind`  | type     | `'http' \| 'network' \| 'abort' \| 'timeout' \| 'parse' \| 'middleware'` -- discriminates `ApiError.kind` |
-| `RequestConfig` | type     | Config object for the `Request` constructor                        |
-| `ApiConfig`     | type     | Config object for `createApi`                                      |
-| `CallOptions`   | type     | Per-call overrides (`middleware`, `skipMiddleware`, `headers`, `signal`, `timeout`) |
-| `Result`        | type     | Discriminated union of every API call's outcome: `SuccessResult<T> \| ErrorResult<T>` |
-| `SuccessResult` | type     | The success branch of `Result`: `{ data: T, error: null, response: Response, retry }` |
-| `ErrorResult`   | type     | The error branch of `Result`: `{ data: null, error: ApiError, response: Response \| null, retry }` |
-| `Middleware`    | type     | Middleware function signature: `(ctx, next) => Promise<Result>`    |
-| `MiddlewareContext` | type | Request context passed to middleware                               |
-| `MiddlewareNext` | type    | The `next` function passed to middleware                           |
-| `createGraphQL`     | function | Creates a typed GraphQL client from a config of Operation definitions  |
-| `Operation`         | class    | Typed operation definition -- one instance per GraphQL operation       |
-| `gql`               | const    | Tagged template literal for GraphQL documents (editor tooling support) |
-| `OperationConfig`   | type     | Config object for the `Operation` constructor                          |
-| `GraphQLBaseConfig` | type     | Config object for `createGraphQL`                                      |
-| `GraphQLError`      | type     | Shape of a single GraphQL error from `{ errors: [...] }`              |
-
-### Built-in middleware (`liaise/middleware`)
-
-| Export            | Kind     | Description                                                   |
-| ----------------- | -------- | ------------------------------------------------------------- |
-| `retryMiddleware` | function | Factory that returns middleware retrying on 5xx by default, with a configurable backoff policy |
-| `RetryOptions`    | type     | Options object accepted by `retryMiddleware` (`max`, `delay`, `baseDelay`, `maxDelay`, `jitter`, `respectRetryAfter`, `retryOn`, `onRetry`) |
-| `RetryInfo`       | type     | Shape of the argument passed to `RetryOptions.onRetry`         |
-| `logMiddleware`   | const    | Middleware that logs request lifecycle to the console          |
-| `cacheMiddleware` | function | Factory that returns a per-request in-memory cache with `clear()` |
-| `CacheMiddleware` | type     | Return type of `cacheMiddleware()` -- a `Middleware` with an attached `clear()` |
-
-### Testing (`liaise/testing`)
-
-| Export          | Kind     | Description                                                        |
-| --------------- | -------- | ------------------------------------------------------------------ |
-| `mockFetch`     | function | Builds a route-matching `fetch` stub, with `install()`/`restore()`, call recording, and response sequencing |
-| `jsonResponse`  | function | Builds a `Response` with a JSON body and a `content-type` header, for use as a route value |
-| `successResult` | function | Builds a well-formed success `Result<T>` directly, for stubbing at the `Result` level |
-| `errorResult`   | function | Builds a well-formed error `Result<T>` with a given HTTP status, for stubbing at the `Result` level |
-| `RouteContext`  | type     | `{ params, request }` passed to a route handler function          |
-| `RouteHandler`  | type     | `(ctx: RouteContext) => Response \| Promise<Response>` -- a route value that computes its response |
-| `RouteValue`    | type     | `Response \| RouteHandler \| Array<Response \| RouteHandler>` -- anything a route key can map to |
-| `RecordedCall`  | type     | `{ method, url, headers, body }` -- shape of each entry in `mock.calls` |
-
-## Contributing
-
-Bug reports, fixes and ideas are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to report a bug, run the tests, and the few rules a pull request is checked against.
-
-## License
-
-MIT
+#### Stream bodies
+
+A `ReadableStream` body is used up as it is sent, so liaise can't send it again. A second attempt, from `retryMiddleware` or `result.retry()`, returns `kind: 'network'` and `status: 0`, with a `TypeError` that tells you to read the stream into a `Blob` or `ArrayBuffer` first. Under `retryMiddleware` that error is the final `Result`, so the 5xx that caused the retry isn't in it.
+
+#### Empty bodies
+
+- **A 2xx with an empty body under `'json'`** is a `'parse'` error ([Reading responses](#reading-responses)), and its `Result` still has `retry()`.
+- **A non-2xx with an empty body** is an ordinary `'http'` error with `error.body` set to `null`. So is a non-2xx whose JSON body doesn't parse, such as an HTML page from a gateway. Nobody promised a body on failure, so neither is a `'parse'` error.
+- **On GraphQL**, a 2xx with neither `data` nor `errors` is a `'parse'` error with the raw text in `error.body` ([GraphQL errors](#graphql-errors)). That includes a root of `null`, a number or an array. Each is valid JSON, but GraphQL requires an object.
+
+## Upgrading, contributing, licence
+
+- **Upgrading.** [MIGRATION.md](./MIGRATION.md) says what to change when an upgrade needs it. [CHANGELOG.md](./CHANGELOG.md) lists every release.
+- **Contributing.** Bug reports, fixes and ideas are welcome. [CONTRIBUTING.md](./CONTRIBUTING.md) explains how to report a bug, run the tests, and the few rules a pull request is checked against.
+- **Licence.** MIT, in [LICENSE](./LICENSE).