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

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { UseQueryOptions, DataTag, SkipToken, QueryClient, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult, UseInfiniteQueryOptions, InfiniteData, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { UseQueryOptions, DefaultError, DataTag, SkipToken, QueryClient, DefinedUseQueryResult, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult, UseInfiniteQueryOptions, InfiniteData, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
 import { MaybeOptionalInit, FetchResponse, PathOperation, Client } from 'openapi-typesafe-fetch';
-import { HttpMethod, PathsWithMethod, MediaType, RequiredKeysOf } from 'openapi-typesafe-helpers';
+import { HttpMethod, PathsWithMethod, MediaType, RequiredKeysOf } from 'openapi-typesafe-fetch/helpers';
 
 type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer R ? R : TData;
 /**
@@ -8,6 +8,40 @@ type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => in
  * `null` in the query, as `queryFn` resolves it (upstream #2234, #2464).
  */
 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.
+ */
+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`.
+ */
+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`.
+ */
+type QueryKeyWithDataTag<Key, Data, Error> = {
+    queryKey: DataTag<Key, Data, Error>;
+};
 type InitWithUnknowns<Init> = Init & {
     [key: string]: unknown;
 };
@@ -20,20 +54,44 @@ type InitWithUnknowns<Init> = Init & {
  * so `Parameters<typeof $api.queryOptions>` still requires it then (upstream #2178).
  */
 type InitArguments<Init, Rest extends unknown[]> = RequiredKeysOf<Init> extends never ? [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.
+ */
 type QueryKey<Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init = MaybeOptionalInit<Paths[Path], Method>> = Init extends undefined ? readonly [Method, Path] : readonly [Method, Path, Init];
 /**
  * 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.
  */
 declare const INFINITE_QUERY_KEY_MARKER = "infinite";
 type InfiniteQueryKey<Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>> = readonly [...QueryKey<Paths, Method, Path>, typeof INFINITE_QUERY_KEY_MARKER];
-type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, path: Path, ...[init, options]: InitArguments<Init, [Options?]>) => NoInfer<Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn" | "queryKey"> & {
-    queryKey: DataTag<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>;
+/**
+ * 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;
+type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, path: Path, ...[init, options]: InitArguments<Init, [Options?]>) => NoInfer<Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn" | "queryKey"> & QueryKeyWithDataTag<QueryKey<Paths, Method, Path>, QueryData<Response["data"]>, 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>;
 }>;
-type UseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"]>;
+type UseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => QueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryError<Response["error"]>, Options>;
 /**
  * The type of the page params: the initial one and the ones `getNextPageParam` and
  * `getPreviousPageParam` return (upstream #2458). It was `unknown`. It stays `unknown` when a
@@ -65,12 +123,12 @@ interface PageParamSources<Initial, Next, Previous> {
  * `unknown` there and failed against the typed page param.
  */
 type InfinitePlaceholderData<Data, Error, Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>> = UseInfiniteQueryOptions<Data, Error, InfiniteData<Data, unknown>, InfiniteQueryKey<Paths, Method, Path>, unknown>["placeholderData"];
-type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], Response["error"], InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, InfiniteQueryKey<Paths, Method, Path>, PageParam<Initial, Next, Previous>>, "queryKey" | "queryFn" | "placeholderData"> & {
-    placeholderData?: InfinitePlaceholderData<Response["data"], Response["error"], Paths, Method, Path>;
+type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], QueryError<Response["error"]>, InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, InfiniteQueryKey<Paths, Method, Path>, PageParam<Initial, Next, Previous>>, "queryKey" | "queryFn" | "placeholderData"> & {
+    placeholderData?: InfinitePlaceholderData<Response["data"], QueryError<Response["error"]>, Paths, Method, Path>;
     pageParamName?: string;
-}, Initial = unknown, Next = never, Previous = NoPreviousPageParam>(method: Method, url: Path, init: InitWithUnknowns<Init>, options: PageParamSources<Initial, Next, Previous> & Options, queryClient?: QueryClient) => UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, Response["error"]>;
-type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseSuspenseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseSuspenseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"]>;
-type UseMutationMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, TOnMutateResult = unknown>(method: Method, url: Path, options?: Omit<UseMutationOptions<Response["data"], Response["error"], Init, TOnMutateResult>, "mutationKey" | "mutationFn">, queryClient?: QueryClient) => UseMutationResult<Response["data"], Response["error"], Init, TOnMutateResult>;
+}, Initial = unknown, Next = never, Previous = NoPreviousPageParam>(method: Method, url: Path, init: InitWithUnknowns<Init>, options: PageParamSources<Initial, Next, Previous> & Options, queryClient?: QueryClient) => UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, QueryError<Response["error"]>>;
+type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseSuspenseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseSuspenseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryError<Response["error"]>>;
+type UseMutationMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, TOnMutateResult = unknown>(method: Method, url: Path, options?: Omit<UseMutationOptions<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>, "mutationKey" | "mutationFn">, queryClient?: QueryClient) => UseMutationResult<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>;
 interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaType> {
     queryOptions: QueryOptionsFunction<Paths, Media>;
     useQuery: UseQueryMethod<Paths, Media>;
@@ -81,11 +139,28 @@ interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaTy
 type MethodResponse<CreatedClient extends OpenapiQueryClient<any, any>, Method extends HttpMethod, Path extends CreatedClient extends OpenapiQueryClient<infer Paths, infer _Media> ? PathsWithMethod<Paths, Method> : never, Options = object> = CreatedClient extends OpenapiQueryClient<infer Paths extends {
     [key: string]: any;
 }, infer Media extends MediaType> ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>["data"]> : never;
+/**
+ * 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`.
+ */
+declare function isResponseError(error: unknown): error is ResponseError;
+/** Options of `createClient`. */
+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;
+}
 /**
  * Hooks and query options for a fetch client. A `QueryClient` other than the one from the React
  * context is passed to each hook as its last argument; `createClient` does not take one.
  */
-declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>): OpenapiQueryClient<Paths, Media>;
+declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>, { keyScope }?: CreateClientOptions): OpenapiQueryClient<Paths, Media>;
 
