fix(query-core): update initialData when an observer mounts while a Query without data exists

TkDodo · TkDodo · commit a6269e967c09 · 2025-09-05T15:52:35.000+02:00
initialData gives the guarantee that data cannot be undefined, but this falls short when you create a Query via prefetching, and then mount the observer that has initialData set.

That's because initialData is only doing something in the constructor of the Query, so if the Observer isn't the one who creates the Query, it does nothing

This fix makes sure that when new options are applied on a Query (which e.g. happens when an observer mounts), initialData is taken into account when the Query doesn't have any data yet
diff --git a/packages/query-core/src/__tests__/query.test.tsx b/packages/query-core/src/__tests__/query.test.tsx
@@ -1193,6 +1193,68 @@ describe('query', () => {
     expect(query.state.data).toBe('initial data')
   })
 
+  test('should update initialData when Query exists without data', async () => {
+    const key = queryKey()
+    const queryFn = vi.fn(async () => {
+      await sleep(100)
+      return 'data'
+    })
+
+    const promise = queryClient.prefetchQuery({
+      queryKey: key,
+      queryFn,
+      staleTime: 1000,
+    })
+
+    vi.advanceTimersByTime(50)
+
+    expect(queryClient.getQueryState(key)).toMatchObject({
+      data: undefined,
+      status: 'pending',
+      fetchStatus: 'fetching',
+    })
+
+    const observer = new QueryObserver(queryClient, {
+      queryKey: key,
+      queryFn,
+      staleTime: 1000,
+      initialData: 'initialData',
+      initialDataUpdatedAt: 10,
+    })
+
+    const unsubscribe = observer.subscribe(vi.fn())
+
+    expect(queryClient.getQueryState(key)).toMatchObject({
+      data: 'initialData',
+      dataUpdatedAt: 10,
+      status: 'success',
+      fetchStatus: 'fetching',
+    })
+
+    vi.advanceTimersByTime(50)
+
+    await promise
+
+    expect(queryClient.getQueryState(key)).toMatchObject({
+      data: 'data',
+      status: 'success',
+      fetchStatus: 'idle',
+    })
+
+    expect(queryFn).toHaveBeenCalledTimes(1)
+
+    unsubscribe()
+
+    // resetting should get us back ot 'initialData'
+    queryClient.getQueryCache().find({ queryKey: key })!.reset()
+
+    expect(queryClient.getQueryState(key)).toMatchObject({
+      data: 'initialData',
+      status: 'success',
+      fetchStatus: 'idle',
+    })
+  })
+
   test('should not override fetching state when revert happens after new observer subscribes', async () => {
     const key = queryKey()
     let count = 0
diff --git a/packages/query-core/src/query.ts b/packages/query-core/src/query.ts
@@ -205,6 +205,18 @@ export class Query<
     this.options = { ...this.#defaultOptions, ...options }
 
     this.updateGcTime(this.options.gcTime)
+
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (this.state && this.state.data === undefined) {
+      const defaultState = getDefaultState(this.options)
+      if (defaultState.data !== undefined) {
+        this.setData(defaultState.data, {
+          updatedAt: defaultState.dataUpdatedAt,
+          manual: true,
+        })
+        this.#initialState = defaultState
+      }
+    }
   }
 
   protected optionalRemove() {
