liaise 5.0.2 → 5.0.3

package/dist/types.d.ts

@@ -43,7 +43,7 @@ export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  *   ceremony with no effect. Mismatch it and you get a wrong `TResponse`
  *   silently, same as always — declare it as `undefined`.
  *
- *   This describes `new Request`'s behaviour specifically. As of 4.1.0,
+ *   This describes `new Request`'s behaviour specifically.
  *   `defineRequest` DOES enforce this pairing at compile time — see
  *   `EmptyBodyGuard` in `define-request.ts` — because a curried function,
  *   unlike a constructor, has no permissive overload for the guard to fall
@@ -178,7 +178,7 @@ export interface RequestConfig {
      * Declaring `responseType: 'none'` alongside a schema is a contradiction —
      * there is no body to validate, and every call will fail validation. It is
      * not rejected at compile time because the runtime failure is immediate and
-     * loud; see the spec's non-goals.
+     * loud.
      *
      * On this class path, `schema` and `TResponse` are also not tied together at
      * compile time: `new Request<P, User>({ ..., schema: numberSchema })`
@@ -219,12 +219,14 @@ export interface RequestConfig {
      * and an `'abort'` give-up does not (see {@link ApiConfig.onError}). A per-*request*
      * {@link RequestConfig.timeout}, by contrast, bounds the shared request
      * itself for everyone.
-     * A call whose params are a special body type — `FormData`, `Blob`,
-     * `ArrayBuffer`, `URLSearchParams`, or a raw string — is also never shared:
-     * the stable serialisation used for identity can't distinguish two
-     * different payloads of these types from each other, so sharing them could
-     * hand one caller the response to a *different* payload than the one it
-     * sent.
+     * A call whose params cannot be compared by content is also never shared.
+     * That is, at any depth: a BigInt, a function or symbol, an `ArrayBuffer`,
+     * `Blob`, `FormData` or `URLSearchParams`, a boxed primitive, a circular
+     * structure, or a non-plain object with no enumerable keys (an `Error`, a
+     * class keeping its state in private fields). These are declined because
+     * their content can't be keyed reliably, and a wrong match would hand one
+     * caller the response to another's request. A string, `Date`, `Map`, `Set` or typed
+     * array is compared by content and shares normally.
      *
      * `result.retry()` on a shared result re-runs the pipeline using the
      * **acquiring caller's** own per-call options (headers, signal, timeout) —
@@ -233,15 +235,6 @@ export interface RequestConfig {
      * non-aborting sharer receiving the literal same `Result` object; it is
      * unavoidable given that design, but worth knowing before relying on it.
      *
-     * **Known limitation:** middleware (global or per-request) that replaces
-     * `ctx.request.signal` — see {@link MiddlewareContext.request.signal} — is
-     * re-merged with the dedupe signal under `dedupe: true`, but is **not**
-     * currently re-merged with the share refcount controller. Combining
-     * `share` with signal-replacing middleware means that middleware's signal,
-     * not the refcount, ends up controlling the shared request: one sharer's
-     * middleware-installed signal could cancel the request for every other
-     * sharer.
-     *
      * @default false
      */
     share?: boolean;
@@ -272,8 +265,7 @@ export interface RequestConfig {
      * **This is a whole-operation deadline, not a per-attempt budget.** It covers
      * the entire middleware chain including every retry and every backoff delay,
      * so `timeout: 5000` with `retryMiddleware(3)` still means "an answer within
-     * 5 seconds" — not five seconds per attempt. This deliberately differs from
-     * axios, XHR and `got`, which apply timeouts per attempt.
+     * 5 seconds" — not five seconds per attempt.
      *
      * For a per-attempt budget, use a signal-replacing middleware placed inside
      * the retry middleware instead:
@@ -313,8 +305,8 @@ export interface RequestConfig {
  */
 export interface SuccessResult<TResponse> {
     /**
-     * The parsed response data, narrowed by `error === null`. Since 4.0.0 a 2xx
-     * that carries no body under `responseType: 'json'` is a `'parse'` error
+     * The parsed response data, narrowed by `error === null`. A 2xx that
+     * carries no body under `responseType: 'json'` is a `'parse'` error
      * rather than a success, so this is not `null` for that case — declare
      * `responseType: 'none'` on an endpoint that answers with no body. See the
      * `responseType` reference.
@@ -340,7 +332,7 @@ export interface SuccessResult<TResponse> {
  * A failed API call. `error` is populated and `data` is `null`.
  *
  * `response` is present for HTTP and parse failures (the server responded)
- * and `null` for network failures, aborts and timeouts. Check
+ * and `null` for network failures, aborts, timeouts and middleware errors. Check
  * {@link ApiError.kind} to tell them apart.
  */
 export interface ErrorResult<TResponse> {
@@ -403,7 +395,10 @@ export interface CallOptions {
      * new reference that won't match the original.
      */
     skipMiddleware?: Middleware[];
-    /** Extra headers for this call. Highest merge priority (overrides all). */
+    /**
+     * Extra headers for this call. Each one replaces the client's and the
+     * endpoint's value for the same header; other headers are kept.
+     */
     headers?: HeadersInit;
     /**
      * An `AbortSignal` to cancel this request. When the signal fires,
@@ -425,8 +420,9 @@ export interface CallOptions {
      * cannot outlast it.
      *
      * A fractional or out-of-range value is normalised rather than rejected:
-     * rounded down to whole milliseconds, clamped to the platform timer ceiling,
-     * and treated as "no timeout" if it is `NaN` or non-positive.
+     * rounded down to whole milliseconds with a 1 ms minimum, clamped to the
+     * platform timer ceiling, and treated as "no timeout" if it is `NaN` or
+     * non-positive.
      */
     timeout?: number;
 }
@@ -440,10 +436,9 @@ export interface CallOptions {
  * Middleware can read and modify `ctx.request.headers` and `ctx.request.body`
  * before calling `next()` — changes will propagate to the actual fetch call.
  *
- * **Typing note:** The spec defines MiddlewareContext with generic TParams and
- * TResponse, but middleware is intentionally loosely typed. Authors work with
- * `unknown` and cast internally if they need specific types. This avoids
- * complex generic inference issues and keeps middleware composable.
+ * Middleware is deliberately loosely typed: authors work with `unknown` and
+ * cast internally if they need specific types. This avoids complex generic
+ * inference issues and keeps middleware composable.
  */
 export interface MiddlewareContext {
     /** Mutable request details — middleware can modify headers and body. */
@@ -458,7 +453,7 @@ export interface MiddlewareContext {
         params: unknown;
         /** Merged headers — middleware can add/remove headers here. */
         headers: Headers;
-        /** Serialized request body, or null for GET/DELETE requests. */
+        /** Serialized request body, or null when there is none. */
         body: unknown | null;
         /**
          * The AbortSignal that will be handed to `fetch`.
@@ -469,7 +464,9 @@ export interface MiddlewareContext {
          * middleware takes effect. Under `dedupe: true` the replacement is merged
          * into the dedupe signal rather than discarded: the fetch is then
          * cancelled by whichever fires first, the middleware's signal or a newer
-         * call superseding this one.
+         * call superseding this one. Under `share: true` the shared request's
+         * refcount signal is merged back in the same way, so the request is still
+         * cancelled once every sharer has given up.
          *
          * While middleware runs — before `next()` reaches the core fetch — this
          * holds the caller's `CallOptions.signal` merged with the timeout signal
@@ -685,7 +682,7 @@ export interface OperationConfig {
      *
      * Unlike the REST side, a schema here does **not** supply the response type —
      * `Operation`'s `TData` stays explicit, because only the REST pipeline has a
-     * factory that can infer it. See the spec's non-goals.
+     * factory that can infer it.
      */
     schema?: StandardSchemaV1<unknown>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "liaise",
-  "version": "5.0.2",
+  "version": "5.0.3",
   "description": "Type-safe API client for REST and GraphQL on standard fetch. Never throws. Zero dependencies.",
   "type": "module",
   "sideEffects": false,
@@ -34,10 +34,11 @@
     "test": "vitest",
     "test:run": "vitest run",
     "test:integration": "vitest run --config vitest.integration.ts",
+    "docs:check": "node scripts/check-readme.mjs",
     "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 && npm run size"
+    "prepublishOnly": "npm run typecheck && npm run test:types && npm run test:run && npm run test:integration && npm run docs:check && npm run build && npm run size"
   },
   "repository": {
     "type": "git",
@@ -69,6 +70,7 @@
     "http-client"
   ],
   "devDependencies": {
+    "@tanstack/query-core": "5.104.1",
     "@types/node": "^22.19.18",
     "esbuild": "0.27.4",
     "typescript": "~5.8.0",