openapi-typesafe-react-query 1.0.0-rc.3 → 1.0.0-rc.5

package/src/index.ts

@@ -1,5 +1,7 @@
 import {
   type DataTag,
+  type DefaultError,
+  type DefinedUseQueryResult,
   type InfiniteData,
   type QueryClient,
   type QueryFunctionContext,
@@ -25,12 +27,17 @@ import type {
   MaybeOptionalInit,
   PathOperation,
 } from "openapi-typesafe-fetch";
+// The helper types come from the client, which declares them: types inferred from the hooks then
+// print the client's `helpers` entry, of a peer every user has, and not `openapi-typesafe-helpers`,
+// which Yarn PnP does not let a library reach (ADR-034).
 import type {
   HttpMethod,
   MediaType,
   PathsWithMethod,
   RequiredKeysOf,
-} from "openapi-typesafe-helpers";
+} from "openapi-typesafe-fetch/helpers";
+import { queryKeyInit } from "./query-key.js";
+import { withQuerySignal } from "./query-signal.js";
 
 // Helper type to dynamically infer the type from the `select` property
 type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer R ? R : TData;
@@ -41,6 +48,46 @@ type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => in
  */
 type QueryData<Data> = undefined extends Data ? Exclude<Data, undefined> | null : Data;
 
+/**
+ * What the hooks throw when a request fails and the response has no error body: a non-OK status
+ * with an empty body, a JSON `null` body, or one whose operation declares no content for it. The
+ * fetch client gives `error: undefined` (or `null`) then; throwing that left `error` empty in
+ * TanStack Query while its type said there was an error body. Tell it apart with
+ * `isResponseError(error)`: `error instanceof Error` also matches a network or parse error. The
+ * message names the status, not the URL, which can carry secrets.
+ */
+export interface ResponseError extends Error {
+  readonly name: "ResponseError";
+  /** The response that failed. */
+  readonly response: Response;
+  /** Its HTTP status, as `response.status`. */
+  readonly status: number;
+}
+
+/**
+ * The error of a hook: the error body of a failed response, a `ResponseError` when it has none, or
+ * what the request threw before there was a response to read: a network error (`TypeError`), an
+ * abort, a body that is not JSON (`SyntaxError`) or a middleware error. TanStack Query types that
+ * last part as `DefaultError` (`Error` unless `Register` says otherwise; a registered `unknown`
+ * makes the whole type `unknown`, as for TanStack's own hooks). `undefined` and `null` are left
+ * out: a failed response without an error body throws a `ResponseError`.
+ */
+export type QueryError<ErrorBody> =
+  | Exclude<ErrorBody, undefined | null>
+  | ResponseError
+  | DefaultError;
+
+/**
+ * An object whose `queryKey` is tagged with the query's data and error types: the type that
+ * TanStack Query 5.102 exports as `QueryKeyWithDataTag`, for the whole peer range. A named object
+ * type, so the declarations of an exported `queryOptions` result print it by name. Spelled out,
+ * the tag prints TanStack's `dataTagSymbol` keys, which a declaration file cannot import, and
+ * the library's users get TS2304, or `any` cached data with `skipLibCheck`.
+ */
+export type QueryKeyWithDataTag<Key, Data, Error> = {
+  queryKey: DataTag<Key, Data, Error>;
+};
+
 type InitWithUnknowns<Init> = Init & { [key: string]: unknown };
 
 /**
@@ -56,6 +103,12 @@ type InitArguments<Init, Rest extends unknown[]> =
     ? [InitWithUnknowns<Init>?, ...Rest]
     : [InitWithUnknowns<Init>, ...Rest];
 
+/**
+ * The key of a query: the method, the path and the request. Its init is the init of the call with
+ * the headers and the body as plain values, and the client's `keyScope`, or its `baseUrl` when the
+ * init has none, so two requests never share a key; it is left out when nothing is left. Read a
+ * query's key from `queryOptions(...).queryKey` rather than writing it out.
+ */
 export type QueryKey<
   Paths extends {},
   Method extends HttpMethod,
