@tanstack/react-db 0.5.11 → 1.0.0-rc.1

package/src/useLiveSuspenseQuery.ts

@@ -1,6 +1,7 @@
 'use client'
 
 import { useRef } from 'react'
+import { rejectLiveQueryInput, toBoundaryError } from '@tanstack/db'
 import { useLiveQueryForSuspense } from './useLiveQuery'
 import { getLiveQueryResultInfo } from './live-query-internals'
 import type { UseLiveQueryConfig } from './useLiveQuery'
@@ -9,9 +10,9 @@ import type {
   Context,
   DbClient,
   GetResult,
+  HealthNode,
   InferResultType,
   InitialQueryBuilder,
-  LiveQueryCollectionConfig,
   NonSingleResult,
   QueryBuilder,
   SingleResult,
@@ -60,10 +61,12 @@ function rememberInitialRenderError(
 /**
  * Create a live query with React Suspense support
  * @param queryFn - Query function that defines what data to fetch
- * @param deps - Deprecated array of dependencies that trigger query re-execution when changed
  * @returns Object with reactive data and state - data is guaranteed to be defined
  * @throws Promise when data is loading (caught by Suspense boundary)
- * @throws Error when collection fails (caught by Error boundary)
+ * @throws Error when the first load fails or the Collection crashes (caught by
+ * an Error boundary): the cause itself when it is an Error, otherwise an Error
+ * with the problem's message (`health.error.message`) whose `cause` is the
+ * value the sync adapter reported
  * @example
  * // Basic usage with Suspense
  * function TodoList() {
@@ -150,11 +153,11 @@ function rememberInitialRenderError(
 // Overload 1: Accept query function that always returns QueryBuilder
 export function useLiveSuspenseQuery<TContext extends Context>(
   queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,
-  deps?: Array<unknown>,
 ): {
   state: Map<string | number, GetResult<TContext>>
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
+  health: HealthNode | undefined
 }
 
 // Overload 2: Accept config object
@@ -164,16 +167,7 @@ export function useLiveSuspenseQuery<TContext extends Context>(
   state: Map<string | number, GetResult<TContext>>
   data: InferResultType<TContext>
   collection: Collection<GetResult<TContext>, string | number, {}>
-}
-
-// Overload 3: Accept legacy config object
-export function useLiveSuspenseQuery<TContext extends Context>(
-  config: LiveQueryCollectionConfig<TContext>,
-  deps?: Array<unknown>,
-): {
-  state: Map<string | number, GetResult<TContext>>
-  data: InferResultType<TContext>
-  collection: Collection<GetResult<TContext>, string | number, {}>
+  health: HealthNode | undefined
 }
 
 // Overload 4: Accept pre-created live query collection
@@ -187,6 +181,7 @@ export function useLiveSuspenseQuery<
   state: Map<TKey, TResult>
   data: Array<TResult>
   collection: Collection<TResult, TKey, TUtils>
+  health: HealthNode | undefined
 }
 
 // Overload 5: Accept pre-created live query collection with singleResult: true
@@ -200,22 +195,17 @@ export function useLiveSuspenseQuery<
   state: Map<TKey, TResult>
   data: TResult | undefined
   collection: Collection<TResult, TKey, TUtils> & SingleResult
+  health: HealthNode | undefined
 }
 
 // Implementation - uses useLiveQuery internally and adds Suspense logic
-export function useLiveSuspenseQuery(
-  configOrQueryOrCollection: any,
-  deps?: Array<unknown>,
-) {
+export function useLiveSuspenseQuery(configOrQueryOrCollection: any) {
   const promiseRef = useRef<Promise<void> | null>(null)
   const collectionRef = useRef<Collection<any, any, any> | null>(null)
   const hasBeenReadyRef = useRef(false)
 
   // Use useLiveQuery to handle collection management and reactivity
-  const result =
-    deps === undefined
-      ? useLiveQueryForSuspense(configOrQueryOrCollection, undefined)
-      : useLiveQueryForSuspense(configOrQueryOrCollection, deps)
+  const result = useLiveQueryForSuspense(configOrQueryOrCollection)
 
   if (!result.isEnabled) {
     // Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior
@@ -229,81 +219,43 @@ export function useLiveSuspenseQuery(
   }
 
   const queryInfo = getLiveQueryResultInfo(result)
+  // The render boundary: an error thrown before this render commits releases
+  // the sync starts it deferred. A thrown promise suspends; its preload owns
+  // those starts.
+  try {
+    // Reset promise and ready state when query identity changes
+    if (collectionRef.current !== result.collection) {
+      promiseRef.current = null
+      collectionRef.current = result.collection
+      hasBeenReadyRef.current = false
+    }
 
-  // Reset promise and ready state when query identity changes
-  if (collectionRef.current !== result.collection) {
-    promiseRef.current = null
-    collectionRef.current = result.collection
-    hasBeenReadyRef.current = false
-  }
-
-  // SUSPENSE LOGIC: Throw promise or error based on collection status
-
-  const collectionStatus = result.collection.status
-
-  // Track when we reach ready state
-  if (result.isReady || queryInfo.observer.isInitialRenderReady()) {
-    hasBeenReadyRef.current = true
-    promiseRef.current = null
-    clearInitialRenderError(result.collection, queryInfo.client)
-  }
+    // SUSPENSE LOGIC: Throw promise or error based on collection status
 
-  const observerError = queryInfo.observer.getError()
-  // A client request can reject with undefined, which getError() cannot
-  // distinguish from no error. The request status preserves that distinction.
-  const clientQuery =
-    queryInfo.client && queryInfo.queryHash
-      ? queryInfo.client._getLiveQuery(queryInfo.queryHash)
-      : undefined
-  // A configured persisted restore may still satisfy this render after the
-  // client query fails. Let the observer classify that failure below.
-  if (
-    !hasBeenReadyRef.current &&
-    (result.persistedStatus === `unavailable` ||
-      result.persistedStatus === `error`) &&
-    (observerError !== undefined || clientQuery?.status === `error`)
-  ) {
-    promiseRef.current = null
-    throw observerError === undefined ? clientQuery?.error : observerError
-  }
+    const collectionStatus = result.collection.status
 
-  const errorEntry = initialRenderErrors.get(result.collection)
-  const initialRenderError = queryInfo.client
-    ? errorEntry?.byClient.get(queryInfo.client)
-    : errorEntry?.unscoped
-  // A replacement client query must not inherit the prior request's error.
-  if (
-    initialRenderError?.clientQuery !== undefined &&
-    initialRenderError.clientQuery !== clientQuery
-  ) {
-    clearInitialRenderError(result.collection, queryInfo.client)
-  } else if (initialRenderError && !hasBeenReadyRef.current) {
-    promiseRef.current = null
-    throw initialRenderError.error
-  }
+    // Track when we reach ready state
+    if (result.isReady) {
+      hasBeenReadyRef.current = true
+      promiseRef.current = null
+      clearInitialRenderError(result.collection, queryInfo.client)
+    }
 
-  // Only throw errors during initial load (before first ready)
-  // After success, errors surface as stale data (matches TanStack Query behavior)
-  if (
-    collectionStatus === `error` &&
-    !hasBeenReadyRef.current &&
-    (result.persistedStatus === `unavailable` ||
-      result.persistedStatus === `error`)
-  ) {
-    promiseRef.current = null
-    // TODO: Once collections hold a reference to their last error object (#671),
-    // we should rethrow that actual error instead of creating a generic message
-    throw new Error(`Collection "${result.collection.id}" failed to load`)
-  }
+    const observerError = queryInfo.observer.getError()
+    // A client request can reject with undefined, which getError() cannot
+    // distinguish from no error. The request status preserves that distinction.
+    const clientQuery =
+      queryInfo.client && queryInfo.queryHash
+        ? queryInfo.client._getLiveQuery(queryInfo.queryHash)
+        : undefined
+    if (
+      !hasBeenReadyRef.current &&
+      (observerError !== undefined || clientQuery?.status === `error`)
+    ) {
+      promiseRef.current = null
+      throw observerError === undefined ? clientQuery?.error : observerError
+    }
 
-  if (
-    !hasBeenReadyRef.current &&
-    (result.isLoading ||
-      result.isIdle ||
-      result.isError ||
-      (collectionStatus === `error` &&
-        result.persistedStatus !== `unavailable`))
-  ) {
     if (queryInfo.client?._isSsrStreamingEnabled() && !queryInfo.queryHash) {
       const reason = queryInfo.identityError
         ? `${queryInfo.identityError.reason} at ${queryInfo.identityError.path}`
@@ -312,48 +264,86 @@ export function useLiveSuspenseQuery(
         `Cannot stream this live query during SSR because ${reason}. Provide an explicit serializable queryKey.`,
       )
     }
-    // Create or reuse promise for current collection
-    if (!promiseRef.current) {
-      const collection = result.collection
-      const client = queryInfo.client
-      const queryHash = queryInfo.queryHash
-      let active = true
-      const stopWatchingCleanup = collection.once(`status:cleaned-up`, () => {
-        active = false
-      })
-      let preload: Promise<void>
-      try {
-        preload = queryInfo.observer.preloadForInitialRender()
-      } catch (error) {
-        stopWatchingCleanup()
-        throw error
-      }
-      const preloadClientQuery =
-        client && queryHash ? client._getLiveQuery(queryHash) : undefined
-      promiseRef.current = preload
-        .catch((error: unknown) => {
-          const latestClientQuery =
-            client && queryHash ? client._getLiveQuery(queryHash) : undefined
-          if (active && latestClientQuery === preloadClientQuery)
-            rememberInitialRenderError(
-              collection,
-              client,
-              error,
-              preloadClientQuery,
-            )
-          throw error
+    const errorEntry = initialRenderErrors.get(result.collection)
+    const initialRenderError = queryInfo.client
+      ? errorEntry?.byClient.get(queryInfo.client)
+      : errorEntry?.unscoped
+    // A replacement client query must not inherit the prior request's error.
+    if (
+      initialRenderError?.clientQuery !== undefined &&
+      initialRenderError.clientQuery !== clientQuery
+    ) {
+      clearInitialRenderError(result.collection, queryInfo.client)
+    } else if (initialRenderError && !hasBeenReadyRef.current) {
+      promiseRef.current = null
+      throw toBoundaryError(initialRenderError.error)
+    }
+
+    // A failed first load throws only before the first ready; later sync
+    // problems surface in `health` with the data kept (as in TanStack Query).
+    // A crash throws at any time: the Collection can no longer serve reads.
+    if (
+      collectionStatus === `crashed` ||
+      (collectionStatus === `error` && !hasBeenReadyRef.current)
+    ) {
+      promiseRef.current = null
+      throw toBoundaryError(result.collection.health.error?.cause)
+    }
+
+    if (
+      !hasBeenReadyRef.current &&
+      (result.isLoading ||
+        result.isIdle ||
+        result.isLoadingError ||
+        result.isCrashed)
+    ) {
+      // Create or reuse promise for current collection
+      if (!promiseRef.current) {
+        const collection = result.collection
+        const client = queryInfo.client
+        const queryHash = queryInfo.queryHash
+        let active = true
+        const stopWatchingCleanup = collection.once(`status:cleaned-up`, () => {
+          active = false
         })
-        .finally(stopWatchingCleanup)
+        let preload: Promise<void>
+        try {
+          preload = queryInfo.observer.preload()
+        } catch (error) {
+          stopWatchingCleanup()
+          throw error
+        }
+        const preloadClientQuery =
+          client && queryHash ? client._getLiveQuery(queryHash) : undefined
+        promiseRef.current = preload
+          .catch((error: unknown) => {
+            const latestClientQuery =
+              client && queryHash ? client._getLiveQuery(queryHash) : undefined
+            if (active && latestClientQuery === preloadClientQuery)
+              rememberInitialRenderError(
+                collection,
+                client,
+                error,
+                preloadClientQuery,
+              )
+            throw error
+          })
+          .finally(stopWatchingCleanup)
+      }
+      // React Suspense catches this promise and retries after preload settles.
+      throw promiseRef.current
     }
-    // React Suspense catches this promise and retries after preload settles.
-    throw promiseRef.current
-  }
 
-  // Return data without status/loading flags (handled by Suspense/ErrorBoundary)
-  // If error after success, return last known good state (stale data)
-  return {
-    state: result.state,
-    data: result.data,
-    collection: result.collection,
+    // Return data without status/loading flags (handled by Suspense/ErrorBoundary)
+    // If error after success, return last known good state (stale data)
+    return {
+      state: result.state,
+      data: result.data,
+      collection: result.collection,
+      health: result.health,
+    }
+  } catch (error) {
+    if (error instanceof Promise) throw error
+    return rejectLiveQueryInput(queryInfo.deferredCollections, error)
   }
 }

package/src/usePacedMutations.ts

@@ -36,7 +36,7 @@ import type { PacedMutationsConfig, Transaction } from '@tanstack/db'
  *
  *     // Optional: await persistence or handle errors
  *     try {
- *       await tx.isPersisted.promise
+ *       await tx.when('settled')
  *       console.log('Saved!')
  *     } catch (error) {
  *       console.error('Save failed:', error)