Possibility of adding cancel function to UseQueryOptions

[ashwinGokhale]

The current way that cancellations are handled is by having the user attach a cancel function to the promise itself. One downside with this approach is that the user must attach the cancel function to the outermost promise, which means that it discourages using the async/await syntax for the QueryFunction. Another minor inconvenience for typescript users is that there is no cancel function on a Promise, so you have to create a new interface just for this.

For example, this works:

 import { CancelToken } from 'axios'
 
 const query = useQuery('todos', () => {
   // Create a new CancelToken source for this request
   const source = CancelToken.source()
 
   const promise = axios.get('/todos', {
     // Pass the source token to your request
     cancelToken: source.token,
   })
 
   // Cancel the request if React Query calls the `promise.cancel` method
   promise.cancel = () => {
     source.cancel('Query was cancelled by React Query')
   }
 
   return promise
 })

But this does not:

 import { CancelToken } from 'axios'
 
 const query = useQuery('todos', async () => {
   // Create a new CancelToken source for this request
   const source = CancelToken.source()
 
   const promise = axios.get('/todos', {
     // Pass the source token to your request
     cancelToken: source.token,
   })
 
   // Cancel the request if React Query calls the `promise.cancel` method
   promise.cancel = () => {
     source.cancel('Query was cancelled by React Query')
   }
   
   const value = await promise; 

   return value;
 })

I was thinking that maybe there could be an optional cancel function added to the UseQueryOptions as an alternate way of handling query cancellation.

For example:

import React from "react";
import axios from 'axios';
import axiosCancel from 'axios-cancel';
import { useQuery } from "react-query";
 
axiosCancel(axios);
 
const requestId = 'fetchPostsRequest';

const fetchPosts = async () => {
  const { data } = await axios.get('https://jsonplaceholder.typicode.com/posts', { requestId })
  return data;
}

export default function Posts() {
  const { data } = useQuery('posts', () => fetchPosts(), {
    cancel: () => axios.cancel(requestId)
  });

  return (
    <div>
      <h1>My Posts</h1>
      <div>{JSON.stringify(data)}</div>
    </div>
  );
}

[TkDodo]

I would tend to agree that the current approach is not ideal. We’ve had issues reported for both cases you described (async and TS). Maybe we could add the cancel option in a minor and remove the “cancel-on-the-promise” in the next major. Could you provide examples for:

• axios without axios-cancel
• fetch w/ Abortcontroller

some situations why this might not work:

• you could have one subscriber with the option and one without - what happens then?
• will this approach work with queryClient.cancelQueries(key)?
• Will this approach work if you define this option on the queryDefaults in the QueryClientProvider?

[ashwinGokhale]

It would be a bit of extra code but I'll see if I can come up with concise examples for both fetch and axios. The basic idea would be that you keep a mapping of request id --> cancel token and before making a new request, you get the token based on the request id and cancel the previous one.

1. If you have one subscriber with and one without, then these 2 examples would be equivalent:

With Promise.cancel():

const fetchPosts = async (requestId?: string) => {
  const { data } = await axios.get('https://jsonplaceholder.typicode.com/posts', { requestId })
  return data;
}

export default function Posts() {
  const q1 = useQuery('posts', 
        () => {
            const promise = fetchPosts('fetchPostsRequest');

            promise.cancel = () => axios.cancel('fetchPostsRequest');

            return promise;
        });

  const q2 = useQuery('posts', () => fetchPosts());

  return (
    <div>
      <h1>My Posts</h1>
      <div>{JSON.stringify(q1.data)}</div>
      <div>{JSON.stringify(q2.data)}</div>
    </div>
  );
}

With cancel method:

export default function Posts() {
  const q1 = useQuery('posts', () => fetchPosts('fetchPostsRequest'), { // Same fetchPosts from above
    cancel: () => axios.cancel('fetchPostsRequest')
  });

  const q2 = useQuery('posts', () => fetchPosts());

  return (
    <div>
      <h1>My Posts</h1>
      <div>{JSON.stringify(q1.data)}</div>
      <div>{JSON.stringify(q2.data)}</div>
    </div>
  );
}

2. I'm not really familiar with the internals of how react-query works but my theory would be if react-query wants to cancel a query from queryClient.cancelQueries(key), it would fuzzy search the query by its query key, which will give it some list of matching query objects that contain some metadata (the promise, the query options, the query key, etc...) about their queries. It would then go through each query object and call query.promise.cancel() on each promise. If you can get the promise for that query, then I would assume you can also get the options for that query, so after you call query.promise.cancel?.(), you would also call query.options.cancel?.() in the line right after. Ideally, it would have the exact same behavior as attaching a cancel function to the query function, but instead of it being attached to the promise, it would be attached to the query options.

