test: add callback return type tests for mutation callbacks (#9252)

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

This reverts commit 982f6ca.

* test: add callback return type tests for mutation callbacks

Adds test coverage for mutation callback return types, inspired by the discussions and [TkDodo's comment](#9245 (comment)
) in #9245 and the original Promise.all() edge case identified in #9202.

The original PR #9202 narrowed callback return types from `Promise<unknown> | unknown`
to `Promise<void> | void`, but this broke common patterns like:

```ts
onSuccess: (data) => Promise.all([
  invalidateQueries(),
  trackAnalytics(),
])
```

As noted in [the original discussion](#9202 (comment)),
this `Promise.all()` pattern was a legitimate use case that many users relied on.

These tests ensure we support all the callback patterns that users expect:

✅ **Sync patterns**: Implicit void, explicit void, non-void returns
✅ **Async patterns**: Async functions, Promise.resolve(), Promise<T> returns
✅ **Promise.all() patterns**: The original breaking case from #9202
✅ **Promise.allSettled() patterns**: Additional parallel operation support
✅ **Mixed patterns**: Different callback types in same mutation
✅ **Error handling**: All patterns work in error scenarios
✅ **Return value isolation**: Callback returns don't affect mutation result

* refactor(tests): remove unnecessary parameters in mutation tests

* test(mutations): fix mutation test ordering with error handling and cleanup verification

---------

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: braden-w

packages/query-core/src/__tests__/mutations.test.tsx

@@ -1,7 +1,7 @@
-import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { queryKey, sleep } from '@tanstack/query-test-utils'
-import { MutationObserver } from '../mutationObserver'
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 import { QueryClient } from '..'
+import { MutationObserver } from '../mutationObserver'
 import { executeMutation } from './utils'
 import type { MutationState } from '../mutation'
 
@@ -613,4 +613,221 @@ describe('mutations', () => {
       'finish-B2',
     ])
   })
