refactor: use union of function signatures for callback return types

Replace callback return type unions
with unions of complete function signatures to improve type safety and clarity.

This change addresses the issues raised in TanStack#9241 and TanStack#9245 by:
- Preventing mixed sync/async behavior within single callbacks
- Maintaining support for Promise.all() patterns

Author: braden-w

docs/framework/react/plugins/persistQueryClient.md

@@ -214,12 +214,12 @@ ReactDOM.createRoot(rootElement).render(
 
 - `persistOptions: PersistQueryClientOptions`
   - all [options](#options) you can pass to [persistQueryClient](#persistqueryclient) minus the QueryClient itself
-- `onSuccess?: () => void | Promise<void> | Promise<Array<void>>`
+- `onSuccess?: (() => void) | (() => Promise<void>)`
   - optional
   - will be called when the initial restore is finished
   - can be used to [resumePausedMutations](../../../../reference/QueryClient.md#queryclientresumepausedmutations)
   - if a Promise is returned, it will be awaited; restoring is seen as ongoing until then
-- `onError?: () => void | Promise<void> | Promise<Array<void>>`
+- `onError?: (() => void) | (() => Promise<void>)`
   - optional
   - will be called when an error is thrown during restoration
   - if a Promise is returned, it will be awaited

docs/framework/react/reference/useMutation.md

@@ -68,13 +68,13 @@ mutate(variables, {
   - This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
   - Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
   - The value returned from this function will be passed to both the `onError` and `onSettled` functions in the event of a mutation failure and can be useful for rolling back optimistic updates.
-- `onSuccess: (data: TData, variables: TVariables, context: TContext) => void | Promise<void> | Promise<Array<void>>`
+- `onSuccess: ((data: TData, variables: TVariables, context: TContext) => void) | ((data: TData, variables: TVariables, context: TContext) => Promise<void>)`
   - Optional
   - This function will fire when the mutation is successful and will be passed the mutation's result.
-- `onError: (err: TError, variables: TVariables, context?: TContext) => void | Promise<void> | Promise<Array<void>>`
+- `onError: ((err: TError, variables: TVariables, context?: TContext) => void) | ((err: TError, variables: TVariables, context?: TContext) => Promise<void>)`
   - Optional
   - This function will fire if the mutation encounters an error and will be passed the error.
-- `onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => void | Promise<void> | Promise<Array<void>>`
+- `onSettled: ((data: TData, error: TError, variables: TVariables, context?: TContext) => void) | ((data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<void>)`
   - Optional
   - This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
 - `retry: boolean | number | (failureCount: number, error: TError) => boolean`

docs/reference/MutationCache.md

@@ -28,19 +28,19 @@ Its available methods are:
 
 **Options**
 
-- `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => void | Promise<void> | Promise<Array<void>>`
+- `onError?: ((error: unknown, variables: unknown, context: unknown, mutation: Mutation) => void) | ((error: unknown, variables: unknown, context: unknown, mutation: Mutation) => Promise<void>)`
   - Optional
   - This function will be called if some mutation encounters an error.
   - If you return a Promise from it, it will be awaited
-- `onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => void | Promise<void> | Promise<Array<void>>`
+- `onSuccess?: ((data: unknown, variables: unknown, context: unknown, mutation: Mutation) => void) | ((data: unknown, variables: unknown, context: unknown, mutation: Mutation) => Promise<void>)`
   - Optional
   - This function will be called if some mutation is successful.
   - If you return a Promise from it, it will be awaited
-- `onSettled?: (data: unknown | undefined, error: unknown | null, variables: unknown, context: unknown, mutation: Mutation) => void | Promise<void> | Promise<Array<void>>`
+- `onSettled?: ((data: unknown | undefined, error: unknown | null, variables: unknown, context: unknown, mutation: Mutation) => void) | ((data: unknown | undefined, error: unknown | null, variables: unknown, context: unknown, mutation: Mutation) => Promise<void>)`
   - Optional
   - This function will be called if some mutation is settled (either successful or errored).
   - If you return a Promise from it, it will be awaited
-- `onMutate?: (variables: unknown, mutation: Mutation) => void | Promise<void> | Promise<Array<void>>`
+- `onMutate?: ((variables: unknown, mutation: Mutation) => void) | ((variables: unknown, mutation: Mutation) => Promise<void>)`
   - Optional
   - This function will be called before some mutation executes.
   - If you return a Promise from it, it will be awaited

packages/angular-query-persist-client/src/with-persist-query-client.ts

@@ -20,8 +20,8 @@ import type { PersistQueryClientFeature } from '@tanstack/angular-query-experime
 
 type PersistQueryClientOptions = {
   persistOptions: Omit<PersistQueryClientOptionsCore, 'queryClient'>
-  onSuccess?: () => void | Promise<void> | Promise<Array<void>>
-  onError?: () => void | Promise<void> | Promise<Array<void>>
+  onSuccess?: (() => void) | (() => Promise<void>)
+  onError?: (() => void) | (() => Promise<void>)
 }
 
 /**

packages/query-core/src/mutationCache.ts

@@ -11,29 +11,56 @@ import type { MutationFilters } from './utils'
 // TYPES
 
 interface MutationCacheConfig {
-  onError?: (
-    error: DefaultError,
-    variables: unknown,
-    context: unknown,
-    mutation: Mutation<unknown, unknown, unknown>,
-  ) => void | Promise<void> | Promise<Array<void>>
-  onSuccess?: (
-    data: unknown,
-    variables: unknown,
-    context: unknown,
-    mutation: Mutation<unknown, unknown, unknown>,
-  ) => void | Promise<void> | Promise<Array<void>>
-  onMutate?: (
-    variables: unknown,
-    mutation: Mutation<unknown, unknown, unknown>,
-  ) => void | Promise<void> | Promise<Array<void>>
-  onSettled?: (
-    data: unknown | undefined,
-    error: DefaultError | null,
-    variables: unknown,
-    context: unknown,
-    mutation: Mutation<unknown, unknown, unknown>,
-  ) => void | Promise<void> | Promise<Array<void>>
+  onError?:
+    | ((
+        error: DefaultError,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => void)
+    | ((
+        error: DefaultError,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => Promise<void>)
+  onSuccess?:
+    | ((
+        data: unknown,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => void)
+    | ((
+        data: unknown,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => Promise<void>)
+  onMutate?:
+    | ((
+        variables: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => void)
+    | ((
+        variables: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => Promise<void>)
+  onSettled?:
+    | ((
+        data: unknown | undefined,
+        error: DefaultError | null,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => void)
+    | ((
+        data: unknown | undefined,
+        error: DefaultError | null,
+        variables: unknown,
+        context: unknown,
+        mutation: Mutation<unknown, unknown, unknown>,
+      ) => Promise<void>)
 }
 
 interface NotifyEventMutationAdded extends NotifyEvent {

packages/query-core/src/types.ts

@@ -1102,22 +1102,33 @@ export interface MutationOptions<
   onMutate?: (
     variables: TVariables,
   ) => Promise<TContext | undefined> | TContext | undefined
-  onSuccess?: (
-    data: TData,
-    variables: TVariables,
-    context: TContext,
-  ) => void | Promise<void> | Promise<Array<void>>
-  onError?: (
-    error: TError,
-    variables: TVariables,
-    context: TContext | undefined,
-  ) => void | Promise<void> | Promise<Array<void>>
-  onSettled?: (
-    data: TData | undefined,
-    error: TError | null,
-    variables: TVariables,
-    context: TContext | undefined,
-  ) => void | Promise<void> | Promise<Array<void>>
+  onSuccess?:
+    | ((data: TData, variables: TVariables, context: TContext) => void)
+    | ((data: TData, variables: TVariables, context: TContext) => Promise<void>)
+  onError?:
+    | ((
+        error: TError,
+        variables: TVariables,
+        context: TContext | undefined,
+      ) => void)
+    | ((
+        error: TError,
+        variables: TVariables,
+        context: TContext | undefined,
+      ) => Promise<void>)
+  onSettled?:
+    | ((
+        data: TData | undefined,
+        error: TError | null,
+        variables: TVariables,
+        context: TContext | undefined,
+      ) => void)
+    | ((
+        data: TData | undefined,
+        error: TError | null,
+        variables: TVariables,
+        context: TContext | undefined,
+      ) => Promise<void>)
   retry?: RetryValue<TError>
   retryDelay?: RetryDelayValue<TError>
   networkMode?: NetworkMode

packages/react-query-persist-client/src/PersistQueryClientProvider.tsx

@@ -11,8 +11,8 @@ import type { OmitKeyof, QueryClientProviderProps } from '@tanstack/react-query'
 
 export type PersistQueryClientProviderProps = QueryClientProviderProps & {
   persistOptions: OmitKeyof<PersistQueryClientOptions, 'queryClient'>
-  onSuccess?: () => void | Promise<void> | Promise<Array<void>>
-  onError?: () => void | Promise<void> | Promise<Array<void>>
+  onSuccess?: (() => void) | (() => Promise<void>)
+  onError?: (() => void) | (() => Promise<void>)
 }
 
 export const PersistQueryClientProvider = ({