3. Adding a default cancel function could work by just merging the defaults with each useQuery options, but I'm not sure how much value it would add. If you wanted it to be generic, then maybe the cancel function could take the query key so that you know which request you are canceling:
   Instead of cancel: () => void it would be cancel: (queryKey: QueryKey) => void.
   If users have access to the query key, users could serialize it however they want in order to retrieve the correct cancel token / abort controller.

[tannerlinsley]

The reason for today’s api is so you can cancel specific instances of a fetch function that have been called. All, some, or one. If you extract out the cancel logic, you lose that fidelity that you can only get inside of the current scope of Query function execution. Yes, this means you can’t pass an async syntax function directly, but it’s simple enough to wrap into it with Promise.resolve() Some pseudo code from my phone while laying in bed ;) () => {   // create the cancel token   const promise = Promise.resolve().then(async () => {     // pass the cancel token     const stuff = await axios.get()     return stuff   }   promise.cancel = token.cancel   return promise } Tanner Linsley

…

On Jan 23, 2021, 5:23 AM -0700, Dominik Dorfmeister ***@***.***>, wrote: I would tend to agree that the current approach is not ideal. We’ve had issues reported for both cases you described (async and TS). Maybe we could add the cancel option in a minor and remove the “cancel-on-the-promise” in the next major. Could you provide examples for: • axios without axios-cancel • fetch w/ Abortcontroller some situations why this might not work: • you could have one subscriber with the option and one without - what happens then? • will this approach work with queryClient.cancelQueries(key)? • Will this approach work if you define this option on the queryDefaults in the QueryClientProvider? — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[ashwinGokhale]

Creating a cancel token inside the scope of the query function is a good point, and for this reason I don't think the cancel function in the options will completely replace the "cancel-on-the-promise" way of doing things. Personally, I use axios-cancel, so I can control the cancellations for one, some, or all requests by specifying a request id that fits my use case. Since I don't need to create the cancel token inside the query function, I feel like it make more sense to add the cancel function to the options instead of to the Promise itself. This way I can write less code, use async/await, and keep Typescript happy. In my mind, users would have both options at their disposal and can choose which one they want depending on their use case, but the behavior of both would be identical. It would just be an alternate way of telling react-query how to get to the cancel function for that specific query.

[jcready]

I would like to propose another alternative: have react-query provide its own AbortSignal instance to the user-supplied queryFn (and possibly mutationFn). The idea would be that all queries are "cancellable" from react-query's POV since it is the one holding onto the AbortController instances. Unlike the existing, completely non-standard solution that breaks TypeScript type-checking, the AbortController and AbortSignal interfaces are actually standardized and work correctly with TypeScript.

// Fetch usage - look ma, I can use async functions at the top level and still support cancellation!
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;
});

// axios usage
import axios from 'axios'

const query = useQuery('todos', ({ signal }) => {
  // Create a new CancelToken source for this request
  const CancelToken = axios.CancelToken
  const source = CancelToken.source()
  signal.addEventListener('abort', () => {
    source.cancel('Query was cancelled by React Query')
  })

  return axios.get('/todos', {
    // Pass the source token to your request
    cancelToken: source.token,
  })
})

// XMLHttpRequest usage
const query = useQuery('todos', ({ signal }) => {
  return new Promise((resolve, reject) => {
    var oReq = new XMLHttpRequest();
    oReq.addEventListener('load', () => {
      resolve(JSON.parse(oReq.responseText));
    });
    signal.addEventListener('abort', () => {
      oReq.abort();
      reject();
    });
    oReq.open('GET', 'http://www.example.org/example.txt');
    oReq.send();
  });
});

[TkDodo]

There are some reasons why I wouldn't think this is a good idea:

• AbortController is browser specific and not available in all browsers.
• you would need extra work if you're already using libraries that support cancellation in a different way, like axios.
• react-query itself is not network specific but promise-based. You can give it a promise that fetches from somewhere else, like e.g. an AsyncStorage. You could even use it on the backend to fetch from a database 🤷 . In all those scenarios, you might have a completely different way of performing the actual cancellation that has nothing to do with cancelling a network request and thus the AbortController.

[jcready]

AbortController is browser specific and not available in all browsers.

It's availability is at >93% according to your own link. Promises are only a few percentage points higher at 96%. It is a fairly simply construct that has polyfills available. Not only is it widely supported in browsers, it is also supported in Node. It is also the way that react-query's own docs suggest that users implement cancellation.

you would need extra work if you're already using libraries that support cancellation in a different way, like axios.

Supplying the queryFn an AbortSignal instance would require less work in the majority of cases for most consumers since they no longer need to create their own AbortController as the docs suggest. It would literally take the exact same number of lines as the axios example in the docs:

