fix(query-db-collection): sync=on-demand tanstack-query lifecycle

Author: delphinaubin

.changeset/sync-on-demand-collection-fix.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/query-db-collection': patch
+---
+
+Fix on-demand sync behavior so the full TanStack Query lifecycle is respected.
+
+This patch resolves an issue where using on-demand synchronization could break the query lifecycle, including the error reported in https://github.com/TanStack/db/issues/998.

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

@@ -692,13 +692,16 @@ export function queryCollectionOptions(
           // Query is still loading, wait for the first result
           return new Promise<void>((resolve, reject) => {
             const unsubscribe = observer.subscribe((result) => {
-              if (result.isSuccess) {
-                unsubscribe()
-                resolve()
-              } else if (result.isError) {
-                unsubscribe()
-                reject(result.error)
-              }
+              // Use a microtask in case `subscribe` is called synchronously, before `unsubscribe` is initialized
+              queueMicrotask(() => {
+                if (result.isSuccess) {
+                  unsubscribe()
+                  resolve()
+                } else if (result.isError) {
+                  unsubscribe()
+                  reject(result.error)
+                }
+              })
             })
           })
         }
@@ -745,13 +748,16 @@ export function queryCollectionOptions(
       // Create a promise that resolves when the query result is first available
       const readyPromise = new Promise<void>((resolve, reject) => {
         const unsubscribe = localObserver.subscribe((result) => {
-          if (result.isSuccess) {
-            unsubscribe()
-            resolve()
-          } else if (result.isError) {
-            unsubscribe()
-            reject(result.error)
-          }
+          // Use a microtask in case `subscribe` is called synchronously, before `unsubscribe` is initialized
+          queueMicrotask(() => {
+            if (result.isSuccess) {
+              unsubscribe()
+              resolve()
+            } else if (result.isError) {
+              unsubscribe()
+              reject(result.error)
+            }
+          })
         })
       })
 

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

@@ -4219,7 +4219,7 @@ describe(`QueryCollection`, () => {
         defaultOptions: {
           queries: {
             gcTime: 5 * 60 * 1000, // 5 minutes
-            staleTime: 0,
+            staleTime: Infinity, // set an Infinity staleTime to prevent a refetch
             retry: false,
           },
         },
@@ -4562,7 +4562,7 @@ describe(`QueryCollection`, () => {
       const testQueryClient = new QueryClient({
         defaultOptions: {
           queries: {
-            staleTime: 0,
+            staleTime: Infinity, // set an Infinity staleTime to prevent a refetch
             gcTime: 300,
             retry: false,
           },