-export { createClient as default };
-export type { InfiniteQueryKey, MethodResponse, OpenapiQueryClient, QueryKey, QueryOptionsFunction, UseInfiniteQueryMethod, UseMutationMethod, UseQueryMethod, UseSuspenseQueryMethod };
+export { createClient as default, isResponseError };
+export type { CreateClientOptions, InfiniteQueryKey, MethodResponse, OpenapiQueryClient, QueryError, QueryKey, QueryKeyWithDataTag, QueryOptionsFunction, ResponseError, UseInfiniteQueryMethod, UseMutationMethod, UseQueryMethod, UseSuspenseQueryMethod };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { UseQueryOptions, DataTag, SkipToken, QueryClient, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult, UseInfiniteQueryOptions, InfiniteData, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
+import { UseQueryOptions, DefaultError, DataTag, SkipToken, QueryClient, DefinedUseQueryResult, UseQueryResult, UseSuspenseQueryOptions, UseSuspenseQueryResult, UseInfiniteQueryOptions, InfiniteData, UseInfiniteQueryResult, UseMutationOptions, UseMutationResult } from '@tanstack/react-query';
 import { MaybeOptionalInit, FetchResponse, PathOperation, Client } from 'openapi-typesafe-fetch';
-import { HttpMethod, PathsWithMethod, MediaType, RequiredKeysOf } from 'openapi-typesafe-helpers';
+import { HttpMethod, PathsWithMethod, MediaType, RequiredKeysOf } from 'openapi-typesafe-fetch/helpers';
 
 type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => infer R ? R : TData;
 /**
@@ -8,6 +8,40 @@ type InferSelectReturnType<TData, TSelect> = TSelect extends (data: TData) => in
  * `null` in the query, as `queryFn` resolves it (upstream #2234, #2464).
  */
 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.
+ */
+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`.
+ */
+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`.
+ */
+type QueryKeyWithDataTag<Key, Data, Error> = {
+    queryKey: DataTag<Key, Data, Error>;
+};
 type InitWithUnknowns<Init> = Init & {
     [key: string]: unknown;
 };
@@ -20,20 +54,44 @@ type InitWithUnknowns<Init> = Init & {
  * so `Parameters<typeof $api.queryOptions>` still requires it then (upstream #2178).
  */
 type InitArguments<Init, Rest extends unknown[]> = RequiredKeysOf<Init> extends never ? [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.
+ */
 type QueryKey<Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init = MaybeOptionalInit<Paths[Path], Method>> = Init extends undefined ? readonly [Method, Path] : readonly [Method, Path, Init];
 /**
  * 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.
  */
 declare const INFINITE_QUERY_KEY_MARKER = "infinite";
 type InfiniteQueryKey<Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>> = readonly [...QueryKey<Paths, Method, Path>, typeof INFINITE_QUERY_KEY_MARKER];
-type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, path: Path, ...[init, options]: InitArguments<Init, [Options?]>) => NoInfer<Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn" | "queryKey"> & {
-    queryKey: DataTag<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>;
+/**
+ * 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;
+type QueryOptionsFunction<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, path: Path, ...[init, options]: InitArguments<Init, [Options?]>) => NoInfer<Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryFn" | "queryKey"> & QueryKeyWithDataTag<QueryKey<Paths, Method, Path>, QueryData<Response["data"]>, 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>;
 }>;
-type UseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"]>;
+type UseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => QueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryError<Response["error"]>, Options>;
 /**
  * The type of the page params: the initial one and the ones `getNextPageParam` and
  * `getPreviousPageParam` return (upstream #2458). It was `unknown`. It stays `unknown` when a
@@ -65,12 +123,12 @@ interface PageParamSources<Initial, Next, Previous> {
  * `unknown` there and failed against the typed page param.
  */
 type InfinitePlaceholderData<Data, Error, Paths extends {}, Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>> = UseInfiniteQueryOptions<Data, Error, InfiniteData<Data, unknown>, InfiniteQueryKey<Paths, Method, Path>, unknown>["placeholderData"];
-type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], Response["error"], InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, InfiniteQueryKey<Paths, Method, Path>, PageParam<Initial, Next, Previous>>, "queryKey" | "queryFn" | "placeholderData"> & {
-    placeholderData?: InfinitePlaceholderData<Response["data"], Response["error"], Paths, Method, Path>;
+type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseInfiniteQueryOptions<Response["data"], QueryError<Response["error"]>, InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, InfiniteQueryKey<Paths, Method, Path>, PageParam<Initial, Next, Previous>>, "queryKey" | "queryFn" | "placeholderData"> & {
+    placeholderData?: InfinitePlaceholderData<Response["data"], QueryError<Response["error"]>, Paths, Method, Path>;
     pageParamName?: string;
-}, Initial = unknown, Next = never, Previous = NoPreviousPageParam>(method: Method, url: Path, init: InitWithUnknowns<Init>, options: PageParamSources<Initial, Next, Previous> & Options, queryClient?: QueryClient) => UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, Response["error"]>;
-type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseSuspenseQueryOptions<QueryData<Response["data"]>, Response["error"], InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseSuspenseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, Response["error"]>;
-type UseMutationMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, TOnMutateResult = unknown>(method: Method, url: Path, options?: Omit<UseMutationOptions<Response["data"], Response["error"], Init, TOnMutateResult>, "mutationKey" | "mutationFn">, queryClient?: QueryClient) => UseMutationResult<Response["data"], Response["error"], Init, TOnMutateResult>;
+}, Initial = unknown, Next = never, Previous = NoPreviousPageParam>(method: Method, url: Path, init: InitWithUnknowns<Init>, options: PageParamSources<Initial, Next, Previous> & Options, queryClient?: QueryClient) => UseInfiniteQueryResult<InferSelectReturnType<InfiniteData<Response["data"], PageParam<Initial, Next, Previous>>, Options["select"]>, QueryError<Response["error"]>>;
+type UseSuspenseQueryMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, Options extends Omit<UseSuspenseQueryOptions<QueryData<Response["data"]>, QueryError<Response["error"]>, InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryKey<Paths, Method, Path>>, "queryKey" | "queryFn">>(method: Method, url: Path, ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>) => UseSuspenseQueryResult<InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>, QueryError<Response["error"]>>;
+type UseMutationMethod<Paths extends {}, Media extends MediaType> = <Method extends HttpMethod, Path extends PathsWithMethod<Paths, Method>, Init extends MaybeOptionalInit<Paths[Path], Method>, Response extends Required<FetchResponse<PathOperation<Paths, Path, Method>, Init, Media>>, TOnMutateResult = unknown>(method: Method, url: Path, options?: Omit<UseMutationOptions<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>, "mutationKey" | "mutationFn">, queryClient?: QueryClient) => UseMutationResult<Response["data"], QueryError<Response["error"]>, Init, TOnMutateResult>;
 interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaType> {
     queryOptions: QueryOptionsFunction<Paths, Media>;
     useQuery: UseQueryMethod<Paths, Media>;
@@ -81,11 +139,28 @@ interface OpenapiQueryClient<Paths extends {}, Media extends MediaType = MediaTy
 type MethodResponse<CreatedClient extends OpenapiQueryClient<any, any>, Method extends HttpMethod, Path extends CreatedClient extends OpenapiQueryClient<infer Paths, infer _Media> ? PathsWithMethod<Paths, Method> : never, Options = object> = CreatedClient extends OpenapiQueryClient<infer Paths extends {
     [key: string]: any;
 }, infer Media extends MediaType> ? NonNullable<FetchResponse<Paths[Path][Method], Options, Media>["data"]> : never;
+/**
+ * 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`.
+ */
+declare function isResponseError(error: unknown): error is ResponseError;
+/** Options of `createClient`. */
+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;
+}
 /**
  * Hooks and query options for a fetch client. A `QueryClient` other than the one from the React
  * context is passed to each hook as its last argument; `createClient` does not take one.
  */
-declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>): OpenapiQueryClient<Paths, Media>;
+declare function createClient<Paths extends {}, Media extends MediaType = MediaType>(client: Client<Paths, Media>, { keyScope }?: CreateClientOptions): OpenapiQueryClient<Paths, Media>;
 
-export { createClient as default };
-export type { InfiniteQueryKey, MethodResponse, OpenapiQueryClient, QueryKey, QueryOptionsFunction, UseInfiniteQueryMethod, UseMutationMethod, UseQueryMethod, UseSuspenseQueryMethod };
+export { createClient as default, isResponseError };
+export type { CreateClientOptions, InfiniteQueryKey, MethodResponse, OpenapiQueryClient, QueryError, QueryKey, QueryKeyWithDataTag, QueryOptionsFunction, ResponseError, UseInfiniteQueryMethod, UseMutationMethod, UseQueryMethod, UseSuspenseQueryMethod };

package/dist/index.mjs

@@ -1,39 +1,174 @@
 import { useMutation, useInfiniteQuery, useSuspenseQuery, useQuery } from '@tanstack/react-query';
 
+const TYPE_TAG_START = "[object ".length;
+const TYPE_TAG_END = -1;
+function isClass(value, name) {
+  const type = globalThis[name];
+  return typeof type === "function" && value instanceof type || Object.prototype.toString.call(value).slice(TYPE_TAG_START, TYPE_TAG_END) === name;
+}
+function plainHeaders(headers) {
+  if (!(Symbol.iterator in headers)) {
+    return headers;
+  }
+  const record = {};
+  for (const pair of headers) {
+    const [name, value] = Array.from(pair);
+    const key = String(name).toLowerCase();
+    record[key] = key in record ? `${record[key]}, ${String(value)}` : String(value);
+  }
+  return record;
+}
+function blobKey(blob) {
+  const { name, lastModified } = blob;
+  return { type: blob.type, size: blob.size, name, lastModified };
+}
+function formDataKey(form) {
+  if (typeof form.entries !== "function") {
+    return [];
+  }
+  return Array.from(form.entries(), ([name, value]) => [
+    name,
+    typeof value === "string" ? value : blobKey(value)
+  ]);
+}
+function bodyBytes(body) {
+  if (ArrayBuffer.isView(body)) {
+    return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+  }
+  return isClass(body, "ArrayBuffer") ? new Uint8Array(body) : null;
+}
+function bodyKey(body) {
+  if (typeof body !== "object" || body === null) {
+    return body;
+  }
+  if (isClass(body, "URLSearchParams")) {
+    return { URLSearchParams: String(body) };
+  }
+  if (isClass(body, "FormData")) {
+    return { FormData: formDataKey(body) };
+  }
+  if (isClass(body, "Blob") || isClass(body, "File")) {
+    return { Blob: blobKey(body) };
+  }
+  const bytes = bodyBytes(body);
+  return bytes === null ? body : { bytes: Array.from(bytes) };
+}
+function queryKeyInit(init, client) {
+  const { signal: _signal, ...rest } = init ?? {};
+  const keyInit = { ...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 !== void 0) {
+    keyInit.keyScope = client.keyScope;
+  } else if (!rest.baseUrl && client.baseUrl) {
+    keyInit.baseUrl = client.baseUrl;
+  }
+  return Object.keys(keyInit).length === 0 ? void 0 : keyInit;
+}
+
+const ABORT_EVENT = "abort";
+function withoutRelease(init) {
+  return { init, release: () => void 0 };
+}
+function withQuerySignal(init, querySignal) {
+  const { signal: ownSignal, ...rest } = init ?? {};
+  if (!ownSignal) {
+    return withoutRelease({ ...rest, signal: querySignal });
+  }
+  const controller = new AbortController();
+  const sources = [ownSignal, querySignal];
+  const aborted = sources.find((source) => source.aborted);
+  if (aborted !== void 0) {
+    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();
+      }
+    }
+  };
+}
+
 const INFINITE_QUERY_KEY_MARKER = "infinite";
