fix: render persisted data in Suspense after client stream errors #1960
main fromrefs/pull/1960/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Changes#
React Suspense now renders completed persisted query data when an opted-in client query stream fails. Previously, the hook could throw the stream error or return empty rows before restore completed. This follows up on #1955.
Apps still select initialRender: { strategy: 'network-first' } on each eager persisted source Collection. Every query source must opt in. useLiveSuspenseQuery still prefers Collection readiness until the network deadline. If the client stream fails, the hook waits for every persisted restore. It then renders the derived query result, including a completed empty result. Network sync continues.
The stream can fail before the hook mounts, while restore is pending, or after restore. The observer recognizes the current failed client record in each case. The hook keeps Suspense active until the observer permits fallback.
Errors and retries#
A derived-query failure is not a network fallback signal. It reaches the React ErrorBoundary, even if a client stream also failed. An unconfigured query still reports its client error, including an undefined rejection.
The hook saves definitive initial-render errors across React render retries. A replacement client record does not inherit an old error. Collection cleanup invalidates late errors from the old sync run. Collection readiness clears saved errors.
This PR keeps the existing deadline and all-source opt-in rule. It does not change ordinary useLiveQuery row publication. A mixed query with an unconfigured source still has persistedStatus: 'unavailable'.
Persisted readiness does not prove current authorization. Apps must isolate persisted storage by user or tenant. Apps must block the view separately if a policy denial must hide cached rows.
Verification#
- The persisted-readiness oracle passed 35 tests. Its new cases cover empty and nonempty restore before and after stream failure.
- The oracle also covers a failed stream before observer construction. That case failed before this repair.
- React passed 300 runtime tests. Its new cases cover stream failure before mount, before restore, and after restore.
- React keeps derived-query failures on the ErrorBoundary and preserves client retry and cleanup behavior.
- The observer passed 54 tests. Solid passed 48 focused tests.
- TypeScript checks passed for
@tanstack/db, React DB, and SQLite persistence core. Formatting and changed-file lint checks passed. - Full-package Vitest typecheck still reports cross-package
rootDirerrors. Direct TypeScript project checks passed with the repository root asrootDir.
The existing Solid duplicate-observer optimization remains separate work. The reported reportUpstreamError startup side effect did not reproduce through the source sync callback.
✅ Checklist#
- I have tested this code locally with
pnpm test.
🚀 Release Impact#
- This change affects published code, and I have generated a changeset.
- This change is docs/CI/dev-only (no release).
Summary by CodeRabbit#
- Bug Fixes
- When a client query stream fails during network-first initial rendering, completed persisted data can still be displayed.
- Failures in derived queries continue to reach React Error Boundaries, including when a client query stream has also failed.
- Initial-render errors are isolated between database clients and cleared when a collection restarts or is cleaned up, preventing stale failures from affecting fresh queries.
- 1
More templates
- todos
- offline-transactions-react-native
- shopping-list-react-native
- @tanstack/db-example-react-next-ssr-e2e
- tanstack-start-example-basic
- @tanstack/db-example-paced-mutations-demo
- tanstack-start-db-projects-example
- @tanstack/db-example-react-start-ssr-e2e
- @tanstack/db-example-react-todo
- @tanstack/db-example-solid-todo
- offline-first-electron
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1960@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1960@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1960@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1960@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1960@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1960@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1960@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1960@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1960@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1960@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1960@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1960@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1960@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1960@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1960@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1960@tanstack/react-router-with-db
npm i https://pkg.pr.new/@tanstack/react-router-with-db@1960@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1960@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1960@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1960@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1960@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1960@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1960commit:
3657322Size Change: +106 B (+0.06%)
Total Size: 175 kB
📦 View Changed
Filename Size Change packages/db/dist/esm/live-query-observer.js4.82 kB +106 B (+2.25%) compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/client.js3.7 kB packages/db/dist/esm/collection-options.js236 B packages/db/dist/esm/collection/change-events.js1.45 kB packages/db/dist/esm/collection/changes.js2.41 kB packages/db/dist/esm/collection/cleanup-queue.js822 B packages/db/dist/esm/collection/events.js481 B packages/db/dist/esm/collection/index.js4.46 kB packages/db/dist/esm/collection/indexes.js2.06 kB packages/db/dist/esm/collection/lifecycle.js2.69 kB packages/db/dist/esm/collection/mutations.js2.61 kB packages/db/dist/esm/collection/state.js8.38 kB packages/db/dist/esm/collection/subscription.js8.81 kB packages/db/dist/esm/collection/sync.js5.09 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js5.49 kB packages/db/dist/esm/event-emitter.js964 B packages/db/dist/esm/index.js3.94 kB packages/db/dist/esm/indexes/auto-index.js841 B packages/db/dist/esm/indexes/base-index.js1.26 kB packages/db/dist/esm/indexes/basic-index.js2.05 kB packages/db/dist/esm/indexes/btree-index.js2.33 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js376 B packages/db/dist/esm/live-query-adapter.js318 B packages/db/dist/esm/live-query-options.js731 B packages/db/dist/esm/live-query-window-controller.js4.4 kB packages/db/dist/esm/local-only.js989 B packages/db/dist/esm/local-storage.js2.17 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js702 B packages/db/dist/esm/persisted-readiness.js195 B packages/db/dist/esm/proxy.js3.32 kB packages/db/dist/esm/query/builder/clone-query.js766 B packages/db/dist/esm/query/builder/functions.js1.45 kB packages/db/dist/esm/query/builder/index.js6.82 kB packages/db/dist/esm/query/builder/query-ir.js116 B packages/db/dist/esm/query/builder/ref-proxy-identity.js198 B packages/db/dist/esm/query/builder/ref-proxy.js1.35 kB packages/db/dist/esm/query/builder/wrapper-identity.js221 B packages/db/dist/esm/query/compiler/evaluators.js2.06 kB packages/db/dist/esm/query/compiler/expressions.js603 B packages/db/dist/esm/query/compiler/group-by.js4.16 kB packages/db/dist/esm/query/compiler/index.js9.1 kB packages/db/dist/esm/query/compiler/joins.js2.99 kB packages/db/dist/esm/query/compiler/lazy-targets.js1.13 kB packages/db/dist/esm/query/compiler/order-by.js1.99 kB packages/db/dist/esm/query/compiler/parent-routes.js319 B packages/db/dist/esm/query/compiler/query-equivalence.js455 B packages/db/dist/esm/query/compiler/route-metadata.js1.24 kB packages/db/dist/esm/query/compiler/select.js1.59 kB packages/db/dist/esm/query/effect.js4.98 kB packages/db/dist/esm/query/equality-value-identity.js591 B packages/db/dist/esm/query/expression-helpers.js1.45 kB packages/db/dist/esm/query/ir-stable-identity.js4.22 kB packages/db/dist/esm/query/ir.js1.7 kB packages/db/dist/esm/query/live-query-collection.js391 B packages/db/dist/esm/query/live/bucket-facade-adapter.js2.73 kB packages/db/dist/esm/query/live/collection-config-builder.js6.58 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js2.16 kB packages/db/dist/esm/query/live/graph-scheduler.js303 B packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/materialized-pipeline.js2.32 kB packages/db/dist/esm/query/live/ordered-source-loader.js4.47 kB packages/db/dist/esm/query/live/subset-demand-controller.js1.67 kB packages/db/dist/esm/query/live/utils.js1.2 kB packages/db/dist/esm/query/optimizer.js2.93 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/runtime-reference-identity.js630 B packages/db/dist/esm/query/subset-dedupe.js497 B packages/db/dist/esm/scheduler.js1.14 kB packages/db/dist/esm/SortedMap.js1.63 kB packages/db/dist/esm/strategies/debounceStrategy.js331 B packages/db/dist/esm/strategies/queueStrategy.js488 B packages/db/dist/esm/strategies/throttleStrategy.js386 B packages/db/dist/esm/sync-persistence.js530 B packages/db/dist/esm/transactions.js3.73 kB packages/db/dist/esm/utils.js1.22 kB packages/db/dist/esm/utils/array-utils.js270 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js3.01 kB packages/db/dist/esm/utils/callbacks.js174 B packages/db/dist/esm/utils/comparison.js1.59 kB packages/db/dist/esm/utils/cursor.js677 B packages/db/dist/esm/utils/error.js167 B packages/db/dist/esm/utils/get-or-create.js155 B packages/db/dist/esm/utils/index-optimization.js2.42 kB packages/db/dist/esm/utils/type-guards.js230 B packages/db/dist/esm/utils/uuid.js449 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 8.06 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/DbProvider.js317 B packages/react-db/dist/esm/HydrationBoundary.js263 B packages/react-db/dist/esm/index.js330 B packages/react-db/dist/esm/live-query-internals.js282 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.93 kB packages/react-db/dist/esm/useLiveQuery.js3.3 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js881 B packages/react-db/dist/esm/usePacedMutations.js401 B KyleAMathews(GitHub profile, opens in a new tab) changed the title
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
Navigate logical layers of code changes, visualize relationships, and explore their blast radius.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Advanced
Run ID:
4dc74310-b01d-44ef-8f70-d12aebb37ca7📥 Commits
Reviewing files that changed from the base of the PR and between 7eeff97c53fe589549dd0cf9bb7f0ed6acdf6125 and 365732246e0bc99a8a650d982e3091471f72056a.
📒 Files selected for processing (8)
.changeset/fix-react-persisted-query-error.mddocs/contributing/glossary.mddocs/contributing/oracle-coverage.mdpackages/db-sqlite-persistence-core/tests/persisted-readiness-oracle.test.tspackages/db/src/live-query-observer.tspackages/react-db/src/useLiveSuspenseQuery.tspackages/react-db/tests/useLiveSuspenseQuery-recovery.test.tsxpackages/react-db/tests/useLiveSuspenseQuery.test.tsx🚧 Files skipped from review as they are similar to previous changes (1)
Included review availability: This review used your included allowance. Your plan provides up to 8 included reviews per hour; 6 remain after this review.
📝 Walkthrough
Walkthrough#
The observer now treats a failed client query stream as a network failure during initial rendering when persisted data is complete. The React hook tracks eligible preload failures by collection and client, and surfaces them until readiness or cleanup.
Changes#
Initial-render readiness and React error handling
packages/db/src/live-query-observer.ts,packages/db-sqlite-persistence-core/tests/persisted-readiness-oracle.test.ts,docs/contributing/oracle-coverage.mdpackages/react-db/src/useLiveSuspenseQuery.ts,packages/react-db/tests/useLiveSuspenseQuery*.test.tsx,docs/contributing/glossary.md,.changeset/fix-react-persisted-query-error.mdPriority: ⬇️ Low
Estimated code review effort: 3 (Moderate) | ~25 minutes
Change: Bug fix
Merge Risk: ⚪ Minimal · up to
36573The change enables completed persisted data to render after client-stream failures while preserving query-error handling. No concrete merge-blocking issue is identified; merge after normal checks pass.
Security Architecture Review#
Security architecture risk: 🔵 Low · up to
36573The change preserves important client-isolation and cleanup safeguards. No security vulnerability was established, but rendering persisted data after a failed client request depends on data remaining authorized for the current user. That assumption and one request-recovery edge remain incompletely established.
Retained concerns No architecture-level concerns identified.
Security review details
Security Blast Radius
Trust Boundaries and Controls
Resilience and Maintainability Implications
Hardening Proposals
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
Full details: Docstring Coverage
Explanation
Docstring coverage is 15.38% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files. (3 skipped: 3 unsupported.)
✨ Finishing Touches 💡 1
📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
❤️ Share