feat(mutation): add onMutate to MutationCache (TanStack#3038)

Author: stefanprobst

docs/src/pages/reference/MutationCache.md

@@ -16,7 +16,7 @@ const mutationCache = new MutationCache({
   },
   onSuccess: data => {
     console.log(data)
-  }
+  },
 })
 ```
 
@@ -34,11 +34,16 @@ Its available methods are:
 - `onSuccess?: (data: unknown, variables: unknown, context: unknown, mutation: Mutation) => void`
   - Optional
   - This function will be called if some mutation is successful.
+- `onMutate?: (variables: unknown, mutation: Mutation) => void`
+  - Optional
+  - This function will be called before some mutation executes.
 
 ## Global callbacks
 
-The `onError` and `onSuccess` callbacks on the MutationCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
+The `onError`, `onSuccess` and `onMutate` callbacks on the MutationCache can be used to handle these events on a global level. They are different to `defaultOptions` provided to the QueryClient because:
+
 - `defaultOptions` can be overridden by each Mutation - the global callbacks will **always** be called.
+- `onMutate` does not allow returning a context value.
 
 ## `mutationCache.getAll`
 

src/core/mutation.ts

@@ -143,6 +143,13 @@ export class Mutation<
     if (!restored) {
       this.dispatch({ type: 'loading', variables: this.options.variables! })
       promise = promise
+        .then(() => {
+          // Notify cache callback
+          this.mutationCache.config.onMutate?.(
+            this.state.variables,
+            this as Mutation<unknown, unknown, unknown, unknown>
+          )
+        })
         .then(() => this.options.onMutate?.(this.state.variables!))
         .then(context => {
           if (context !== this.state.context) {

src/core/mutationCache.ts

@@ -20,6 +20,10 @@ interface MutationCacheConfig {
     context: unknown,
     mutation: Mutation<unknown, unknown, unknown, unknown>
   ) => void
+  onMutate?: (
+    variables: unknown,
+    mutation: Mutation<unknown, unknown, unknown, unknown>
+  ) => void
 }
 
 type MutationCacheListener = (mutation?: Mutation) => void

src/core/tests/mutationCache.test.tsx

@@ -53,6 +53,29 @@ describe('mutationCache', () => {
       )
     })
   })
+  describe('MutationCacheConfig.onMutate', () => {
+    test('should be called before a mutation executes', async () => {
+      const consoleMock = mockConsoleError()
+      const key = queryKey()
+      const onMutate = jest.fn()
+      const testCache = new MutationCache({ onMutate })
+      const testClient = new QueryClient({ mutationCache: testCache })
+
+      try {
+        await testClient.executeMutation({
+          mutationKey: key,
+          variables: 'vars',
+          mutationFn: () => Promise.resolve({ data: 5 }),
+          onMutate: () => 'context',
+        })
+      } catch {
+        consoleMock.mockRestore()
+      }
+
+      const mutation = testCache.getAll()[0]
+      expect(onMutate).toHaveBeenCalledWith('vars', mutation)
+    })
+  })
 
   describe('find', () => {
     test('should filter correctly', async () => {