@tanstack/react-db 0.1.40 → 0.1.42

package/dist/cjs/index.cjs

@@ -1,10 +1,12 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const useLiveQuery = require("./useLiveQuery.cjs");
+const useLiveSuspenseQuery = require("./useLiveSuspenseQuery.cjs");
 const usePacedMutations = require("./usePacedMutations.cjs");
 const useLiveInfiniteQuery = require("./useLiveInfiniteQuery.cjs");
 const db = require("@tanstack/db");
 exports.useLiveQuery = useLiveQuery.useLiveQuery;
+exports.useLiveSuspenseQuery = useLiveSuspenseQuery.useLiveSuspenseQuery;
 exports.usePacedMutations = usePacedMutations.usePacedMutations;
 exports.useLiveInfiniteQuery = useLiveInfiniteQuery.useLiveInfiniteQuery;
 Object.defineProperty(exports, "createTransaction", {

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;"}

package/dist/cjs/index.d.cts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.cjs';
+export * from './useLiveSuspenseQuery.cjs';
 export * from './usePacedMutations.cjs';
 export * from './useLiveInfiniteQuery.cjs';
 export * from '@tanstack/db';

package/dist/cjs/useLiveSuspenseQuery.cjs

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const react = require("react");
+const useLiveQuery = require("./useLiveQuery.cjs");
+function useLiveSuspenseQuery(configOrQueryOrCollection, deps = []) {
+  const promiseRef = react.useRef(null);
+  const collectionRef = react.useRef(null);
+  const hasBeenReadyRef = react.useRef(false);
+  const result = useLiveQuery.useLiveQuery(configOrQueryOrCollection, deps);
+  if (collectionRef.current !== result.collection) {
+    promiseRef.current = null;
+    collectionRef.current = result.collection;
+    hasBeenReadyRef.current = false;
+  }
+  if (result.status === `ready`) {
+    hasBeenReadyRef.current = true;
+    promiseRef.current = null;
+  }
+  if (!result.isEnabled) {
+    throw new Error(
+      `useLiveSuspenseQuery does not support disabled queries. Use useLiveQuery instead for conditional queries.`
+    );
+  }
+  if (result.status === `error` && !hasBeenReadyRef.current) {
+    promiseRef.current = null;
+    throw new Error(`Collection "${result.collection.id}" failed to load`);
+  }
+  if (result.status === `loading` || result.status === `idle`) {
+    if (!promiseRef.current) {
+      promiseRef.current = result.collection.preload();
+    }
+    throw promiseRef.current;
+  }
+  return {
+    state: result.state,
+    data: result.data,
+    collection: result.collection
+  };
+}
+exports.useLiveSuspenseQuery = useLiveSuspenseQuery;
+//# sourceMappingURL=useLiveSuspenseQuery.cjs.map

package/dist/cjs/useLiveSuspenseQuery.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLiveSuspenseQuery.cjs","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// 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  // Track when we reach ready state\n  if (result.status === `ready`) {\n    hasBeenReadyRef.current = true\n    promiseRef.current = null\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 - throw error\n    throw new Error(\n      `useLiveSuspenseQuery does not support disabled queries. Use useLiveQuery instead for conditional queries.`\n    )\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 (result.status === `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 (result.status === `loading` || result.status === `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":["useRef","useLiveQuery"],"mappings":";;;;AAyHO,SAAS,qBACd,2BACA,OAAuB,IACvB;AACA,QAAM,aAAaA,MAAAA,OAA6B,IAAI;AACpD,QAAM,gBAAgBA,MAAAA,OAAyC,IAAI;AACnE,QAAM,kBAAkBA,MAAAA,OAAO,KAAK;AAGpC,QAAM,SAASC,aAAAA,aAAa,2BAA2B,IAAI;AAG3D,MAAI,cAAc,YAAY,OAAO,YAAY;AAC/C,eAAW,UAAU;AACrB,kBAAc,UAAU,OAAO;AAC/B,oBAAgB,UAAU;AAAA,EAC5B;AAGA,MAAI,OAAO,WAAW,SAAS;AAC7B,oBAAgB,UAAU;AAC1B,eAAW,UAAU;AAAA,EACvB;AAIA,MAAI,CAAC,OAAO,WAAW;AAErB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAIA,MAAI,OAAO,WAAW,WAAW,CAAC,gBAAgB,SAAS;AACzD,eAAW,UAAU;AAGrB,UAAM,IAAI,MAAM,eAAe,OAAO,WAAW,EAAE,kBAAkB;AAAA,EACvE;AAEA,MAAI,OAAO,WAAW,aAAa,OAAO,WAAW,QAAQ;AAE3D,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;;"}

package/dist/cjs/useLiveSuspenseQuery.d.cts

@@ -0,0 +1,81 @@
+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
+ * @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 }))
+ *   )
+ *
+ *   return (
+ *     <ul>
+ *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading...</div>}>
+ *       <TodoList />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * @example
+ * // Single result query
+ * const { data } = useLiveSuspenseQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => eq(todos.id, 1))
+ *          .findOne()
+ * )
+ * // 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 })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-suspends when minPriority changes
+ * )
+ *
+ * @example
+ * // With Error boundary
+ * function App() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Error loading data</div>}>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         <TodoList />
+ *       </Suspense>
+ *     </ErrorBoundary>
+ *   )
+ * }
+ */
+export declare 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, {}>;
+};
+export declare 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, {}>;
+};
+export declare function useLiveSuspenseQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult): {
+    state: Map<TKey, TResult>;
+    data: Array<TResult>;
+    collection: Collection<TResult, TKey, TUtils>;
+};
+export declare function useLiveSuspenseQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult): {
+    state: Map<TKey, TResult>;
+    data: TResult | undefined;
+    collection: Collection<TResult, TKey, TUtils> & SingleResult;
+};