+const RESPONSE_ERROR_NAME = "ResponseError";
+class ResponseWithoutErrorBody extends Error {
+  name = RESPONSE_ERROR_NAME;
+  response;
+  status;
+  constructor(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;
+  }
+}
+function isResponseError(error) {
+  return error instanceof Error && error.name === RESPONSE_ERROR_NAME;
+}
 function throwIfFailed(result) {
-  if (result.error !== void 0 || !result.response.ok) {
+  if (result.error !== void 0 && result.error !== null) {
     throw result.error;
   }
+  if (!result.response.ok) {
+    throw new ResponseWithoutErrorBody(result.response);
+  }
 }
 const DEFAULT_PAGE_PARAM_NAME = "cursor";
-function pageInit(init, { pageParamName, pageParam, signal }) {
+function pageInit(init, { pageParamName, pageParam }) {
   const { params, ...rest } = init ?? {};
   const page = pageParam === void 0 ? {} : { [pageParamName]: pageParam };
-  return { ...rest, signal, params: { ...params, query: { ...params?.query, ...page } } };
+  return { ...rest, params: { ...params, query: { ...params?.query, ...page } } };
 }
-function createClient(client) {
-  const queryFn = async ({
-    queryKey,
-    signal
-  }) => {
-    const [method, path, init] = queryKey;
+function createClient(client, { keyScope } = {}) {
+  const keyClient = { baseUrl: client.baseUrl, keyScope };
+  const fetchPage = async (method, path, init, signal) => {
     const mth = method.toUpperCase();
     const fn = client[mth];
-    const result = await fn(path, { signal, ...init });
-    throwIfFailed(result);
-    return result.data ?? null;
+    const request = withQuerySignal(init, signal);
+    try {
+      const result = await fn(path, request.init);
+      throwIfFailed(result);
+      return result.data;
+    } finally {
+      request.release();
+    }
+  };
+  const queryOptions = (method, path, ...[init, options]) => {
+    const keyInit = queryKeyInit(init, keyClient);
+    return {
+      queryKey: keyInit === void 0 ? [method, path] : [method, path, keyInit],
+      // 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 }) => await fetchPage(method, path, init, signal) ?? null,
+      // Without options, `Options` is its constraint, which has no `initialData` to keep.
+      ...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.
+    };
   };
-  const queryOptions = (method, path, ...[init, options]) => ({
-    queryKey: init === void 0 ? [method, path] : [method, path, init],
-    queryFn,
-    ...options
-  });
   return {
     queryOptions,
-    useQuery: (method, path, ...[init, options, queryClient]) => useQuery(
-      queryOptions(method, path, init, options),
-      queryClient
+    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, options),
+        queryClient
+      )
     ),
     useSuspenseQuery: (method, path, ...[init, options, queryClient]) => useSuspenseQuery(
       queryOptions(method, path, init, options),
@@ -43,21 +178,12 @@ function createClient(client) {
     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();
-      const fn = client[mth];
       return useInfiniteQuery(
         {
           queryKey: [...queryKey, INFINITE_QUERY_KEY_MARKER],
-          // 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 })
-            );
-            throwIfFailed(result);
-            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.
@@ -85,5 +211,5 @@ function createClient(client) {
   };
 }
 
-export { createClient as default };
+export { createClient as default, isResponseError };
 //# sourceMappingURL=index.mjs.map