+
+  describe('callback return types', () => {
+    test('should handle all sync callback patterns', async () => {
+      const key = queryKey()
+      const results: Array<string> = []
+
+      await executeMutation(
+        queryClient,
+        {
+          mutationKey: key,
+          mutationFn: () => Promise.resolve('success'),
+          onMutate: () => {
+            results.push('onMutate-sync')
+            return { backup: 'data' } // onMutate can return context
+          },
+          onSuccess: () => {
+            results.push('onSuccess-implicit-void')
+            // Implicit void return
+          },
+          onError: () => {
+            results.push('onError-explicit-void')
+            return // Explicit void return
+          },
+          onSettled: () => {
+            results.push('onSettled-return-value')
+            return 'ignored-value' // Non-void return (should be ignored)
+          },
+        },
+        'vars',
+      )
+
+      expect(results).toEqual([
+        'onMutate-sync',
+        'onSuccess-implicit-void',
+        'onSettled-return-value',
+      ])
+    })
+
+    test('should handle all async callback patterns', async () => {
+      const key = queryKey()
+      const results: Array<string> = []
+
+      executeMutation(
+        queryClient,
+        {
+          mutationKey: key,
+          mutationFn: () => Promise.resolve('success'),
+          onMutate: async () => {
+            results.push('onMutate-async')
+            await sleep(1)
+            return { backup: 'async-data' }
+          },
+          onSuccess: async () => {
+            results.push('onSuccess-async-start')
+            await sleep(2)
+            results.push('onSuccess-async-end')
+            // Implicit void return from async
+          },
+          onSettled: () => {
+            results.push('onSettled-promise')
+            return Promise.resolve('also-ignored') // Promise<string> (should be ignored)
+          },
+        },
+        'vars',
+      )
+
+      await vi.runAllTimersAsync()
+
+      expect(results).toEqual([
+        'onMutate-async',
+        'onSuccess-async-start',
+        'onSuccess-async-end',
+        'onSettled-promise',
+      ])
+    })
+
+    test('should handle Promise.all() and Promise.allSettled() patterns', async () => {
+      const key = queryKey()
+      const results: Array<string> = []
+
+      executeMutation(
+        queryClient,
+        {
+          mutationKey: key,
+          mutationFn: () => Promise.resolve('success'),
+          onSuccess: () => {
+            results.push('onSuccess-start')
+            return Promise.all([
+              sleep(2).then(() => results.push('invalidate-queries')),
+              sleep(1).then(() => results.push('track-analytics')),
+            ])
+          },
+          onSettled: () => {
+            results.push('onSettled-start')
+            return Promise.allSettled([
+              sleep(1).then(() => results.push('cleanup-1')),
+              Promise.reject('error').catch(() =>
+                results.push('cleanup-2-failed'),
+              ),
+            ])
+          },
+        },
+        'vars',
+      )
+
+      await vi.runAllTimersAsync()
+
+      expect(results).toEqual([
+        'onSuccess-start',
+        'track-analytics',
+        'invalidate-queries',
+        'onSettled-start',
+        'cleanup-2-failed',
+        'cleanup-1',
+      ])
+    })
+
+    test('should handle mixed sync/async patterns and return value isolation', async () => {
+      const key = queryKey()
+      const results: Array<string> = []
+
+      const mutationPromise = executeMutation(
+        queryClient,
+        {
+          mutationKey: key,
+          mutationFn: () => Promise.resolve('actual-result'),
+          onMutate: () => {
+            results.push('sync-onMutate')
+            return { rollback: 'data' }
+          },
+          onSuccess: async () => {
+            results.push('async-onSuccess')
+            await sleep(1)
+            return 'success-return-ignored'
+          },
+          onError: () => {
+            results.push('sync-onError')
+            return Promise.resolve('error-return-ignored')
+          },
+          onSettled: (_data, _error, _variables, context) => {
+            results.push(`settled-context-${context?.rollback}`)
+            return Promise.all([
+              Promise.resolve('cleanup-1'),
+              Promise.resolve('cleanup-2'),
+            ])
+          },
+        },
+        'vars',
+      )
+
+      await vi.runAllTimersAsync()
+
+      const mutationResult = await mutationPromise
+
+      // Verify mutation returns its own result, not callback returns
+      expect(mutationResult).toBe('actual-result')
+      console.log(results)
+      expect(results).toEqual([
+        'sync-onMutate',
+        'async-onSuccess',
+        'settled-context-data',
+      ])
+    })
+
+    test('should handle error cases with all callback patterns', async () => {
+      const key = queryKey()
+      const results: Array<string> = []
+
+      const newMutationError = new Error('mutation-error')
+      let mutationError: Error | undefined
+      executeMutation(
+        queryClient,
+        {
+          mutationKey: key,
+          mutationFn: () => Promise.reject(newMutationError),
+          onMutate: () => {
+            results.push('onMutate')
+            return { backup: 'error-data' }
+          },
+          onSuccess: () => {
+            results.push('onSuccess-should-not-run')
+          },
+          onError: async () => {
+            results.push('onError-async')
+            await sleep(1)
+            // Test Promise.all() in error callback
+            return Promise.all([
+              sleep(1).then(() => results.push('error-cleanup-1')),
+              sleep(2).then(() => results.push('error-cleanup-2')),
+            ])
+          },
+          onSettled: (_data, _error, _variables, context) => {
+            results.push(`settled-error-${context?.backup}`)
+            return Promise.allSettled([
+              Promise.resolve('settled-cleanup'),
+              Promise.reject('settled-error'),
+            ])
+          },
+        },
+        'vars',
+      ).catch((error) => {
+        mutationError = error
+      })
+
+      await vi.runAllTimersAsync()
+
+      expect(results).toEqual([
+        'onMutate',
+        'onError-async',
+        'error-cleanup-1',
+        'error-cleanup-2',
+        'settled-error-error-data',
+      ])
+
+      expect(mutationError).toEqual(newMutationError)
+    })
+  })
 })