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

package/src/index.ts

@@ -1,5 +1,6 @@
 import {
   type DataTag,
+  type DefaultError,
   type InfiniteData,
   type QueryClient,
   type QueryFunctionContext,
@@ -25,12 +26,15 @@ 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";
 
 // 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 +45,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 };
 
 /**
@@ -66,8 +110,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";
 
@@ -86,7 +130,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 +144,27 @@ 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"]>
+    > & {
+      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 +176,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>
     >,
@@ -144,7 +188,7 @@ export type UseQueryMethod<Paths extends {}, Media extends MediaType> = <
   ...[init, options, queryClient]: InitArguments<Init, [Options?, QueryClient?]>
 ) => UseQueryResult<
   InferSelectReturnType<QueryData<Response["data"]>, Options["select"]>,
-  Response["error"]
+  QueryError<Response["error"]>
 >;
 
 /**
@@ -212,7 +256,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 +268,7 @@ export type UseInfiniteQueryMethod<Paths extends {}, Media extends MediaType> =
   > & {
     placeholderData?: InfinitePlaceholderData<
       Response["data"],
-      Response["error"],
+      QueryError<Response["error"]>,
       Paths,
       Method,
       Path
@@ -246,7 +290,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 +302,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 +314,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 +328,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 +359,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. */