Add useLiveSuspenseQuery hook for React Suspense support

[KyleAMathews]

Introduces a new useLiveSuspenseQuery hook that provides declarative data loading with React Suspense, following TanStack Query's useSuspenseQuery pattern.

Key features:

• React 18+ compatible using the throw promise pattern
• Type-safe API with guaranteed data (never undefined)
• Automatic error handling via Error Boundaries
• Reactive updates after initial load via useSyncExternalStore
• Support for dependency-based re-suspension
• Works with query functions, config objects, and pre-created collections

Example usage:

import { Suspense } from 'react';
import { useLiveSuspenseQuery } from '@tanstack/react-db';

function TodoList() {
  // Data is guaranteed to be defined - no isLoading needed
  const { data } = useLiveSuspenseQuery((q) =>
    q.from({ todos: todosCollection })
      .where(({ todos }) => eq(todos.completed, false))
  );

  return (
    <ul>
      {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
    </ul>
  );
}

function App() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <TodoList />
    </Suspense>
  );
}

Implementation details:

• Throws promises when collection is loading (caught by Suspense)
• Throws errors when collection fails (caught by Error Boundary)
• Reuses promise across re-renders to prevent infinite loops
• Detects dependency changes and creates new collection/promise
• Same TypeScript overloads as useLiveQuery for consistency

Resolves #692

[changeset-bot]

🦋 Changeset detected

Latest commit: 50e5aad

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@tanstack/react-db	Patch
@tanstack/db-example-react-todo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@697

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@697

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@697

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@697

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@697

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@697

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@697

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@697

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@697

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@697

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@697

commit: 50e5aad

[github-actions]

Size Change: 0 B

Total Size: 83.7 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	963 B
./packages/db/dist/esm/collection/changes.js	1.01 kB
./packages/db/dist/esm/collection/events.js	413 B
./packages/db/dist/esm/collection/index.js	3.23 kB
./packages/db/dist/esm/collection/indexes.js	1.16 kB
./packages/db/dist/esm/collection/lifecycle.js	1.8 kB
./packages/db/dist/esm/collection/mutations.js	2.52 kB
./packages/db/dist/esm/collection/state.js	3.79 kB
./packages/db/dist/esm/collection/subscription.js	2.2 kB
./packages/db/dist/esm/collection/sync.js	2.2 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.57 kB
./packages/db/dist/esm/event-emitter.js	798 B
./packages/db/dist/esm/index.js	1.65 kB
./packages/db/dist/esm/indexes/auto-index.js	794 B
./packages/db/dist/esm/indexes/base-index.js	835 B
./packages/db/dist/esm/indexes/btree-index.js	2 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.21 kB
./packages/db/dist/esm/indexes/reverse-index.js	577 B
./packages/db/dist/esm/local-only.js	967 B
./packages/db/dist/esm/local-storage.js	2.33 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.86 kB
./packages/db/dist/esm/query/builder/functions.js	615 B
./packages/db/dist/esm/query/builder/index.js	4.04 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	938 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.55 kB
./packages/db/dist/esm/query/compiler/expressions.js	760 B
./packages/db/dist/esm/query/compiler/group-by.js	2.04 kB
./packages/db/dist/esm/query/compiler/index.js	2.21 kB
./packages/db/dist/esm/query/compiler/joins.js	2.65 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.43 kB
./packages/db/dist/esm/query/compiler/select.js	1.28 kB
./packages/db/dist/esm/query/ir.js	785 B
./packages/db/dist/esm/query/live-query-collection.js	404 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.54 kB
./packages/db/dist/esm/query/live/collection-registry.js	233 B
./packages/db/dist/esm/query/live/collection-subscriber.js	2.11 kB
./packages/db/dist/esm/query/optimizer.js	3.26 kB
./packages/db/dist/esm/scheduler.js	1.29 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	3.05 kB
./packages/db/dist/esm/utils.js	1.01 kB
./packages/db/dist/esm/utils/browser-polyfills.js	365 B
./packages/db/dist/esm/utils/btree.js	6.01 kB
./packages/db/dist/esm/utils/comparison.js	754 B
./packages/db/dist/esm/utils/index-optimization.js	1.73 kB

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 2.89 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	168 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.41 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.31 kB

_{compressed-size-action::react-db-package-size}

[samwillis]

This duplicates most of the code in useLiveQuery, as it's quite complex and has had errors it would be a good idea to try either use the useLiveQuery hook inside this one, or create an abstraction they both use. Same with the type interfaces.

Love the hook though, makes a ton of sense!

[KyleAMathews]

Yeah, agree it's not great it duplicates things – I'll ask it to not

[KyleAMathews]

Ok updated

[mhsnook]

Excellent! I am switching my tanstack router SPA from react-query to react-db and this will be very helpful for me :)