liaise 5.0.0 → 5.0.2

package/CHANGELOG.md

@@ -5,6 +5,98 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.0.2] — 2026-10-04
+
+### Fixed
+
+- **A path parameter with no usable value is refused instead of sent.** A token
+  was filled with `String(value)` unchecked, so `getUser({ id: undefined })` on
+  `/users/:id` fetched `/users/undefined`, and `null`, `''`, an object or an array
+  built `/users/null`, `/users/`, `/users/%5Bobject%20Object%5D` or `/users/1%2C2`.
+  The usual cause is a component rendering before the id has loaded. Such a call
+  now returns an error Result (`kind: 'network'`, a `TypeError` naming each bad
+  param, e.g. `Path parameter "id" is undefined in path "/users/:id", so the call
+  was not sent.`) and nothing reaches the server. Accepted values are non-empty
+  strings, finite numbers, bigints and booleans; a `Date` is refused with a hint
+  to convert it first (`toISOString()` or `getTime()`), as in a query string.
+  `NaN` and `Infinity` are refused too. See
+  [MIGRATION.md](./MIGRATION.md#upgrading-to-502).
+
+### Changed
+
+- The README's size figures are re-measured with `npm run size`: about 5.8 kB
+  gzipped for a REST-only import, 6.9 kB for the core entry, 8.0 kB with all
+  middleware (the new check and its error messages add about 0.2 kB).
+
+## [5.0.1] — 2026-10-03
+
+A bug-fix release from an audit of 5.0.0. Nothing in the API changes; a few calls
+that used to send the wrong thing, or nothing, now send the right thing or say why
+they cannot. See [MIGRATION.md](./MIGRATION.md#upgrading-to-501).
+
+### Fixed
+
+- **Typed arrays, `DataView`, `Buffer` and `ReadableStream` are sent as real
+  binary bodies.** They fell through to `JSON.stringify`, so a `Uint8Array([1, 2])`
+  arrived as `{"0":1,"1":2}`. They now go to `fetch` as they are, with
+  `Content-Type: application/octet-stream`; a stream is sent with `duplex: 'half'`
+  set for you. A stream can be read once, so a retry (`retryMiddleware`,
+  `result.retry()`) now returns an error Result saying it cannot be resent, where
+  it used to send an empty body.
+- **Params that used to send nothing now send what they hold, or are refused.**
+  A `Map` with string keys is the object it spells; a class with only `toJSON()`
+  is sent as its JSON (body only). A `Set`, a bare `Date`, a `Map` with non-string
+  keys and a class with no fields return an error Result (`kind: 'network'`, a
+  `TypeError` naming the type) instead of leaving with an empty body. A typed
+  array, `DataView`, stream or `toJSON`-only class on a request whose params go in
+  the query string (a GET) is refused for the same reason.
+- **Abort listeners no longer accumulate on a long-lived caller signal.** Each
+  call with `dedupe`, `timeout` or `share` (and each GraphQL call) left a listener
+  on the caller's `AbortSignal`, so a component-scoped controller used for many
+  calls grew without bound. The merged signals are now released when the call
+  settles. One consequence: after a call settles, a later abort of the caller's
+  signal no longer reaches that call's `ctx.request.signal`, so fire-and-forget
+  middleware work still holding it is no longer cancelled by the caller.
+- **`cacheMiddleware` keys on more than name and params.** The key was the request
+  name plus params, so a second user's call could be served the first user's
+  cached `/me`, and one `Request` used with two base URLs shared entries. The key
+  is now request name, method, URL (query string included, its pairs sorted by
+  name), params, and every request header except `Content-Type`. A warm cache is cold once after
+  upgrading, and a middleware placed before the cache that adds a per-call unique
+  header (a request ID) now makes every call a miss; place it after.
+- **A path token can no longer be hit by an unrelated param key.** Substitution
+  built a regular expression from each param key, so a key like `a.b` could fill
+  the token `:aXb`. Tokens are now scanned from the template, using the documented
+  grammar `[a-zA-Z0-9_]`. A template like `/x/:a-b` with a key `a-b` used to
+  resolve by accident; the scan reads the token as `:a` followed by `-b`, finds no
+  `a` key, and the call now returns an error Result (a `TypeError`, "Unresolved
+  path parameter :a…"). Use only `[a-zA-Z0-9_]` in path token names and their keys.
+- **A `Date` in a query string is reported as a `Date`.** The error said a nested
+  object was not allowed; it now names the `Date` and suggests `toISOString()` or
+  `getTime()`. It is still refused.
+- **A header name repeated within one source is joined, not overwritten.** Two
+  entries for one name in an array of header pairs kept only the last; they are now
+  joined as `a, b`, as the platform's `Headers` does. So are case-variant
+  duplicates inside one record (`{ Accept: 'a', accept: 'b' }` sends `a, b`). A
+  later source still replaces an earlier one.
+- **`timeout` works where `AbortSignal.timeout` does not exist** (React Native's
+  Hermes). A fallback built from `AbortController` and `setTimeout` is used. The
+  result is `kind: 'timeout'` where the runtime's `AbortController` carries abort
+  reasons (Node's does; this is what the tests cover), and possibly `'abort'`
+  where it ignores them. Not tested on a device. Nothing global is patched.
+- **A call with no params is no longer keyed the same as a bare `[undefined]`
+  param.** For `share` and `cacheMiddleware` the two collided, so one could be
+  handed the other's response.
+
+### Changed
+
+- **The README's size numbers are measured, and CI enforces them.** The old
+  "2.9 kB / 4.4 kB gzipped" had gone stale and understated the bundle. `npm run size`
+  now bundles each entry with esbuild and reports gzip and brotli: about 5.6 kB
+  gzipped for a REST-only import, 6.7 kB for the core entry and 7.8 kB with all
+  middleware. CI fails if one grows past its budget. `esbuild` is a new
+  devDependency; the package still has no runtime dependencies.
+
 ## [5.0.0] — 2026-10-03
 
 **Renamed from `@iremlopsum/apify` to `liaise`.** Same code, same API, full git
@@ -939,6 +1031,8 @@ Initial release of the rewritten client. Reconstructed from the release commit
   `ArrayBuffer` and strings
 - Response parsing as `json`, `text`, `blob`, `arrayBuffer` or `formData`
 
+[5.0.2]: https://github.com/iremlopsum/liaise/compare/v5.0.1...v5.0.2
+[5.0.1]: https://github.com/iremlopsum/liaise/compare/v5.0.0...v5.0.1
 [5.0.0]: https://github.com/iremlopsum/liaise/compare/v4.4.3...v5.0.0
 [4.4.3]: https://github.com/iremlopsum/liaise/compare/v4.4.2...v4.4.3
 [4.4.2]: https://github.com/iremlopsum/liaise/compare/v4.4.1...v4.4.2

package/MIGRATION.md

@@ -7,6 +7,62 @@ For the full record of what changed in each release, see [CHANGELOG.md](./CHANGE
 
 ---
 
+## Upgrading to 5.0.2
+
+No code changes needed. A call whose path parameter is `undefined`, `null`, an
+empty string, an object, an array, a `Date`, a function, a symbol, `NaN` or `Infinity` now returns an
+error Result instead of being sent to a URL like `/users/undefined`. Those calls
+were already hitting the wrong URL; now they say so. If you relied on a literal
+`null` or `undefined` segment, pass the string (`'null'`) explicitly.
+
+---
+
+## Upgrading to 5.0.1
+
+No code changes for most callers. Six things you may observe.
+
+**Binary bodies arrive as binary.** A `Uint8Array`, other typed array, `DataView`
+or `Buffer` used to be sent as a JSON index map (`{"0":1,"1":2}`); it is now the
+raw bytes, with `Content-Type: application/octet-stream`. A `ReadableStream` is
+sent as a streaming upload and can be sent once: `retryMiddleware` and
+`result.retry()` return an error Result for it. If a call with a stream may be
+retried, read it into a `Blob` or `ArrayBuffer` first. If your server decoded the
+old index map, it needs to read bytes now.
+
+**Calls that used to send nothing now send, or fail with a Result.** A `Map` with
+string keys and a class with only `toJSON()` are now sent. A `Set`, a bare `Date`,
+a `Map` with non-string keys and a class with no fields return an error Result
+(`kind: 'network'`, `body` a `TypeError` naming the type). A typed array, stream
+or `toJSON`-only class on a GET is refused. If you were relying on the empty body,
+pass the object you meant: `{ ids: [...set] }`, `{ since: date.toISOString() }`.
+
+**`cacheMiddleware` entries are per URL and per header set.** The key now includes
+method, full URL (query string included, pairs sorted by name) and every request
+header except `Content-Type`. A different `Authorization` or other header, base
+URL, path or query value gets its own entry; the same query params in a different
+order share one. A warm cache is cold once after
+upgrading. A middleware placed before `cacheMiddleware` that adds a per-call
+unique header (a request ID) makes every call a miss; put it after
+`cacheMiddleware` in the `middleware` array.
+
+**Repeated header names within one source are joined.** A header-pairs array
+with two entries for one name now sends `a, b`, where the last used to win; so
+does a record with case-variant duplicates (`{ Accept: 'a', accept: 'b' }`). A
+later source (per-call over request over config) still replaces an earlier one.
+
+**After a call settles, a later abort no longer reaches it.** Aborting the
+caller's signal no longer reaches that call's `ctx.request.signal`, so
+fire-and-forget middleware work still holding it is not cancelled by the caller;
+keep your own controller if you need that.
+
+**A path token with non-word characters now fails.** Path tokens are
+`[a-zA-Z0-9_]`. A template like `/x/:a-b` with a key `a-b` used to resolve by
+accident; it is now read as the token `:a` followed by `-b`, and the call returns
+an error Result (a `TypeError`, "Unresolved path parameter :a…"). Use only
+`[a-zA-Z0-9_]` in path token names and their keys.
+
+---
+
 ## Upgrading to 5.0.0
 
 The package has a new name: **`@iremlopsum/apify` is now `liaise`**. Nothing

package/README.md

@@ -10,8 +10,8 @@ Runtime-agnostic, type-safe HTTP client for REST and GraphQL. Built on standard
 - **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 — any environment with `fetch`
-- **Tiny** — about **2.9 kB gzipped** for a REST-only import, 4.4 kB for everything including GraphQL and all middleware; tree-shaking drops what you do not import
+- **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.8 kB gzipped** for a REST-only import, 6.9 kB for the core entry, 8.0 kB with all middleware (measured by `npm run size`); tree-shaking drops what you do not import
 
 ```
 npm install liaise
@@ -43,6 +43,7 @@ npm install liaise
 - [Testing](#testing)
 - [Philosophy](#philosophy)
 - [API Reference](#api-reference)
+- [Contributing](#contributing)
 
 ## Getting Started
 
@@ -134,6 +135,8 @@ const getItem = new Request<{ orgId: string; id: string }, Item>({
 await api.getItem({ orgId: 'acme', id: '42' })
 ```
 
+A path parameter must be a non-empty string, a finite number, a bigint or a boolean. Anything else (`undefined`, `null`, `''`, an object, an array, a `Date`, `NaN`) is refused before the request is sent, with an error Result naming the parameter. This catches the common front-end mistake of calling before an id has loaded: `getItem({ orgId: 'acme', id: undefined })` returns an error instead of fetching `/orgs/acme/items/undefined`.
+
 #### `responseType`
 
 Controls how the response body is parsed. Defaults to `'json'`.
@@ -442,6 +445,7 @@ never going to reach the server.
 | `{ 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.
 
@@ -449,6 +453,8 @@ never going to reach the server.
 
 **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.
 
+**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()`.
+
 ### Result
 
 Every API call returns a `Result<TResponse>` instead of throwing. It's a discriminated union on `error`, not a plain interface:
@@ -839,7 +845,7 @@ const api = createApi({
 
 **`cacheMiddleware(options?)`**
 
-Caches successful responses in memory, keyed by request name and params. Calls with identical params within the TTL window are served from cache without hitting the network. Each `cacheMiddleware()` call creates an isolated store — different endpoints never share entries.
+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.
 
 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).
 
@@ -873,8 +879,25 @@ Request bodies are automatically serialized based on the input type. The `Conten
 | `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`                    |
 
+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.
+
+#### What params can be
+
+| 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. |
+
+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.
+
 Header merge precedence (most specific wins):
 
 1. **Global headers** (from `createApi` config) -- lowest priority
@@ -1331,7 +1354,7 @@ Type safety comes from inference, not annotation. Define `Request<TParams, TResp
 
 ### Runtime-agnostic
 
-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, Cloudflare Workers, edge runtimes.
+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.
 
 ### Framework-agnostic
 
@@ -1393,6 +1416,10 @@ The library has no opinion about your UI framework, or whether you have one. A c
 | `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

package/dist/built-in-middleware.js

@@ -106,7 +106,27 @@ export function cacheMiddleware(options) {
         const paramsStr = stableKey(ctx.request.params);
         if (paramsStr === null)
             return next();
-        const key = `${ctx.requestName}|${paramsStr}`;
+        const headerPairs = [];
+        ctx.request.headers.forEach((value, name) => {
+            if (name !== 'content-type')
+                headerPairs.push([name, value]);
+        });
+        const headerKey = JSON.stringify(headerPairs);
+        const fullUrl = ctx.request.url;
+        const qIndex = fullUrl.indexOf('?');
+        let urlKey = fullUrl;
+        if (qIndex !== -1) {
+            const hashIndex = fullUrl.indexOf('#', qIndex);
+            const rawQuery = fullUrl.slice(qIndex + 1, hashIndex === -1 ? undefined : hashIndex);
+            const segments = rawQuery.split('&').filter(seg => seg !== '');
+            const nameOf = (seg) => seg.split('=')[0];
+            segments.sort((x, y) => {
+                const nx = nameOf(x), ny = nameOf(y);
+                return nx < ny ? -1 : nx > ny ? 1 : 0;
+            });
+            urlKey = `${fullUrl.slice(0, qIndex)}?${segments.join('&')}`;
+        }
+        const key = `${ctx.requestName}|${ctx.request.method}|${urlKey}|${paramsStr}|${headerKey}`;
         const cached = store.get(key);
         if (cached !== null) {
             if (debug)

package/dist/create-api.js

@@ -6,12 +6,14 @@ import { DedupeTracker } from './utils/dedupe.js';
 import { ShareTracker, isAbandoned } from './utils/share.js';
 import { mergeHeaders } from './utils/headers.js';
 import { abortKind, propagatesReason } from './utils/abort-kind.js';
-import { anySignal } from './utils/any-signal.js';
+import { anySignal, releaseSignal } from './utils/any-signal.js';
 import { operationBudget, perCallerBudget } from './utils/budget.js';
 import { stableKey } from './utils/stable-key.js';
 import { createBackstop } from './utils/backstop.js';
-import { isSpecialBody } from './utils/special-body.js';
+import { isReadableStream } from './utils/special-body.js';
+import { classifyParams } from './utils/classify-params.js';
 import { runSchema } from './utils/validate.js';
+const sentStreams = new WeakSet();
 const EMPTY_JSON_BODY = Symbol('liaise.emptyJsonBody');
 async function parseResponse(response, responseType = 'json') {
     switch (responseType) {
@@ -39,9 +41,9 @@ async function parseResponse(response, responseType = 'json') {
 }
 function resolveRequestUrl(baseUrl, request, params) {
     const asQuery = request.shouldSerializeAsQuery;
-    const paramsIsSpecialBody = isSpecialBody(params);
-    const { url, remaining } = buildUrl(baseUrl, request.config.path, paramsIsSpecialBody ? {} : params, asQuery);
-    return { url, remaining, asQuery, paramsIsSpecialBody };
+    const classified = classifyParams(params, asQuery);
+    const { url, remaining } = buildUrl(baseUrl, request.config.path, classified.kind === 'fields' ? classified.fields : {}, asQuery);
+    return { url, remaining, asQuery, whole: classified.kind === 'whole' ? { value: classified.value } : null };
 }
 function urlForError(baseUrl, request, params) {
     try {
@@ -112,6 +114,13 @@ export function createApi(config) {
                 return result;
             }
             const execute = (sharedSignal, onSettled) => {
+                const merged = [];
+                const own = (signal, ...inputs) => {
+                    if (signal && !inputs.includes(signal))
+                        merged.push(signal);
+                };
+                const releaseAll = () => { for (const s of merged)
+                    releaseSignal(s); };
                 try {
                     const allMiddleware = [
                         ...globalMiddleware,
@@ -119,19 +128,25 @@ export function createApi(config) {
                         ...(options.middleware ?? [])
                     ];
                     const operation = operationBudget(options.timeout, request.config.timeout, options.signal, sharedSignal !== undefined);
+                    own(operation, options.signal);
                     const callerSignal = sharedSignal
                         ? anySignal([sharedSignal, operation])
                         : operation;
+                    own(callerSignal, sharedSignal, operation);
                     let dedupeController;
                     const core = async (ctx) => {
                         try {
                             if (sharedSignal && ctx.request.signal !== sharedSignal) {
-                                ctx.request.signal = anySignal([ctx.request.signal, sharedSignal]);
+                                const installed = ctx.request.signal;
+                                ctx.request.signal = anySignal([installed, sharedSignal]);
+                                own(ctx.request.signal, installed, sharedSignal);
                             }
                             if (request.config.dedupe && !dedupeController) {
-                                const tracked = dedupeTracker.track(name, ctx.request.signal ?? callerSignal);
+                                const external = ctx.request.signal ?? callerSignal;
+                                const tracked = dedupeTracker.track(name, external);
                                 dedupeController = tracked.controller;
                                 ctx.request.signal = tracked.signal;
+                                own(tracked.signal, external);
                                 backstop.watch(tracked.controller.signal);
                             }
                             const fetchInit = {
@@ -140,7 +155,16 @@ export function createApi(config) {
                                 signal: ctx.request.signal
                             };
                             if (ctx.request.body !== null && ctx.request.body !== undefined) {
-                                fetchInit.body = ctx.request.body;
+                                const body = ctx.request.body;
+                                if (isReadableStream(body)) {
+                                    if (sentStreams.has(body)) {
+                                        throw new TypeError('A ReadableStream body can only be sent once, so retry() and retryMiddleware cannot resend it. ' +
+                                            'If this call may be retried, read the stream into a Blob or ArrayBuffer first.');
+                                    }
+                                    sentStreams.add(body);
+                                    fetchInit.duplex = 'half';
+                                }
+                                fetchInit.body = body;
                             }
                             const response = await fetch(ctx.request.url, fetchInit);
                             if (!response.ok) {
@@ -261,12 +285,12 @@ export function createApi(config) {
                             return createNetworkErrorResult(error, retry);
                         }
                     };
-                    const { url, remaining, asQuery, paramsIsSpecialBody } = resolveRequestUrl(baseUrl, request, params);
+                    const { url, remaining, asQuery, whole } = resolveRequestUrl(baseUrl, request, params);
                     const headers = mergeHeaders(globalHeaders, request.config.headers, options.headers);
                     let body = null;
                     if (!asQuery) {
-                        const toSerialize = paramsIsSpecialBody ? params : remaining;
-                        if (paramsIsSpecialBody || Object.keys(remaining).length > 0) {
+                        const toSerialize = whole ? whole.value : remaining;
+                        if (whole || Object.keys(remaining).length > 0) {
                             const serialized = serializeBody(toSerialize);
                             body = serialized.body;
                             if (serialized.contentType && !headers.has('Content-Type')) {
@@ -308,19 +332,25 @@ export function createApi(config) {
                                 dedupeController.abort();
                             dedupeTracker.clear(name, dedupeController);
                         }
+                        releaseAll();
                         const abandoned = sharedSignal?.aborted === true && isAbandoned(sharedSignal.reason);
                         if (result.error && !abandoned)
                             fireOnError(result.error);
                         return result;
-                    }, (err) => failedResult(err, undefined, 'abort'));
+                    }, (err) => {
+                        releaseAll();
+                        return failedResult(err, undefined, 'abort');
+                    });
                 }
                 catch (err) {
+                    releaseAll();
                     return Promise.resolve(failedResult(err, undefined, 'network'));
                 }
             };
             function retry() {
                 return execute();
             }
+            let builtPerCaller;
             try {
                 const key = request.config.share === true &&
                     isEmptyHeaders(options.headers) &&
@@ -331,6 +361,7 @@ export function createApi(config) {
                     return execute();
                 const shareKey = `${name}|${key}`;
                 const perCaller = perCallerBudget(options.timeout, options.signal);
+                builtPerCaller = perCaller;
                 const { promise, release, hasSettled } = shareTracker.acquire(shareKey, (signal, markSettled) => execute(signal, markSettled));
                 if (!perCaller)
                     return promise.then(r => r, (err) => failedResult(err, undefined, 'network'));
@@ -341,6 +372,8 @@ export function createApi(config) {
                             return;
                         done = true;
                         perCaller.removeEventListener('abort', onAbort);
+                        if (perCaller !== options.signal)
+                            releaseSignal(perCaller);
                         resolve(r);
                     };
                     promise.then(r => finish(r), (err) => {
@@ -362,6 +395,8 @@ export function createApi(config) {
                 });
             }
             catch (err) {
+                if (builtPerCaller !== options.signal)
+                    releaseSignal(builtPerCaller);
                 return Promise.resolve(failedResult(err, undefined, 'network'));
             }
         };

package/dist/define-request.d.ts

@@ -4,7 +4,7 @@ import type { RequestConfig, ResponseType, StandardSchemaV1, InferOutput } from
  * The characters a path token name may contain.
  *
  * This list is not arbitrary and must not be "simplified": it mirrors
- * `buildUrl`'s substitution pattern, `:${key}(?=[^a-zA-Z0-9_]|$)`
+ * the `/:([a-zA-Z0-9_]+)/g` template scan in `buildUrl`
  * (src/utils/path-params.ts). If the two ever disagree, the types describe a
  * URL the runtime does not build.
  */

package/dist/graphql.js

@@ -4,6 +4,7 @@ import { DedupeTracker } from './utils/dedupe.js';
 import { mergeHeaders } from './utils/headers.js';
 import { abortKind, propagatesReason } from './utils/abort-kind.js';
 import { resolveBudget } from './utils/budget.js';
+import { releaseSignal } from './utils/any-signal.js';
 import { createBackstop } from './utils/backstop.js';
 import { runSchema } from './utils/validate.js';
 export class Operation {
@@ -43,6 +44,13 @@ export function createGraphQL(config) {
                     });
                     return createNetworkErrorResult(error, execute);
                 }
+                const merged = [];
+                const own = (signal, ...inputs) => {
+                    if (signal && !inputs.includes(signal))
+                        merged.push(signal);
+                };
+                const releaseAll = () => { for (const s of merged)
+                    releaseSignal(s); };
                 try {
                     const allMiddleware = [
                         ...globalMiddleware,
@@ -51,13 +59,16 @@ export function createGraphQL(config) {
                     ];
                     const budget = resolveBudget(options.timeout, operation.config.timeout, options.signal, false);
                     const callerSignal = budget.operation;
+                    own(callerSignal, options.signal);
                     let dedupeController;
                     const core = async (ctx) => {
                         try {
                             if (operation.config.dedupe && !dedupeController) {
-                                const tracked = dedupeTracker.track(name, ctx.request.signal ?? callerSignal);
+                                const external = ctx.request.signal ?? callerSignal;
+                                const tracked = dedupeTracker.track(name, external);
                                 dedupeController = tracked.controller;
                                 ctx.request.signal = tracked.signal;
+                                own(tracked.signal, external);
                                 backstop.watch(tracked.controller.signal);
                             }
                             const response = await fetch(ctx.request.url, {
@@ -218,16 +229,19 @@ export function createGraphQL(config) {
                                 dedupeController.abort();
                             dedupeTracker.clear(name, dedupeController);
                         }
+                        releaseAll();
                         if (result.error)
                             fireOnError(result.error);
                         return result;
                     }, (err) => {
+                        releaseAll();
                         const result = buildFailedResult(err, undefined, 'abort');
                         fireOnError(result.error);
                         return result;
                     });
                 }
                 catch (err) {
+                    releaseAll();
                     const error = new ApiError({
                         status: 0,
                         kind: 'network',

package/dist/utils/any-signal.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Remove the listeners `anySignal` registered for `signal`. Call it once the
+ * call that owns the signal has settled. A no-op for a signal anySignal did
+ * not create (a caller's own signal, the single-signal fast path, undefined),
+ * and idempotent. It deliberately does NOT release the merge's inputs: an
+ * input may be a signal another, still-running call owns, for example when a
+ * middleware passes ctx.request.signal into a nested api call.
+ */
+export declare function releaseSignal(signal: AbortSignal | undefined): void;
 /**
  * Composes several abort signals into one that aborts when the first of them
  * aborts, carrying that signal's `reason` through.

package/dist/utils/any-signal.js

@@ -1,3 +1,13 @@
+const disposers = new WeakMap();
+export function releaseSignal(signal) {
+    if (!signal)
+        return;
+    const dispose = disposers.get(signal);
+    if (!dispose)
+        return;
+    disposers.delete(signal);
+    dispose();
+}
 export function anySignal(signals) {
     const defined = signals.filter((s) => s !== undefined);
     if (defined.length === 0)
@@ -25,5 +35,6 @@ export function anySignal(signals) {
         registered.push({ signal, listener });
         signal.addEventListener('abort', listener, { once: true });
     }
+    disposers.set(controller.signal, cleanup);
     return controller.signal;
 }

package/dist/utils/classify-params.d.ts

@@ -0,0 +1,13 @@
+export type ClassifiedParams = {
+    kind: 'fields';
+    fields: Record<string, unknown>;
+} | {
+    kind: 'whole';
+    value: unknown;
+};
+/**
+ * @param params - The call's params, as passed.
+ * @param asQuery - Whether this request's params go in the query string.
+ * @throws TypeError for a value that has no honest wire form here.
+ */
+export declare function classifyParams(params: unknown, asQuery: boolean): ClassifiedParams;

package/dist/utils/classify-params.js

@@ -0,0 +1,50 @@
+import { isReadableStream, isSpecialBody } from './special-body.js';
+function typeName(value) {
+    const name = value.constructor?.name;
+    return typeof name === 'string' && name !== '' ? name : 'object';
+}
+function withArticle(value) {
+    const name = typeName(value);
+    return `${/^([aeio]|u(?!int))/i.test(name) ? 'an' : 'a'} ${name}`;
+}
+export function classifyParams(params, asQuery) {
+    if (params === null || params === undefined)
+        return { kind: 'fields', fields: {} };
+    if (isSpecialBody(params)) {
+        if (asQuery && (ArrayBuffer.isView(params) || isReadableStream(params))) {
+            throw new TypeError(`Cannot send ${withArticle(params)} as params for a request whose params go in the query string. ` +
+                'Send it with POST, PUT or PATCH.');
+        }
+        return { kind: 'whole', value: params };
+    }
+    if (typeof params !== 'object' || Array.isArray(params)) {
+        return { kind: 'fields', fields: params };
+    }
+    if (params instanceof Map) {
+        for (const key of params.keys()) {
+            if (typeof key !== 'string') {
+                throw new TypeError('Cannot send a Map with non-string keys as request params. Use string keys, or convert it to an object first.');
+            }
+        }
+        return { kind: 'fields', fields: Object.fromEntries(params) };
+    }
+    if (params instanceof Set) {
+        throw new TypeError('Cannot send a Set as request params. Put it in an object as an array, e.g. { ids: [...set] }.');
+    }
+    if (params instanceof Date) {
+        throw new TypeError('Cannot send a Date as request params on its own. Put it in an object, e.g. { since: date.toISOString() }.');
+    }
+    const proto = Object.getPrototypeOf(params);
+    const plain = proto === Object.prototype || proto === null ||
+        Object.getPrototypeOf(proto) === null;
+    if (plain || Object.keys(params).length > 0) {
+        return { kind: 'fields', fields: params };
+    }
+    if (typeof params.toJSON === 'function') {
+        if (asQuery) {
+            throw new TypeError(`Cannot send ${withArticle(params)} in a query string. Send it with POST, PUT or PATCH, or pass its fields as a plain object.`);
+        }
+        return { kind: 'whole', value: params };
+    }
+    throw new TypeError(`Cannot send ${withArticle(params)} as request params: it has no fields to send. Pass a plain object, or give the class a toJSON() method.`);
+}

package/dist/utils/headers.js

@@ -3,17 +3,7 @@ export function mergeHeaders(...sources) {
     for (const source of sources) {
         if (!source)
             continue;
-        if (source instanceof Headers) {
-            source.forEach((value, key) => merged.set(key, value));
-        }
-        else {
-            const entries = Array.isArray(source)
-                ? source
-                : Object.entries(source);
-            for (const [key, value] of entries) {
-                merged.set(key, value);
-            }
-        }
+        new Headers(source).forEach((value, key) => merged.set(key, value));
     }
     return merged;
 }

package/dist/utils/path-params.d.ts

@@ -56,10 +56,12 @@ export declare class FragmentError extends TypeError {
  * This is the main URL construction function used by the request engine.
  * It handles the full lifecycle from path template to final URL.
  *
- * **Path param matching** uses regex with a word-boundary lookahead to prevent
- * partial matches. For example, a param key `id` will match `:id` but NOT
- * `:idExtra`. This is achieved by requiring that the character after the param
- * name is either a non-alphanumeric-underscore character or end of string.
+ * **Path param matching** scans the template once for `:name` tokens
+ * (`[a-zA-Z0-9_]+`, greedy), so a param key `id` fills `:id` but never part of
+ * `:idExtra`. A token is filled only from a non-empty string, a finite number,
+ * a bigint or a boolean; `undefined`, `null`, `''`, objects, arrays and Dates
+ * throw a TypeError naming the param, so a call is never sent to
+ * '/users/undefined'.
  *
  * **Query string rules** (when `asQuery` is true):
  * - Primitives: `{ page: 1 }` → `?page=1`

package/dist/utils/path-params.js

@@ -25,25 +25,58 @@ export class FragmentError extends TypeError {
         this.resolvedUrl = resolvedUrl;
     }
 }
+function unusableSegment(value) {
+    if (value === undefined)
+        return 'undefined';
+    if (value === null)
+        return 'null';
+    if (value === '')
+        return 'an empty string';
+    if (typeof value === 'number' && !Number.isFinite(value))
+        return String(value);
+    if (value instanceof Date)
+        return 'a Date (convert it first, e.g. date.toISOString() or date.getTime())';
+    if (Array.isArray(value))
+        return 'an array';
+    if (typeof value === 'object')
+        return 'an object';
+    if (typeof value === 'function' || typeof value === 'symbol')
+        return `a ${typeof value}`;
+    return null;
+}
 export function buildUrl(baseUrl, path, params, asQuery = false) {
     const fragmentIn = path.includes('#') ? { where: 'path', value: path } : baseUrl.includes('#') ? { where: 'baseUrl', value: baseUrl } : null;
     let resolvedPath = path;
     const remaining = {};
-    for (const [key, value] of Object.entries(params)) {
-        const pattern = new RegExp(`:${key}(?=[^a-zA-Z0-9_]|$)`, 'g');
-        const substituted = resolvedPath.replace(pattern, encodeURIComponent(String(value)));
-        if (substituted !== resolvedPath) {
-            resolvedPath = substituted;
+    const lookup = new Map(Object.entries(params));
+    const consumed = new Set();
+    const unusable = [];
+    resolvedPath = resolvedPath.replace(/:([a-zA-Z0-9_]+)/g, (token, name) => {
+        if (!lookup.has(name))
+            return token;
+        consumed.add(name);
+        const value = lookup.get(name);
+        const problem = unusableSegment(value);
+        if (problem) {
+            if (!unusable.some(entry => entry.startsWith(`"${name}"`)))
+                unusable.push(`"${name}" is ${problem}`);
+            return token;
         }
-        else {
+        return encodeURIComponent(String(value));
+    });
+    for (const [key, value] of lookup) {
+        if (!consumed.has(key))
             remaining[key] = value;
-        }
     }
     if (fragmentIn) {
         const fragment = fragmentIn.value.slice(fragmentIn.value.indexOf('#'));
         throw new FragmentError(`A URL fragment is never sent to the server, so it cannot appear in a ${fragmentIn.where}. ` +
             `Remove "${fragment}" from "${fragmentIn.value}".`, joinUrl(baseUrl, resolvedPath));
     }
+    if (unusable.length > 0) {
+        throw new TypeError(`Path parameter ${unusable.join(', ')} in path "${path}", so the call was not sent. ` +
+            'A path parameter must be a non-empty string, a finite number, a bigint or a boolean.');
+    }
     const unresolved = resolvedPath
         .split('/')
         .map(segment => /^:[a-zA-Z0-9_]+/.exec(segment)?.[0])
@@ -64,6 +97,9 @@ export function buildUrl(baseUrl, path, params, asQuery = false) {
                     searchParams.append(key, String(item));
                 }
             }
+            else if (value instanceof Date) {
+                throw new TypeError(`A Date cannot be sent in a query string as is. Convert param "${key}" first, e.g. ${key}: date.toISOString() or date.getTime().`);
+            }
             else if (typeof value === 'object') {
                 throw new TypeError(`Nested objects are not supported in query strings. Flatten param "${key}" before passing.`);
             }

package/dist/utils/serialize.d.ts

@@ -32,6 +32,8 @@ export interface SerializeResult {
  * | `URLSearchParams` | as-is                | `application/x-www-form-urlencoded`  |
  * | `Blob`            | as-is                | `application/octet-stream`           |
  * | `ArrayBuffer`     | as-is                | `application/octet-stream`           |
+ * | `ArrayBufferView` (typed array, `DataView`, `Buffer`) | as-is | `application/octet-stream` |
+ * | `ReadableStream`  | as-is                | `application/octet-stream`           |
  * | Plain object      | `JSON.stringify()`   | `application/json`                   |
  *
  * @param input - The raw body value to serialize. Can be any type — the function

package/dist/utils/serialize.js

@@ -1,3 +1,4 @@
+import { isReadableStream } from './special-body.js';
 export function serializeBody(input) {
     if (input === null || input === undefined) {
         return { body: null, contentType: null };
@@ -17,5 +18,11 @@ export function serializeBody(input) {
     if (input instanceof ArrayBuffer) {
         return { body: input, contentType: 'application/octet-stream' };
     }
+    if (ArrayBuffer.isView(input)) {
+        return { body: input, contentType: 'application/octet-stream' };
+    }
+    if (isReadableStream(input)) {
+        return { body: input, contentType: 'application/octet-stream' };
+    }
     return { body: JSON.stringify(input), contentType: 'application/json' };
 }

package/dist/utils/special-body.d.ts

@@ -1,7 +1,13 @@
+/**
+ * True for a WHATWG `ReadableStream`. Guarded with `typeof` because a runtime
+ * without streams has no global to `instanceof` against.
+ */
+export declare function isReadableStream(value: unknown): value is ReadableStream;
 /**
  * True when `value` is a body type that cannot be decomposed into key-value
- * pairs — `FormData`, `Blob`, `ArrayBuffer`, `URLSearchParams`, or a raw
- * string.
+ * pairs — `FormData`, `Blob`, `ArrayBuffer`, any `ArrayBufferView` (typed
+ * arrays, `DataView`, Node's `Buffer`), a `ReadableStream`, `URLSearchParams`,
+ * or a raw string.
  *
  * Used by `create-api.ts`'s URL-building step, which skips path/query
  * decomposition for these entirely and hands them straight to

package/dist/utils/special-body.js

@@ -1,7 +1,12 @@
+export function isReadableStream(value) {
+    return typeof ReadableStream !== 'undefined' && value instanceof ReadableStream;
+}
 export function isSpecialBody(value) {
     return (value instanceof FormData ||
         value instanceof Blob ||
         value instanceof ArrayBuffer ||
+        ArrayBuffer.isView(value) ||
+        isReadableStream(value) ||
         value instanceof URLSearchParams ||
         typeof value === 'string');
 }

package/dist/utils/stable-key.d.ts

@@ -13,8 +13,9 @@
  *
  * Keys are built by content, in the order the rules are checked:
  *
- * - `undefined` at the top level → `[undefined]` (a call with no params is
- *   keyable). An `undefined` *object member* is dropped, since both transports
+ * - `undefined` at the top level → `''` (a call with no params is keyable,
+ *   and distinct from a bare `[undefined]` array param). An `undefined`
+ *   *object member* is dropped, since both transports
  *   omit it, so `{ a: undefined }` and `{}` key the same. As an array element,
  *   Map key/value or Set element it keys as the unquoted token `undefined`
  *   (a query string sends `ids=undefined`, not `ids=null`), and so does a
@@ -30,8 +31,9 @@
  *   returns `undefined` the member is dropped, as JSON does.
  * - `Map` → `Map{k:v,...}` with entries sorted by key; `Set` → `Set[...]` in
  *   insertion order; typed arrays and `DataView` → `Uint8Array[1,2]` etc. The
- *   tag matters: a Map with entry `a: 1` does not send the same bytes as
- *   `{ a: 1 }`, so it must not share its key.
+ *   tag keeps a Map apart from an object with the same entries. A
+ *   string-keyed Map is sent as that object, so over-separating them costs
+ *   one extra miss and is harmless; sharing them wrongly would not be.
  * - arrays → `[...]`; plain objects → sorted, JSON-quoted keys. Any other
  *   object with own enumerable keys is keyed the same way, since that is what
  *   `JSON.stringify` sends for it.

package/dist/utils/stable-key.js

@@ -1,6 +1,6 @@
 export function stableKey(value) {
     if (value === undefined)
-        return '[undefined]';
+        return '';
     try {
         const out = visit(value, '', new Set());
         return out === undefined ? null : out;

package/dist/utils/timeout.js

@@ -1,7 +1,16 @@
+function timeoutSignal(ms) {
+    if (typeof AbortSignal.timeout === 'function')
+        return AbortSignal.timeout(ms);
+    const controller = new AbortController();
+    const reason = new Error('The operation timed out.');
+    reason.name = 'TimeoutError';
+    setTimeout(() => controller.abort(reason), ms);
+    return controller.signal;
+}
 export function timeoutSignalFor(callTimeout, requestTimeout) {
     const raw = Math.min(callTimeout ?? requestTimeout ?? 0, 2 ** 31 - 1);
     if (!(raw > 0))
         return undefined;
     const ms = Math.max(1, Math.floor(raw));
-    return AbortSignal.timeout(ms);
+    return timeoutSignal(ms);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liaise",
-  "version": "5.0.0",
+  "version": "5.0.2",
   "description": "Type-safe API client for REST and GraphQL on standard fetch. Never throws. Zero dependencies.",
   "type": "module",
   "sideEffects": false,
@@ -29,6 +29,7 @@
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "size": "node scripts/size.mjs",
     "build": "npm run clean && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
     "test": "vitest",
     "test:run": "vitest run",
@@ -36,7 +37,7 @@
     "typecheck": "tsc --noEmit",
     "test:types": "vitest run --typecheck",
     "sessions": "test -f .claude/sessions.mjs && node .claude/sessions.mjs || echo \"npm run sessions is a local-only helper (gitignored .claude/); nothing to list in this clone\"",
-    "prepublishOnly": "npm run typecheck && npm run test:types && npm run test:run && npm run test:integration && npm run build"
+    "prepublishOnly": "npm run typecheck && npm run test:types && npm run test:run && npm run test:integration && npm run build && npm run size"
   },
   "repository": {
     "type": "git",
@@ -69,6 +70,7 @@
   ],
   "devDependencies": {
     "@types/node": "^22.19.18",
+    "esbuild": "0.27.4",
     "typescript": "~5.8.0",
     "vitest": "^3.2.0"
   }