Clarify online support

[TkDodo]

We currently have multiple issues pertaining to online / offline support that are hard to fix without breaking something:

• isFetching is always true when there's no internet #2361
• Query never goes into Error state if there's no internet #2179
• retry doesn't stop during the internet is disconnected #2900

Proposed solution

Create a new query flag for offline queries (offline: boolean - name to be discussed). Since react-query is primarily an async state manager, it actually doesn't care about "being online". However, most people will use react-query for data fetching, so it makes sense to default this to false.

If you are using react-query to fetch from somewhere else, like AsyncStorage, where fetches should also happen when you are offline, you can set this flag to true. Also, if your api supports http caching, setting this to true will be beneficial because "fetching" from the browser-cache will also work when you're offline.

This would mean that we would, if offline is false (the default) and you have no internet:

• pause retries when you have no internet. This would be non-breaking because we already do that.
• Do not trigger refetches. Currently, we only do this for window focus refetches, but manual calls to refetch / invalidation don't adhere to this. If a query is explicitly refetched, it should probably be marked as stale instead so that it will be refetched on reconnect.
• When a new query mounts, stay in whatever current state and don't trigger background refetches.
  • This means that if a query mounts for the first time, it will be in idle state - we need to properly communicate this that people need to handle that.
  • if a query is already in error state, we also wouldn't refetch, but stay in error state instead.

if offline is true, we would:

• don't pause retries because you are offline - they would just continue. if you are not fetching via network, it would not be impacted, and if you have cached data in the browser cache, it would succeed on the first try anyways.
• trigger refetches normally - same reasoning as above
• when a new query mounts - also fetch normally (same reasoning as above)

If you say that your query is an offline query, but you are still fetching over the internet and have no browser cache, you will get a failed Promise after 3 retries and have to handle the error properly.

---

This new flag could potentially replace the refetchOnReconnect flag. If a query is an offline query, it wouldn't refetch on reconnect, and if it's an online query, it would. If we want to keep the flag, we could default it to the value of !offline. This is still to be discussed.

[TkDodo]

one thing that is not addressed with the mentioned approach is the following scenario:

• you have an online query
• you start fetching, it takes some time
• you go offline
• the fetch will likely fail, triggering a retry
• the retrier will pause retries because you are offline (and need to be online to continue)

--> your loading spinner will show until you're online again, even though you're not technically "fetching"

two solutions come to mind:

1. remove the feature of pausing retries altogether. It means that once you have started fetching and go offline, it will continue to retry and will likely wind up in error state unless you go online again. I don't think that's ideal.

2. cancel the query and revert it to its previous state. if its a background refetch, the query will go to success state and isFetching will be false, which is nice. If you don't have data yet, the query will go to idle state. I think this would be consistent with the behaviour when a query mounts and you're offline, so this would be my preferred solution.

What do you think @arnaudbzn ?

[TkDodo]

Ah, another good way would be to maybe expose the internal isPaused flag. It should be true when the query is paused by the retrier. That way we could also potentially keep it in loading / fetching state, and consumers could check for isPaused. isFetching could also be exposed as false if isPaused is true, which would make background loading spinners disappear for paused queries 🤔

[arnaudbzn]

Ah, another good way would be to maybe expose the internal isPaused flag. It should be true when the query is paused by the retrier. That way we could also potentially keep it in loading / fetching state, and consumers could check for isPaused. isFetching could also be exposed as false if isPaused is true, which would make background loading spinners disappear for paused queries

I prefer this solution!
If isFetching is false, I can check isPaused if I need to display a "in pause" indicator!

A new pauseReason: offline | notFocused can be handy to have a direct access to pause reason (it can be array of reasons).

onlineManager.setEventListener already provides a solution to customize what is an offline mode.
It means that the default concept of online/offline is associated to the network connectivity but it can be customized.
Same for the focus management.
So if a fetch the AsyncStorage, I have to use onlineManager.setEventListener to customize the online mode.
We could support a query based onlineManager.setEventListener for more granularity.

[TkDodo]

I prefer this solution!
If isFetching is false, I can check isPaused if I need to display a "in pause" indicator!

spinning this idea a bit further:

type FetchingState = 'fetching' | 'paused' | 'idle'

we could of course provide isFetching and isPaused derived booleans from that internal state, similar to how query.state drives isSuccess, isError etc.

it would mean that if a new query mounts that doesn't have any data yet, if you are offline, instead of putting it in the idle state, we could just put it in:

status: 'loading',
fetchingStatus: 'paused'

sure, if you just display a loading spinner based on the status, you would see the spinner, but I think this is better than putting the query in idle state, which might not be handled at all by most people.

similar, if you have data already and mount a new query, the refetchOnMount would trigger but instead of actually fetching, it would put the query in:

status: 'success',
data: yourStaleData,
fetchingStatus: 'paused'

A new pauseReason: offline | notFocused can be handy to have a direct access to pause reason.

I think we could do that, too.

We could support a query based onlineManager.setEventListener for more granularity.

could you elaborate a bit on how that could look like?

---

I'm still not totally happy with the fact that you have to decide between online / offline queries. For example, you can't know if a query will yield data from the browser cache or not. If it does, mounting it, fetching + getting data from the browser cache would work, but with the initial proposal, you would have to specify it as an offline query because it otherwise wouldn't start fetching. But if you do that and there is no browser cache data available for whatever reason, retries wouldn't pause :/
So essentially, in this situation, trying the fetch once and then pausing the retries would be nice, which is essentially what we are doing today. However, if you for example turn off retries and are offline, we fetch and would give you the error immediately, which would spark the question of why did we even try to fetch at all...

[arnaudbzn]

We could support a query based onlineManager.setEventListener for more granularity.
could you elaborate a bit on how that could look like?

I can have one query for the AsyncStorage and another one for an API. The same concept of offline cannot apply for both.
setEventListener could accept a new queryKey argument. So my AsyncStorage based query can be always online.

[TkDodo]

So my AsyncStorage based query can be always online.

I think this is exactly the case I wanted to solve with the offline query option. It could be set on a per-query level to define which queries need to be online to work and which don't.

The onlineManager is a global singleton, which doesn't have any correlation to queries. You either are online, or you're not (I think...)

[arnaudbzn]

I think this is exactly the case I wanted to solve with the offline query option. It could be set on a per-query level to define which queries need to be online to work and which don't.

The naming could be more precise, instead of offline:

• offlineModeSupport: true
  or
• mode: online (default) | offline | all

[TkDodo]

yes, definitely agree. I like mode: 'online' | 'offline' - but what would 'all' be 😅 ?

[arnaudbzn]

yes, definitely agree. I like mode: 'online' | 'offline' - but what would 'all' be 😅 ?

all it's weird indeed.
I was just thinking about 3 possible modes

• online
• offline only
• online and offline (all)

offline only mode means that the query isPaused: true when the connectivity is online, but I have no use case in mind for this mode..

mode: 'online' | 'offline' is straightforward!

[Liam-Tait]

What about requiresInternetConnection: boolean?

I imagine this would be able to be set as a config value in QueryClient and it would be rare to override that value on a per query basis. This means the verboseness of the name is less of an issue