openapi-typesafe-react-query 1.0.0-rc.4 → 1.0.0-rc.6

package/src/index.ts

@@ -1,6 +1,7 @@
 import {
   type DataTag,
   type DefaultError,
+  type DefinedUseQueryResult,
   type InfiniteData,
   type QueryClient,
   type QueryFunctionContext,
@@ -35,6 +36,8 @@ import type {
   PathsWithMethod,
   RequiredKeysOf,
 } 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;
@@ -100,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,
@@ -121,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>,
@@ -154,7 +193,8 @@ export type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <
       QueryKey<Paths, Method, Path>,
       QueryData<Response["data"]>,
       QueryError<Response["error"]>
-    > & {
+    > &
+    InitialDataOf<Options, QueryData<Response["data"]>> & {
       queryFn: Exclude<
         UseQueryOptions<
           QueryData<Response["data"]>,
@@ -186,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"]>,
-  QueryError<Response["error"]>
+  QueryError<Response["error"]>,
+  Options
 >;
 
 /**
@@ -408,7 +449,6 @@ const DEFAULT_PAGE_PARAM_NAME = "cursor";
 interface PageRequest {
   readonly pageParamName: string;
   readonly pageParam: unknown;
-  readonly signal: AbortSignal;
 }
 
 /**
@@ -416,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;
 }
 
 /**
@@ -429,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),
@@ -481,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,154 @@
+/**
+ * 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 of a File. Its bytes cannot be read while
+ * the component renders, so two Blobs of the same type and size share an entry. The date of a File
+ * is left out: `FormData.append` and `new File` set it to the current time, so a body built while
+ * rendering got a new key, and a new request, on every render.
+ */
+function blobKey(blob: Blob): object {
+  const { name } = blob as Partial<File>;
+  return { type: blob.type, size: blob.size, name };
+}
+
+/** 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 body that JSON cannot hold, as a value TanStack Query hashes, and the name of its kind. */
+interface RawBodyKey {
+  readonly body: unknown;
+  readonly bodyType: "URLSearchParams" | "FormData" | "Blob" | "bytes";
+}
+
+/**
+ * A body that JSON cannot hold by its content: a URLSearchParams as its text, a FormData as its
+ * fields, a Blob as `blobKey` and bytes as their numbers. Undefined for any other body.
+ */
+function rawBodyKey(body: unknown): RawBodyKey | undefined {
+  if (typeof body !== "object" || body === null) {
+    return undefined;
+  }
+  if (isClass(body, "URLSearchParams")) {
+    return { body: String(body), bodyType: "URLSearchParams" };
+  }
+  if (isClass(body, "FormData")) {
+    return { body: formDataKey(body as FormData), bodyType: "FormData" };
+  }
+  if (isClass(body, "Blob") || isClass(body, "File")) {
+    return { body: blobKey(body as Blob), bodyType: "Blob" };
+  }
+  const bytes = bodyBytes(body);
+  return bytes === null ? undefined : { body: Array.from(bytes), bodyType: "bytes" };
+}
+
+/**
+ * The init fields that are not `undefined`. A field set to `undefined` (`headers: token ? … :
+ * undefined`) sends the same request as none, so it must not make the init count as not empty.
+ */
+function definedFields(fields: object): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * 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. A body that JSON cannot hold also names its kind in
+ * `bodyType`, a field no init has, so it never shares a key with a JSON body of the same content.
+ * Undefined when nothing is left, so a call without an init and one with an empty init, or one
+ * of only `undefined` fields, 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 = definedFields(rest);
+  if (typeof rest.headers === "object" && rest.headers !== null) {
+    keyInit.headers = plainHeaders(rest.headers);
+  }
+  const rawBody = rawBodyKey(rest.body);
+  if (rawBody !== undefined) {
+    Object.assign(keyInit, rawBody);
+  }
+  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();
+      }
+    },
+  };
+}