package/dist/esm/index.d.ts

@@ -1,4 +1,5 @@
 export * from './useLiveQuery.js';
+export * from './useLiveSuspenseQuery.js';
 export * from './usePacedMutations.js';
 export * from './useLiveInfiniteQuery.js';
 export * from '@tanstack/db';

package/dist/esm/index.js

@@ -1,4 +1,5 @@
 import { useLiveQuery } from "./useLiveQuery.js";
+import { useLiveSuspenseQuery } from "./useLiveSuspenseQuery.js";
 import { usePacedMutations } from "./usePacedMutations.js";
 import { useLiveInfiniteQuery } from "./useLiveInfiniteQuery.js";
 export * from "@tanstack/db";
@@ -7,6 +8,7 @@ export {
   createTransaction,
   useLiveInfiniteQuery,
   useLiveQuery,
+  useLiveSuspenseQuery,
   usePacedMutations
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/dist/esm/useLiveSuspenseQuery.d.ts

@@ -0,0 +1,81 @@
+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
+ * @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 }))
+ *   )
+ *
+ *   return (
+ *     <ul>
+ *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading...</div>}>
+ *       <TodoList />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * @example
+ * // Single result query
+ * const { data } = useLiveSuspenseQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => eq(todos.id, 1))
+ *          .findOne()
+ * )
+ * // 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 })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-suspends when minPriority changes
+ * )
+ *
+ * @example
+ * // With Error boundary
+ * function App() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Error loading data</div>}>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         <TodoList />
+ *       </Suspense>
+ *     </ErrorBoundary>
+ *   )
+ * }
+ */
+export declare 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, {}>;
+};
+export declare 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, {}>;
+};
+export declare function useLiveSuspenseQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult): {
+    state: Map<TKey, TResult>;
+    data: Array<TResult>;
+    collection: Collection<TResult, TKey, TUtils>;
+};
+export declare function useLiveSuspenseQuery<TResult extends object, TKey extends string | number, TUtils extends Record<string, any>>(liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult): {
+    state: Map<TKey, TResult>;
+    data: TResult | undefined;
+    collection: Collection<TResult, TKey, TUtils> & SingleResult;
+};

package/dist/esm/useLiveSuspenseQuery.js

@@ -0,0 +1,41 @@
+import { useRef } from "react";
+import { useLiveQuery } from "./useLiveQuery.js";
+function useLiveSuspenseQuery(configOrQueryOrCollection, deps = []) {
+  const promiseRef = useRef(null);
+  const collectionRef = useRef(null);
+  const hasBeenReadyRef = useRef(false);
+  const result = useLiveQuery(configOrQueryOrCollection, deps);
+  if (collectionRef.current !== result.collection) {
+    promiseRef.current = null;
+    collectionRef.current = result.collection;
+    hasBeenReadyRef.current = false;
+  }
+  if (result.status === `ready`) {
+    hasBeenReadyRef.current = true;
+    promiseRef.current = null;
+  }
+  if (!result.isEnabled) {
+    throw new Error(
+      `useLiveSuspenseQuery does not support disabled queries. Use useLiveQuery instead for conditional queries.`
+    );
+  }
+  if (result.status === `error` && !hasBeenReadyRef.current) {
+    promiseRef.current = null;
+    throw new Error(`Collection "${result.collection.id}" failed to load`);
+  }
+  if (result.status === `loading` || result.status === `idle`) {
+    if (!promiseRef.current) {
+      promiseRef.current = result.collection.preload();
+    }
+    throw promiseRef.current;
+  }
+  return {
+    state: result.state,
+    data: result.data,
+    collection: result.collection
+  };
+}
+export {
+  useLiveSuspenseQuery
+};
+//# sourceMappingURL=useLiveSuspenseQuery.js.map

package/dist/esm/useLiveSuspenseQuery.js.map

