feat(queryObserver): add isInitialLoading derived flag (#4244)

* feat(queryObserver): add isInitialLoading derived flag

this flag describes isLoading && isFetching and can be used to show a loading spinner for lazy or disabled queries

* chore(ci): fix caching

apparently, v3 has a fix: actions/setup-node#543

* chore(ci): properly fix token issue

as described here: https://stackoverflow.com/questions/52015748/npm-failed-to-replace-env-in-config-npm-token

he extra warn output made the caching fail

* chore: fix bundlewatch glob

* docs: add a section about isInitialLoading to the migration guide

Author: TkDodo

.github/workflows/ci.yml

@@ -21,14 +21,16 @@ jobs:
       - uses: pnpm/action-setup@v2.2.2
         with:
           version: 7
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v3
         with:
           node-version: 16.14.2
           registry-url: https://registry.npmjs.org/
+          cache: 'pnpm'
       - run: |
-          pnpm --filter "./packages/**" --filter query install
+          pnpm --filter "./packages/**" --filter query --prefer-offline install
           git config --global user.name 'Tanner Linsley'
           git config --global user.email 'tannerlinsley@users.noreply.github.com'
+          npm config set '//registry.npmjs.org/:_authToken' "${NPM_TOKEN}"
           pnpm run cipublish
         env:
           GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}

.github/workflows/pr.yml

@@ -13,12 +13,12 @@ jobs:
       - uses: pnpm/action-setup@v2.2.2
         with:
           version: 7
-      - uses: actions/setup-node@v2
+      - uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node }}
           cache: 'pnpm'
       - name: Install dependencies
-        run: pnpm --filter "./packages/**" --filter query install
+        run: pnpm --filter "./packages/**" --filter query --prefer-offline install
       - run: |
           pnpm run test:ci
           pnpm run test:size

.npmrc

@@ -19,7 +19,7 @@ When `enabled` is `false`:
 ```tsx
 function Todos() {
   const {
-    isLoading,
+    isInitialLoading,
     isError,
     data,
     error,
@@ -45,10 +45,10 @@ function Todos() {
         isError ? (
           <span>Error: {error.message}</span>
         ) : (
-          (isLoading && !isFetching) ? (
-           <span>Not ready ...</span>
+          isInitialLoading ? (
+            <span>Loading...</span>
          ) : (
-           <span>Loading...</span>
+            <span>Not ready ...</span>
          )
         )
       )}
@@ -87,3 +87,13 @@ function Todos() {
   )
 }
 ```
+
+### isInitialLoading
+
+Lazy queries will be in `status: 'loading'` right from the start because `loading` means that there is no data yet. This is technically true, however, since we are not currently fetching any data (as the query is not _enabled_), it also means you likely cannot use this flag to show a loading spinner.
+
+If you are using disabled or lazy queries, you can use the `isInitialLoading` flag instead. It's a derived flag that is computed from:
+
+`isLoading && isFetching`
+
+so it will only be true if the query is currently fetching for the first time.

docs/guides/disabling-queries.md

@@ -112,6 +112,17 @@ This will mostly affect `disabled` queries that don't have any `data` yet, as th
 
 Also, have a look at [the guide on dependent queries](../guides/dependent-queries)
 
+#### disabled queries
+
+Due to this change, disabled queries (even temporarily disabled ones) will start in `loading` state. To make migration easier, especially for having a good flag to know when to display a loading spinner, you can check for `isInitialLoading` instead of `isLoading`:
+
+```diff
+- isLoading
++ isInitialLoading
+```
+
+See also the guide on [disabling queries](../guides/disabling-queries#isInitialLoading)
+
 ### new API for `useQueries`
 
 The `useQueries` hook now accepts an object with a `queries` prop as its input. The value of the `queries` prop is an array of queries (this array is identical to what was passed into `useQueries` in v3).

docs/guides/migrating-to-react-query-4.md

@@ -244,6 +244,9 @@ const result = useQuery({
 - `isRefetching: boolean`
   - Is `true` whenever a background refetch is in-flight, which _does not_ include initial `loading`
   - Is the same as `isFetching && !isLoading`
+- `isInitialLoading: boolean`
+  - Is `true` whenever the first fetch for a query is in-flight
+  - Is the same as `isFetching && isLoading`
 - `failureCount: number`
   - The failure count for the query.
   - Incremented every time the query fails.

docs/reference/useQuery.md

@@ -96,7 +96,7 @@
   "bundlewatch": {
     "files": [
       {
-        "path": "packages/**/build/umd/*.production.js"
+        "path": "packages/*/build/umd/*.production.js"
       }
     ]
   }

package.json

@@ -547,13 +547,16 @@ export class QueryObserver<
     }
 
     const isFetching = fetchStatus === 'fetching'
+    const isLoading = status === 'loading'
+    const isError = status === 'error'
 
     const result: QueryObserverBaseResult<TData, TError> = {
       status,
       fetchStatus,
-      isLoading: status === 'loading',
+      isLoading,
       isSuccess: status === 'success',
-      isError: status === 'error',
+      isError,
+      isInitialLoading: isLoading && isFetching,
       data,
       dataUpdatedAt,
       error,
@@ -564,13 +567,13 @@ export class QueryObserver<
       isFetchedAfterMount:
         state.dataUpdateCount > queryInitialState.dataUpdateCount ||
         state.errorUpdateCount > queryInitialState.errorUpdateCount,
-      isFetching: isFetching,
-      isRefetching: isFetching && status !== 'loading',
-      isLoadingError: status === 'error' && state.dataUpdatedAt === 0,
+      isFetching,
+      isRefetching: isFetching && !isLoading,
+      isLoadingError: isError && state.dataUpdatedAt === 0,
       isPaused: fetchStatus === 'paused',
       isPlaceholderData,
       isPreviousData,
-      isRefetchError: status === 'error' && state.dataUpdatedAt !== 0,
+      isRefetchError: isError && state.dataUpdatedAt !== 0,
       isStale: isStale(query, options),
       refetch: this.refetch,
       remove: this.remove,

packages/query-core/src/queryObserver.ts

@@ -373,6 +373,7 @@ export interface QueryObserverBaseResult<TData = unknown, TError = unknown> {
   isFetching: boolean
   isLoading: boolean
   isLoadingError: boolean
+  isInitialLoading: boolean
   isPaused: boolean
   isPlaceholderData: boolean
   isPreviousData: boolean

packages/query-core/src/types.ts

@@ -84,6 +84,7 @@ describe('useInfiniteQuery', () => {
       isFetchingNextPage: false,
       isFetchingPreviousPage: false,
       isLoading: true,
+      isInitialLoading: true,
       isLoadingError: false,
       isPlaceholderData: false,
       isPreviousData: false,
@@ -116,6 +117,7 @@ describe('useInfiniteQuery', () => {
       isFetchingNextPage: false,
       isFetchingPreviousPage: false,
       isLoading: false,
+      isInitialLoading: false,
       isLoadingError: false,
       isPlaceholderData: false,
       isPreviousData: false,