@tanstack/react-db 0.2.0 → 0.3.0

package/dist/esm/useLiveSuspenseQuery.d.ts

@@ -1,19 +1,21 @@
+import { UseLiveQueryConfig } from './useLiveQuery.js';
 import { Collection, Context, GetResult, InferResultType, InitialQueryBuilder, LiveQueryCollectionConfig, NonSingleResult, QueryBuilder, SingleResult } from '@tanstack/db';
 /**
  * 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>
@@ -40,12 +42,11 @@ import { Collection, Context, GetResult, InferResultType, InitialQueryBuilder, L
  * // 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
@@ -74,9 +75,9 @@ import { Collection, Context, GetResult, InferResultType, InitialQueryBuilder, L
  * ✅ **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>
  * }
  *
@@ -84,12 +85,9 @@ import { Collection, Context, GetResult, InferResultType, InitialQueryBuilder, L
  * {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>}
  * ```
  */
 export declare function useLiveSuspenseQuery<TContext extends Context>(queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>, deps?: Array<unknown>): {
@@ -97,6 +95,11 @@ export declare function useLiveSuspenseQuery<TContext extends Context>(queryFn:
     data: InferResultType<TContext>;
     collection: Collection<GetResult<TContext>, string | number, {}>;
 };
+export declare function useLiveSuspenseQuery<TContext extends Context>(config: UseLiveQueryConfig<TContext>): {
+    state: Map<string | number, GetResult<TContext>>;
+    data: InferResultType<TContext>;
+    collection: Collection<GetResult<TContext>, string | number, {}>;
+};
 export declare function useLiveSuspenseQuery<TContext extends Context>(config: LiveQueryCollectionConfig<TContext>, deps?: Array<unknown>): {
     state: Map<string | number, GetResult<TContext>>;
     data: InferResultType<TContext>;

package/dist/esm/useLiveSuspenseQuery.js

@@ -1,10 +1,13 @@
+"use client";
 import { useRef } from "react";
 import { useLiveQuery } from "./useLiveQuery.js";
-function useLiveSuspenseQuery(configOrQueryOrCollection, deps = []) {
+import { getLiveQueryResultInfo } from "./live-query-internals.js";
+function useLiveSuspenseQuery(configOrQueryOrCollection, deps) {
   const promiseRef = useRef(null);
   const collectionRef = useRef(null);
   const hasBeenReadyRef = useRef(false);
-  const result = useLiveQuery(configOrQueryOrCollection, deps);
+  const result = deps === void 0 ? useLiveQuery(configOrQueryOrCollection) : useLiveQuery(configOrQueryOrCollection, deps);
+  const queryInfo = getLiveQueryResultInfo(result);
   if (collectionRef.current !== result.collection) {
     promiseRef.current = null;
     collectionRef.current = result.collection;
@@ -16,17 +19,28 @@ function useLiveSuspenseQuery(configOrQueryOrCollection, deps = []) {
     );
   }
   const collectionStatus = result.collection.status;
-  if (collectionStatus === `ready`) {
+  if (result.isReady) {
     hasBeenReadyRef.current = true;
     promiseRef.current = null;
   }
+  const observerError = queryInfo.observer.getError();
+  if (observerError !== void 0 && !hasBeenReadyRef.current) {
+    promiseRef.current = null;
+    throw observerError;
+  }
   if (collectionStatus === `error` && !hasBeenReadyRef.current) {
     promiseRef.current = null;
     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.`
+      );
+    }
     if (!promiseRef.current) {
-      promiseRef.current = result.collection.preload();
+      promiseRef.current = queryInfo.observer.preload();
     }
     throw promiseRef.current;
   }

package/dist/esm/useLiveSuspenseQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLiveSuspenseQuery.js","sources":["../../src/useLiveSuspenseQuery.ts"],"sourcesContent":["import { useRef } from 'react'\nimport { useLiveQuery } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\n/**\n * Create a live query with React Suspense support\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data and state - data is guaranteed to be defined\n * @throws Promise when data is loading (caught by Suspense boundary)\n * @throws Error when collection fails (caught by Error boundary)\n * @example\n * // Basic usage with Suspense\n * function TodoList() {\n *   const { data } = useLiveSuspenseQuery((q) =>\n *     q.from({ todos: todosCollection })\n *      .where(({ todos }) => eq(todos.completed, false))\n *      .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n *   )\n *\n *   return (\n *     <ul>\n *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *     </ul>\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <Suspense fallback={<div>Loading...</div>}>\n *       <TodoList />\n *     </Suspense>\n *   )\n * }\n *\n * @example\n * // Single result query\n * const { data } = useLiveSuspenseQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * )\n * // data is guaranteed to be the single item (or undefined if not found)\n *\n * @example\n * // With dependencies that trigger re-suspension\n * const { data } = useLiveSuspenseQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n *   [minPriority] // Re-suspends when minPriority changes\n * )\n *\n * @example\n * // With Error boundary\n * function App() {\n *   return (\n *     <ErrorBoundary fallback={<div>Error loading data</div>}>\n *       <Suspense fallback={<div>Loading...</div>}>\n *         <TodoList />\n *       </Suspense>\n *     </ErrorBoundary>\n *   )\n * }\n *\n * @remarks\n * **Important:** This hook does NOT support disabled queries (returning undefined/null).\n * Following TanStack Query's useSuspenseQuery design, the query callback must always\n * return a valid query, collection, or config object.\n *\n * ❌ **This will cause a type error:**\n * ```ts\n * useLiveSuspenseQuery(\n *   (q) => userId ? q.from({ users }) : undefined  // ❌ Error!\n * )\n * ```\n *\n * ✅ **Use conditional rendering instead:**\n * ```ts\n * function Profile({ userId }: { userId: string }) {\n *   const { data } = useLiveSuspenseQuery(\n *     (q) => q.from({ users }).where(({ users }) => eq(users.id, userId))\n *   )\n *   return <div>{data.name}</div>\n * }\n *\n * // In parent component:\n * {userId ? <Profile userId={userId} /> : <div>No user</div>}\n * ```\n *\n * ✅ **Or use useLiveQuery for conditional queries:**\n * ```ts\n * const { data, isEnabled } = useLiveQuery(\n *   (q) => userId ? q.from({ users }) : undefined,  // ✅ Supported!\n *   [userId]\n * )\n * ```\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveSuspenseQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n}\n\n// Overload 2: Accept config object\nexport function useLiveSuspenseQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n}\n\n// Overload 3: Accept pre-created live query collection\nexport function useLiveSuspenseQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n}\n\n// Overload 4: Accept pre-created live query collection with singleResult: true\nexport function useLiveSuspenseQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n}\n\n// Implementation - uses useLiveQuery internally and adds Suspense logic\nexport function useLiveSuspenseQuery(\n  configOrQueryOrCollection: any,\n  deps: Array<unknown> = [],\n) {\n  const promiseRef = useRef<Promise<void> | null>(null)\n  const collectionRef = useRef<Collection<any, any, any> | null>(null)\n  const hasBeenReadyRef = useRef(false)\n\n  // Use useLiveQuery to handle collection management and reactivity\n  const result = useLiveQuery(configOrQueryOrCollection, deps)\n\n  // Reset promise and ready state when collection changes (deps changed)\n  if (collectionRef.current !== result.collection) {\n    promiseRef.current = null\n    collectionRef.current = result.collection\n    hasBeenReadyRef.current = false\n  }\n\n  // SUSPENSE LOGIC: Throw promise or error based on collection status\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!result.isEnabled) {\n    // Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior\n    throw new Error(\n      `useLiveSuspenseQuery does not support disabled queries (callback returned undefined/null). ` +\n        `The Suspense pattern requires data to always be defined (T, not T | undefined). ` +\n        `Solutions: ` +\n        `1) Use conditional rendering - don't render the component until the condition is met. ` +\n        `2) Use useLiveQuery instead, which supports disabled queries with the 'isEnabled' flag.`,\n    )\n  }\n\n  // It’s not recommended to suspend a render based on a store value returned by useSyncExternalStore.\n  // result.status is the snapshot from syncExternalStore. We read the fresh status from the collection reference instead.\n  const collectionStatus = result.collection.status\n\n  // Track when we reach ready state\n  if (collectionStatus === `ready`) {\n    hasBeenReadyRef.current = true\n    promiseRef.current = null\n  }\n\n  // Only throw errors during initial load (before first ready)\n  // After success, errors surface as stale data (matches TanStack Query behavior)\n  if (collectionStatus === `error` && !hasBeenReadyRef.current) {\n    promiseRef.current = null\n    // TODO: Once collections hold a reference to their last error object (#671),\n    // we should rethrow that actual error instead of creating a generic message\n    throw new Error(`Collection \"${result.collection.id}\" failed to load`)\n  }\n\n  if (collectionStatus === `loading` || collectionStatus === `idle`) {\n    // Create or reuse promise for current collection\n    if (!promiseRef.current) {\n      promiseRef.current = result.collection.preload()\n    }\n    // THROW PROMISE - React Suspense catches this (React 18+ required)\n    // Note: We don't check React version here. In React <18, this will be caught\n    // by an Error Boundary, which provides a reasonable failure mode.\n    throw promiseRef.current\n  }\n\n  // Return data without status/loading flags (handled by Suspense/ErrorBoundary)\n  // If error after success, return last known good state (stale data)\n  return {\n    state: result.state,\n    data: result.data,\n    collection: result.collection,\n  }\n}\n"],"names":[],"mappings":";;AA0JO,SAAS,qBACd,2BACA,OAAuB,IACvB;AACA,QAAM,aAAa,OAA6B,IAAI;AACpD,QAAM,gBAAgB,OAAyC,IAAI;AACnE,QAAM,kBAAkB,OAAO,KAAK;AAGpC,QAAM,SAAS,aAAa,2BAA2B,IAAI;AAG3D,MAAI,cAAc,YAAY,OAAO,YAAY;AAC/C,eAAW,UAAU;AACrB,kBAAc,UAAU,OAAO;AAC/B,oBAAgB,UAAU;AAAA,EAC5B;AAIA,MAAI,CAAC,OAAO,WAAW;AAErB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAMJ;AAIA,QAAM,mBAAmB,OAAO,WAAW;AAG3C,MAAI,qBAAqB,SAAS;AAChC,oBAAgB,UAAU;AAC1B,eAAW,UAAU;AAAA,EACvB;AAIA,MAAI,qBAAqB,WAAW,CAAC,gBAAgB,SAAS;AAC5D,eAAW,UAAU;AAGrB,UAAM,IAAI,MAAM,eAAe,OAAO,WAAW,EAAE,kBAAkB;AAAA,EACvE;AAEA,MAAI,qBAAqB,aAAa,qBAAqB,QAAQ;AAEjE,QAAI,CAAC,WAAW,SAAS;AACvB,iBAAW,UAAU,OAAO,WAAW,QAAA;AAAA,IACzC;AAIA,UAAM,WAAW;AAAA,EACnB;AAIA,SAAO;AAAA,IACL,OAAO,OAAO;AAAA,IACd,MAAM,OAAO;AAAA,IACb,YAAY,OAAO;AAAA,EAAA;AAEvB;"}
+{"version":3,"file":"useLiveSuspenseQuery.js","sources":["../../src/useLiveSuspenseQuery.ts"],"sourcesContent":["'use client'\n\nimport { useRef } from 'react'\nimport { useLiveQuery } from './useLiveQuery'\nimport { getLiveQueryResultInfo } from './live-query-internals'\nimport type { UseLiveQueryConfig } from './useLiveQuery'\nimport type {\n  Collection,\n  Context,\n  GetResult,\n  InferResultType,\n  InitialQueryBuilder,\n  LiveQueryCollectionConfig,\n  NonSingleResult,\n  QueryBuilder,\n  SingleResult,\n} from '@tanstack/db'\n\n/**\n * Create a live query with React Suspense support\n * @param queryFn - Query function that defines what data to fetch\n * @param deps - Deprecated array of dependencies that trigger query re-execution when changed\n * @returns Object with reactive data and state - data is guaranteed to be defined\n * @throws Promise when data is loading (caught by Suspense boundary)\n * @throws Error when collection fails (caught by Error boundary)\n * @example\n * // Basic usage with Suspense\n * function TodoList() {\n *   const { data } = useLiveSuspenseQuery({\n *     query: (q) =>\n *       q.from({ todos: todosCollection })\n *        .where(({ todos }) => eq(todos.completed, false))\n *        .select(({ todos }) => ({ id: todos.id, text: todos.text }))\n *   })\n *\n *   return (\n *     <ul>\n *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}\n *     </ul>\n *   )\n * }\n *\n * function App() {\n *   return (\n *     <Suspense fallback={<div>Loading...</div>}>\n *       <TodoList />\n *     </Suspense>\n *   )\n * }\n *\n * @example\n * // Single result query\n * const { data } = useLiveSuspenseQuery(\n *   (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => eq(todos.id, 1))\n *          .findOne()\n * )\n * // data is guaranteed to be the single item (or undefined if not found)\n *\n * @example\n * // Structured captured values are included in derived query identity and trigger re-suspension\n * const { data } = useLiveSuspenseQuery({\n *   query: (q) => q.from({ todos: todosCollection })\n *          .where(({ todos }) => gt(todos.priority, minPriority)),\n * })\n *\n * @example\n * // With Error boundary\n * function App() {\n *   return (\n *     <ErrorBoundary fallback={<div>Error loading data</div>}>\n *       <Suspense fallback={<div>Loading...</div>}>\n *         <TodoList />\n *       </Suspense>\n *     </ErrorBoundary>\n *   )\n * }\n *\n * @remarks\n * **Important:** This hook does NOT support disabled queries (returning undefined/null).\n * Following TanStack Query's useSuspenseQuery design, the query callback must always\n * return a valid query, collection, or config object.\n *\n * ❌ **This will cause a type error:**\n * ```ts\n * useLiveSuspenseQuery(\n *   (q) => userId ? q.from({ users }) : undefined  // ❌ Error!\n * )\n * ```\n *\n * ✅ **Use conditional rendering instead:**\n * ```ts\n * function Profile({ userId }: { userId: string }) {\n *   const { data } = useLiveSuspenseQuery({\n *     query: (q) => q.from({ users }).where(({ users }) => eq(users.id, userId)),\n *   })\n *   return <div>{data.name}</div>\n * }\n *\n * // In parent component:\n * {userId ? <Profile userId={userId} /> : <div>No user</div>}\n * ```\n *\n * ✅ **For optional inputs, conditionally render a component with complete query inputs:**\n * ```ts\n * {userId ? <Profile userId={userId} /> : <div>No user</div>}\n * ```\n */\n// Overload 1: Accept query function that always returns QueryBuilder\nexport function useLiveSuspenseQuery<TContext extends Context>(\n  queryFn: (q: InitialQueryBuilder) => QueryBuilder<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n}\n\n// Overload 2: Accept config object\nexport function useLiveSuspenseQuery<TContext extends Context>(\n  config: UseLiveQueryConfig<TContext>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n}\n\n// Overload 3: Accept legacy config object\nexport function useLiveSuspenseQuery<TContext extends Context>(\n  config: LiveQueryCollectionConfig<TContext>,\n  deps?: Array<unknown>,\n): {\n  state: Map<string | number, GetResult<TContext>>\n  data: InferResultType<TContext>\n  collection: Collection<GetResult<TContext>, string | number, {}>\n}\n\n// Overload 4: Accept pre-created live query collection\nexport function useLiveSuspenseQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: Array<TResult>\n  collection: Collection<TResult, TKey, TUtils>\n}\n\n// Overload 5: Accept pre-created live query collection with singleResult: true\nexport function useLiveSuspenseQuery<\n  TResult extends object,\n  TKey extends string | number,\n  TUtils extends Record<string, any>,\n>(\n  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult,\n): {\n  state: Map<TKey, TResult>\n  data: TResult | undefined\n  collection: Collection<TResult, TKey, TUtils> & SingleResult\n}\n\n// Implementation - uses useLiveQuery internally and adds Suspense logic\nexport function useLiveSuspenseQuery(\n  configOrQueryOrCollection: any,\n  deps?: Array<unknown>,\n) {\n  const promiseRef = useRef<Promise<void> | null>(null)\n  const collectionRef = useRef<Collection<any, any, any> | null>(null)\n  const hasBeenReadyRef = useRef(false)\n\n  // Use useLiveQuery to handle collection management and reactivity\n  const result =\n    deps === undefined\n      ? useLiveQuery(configOrQueryOrCollection)\n      : useLiveQuery(configOrQueryOrCollection, deps)\n  const queryInfo = getLiveQueryResultInfo(result)\n\n  // Reset promise and ready state when query identity changes\n  if (collectionRef.current !== result.collection) {\n    promiseRef.current = null\n    collectionRef.current = result.collection\n    hasBeenReadyRef.current = false\n  }\n\n  // SUSPENSE LOGIC: Throw promise or error based on collection status\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  if (!result.isEnabled) {\n    // Suspense queries cannot be disabled - this matches TanStack Query's useSuspenseQuery behavior\n    throw new Error(\n      `useLiveSuspenseQuery does not support disabled queries (callback returned undefined/null). ` +\n        `The Suspense pattern requires data to always be defined (T, not T | undefined). ` +\n        `Solutions: ` +\n        `1) Use conditional rendering - don't render the component until the condition is met. ` +\n        `2) Use useLiveQuery instead, which supports disabled queries with the 'isEnabled' flag.`,\n    )\n  }\n\n  const collectionStatus = result.collection.status\n\n  // Track when we reach ready state\n  if (result.isReady) {\n    hasBeenReadyRef.current = true\n    promiseRef.current = null\n  }\n\n  const observerError = queryInfo.observer.getError()\n  if (observerError !== undefined && !hasBeenReadyRef.current) {\n    promiseRef.current = null\n    throw observerError\n  }\n\n  // Only throw errors during initial load (before first ready)\n  // After success, errors surface as stale data (matches TanStack Query behavior)\n  if (collectionStatus === `error` && !hasBeenReadyRef.current) {\n    promiseRef.current = null\n    // TODO: Once collections hold a reference to their last error object (#671),\n    // we should rethrow that actual error instead of creating a generic message\n    throw new Error(`Collection \"${result.collection.id}\" failed to load`)\n  }\n\n  if (!hasBeenReadyRef.current && (result.isLoading || result.isIdle)) {\n    if (queryInfo.client?._isSsrStreamingEnabled() && !queryInfo.queryHash) {\n      const reason = queryInfo.identityError\n        ? `${queryInfo.identityError.reason} at ${queryInfo.identityError.path}`\n        : `the query has no stable identity`\n      throw new Error(\n        `Cannot stream this live query during SSR because ${reason}. Provide an explicit serializable queryKey.`,\n      )\n    }\n\n    // Create or reuse promise for current collection\n    if (!promiseRef.current) {\n      promiseRef.current = queryInfo.observer.preload()\n    }\n    // THROW PROMISE - React Suspense catches this (React 18+ required)\n    // Note: We don't check React version here. In React <18, this will be caught\n    // by an Error Boundary, which provides a reasonable failure mode.\n    throw promiseRef.current\n  }\n\n  // Return data without status/loading flags (handled by Suspense/ErrorBoundary)\n  // If error after success, return last known good state (stale data)\n  return {\n    state: result.state,\n    data: result.data,\n    collection: result.collection,\n  }\n}\n"],"names":[],"mappings":";;;;AAoKO;AAIL;AACA;AACA;AAGA;AAIA;AAGA;AACE;AACA;AACA;AAA0B;AAK5B;AAEE;AAAU;AACR;AAAA;AAQJ;AAGA;AACE;AACA;AAAqB;AAGvB;AACA;AACE;AACA;AAAM;AAKR;AACE;AAGA;AAAqE;AAGvE;AACE;AACE;AAGA;AAAU;AACkD;AAAA;AAK9D;AACE;AAAwC;AAK1C;AAAiB;AAKnB;AAAO;AACS;AACD;AACM;AAEvB;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-db",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "React integration for @tanstack/db",
   "author": "Kyle Mathews",
   "license": "MIT",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.7.1"
+    "@tanstack/db": "0.8.0"
   },
   "peerDependencies": {
     "react": ">=16.8.0"

package/skills/react-db/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: react-db
 description: >
-  React bindings for TanStack DB. useLiveQuery hook with dependency arrays
-  (8 overloads: query function, config object, pre-created collection,
-  disabled state via returning undefined/null). useLiveSuspenseQuery for
+  React bindings for TanStack DB. Prefer useLiveQuery({ query }) with
+  derived structured query identity. Provide queryKey only for opaque
+  functional query variants or very hot render paths. Dependency arrays are
+  legacy and warn before 1.0 removal. useLiveSuspenseQuery for
   React Suspense with Error Boundaries (data always defined).
   useLiveInfiniteQuery for cursor-based pagination (pageSize, fetchNextPage,
   hasNextPage, isFetchingNextPage). usePacedMutations for debounced React
@@ -13,7 +14,7 @@ description: >
 type: framework
 library: db
 framework: react
-library_version: '0.6.0'
+library_version: '0.6.17'
 requires:
   - db-core
 sources:
@@ -30,15 +31,16 @@ This skill builds on db-core. Read it first for collection setup, query builder,
 ## Setup
 
 ```tsx
-import { useLiveQuery, eq, not } from '@tanstack/react-db'
+import { eq, not, useLiveQuery } from '@tanstack/react-db'
 
 function TodoList() {
-  const { data: todos, isLoading } = useLiveQuery((q) =>
-    q
-      .from({ todo: todoCollection })
-      .where(({ todo }) => not(todo.completed))
-      .orderBy(({ todo }) => todo.created_at, 'asc'),
-  )
+  const { data: todos, isLoading } = useLiveQuery({
+    query: (q) =>
+      q
+        .from({ todo: todoCollection })
+        .where(({ todo }) => not(todo.completed))
+        .orderBy(({ todo }) => todo.created_at, 'asc'),
+  })
 
   if (isLoading) return <div>Loading...</div>
 
@@ -59,7 +61,7 @@ function TodoList() {
 ### useLiveQuery
 
 ```tsx
-// Query function with dependency array
+// Preferred config object with derived query identity
 const {
   data,
   state,
@@ -70,15 +72,14 @@ const {
   isError,
   isIdle,
   isCleanedUp,
-} = useLiveQuery(
-  (q) =>
+} = useLiveQuery({
+  query: (q) =>
     q
       .from({ todo: todoCollection })
       .where(({ todo }) => eq(todo.userId, userId)),
-  [userId],
-)
+})
 
-// Config object
+// Static query
 const { data } = useLiveQuery({
   query: (q) => q.from({ todo: todoCollection }),
   gcTime: 60000,
@@ -87,16 +88,13 @@ const { data } = useLiveQuery({
 // Pre-created collection (from route loader)
 const { data } = useLiveQuery(preloadedCollection)
 
-// Conditional query — return undefined/null to disable
-const { data, status } = useLiveQuery(
-  (q) => {
-    if (!userId) return undefined
-    return q
-      .from({ todo: todoCollection })
-      .where(({ todo }) => eq(todo.userId, userId))
-  },
-  [userId],
-)
+// Conditional query — derived identity handles enabled/disabled transitions
+const { data, status } = useLiveQuery((q) => {
+  if (!userId) return undefined
+  return q
+    .from({ todo: todoCollection })
+    .where(({ todo }) => eq(todo.userId, userId))
+})
 // When disabled: status='disabled', data=undefined
 ```
 
@@ -106,9 +104,9 @@ const { data, status } = useLiveQuery(
 // data is ALWAYS defined — never undefined
 // Must wrap in <Suspense> and <ErrorBoundary>
 function TodoList() {
-  const { data: todos } = useLiveSuspenseQuery((q) =>
-    q.from({ todo: todoCollection }),
-  )
+  const { data: todos } = useLiveSuspenseQuery({
+    query: (q) => q.from({ todo: todoCollection }),
+  })
 
   return (
     <ul>
@@ -119,14 +117,13 @@ function TodoList() {
   )
 }
 
-// With deps — re-suspends when deps change
-const { data } = useLiveSuspenseQuery(
-  (q) =>
+// Structured captured values are part of the derived identity and re-suspend when changed
+const { data } = useLiveSuspenseQuery({
+  query: (q) =>
     q
       .from({ todo: todoCollection })
       .where(({ todo }) => eq(todo.category, category)),
-  [category],
-)
+})
 ```
 
 ### useLiveInfiniteQuery
@@ -137,9 +134,11 @@ const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
     (q) =>
       q
         .from({ posts: postsCollection })
+        .where(({ posts }) => eq(posts.category, category))
         .orderBy(({ posts }) => posts.createdAt, 'desc'),
-    { pageSize: 20 },
-    [category],
+    {
+      pageSize: 20,
+    },
   )
 
 // data is the flat array of all loaded pages
@@ -174,16 +173,17 @@ When a query uses includes (subqueries in `select`), each child field is a live
 
 ```tsx
 function ProjectList() {
-  const { data: projects } = useLiveQuery((q) =>
-    q.from({ p: projectsCollection }).select(({ p }) => ({
-      id: p.id,
-      name: p.name,
-      issues: q
-        .from({ i: issuesCollection })
-        .where(({ i }) => eq(i.projectId, p.id))
-        .select(({ i }) => ({ id: i.id, title: i.title })),
-    })),
-  )
+  const { data: projects } = useLiveQuery({
+    query: (q) =>
+      q.from({ p: projectsCollection }).select(({ p }) => ({
+        id: p.id,
+        name: p.name,
+        issues: q
+          .from({ i: issuesCollection })
+          .where(({ i }) => eq(i.projectId, p.id))
+          .select(({ i }) => ({ id: i.id, title: i.title })),
+      })),
+  })
 
   return (
     <ul>
@@ -217,19 +217,20 @@ With `toArray()`, child results are plain arrays and the parent re-renders on ch
 ```tsx
 import { toArray, eq } from '@tanstack/react-db'
 
-const { data: projects } = useLiveQuery((q) =>
-  q.from({ p: projectsCollection }).select(({ p }) => ({
-    id: p.id,
-    name: p.name,
-    issues: toArray(
-      q
-        .from({ i: issuesCollection })
-        .where(({ i }) => eq(i.projectId, p.id))
-        .select(({ i }) => ({ id: i.id, title: i.title })),
-    ),
-  })),
-)
-// project.issues is string[] — no subcomponent needed
+const { data: projects } = useLiveQuery({
+  query: (q) =>
+    q.from({ p: projectsCollection }).select(({ p }) => ({
+      id: p.id,
+      name: p.name,
+      issues: toArray(
+        q
+          .from({ i: issuesCollection })
+          .where(({ i }) => eq(i.projectId, p.id))
+          .select(({ i }) => ({ id: i.id, title: i.title })),
+      ),
+    })),
+})
+// project.issues is Array<{ id: string; title: string }> — no subcomponent needed
 ```
 
 See db-core/live-queries/SKILL.md for full includes rules (correlation conditions, nested includes, aggregates).
@@ -238,7 +239,8 @@ See db-core/live-queries/SKILL.md for full includes rules (correlation condition
 
 Live query results include computed, read-only virtual properties on every row:
 
-- `$synced`: `true` when the row is confirmed by sync; `false` when it is still optimistic.
+- `$synced`: `true` when no pending local optimistic write affects the row;
+  `false` while one does. It does not prove backend confirmation.
 - `$origin`: `"local"` if the last confirmed change came from this client, otherwise `"remote"`.
 - `$key`: the row key for the result.
 - `$collectionId`: the source collection ID.
@@ -246,38 +248,54 @@ Live query results include computed, read-only virtual properties on every row:
 These props are added automatically and can be used in `where`, `select`, and `orderBy` clauses. Do not persist them back to storage.
 
 ```tsx
-const { data } = useLiveQuery(
-  (q) =>
+const { data } = useLiveQuery({
+  query: (q) =>
     q
       .from({ todo: todoCollection })
       .where(({ todo }) => eq(todo.$synced, false)),
-  [],
-)
-// Shows only optimistic (unconfirmed) todos
+})
+// Shows rows with pending local optimistic writes
 ```
 
 ## React-Specific Patterns
 
-### Dependency arrays
+### Query identity
 
 ```tsx
-// Include ALL external reactive values
-const { data } = useLiveQuery(
-  (q) =>
+// Structured captured values are included in the derived identity
+const { data } = useLiveQuery({
+  query: (q) =>
     q
       .from({ todo: todoCollection })
       .where(({ todo }) =>
         and(eq(todo.userId, userId), eq(todo.status, filter)),
       ),
-  [userId, filter],
-)
+})
+
+// Static query
+const { data } = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+})
+```
 
-// Empty array = static query, never re-runs
-const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
+Use `queryKey` only when DB cannot derive identity from structured IR, such as
+`.fn.where`, `.fn.select`, `.fn.having`, or as a deliberate performance escape
+hatch on a hot render path:
 
-// No array = re-runs on every render (usually wrong)
+```tsx
+const { data } = useLiveQuery({
+  queryKey: [todoCollection.id, 'search', search],
+  query: (q) =>
+    q.from({ todo: todoCollection }).fn.where(({ todo }) => {
+      return fuzzyMatch(todo.title, search)
+    }),
+})
 ```
 
+Before 1.0, opaque IR warns and keeps legacy mount-stable identity. Slow or
+repeated derived identity work also warns once. Both point to the same
+`queryKey` escape hatch; unhashable IR without a key will throw in 1.0.
+
 ### Suspense + Error Boundary
 
 ```tsx
@@ -295,36 +313,42 @@ const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }), [])
 await todoCollection.preload()
 
 // In component — data available immediately:
-const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+const { data } = useLiveQuery({
+  query: (q) => q.from({ todo: todoCollection }),
+})
 ```
 
 See meta-framework/SKILL.md for full preloading patterns.
 
 ## Common Mistakes
 
-### CRITICAL Missing external values in dependency array
+### CRITICAL Using opaque query logic without queryKey
 
 Wrong:
 
 ```tsx
-const { data } = useLiveQuery((q) =>
-  q.from({ todo: todoCollection }).where(({ todo }) => eq(todo.userId, userId)),
-)
+const { data } = useLiveQuery({
+  query: (q) =>
+    q.from({ todo: todoCollection }).fn.where(({ todo }) => {
+      return fuzzyMatch(todo.title, search)
+    }),
+})
 ```
 
 Correct:
 
 ```tsx
-const { data } = useLiveQuery(
-  (q) =>
-    q
-      .from({ todo: todoCollection })
-      .where(({ todo }) => eq(todo.userId, userId)),
-  [userId],
-)
+const { data } = useLiveQuery({
+  queryKey: [todoCollection.id, 'search', search],
+  query: (q) =>
+    q.from({ todo: todoCollection }).fn.where(({ todo }) => {
+      return fuzzyMatch(todo.title, search)
+    }),
+})
 ```
 
-When the query uses external state not in the deps array, the query won't re-run when that value changes, showing stale results.
+Structured expressions are hashable by default. Functional query variants are
+opaque runtime code, so they need an explicit key to say when identity changes.
 
 Source: docs/framework/react/overview.md
 
@@ -354,7 +378,12 @@ Source: docs/guides/live-queries.md
 
 ### HIGH "Not a Collection" error from duplicate @tanstack/db
 
-If `useLiveQuery` throws `InvalidSourceError: The value provided for alias "todo" is not a Collection`, it usually means two copies of `@tanstack/db` are installed. The collection was created by one copy, but `useLiveQuery` checks `instanceof` against the other.
+If a query-builder alias throws
+`InvalidSourceError: The value provided for alias "todo" is not a Collection`,
+it can mean two copies of `@tanstack/db` are installed. Direct
+`useLiveQuery(preCreatedCollection)` detection is structural and works across
+package copies or realms, but `q.from({ todo: collection })` still validates
+the source with the core collection class.
 
 In dev mode, TanStack DB also throws `DuplicateDbInstanceError` if two instances are detected.
 
@@ -372,7 +401,7 @@ If multiple versions appear, fix with one of:
 {
   "pnpm": {
     "overrides": {
-      "@tanstack/db": "^0.6.0"
+      "@tanstack/db": "^0.6.17"
     }
   }
 }

package/src/DbProvider.tsx

@@ -0,0 +1,32 @@
+'use client'
+
+import { createContext, useContext } from 'react'
+import type { DbClient } from '@tanstack/db'
+import type { ReactNode } from 'react'
+
+const DbContext = createContext<DbClient | undefined>(undefined)
+
+export type DbProviderProps = {
+  client: DbClient
+  children?: ReactNode
+}
+
+export function DbProvider(props: DbProviderProps) {
+  return (
+    <DbContext.Provider value={props.client}>
+      {props.children}
+    </DbContext.Provider>
+  )
+}
+
+export function useDbClient(): DbClient {
+  const client = useContext(DbContext)
+  if (!client) {
+    throw new Error(`useDbClient must be used within a DbProvider.`)
+  }
+  return client
+}
+
+export function useOptionalDbClient(): DbClient | undefined {
+  return useContext(DbContext)
+}

package/src/HydrationBoundary.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+import { useRef } from 'react'
+import { useDbClient } from './DbProvider'
+import type { DehydratedDbState } from '@tanstack/db'
+import type { ReactNode } from 'react'
+
+export type HydrationBoundaryProps = {
+  state: DehydratedDbState
+  children?: ReactNode
+}
+
+export function HydrationBoundary({ state, children }: HydrationBoundaryProps) {
+  const client = useDbClient()
+  const hydrated = useRef<
+    { client: typeof client; state: DehydratedDbState } | undefined
+  >(undefined)
+
+  if (hydrated.current?.client !== client || hydrated.current.state !== state) {
+    client.hydrate(state)
+    hydrated.current = { client, state }
+  }
+
+  return children
+}

package/src/index.ts

@@ -1,5 +1,12 @@
 // Re-export all public APIs
-export * from './useLiveQuery'
+export { useLiveQuery } from './useLiveQuery'
+export type {
+  LiveQueryKey,
+  UseLiveQueryConfig,
+  UseLiveQueryStatus,
+} from './useLiveQuery'
+export * from './DbProvider'
+export * from './HydrationBoundary'
 export * from './useLiveSuspenseQuery'
 export * from './usePacedMutations'
 export * from './useLiveInfiniteQuery'