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

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?: () => 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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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<unknown> | unknown`
+- `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,15 @@ 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<unknown> | unknown
-  onError?: () => Promise<unknown> | unknown
+  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,12 @@ 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 +21,24 @@ interface MutationCacheConfig {
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
   onSuccess?: (
     data: unknown,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
   onMutate?: (
     variables: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
   onSettled?: (
     data: unknown | undefined,
     error: DefaultError | null,
     variables: unknown,
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown>,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
 }
 
 interface NotifyEventMutationAdded extends NotifyEvent {

packages/query-core/src/query.ts

@@ -16,6 +16,7 @@ import type {
   DefaultError,
   FetchStatus,
   InitialDataFunction,
+  MaybePromise,
   OmitKeyof,
   QueryFunction,
   QueryFunctionContext,
@@ -65,7 +66,7 @@ export interface FetchContext<
   TData,
   TQueryKey extends QueryKey = QueryKey,
 > {
-  fetchFn: () => unknown | Promise<unknown>
+  fetchFn: () => MaybePromise<unknown>
   fetchOptions?: FetchOptions
   signal: AbortSignal
   options: QueryOptions<TQueryFnData, TError, TData, any>

packages/query-core/src/retryer.ts

@@ -2,12 +2,17 @@ import { focusManager } from './focusManager'
 import { onlineManager } from './onlineManager'
 import { pendingThenable } from './thenable'
 import { isServer, sleep } from './utils'
-import type { CancelOptions, DefaultError, NetworkMode } from './types'
+import type {
+  CancelOptions,
+  DefaultError,
+  MaybePromise,
+  NetworkMode,
+} from './types'
 
 // TYPES
 
 interface RetryerConfig<TData = unknown, TError = DefaultError> {
-  fn: () => TData | Promise<TData>
+  fn: () => MaybePromise<TData>
   initialPromise?: Promise<TData>
   abort?: () => void
   onError?: (error: TError) => void
@@ -142,7 +147,7 @@ export function createRetryer<TData = unknown, TError = DefaultError>(
       return
     }
 
-    let promiseOrValue: any
+    let promiseOrValue: MaybePromise<TData>
 
     // we can re-use config.initialPromise on the first call of run()
     const initialPromise =

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<
@@ -97,7 +98,7 @@ export type QueryFunction<
   T = unknown,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = never,
-> = (context: QueryFunctionContext<TQueryKey, TPageParam>) => T | Promise<T>
+> = (context: QueryFunctionContext<TQueryKey, TPageParam>) => MaybePromise<T>
 
 export type StaleTime<
   TQueryFnData = unknown,
@@ -124,12 +125,12 @@ export type QueryPersister<
       queryFn: QueryFunction<T, TQueryKey, never>,
       context: QueryFunctionContext<TQueryKey>,
       query: Query,
-    ) => T | Promise<T>
+    ) => MaybePromise<T>
   : (
       queryFn: QueryFunction<T, TQueryKey, TPageParam>,
       context: QueryFunctionContext<TQueryKey>,
       query: Query,
-    ) => T | Promise<T>
+    ) => MaybePromise<T>
 
 export type QueryFunctionContext<
   TQueryKey extends QueryKey = QueryKey,
@@ -1105,18 +1106,18 @@ export interface MutationOptions<
     data: TData,
     variables: TVariables,
     context: TContext,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
   onError?: (
     error: TError,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<unknown> | unknown
+  ) => MaybePromise<void>
   onSettled?: (
     data: TData | undefined,
     error: TError | null,
     variables: TVariables,
     context: TContext | undefined,
-  ) => Promise<unknown> | unknown
+  ) => 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>
@@ -180,7 +179,7 @@ export function experimental_createQueryPersister<TStorageValue = string>({
   }
 
   async function persisterFn<T, TQueryKey extends QueryKey>(
-    queryFn: (context: QueryFunctionContext<TQueryKey>) => T | Promise<T>,
+    queryFn: (context: QueryFunctionContext<TQueryKey>) => MaybePromise<T>,
     ctx: QueryFunctionContext<TQueryKey>,
     query: Query,
   ) {

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

@@ -7,12 +7,16 @@ 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<unknown> | unknown
-  onError?: () => Promise<unknown> | unknown
+  onSuccess?: () => MaybePromise<void>
+  onError?: () => MaybePromise<void>
 }
 
 export const PersistQueryClientProvider = ({

packages/svelte-query-persist-client/src/PersistQueryClientProvider.svelte

@@ -7,11 +7,15 @@
   } from '@tanstack/svelte-query'
   import { writable } from 'svelte/store'
   import type { PersistQueryClientOptions } from '@tanstack/query-persist-client-core'
-  import type { OmitKeyof, QueryClient } from '@tanstack/svelte-query'
+  import type {
+    MaybePromise,
+    OmitKeyof,
+    QueryClient,
+  } from '@tanstack/svelte-query'
 
   export let client: QueryClient
-  export let onSuccess: () => Promise<unknown> | unknown = () => undefined
-  export let onError: () => Promise<unknown> | unknown = () => undefined
+  export let onSuccess: () => MaybePromise<unknown> = () => undefined
+  export let onError: () => MaybePromise<unknown> = () => undefined
   export let persistOptions: OmitKeyof<PersistQueryClientOptions, 'queryClient'>
 
   const isRestoring = writable(true)