Skip to content
Source
Sign inSign up
TanStack/db

feat(db): add network-first initial rendering for persisted collections #1955

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 4 commits intomain fromrefs/pull/1955/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

Showing 30 changed files with 38 additions and 0 deletions (loading 27).

x
0 of 30 viewed, 30 left
11 additions and 0 deletions.changeset/add-network-first-persisted-initial-render.mdAdded
View file
@@ -0,0 +1,11 @@
+---
+'@tanstack/db': minor
+'@tanstack/db-sqlite-persistence-core': minor
+'@tanstack/angular-db': minor
+'@tanstack/react-db': minor
+'@tanstack/solid-db': minor
+'@tanstack/svelte-db': minor
+'@tanstack/vue-db': minor
+---
+​
+Add opt-in network-first initial rendering for eagerly persisted SQLite Collections. `initialRender: { strategy: 'network-first', networkTimeoutMs }` lets React and Solid Suspense render restored rows after the configured deadline (three seconds by default) or a network failure while sync continues. Live-query observers and the Angular, React, Solid, Svelte, and Vue integrations expose `persistedStatus`, `isPersistedReady`, and `persistedError` separately from Collection readiness.
3 additions and 0 deletionsdocs/contributing/glossary.mdModified
View file
@@ -41,6 +41,9 @@
| publication | The boundary that makes one coherent result observable to reads, events, and downstream queries. | Provider return, request settlement, or sync commit by itself. |
| atomic publication | One publication boundary at which state, events, and consumers observe the same result without an intermediate public state. | Any individual `commit()` call or source snapshot. |
| readiness | Evidence that a named consumer may proceed. Always qualify Collection readiness, subscription readiness, or initial-query readiness; they settle at different boundaries. | Provider completion or publication in general. |
+| persisted restore | The eager persisted source Collection's startup read and publication of its durable rows, including an empty snapshot, in the current sync run. | Upstream/provider readiness or an SSR seed. |
+| persisted readiness | An opt-in live-query signal that every source Collection completed persisted restore in the current sync run; it is unavailable if any source did not opt in. | Collection readiness, network availability, or row nonemptiness. |
+| network-first initial render | An opt-in Suspense gate that prefers Collection readiness until a configured deadline or network failure, then permits a completed persisted restore. It does not stop network sync. | The persisted-readiness status itself or a change to ordinary live-query row publication. |
​
`source` names a role in a data flow; it does not own a lifecycle. Do not coin a
`source session`. Use `sync run` for the local Collection sync invocation