Implement refetchOnFocus, refetchOnReconnect (#90)

Co-authored-by: Lenz Weber <[email protected]>

Author: msutkowski

docs/api/createApi.md

@@ -21,6 +21,8 @@ The main point where you will define a service to use in your application.
   serializeQueryArgs?: SerializeQueryArgs<InternalQueryArgs>;
   keepUnusedDataFor?: number; // value is in seconds
   refetchOnMountOrArgChange?: boolean | number; // value is in seconds
+  refetchOnFocus?: boolean;
+  refetchOnReconnect?: boolean;
 ```
 
 ### `baseQuery`
@@ -216,12 +218,36 @@ Defaults to `false`. This setting allows you to control whether RTK Query will o
 - `true` - Will always refetch when a new subscriber to a query is added. Behaves the same as calling the `refetch` callback or passing `forceRefetch: true` in the action creator.
 - `number` - **Value is in seconds**. If a number is provided and there is an existing query in the cache, it will compare the current time vs the last fulfilled timestamp, and only refetch if enough time has elapsed.
 
-If you specify this option as well as with `skip: true`, this **will not be evaluated** until `skip` is false.
+If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
 
 :::note
 You can set this globally in `createApi`, but you can also override the default value and have more granular control by passing `refetchOnMountOrArgChange` to each individual hook call or when dispatching the [`initiate`](#initiate) action.
 :::
 
+### `refetchOnFocus`
+
+Defaults to `false`. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after the application window regains focus.
+
+If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
+
+:::note
+You can set this globally in `createApi`, but you can also override the default value and have more granular control by passing `refetchOnFocus` to each individual hook call or when dispatching the [`initiate`](#initiate) action.
+
+If you specify `track: false` when manually dispatching queries, RTK Query will not be able to automatically refetch for you.
+:::
+
+### `refetchOnReconnect`
+
+Defaults to `false`. This setting allows you to control whether RTK Query will try to refetch all subscribed queries after regaining a network connection.
+
+If you specify this option alongside `skip: true`, this **will not be evaluated** until `skip` is false.
+
+:::note
+You can set this globally in `createApi`, but you can also override the default value and have more granular control by passing `refetchOnReconnect` to each individual hook call or when dispatching the [`initiate`](#initiate) action.
+
+If you specify `track: false` when manually dispatching queries, RTK Query will not be able to automatically refetch for you.
+:::
+
 ## Return value
 
 - [`reducerPath`](#reducerpath)

docs/api/setupListeners.md

@@ -0,0 +1,70 @@
+---
+id: setupListeners
+title: setupListeners
+sidebar_label: setupListeners
+hide_title: true
+hide_table_of_contents: false
+---
+
+# `setupListeners`
+
+A utility used to enable `refetchOnMount` and `refetchOnReconnect` behaviors. It requires the `dispatch` method from your store. Calling `setupListeners(store.dispatch)` will configure listeners with the recommended defaults, but you have the optional of providing a callback for more granular control.
+
+```ts title="setupListeners default configuration"
+let initialized = false;
+export function setupListeners(
+  dispatch: ThunkDispatch<any, any, any>,
+  customHandler?: (
+    dispatch: ThunkDispatch<any, any, any>,
+    actions: {
+      onFocus: typeof onFocus;
+      onFocusLost: typeof onFocusLost;
+      onOnline: typeof onOnline;
+      onOffline: typeof onOffline;
+    }
+  ) => () => void
+) {
+  function defaultHandler() {
+    const handleFocus = () => dispatch(onFocus());
+    const handleFocusLost = () => dispatch(onFocusLost());
+    const handleOnline = () => dispatch(onOnline());
+    const handleOffline = () => dispatch(onOffline());
+    const handleVisibilityChange = () => {
+      if (window.document.visibilityState === 'visible') {
+        handleFocus();
+      } else {
+        handleFocusLost();
+      }
+    };
+
+    if (!initialized) {
+      if (typeof window !== 'undefined' && window.addEventListener) {
+        // Handle focus events
+        window.addEventListener('visibilitychange', handleVisibilityChange, false);
+        window.addEventListener('focus', handleFocus, false);
+
+        // Handle connection events
+        window.addEventListener('online', handleOnline, false);
+        window.addEventListener('offline', handleOffline, false);
+        initialized = true;
+      }
+    }
+    const unsubscribe = () => {
+      window.removeEventListener('focus', handleFocus);
+      window.removeEventListener('visibilitychange', handleVisibilityChange);
+      window.removeEventListener('online', handleOnline);
+      window.removeEventListener('offline', handleOffline);
+      initialized = false;
+    };
+    return unsubscribe;
+  }
+
+  return customHandler ? customHandler(dispatch, { onFocus, onFocusLost, onOffline, onOnline }) : defaultHandler();
+}
+```
+
+If you notice, `onFocus`, `onFocusLost`, `onOffline`, `onOnline` are all actions that are provided to the callback. Additionally, these action are made available to `api.internalActions` and are able to be used by dispatching them like this:
+
+```ts title="Manual onFocus event"
+dispatch(api.internalActions.onFocus())`
+```

docs/concepts/queries.md

@@ -21,9 +21,13 @@ Hooks are automatically generated based on the name of the `endpoint` in the ser
 
 #### Query Hook Options
 
-- [pollingInterval?](./polling) - Defaults to `0`
-- [refetchOnMountOrArgChange?](../api/createApi#refetchOnMountOrArgChange) - Defaults to `false`. Will override any value that was specified in `createApi`.
-- [skip?](./conditional-fetching) - Defaults to `false`
+- [skip](./conditional-fetching) - Defaults to `false`
+- [pollingInterval](./polling) - Defaults to `0` _(off)_
+- [refetchOnMountOrArgChange](../api/createApi#refetchonmountorargchange) - Defaults to `false`
+- [refetchOnFocus](../api/createApi#refetchonfocus) - Defaults to `false`
+- [refetchOnReconnect](../api/createApi#refetchonreconnect) - Defaults to `false`
+
+> All `refetch`-related options will override the defaults you may have set in [createApi](../api/createApi)
 
 Here is an example of a `PostDetail` component:
 

docs/introduction/getting-started.md

@@ -69,7 +69,7 @@ With RTK Query, you usually define your entire API definition in one place. This
 An RTK service generates a "slice reducer" that should be included in the Redux root reducer, and a custom middleware that handles the data fetching. Both need to be added to the Redux store.
 
 ```ts title="src/store.ts"
-import { configureStore } from '@reduxjs/toolkit';
+import { configureStore, setupListeners } from '@reduxjs/toolkit';
 import { pokemonApi } from './services/pokemon';
 
 export const store = configureStore({
@@ -85,6 +85,10 @@ export const store = configureStore({
   middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(pokemonApi.middleware),
   // highlight-end
 });
+
+// optional, but required for refetchOnFocus/refetchOnReconnect behaviors
+// see `setupListeners` docs - takes an optional callback as the 2nd arg for customization
+setupListeners(store.dispatch);
 ```
 
 ### Wrap your application with the `Provider`

examples/react/src/app/services/times.ts

@@ -14,6 +14,8 @@ export const timeApi = createApi({
       provides: (_, id) => [{ type: 'Time', id }],
     }),
   }),
+  refetchOnReconnect: true,
+  refetchOnMountOrArgChange: 10,
 });
 
 export const { usePrefetch: usePrefetchTime, useGetTimeQuery } = timeApi;

examples/react/src/app/store.ts

@@ -6,6 +6,7 @@ import { timeApi } from './services/times';
 import polling from '../features/polling/pollingSlice';
 import { splitApi } from './services/split';
 import auth from '../features/auth/authSlice';
+import { setupListeners } from '@rtk-incubator/rtk-query';
 
 export const createStore = (options?: ConfigureStoreOptions['preloadedState'] | undefined) =>
   configureStore({
@@ -23,6 +24,7 @@ export const createStore = (options?: ConfigureStoreOptions['preloadedState'] |
   });
 
 export const store = createStore();
+setupListeners(store.dispatch);
 
 export type AppDispatch = typeof store.dispatch;
 export const useAppDispatch = () => useDispatch<AppDispatch>();

examples/react/src/features/time/TimeList.tsx

@@ -80,7 +80,8 @@ const TimeDisplay = ({ offset, label }: { offset: string; label: string }) => {
   const [pollingInterval, setPollingInterval] = React.useState(0);
   const { data, refetch, isFetching } = useGetTimeQuery(offset, {
     pollingInterval: canPoll ? pollingInterval : 0,
-    refetchOnMountOrArgChange: 10,
+    refetchOnReconnect: false,
+    refetchOnFocus: true,
   });
 
   return (

src/ApiProvider.tsx

@@ -1,6 +1,7 @@
 import { configureStore } from '@reduxjs/toolkit';
 import React from 'react';
 import { Provider } from 'react-redux';
+import { setupListeners } from './setupListeners';
 import { Api } from './apiTypes';
 
 /**
@@ -9,7 +10,11 @@ import { Api } from './apiTypes';
  * conflict with each other - please use the traditional redux setup
  * in that case.
  */
-export function ApiProvider<A extends Api<any, {}, any, string>>(props: { children: any; api: A }) {
+export function ApiProvider<A extends Api<any, {}, any, string>>(props: {
+  children: any;
+  api: A;
+  setupListeners?: Parameters<typeof setupListeners>[1];
+}) {
   const [store] = React.useState(() =>
     configureStore({
       reducer: {
@@ -18,6 +23,8 @@ export function ApiProvider<A extends Api<any, {}, any, string>>(props: { childr
       middleware: (gDM) => gDM().concat(props.api.middleware),
     })
   );
+  // Adds the event listeners for online/offline/focus/etc
+  setupListeners(store.dispatch, props.setupListeners);
 
   return <Provider store={store}>{props.children}</Provider>;
 }

src/apiState.ts

@@ -14,6 +14,12 @@ export type QueryCacheKey = string & { _type: 'queryCacheKey' };
 export type QuerySubstateIdentifier = { queryCacheKey: QueryCacheKey };
 export type MutationSubstateIdentifier = { requestId: string };
 
+export type RefetchConfigOptions = {
+  refetchOnMountOrArgChange: boolean | number;
+  refetchOnReconnect: boolean;
+  refetchOnFocus: boolean;
+};
+
 export enum QueryStatus {
   uninitialized = 'uninitialized',
   pending = 'pending',
@@ -61,7 +67,11 @@ export function getRequestStatusFlags(status: QueryStatus): RequestStatusFlags {
   } as any;
 }
 
-export type SubscriptionOptions = { pollingInterval?: number };
+export type SubscriptionOptions = {
+  pollingInterval?: number;
+  refetchOnReconnect?: boolean;
+  refetchOnFocus?: boolean;
+};
 export type Subscribers = { [requestId: string]: SubscriptionOptions };
 export type QueryKeys<Definitions extends EndpointDefinitions> = {
   [K in keyof Definitions]: Definitions[K] extends QueryDefinition<any, any, any, any> ? K : never;
@@ -144,6 +154,7 @@ export type CombinedState<D extends EndpointDefinitions, E extends string> = {
   mutations: MutationState<D>;
   provided: InvalidationState<E>;
   subscriptions: SubscriptionState;
+  config: ConfigState;
 };
 
 export type InvalidationState<EntityTypes extends string> = {
@@ -161,6 +172,15 @@ export type SubscriptionState = {
   [queryCacheKey: string]: Subscribers | undefined;
 };
 
+export type ConfigState = {
+  online: boolean;
+  focused: boolean;
+} & ModifiableConfigState;
+
+export type ModifiableConfigState = {
+  keepUnusedDataFor: number;
+} & RefetchConfigOptions;
+
 export type MutationState<D extends EndpointDefinitions> = {
   [requestId: string]: MutationSubState<D[string]> | undefined;
 };

src/apiTypes.ts

@@ -16,6 +16,7 @@ import { UnionToIntersection } from './tsHelpers';
 import { TS41Hooks } from './ts41Types';
 import './buildSelectors';
 import { SliceActions } from './buildSlice';
+import { onFocus, onFocusLost, onOffline, onOnline } from './setupListeners';
 
 type UnwrapPromise<T> = T extends PromiseLike<infer V> ? V : T;
 type MaybePromise<T> = T | PromiseLike<T>;
@@ -113,4 +114,17 @@ export type ApiWithInjectedEndpoints<
 
 export type InternalActions = SliceActions & {
   prefetchThunk: (endpointName: any, arg: any, options: PrefetchOptions) => ThunkAction<void, any, any, AnyAction>;
+} & {
+  /**
+   * Will cause the RTK Query middleware to trigger any refetchOnReconnect-related behavior
+   * @link https://rtk-query-docs.netlify.app/api/setupListeners
+   */
+  onOnline: typeof onOnline;
+  onOffline: typeof onOffline;
+  /**
+   * Will cause the RTK Query middleware to trigger any refetchOnFocus-related behavior
+   * @link https://rtk-query-docs.netlify.app/api/setupListeners
+   */
+  onFocus: typeof onFocus;
+  onFocusLost: typeof onFocusLost;
 };

src/buildActionMaps.ts

@@ -23,9 +23,8 @@ declare module './apiTypes' {
 
 export interface StartQueryActionCreatorOptions {
   subscribe?: boolean;
-  forceRefetch?: boolean;
+  forceRefetch?: boolean | number;
   subscriptionOptions?: SubscriptionOptions;
-  refetchOnMountOrArgChange?: boolean | number;
 }
 
 type StartQueryActionCreator<D extends QueryDefinition<any, any, any, any, any>> = (
@@ -81,14 +80,13 @@ export function buildActionMaps<Definitions extends EndpointDefinitions, Interna
   function buildQueryAction(endpoint: string, definition: QueryDefinition<any, any, any, any>) {
     const queryAction: StartQueryActionCreator<any> = (
       arg,
-      { subscribe = true, forceRefetch = false, refetchOnMountOrArgChange = false, subscriptionOptions } = {}
+      { subscribe = true, forceRefetch, subscriptionOptions } = {}
     ) => (dispatch, getState) => {
       const internalQueryArgs = definition.query(arg);
       const queryCacheKey = serializeQueryArgs({ queryArgs: arg, internalQueryArgs, endpoint });
       const thunk = queryThunk({
         subscribe,
         forceRefetch,
-        refetchOnMountOrArgChange,
         subscriptionOptions,
         endpoint,
         originalArgs: arg,

src/buildHooks.ts

@@ -118,13 +118,15 @@ export function buildHooks<Definitions extends EndpointDefinitions>({
   }
 
   function buildQueryHook(name: string): QueryHook<any> {
-    return (arg: any, { refetchOnMountOrArgChange = false, skip = false, pollingInterval = 0 } = {}) => {
+    return (
+      arg: any,
+      { refetchOnReconnect, refetchOnFocus, refetchOnMountOrArgChange, skip = false, pollingInterval = 0 } = {}
+    ) => {
       const { select, initiate } = api.endpoints[name] as ApiEndpointQuery<
         QueryDefinition<any, any, any, any, any>,
         Definitions
       >;
       const dispatch = useDispatch<ThunkDispatch<any, any, AnyAction>>();
-
       const stableArg = useShallowStableValue(arg);
 
       const lastData = useRef<ResultTypeFrom<Definitions[string]> | undefined>();
@@ -141,15 +143,27 @@ export function buildHooks<Definitions extends EndpointDefinitions>({
         const lastPromise = promiseRef.current;
         if (lastPromise && lastPromise.arg === stableArg) {
           // arg did not change, but options did probably, update them
-          lastPromise.updateSubscriptionOptions({ pollingInterval });
+          lastPromise.updateSubscriptionOptions({ pollingInterval, refetchOnReconnect, refetchOnFocus });
         } else {
           if (lastPromise) lastPromise.unsubscribe();
           const promise = dispatch(
-            initiate(stableArg, { subscriptionOptions: { pollingInterval }, refetchOnMountOrArgChange })
+            initiate(stableArg, {
+              subscriptionOptions: { pollingInterval, refetchOnReconnect, refetchOnFocus },
+              forceRefetch: refetchOnMountOrArgChange,
+            })
           );
           promiseRef.current = promise;
         }
-      }, [stableArg, dispatch, skip, pollingInterval, refetchOnMountOrArgChange, initiate]);
+      }, [
+        stableArg,
+        dispatch,
+        skip,
+        pollingInterval,
+        refetchOnMountOrArgChange,
+        refetchOnFocus,
+        refetchOnReconnect,
+        initiate,
+      ]);
 
       useEffect(() => {
         return () => void promiseRef.current?.unsubscribe();