feat(types): TError can now globally be defaulted / registered (#4903)

* types: TError can now globally be defaulted / registered

* docs: add DefaultError

* test: stabilize a flaky test

Author: TkDodo

docs/react/guides/migrating-to-v5.md

@@ -167,7 +167,7 @@ const queryClient = new QueryClient({
 
 To make the `useErrorBoundary` option more framework-agnostic and avoid confusion with the established React function prefix "`use`" for hooks and the "ErrorBoundary" component name, it has been renamed to `throwErrors` to more accurately reflect its functionality.
 
-### `Error` is now the default type for errors instead of `unknown`
+### TypeScript: `Error` is now the default type for errors instead of `unknown`
 
 Even though in JavaScript, you can `throw` anything (which makes `unknown` the most correct type), almost always, `Errors` (or subclasses of `Error`) are thrown. This change makes it easier to work with the `error` field in TypeScript for most cases.
 
@@ -185,6 +185,8 @@ useQuery<number, string>({
 })
 ```
 
+For a way to set a different kind of Error globally, see [the TypeScript Guide](../typescript#registering-a-global-error).
+
 ### eslint `prefer-query-object-syntax` rule is removed
 
 Since the only supported syntax now is the object syntax, this rule is no longer needed

docs/react/typescript.md

@@ -85,34 +85,59 @@ if (isSuccess) {
 
 ## Typing the error field
 
-The type for error defaults to `unknown`. This is in line with what TypeScript gives you per default in a catch clauses (see [useUnknownInCatchVariables](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#use-unknown-catch-variables)). The safest way to work with `error` would be to perform a runtime check; another way would be to explicitly define types for `data` and `error`:
+The type for error defaults to `Error`, because that is what most users expect.
 
 ```tsx
 const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
-//      ^? const error: unknown
-
-if (error instanceof Error) {
-  error
-  // ^? const error: Error
-}
+//      ^? const error: Error
 ```
 
 [//]: # 'Playground5'
 
-[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAORToCGAxjALQCOO+VAsAFCiSw4dAB7AIqUuUpURY1Nx68YeMOjgBxcsjBwAvIjjAAJgC44AO2QgARriK9eDCOdTwS6GAwAWmiNon6ABQAlGYAClLAGAA8vtoA2gC6AHx6qbLiAHQA5h6BVAD02Vpg8sGZMF7o5oG0qJAuarqpdQ0YmUZ0MHTBDjxOLvBIuORQRHooGNi4eIHxVMV+pVSJADSkHt5xpb08BQVwh0cAegD8fcAkcIEj0IaDdOYM6BBXAKJQo8GIvIe3ULx9nAzrxCEA)
+[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAOQACMAhgHaoMDGA1gPRTr2swBaAI458VALAAoUJFhx6AD2ARUpcpSqLlqCZKkw8YdHADi5ZGDgBeRHGAATAFxxGyEACNcRKVNYRm8CToMKwAFmYQFqo2ABQAlM4ACurAGAA8ERYA2gC6AHzWBVoqAHQA5sExVJxl5mA6cSUwoeiMMTyokMzGVgUdXRgl9vQMcT6SfgG2uORQRNYoGNi4eDFZVLWR9VQ5ADSkwWGZ9WOSnJxwl1cAegD8QA)
 
 [//]: # 'Playground5'
 
+If you want to throw a custom error, or something that isn't an Error at all, you can specify the type of the error field:
+
 ```tsx
-const { error } = useQuery<Group[], Error>(['groups'], fetchGroups)
+const { error } = useQuery<Group[], string>(['groups'], fetchGroups)
+//      ^? const error: string | null
+```
+
+However, this has the drawback that type inference for all other generics of `useQuery` will not work anymore. It is generally not considered a good practice to throw something that isn't and `Error`, so if you have a subclass like `AxisError` you can use _type narrowing_ to make the error field more specific:
+
+```tsx
+import axios from 'axios'
+
+const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
 //      ^? const error: Error | null
+
+if (axios.isAxiosError(error)) {
+  error
+  // ^? const error: AxiosError
+}
 ```
 
+[//]: # 'Playground6'
+[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAOQACMAhgHaoMDGA1gPRTr2swBaAI458VALAAoUJFhx6AD2ARUpcpSqLlqCZKkw8YdHADi5ZGDgBeRHGAATAFxxGyEACNcRKVNYRm8CToMKwAFmYQFqo2ABQAlM4ACurAGAA8ERYA2gC6AHzWBVoqAHQA5sExVJxl5mA6cSUwoeiMMTyokMzGVgUdXRgl9vQMcT6SfgG2uORQRNYoGNi4eDFIIisA0uh4zllUtZH1VDkANHAb+ABijM5BIeF1qoRjkpyccJ9fAHoA-OPAEhwGLFVAlVIAQSUKgAolBZjEZtA4nFEFJPkioOi4O84H8pIQgA)
 [//]: # 'Playground6'
 
-[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAORToCGAxjALQCOO+VAsAFCiSw4dAB7AIqUuUpURY1Nx68YeMOjgBxcsjBwAvIjjAAJgC44AO2QgARriK9eDCOdTwS6GAwAWmiNon6ABQAlGYAClLAGAA8vtoA2gC6AHx6qbLiAHQA5h6BVAD02Vpg8sGZMF7o5oG0qJAuarqpdQ0YmUZ0MHTBDjxOLvBIuORQRHooGNi4eLElSQA0cACiUKPJgfFUxX6lVIlL7p4+Jai9PAUFcNc3AHoA-LxAA)
+### Registering a global Error
+
+TanStack Query v5 allows for a way to set a global Error type for everything, without having to specify generics on call-sides, by amending the `Register` interface. This will make sure inference still works, but the error field will be of the specified type:
+
+```tsx
+declare module '@tanstack/react-query' {
+  interface Register {
+    defaultError: AxiosError
+  }
+}
+
+const { error } = useQuery({ queryKey: ['groups'], queryFn: fetchGroups })
+//      ^? const error: AxiosError | null
+```
 
-[//]: # 'Playground6'
 [//]: # 'Materials'
 
 ## Further Reading

docs/vue/typescript.md

@@ -33,7 +33,7 @@ replace:
 [//]: # 'Playground5'
 [//]: # 'Playground6'
 
-[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAOQACMAhgHaoMDGA1gPQBuOAtAEcc+KgFgAUKEiw49AB7AIqUuUpV5i1GPESYeMOjgBxcsjBwAvIjjAAJgC44jZCABGuIhImsIzeCXQYVgALEwgzZSsACgBKRwAFVWAMAB4wswBtAF0APks8jSUAOgBzQKiqThLTMC0Yophg9EYoqHRUSGZDCzy2jt8MItt6BhivcR8-a1xyKCJLFAxsXDw0muyAGjgAUShZnKiMqmrw2qosrYCg0JrUMfFOTjhnl4A9AH4JIA)
+[typescript playground](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAbzgVwM4FMCKz1QJ5wC+cAZlBCHAOQACMAhgHaoMDGA1gPRTr2swBaAI458VALAAoUJFhx6AD2ARUpcpSqLlqCZKkw8YdHADi5ZGDgBeRHGAATAFxxGyEACNcRKVNYRm8CToMKwAFmYQFqo2ABQAlM4ACurAGAA8ERYA2gC6AHzWBVoqAHQA5sExVJxl5mA6cSUwoeiMMTyokMzGVgUdXRgl9vQMcT6SfgG2uORQRNYoGNi4eDFIIisA0uh4zllUtZH1VDkANHAb+ABijM5BIeF1qoRjkpyccJ9fAHoA-OPAEhwGLFVAlVIAQSUKgAolBZjEZtA4nFEFJPkioOi4O84H8pIQgA)
 
 [//]: # 'Playground6'
 [//]: # 'Materials'

packages/query-core/src/infiniteQueryObserver.ts

@@ -6,6 +6,7 @@ import type {
   InfiniteQueryObserverOptions,
   InfiniteQueryObserverResult,
   QueryKey,
+  RegisteredError,
 } from './types'
 import type { QueryClient } from './queryClient'
 import type { NotifyOptions, ObserverFetchOptions } from './queryObserver'
@@ -23,7 +24,7 @@ type InfiniteQueryObserverListener<TData, TError> = (
 
 export class InfiniteQueryObserver<
   TQueryFnData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,

packages/query-core/src/mutation.ts

@@ -1,4 +1,9 @@
-import type { MutationOptions, MutationStatus, MutationMeta } from './types'
+import type {
+  MutationOptions,
+  MutationStatus,
+  MutationMeta,
+  RegisteredError,
+} from './types'
 import type { MutationCache } from './mutationCache'
 import type { MutationObserver } from './mutationObserver'
 import { notifyManager } from './notifyManager'
@@ -19,7 +24,7 @@ interface MutationConfig<TData, TError, TVariables, TContext> {
 
 export interface MutationState<
   TData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > {
@@ -75,7 +80,7 @@ export type Action<TData, TError, TVariables, TContext> =
 
 export class Mutation<
   TData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends Removable {

packages/query-core/src/mutationCache.ts

@@ -1,5 +1,5 @@
 import type { MutationObserver } from './mutationObserver'
-import type { MutationOptions } from './types'
+import type { MutationOptions, RegisteredError } from './types'
 import type { QueryClient } from './queryClient'
 import { notifyManager } from './notifyManager'
 import type { Action, MutationState } from './mutation'
@@ -127,7 +127,12 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
     return this.#mutations
   }
 
-  find<TData = unknown, TError = Error, TVariables = any, TContext = unknown>(
+  find<
+    TData = unknown,
+    TError = RegisteredError,
+    TVariables = any,
+    TContext = unknown,
+  >(
     filters: MutationFilters,
   ): Mutation<TData, TError, TVariables, TContext> | undefined {
     if (typeof filters.exact === 'undefined') {

packages/query-core/src/mutationObserver.ts

@@ -8,6 +8,7 @@ import type {
   MutationObserverBaseResult,
   MutationObserverResult,
   MutationObserverOptions,
+  RegisteredError,
 } from './types'
 import { shallowEqualObjects } from './utils'
 
@@ -26,7 +27,7 @@ interface NotifyOptions {
 
 export class MutationObserver<
   TData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TVariables = void,
   TContext = unknown,
 > extends Subscribable<

packages/query-core/src/query.ts

@@ -9,6 +9,7 @@ import type {
   CancelOptions,
   SetDataOptions,
   FetchStatus,
+  RegisteredError,
 } from './types'
 import type { QueryCache } from './queryCache'
 import type { QueryObserver } from './queryObserver'
@@ -33,7 +34,7 @@ interface QueryConfig<
   state?: QueryState<TData, TError>
 }
 
-export interface QueryState<TData = unknown, TError = Error> {
+export interface QueryState<TData = unknown, TError = RegisteredError> {
   data: TData | undefined
   dataUpdateCount: number
   dataUpdatedAt: number
@@ -64,7 +65,7 @@ export interface FetchContext<
 
 export interface QueryBehavior<
   TQueryFnData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > {
@@ -137,7 +138,7 @@ export interface SetStateOptions {
 
 export class Query<
   TQueryFnData = unknown,
-  TError = Error,
+  TError = RegisteredError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
 > extends Removable {

packages/query-core/src/queryCache.ts

@@ -2,7 +2,12 @@ import type { QueryFilters } from './utils'
 import { hashQueryKeyByOptions, matchQuery } from './utils'
 import type { Action, QueryState } from './query'
 import { Query } from './query'
-import type { QueryKey, QueryOptions, WithRequired } from './types'
+import type {
+  QueryKey,
+  QueryOptions,
+  RegisteredError,
+  WithRequired,
+} from './types'
 import { notifyManager } from './notifyManager'
 import type { QueryClient } from './queryClient'
 import { Subscribable } from './subscribable'
@@ -134,7 +139,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
 
   get<
     TQueryFnData = unknown,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -149,7 +154,7 @@ export class QueryCache extends Subscribable<QueryCacheListener> {
     return [...this.#queries.values()]
   }
 
-  find<TQueryFnData = unknown, TError = Error, TData = TQueryFnData>(
+  find<TQueryFnData = unknown, TError = RegisteredError, TData = TQueryFnData>(
     filters: WithRequired<QueryFilters, 'queryKey'>,
   ): Query<TQueryFnData, TError, TData> | undefined {
     if (typeof filters.exact === 'undefined') {

packages/query-core/src/queryClient.ts

@@ -25,6 +25,7 @@ import type {
   ResetOptions,
   ResetQueryFilters,
   SetDataOptions,
+  RegisteredError,
 } from './types'
 import type { QueryState } from './query'
 import { QueryCache } from './queryCache'
@@ -177,7 +178,7 @@ export class QueryClient {
     )
   }
 
-  getQueryState<TQueryFnData = unknown, TError = Error>(
+  getQueryState<TQueryFnData = unknown, TError = RegisteredError>(
     queryKey: QueryKey,
   ): QueryState<TQueryFnData, TError> | undefined {
     return this.#queryCache.find<TQueryFnData, TError>({ queryKey })?.state
@@ -276,7 +277,7 @@ export class QueryClient {
 
   fetchQuery<
     TQueryFnData,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -298,7 +299,7 @@ export class QueryClient {
 
   prefetchQuery<
     TQueryFnData = unknown,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -309,7 +310,7 @@ export class QueryClient {
 
   fetchInfiniteQuery<
     TQueryFnData,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -321,7 +322,7 @@ export class QueryClient {
 
   prefetchInfiniteQuery<
     TQueryFnData,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,
   >(
@@ -405,7 +406,7 @@ export class QueryClient {
 
   defaultQueryOptions<
     TQueryFnData = unknown,
-    TError = Error,
+    TError = RegisteredError,
     TData = TQueryFnData,
     TQueryData = TQueryFnData,
     TQueryKey extends QueryKey = QueryKey,