queryFn Gets client, But Why Not mutationFn?

[raymondanythings]

Mutation is commonly used to modify server state.
As a result, it's often necessary to access the queryClient for tasks like optimistic updates.
After noticing that client is passed as an argument to queryFn, I tried using it with mutationFn as well, but found that this functionality is currently not supported.

Problem

To update the query cache, we currently need to wrap the mutation in a custom hook, like this:

const useMutationData = () => {
  const queryClient = useQueryClient();
  const mutation = useMutation({
    mutationFn: (data: Params) => axios.post("/api/data", data),
    onMutate: (data) => {
      queryClient.setQueryData(["data"], data);
    },
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: ["data"] });
    },
  });
};

However, if the client could be passed as an argument like in queryFn, the intended behavior of the mutation could be implemented more easily:

useMutation({
  mutationFn: (data: Params) => axios.post("/api/data", data),
  onMutate: (...args) => {
    const [data, , , client] = args;
    client.setQueryData(["data"], data);
  },
  onSuccess: (...args) => {
    const [, , , client] = args;
    client.invalidateQueries({ queryKey: ["data"] });
  },
});

This would allow all necessary logic to remain within the mutation hook itself, without requiring a custom wrapper.

Why This Matters

With the addition of mutationOptions, it's now possible to structure mutations separately in their own layer.
However, accessing the query cache via a custom hook feels contrary to that design intention.
If we could access queryClient directly within mutationOptions, it would align better with the purpose of mutations and eliminate the need for additional boilerplate.

[TkDodo]

we actually have a PR up for this:

• feat(query-core): add MutationFunctionContext argument to mutateFn #9193

but it seems like you’d want it in the callbacks, not in the mutationFn? At least your examples aren’t using it there...

[raymondanythings]

I believe injecting the client would be more useful in the callbacks rather than the mutateFn.
Since query state updates often happen in the onMutate or onSuccess callbacks, having access to the client there would be more practical.
Would it be okay if I opened a new PR for this?

[atomanyih]

Having access to QueryClient in onMutate and onSuccess would be helpful for us as well. Since these are the callbacks where we are updating or invalidating the cache, it is awkward to always have to manually access the query client through the hook. It would also be nice to extract mutations into their own layer like we can do with QueryOptions