fix: re-add useMutation callback composition

Author: boschni

docs/src/pages/guides/migrating-to-react-query-3.md

@@ -190,9 +190,6 @@ try {
 }
 ```
 
-Callbacks passed to the `mutate` or `mutateAsync` functions will now override the callbacks defined on `useMutation`.
-The `mutateAsync` function can be used to compose side effects.
-
 ### Query object syntax
 
 The object syntax has been collapsed:

docs/src/pages/guides/mutations.md

@@ -149,30 +149,30 @@ useMutation(addTodo, {
 })
 ```
 
-You might find that you want to **trigger different callbacks** then the ones defined on `useMutation` when calling `mutate`. To do that, you can provide any of the same callback options to the `mutate` function after your mutation variable. Supported overrides include: `onSuccess`, `onError` and `onSettled`.
+You might find that you want to **trigger additional callbacks** then the ones defined on `useMutation` when calling `mutate`. This can be used to trigger component specific side effects. To do that, you can provide any of the same callback options to the `mutate` function after your mutation variable. Supported overrides include: `onSuccess`, `onError` and `onSettled`.
 
 ```js
 useMutation(addTodo, {
   onSuccess: (data, variables, context) => {
-    // I will not fire
+    // I will fire first
   },
   onError: (error, variables, context) => {
-    // I will not fire
+    // I will fire first
   },
   onSettled: (data, error, variables, context) => {
-    // I will not fire
+    // I will fire first
   },
 })
 
 mutate(todo, {
   onSuccess: (data, variables, context) => {
-    // I will fire instead!
+    // I will fire second!
   },
   onError: (error, variables, context) => {
-    // I will fire instead!
+    // I will fire second!
   },
   onSettled: (data, error, variables, context) => {
-    // I will fire instead!
+    // I will fire second!
   },
 })
 ```

src/core/mutation.ts

@@ -64,7 +64,7 @@ interface SetStateAction<TData, TError, TVariables, TContext> {
   state: MutationState<TData, TError, TVariables, TContext>
 }
 
-type Action<TData, TError, TVariables, TContext> =
+export type Action<TData, TError, TVariables, TContext> =
   | ContinueAction
   | ErrorAction<TError>
   | FailedAction
@@ -230,7 +230,7 @@ export class Mutation<
 
     notifyManager.batch(() => {
       this.observers.forEach(observer => {
-        observer.onMutationUpdate()
+        observer.onMutationUpdate(action)
       })
       this.mutationCache.notify(this)
     })

src/core/mutationObserver.ts

@@ -1,4 +1,4 @@
-import { getDefaultState, Mutation } from './mutation'
+import { Action, getDefaultState, Mutation } from './mutation'
 import { notifyManager } from './notifyManager'
 import type { QueryClient } from './queryClient'
 import { Subscribable } from './subscribable'
@@ -15,6 +15,12 @@ type MutationObserverListener<TData, TError, TVariables, TContext> = (
   result: MutationObserverResult<TData, TError, TVariables, TContext>
 ) => void
 
+interface NotifyOptions {
+  listeners?: boolean
+  onError?: boolean
+  onSuccess?: boolean
+}
+
 // CLASS
 
 export class MutationObserver<
@@ -35,6 +41,7 @@ export class MutationObserver<
     TContext
   >
   private currentMutation?: Mutation<TData, TError, TVariables, TContext>
+  private mutateOptions?: MutateOptions<TData, TError, TVariables, TContext>
 
   constructor(
     client: QueryClient,
@@ -65,9 +72,21 @@ export class MutationObserver<
     }
   }
 
-  onMutationUpdate(): void {
+  onMutationUpdate(action: Action<TData, TError, TVariables, TContext>): void {
     this.updateResult()
-    this.notify()
+
+    // Determine which callbacks to trigger
+    const notifyOptions: NotifyOptions = {
+      listeners: true,
+    }
+
+    if (action.type === 'success') {
+      notifyOptions.onSuccess = true
+    } else if (action.type === 'error') {
+      notifyOptions.onError = true
+    }
+
+    this.notify(notifyOptions)
   }
 
   getCurrentResult(): MutationObserverResult<
@@ -82,20 +101,21 @@ export class MutationObserver<
   reset(): void {
     this.currentMutation = undefined
     this.updateResult()
-    this.notify()
+    this.notify({ listeners: true })
   }
 
   mutate(
     variables?: TVariables,
     options?: MutateOptions<TData, TError, TVariables, TContext>
   ): Promise<TData> {
+    this.mutateOptions = options
+
     if (this.currentMutation) {
       this.currentMutation.removeObserver(this)
     }
 
     this.currentMutation = this.client.getMutationCache().build(this.client, {
       ...this.options,
-      ...options,
       variables: variables ?? this.options.variables,
     })
 
@@ -117,11 +137,43 @@ export class MutationObserver<
     }
   }
 
