feat(db): live query without fetching #2179
Open
jchook(GitHub profile, opens in a new tab)wants to merge 13 commits into
main fromrefs/pull/2179/head·opened Showing 19 changed files with 89 additions and 0 deletions (loading 16).
x
@@ -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.
@@ -70,6 +70,7 @@
| 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. |
| 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. |
82 additions and 0 deletions+82-0docs/contributing/oracle-reviews/2026-10-14-local-live-query.mdAddedView file
@@ -0,0 +1,82 @@
+# Live-query automatic-loading review
+