Feature request: useMutation should return 'createMutation' and 'getMutution' functions to allow for concurrent mutations of the same type.

[dwjohnston]

This question relates to several existing issues/discussions, I'm hoping to do a good job here of the explaining the use case.

Problem statement

In some scenarios I may want to have a per-item instance of a useMutation call. For example, I may have an array of items which I display as list, each with their own delete button. I want to track the state of individual mutation calls, and I don't want to do this by putting a useMutation into the specific component.

Suggested solution

The useMutation also returns functions of the shape:

createMutationFn: (id: string) => (input:T) => void; 
getMutationState: (id: string) =>  {isLoading: boolean; isIdle: boolean; isError: boolean; isSuccess: boolean;} // Possibly also expose reset etc.

Related Issues/Discussions

#2304 - This issue is more the converse - how individual useMutation calls have distinct results, while all useQuery have the same result. useIsMutating appears to solve the issue, though I could see the need for a more flexible solution.

#4009 - Looks like the same request. Suggested solution doesn't appear particularly appropriate - although I have a hacky ref solution in that line, that does work.

Details

All examples can be found here:

dwjohnston/query-play@6d7b912

Code sandbox

Example 1 - Naive example

I have a 'like' button. When a user clicks the button it should show a loading cursor, until finished, and then show success/error.

export const SpecialLikeButton = (props: SpecialButtonProps) => {
    const { thingyId } = props;
    const mutation = useMutation(likeTheThing);
    const { isLoading, isSuccess, isIdle, isError, mutate } = mutation;
    return (
        <button onClick={() => mutate(thingyId)}>

            {isLoading && "loading..."}
            {isSuccess && "Liked"}
            {isIdle && "Like thingy"}
            {isError && "sorry something went wrong"}

        </button>
    );
};

This is absolutely fine. But: I don't want to call useMutation directly within such a button.

• What if this button is part of a exported component library - I don't want to require that they use react-query
• For testing, both Storybook and RTL I similarly don't want to have to be setting up contexts to test the behaviour of this component.

Example 2 - Removing useMutation from our special like button.

We can refactor the button's props to look like this, which is more inline with what've what we've want - something state management/context agnostic.

export type SpecialButtonProps = {
    thingyStatus: "idle" | "success" | "loading" | "error"; 
    onButtonClick: () => void; 
};

export const SpecialLikeButton = (props: SpecialButtonProps) => {
    const { thingyStatus, onButtonClick } = props;
    return (
        <button onClick={onButtonClick}>

            {thingyStatus === "loading" && "loading..."}
            {thingyStatus === "success" && "Liked"}
            {thingyStatus === "idle" && "Like thingy"}
            {thingyStatus === "error" && "sorry something went wrong"}

        </button>
    );
};

But how do we pass in those props?

// App.tsx


    const mutationResult = useMutation(likeTheThing);
    const status = determineStatus(mutationResult); // "success" |"idle"|"error"|"loading"; 


return <>

        {widgets.map((v) => {
            return <div> 
                    Widget {v}
                    <SpecialLikeButton onButtonClick={()=> mutationResult.mutate(v)}
                        thingyStatus={status}
                    />
                </div>; 
        })}
</>

This doesn't suffice - a click on a single button will show loading buttons for all buttons.

Example 3 - Use a wrapper/container component.

function WrappedSpecialLikeButton(props: {id: string}) {
    const mutationResult = useMutation(likeTheThing);
    const status = determineStatus(mutationResult)
    return <SpecialLikeButton thingyStatus={status} onButtonClick={()=> mutationResult.mutate(props.id)}/>
}

This is gives us a per-item useMutation result - but it doesn't really solve the problem - what if we wanted to export a component that used this component?

Example 4 - Hacky ref solution.

This does seem to work:

function useMultipleMutation(ids: Array<string>){
    const ref = useRef<Record<string, any>>({}); 
    ids.forEach((v) => {
        
        // eslint-disable-next-line react-hooks/rules-of-hooks
        const result = useMutation(likeTheThing); 
        ref.current[v] = result; 
    })
    return ref; 
} 