- // Cancel the request if React Query calls the `promise.cancel` method
- promise.cancel = () => {
+ // Cancel the request if React Query tells us to abort
+ signal.addEventListener('abort', () => {
    source.cancel('Query was cancelled by React Query')
  })

Not to mention that Axios itself admits they're cancellation system is based on a now defunct/abandoned/withdrawn proposal. Whereas the AbortController and AbortSignal is standardized.

react-query itself is not network specific but promise-based. You can give it a promise that fetches from somewhere else, like e.g. an AsyncStorage. You could even use it on the backend to fetch from a database 🤷 . In all those scenarios, you might have a completely different way of performing the actual cancellation that has nothing to do with cancelling a network request and thus the AbortController.

You are clearly not understanding the purpose of the AbortController/AbortSignal spec. It has nothing to do with networking. It is a general purpose construct for aborting ongoing activities: "Though promises do not have a built-in aborting mechanism, many APIs using them require abort semantics. AbortController is meant to support these requirements by providing an abort() method that toggles the state of a corresponding AbortSignal object. The API which wishes to support aborting can accept an AbortSignal object, and use its state to determine how to proceed."

[TkDodo]

@jcready can we make sure that this won't break in environments where AbortController is not present? If so, I could see us extending the functionality in a minor by adding the abort signal to the QueryFunctionContext as an additional means of cancelling, potentially deprecating the old one in a new major.

But we'd also need to consult with @tannerlinsley please.

[jcready]

I can imagine a few ways to solve the issue of environments not having AbortController:

1. Explicitly call out the requirement in the docs/readme and provide links to polyfills (easiest).
2. Include a dependency on polyfill (easy but extra dependencies are strictly worse than fewer).
3. Only support this method of cancellation in environments that have support for AbortController. If it is available an AbortController is made and an AbortSignal instance is passed to the queryFn. If not then no AbortSignal is passed to the queryFn. The TS type for the signal property passed to the queryFn would simply be signal?: AbortSignal | null. It's a little more work for both the library and the consumer who would be forced to always check for truthy-ness (or just use !).
   1. Another option here would be to keep the type as signal: AbortSignal and just fake the interface for environments w/o support (e.g. it would never actually abort) with a warning in the docs/readme about how environments w/o support will simply never see their AbortSignals actually become aborted:

      const noopDescriptor = { value: () => {} };
      function FakeAbortSignal() {}
      Object.defineProperties(FakeAbortSignal.prototype, {
        addEventListener: noopDescriptor,
        removeEventListener: noopDescriptor,
        aborted: { value: false }
      });

Personally I'd go with 1 and then 3.i, but I'd be happy with any of those options as they'd all be superior to the existing solution. Here are just a few polyfills I've found:

• https://github.com/mo/abortcontroller-polyfill
• https://github.com/mysticatea/abort-controller
• https://github.com/benlesh/abort-controller-polyfill

[tannerlinsley]

I like this idea as long as we can make sure it doesnt require polyfills for all of our standard environments, eg most browsers, recent node versions, and React Native. If we can guarantee that and also make the change non breaking, go for it. We can then deprecate the old way in a major in the future.

…

On Oct 9, 2021, 7:50 AM -0600, James Wyatt Cready-Pyle ***@***.***>, wrote: I can imagine a few ways to solve the issue of environments not having AbortController: 1. Explicitly call out the requirement in the docs/readme and provide links to polyfills (easiest). 2. Include a dependency on polyfill (easy but extra dependencies are strictly worse than fewer). 3. Only support this method of cancellation in environments that have support for AbortController. If it is available an AbortController is made and an AbortSignal instance is passed to the queryFn. If not then no AbortSignal is passed to the queryFn. The TS type for the signal property passed to the queryFn would simply be signal?: AbortSignal | null. It's a little more work for both the library and the consumer who would be forced to always check for truthy-ness (or just use !). a. Another option here would be to keep the type as signal: AbortSignal and just fake the interface for environments w/o support (e.g. it would never actually abort) with a warning in the docs/readme about how environments w/o support will simply never see their AbortSignals actually become aborted: const noopDescriptor = { value: () => {} }; function FakeAbortSignal() {} Object.defineProperties(FakeAbortSignal.prototype, { addEventListener: noopDescriptor, removeEventListener: noopDescriptor, aborted: { value: false } }); Personally I'd go with 1 and then 3.i, but I'd be happy with any of those options as they'd all be superior to the existing solution. Here are just a few polyfills I've found: • https://github.com/mo/abortcontroller-polyfill • https://github.com/mysticatea/abort-controller • https://github.com/benlesh/abort-controller-polyfill — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe. Triage notifications on the go with GitHub Mobile for iOS or Android.

[TkDodo]

Nice, in that case, I would also go with 1) and 3.i (the empty fake interface when there is no support and no polyfill provided by the user). @jcready would you like to give it a go? I'm happy to provide assistance if needed.

[jcready]

I haven't updated the docs or anything, but here's a draft PR that has the implementation and tests: #2782

[ashwinGokhale]

Looks like axios v0.22.0 also has support for signal: axios/axios#3305