refactor(types): narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void (#9202)

* refactor: narrow onSuccess/onError/onMutate/onSettled callback types to Promise<void> | void

Previously, the `onSuccess`, `onError`, `onMutate`, and `onSettled` callbacks were typed as `() => Promise<unknown> | unknown`. While `unknown` is technically valid, it implies that the return value might be used, assigned, or further processed. However, throughout the codebase, these callbacks are invoked solely for their side effects, and their return values are always ignored. Narrowing the type to `Promise<void> | void` makes this intent explicit, clarifies that any return value will be discarded, and prevents misleading type signatures that suggest otherwise.

This commit narrows their types to `() => Promise<void> | void`, which more accurately reflects their intended use.

* docs: update callback return types to Promise<void> | void in mutation-related documentation

This commit refines the documentation for mutation-related callbacks (`onSuccess`, `onError`, `onSettled`, and `onMutate`), changing their return types from `Promise<unknown> | unknown` to `Promise<void> | void`.

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?: () => Promise<unknown> | unknown`
+- `onSuccess?: () => Promise<void> | 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?: () => Promise<unknown> | unknown`
+- `onError?: () => Promise<void> | 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,15 +68,15 @@ 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) => Promise<unknown> | unknown`
+- `onSuccess: (data: TData, variables: TVariables, context: TContext) => Promise<void> | void`
   - Optional
   - This function will fire when the mutation is successful and will be passed the mutation's result.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onError: (err: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown`
+- `onError: (err: TError, variables: TVariables, context?: TContext) => Promise<void> | void`
   - Optional
   - This function will fire if the mutation encounters an error and will be passed the error.
   - If a promise is returned, it will be awaited and resolved before proceeding
-- `onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<unknown> | unknown`
+- `onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => Promise<void> | 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
   - If a promise is returned, it will be awaited and resolved before proceeding

docs/reference/MutationCache.md

@@ -28,19 +28,19 @@ Its available methods are:
 
 **Options**
 
-- `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => Promise<unknown> | unknown`
+- `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => Promise<void> | 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) => Promise<unknown> | unknown`
+- `onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => Promise<void> | 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) => Promise<unknown> | unknown`
+- `onSettled?: (data: unknown | undefined, error: unknown | null, variables: unknown, context: unknown, mutation: Mutation) => Promise<void> | 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) => Promise<unknown> | unknown`
+- `onMutate?: (variables: unknown, mutation: Mutation) => Promise<void> | 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?: () => Promise<unknown> | unknown
-  onError?: () => Promise<unknown> | unknown
+  onSuccess?: () => Promise<void> | void
+  onError?: () => Promise<void> | void
 }
 
 /**

packages/query-core/src/mutationCache.ts

@@ -16,24 +16,24 @@ interface MutationCacheConfig {
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
   onSuccess?: (
     data: unknown,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
   onMutate?: (
     variables: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
 }
 
 interface NotifyEventMutationAdded extends NotifyEvent {

packages/query-core/src/query.ts

@@ -67,7 +67,7 @@ export interface FetchContext<
   TData,
   TQueryKey extends QueryKey = QueryKey,
 > {
-  fetchFn: () => unknown | Promise<unknown>
+  fetchFn: () => Promise<unknown> | unknown
   fetchOptions?: FetchOptions
   signal: AbortSignal
   options: QueryOptions<TQueryFnData, TError, TData, any>

packages/query-core/src/types.ts

@@ -1109,18 +1109,18 @@ export interface MutationOptions<
     data: TData,
     variables: TVariables,
     context: TContext,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
   onError?: (
     error: TError,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | void
   onSettled?: (
     data: TData | undefined,
     error: TError | null,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<unknown> | unknown
+  ) => Promise<void> | 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?: () => Promise<unknown> | unknown
-  onError?: () => Promise<unknown> | unknown
+  onSuccess?: () => Promise<void> | void
+  onError?: () => Promise<void> | void
 }
 
 export const PersistQueryClientProvider = ({