feat: add ability to manually control the online and focus state

Author: boschni

docs/src/manifests/manifest.json

@@ -367,6 +367,16 @@
           "path": "/reference/useQueryErrorResetBoundary",
           "editUrl": "/reference/useQueryErrorResetBoundary.md"
         },
+        {
+          "title": "focusManager",
+          "path": "/reference/focusManager",
+          "editUrl": "/reference/focusManager.md"
+        },
+        {
+          "title": "onlineManager",
+          "path": "/reference/onlineManager",
+          "editUrl": "/reference/onlineManager.md"
+        },
         {
           "title": "setLogger",
           "path": "/reference/setLogger",

docs/src/pages/guides/window-focus-refetching.md

@@ -30,10 +30,10 @@ useQuery('todos', fetchTodos, { refetchOnWindowFocus: false })
 
 ## Custom Window Focus Event
 
-In rare circumstances, you may want to manage your own window focus events that trigger React Query to revalidate. To do this, React Query provides a `focusManager.setHandler` function that supplies you the callback that should be fired when the window is focused and allows you to set up your own events. When calling `focusManager.setHandler`, the previously set handler is removed (which in most cases will be the default handler) and your new handler is used instead. For example, this is the default handler:
+In rare circumstances, you may want to manage your own window focus events that trigger React Query to revalidate. To do this, React Query provides a `focusManager.setEventListener` function that supplies you the callback that should be fired when the window is focused and allows you to set up your own events. When calling `focusManager.setEventListener`, the previously set handler is removed (which in most cases will be the default handler) and your new handler is used instead. For example, this is the default handler:
 
 ```js
-focusManager.setHandler(handleFocus => {
+focusManager.setEventListener(handleFocus => {
   // Listen to visibillitychange and focus
   if (typeof window !== 'undefined' && window.addEventListener) {
     window.addEventListener('visibilitychange', handleFocus, false)
@@ -56,7 +56,7 @@ A great use-case for replacing the focus handler is that of iframe events. Ifram
 import { focusManager } from 'react-query'
 import onWindowFocus from './onWindowFocus' // The gist above
 
-focusManager.setHandler(onWindowFocus) // Boom!
+focusManager.setEventListener(onWindowFocus) // Boom!
 ```
 
 ## Managing Focus in React Native
@@ -67,7 +67,7 @@ Instead of event listeners on `window`, React Native provides focus information
 import { focusManager } from 'react-query'
 import { AppState } from 'react-native'
 
-focusManager.setHandler(handleFocus => {
+focusManager.setEventListener(handleFocus => {
   const handleAppStateChange = appState => {
     if (appState === 'active') {
       handleFocus()
@@ -77,3 +77,15 @@ focusManager.setHandler(handleFocus => {
   return () => AppState.removeEventListener('change', handleAppStateChange)
 })
 ```
+
+## Managing focus state
+
+```js
+import { focusManager } from 'react-query'
+
+// Override the default focus state
+focusManager.setFocused(true)
+
+// Fallback to the default focus check
+focusManager.setFocused(undefined)
+```

docs/src/pages/reference/focusManager.md

@@ -0,0 +1,65 @@
+---
+id: FocusManager
+title: FocusManager
+---
+
+The `FocusManager` manages the focus state within React Query.
+
+It can be used to change the default event listeners or to manually change the focus state.
+
+Its available methods are:
+
+- [`setEventListener`](#focusmanagerseteventlistener)
+- [`setFocused`](#focusmanagersetfocused)
+- [`isFocused`](#focusmanagerisfocused)
+
+## `focusManager.setEventListener`
+
+`setEventListener` can be used to set a custom event listener:
+
+```js
+import { focusManager } from 'react-query'
+
+focusManager.setEventListener(handleFocus => {
+  // Listen to visibillitychange and focus
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    window.addEventListener('visibilitychange', handleFocus, false)
+    window.addEventListener('focus', handleFocus, false)
+  }
+
+  return () => {
+    // Be sure to unsubscribe if a new handler is set
+    window.removeEventListener('visibilitychange', handleFocus)
+    window.removeEventListener('focus', handleFocus)
+  }
+})
+```
+
+## `focusManager.setFocused`
+
+`setFocsued` can be used to manually set the focus state. Set `undefined` to fallback to the default focus check.
+
+```js
+import { focusManager } from 'react-query'
+
+// Set focused
+focusManager.setFocused(true)
+
+// Set unfocused
+focusManager.setFocused(false)
+
+// Fallback to the default focus check
+focusManager.setFocused(undefined)
+```
+
+**Options**
+
+- `focused: boolean | undefined`
+
+## `focusManager.isFocused`
+
+`isFocused` can be used to get the current focus state.
+
+```js
+const isFocused = focusManager.isFocused()
+```

docs/src/pages/reference/onlineManager.md

@@ -0,0 +1,65 @@
+---
+id: OnlineManager
+title: OnlineManager
+---
+
+The `OnlineManager` manages the online state within React Query.
+
+It can be used to change the default event listeners or to manually change the online state.
+
+Its available methods are:
+
+- [`setEventListener`](#onlinemanagerseteventlistener)
+- [`setOnline`](#onlinemanagersetonline)
+- [`isOnline`](#onlinemanagerisonline)
+
+## `onlineManager.setEventListener`
+
+`setEventListener` can be used to set a custom event listener:
+
+```js
+import { onlineManager } from 'react-query'
+
+onlineManager.setEventListener(handleOnline => {
+  // Listen to visibillitychange and online
+  if (typeof window !== 'undefined' && window.addEventListener) {
+    window.addEventListener('visibilitychange', handleOnline, false)
+    window.addEventListener('online', handleOnline, false)
+  }
+
+  return () => {
+    // Be sure to unsubscribe if a new handler is set
+    window.removeEventListener('visibilitychange', handleOnline)
+    window.removeEventListener('online', handleOnline)
+  }
+})
+```
+
+## `onlineManager.setOnline`
+
+`setOnline` can be used to manually set the online state. Set `undefined` to fallback to the default online check.
+
+```js
+import { onlineManager } from 'react-query'
+
+// Set to online
+onlineManager.setOnline(true)
+
+// Set to offline
+onlineManager.setOnline(false)
+
+// Fallback to the default online check
+onlineManager.setOnline(undefined)
+```
+
+**Options**
+
+- `online: boolean | undefined`
+
+## `onlineManager.isOnline`
+
+`isOnline` can be used to get the current online state.
+
+```js
+const isOnline = onlineManager.isOnline()
+```

src/core/focusManager.ts

@@ -2,19 +2,20 @@ import { Subscribable } from './subscribable'
 import { isServer } from './utils'
 
 class FocusManager extends Subscribable {
-  private removeHandler?: () => void
+  private focused?: boolean
+  private removeEventListener?: () => void
 
   protected onSubscribe(): void {
-    if (!this.removeHandler) {
-      this.setDefaultHandler()
+    if (!this.removeEventListener) {
+      this.setDefaultEventListener()
     }
   }
 
-  setHandler(init: (onFocus: () => void) => () => void): void {
-    if (this.removeHandler) {
-      this.removeHandler()
+  setEventListener(setup: (onFocus: () => void) => () => void): void {
+    if (this.removeEventListener) {
+      this.removeEventListener()
     }
-    this.removeHandler = init(() => {
+    this.removeEventListener = setup(() => {
       this.onFocus()
     })
   }
@@ -25,7 +26,19 @@ class FocusManager extends Subscribable {
     })
   }
 
+  setFocused(focused: boolean | undefined): void {
+    this.focused = focused
+
+    if (focused) {
+      this.onFocus()
+    }
+  }
+
   isFocused(): boolean {
+    if (typeof this.focused === 'boolean') {
+      return this.focused
+    }
+
     // document global can be unavailable in react native
     if (typeof document === 'undefined') {
       return true
@@ -36,9 +49,9 @@ class FocusManager extends Subscribable {
     )
   }
 
-  private setDefaultHandler() {
+  private setDefaultEventListener() {
     if (!isServer && window?.addEventListener) {
-      this.setHandler(onFocus => {
+      this.setEventListener(onFocus => {
         // Listen to visibillitychange and focus
         window.addEventListener('visibilitychange', onFocus, false)
         window.addEventListener('focus', onFocus, false)

src/core/onlineManager.ts

@@ -2,19 +2,20 @@ import { Subscribable } from './subscribable'
 import { isServer } from './utils'
 
 class OnlineManager extends Subscribable {
-  private removeHandler?: () => void
+  private online?: boolean
+  private removeEventListener?: () => void
 
   protected onSubscribe(): void {
-    if (!this.removeHandler) {
-      this.setDefaultHandler()
+    if (!this.removeEventListener) {
+      this.setDefaultEventListener()
     }
   }
 
-  setHandler(init: (onOnline: () => void) => () => void): void {
-    if (this.removeHandler) {
-      this.removeHandler()
+  setEventListener(setup: (onOnline: () => void) => () => void): void {
+    if (this.removeEventListener) {
+      this.removeEventListener()
     }
-    this.removeHandler = init(() => {
+    this.removeEventListener = setup(() => {
       this.onOnline()
     })
   }
@@ -25,13 +26,25 @@ class OnlineManager extends Subscribable {
     })
   }
 
+  setOnline(online: boolean | undefined): void {
+    this.online = online
+
+    if (online) {
+      this.onOnline()
+    }
+  }
+
   isOnline(): boolean {
+    if (typeof this.online === 'boolean') {
+      return this.online
+    }
+
     return navigator.onLine === undefined || navigator.onLine
   }
 
-  private setDefaultHandler() {
+  private setDefaultEventListener() {
     if (!isServer && window?.addEventListener) {
-      this.setHandler(onOnline => {
+      this.setEventListener(onOnline => {
         // Listen to online
         window.addEventListener('online', onOnline, false)
 

src/core/tests/queryCache.test.tsx

@@ -3,7 +3,6 @@ import {
   queryKey,
   mockVisibilityState,
   mockConsoleError,
-  mockNavigatorOnLine,
   expectType,
 } from '../../react/tests/utils'
 import {
@@ -12,6 +11,7 @@ import {
   QueryObserver,
   isCancelledError,
   isError,
+  onlineManager,
 } from '../..'
 import { QueryObserverResult } from '../types'
 import { QueriesObserver } from '../queriesObserver'
@@ -1172,7 +1172,7 @@ describe('queryCache', () => {
     it('should continue retry after reconnect and resolve all promises', async () => {
       const key = queryKey()
 
-      mockNavigatorOnLine(false)
+      onlineManager.setOnline(false)
 
       let count = 0
       let result
@@ -1206,8 +1206,7 @@ describe('queryCache', () => {
       expect(result).toBeUndefined()
 
       // Reset navigator to original value
-      mockNavigatorOnLine(true)
-      window.dispatchEvent(new Event('online'))
+      onlineManager.setOnline(true)
 
       // There should not be a result yet
       expect(result).toBeUndefined()