fix: make sure setQueryData is not considered as initial data

Author: boschni

docs/src/pages/docs/api.md

@@ -83,7 +83,7 @@ const queryInfo = useQuery({
   - A function like `attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000)` applies exponential backoff.
   - A function like `attempt => attempt * 1000` applies linear backoff.
 - `staleTime: Int | Infinity`
-  - The time in milliseconds that cache data remains fresh. After a successful cache update, that cache data will become stale after this duration.
+  - The time in milliseconds after data is considered stale.
   - If set to `Infinity`, query will never go stale
 - `cacheTime: Int | Infinity`
   - The time in milliseconds that unused/inactive cache data remains in memory. When a query's cache becomes unused or inactive, that cache data will be garbage collected after this duration.

src/core/query.ts

@@ -45,6 +45,7 @@ export interface QueryState<TResult, TError> {
   isFetching: boolean
   isFetchingMore: IsFetchingMoreValue
   isIdle: boolean
+  isInitialData: boolean
   isLoading: boolean
   isSuccess: boolean
   status: QueryStatus
@@ -594,6 +595,7 @@ function getDefaultState<TResult, TError>(
     isFetched: false,
     isFetching: initialStatus === QueryStatus.Loading,
     isFetchingMore: false,
+    isInitialData: config.isInitialData !== false,
     failureCount: 0,
     fetchedCount: 0,
     data: initialData,
@@ -634,6 +636,7 @@ export function queryReducer<TResult, TError>(
         isFetched: true,
         isFetching: false,
         isFetchingMore: false,
+        isInitialData: false,
         canFetchMore: action.canFetchMore,
         updatedAt: Date.now(),
         failureCount: 0,

src/core/queryCache.ts

@@ -339,7 +339,7 @@ export class QueryCache {
     }
 
     this.buildQuery<TResult, TError>(queryKey, {
-      initialStale: typeof config?.staleTime === 'undefined',
+      isInitialData: false,
       initialData: functionalUpdate(updater, undefined),
       ...config,
     })

src/core/queryObserver.ts

@@ -244,11 +244,9 @@ export class QueryObserver<TResult, TError> {
       isPreviousData = true
     }
 
-    let isStale = false
+    let isStale
 
-    // When the query has not been fetched yet and this is the initial render,
-    // determine the staleness based on the initialStale or existence of initial data.
-    if (!currentResult && !state.isFetched) {
+    if (state.isInitialData && !currentResult) {
       if (typeof config.initialStale === 'function') {
         isStale = config.initialStale()
       } else if (typeof config.initialStale === 'boolean') {

src/core/types.ts

@@ -42,15 +42,14 @@ export interface BaseQueryConfig<TResult, TError = unknown, TData = TResult> {
    */
   retry?: boolean | number | ((failureCount: number, error: TError) => boolean)
   retryDelay?: number | ((retryAttempt: number) => number)
-  staleTime?: number
   cacheTime?: number
   isDataEqual?: (oldData: unknown, newData: unknown) => boolean
   queryFn?: QueryFunction<TData>
   queryKey?: QueryKey
   queryKeySerializerFn?: QueryKeySerializerFunction
   queryFnParamsFilter?: (args: ArrayQueryKey) => ArrayQueryKey
   initialData?: TResult | InitialDataFunction<TResult>
-  initialStale?: boolean | InitialStaleFunction
+  isInitialData?: boolean
   infinite?: true
   /**
    * Set this to `false` to disable structural sharing between query results.
@@ -75,6 +74,17 @@ export interface QueryObserverConfig<
    * Defaults to `true`.
    */
   enabled?: boolean | unknown
+  /**
+   * The time in milliseconds after data is considered stale.
+   * If set to `Infinity`, the data will never be stale.
+   */
+  staleTime?: number
+  /**
+   * If set, this will mark any `initialData` provided as stale and will likely cause it to be refetched on mount.
+   * If a function is passed, it will be called only when appropriate to resolve the `initialStale` value.
+   * This can be useful if your `initialStale` value is costly to calculate.
+   */
+  initialStale?: boolean | InitialStaleFunction
   /**
    * If set to a number, the query will continuously refetch at this frequency in milliseconds.
    * Defaults to `false`.

src/react/tests/useQuery.test.tsx

@@ -1225,6 +1225,41 @@ describe('useQuery', () => {
     consoleMock.mockRestore()
   })
 
+  it('should fetch on mount when a query was already created with setQueryData', async () => {
+    const key = queryKey()
+    const states: QueryResult<string>[] = []
+
+    queryCache.setQueryData(key, 'prefetched')
+
+    function Page() {
+      const state = useQuery(key, () => 'data')
+      states.push(state)
+      return null
+    }
+
+    render(<Page />)
+
+    await waitFor(() =>
+      expect(states).toMatchObject([
+        {
+          data: 'prefetched',
+          isFetching: false,
+          isStale: true,
+        },
+        {
+          data: 'prefetched',
+          isFetching: true,
+          isStale: true,
+        },
+        {
+          data: 'data',
+          isFetching: false,
+          isStale: true,
+        },
+      ])
+    )
+  })
+
   it('should refetch after focus regain', async () => {
     const key = queryKey()
     const states: QueryResult<string>[] = []
@@ -1245,29 +1280,34 @@ describe('useQuery', () => {
 
     render(<Page />)
 
-    await waitFor(() => expect(states.length).toBe(2))
+    await waitFor(() => expect(states.length).toBe(3))
 
     act(() => {
       // reset visibilityState to original value
       mockVisibilityState(originalVisibilityState)
       window.dispatchEvent(new FocusEvent('focus'))
     })
 
-    await waitFor(() => expect(states.length).toBe(4))
+    await waitFor(() => expect(states.length).toBe(5))
 
     expect(states).toMatchObject([
       {
         data: 'prefetched',
         isFetching: false,
-        isStale: false,
+        isStale: true,
       },
       {
         data: 'prefetched',
+        isFetching: true,
+        isStale: true,
+      },
+      {
+        data: 'data',
         isFetching: false,
         isStale: true,
       },
       {
-        data: 'prefetched',
+        data: 'data',
         isFetching: true,
         isStale: true,
       },