@tanstack/react-db 0.2.0 → 0.3.0

package/src/useLiveSuspenseQuery.ts

@@ -1,5 +1,9 @@
+'use client'
+
 import { useRef } from 'react'
 import { useLiveQuery } from './useLiveQuery'
+import { getLiveQueryResultInfo } from './live-query-internals'
+import type { UseLiveQueryConfig } from './useLiveQuery'
 import type {
   Collection,
   Context,
@@ -15,18 +19,19 @@ import type {
 /**
  * Create a live query with React Suspense support
  * @param queryFn - Query function that defines what data to fetch
- * @param deps - Array of dependencies that trigger query re-execution when changed
+ * @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)
  * @example
  * // Basic usage with Suspense
  * function TodoList() {
- *   const { data } = useLiveSuspenseQuery((q) =>
- *     q.from({ todos: todosCollection })
- *      .where(({ todos }) => eq(todos.completed, false))
- *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))
- *   )
+ *   const { data } = useLiveSuspenseQuery({
+ *     query: (q) =>
+ *       q.from({ todos: todosCollection })
+ *        .where(({ todos }) => eq(todos.completed, false))
+ *        .select(({ todos }) => ({ id: todos.id, text: todos.text }))
+ *   })
  *
  *   return (
  *     <ul>
@@ -53,12 +58,11 @@ import type {
  * // data is guaranteed to be the single item (or undefined if not found)
  *
  * @example
- * // With dependencies that trigger re-suspension
- * const { data } = useLiveSuspenseQuery(
- *   (q) => q.from({ todos: todosCollection })
+ * // Structured captured values are included in derived query identity and trigger re-suspension
+ * const { data } = useLiveSuspenseQuery({
+ *   query: (q) => q.from({ todos: todosCollection })
  *          .where(({ todos }) => gt(todos.priority, minPriority)),
- *   [minPriority] // Re-suspends when minPriority changes
- * )
+ * })
  *
  * @example
  * // With Error boundary
@@ -87,9 +91,9 @@ import type {
  * ✅ **Use conditional rendering instead:**
  * ```ts
  * function Profile({ userId }: { userId: string }) {
- *   const { data } = useLiveSuspenseQuery(
- *     (q) => q.from({ users }).where(({ users }) => eq(users.id, userId))
- *   )
+ *   const { data } = useLiveSuspenseQuery({
+ *     query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),
+ *   })
  *   return <div>{data.name}</div>
  * }
  *
@@ -97,12 +101,9 @@ import type {
  * {userId ? <Profile userId={userId} /> : <div>No user</div>}
  * ```
  *
- * ✅ **Or use useLiveQuery for conditional queries:**
+ * ✅ **For optional inputs, conditionally render a component with complete query inputs:**
  * ```ts
- * const { data, isEnabled } = useLiveQuery(
- *   (q) => userId ? q.from({ users }) : undefined,  // ✅ Supported!
- *   [userId]
- * )
+ * {userId ? <Profile userId={userId} /> : <div>No user</div>}
  * ```
  */
 // Overload 1: Accept query function that always returns QueryBuilder
@@ -116,6 +117,15 @@ export function useLiveSuspenseQuery<TContext extends Context>(
 }
 
 // Overload 2: Accept config object
+export function useLiveSuspenseQuery<TContext extends Context>(
+  config: UseLiveQueryConfig<TContext>,
+): {
+  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>,
@@ -125,7 +135,7 @@ export function useLiveSuspenseQuery<TContext extends Context>(
   collection: Collection<GetResult<TContext>, string | number, {}>
 }
 
-// Overload 3: Accept pre-created live query collection
+// Overload 4: Accept pre-created live query collection
 export function useLiveSuspenseQuery<
   TResult extends object,
   TKey extends string | number,
@@ -138,7 +148,7 @@ export function useLiveSuspenseQuery<
   collection: Collection<TResult, TKey, TUtils>
 }
 
-// Overload 4: Accept pre-created live query collection with singleResult: true
+// Overload 5: Accept pre-created live query collection with singleResult: true
 export function useLiveSuspenseQuery<
   TResult extends object,
   TKey extends string | number,
@@ -154,16 +164,20 @@ export function useLiveSuspenseQuery<
 // Implementation - uses useLiveQuery internally and adds Suspense logic
 export function useLiveSuspenseQuery(
   configOrQueryOrCollection: any,
-  deps: Array<unknown> = [],
+  deps?: Array<unknown>,
 ) {
   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 = useLiveQuery(configOrQueryOrCollection, deps)
+  const result =
+    deps === undefined
+      ? useLiveQuery(configOrQueryOrCollection)
+      : useLiveQuery(configOrQueryOrCollection, deps)
+  const queryInfo = getLiveQueryResultInfo(result)
 
-  // Reset promise and ready state when collection changes (deps changed)
+  // Reset promise and ready state when query identity changes
   if (collectionRef.current !== result.collection) {
     promiseRef.current = null
     collectionRef.current = result.collection
@@ -183,16 +197,20 @@ export function useLiveSuspenseQuery(
     )
   }
 
-  // It’s not recommended to suspend a render based on a store value returned by useSyncExternalStore.
-  // result.status is the snapshot from syncExternalStore. We read the fresh status from the collection reference instead.
   const collectionStatus = result.collection.status
 
   // Track when we reach ready state
-  if (collectionStatus === `ready`) {
+  if (result.isReady) {
     hasBeenReadyRef.current = true
     promiseRef.current = null
   }
 
+  const observerError = queryInfo.observer.getError()
+  if (observerError !== undefined && !hasBeenReadyRef.current) {
+    promiseRef.current = null
+    throw observerError
+  }
+
   // 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) {
@@ -202,10 +220,19 @@ export function useLiveSuspenseQuery(
     throw new Error(`Collection "${result.collection.id}" failed to load`)
   }
 
-  if (collectionStatus === `loading` || collectionStatus === `idle`) {
+  if (!hasBeenReadyRef.current && (result.isLoading || result.isIdle)) {
+    if (queryInfo.client?._isSsrStreamingEnabled() && !queryInfo.queryHash) {
+      const reason = queryInfo.identityError
+        ? `${queryInfo.identityError.reason} at ${queryInfo.identityError.path}`
+        : `the query has no stable identity`
+      throw new Error(
+        `Cannot stream this live query during SSR because ${reason}. Provide an explicit serializable queryKey.`,
+      )
+    }
+
     // Create or reuse promise for current collection
     if (!promiseRef.current) {
-      promiseRef.current = result.collection.preload()
+      promiseRef.current = queryInfo.observer.preload()
     }
     // THROW PROMISE - React Suspense catches this (React 18+ required)
     // Note: We don't check React version here. In React <18, this will be caught