-  private notify() {
+  private notify(options: NotifyOptions) {
     notifyManager.batch(() => {
-      this.listeners.forEach(listener => {
-        listener(this.currentResult)
-      })
+      // First trigger the mutate callbacks
+      if (this.mutateOptions) {
+        if (options.onSuccess) {
+          this.mutateOptions.onSuccess?.(
+            this.currentResult.data!,
+            this.currentResult.variables!,
+            this.currentResult.context
+          )
+          this.mutateOptions.onSettled?.(
+            this.currentResult.data!,
+            null,
+            this.currentResult.variables!,
+            this.currentResult.context
+          )
+        } else if (options.onError) {
+          this.mutateOptions.onError?.(
+            this.currentResult.error!,
+            this.currentResult.variables!,
+            this.currentResult.context
+          )
+          this.mutateOptions.onSettled?.(
+            undefined,
+            this.currentResult.error,
+            this.currentResult.variables!,
+            this.currentResult.context
+          )
+        }
+      }
+
+      // Then trigger the listeners
+      if (options.listeners) {
+        this.listeners.forEach(listener => {
+          listener(this.currentResult)
+        })
+      }
     })
   }
 }

src/core/types.ts

@@ -69,30 +69,23 @@ export interface QueryOptions<
   getNextPageParam?: GetNextPageParamFunction<TQueryFnData>
 }
 
-export interface FetchQueryOptions<
-  TData = unknown,
-  TError = unknown,
-  TQueryFnData = TData
-> extends QueryOptions<TData, TError, TQueryFnData> {
-  /**
-   * The time in milliseconds after data is considered stale.
-   * If set to `Infinity`, the data will never be considered stale.
-   */
-  staleTime?: number
-}
-
 export interface QueryObserverOptions<
   TData = unknown,
   TError = unknown,
   TQueryFnData = TData,
   TQueryData = TQueryFnData
-> extends FetchQueryOptions<TData, TError, TQueryFnData> {
+> extends QueryOptions<TData, TError, TQueryFnData> {
   /**
    * Set this to `false` to disable automatic refetching when the query mounts or changes query keys.
    * To refetch the query, use the `refetch` method returned from the `useQuery` instance.
    * Defaults to `true`.
    */
   enabled?: boolean
+  /**
+   * The time in milliseconds after data is considered stale.
+   * If set to `Infinity`, the data will never be considered stale.
+   */
+  staleTime?: number
   /**
    * If set to a number, the query will continuously refetch at this frequency in milliseconds.
    * Defaults to `false`.
@@ -186,6 +179,18 @@ export interface InfiniteQueryObserverOptions<
     InfiniteData<TQueryData>
   > {}
 
+export interface FetchQueryOptions<
+  TData = unknown,
+  TError = unknown,
+  TQueryFnData = TData
+> extends QueryOptions<TData, TError, TQueryFnData> {
+  /**
+   * The time in milliseconds after data is considered stale.
+   * If the data is fresh it will be returned from the cache.
+   */
+  staleTime?: number
+}
+
 export interface ResultOptions {
   throwOnError?: boolean
 }

src/react/tests/useMutation.test.tsx

@@ -247,6 +247,8 @@ describe('useMutation', () => {
     await sleep(100)
 
     expect(callbacks).toEqual([
+      'useMutation.onSuccess',
+      'useMutation.onSettled',
       'mutateAsync.onSuccess',
       'mutateAsync.onSettled',
       'mutateAsync.result:todo',
@@ -296,6 +298,8 @@ describe('useMutation', () => {
     await sleep(100)
 
     expect(callbacks).toEqual([
+      'useMutation.onError',
+      'useMutation.onSettled',
       'mutateAsync.onError',
       'mutateAsync.onSettled',
       'mutateAsync.error:oops',