RFC: Mutation log reconciliation for optimistic writes#1630
Draft
KyleAMathews wants to merge 32 commits into
Draft
RFC: Mutation log reconciliation for optimistic writes#1630KyleAMathews wants to merge 32 commits into
KyleAMathews wants to merge 32 commits into
Conversation
Contributor
|
Important Review skippedDraft detected. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 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. Comment |
…-state # Conflicts: # packages/db/tests/collection.test.ts
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@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/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: +266 B (+0.21%) Total Size: 125 kB 📦 View Changed
ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 4.26 kB ℹ️ View Unchanged
|
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
1 participant
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.
Summary
Implements Phase 1 of Mutation Log reconciliation for optimistic writes. Committed sync/base updates now apply immediately while unsettled optimistic mutations remain projected in visible collection state, improving reconciliation stability for collections,
subscribeChanges, and live-query consumers.Root Cause
TanStack DB previously treated persisting local transactions as a reason to delay normal committed sync application. That avoided some flicker, but it also meant synced/base state could lag behind while optimistic mutations were active, making materialized visible state and change events depend on delayed-sync branches instead of a single reconciliation model.
Approach
This PR shifts collection state toward the invariant:
Key implementation details:
CollectionStateManager.commitPendingTransactions().$synced: false -> truewhen they are part of subscribed visible values.Key Invariants
Non-goals
This is intentionally limited to the Phase 1 internal reconciliation slice. It does not add:
$hasPendingWrites,$writeStatus,tx.when(...), ordb.mutationsacceptedorobservedTrade-offs
The implementation keeps the existing mutation/transaction primitives instead of introducing a new operation lifecycle. That keeps Phase 1 smaller and aligned with current public vocabulary, but it leaves future public mutation-log/query APIs as follow-up work rather than mixing them into this reconciliation change.
Verification
Local validation during prep:
@tanstack/dbsuite passed before final prep-review fixesFiles changed
packages/db/src/collection/state.ts— immediate sync/base reconciliation, optimistic projection, visible-state diffing, cleanup/confirmation handling.packages/db/src/collection/sync.ts— small sync write adjustment for keyed authoritative payload handling.packages/db/tests/collection.test.ts— direct collection reconciliation regressions.packages/db/tests/collection-subscribe-changes.test.ts— stable change-event, metadata, virtual prop, and confirmation regressions.packages/db/tests/query/live-query-collection.test.tsandpackages/db/tests/query/query-while-syncing.test.ts— live-query behavior under immediate-base reconciliation.docs/rfcs/2026-06-25-mutation-log-reconciliation.md— RFC for the mutation-log reconciliation direction and future/non-Phase-1 boundaries.docs/superpowers/plans/2026-06-29-mutation-log-reconciliation.md— implementation plan/history for this slice..changeset/mutation-log-reconciliation.md— patch changeset for@tanstack/db.