Consolidate useMutation API to use the object pattern?

[cliffordfajardo]

⚠️ This more of a subjective API / developer experience discussion. No bug or code related issues here.

While browsing the react-query docs for useMutation the example shown is the version of useMutation that takes the mutationFn as it's first argument.

There is also the version of useMutation that takes in an object (UseMutationOptions), but is not shown on the website docs (it is with typescript types & editor autocomplete)

I think the useMutation call using the UseMutationOptions object might have a few more benefits than the other available ways to call the useMutation hook:

• readable arguments
• order of passed in args doesn't matter
• easier to maintain docs and examples with this one 1 pattern

I imagine that the reason we have multiple ways to call useMutation is for backwards compatibility & historical purposes. In the future, do you think it is worth or even feasible consolidating the useMutationAPI?

• Maybe I'm asking dumb questions, but simply trying to understand the the perspective of a library maintainer as well 🙏

What do you think about me updating the docs examples to use the passing of the object approach?

[TkDodo]

It was actually on our roadmap for v4 to remove all overloads and only use a single object for useQuery and useMutation. However, we got stopped by a known typescript limitation where TS has troubles with type inference in certain situations, which would be worse. For reference: microsoft/TypeScript#43371 (comment)

[cliffordfajardo]

Ahhh - thanks for adding context!

[zbigg]

I was looking whether "object syntax" variant useMutation is an official or accidental (in typings, but not documented) API and found this thread and it looks like not documenting it is only by omission.

But original question was unanswered:

What do you think about me updating the docs examples to use the passing of the object approach?

Are we right? Shall we update doc to state that useMutation also can also be used with "the object syntax"?

I'm happy to open PR, it should be trivial.

[TkDodo]

for queries, its documented here: https://react-query.tanstack.com/guides/query-functions#using-a-query-object-instead-of-parameters

we could add something similar to the mutations page: https://react-query.tanstack.com/guides/mutations