@@ -0,0 +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// 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  // Track when we reach ready state\n  if (result.status === `ready`) {\n    hasBeenReadyRef.current = true\n    promiseRef.current = null\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 - throw error\n    throw new Error(\n      `useLiveSuspenseQuery does not support disabled queries. Use useLiveQuery instead for conditional queries.`\n    )\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 (result.status === `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 (result.status === `loading` || result.status === `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":";;AAyHO,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;AAGA,MAAI,OAAO,WAAW,SAAS;AAC7B,oBAAgB,UAAU;AAC1B,eAAW,UAAU;AAAA,EACvB;AAIA,MAAI,CAAC,OAAO,WAAW;AAErB,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAIA,MAAI,OAAO,WAAW,WAAW,CAAC,gBAAgB,SAAS;AACzD,eAAW,UAAU;AAGrB,UAAM,IAAI,MAAM,eAAe,OAAO,WAAW,EAAE,kBAAkB;AAAA,EACvE;AAEA,MAAI,OAAO,WAAW,aAAa,OAAO,WAAW,QAAQ;AAE3D,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;"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/react-db",
   "description": "React integration for @tanstack/db",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "author": "Kyle Mathews",
   "license": "MIT",
   "repository": {
@@ -17,7 +17,7 @@
   ],
   "dependencies": {
     "use-sync-external-store": "^1.6.0",
-    "@tanstack/db": "0.4.18"
+    "@tanstack/db": "0.4.19"
   },
   "devDependencies": {
     "@electric-sql/client": "1.1.0",

package/src/index.ts

@@ -1,5 +1,6 @@
 // Re-export all public APIs
 export * from "./useLiveQuery"
+export * from "./useLiveSuspenseQuery"
 export * from "./usePacedMutations"
 export * from "./useLiveInfiniteQuery"
 

package/src/useLiveSuspenseQuery.ts

@@ -0,0 +1,182 @@
+import { useRef } from "react"
+import { useLiveQuery } from "./useLiveQuery"
+import type {
+  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
+ * @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 }))
+ *   )
+ *
+ *   return (
+ *     <ul>
+ *       {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
+ *     </ul>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<div>Loading...</div>}>
+ *       <TodoList />
+ *     </Suspense>
+ *   )
+ * }
+ *
+ * @example
+ * // Single result query
+ * const { data } = useLiveSuspenseQuery(
+ *   (q) => q.from({ todos: todosCollection })
+ *          .where(({ todos }) => eq(todos.id, 1))
+ *          .findOne()
+ * )
+ * // 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 })
+ *          .where(({ todos }) => gt(todos.priority, minPriority)),
+ *   [minPriority] // Re-suspends when minPriority changes
+ * )
+ *
+ * @example
+ * // With Error boundary
+ * function App() {
+ *   return (
+ *     <ErrorBoundary fallback={<div>Error loading data</div>}>
+ *       <Suspense fallback={<div>Loading...</div>}>
+ *         <TodoList />
+ *       </Suspense>
+ *     </ErrorBoundary>
+ *   )
+ * }
+ */
+// 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, {}>
+}
+
+// Overload 2: Accept 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, {}>
+}
+
+// Overload 3: Accept pre-created live query collection
+export function useLiveSuspenseQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & NonSingleResult
+): {
+  state: Map<TKey, TResult>
+  data: Array<TResult>
+  collection: Collection<TResult, TKey, TUtils>
+}
+
+// Overload 4: Accept pre-created live query collection with singleResult: true
+export function useLiveSuspenseQuery<
+  TResult extends object,
+  TKey extends string | number,
+  TUtils extends Record<string, any>,
+>(
+  liveQueryCollection: Collection<TResult, TKey, TUtils> & SingleResult
+): {
+  state: Map<TKey, TResult>
+  data: TResult | undefined
+  collection: Collection<TResult, TKey, TUtils> & SingleResult
+}
+
+// Implementation - uses useLiveQuery internally and adds Suspense logic
+export function useLiveSuspenseQuery(
+  configOrQueryOrCollection: any,
+  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)
+
+  // Reset promise and ready state when collection changes (deps changed)
+  if (collectionRef.current !== result.collection) {
+    promiseRef.current = null
+    collectionRef.current = result.collection
+    hasBeenReadyRef.current = false
+  }
+
+  // Track when we reach ready state
+  if (result.status === `ready`) {
+    hasBeenReadyRef.current = true
+    promiseRef.current = null
+  }
+
+  // SUSPENSE LOGIC: Throw promise or error based on collection status
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  if (!result.isEnabled) {
+    // Suspense queries cannot be disabled - throw error
+    throw new Error(
+      `useLiveSuspenseQuery does not support disabled queries. Use useLiveQuery instead for conditional queries.`
+    )
+  }
+
+  // Only throw errors during initial load (before first ready)
+  // After success, errors surface as stale data (matches TanStack Query behavior)
+  if (result.status === `error` && !hasBeenReadyRef.current) {
+    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`)
+  }
+
+  if (result.status === `loading` || result.status === `idle`) {
+    // Create or reuse promise for current collection
+    if (!promiseRef.current) {
+      promiseRef.current = result.collection.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
+    // by an Error Boundary, which provides a reasonable failure mode.
+    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,
+  }
+}