feat(queryClient): respect cancelRefetch flag

[TkDodo]

for refetchQueries, as well as for invalidateQueries

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/tannerlinsley/react-query/6uJzVJgj49NYGHoLMfGzFjPeVvmX
✅ Preview: https://react-query-git-fork-tkdodo-feature-cancel-284254-tannerlinsley.vercel.app

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 65bcf42:

Sandbox	Source
tannerlinsley/react-query: basic	Configuration
tannerlinsley/react-query: basic-typescript	Configuration

[tannerlinsley]

🎉 This PR is included in version 3.27.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[dimagimburg]

@TkDodo Hey, until now we used whats written in this page for cancellation, the requests were cancelled without providing cancelRefetch flags.

Will this behavior change in some way?

(i.e similar to the test case you provided, basically works in our project without providing any cancelRefetch flag when using invalidateQueries 🤷 )

[TkDodo]

Query cancellation, as described in the docs page, is just a mechanism to actually cancel the fetch on transport level. The cancelRefetch flag is used to actually let react-query "cancel" currently ongoing fetches. It's equivalent to calling queryClient.cancelQueries before doing the invalidation. That cancellation might lead to a cancellation on network level (if a .cancel method was added to the promise). otherwise, react-query will just ignore the result.

This PR has been sparked by this twitter discussion, where I outline some cases where invalidation alone might not be enough: https://twitter.com/TkDodo/status/1448677532983832580

The bottom line is: If a fetch is already in progress and you instruct react-query to refetch (e.g. via invalidateQueries), it will not do that per default, because a fetch is already going on. With cancelRefetch, the ongoing fetch will be cancelled and a new fetch will be started.

I think we might make this the default behaviour in the next major. If react-query is explicitly instructed to refetch, I think it should do so :)

[dimagimburg]

Thanks for this explanation @TkDodo.

Just mentioning it seems to be a different behavior than what was before cancelRefetch. I would suggest also to delegate the default decision to the client

new QueryClient({
        defaultOptions: {
            queries: {
                cancelRefetch: true
            }
        }
    }

(as I don't see it in QueryObserverOptions).

For example we pretty much rely on cancellation by default (well, not rely, but it helps us with high-bandwidth requests), and would want to avoid adding cancelRefetch to all invalidateQueries because the default is false.

[TkDodo]

Just to be on the same page: This PR didn't change anything regarding the default behaviour. cancelRefetch was previously accepted as an option, but it was never passed to the actual fetch function - so it was always false per default.

Now, you have the option of setting it to true if you want. If things worked for your use-cases before, they should certainly work now, too :)

[VanTanev]

I'm commenting here before opening an issue.

Should the docs at https://react-query.tanstack.com/guides/optimistic-updates be updated, so that

   onSettled: () => {
     queryClient.invalidateQueries('todos')
   },

uses { cancelRefetch: true } ?

[TkDodo]

@VanTanev i don’t think so. We’re already canceling in onMutate, which should be enough for most cases.

[VanTanev]

@TkDodo I wasn't sure, thanks for clarifying!