Repository navigation
perf(db): preserve row references across metadata snapshots - #2328
Closed
benjavicente wants to merge 1 commit into
Closed
benjavicente wants to merge 1 commit into
benjavicente wants to merge 1 commit into
Conversation
Cache row materialization separately from full observer snapshots. Keep lazy state Maps and data arrays stable across status/health changes while preserving value-only updates, layout changes, and retained point-in-time reads. Law: metadata-only snapshots retain their row containers (maintainer decision 2026-11-01; LiveQuerySnapshot contract). Reach: 52 fixed and 52 random histories cross both observer modes, attached and detached reads, empty/nonempty rows, read order, readiness, health, and writes. RED: unchanged production fails metadata reference equality; seed 1101, path 0:0:0:0, in live-query-observer.row-container-sharing. GREEN: 100 observer tests, 89 existing Angular tests (one TODO), focused types, ESLint, oracle lint, mangle validation, package build, and docs snippets pass on Node 24.8.0. The patch Changeset releases this independently of Angular fixes. Mutant: same-cardinality reuse fails a same-key value write; seed 1101, path 0:0:1:2. The final implementation is restored. Limits: the new lane uses synchronous direct Collections with 0..3 string keys; existing ordered/findOne/hydration suites cover neighboring laws. No new host scheduling or external-provider guarantee.
🦋 Changeset detectedLatest commit: 62d15fa The changes in this PR will be included in the next version bump. This PR includes changesets to release 24 packages
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 |
2 of 4 tasks
Contributor
|
No actionable comments were generated in the recent review.
 |
| Layer / File(s) | Summary |
|---|---|
Cache and reuse observer row containers packages/db/src/live-query-observer.ts, packages/db/mangle-cache.json, .changeset/observer-row-container-sharing.md |
The observer caches row containers by entries-array identity. Metadata-only snapshots reuse the data array and lazy state Map; changed entries produce new containers. Cache change detection compares entries even when a collection revision is available. |
History validation and evidence packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts, packages/db/tests/oracle-config.ts, docs/contributing/oracle-coverage.md, docs/contributing/oracle-reviews/2026-11-01-observer-row-containers.md |
Property histories check row values and container identity across metadata changes and writes. They cover granular and wholesale modes, attached and detached observers, and empty and populated collections. Oracle coverage and review evidence document the lane and its results. |
Estimated code review effort: 3 (Moderate) | ~20 minutes
Change: Refactor
Possibly related issues
- TanStack/db issue 2320: This change addresses observer reuse for metadata-only updates. The issue also covers collection-level reuse after equal selected values, which is outside this change.
Suggested reviewers: kyleamathews, kevin-dp
Merge Risk: 
62d15
-
No merge-blocking issue was established; the change is ready for normal merge checks.
Pre-merge checks: 
-
Check name Status Explanation Resolution Docstring Coverage Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat… Write docstrings for the functions missing them to satisfy the coverage threshold. -
Check name Status Explanation Title check The title clearly and concisely describes the main change: preserving row references across metadata snapshots. Description check The description includes the required Changes, Oracle Coverage, Checklist, and Release Impact sections. It explains the behavior change, test evidence, limits, and changeset. It also accurately states… Linked Issues check Check skipped because no linked issues were found for this pull request. Out of Scope Changes check Check skipped because no linked issues were found for this pull request. Full details: Description check
-
Explanation
The description includes the required Changes, Oracle Coverage, Checklist, and Release Impact sections. It explains the behavior change, test evidence, limits, and changeset. It also accurately states that the full workspace pnpm test suite was not run.
-
Full details: Docstring Coverage
-
Explanation
Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 1 functions across 3 files. (4 skipped: 4 unsupported.)
Resolution
Write docstrings for the functions missing them to satisfy the coverage threshold.
-
Finishing Touches
-
Generate unit tests (beta)
-
- Create a new PR
-
- Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
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.
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/convex-db-collection
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/preact-db
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/react-router-with-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
1 of 3 tasks
Collaborator
|
Thanks for this fix, @benjavicente! I preserved your original commit in #2346 and added stronger oracle coverage and a smaller shared observer cache. Closing this PR in favor of that follow-up. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🎯 Changes
Status-only and health-only observer updates currently rebuild row containers even when the rows have not changed. The new array and Map identities can trigger unnecessary work in consumers that use reference equality.
Cache row materialization separately from the full snapshot. Metadata changes still produce a fresh snapshot with current status and health, while reusing its data array and lazy state Map. Value, membership, and ordering changes remain visible, and retained snapshots keep their capture-time rows.
This complements the Angular fixes in #2327. Its snapshot-based signals follow the current query immediately, and its separate row-state projection can preserve the adapter's defensive Map copy when the observer keeps the same Map reference. Together, the changes avoid unnecessary row-signal value changes and downstream recomputation on metadata-only updates. They do not eliminate all notification or dirty-marking work.
The observer change is independent of the Angular adapter and can merge in either order.
🔬 Oracle Coverage
Owner:
packages/db/tests/live-query-observer-snapshot-oracle.property.test.ts, extended withlive-query-observer.row-container-sharing.packages/db,../../node_modules/.bin/vitest --run --coverage.enabled=false tests/live-query-observer-snapshot-oracle.property.test.ts -t 'metadata snapshots'fails on unchanged production because a metadata transition replaces the data array.Detailed evidence and replay instructions.
✅ Checklist
pnpm test.Affected tests, focused typecheck, ESLint, oracle lint, mangle validation, formatting, package build, and documentation snippet checks pass on Node 24.8.0. The full workspace
pnpm testsuite was not run locally.🚀 Release Impact
Patch changeset for
@tanstack/db.Summary by CodeRabbit