Skip to content
Source
Sign inSign up
TanStack/db

feat(db): live query without fetching #2179

Openjchook(GitHub profile, opens in a new tab)wants to merge 13 commits intomain fromrefs/pull/2179/headopened

Showing 19 changed files with 89 additions and 0 deletions (loading 16).

x
0 of 19 viewed, 19 left
6 additions and 0 deletions.changeset/local-query-observation.mdAdded
View file
@@ -0,0 +1,6 @@
+---
+'@tanstack/db': minor
+'@tanstack/react-db': minor
+---
+​
+Add `autoLoad: false` to live-query configuration and React query hooks to observe available rows without initiating source loading. Queries remain reactive across joins and pagination, become ready independently of provider loading, and have separate identities from queries that load data automatically.
1 addition and 0 deletionsdocs/contributing/oracle-coverage.mdModified
View file
@@ -70,6 +70,7 @@
| D2 Index storage | Complete for bounded prefix grammar | The contract, plain-`Map` multiset model, prefixed and unprefixed value grammar, `Index` driver, and per-addition `get`/`has` check are literate. Compaction, presence tracking, and structural payloads remain outside this owner. |
| Pooled live queries | Complete for bounded eq-filter grammar | The contract, independent `eq` model, live-query Collection second formulation, sync/optimistic/mount/cleanup-restart grammar, observer driver, and per-step refinement check are literate. On-demand and persisted sources, `DbClient`, Suspense, and every clause beyond `eq` conjuncts keep the live-query Collection. |
| Live-query deferred acquisition | Complete for bounded synchronous grammar | The law, independent model, history grammar over source states, shapes, and depth, real-Collection driver, and per-step refinement check are literate. Pooled views and DbClient stream preloads have their own blocks. The grammar also adds a peer consumer starting the source and a source truncate before the first subscriber; pinned blocks cover a subscriber that outlives cleanup, reads that wait for readiness, and release of two independent descriptor sources when one start fails. Asynchronous sources, several live-query consumers, and general failure histories stay open. |
+| Live queries with automatic loading disabled | [local evaluation oracle](https://github.com/TanStack/db/blob/main/packages/db/tests/live-query-auto-load-oracle.test.ts), [React boundary tests](https://github.com/TanStack/db/blob/main/packages/react-db/tests/live-query-auto-load.test.tsx), [Query Collection ingestion](https://github.com/TanStack/db/blob/main/packages/query-db-collection/tests/live-query-auto-load.test.ts) | Available-row results and zero acquisition across windows, joins, includes, and lifecycle changes. Covers eager/on-demand sources and explicit index presence/absence. React checks identity isolation, mode changes, and pagination; Query Collection checks direct ingestion without fetching. Excludes remote provider protocols, arbitrary nested plans, and other frameworks. |
| Flat-row change tracking | Complete for bounded flat-row grammar | Flat and proxy trackers and an independent change model run the same generated callbacks. Nested values fall back to the proxy, which its own oracles own. |
| Production error messages | `packages/db/tests/production-error-messages-oracle.test.ts` | Every public error class keeps its development message for frozen sample inputs, and its coded production line shows the JSON of each shown input, even for hostile inputs. Every plain `Error`, `TypeError`, `RangeError`, or `AggregateError` site in `packages/db/src` keeps its frozen development template, has a code, and passes each showable interpolated expression or one of its sub-expressions; the TypeScript checker keeps plain objects, such as rows, out of production lines. A projection of an object, such as `Object.keys(handlers)`, is not required. Every `console` call whose argument holds library text is coded, development-only with its text frozen per guarded region, or a development-only decoration of a value. Text that reaches the console through a parameter, such as `setErrorState(message)`, is coded where it is written; the census cannot follow it. `scripts/test-production-errors.mjs` checks that a production bundle drops the full text and every development-only hint, in ESM and CommonJS. Errors built from a caller's value stay outside this owner. |
| Lazy target path identity | Focused compiler boundary | A same-source union/coalesce witness keeps dotted and nested demand paths distinct during target deduplication. |
82 additions and 0 deletionsdocs/contributing/oracle-reviews/2026-10-14-local-live-query.mdAdded
View file
@@ -0,0 +1,82 @@
+# Live-query automatic-loading review
+​