refactor: standardize use of MaybePromise<T> in place of Promise<T> | T

This commit builds on the changes introduced in [refactor/narrow-callback-types](#9202) and replaces all instances of `Promise<T> | T` with the new `MaybePromise<T>` helper type. The `MaybePromise` type, originally defined in `@tanstack/query-persist-client-core/src/createPersister.ts`, is now moved to `query-core` for broader, consistent use.

- Moves the `MaybePromise` type definition to `query-core`, making it the canonical utility for representing values that may be returned synchronously or as a promise.
- Updates all relevant callback signatures (such as `onSuccess`, `onError`, `onMutate`, `onSettled`, and other callbacks) to use `MaybePromise<T>` instead of `Promise<T> | T`.
- Updates documentation to reference `MaybePromise<T>` for clarity and consistency.

This builds on the direction set by [refactor/narrow-callback-types](#9202), further improving type readability and maintainability by using a single, expressive type for all maybe-async callback returns.

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<void> | void`
+- `onSuccess?: () => MaybePromise<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<void> | void`
+- `onError?: () => MaybePromise<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<void> | void`
+- `onSuccess: (data: TData, variables: TVariables, context: TContext) => MaybePromise<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<void> | void`
+- `onError: (err: TError, variables: TVariables, context?: TContext) => MaybePromise<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<void> | void`
+- `onSettled: (data: TData, error: TError, variables: TVariables, context?: TContext) => MaybePromise<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<void> | void`
+- `onError?: (error: unknown, variables: unknown, context: unknown, mutation: Mutation) => MaybePromise<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<void> | void`
+- `onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => MaybePromise<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<void> | void`
+- `onSettled?: (data: unknown | undefined, error: unknown | null, variables: unknown, context: unknown, mutation: Mutation) => MaybePromise<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<void> | void`
+- `onMutate?: (variables: unknown, mutation: Mutation) => MaybePromise<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

@@ -16,12 +16,12 @@ import {
   persistQueryClientSubscribe,
 } from '@tanstack/query-persist-client-core'
 import type { PersistQueryClientOptions as PersistQueryClientOptionsCore } from '@tanstack/query-persist-client-core'
-import type { PersistQueryClientFeature } from '@tanstack/angular-query-experimental'
+import type { MaybePromise, PersistQueryClientFeature } from '@tanstack/angular-query-experimental'
 
 type PersistQueryClientOptions = {
   persistOptions: Omit<PersistQueryClientOptionsCore, 'queryClient'>
-  onSuccess?: () => Promise<void> | void
-  onError?: () => Promise<void> | void
+  onSuccess?: () => MaybePromise<void>
+  onError?: () => MaybePromise<void>
 }
 
 /**

packages/query-async-storage-persister/src/index.ts

@@ -2,7 +2,6 @@ import { asyncThrottle } from './asyncThrottle'
 import { noop } from './utils'
 import type {
   AsyncStorage,
-  MaybePromise,
   PersistedClient,
   Persister,
   Promisable,
@@ -29,12 +28,12 @@ interface CreateAsyncStoragePersisterOptions {
    * How to serialize the data to storage.
    * @default `JSON.stringify`
    */
-  serialize?: (client: PersistedClient) => MaybePromise<string>
+  serialize?: (client: PersistedClient) => Promisable<string>
   /**
    * How to deserialize the data from storage.
    * @default `JSON.parse`
    */
-  deserialize?: (cachedString: string) => MaybePromise<PersistedClient>
+  deserialize?: (cachedString: string) => Promisable<PersistedClient>
 
   retry?: AsyncPersistRetryer
 }

packages/query-core/src/mutationCache.ts

@@ -3,7 +3,7 @@ import { Mutation } from './mutation'
 import { matchMutation, noop } from './utils'
 import { Subscribable } from './subscribable'
 import type { MutationObserver } from './mutationObserver'
-import type { DefaultError, MutationOptions, NotifyEvent } from './types'
+import type { DefaultError, MaybePromise, MutationOptions, NotifyEvent } from './types'
 import type { QueryClient } from './queryClient'
 import type { Action, MutationState } from './mutation'
 import type { MutationFilters } from './utils'
@@ -16,24 +16,24 @@ interface MutationCacheConfig {
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   onSuccess?: (
     data: unknown,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   onMutate?: (
     variables: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
 }
 
 interface NotifyEventMutationAdded extends NotifyEvent {

packages/query-core/src/query.ts

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

packages/query-core/src/types.ts

@@ -9,6 +9,7 @@ import type { QueryFilters, QueryTypeFilter, SkipToken } from './utils'
 import type { QueryCache } from './queryCache'
 import type { MutationCache } from './mutationCache'
 
+export type MaybePromise<T> = T | Promise<T>
 export type NonUndefinedGuard<T> = T extends undefined ? never : T
 
 export type DistributiveOmit<
@@ -1105,18 +1106,18 @@ export interface MutationOptions<
     data: TData,
     variables: TVariables,
     context: TContext,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   onError?: (
     error: TError,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   onSettled?: (
     data: TData | undefined,
     error: TError | null,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<void> | void
+  ) => MaybePromise<void>
   retry?: RetryValue<TError>
   retryDelay?: RetryDelayValue<TError>
   networkMode?: NetworkMode

packages/query-persist-client-core/src/createPersister.ts

@@ -1,5 +1,6 @@
 import { matchQuery } from '@tanstack/query-core'
 import type {
+  MaybePromise,
   Query,
   QueryClient,
   QueryFilters,
@@ -15,8 +16,6 @@ export interface PersistedQuery {
   state: QueryState
 }
 
-export type MaybePromise<T> = T | Promise<T>
-
 export interface AsyncStorage<TStorageValue = string> {
   getItem: (key: string) => MaybePromise<TStorageValue | undefined | null>
   setItem: (key: string, value: TStorageValue) => MaybePromise<unknown>

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

@@ -7,12 +7,12 @@ import {
 } from '@tanstack/query-persist-client-core'
 import { IsRestoringProvider, QueryClientProvider } from '@tanstack/react-query'
 import type { PersistQueryClientOptions } from '@tanstack/query-persist-client-core'
-import type { OmitKeyof, QueryClientProviderProps } from '@tanstack/react-query'
+import type { MaybePromise, OmitKeyof, QueryClientProviderProps } from '@tanstack/react-query'
 
 export type PersistQueryClientProviderProps = QueryClientProviderProps & {
   persistOptions: OmitKeyof<PersistQueryClientOptions, 'queryClient'>
-  onSuccess?: () => Promise<void> | void
-  onError?: () => Promise<void> | void
+  onSuccess?: () => MaybePromise<void>
+  onError?: () => MaybePromise<void>
 }
 
 export const PersistQueryClientProvider = ({