feat: add refetch on reconnect functionality

Author: boschni

docs/src/pages/docs/api.md

@@ -29,6 +29,7 @@ const {
   cacheTime,
   keepPreviousData,
   refetchOnWindowFocus,
+  refetchOnReconnect,
   refetchInterval,
   refetchIntervalInBackground,
   queryFnParamsFilter,
@@ -92,6 +93,9 @@ const queryInfo = useQuery({
 - `refetchOnWindowFocus: Boolean`
   - Optional
   - Set this to `true` or `false` to enable/disable automatic refetching on window focus for this query.
+- `refetchOnReconnect: Boolean`
+  - Optional
+  - Set this to `true` or `false` to enable/disable automatic refetching on reconnect for this query.
 - `onSuccess: Function(data) => data`
   - Optional
   - This function will fire any time the query successfully fetches new data.

docs/src/pages/docs/comparison.md

@@ -38,7 +38,7 @@ Feature/Capability Key:
 | Query Cancellation                           | ✅                                     | 🛑                                             | 🛑                                                                        |
 | Partial Query Matching<sup>2</sup>           | ✅                                     | 🛑                                             | 🛑                                                                        |
 | Window Focus Refetching                      | ✅                                     | ✅                                             | 🛑                                                                        |
-| Network Status Refetching                    | 🛑                                     | ✅                                             | ✅                                                                        |
+| Network Status Refetching                    | ✅                                     | ✅                                             | ✅                                                                        |
 | Automatic Refetch after Mutation<sup>3</sup> | 🔶                                     | 🔶                                             | ✅                                                                        |
 | Cache Dehydration/Rehydration                | 🛑                                     | 🛑                                             | ✅                                                                        |
 | React Suspense (Experimental)                | ✅                                     | ✅                                             | 🛑                                                                        |

docs/src/pages/docs/guides/important-defaults.md

@@ -7,6 +7,6 @@ Out of the box, React Query is configured with **aggressive but sane** defaults.
 
 - Query results that are _currently rendered on the screen_ (via `useQuery` and similar hooks) will become "stale" immediately after they are resolved and will be refetched automatically in the background when they are rendered or used again. To change this, you can alter the default `staleTime` for queries to something other than `0` milliseconds.
 - Query results that become unused (all instances of the query are unmounted) will still be cached in case they are used again for a default of 5 minutes before they are garbage collected. To change this, you can alter the default `cacheTime` for queries to something other than `1000 * 60 * 5` milliseconds.
-- Stale queries will automatically be refetched in the background **when the browser window is refocused by the user**. You can disable this using the `refetchOnWindowFocus` option in queries or the global config.
+- Stale queries will automatically be refetched in the background **when the browser window is refocused by the user or when the browser reconnects**. You can disable this using the `refetchOnWindowFocus` and `refetchOnReconnect` options in queries or the global config.
 - Queries that fail will silently be retried **3 times, with exponential backoff delay** before capturing and displaying an error to the UI. To change this, you can alter the default `retry` and `retryDelay` options for queries to something other than `3` and the default exponential backoff function.
 - Query results by default are structurally shared to detect if data has actually changed and if not, the data reference remains unchanged to better help with value stabilization with regards to useMemo and useCallback. Structural sharing only works with JSON-compatible values, any other value types will always be considered as changed. If you are seeing performance issues because of large responses for example, you can disable this feature with the `config.structuralSharing` flag. If you are dealing with non-JSON compatible values in your query responses and still want to detect if data has changed or not, you can define a data compare function with `config.isDataEqual`.

src/core/config.ts

@@ -56,6 +56,7 @@ export const DEFAULT_CONFIG: ReactQueryConfig = {
     staleTime: 0,
     cacheTime: 5 * 60 * 1000,
     refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
     refetchOnMount: true,
     structuralSharing: true,
   },

src/core/index.ts

@@ -1,13 +1,7 @@
 export { queryCache, queryCaches, makeQueryCache } from './queryCache'
 export { setFocusHandler } from './setFocusHandler'
-export {
-  CancelledError,
-  deepIncludes,
-  isCancelledError,
-  isError,
-  setConsole,
-  stableStringify,
-} from './utils'
+export { setOnlineHandler } from './setOnlineHandler'
+export { CancelledError, isCancelledError, isError, setConsole } from './utils'
 
 // Types
 export * from './types'

src/core/query.ts

@@ -7,6 +7,7 @@ import {
   isCancelable,
   isCancelledError,
   isDocumentVisible,
+  isOnline,
   isServer,
   replaceEqualDeep,
   sleep,
@@ -280,12 +281,28 @@ export class Query<TResult, TError> {
     return this.observers.some(observer => observer.config.enabled)
   }
 
-  shouldRefetchOnWindowFocus(): boolean {
-    return (
-      this.isEnabled() &&
+  onWindowFocus(): void {
+    if (
       this.state.isStale &&
-      this.observers.some(observer => observer.config.refetchOnWindowFocus)
-    )
+      this.observers.some(
+        observer =>
+          observer.config.enabled && observer.config.refetchOnWindowFocus
+      )
+    ) {
+      this.fetch()
+    }
+  }
+
+  onOnline(): void {
+    if (
+      this.state.isStale &&
+      this.observers.some(
+        observer =>
+          observer.config.enabled && observer.config.refetchOnReconnect
+      )
+    ) {
+      this.fetch()
+    }
   }
 
   subscribe(
@@ -410,8 +427,8 @@ export class Query<TResult, TError> {
           // Delay
           await sleep(functionalUpdate(retryDelay, failureCount) || 0)
 
-          // Pause retry if the document is not visible
-          if (!isDocumentVisible()) {
+          // Pause retry if the document is not visible or when the device is offline
+          if (!isDocumentVisible() || !isOnline()) {
             await new Promise(continueResolve => {
               continueLoop = continueResolve
             })

src/core/queryCache.ts

@@ -3,7 +3,9 @@ import {
   deepIncludes,
   functionalUpdate,
   getQueryArgs,
+  isDocumentVisible,
   isObject,
+  isOnline,
   isServer,
 } from './utils'
 import { getDefaultedQueryConfig } from './config'
@@ -344,3 +346,21 @@ export const queryCaches = [defaultQueryCache]
 export function makeQueryCache(config?: QueryCacheConfig) {
   return new QueryCache(config)
 }
+
+export function onVisibilityOrOnlineChange(isOnlineChange: boolean) {
+  if (isDocumentVisible() && isOnline()) {
+    queryCaches.forEach(queryCache => {
+      queryCache.getQueries(query => {
+        // Trigger query hooks
+        if (isOnlineChange) {
+          query.onOnline()
+        } else {
+          query.onWindowFocus()
+        }
+
+        // Continue any paused queries
+        query.continue()
+      })
+    })
+  }
+}

src/core/setFocusHandler.ts

@@ -1,49 +1,29 @@
-import { isOnline, isDocumentVisible, Console, isServer } from './utils'
-import { queryCaches } from './queryCache'
-
-type FocusHandler = () => void
-
-const visibilityChangeEvent = 'visibilitychange'
-const focusEvent = 'focus'
-
-const onWindowFocus: FocusHandler = () => {
-  if (isDocumentVisible() && isOnline()) {
-    queryCaches.forEach(queryCache => {
-      // Continue any paused queries
-      queryCache.getQueries(query => {
-        query.continue()
-      })
-
-      // Invalidate queries which should refetch on window focus
-      queryCache
-        .invalidateQueries(query => query.shouldRefetchOnWindowFocus())
-        .catch(Console.error)
-    })
-  }
-}
+import { isServer } from './utils'
+import { onVisibilityOrOnlineChange } from './queryCache'
 
 let removePreviousHandler: (() => void) | void
 
-export function setFocusHandler(callback: (callback: FocusHandler) => void) {
+export function setFocusHandler(callback: (handler: () => void) => void) {
   // Unsub the old watcher
   if (removePreviousHandler) {
     removePreviousHandler()
   }
   // Sub the new watcher
-  removePreviousHandler = callback(onWindowFocus)
+  removePreviousHandler = callback(() => onVisibilityOrOnlineChange(false))
 }
 
-setFocusHandler((handleFocus: FocusHandler) => {
+setFocusHandler(handleFocus => {
+  if (isServer || !window?.addEventListener) {
+    return
+  }
+
   // Listen to visibillitychange and focus
-  if (!isServer && window?.addEventListener) {
-    window.addEventListener(visibilityChangeEvent, handleFocus, false)
-    window.addEventListener(focusEvent, handleFocus, false)
+  window.addEventListener('visibilitychange', handleFocus, false)
+  window.addEventListener('focus', handleFocus, false)
 
-    return () => {
-      // Be sure to unsubscribe if a new handler is set
-      window.removeEventListener(visibilityChangeEvent, handleFocus)
-      window.removeEventListener(focusEvent, handleFocus)
-    }
+  return () => {
+    // Be sure to unsubscribe if a new handler is set
+    window.removeEventListener('visibilitychange', handleFocus)
+    window.removeEventListener('focus', handleFocus)
   }
-  return
 })

src/core/setOnlineHandler.ts

@@ -0,0 +1,27 @@
+import { isServer } from './utils'
+import { onVisibilityOrOnlineChange } from './queryCache'
+
+let removePreviousHandler: (() => void) | void
+
+export function setOnlineHandler(callback: (handler: () => void) => void) {
+  // Unsub the old watcher
+  if (removePreviousHandler) {
+    removePreviousHandler()
+  }
+  // Sub the new watcher
+  removePreviousHandler = callback(() => onVisibilityOrOnlineChange(true))
+}
+
+setOnlineHandler(handleOnline => {
+  if (isServer || !window?.addEventListener) {
+    return
+  }
+
+  // Listen to online
+  window.addEventListener('online', handleOnline, false)
+
+  return () => {
+    // Be sure to unsubscribe if a new handler is set
+    window.removeEventListener('online', handleOnline)
+  }
+})

src/core/tests/queryCache.test.tsx

@@ -3,6 +3,7 @@ import {
   queryKey,
   mockVisibilityState,
   mockConsoleError,
+  mockNavigatorOnLine,
 } from '../../react/tests/utils'
 import { makeQueryCache, queryCache as defaultQueryCache } from '..'
 import { isCancelledError, isError } from '../utils'
@@ -435,6 +436,54 @@ describe('queryCache', () => {
       expect(result).toBe('data3')
     })
 
+    it('should continue retry after reconnect and resolve all promises', async () => {
+      const key = queryKey()
+
+      mockNavigatorOnLine(false)
+
+      let count = 0
+      let result
+
+      const promise = defaultQueryCache.prefetchQuery(
+        key,
+        async () => {
+          count++
+
+          if (count === 3) {
+            return `data${count}`
+          }
+
+          throw new Error(`error${count}`)
+        },
+        {
+          retry: 3,
+          retryDelay: 1,
+        }
+      )
+
+      promise.then(data => {
+        result = data
+      })
+
+      // Check if we do not have a result
+      expect(result).toBeUndefined()
+
+      // Check if the query is really paused
+      await sleep(50)
+      expect(result).toBeUndefined()
+
+      // Reset navigator to original value
+      mockNavigatorOnLine(true)
+      window.dispatchEvent(new Event('online'))
+
+      // There should not be a result yet
+      expect(result).toBeUndefined()
+
+      // By now we should have a value
+      await sleep(50)
+      expect(result).toBe('data3')
+    })
+
     it('should throw a CancelledError when a paused query is cancelled', async () => {
       const key = queryKey()