feat(query-core): add queryClient argument to mutation callbacks and mutationFn

[raymondanythings]

Background

When working with mutations, most callback logic (optimistic updates, cache updates, invalidations) needs direct access to queryClient.

Currently, this requires manually calling useQueryClient() inside callbacks, or wrapping mutation logic with custom hooks, which adds boilerplate.

PR #9193 proposes passing queryClient via MutationFunctionContext, but this changes callback parameter structures and may break compatibility with existing code.

What’s Different in This PR

Instead of replacing the last argument with a context object, this PR appends queryClient as the final parameter in:

• mutationFn
• onMutate
• onSuccess
• onError
• onSettled

This preserves all existing parameters and their positions, making it fully backward-compatible for users who don’t use the new argument.

Example Usage

useMutation({
  mutationFn: (variables, queryClient) => {
    return api.updateItem(variables).then(res => {
      queryClient.invalidateQueries({ queryKey: ['items'] })
      return res
    })
  },
  onSuccess: (data, variables, _context, queryClient) => {
    queryClient.setQueryData(['items'], prev => [data, ...(prev ?? [])])
  }
})

Why This Approach

Backward-compatible: Does not alter existing argument order.

Low migration cost: Existing code works without changes.

Simple mental model: queryClient is always the last argument.

[solastley]

@raymondanythings the benefit of the other approach is that we also get access to the meta object, and potentially anything else we want to include in context in the future. The approach in this PR does not allow for that, and if we ever want to add it in the future then we would need a context-like approach anyways.

[TkDodo]

but this changes callback parameter structures and may break compatibility with existing code.

it does no such thing. Just like this PR, it adds a second argument to mutationFn.

This PR:

mutationFn: (variables, queryClient) => {

The other PR:

mutationFn: (variables, context) => {

where context contains queryClient, mutationKey and meta.

The other PR does not affect onSuccess, onError or onSettled callbacks at all.