@@ -66,8 +119,8 @@ export type QueryKey<
 /**
  * The last element of an infinite query's key. `useQuery` and `useInfiniteQuery` cache different
  * data (`TData` and `InfiniteData<TData>`), so the same request must not share one key (upstream
- * #2184, ADR-022). A prefix such as `[method, path]` still matches both. Not exported: a runtime
- * named export next to the default export would change what `require()` returns.
+ * #2184, ADR-022). A prefix such as `[method, path]` still matches both. Not exported: it is not
+ * needed outside the package, and a named export is public API; `InfiniteQueryKey` types the key.
  */
 const INFINITE_QUERY_KEY_MARKER = "infinite";
 
@@ -77,6 +130,36 @@ export type InfiniteQueryKey<
   Path extends PathsWithMethod<Paths, Method>,
 > = readonly [...QueryKey<Paths, Method, Path>, typeof INFINITE_QUERY_KEY_MARKER];
 
+/**
+ * Whether the options give an `initialData` that is never `undefined`: a value, or a function that
+ * never returns `undefined`. Then `data` is never `undefined` either, as for TanStack Query's own
+ * `useQuery` with `DefinedInitialDataOptions`.
+ */
+type HasDefinedInitialData<Options> = Options extends { initialData: infer Initial }
+  ? Initial extends (...args: never) => infer Returned
+    ? undefined extends Returned
+      ? false
+      : true
+    : undefined extends Initial
+      ? false
+      : true
+  : false;
+
+/** The result of `useQuery`: its `data` is defined when the options give defined initial data. */
+type QueryResult<Data, Error, Options> =
+  HasDefinedInitialData<Options> extends true
+    ? DefinedUseQueryResult<Data, Error>
+    : UseQueryResult<Data, Error>;
+
+/**
+ * A defined `initialData` of the options, in the type `queryOptions` returns, so TanStack Query's
+ * `useQuery` takes the result as options with defined initial data. It is typed as the query data,
+ * as TanStack's `DefinedInitialDataOptions` types it: the type of a literal such as `[{ id: 1 }]`
+ * lacks the optional properties of the data, and TanStack's overload rejected it.
+ */
+type InitialDataOf<Options, Data> =
+  HasDefinedInitialData<Options> extends true ? { initialData: Data | (() => Data) } : unknown;
+
 export type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <
   Method extends HttpMethod,
   Path extends PathsWithMethod<Paths, Method>,
@@ -86,7 +169,7 @@ export type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <
   Options extends Omit<
     UseQueryOptions<
       QueryData<Response["data"]>,
-      Response["error"],
+      QueryError<Response["error"]>,
       InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
       QueryKey<Paths, Method, Path>
     >,
@@ -100,27 +183,28 @@ export type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <
   Omit<
     UseQueryOptions<
       QueryData<Response["data"]>,
-      Response["error"],
+      QueryError<Response["error"]>,
       InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
       QueryKey<Paths, Method, Path>
     >,
     "queryFn" | "queryKey"
-  > & {
-    queryKey: DataTag<
+  > &
+    QueryKeyWithDataTag<
       QueryKey<Paths, Method, Path>,
       QueryData<Response["data"]>,
-      Response["error"]
-    >;
-    queryFn: Exclude<
-      UseQueryOptions<
-        QueryData<Response["data"]>,
-        Response["error"],
-        InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
-        QueryKey<Paths, Method, Path>
-      >["queryFn"],
-      SkipToken | undefined
-    >;
-  }
+      QueryError<Response["error"]>
+    > &
+    InitialDataOf<Options, QueryData<Response["data"]>> & {
+      queryFn: Exclude<
+        UseQueryOptions<
+          QueryData<Response["data"]>,
+          QueryError<Response["error"]>,
+          InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
+          QueryKey<Paths, Method, Path>
+        >["queryFn"],
+        SkipToken | undefined
+      >;
+    }
 >;
 
 export type UseQueryMethod<Paths extends {}, Media extends MediaType> = <
@@ -132,7 +216,7 @@ export type UseQueryMethod<Paths extends {}, Media extends MediaType> = <
   Options extends Omit<
     UseQueryOptions<
       QueryData<Response["data"]>,
