feat(cancellation): Provide AbortSignal to queryFn

[jcready]

All queryFn calls will now have an AbortSignal instance passed to them
as part of the QueryFunctionContext. In environments that support the
AbortController/AbortSignal the consumer may use this signal as a
way to get notified about the query being cancelled. Consumers no
longer need to add a .cancel() function to the result of queryFn()

const query = useQuery('todos', async ({ signal }) => {
  const res = await fetch('/todos', {
    method: 'get',
    // Pass the signal to your request
    signal,
  });

  const json = await res.json();
  let data = null;

  if (!signal.aborted) {
    // do expensive CPU transformation of data
    data = expensiveTransform(json);
  }

  return data;
});

The previous behavior for cancellation will continue to work. If a
.cancel() function is provided as the result of calling queryFn()
the AbortSignal will not be notified when the cancellation happens.
If the runtime environment does not support AbortController/AbortSignal
the old behavior will continue to work, but the signal provided to
the queryFn() will not be notified when the cancellation happens.

Ref #1671 (comment)
Ref #1671 (comment)

Fix #2775
Fix #1893
Fix #1265
Fix #886

[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/tanstack/react-query/EP7LTfYpn1gxJSY8SYdAUyRN9RxD
✅ Preview: https://react-query-git-fork-jcready-abort-controller-c-59ac27-tanstack.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 16233b0:

Sandbox	Source
tannerlinsley/react-query: basic-typescript	Configuration
focused-fermat-p8lzj	Issue #886

[jcready]

Regarding the check failure below I thought the @babel/env preset would provide support for globalThis. Is that not the case? I can add the minimal code for a polyfill myself if my understand was incorrect.

[TkDodo]

it looks like we only need globalThis to infer type definitions, so can't we just use window.AbortController ?

[jcready]

@TkDodo I already fixed the issue with globalThis

[TkDodo]

Thank you 🙏. I'm still missing:

• tests that actually use the provided signal, for both useQuery and useInfiniteQuery.
• documentation of the feature, likely on this page: https://react-query.tanstack.com/guides/query-cancellation. we could separate it into the old approach and the new one, preferring the new one, and also stating why that is. You've already shown some usage examples in the discussion, which we could copy over I guess?

[TkDodo]

I think this is great work, thank you 🙏 . It will be exciting to ship this

[jcready]

Despite the tests passing I'm fairly sure that this will fail in old browsers that since the MinimalAbortController implementation is using a WeakMap and it doesn't appear that the build system actually polyfills it.

[TkDodo]

this will fail in old browsers

very old browsers :) WeakMap has pretty good compatibility: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap#browser_compatibility

Nevertheless, I now think not providing a signal at all is better as its less code.

[jcready]

Okay. Huge change. I've switched entirely away from trying to provide a minimal interface and just made the signal optional. If the runtime environment has an AbortController interface available we will always provide the AbortSignal. If the signal exists and is consumed/read from the query context provided to the query function then we consider the query "cancelable" and will attempt to revert the query state when all observers have been removed just like we used to do if the query function returned a cancel function.

[TkDodo]

wow, this looks really slick now 🙌

[TkDodo]

sorry for the conflicts - we had another PR that added something to the queryFunctionContext. I think it means you'll also need to adapt the test to account for that extra field

[jcready]

@TkDodo merged

[tannerlinsley]

🎉 This PR is included in version 3.30.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[TkDodo]

Thank you for this great contribution @jcready . I've announced it on twitter: https://twitter.com/TkDodo/status/1454521789938294787

please let me know if you have a twitter handle so I can add you to the shoutout: https://twitter.com/TkDodo/status/1454521795529355265

[jcready]

Thank you @TkDodo! It was a pleasure working with you on this. I don't have Twitter, but I appreciate the link to my GH.

[caub]

I don't really understand, the useQuery(key, cb) 's cb receive a signal, but how do you trigger cancel? is there a query.cancel() function added to the API?

[jcready]

@caub https://react-query.tanstack.com/guides/query-cancellation#manual-cancellation

[TkDodo]

@caub queries will be cancelled automatically by RQ in some situations, like when the query goes to inactive state (=you’re not using it anymore) and there is a fetch pending. For manual cancellation, see the docs link above

[caub]

Ah ok thanks guys, so in all cases, whether we plan to cancel queries manually or not, it's better to pass down signal right? as react-query can make use of it as you just said (component unmounted, etc..)

[jcready]

@caub that is debatable :) though personally I will be using the signal in every query function.

One tradeoff is that for any query that is cancelled where either a .cancel() function is provided on the returned promise OR the signal from the query context is consumed:

• The query cache will not be populated with the resolution of your query function even if it would've been successful. Perhaps this is obvious, but it's an important difference from the old/normal behavior (no .cancel() function provided and signal not consumed).
• The query will have its state reverted back to whatever it was before the query ran https://github.com/tannerlinsley/react-query/blob/16233b0eac8a67da1b5b95e981a94b31addbfce1/src/core/tests/query.test.tsx#L241-L275 This can lead to some unexpected results: How to tell if a query was cancelled? #2807

[sjc5]

@TkDodo It might be helpful to mention the version number after which this feature is available in the docs. I was getting type errors with the destructured signal argument, and it took a bit of digging to realize this is a brand new feature (I was on 3.27.0). I would submit a PR with the update, but am not sure I have enough context to get the details right. Just a thought. Thanks for the great feature, @jcready -- very cool.

[TkDodo]

@telekstr good idea. The version where we introduced it is 3.30.0: https://github.com/tannerlinsley/react-query/releases/tag/v3.30.0

Please contribute it to the Query cancellation docs page, thank you.

[sjc5]

@telekstr good idea. The version where we introduced it is 3.30.0: https://github.com/tannerlinsley/react-query/releases/tag/v3.30.0

Please contribute it to the Query cancellation docs page, thank you.

Sure thing, here you go: #2887