fix(queryFilters): fetchStatus to queryFilters (#3061)

Author: TkDodo

docs/src/pages/guides/filters.md

@@ -34,9 +34,10 @@ A query filter object supports the following properties:
 - `stale?: boolean`
   - When set to `true` it will match stale queries.
   - When set to `false` it will match fresh queries.
-- `fetching?: boolean`
-  - When set to `true` it will match queries that are currently fetching.
-  - When set to `false` it will match queries that are not fetching.
+- `fetchStatus?: FetchStatus`
+  - When set to `fetching` it will match queries that are currently fetching.
+  - When set to `paused` it will match queries that wanted to fetch, but have been `paused`.
+  - When set to `idle` it will match queries that are not fetching.
 - `predicate?: (query: Query) => boolean`
   - This predicate function will be called for every single query in the cache and be expected to return truthy for queries that are `found`.
 - `queryKey?: QueryKey`

src/core/query.ts

@@ -256,10 +256,6 @@ export class Query<
     return this.observers.some(observer => observer.options.enabled !== false)
   }
 
-  isFetching(): boolean {
-    return this.state.fetchStatus === 'fetching'
-  }
-
   isStale(): boolean {
     return (
       this.state.isInvalidated ||

src/core/queryClient.ts

@@ -99,7 +99,7 @@ export class QueryClient {
   isFetching(queryKey?: QueryKey, filters?: QueryFilters): number
   isFetching(arg1?: QueryKey | QueryFilters, arg2?: QueryFilters): number {
     const [filters] = parseFilterArgs(arg1, arg2)
-    filters.fetching = true
+    filters.fetchStatus = 'fetching'
     return this.queryCache.findAll(filters).length
   }
 

src/core/tests/queryCache.test.tsx

@@ -78,6 +78,7 @@ describe('queryCache', () => {
     test('should filter correctly', async () => {
       const key1 = queryKey()
       const key2 = queryKey()
+      const keyFetching = queryKey()
       await queryClient.prefetchQuery(key1, () => 'data1')
       await queryClient.prefetchQuery(key2, () => 'data2')
       await queryClient.prefetchQuery([{ a: 'a', b: 'b' }], () => 'data3')
@@ -137,6 +138,26 @@ describe('queryCache', () => {
         queryCache.findAll({ predicate: query => query === query3 })
       ).toEqual([query3])
       expect(queryCache.findAll(['posts'])).toEqual([query4])
+
+      expect(queryCache.findAll({ fetchStatus: 'idle' })).toEqual([
+        query1,
+        query2,
+        query3,
+        query4,
+      ])
+      expect(queryCache.findAll(key2, { fetchStatus: undefined })).toEqual([
+        query2,
+      ])
+
+      const promise = queryClient.prefetchQuery(keyFetching, async () => {
+        await sleep(20)
+        return 'dataFetching'
+      })
+      expect(queryCache.findAll({ fetchStatus: 'fetching' })).toEqual([
+        queryCache.find(keyFetching),
+      ])
+      await promise
+      expect(queryCache.findAll({ fetchStatus: 'fetching' })).toEqual([])
     })
 
     test('should return all the queries when no filters are defined', async () => {

src/core/utils.ts

@@ -1,6 +1,7 @@
 import type { Mutation } from './mutation'
 import type { Query } from './query'
 import type {
+  FetchStatus,
   MutationFunction,
   MutationKey,
   MutationOptions,
@@ -33,9 +34,9 @@ export interface QueryFilters {
    */
   stale?: boolean
   /**
-   * Include or exclude fetching queries
+   * Include queries matching their fetchStatus
    */
-  fetching?: boolean
+  fetchStatus?: FetchStatus
 }
 
 export interface MutationFilters {
@@ -164,7 +165,14 @@ export function matchQuery(
   filters: QueryFilters,
   query: Query<any, any, any, any>
 ): boolean {
-  const { type = 'all', exact, fetching, predicate, queryKey, stale } = filters
+  const {
+    type = 'all',
+    exact,
+    fetchStatus,
+    predicate,
+    queryKey,
+    stale,
+  } = filters
 
   if (isQueryKey(queryKey)) {
     if (exact) {
@@ -190,7 +198,10 @@ export function matchQuery(
     return false
   }
 
-  if (typeof fetching === 'boolean' && query.isFetching() !== fetching) {
+  if (
+    typeof fetchStatus !== 'undefined' &&
+    fetchStatus !== query.state.fetchStatus
+  ) {
     return false
   }
 

src/devtools/tests/devtools.test.tsx

@@ -127,7 +127,7 @@ describe('ReactQueryDevtools', () => {
 
     // When the query is fetching then expect number of
     // fetching queries to be 1
-    expect(currentQuery?.isFetching()).toEqual(true)
+    expect(currentQuery?.state.fetchStatus).toEqual('fetching')
     await screen.findByText(
       getByTextContent(
         'fresh (0) fetching (1) paused (0) stale (0) inactive (0)'
@@ -138,7 +138,7 @@ describe('ReactQueryDevtools', () => {
     // until 300ms after, so expect the number of fresh
     // queries to be 1
     await waitFor(() => {
-      expect(currentQuery?.isFetching()).toEqual(false)
+      expect(currentQuery?.state.fetchStatus).toEqual('idle')
     })
     await screen.findByText(
       getByTextContent(