-      Response["error"],
+      QueryError<Response["error"]>,
       InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
       QueryKey<Paths, Method, Path>
     >,
@@ -142,9 +226,10 @@ export type UseQueryMethod<Paths extends {}, Media extends MediaType> = <
   method: Method,
   url: Path,
   ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>
-) => UseQueryResult<
+) => QueryResult<
   InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
-  Response["error"]
+  QueryError<Response["error"]>,
+  Options
 >;
 
 /**
@@ -212,7 +297,7 @@ export type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> =
   Options extends Omit<
     UseInfiniteQueryOptions<
       Response["data"],
-      Response["error"],
+      QueryError<Response["error"]>,
       InferSelectReturnType<
         InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>,
         Options["select"]
@@ -224,7 +309,7 @@ export type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> =
   > & {
     placeholderData?: InfinitePlaceholderData<
       Response["data"],
-      Response["error"],
+      QueryError<Response["error"]>,
       Paths,
       Method,
       Path
@@ -246,7 +331,7 @@ export type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> =
     InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>,
     Options["select"]
   >,
-  Response["error"]
+  QueryError<Response["error"]>
 >;
 
 export type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> = <
@@ -258,7 +343,7 @@ export type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> =
   Options extends Omit<
     UseSuspenseQueryOptions<
       QueryData<Response["data"]>,
-      Response["error"],
+      QueryError<Response["error"]>,
       InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
       QueryKey<Paths, Method, Path>
     >,
@@ -270,7 +355,7 @@ export type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> =
   ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>
 ) => UseSuspenseQueryResult<
   InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
-  Response["error"]
+  QueryError<Response["error"]>
 >;
 
 export type UseMutationMethod<Paths extends {}, Media extends MediaType> = <
@@ -284,11 +369,11 @@ export type UseMutationMethod<Paths extends {}, Media extends MediaType> = <
   method: Method,
   url: Path,
   options?: Omit<
-    UseMutationOptions<Response["data"], Response["error"], Init, TOnMutateResult>,
+    UseMutationOptions<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>,
     "mutationKey" | "mutationFn"
   >,
   queryClient?: QueryClient,
-) => UseMutationResult<Response["data"], Response["error"], Init, TOnMutateResult>;
+) => UseMutationResult<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>;
 
 export interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaType> {
   queryOptions: QueryOptionsFunction<Paths, Media>;
@@ -315,15 +400,47 @@ export type MethodResponse<
     ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>["data"]>
     : never;
 
+/** The `name` of every `ResponseError`. */
+const RESPONSE_ERROR_NAME = "ResponseError";
+
+/** The `ResponseError` of a failed response without an error body. */
+class ResponseWithoutErrorBody extends Error implements ResponseError {
+  override readonly name = RESPONSE_ERROR_NAME;
+  readonly response: Response;
+  readonly status: number;
+
+  constructor(response: Response) {
+    const statusText = response.statusText ? ` ${response.statusText}` : "";
+    super(`Request failed with status ${response.status}${statusText} and no error body`);
+    this.response = response;
+    this.status = response.status;
+  }
+}
+
+/**
+ * Whether `error` is the `ResponseError` of a failed response without an error body. It narrows a
+ * hook's `error`, where `error instanceof Error` also matches network and parse errors. It checks
+ * the `name`, not the class, so a `ResponseError` of another copy of this package (its CommonJS and
+ * ES module builds loaded side by side) is one too. An error body from JSON is never an `Error`.
+ */
+export function isResponseError(error: unknown): error is ResponseError {
+  return error instanceof Error && error.name === RESPONSE_ERROR_NAME;
+}
+
 /**
  * Throw the error of a failed fetch result. `if (error)` missed two failures: a non-OK response
  * with an empty body (`error` is `undefined`, upstream #2070, #2829) and a falsy error body such as
- * `0`.
+ * `0`. Without an error body a `ResponseError` is thrown, so the hooks' `error` is never
+ * `undefined` (ADR-013, decision 3). A JSON `null` body is no error body either: thrown as is, it
+ * left `error` `null` while the query's status was `"error"`.
  */
 function throwIfFailed(result: { error?: unknown; response: Response }): void {
-  if (result.error !== undefined || !result.response.ok) {
+  if (result.error !== undefined && result.error !== null) {
     throw result.error;
   }
+  if (!result.response.ok) {
+    throw new ResponseWithoutErrorBody(result.response);
+  }
 }
 
 /** The query parameter that carries the page param unless `pageParamName` names another. */
@@ -332,7 +449,6 @@ const DEFAULT_PAGE_PARAM_NAME = "cursor";
 interface PageRequest {
   readonly pageParamName: string;
   readonly pageParam: unknown;
-  readonly signal: AbortSignal;
 }
 
 /**
@@ -340,10 +456,21 @@ interface PageRequest {
  * `initialPageParam: undefined`) is left out instead of being sent as `0` (upstream #2715, #2340,
  * ADR-022), so a cursor API gets no cursor on the first page.
  */
-function pageInit(init: unknown, { pageParamName, pageParam, signal }: PageRequest) {
+function pageInit(init: unknown, { pageParamName, pageParam }: PageRequest) {
   const { params, ...rest } = (init ?? {}) as { params?: { query?: DefaultParamsOption } };
   const page = pageParam === undefined ? {} : { [pageParamName]: pageParam };
-  return { ...rest, signal, params: { ...params, query: { ...params?.query, ...page } } };
+  return { ...rest, params: { ...params, query: { ...params?.query, ...page } } };
+}
+
+/** Options of `createClient`. */
+export interface CreateClientOptions {
+  /**
+   * The name of the API in every query key, in place of the fetch client's `baseUrl`. Give the
+   * same name where the server and the browser reach one API by different URLs, so the browser
+   * reads the data the server rendered with; give different names to clients of one base URL that
+   * fetch different data, such as one per tenant header.
+   */
+  keyScope?: string;
 }
 
 /**
@@ -353,49 +480,70 @@ function pageInit(init: unknown, { pageParamName, pageParam, signal }: PageReque
 // biome-ignore lint/complexity/noExcessiveLinesPerFunction: inherited, kept until 1.1 (ADR-036)
 export default function createClient<Paths extends {}, Media extends MediaType = MediaType>(
   client: FetchClient<Paths, Media>,
+  { keyScope }: CreateClientOptions = {},
 ): OpenapiQueryClient<Paths, Media> {
-  const queryFn = async <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>>({
-    queryKey,
-    signal,
-  }: QueryFunctionContext<QueryKey<Paths, Method, Path>>) => {
-    // While `Path` is generic, TypeScript cannot work out that the key is a tuple: the init is a
-    // conditional type per operation (`MaybeOptionalInit`), and the key's type waits for it.
-    const [method, path, init] = queryKey as readonly [Method, Path, unknown?];
+  const keyClient = { baseUrl: client.baseUrl, keyScope };
+  /**
+   * Send one request of a query: the call's own init, with a signal that TanStack Query can abort.
+   * The key only names the cache entry, as for `useInfiniteQuery`: a function in the init (a
+   * `fetch`, a `middleware`) cannot be part of a key, so the request is read from the call.
+   */
+  const fetchPage = async <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>>(
+    method: Method,
+    path: Path,
+    init: unknown,
+    signal: AbortSignal,
+  ) => {
     const mth = method.toUpperCase() as Uppercase<typeof method>;
     const fn = client[mth] as ClientMethod<Paths, typeof method, Media>;
-    // The init is `unknown` here. An `any` init lets the call infer the generic response type
-    // that `queryOptions` declares; a typed init makes TypeScript compare two unresolved
-    // conditional types, which it cannot do.
-    // biome-ignore lint/suspicious/noExplicitAny: see the comment above
-    const result = await fn(path, { signal, ...(init as any) });
-    throwIfFailed(result);
-    // TanStack Query rejects `undefined` query data. The fetch client gives `undefined` for every
-    // success without a body: a 204, `Content-Length: 0`, an empty chunked body, a HEAD request
-    // (upstream #2234). A parsed body is never `undefined`, so this changes nothing else.
-    return result.data ?? null;
+    const request = withQuerySignal(init, signal);
+    try {
+      // The init is `unknown` here. An `any` init lets the call infer the generic response type
+      // that `queryOptions` declares; a typed init makes TypeScript compare two unresolved
+      // conditional types, which it cannot do.
+      // biome-ignore lint/suspicious/noExplicitAny: see the comment above
+      const result = await fn(path, request.init as any);
+      throwIfFailed(result);
+      return result.data;
+    } finally {
+      request.release();
+    }
   };
 
-  const queryOptions: QueryOptionsFunction<Paths, Media> = (method, path, ...[init, options]) => ({
-    queryKey: (init === undefined
-      ? ([method, path] as const)
-      : ([method, path, init] as const)) as DataTag<
-      QueryKey<Paths, typeof method, typeof path>,
-      // biome-ignore lint/suspicious/noExplicitAny: the declared return type sets the data type
-      any,
-      // biome-ignore lint/suspicious/noExplicitAny: the declared return type sets the error type
-      any
-    >,
-    queryFn,
-    ...options,
-  });
+  const queryOptions: QueryOptionsFunction<Paths, Media> = (method, path, ...[init, options]) => {
+    const keyInit = queryKeyInit(init, keyClient);
+    return {
+      queryKey: (keyInit === undefined
+        ? ([method, path] as const)
+        : ([method, path, keyInit] as const)) as DataTag<
+        QueryKey<Paths, typeof method, typeof path>,
+        // biome-ignore lint/suspicious/noExplicitAny: the declared return type sets the data type
+        any,
+        // biome-ignore lint/suspicious/noExplicitAny: the declared return type sets the error type
+        any
+      >,
+      // TanStack Query rejects `undefined` query data. The fetch client gives `undefined` for
+      // every success without a body: a 204, `Content-Length: 0`, an empty chunked body, a HEAD
+      // request (upstream #2234). A parsed body is never `undefined`, so this changes nothing else.
+      queryFn: async ({ signal }: QueryFunctionContext) =>
+        (await fetchPage(method, path, init, signal)) ?? null,
+      // Without options, `Options` is its constraint, which has no `initialData` to keep.
+      ...(options as typeof options & {}),
+      // The declared type types a defined `initialData` as the query data, a conditional type of
+      // the generic options that TypeScript cannot relate to the object; it is the same object.
+    } as never;
+  };
 
   return {
     queryOptions,
     useQuery: (method, path, ...[init, options, queryClient]) =>
+      // TanStack Query's `useQuery` returns `DefinedUseQueryResult` for options with defined
+      // `initialData`; while `Options` is generic it cannot pick that overload, and the declared
+      // `QueryResult` gives the caller the same answer. Both are the same object at runtime.
       useQuery(
         queryOptions(method, path, init as InitWithUnknowns<typeof init>, options),
         queryClient,
-      ),
+      ) as never,
     useSuspenseQuery: (method, path, ...[init, options, queryClient]) =>
       useSuspenseQuery(
         queryOptions(method, path, init as InitWithUnknowns<typeof init>, options),
@@ -405,23 +553,13 @@ export default function createClient<Paths extends {}, Media extends MediaType =
     useInfiniteQuery: (method, path, init, options, queryClient) => {
       const { pageParamName = DEFAULT_PAGE_PARAM_NAME, placeholderData, ...restOptions } = options;
       const { queryKey } = queryOptions(method, path, init);
-      const mth = method.toUpperCase() as Uppercase<typeof method>;
-      const fn = client[mth] as ClientMethod<Paths, typeof method, Media>;
       return useInfiniteQuery(
         {
           queryKey: [...queryKey, INFINITE_QUERY_KEY_MARKER] as const,
-          // The request comes from the arguments; the key only identifies the cache entry.
-          queryFn: async ({ pageParam, signal }) => {
-            const result = await fn(
-              path,
-              // biome-ignore lint/suspicious/noExplicitAny: a generic init; see queryFn
-              pageInit(init, { pageParamName, pageParam, signal }) as any,
-            );
-            throwIfFailed(result);
-            // An empty page stays `undefined`, as in upstream: TanStack Query rejects only
-            // `undefined` query data, and the infinite query data is the `{ pages }` object.
-            return result.data;
-          },
+          // An empty page stays `undefined`, as in upstream: TanStack Query rejects only
+          // `undefined` query data, and the infinite query data is the `{ pages }` object.
+          queryFn: ({ pageParam, signal }) =>
+            fetchPage(method, path, pageInit(init, { pageParamName, pageParam }), signal),
           ...restOptions,
           // Typed with an `unknown` page param for the caller (`InfinitePlaceholderData`). TanStack
           // passes the previous data of this query, with its own page params, and takes it back.

package/src/query-key.ts

@@ -0,0 +1,136 @@
+/**
+ * The request part of a query key (ADR-046). TanStack Query hashes a key as JSON: a `Headers`
+ * object or a list of header pairs hashed as `{}` or by its order, and so did a FormData, a Blob,
+ * an ArrayBuffer or a URLSearchParams body. Two requests that differed in them shared one cache
+ * entry, and the `queryFn` of that entry sent the request of the first. Two clients with
+ * different base URLs shared entries too. The key's init holds the headers and such a body as
+ * plain values, and the base URL the request goes to or the client's key scope, so the key names
+ * what was fetched.
+ */
+
+/** Headers as a plain object, which TanStack Query hashes by its names and values. */
+type HeadersRecord = Readonly<Record<string, unknown>>;
+
+/** What the key takes from the fetch client and the options of `createClient`. */
+export interface KeyClient {
+  /** The fetch client's base URL, `""` without one. */
+  readonly baseUrl: string;
+  /** The name of the API in every key, in place of the base URL. */
+  readonly keyScope?: string | undefined;
+}
+
+/** `[object Name]`: the type tag is between these indexes of `Object.prototype.toString`. */
+const TYPE_TAG_START = "[object ".length;
+const TYPE_TAG_END = -1;
+
+/**
+ * Whether a value is of the class `name`: an instance of this realm's global class of that name
+ * (React Native's classes have no type tag), or a value with its type tag (a class of another
+ * realm or of the `undici` package), as the fetch client tells bodies (ADR-030).
+ */
+function isClass(value: object, name: string): boolean {
+  const type = (globalThis as Record<string, unknown>)[name];
+  return (
+    (typeof type === "function" && value instanceof type) ||
+    Object.prototype.toString.call(value).slice(TYPE_TAG_START, TYPE_TAG_END) === name
+  );
+}
+
+/**
+ * The headers of an init as a plain object. A `Headers` object and a list of pairs, which are both
+ * iterable, become the names and values the request sends: names in lowercase, a repeated one
+ * joined with `, `, as `Headers` writes them. They are read without `Headers`, which threw for an
+ * invalid name or value while the component rendered; the request reports it as a query error. A
+ * plain object stays as it is, since its `null` and array values mean more than a string.
+ */
+function plainHeaders(headers: object): HeadersRecord {
+  if (!(Symbol.iterator in headers)) {
+    return headers as HeadersRecord;
+  }
+  const record: Record<string, string> = {};
+  for (const pair of headers as Iterable<unknown>) {
+    const [name, value] = Array.from(pair as ArrayLike<unknown>);
+    const key = String(name).toLowerCase();
+    record[key] = key in record ? `${record[key]}, ${String(value)}` : String(value);
+  }
+  return record;
+}
+
+/**
+ * A Blob or a File in a key: its type, size, and the name and date of a File. Its bytes cannot be
+ * read while the component renders, so two Blobs of the same type and size share an entry.
+ */
+function blobKey(blob: Blob): object {
+  const { name, lastModified } = blob as Partial<File>;
+  return { type: blob.type, size: blob.size, name, lastModified };
+}
+
+/** The fields of a FormData in a key, in order, with a file as `blobKey`. */
+function formDataKey(form: FormData): unknown[] {
+  // React Native's FormData has no `entries`, so its fields cannot be read.
+  if (typeof form.entries !== "function") {
+    return [];
+  }
+  return Array.from(form.entries(), ([name, value]) => [
+    name,
+    typeof value === "string" ? value : blobKey(value),
+  ]);
+}
+
+/** The bytes of an ArrayBuffer or a typed array, or null for another value. */
+function bodyBytes(body: object): Uint8Array | null {
+  if (ArrayBuffer.isView(body)) {
+    return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+  }
+  return isClass(body, "ArrayBuffer") ? new Uint8Array(body as ArrayBuffer) : null;
+}
+
+/**
+ * A request body as a value TanStack Query hashes by its content. A URLSearchParams is its text,
+ * a FormData its fields, a Blob `blobKey` and bytes their numbers, each under its kind, so it
+ * differs from a JSON body with the same content. Other values stay as they are.
+ */
+function bodyKey(body: unknown): unknown {
+  if (typeof body !== "object" || body === null) {
+    return body;
+  }
+  if (isClass(body, "URLSearchParams")) {
+    return { URLSearchParams: String(body) };
+  }
+  if (isClass(body, "FormData")) {
+    return { FormData: formDataKey(body as FormData) };
+  }
+  if (isClass(body, "Blob") || isClass(body, "File")) {
+    return { Blob: blobKey(body as Blob) };
+  }
+  const bytes = bodyBytes(body);
+  return bytes === null ? body : { bytes: Array.from(bytes) };
+}
+
+/**
+ * The init of a query key: the request init with its headers and body as plain values, and the
+ * client's key scope, or its base URL when the init has none. The `signal` is left out: TanStack
+ * Query gives each request its own. Undefined when nothing is left, so a call without an init and
+ * one with an empty init have the key `[method, path]`.
+ */
+export function queryKeyInit(init: unknown, client: KeyClient): object | undefined {
+  const { signal: _signal, ...rest } = (init ?? {}) as {
+    signal?: unknown;
+    headers?: unknown;
+    baseUrl?: unknown;
+    body?: unknown;
+  };
+  const keyInit: Record<string, unknown> = { ...rest };
+  if (typeof rest.headers === "object" && rest.headers !== null) {
+    keyInit.headers = plainHeaders(rest.headers);
+  }
+  if ("body" in rest) {
+    keyInit.body = bodyKey(rest.body);
+  }
+  if (client.keyScope !== undefined) {
+    keyInit.keyScope = client.keyScope;
+  } else if (!rest.baseUrl && client.baseUrl) {
+    keyInit.baseUrl = client.baseUrl;
+  }
+  return Object.keys(keyInit).length === 0 ? undefined : keyInit;
+}

package/src/query-signal.ts

@@ -0,0 +1,47 @@
+/**
+ * The signal of a query's request. TanStack Query gives every request a signal, which it aborts
+ * when the query is cancelled or no longer used; the init of the call may bring its own. The hooks
+ * sent one of them: `useQuery` the call's, so a cancelled query kept its request, and
+ * `useInfiniteQuery` TanStack's, so the call's signal did nothing. The request now stops when
+ * either is aborted.
+ */
+
+/** The init to send, and how to stop listening to the signals once the request has settled. */
+export interface QueryRequest {
+  readonly init: Record<string, unknown>;
+  readonly release: () => void;
+}
+
+const ABORT_EVENT = "abort";
+
+function withoutRelease(init: Record<string, unknown>): QueryRequest {
+  return { init, release: () => undefined };
+}
+
+/** The init with a signal that aborts when the init's own signal or the query's does. */
+export function withQuerySignal(init: unknown, querySignal: AbortSignal): QueryRequest {
+  const { signal: ownSignal, ...rest } = (init ?? {}) as { signal?: AbortSignal | null };
+  if (!ownSignal) {
+    return withoutRelease({ ...rest, signal: querySignal });
+  }
+  const controller = new AbortController();
+  const sources = [ownSignal, querySignal];
+  const aborted = sources.find((source) => source.aborted);
+  if (aborted !== undefined) {
+    controller.abort(aborted.reason);
+    return withoutRelease({ ...rest, signal: controller.signal });
+  }
+  const listeners = sources.map((source) => {
+    const listener = () => controller.abort(source.reason);
+    source.addEventListener(ABORT_EVENT, listener, { once: true });
+    return () => source.removeEventListener(ABORT_EVENT, listener);
+  });
+  return {
+    init: { ...rest, signal: controller.signal },
+    release: () => {
+      for (const remove of listeners) {
+        remove();
+      }
+    },
+  };
+}