export function App() {

    const widgets = ["1", "2", "3"]; 
    const hackyRef = useMultipleMutation(widgets); 

    return <>
        {widgets.map((v) => {
            return <div> 
                    Widget {v}

                    <SpecialLikeButton  onButtonClick={hackyRef.current[v].mutate} thingyStatus={determineStatus(hackyRef.current[v])}/>

                </div>; 
        })}
    </>





}

However, it makes uncomfortable.

What I would like to see

I would like to be able to use some code like:

export function App() {

    const widgets = ["1", "2", "3"]; 
    const {createMutateFn, getMutateResult}  = useMutation(likeTheThing); 

    return <>
        {widgets.map((v) => {
            return <div> 
                    Widget {v}

                    <SpecialLikeButton  onButtonClick={createMutateFn(v)} thingyStatus={determineStatus(getMutateResult(v)}/>

                </div>; 
        })}
    </>

That is - the ability to configure a useMutation hook with the same parameters, but keep track of individual calls - individual calls being differentiated by a string id.

Performance Considerations

I will mention that there are possible performance considerations here.

As opposed to doing either the Example 1 or Example 3 approach - it's possible that the solution I propose would give the scenario where a button click on a single button would cause rerenders up at the root (where the useMutation is), meaning that a single button click causes all the other buttons to also rerender.

[TkDodo]

I think examples 1 or 3 are perfectly fine. I would always prefer to keep mutations close to where they are used.

What would be the point of having a SpecialLikeButton that doesn't "do anything" ? Exposing it without functionality, e.g. from a component library, is what a Button component would do. I know it's just one example, but I would do:

import { Button } from 'my-component-library'

export const SpecialLikeButton = (props: SpecialButtonProps) => {
    const { thingyId } = props;
    const mutation = useMutation(likeTheThing);
    const { isLoading, isSuccess, isIdle, isError, mutate } = mutation;
    return (
        <Button onClick={() => mutate(thingyId)}>
            {isLoading && "loading..."}
            {isSuccess && "Liked"}
            {isIdle && "Like thingy"}
            {isError && "sorry something went wrong"}
        </Button>
    );
};

the point about testing might be real, and its a trade-off for sure. We use msw to mock network requests in stories and tests so that we can test things like the LikeButton. Otherwise, it always makes sense to me to test these things in the real application - mounting the page in cypress where we also have interceptors available.

[dwjohnston]

What would be the point of having a SpecialLikeButton that doesn't "do anything"

For example, we're creating a music or IMDB type app, we've got 'Like Artist', 'Like Song', 'Like Genre', 'Like Playlist'.

We want these buttons to behave consistently, (with their loading state, what happens after it successfully completes), but the actual API calls for each one are completely different.

the point about testing might be real, and its a trade-off for sure. We use msw to mock network requests in stories and tests so that we can test things like the LikeButton

Yup, so basically I want to avoid API mocking. I've written about it here. The argument is that if you have some kind of complex joining/transformation logic, then it adds a lot of cognitive overhead to writing tests - you have to know which API endpoints need to be called, what their joining conditions are, etc.

[raythurnvoid]

Any update on this? useMutation forces you to place the mutation inside the component that performs the action, and prevents from instead placing this call in the parent component that renders the list.

What if I have 2 visually equal elements but should perform slightly different things when interacted with? I would like to define the logic in the parent component.

[TkDodo]

What if I have 2 visually equal elements but should perform slightly different things when interacted with?

you can always pass the mutationFn down to the children where the mutation is to keep the “logic” in the parent

[raythurnvoid]

But then isLoading and error are shared across all elements in a list

[TkDodo]

no?

function Parent() {
  const mutationFn = () => ...

  return <Child mutationFn={mutationFn} />
}

function Child({ mutationFn }) {
  const { isLoading, error, mutate } = useMutation({ mutationFn })

  ...
}