feat(query): functions for refetchOn options (#3518)

* feat(query): functions for refetchOn options

make refetchOn mount/reconnect/windowFocus also accept a function that gets evaluated on the fly with the current data and query

* feat(query): functions for refetchOn options

docs

* feat(query): functions for refetchOn options

tests

* feat(query): functions for refetchOn options

only pass query to the functions as they don't lean towards error or data

* feat(query): functions for refetchOn options

fix docs

* feat(query): functions for refetchOn options

fix docs

Author: TkDodo

docs/src/pages/reference/useQuery.md

@@ -110,24 +110,27 @@ const result = useQuery({
 - `refetchIntervalInBackground: boolean`
   - Optional
   - If set to `true`, queries that are set to continuously refetch with a `refetchInterval` will continue to refetch while their tab/window is in the background
-- `refetchOnMount: boolean | "always"`
+- `refetchOnMount: boolean | "always" | ((query: Query) => boolean | "always")`
   - Optional
   - Defaults to `true`
   - If set to `true`, the query will refetch on mount if the data is stale.
   - If set to `false`, the query will not refetch on mount.
   - If set to `"always"`, the query will always refetch on mount.
-- `refetchOnWindowFocus: boolean | "always"`
+  - If set to a function, the function will be executed with the query to compute the value
+- `refetchOnWindowFocus: boolean | "always" | ((query: Query) => boolean | "always")`
   - Optional
   - Defaults to `true`
   - If set to `true`, the query will refetch on window focus if the data is stale.
   - If set to `false`, the query will not refetch on window focus.
   - If set to `"always"`, the query will always refetch on window focus.
-- `refetchOnReconnect: boolean | "always"`
+  - If set to a function, the function will be executed with the query to compute the value
+- `refetchOnReconnect: boolean | "always" | ((query: Query) => boolean | "always")`
   - Optional
   - Defaults to `true`
   - If set to `true`, the query will refetch on reconnect if the data is stale.
   - If set to `false`, the query will not refetch on reconnect.
   - If set to `"always"`, the query will always refetch on reconnect.
+  - If set to a function, the function will be executed with the query to compute the value
 - `notifyOnChangeProps: string[] | "tracked"`
   - Optional
   - If set, the component will only re-render if any of the listed properties change.

src/core/queryObserver.ts

@@ -122,11 +122,19 @@ export class QueryObserver<
   }
 
   shouldFetchOnReconnect(): boolean {
-    return shouldFetchOnReconnect(this.currentQuery, this.options)
+    return shouldFetchOn(
+      this.currentQuery,
+      this.options,
+      this.options.refetchOnReconnect
+    )
   }
 
   shouldFetchOnWindowFocus(): boolean {
-    return shouldFetchOnWindowFocus(this.currentQuery, this.options)
+    return shouldFetchOn(
+      this.currentQuery,
+      this.options,
+      this.options.refetchOnWindowFocus
+    )
   }
 
   destroy(): void {
@@ -746,47 +754,30 @@ function shouldLoadOnMount(
   )
 }
 
-function shouldRefetchOnMount(
-  query: Query<any, any, any, any>,
-  options: QueryObserverOptions<any, any, any, any>
-): boolean {
-  return (
-    options.enabled !== false &&
-    query.state.dataUpdatedAt > 0 &&
-    (options.refetchOnMount === 'always' ||
-      (options.refetchOnMount !== false && isStale(query, options)))
-  )
-}
-
 function shouldFetchOnMount(
   query: Query<any, any, any, any>,
   options: QueryObserverOptions<any, any, any, any, any>
 ): boolean {
   return (
-    shouldLoadOnMount(query, options) || shouldRefetchOnMount(query, options)
+    shouldLoadOnMount(query, options) ||
+    (query.state.dataUpdatedAt > 0 &&
+      shouldFetchOn(query, options, options.refetchOnMount))
   )
 }
 
-function shouldFetchOnReconnect(
+function shouldFetchOn(
   query: Query<any, any, any, any>,
-  options: QueryObserverOptions<any, any, any, any, any>
-): boolean {
-  return (
-    options.enabled !== false &&
-    (options.refetchOnReconnect === 'always' ||
-      (options.refetchOnReconnect !== false && isStale(query, options)))
-  )
-}
+  options: QueryObserverOptions<any, any, any, any, any>,
+  field: typeof options['refetchOnMount'] &
+    typeof options['refetchOnWindowFocus'] &
+    typeof options['refetchOnReconnect']
+) {
+  if (options.enabled !== false) {
+    const value = typeof field === 'function' ? field(query) : field
 
-function shouldFetchOnWindowFocus(
-  query: Query<any, any, any, any>,
-  options: QueryObserverOptions<any, any, any, any, any>
-): boolean {
-  return (
-    options.enabled !== false &&
-    (options.refetchOnWindowFocus === 'always' ||
-      (options.refetchOnWindowFocus !== false && isStale(query, options)))
-  )
+    return value === 'always' || (value !== false && isStale(query, options))
+  }
+  return false
 }
 
 function shouldFetchOptionally(

src/core/types.ts

@@ -135,23 +135,41 @@ export interface QueryObserverOptions<
    * If set to `true`, the query will refetch on window focus if the data is stale.
    * If set to `false`, the query will not refetch on window focus.
    * If set to `'always'`, the query will always refetch on window focus.
+   * If set to a function, the function will be executed with the latest data and query to compute the value.
    * Defaults to `true`.
    */
-  refetchOnWindowFocus?: boolean | 'always'
+  refetchOnWindowFocus?:
+    | boolean
+    | 'always'
+    | ((
+        query: Query<TQueryFnData, TError, TQueryData, TQueryKey>
+      ) => boolean | 'always')
   /**
    * If set to `true`, the query will refetch on reconnect if the data is stale.
    * If set to `false`, the query will not refetch on reconnect.
    * If set to `'always'`, the query will always refetch on reconnect.
+   * If set to a function, the function will be executed with the latest data and query to compute the value.
    * Defaults to `true`.
    */
-  refetchOnReconnect?: boolean | 'always'
+  refetchOnReconnect?:
+    | boolean
+    | 'always'
+    | ((
+        query: Query<TQueryFnData, TError, TQueryData, TQueryKey>
+      ) => boolean | 'always')
   /**
    * If set to `true`, the query will refetch on mount if the data is stale.
    * If set to `false`, will disable additional instances of a query to trigger background refetches.
    * If set to `'always'`, the query will always refetch on mount.
+   * If set to a function, the function will be executed with the latest data and query to compute the value
    * Defaults to `true`.
    */
-  refetchOnMount?: boolean | 'always'
+  refetchOnMount?:
+    | boolean
+    | 'always'
+    | ((
+        query: Query<TQueryFnData, TError, TQueryData, TQueryKey>
+      ) => boolean | 'always')
   /**
    * If set to `false`, the query will not be retried on mount if it contains an error.
    * Defaults to `true`.

src/react/tests/useQuery.test.tsx

@@ -2401,6 +2401,35 @@ describe('useQuery', () => {
     expect(states[1]).toMatchObject({ data: 0, isFetching: false })
   })
 
+  it('should not refetch stale query on focus when `refetchOnWindowFocus` is set to a function that returns `false`', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<number>[] = []
+    let count = 0
+
+    function Page() {
+      const state = useQuery(key, () => count++, {
+        staleTime: 0,
+        refetchOnWindowFocus: () => false,
+      })
+      states.push(state)
+      return null
+    }
+
+    renderWithClient(queryClient, <Page />)
+
+    await sleep(10)
+
+    act(() => {
+      window.dispatchEvent(new FocusEvent('focus'))
+    })
+
+    await sleep(10)
+
+    expect(states.length).toBe(2)
+    expect(states[0]).toMatchObject({ data: undefined, isFetching: true })
+    expect(states[1]).toMatchObject({ data: 0, isFetching: false })
+  })
+
   it('should not refetch fresh query on focus when `refetchOnWindowFocus` is set to `true`', async () => {
     const key = queryKey()
     const states: UseQueryResult<number>[] = []
@@ -2468,6 +2497,58 @@ describe('useQuery', () => {
     expect(states[3]).toMatchObject({ data: 1, isFetching: false })
   })
 
+  it('should calculate focus behaviour for `refetchOnWindowFocus` depending on function', async () => {
+    const key = queryKey()
+    const states: UseQueryResult<number>[] = []
+    let count = 0
+
+    function Page() {
+      const state = useQuery(
+        key,
+        async () => {
+          await sleep(1)
+          return count++
+        },
+        {
+          staleTime: 0,
+          retry: 0,
+          refetchOnWindowFocus: query => (query.state.data || 0) < 1,
+        }
+      )
+      states.push(state)
+      return null
+    }
+
+    renderWithClient(queryClient, <Page />)
+
+    await sleep(10)
+
+    expect(states.length).toBe(2)
+    expect(states[0]).toMatchObject({ data: undefined, isFetching: true })
+    expect(states[1]).toMatchObject({ data: 0, isFetching: false })
+
+    act(() => {
+      window.dispatchEvent(new FocusEvent('focus'))
+    })
+
+    await sleep(10)
+
+    // refetch should happen
+    expect(states.length).toBe(4)
+
+    expect(states[2]).toMatchObject({ data: 0, isFetching: true })
+    expect(states[3]).toMatchObject({ data: 1, isFetching: false })
+
+    act(() => {
+      window.dispatchEvent(new FocusEvent('focus'))
+    })
+
+    await sleep(10)
+
+    // no more refetch now
+    expect(states.length).toBe(4)
+  })
+
   it('should refetch fresh query when refetchOnMount is set to always', async () => {
     const key = queryKey()
     const states: UseQueryResult<string>[] = []