fix: ensure LiveQueryCollection markReady is called when source collections have no data (#309)

Co-authored-by: Claude <[email protected]>

Author: KyleAMathews

.changeset/ninety-parts-check.md

@@ -0,0 +1,14 @@
+---
+"@tanstack/query-db-collection": patch
+"@tanstack/db": patch
+---
+
+Fix LiveQueryCollection hanging when source collections have no data
+
+Fixed an issue where `LiveQueryCollection.preload()` would hang indefinitely when source collections call `markReady()` without data changes (e.g., when queryFn returns empty array).
+
+The fix implements a proper event-based solution:
+
+- Collections now emit empty change events when becoming ready with no data
+- WHERE clause filtered subscriptions now correctly pass through empty ready signals
+- Both regular and WHERE clause optimized LiveQueryCollections now work correctly with empty source collections

packages/db/src/change-events.ts

@@ -250,7 +250,9 @@ export function createFilteredCallback<T extends object>(
       }
     }
 
-    if (filteredChanges.length > 0) {
+    // Always call the original callback if we have filtered changes OR
+    // if the original changes array was empty (which indicates a ready signal)
+    if (filteredChanges.length > 0 || changes.length === 0) {
       originalCallback(filteredChanges)
     }
   }

packages/db/src/collection.ts

@@ -318,6 +318,12 @@ export class CollectionImpl<
         const callbacks = [...this.onFirstReadyCallbacks]
         this.onFirstReadyCallbacks = []
         callbacks.forEach((callback) => callback())
+
+        // If the collection is empty when it becomes ready, emit an empty change event
+        // to notify subscribers (like LiveQueryCollection) that the collection is ready
+        if (this.size === 0 && this.changeListeners.size > 0) {
+          this.emitEmptyReadyEvent()
+        }
       }
     }
   }
@@ -882,6 +888,17 @@ export class CollectionImpl<
     return this.syncedData.get(key)
   }
 
+  /**
+   * Emit an empty ready event to notify subscribers that the collection is ready
+   * This bypasses the normal empty array check in emitEvents
+   */
+  private emitEmptyReadyEvent(): void {
+    // Emit empty array directly to all listeners
+    for (const listener of this.changeListeners) {
+      listener([])
+    }
+  }
+
   /**
    * Emit events either immediately or batch them for later emission
    */

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

@@ -88,4 +88,86 @@ describe(`createLiveQueryCollection`, () => {
     expect(activeUsers1.size).toBe(2)
     expect(activeUsers2.size).toBe(2)
   })
+
+  it(`should call markReady when source collection returns empty array`, async () => {
+    // Create an empty source collection using the mock sync options
+    const emptyUsersCollection = createCollection(
+      mockSyncCollectionOptions<User>({
+        id: `empty-test-users`,
+        getKey: (user) => user.id,
+        initialData: [], // Empty initial data
+      })
+    )
+
+    // Create a live query collection that depends on the empty source collection
+    const liveQuery = createLiveQueryCollection((q) =>
+      q
+        .from({ user: emptyUsersCollection })
+        .where(({ user }) => eq(user.active, true))
+    )
+
+    // This should resolve and not hang, even though the source collection is empty
+    await liveQuery.preload()
+
+    expect(liveQuery.status).toBe(`ready`)
+    expect(liveQuery.size).toBe(0)
+  })
+
+  it(`should call markReady when source collection sync doesn't call begin/commit (without WHERE clause)`, async () => {
+    // Create a collection with sync that only calls markReady (like the reproduction case)
+    const problemCollection = createCollection<User>({
+      id: `problem-collection`,
+      sync: {
+        sync: ({ markReady }) => {
+          // Simulate async operation without begin/commit (like empty queryFn case)
+          setTimeout(() => {
+            markReady()
+          }, 50)
+          return () => {} // cleanup function
+        },
+      },
+      getKey: (user) => user.id,
+    })
+
+    // Create a live query collection that depends on the problematic source collection
+    const liveQuery = createLiveQueryCollection((q) =>
+      q.from({ user: problemCollection })
+    )
+
+    // This should resolve and not hang, even though the source collection doesn't commit data
+    await liveQuery.preload()
+
+    expect(liveQuery.status).toBe(`ready`)
+    expect(liveQuery.size).toBe(0)
+  })
+
+  it(`should call markReady when source collection sync doesn't call begin/commit (with WHERE clause)`, async () => {
+    // Create a collection with sync that only calls markReady (like the reproduction case)
+    const problemCollection = createCollection<User>({
+      id: `problem-collection-where`,
+      sync: {
+        sync: ({ markReady }) => {
+          // Simulate async operation without begin/commit (like empty queryFn case)
+          setTimeout(() => {
+            markReady()
+          }, 50)
+          return () => {} // cleanup function
+        },
+      },
+      getKey: (user) => user.id,
+    })
+
+    // Create a live query collection that depends on the problematic source collection
+    const liveQuery = createLiveQueryCollection((q) =>
+      q
+        .from({ user: problemCollection })
+        .where(({ user }) => eq(user.active, true))
+    )
+
+    // This should resolve and not hang, even though the source collection doesn't commit data
+    await liveQuery.preload()
+
+    expect(liveQuery.status).toBe(`ready`)
+    expect(liveQuery.size).toBe(0)
+  })
 })

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

@@ -1016,4 +1016,38 @@ describe(`QueryCollection`, () => {
       expect(finalItem?.name).toMatch(/^Item \d+$/)
     })
   })
+
+  it(`should call markReady when queryFn returns an empty array`, async () => {
+    const queryKey = [`emptyArrayTest`]
+    const queryFn = vi.fn().mockResolvedValue([])
+
+    const config: QueryCollectionConfig<TestItem> = {
+      id: `test`,
+      queryClient,
+      queryKey,
+      queryFn,
+      getKey,
+      startSync: true,
+    }
+
+    const options = queryCollectionOptions(config)
+    const collection = createCollection(options)
+
+    // Wait for the query to complete
+    await vi.waitFor(
+      () => {
+        expect(queryFn).toHaveBeenCalledTimes(1)
+        // The collection should be marked as ready even with empty array
+        expect(collection.status).toBe(`ready`)
+      },
+      {
+        timeout: 1000,
+        interval: 50,
+      }
+    )
+
+    // Verify the collection is empty but ready
+    expect(collection.size).toBe(0)
+    expect(collection.status).toBe(`ready`)
+  })
 })