Fix: Ensure query collections initialize with existing data

.changeset/gold-flowers-rest.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/query-db-collection": patch
+---
+
+fix: race condition creating a collection from a query that has already loaded

packages/query-db-collection/src/query.ts

@@ -497,7 +497,8 @@ export function queryCollectionOptions<
       TQueryKey
     >(queryClient, observerOptions)
 
-    const actualUnsubscribeFn = localObserver.subscribe((result) => {
+    type UpdateHandler = Parameters<typeof localObserver.subscribe>[0]
+    const handleUpdate: UpdateHandler = (result) => {
       if (result.isSuccess) {
         const newItemsArray = result.data
 
@@ -575,7 +576,13 @@ export function queryCollectionOptions<
         // Mark collection as ready even on error to avoid blocking apps
         markReady()
       }
-    })
+    }
+
+    const actualUnsubscribeFn = localObserver.subscribe(handleUpdate)
+
+    // Ensure we process any existing query data (QueryObserver doesn't invoke its callback automatically with initial
+    // state)
+    handleUpdate(localObserver.getCurrentResult())
 
     return async () => {
       actualUnsubscribeFn()

packages/query-db-collection/tests/query.test.ts

@@ -1603,4 +1603,33 @@ describe(`QueryCollection`, () => {
     expect(collection.size).toBe(0)
     expect(collection.status).toBe(`ready`)
   })
+
+  it(`should read the state of a query that is already ready`, async () => {
+    // Populate the query cache, so the query will immediately be loaded
+    const queryKey = [`raceConditionTest`]
+    const initialItems: Array<TestItem> = [
+      { id: `1`, name: `Cached Item 1` },
+      { id: `2`, name: `Cached Item 2` },
+    ]
+    const queryFn = vi.fn().mockReturnValue(initialItems)
+    await queryClient.prefetchQuery({ queryKey, queryFn })
+
+    // The collection should immediately be ready
+    const collection = createCollection(
+      queryCollectionOptions({
+        id: `test`,
+        queryClient,
+        queryKey,
+        queryFn,
+        getKey,
+        startSync: true,
+        staleTime: 60000, // uses the prefetched value without a refetch
+      })
+    )
+    expect(collection.status).toBe(`ready`)
+    expect(collection.size).toBe(2)
+    expect(Array.from(collection.values())).toEqual(
+      expect.arrayContaining(initialItems)
+    )
+  })
 })