Skip to content
Source
Sign inSign up
TanStack/db

fix(db): publish one event per key for metadata-only sync commits #1795

Closedelylucas(GitHub profile, opens in a new tab)wants to merge 1 commit intomain fromrefs/pull/1795/headopened

🎯 Changes

Fixes #1767.

Two optimistic writes in a row on the same key blow up on the second one:

Error: Query contributors with the same row key are not congruent

What's going on

When a collection publishes a batch of changes, that batch is a diff, so each key should appear in it at most once. Here it appeared twice, with both events saying the same thing.

The sequence, using a query collection as the example:

  1. You make an optimistic update, and your mutationFn acknowledges it with utils.writeUpsert.
  2. writeUpsert refreshes the query cache, and applying that result records row ownership metadata. That metadata write goes into its own sync transaction — one with no row operations at all, just a metadata entry.
  3. That transaction stays pending while your transaction is persisting.
  4. When your transaction completes, two different code paths each notice the row switching from optimistic to synced ($synced: false → true), and both emit an event for it. Both land in the same published batch.

The guard meant to prevent that double-emit is recentlySyncedKeys, seeded by capturePreSyncVisibleState. But it derived its keys from a sync transaction's row operations only, while commitPendingTransactions derives its keys from operations plus row metadata writes. A metadata-only transaction fell straight through the gap between those two sets.

Downstream, the duplicated diff leaves the live query counting the old row at -2 and the new one at +2. The next optimistic write on that key then leaves two positive contributors with different values, which is exactly what the keyed reduction rejects.

That also explains the shape of the bug report: round one is what corrupts the bookkeeping, and round two is what notices.

The fix

Pull the "which keys does this sync commit touch" derivation into a single helper, collectAffectedKeys, and use it in all three places that ask the question — commitPendingTransactions, capturePreSyncVisibleState, and cancelPendingSyncedTransaction. The bug was those key sets drifting apart, so this keeps them from drifting again rather than just patching the one that was behind.

Behaviour change is limited to the two sites that were missing metadata keys. commitPendingTransactions already had them.

Tests

Two regression tests, both of which fail with the exact error before the fix:

  • packages/db/tests/collection-metadata-only-sync-commit.test.ts — core-level. Drives a metadata-only sync transaction directly through the sync API while an optimistic mutation is in flight, and asserts no published batch ever names one key twice.
  • packages/query-db-collection/tests/optimistic-writeback.test.ts — the reported path, via utils.writeUpsert.

Why the existing tests missed it

The suite covers sync transactions that carry row operations, and covers row metadata, but never a transaction that writes metadata with no row operations while an optimistic mutation is pending — the one shape where the two key sets disagree. The core test above closes that gap, and its "a batch never names a key twice" assertion is the more general form of the invariant, so it should catch other ways of producing a malformed batch too.

Verification

db 3071 · query-db-collection 170 + 114 e2e · electric 242 · react-db 161 · offline-transactions 65 · powersync 92 · plus trailbase, rxdb, solid, svelte, vue and angular — all passing, typecheck and lint clean.

One note: collection-events.test.ts > should emit events with correct structure times out under full-suite load on my machine. It does the same on an unmodified main (3 runs out of 3), so it looks pre-existing and unrelated to this change.

✅ Checklist

  • I have tested this code locally with pnpm test.

🚀 Release Impact

  • This change affects published code, and I have generated a changeset.
  • This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

  • Bug Fixes

    • Fixed duplicate change events when synchronizing metadata-only updates.
    • Prevented live queries from becoming inconsistent after repeated optimistic writes to the same record.
    • Ensured synchronized metadata updates correctly participate in change tracking.
  • Tests

    • Added regression coverage for metadata-only synchronization and consecutive optimistic updates.
    1. Review Change Stack

      No actionable comments were generated in the recent review. 🎉

      ℹ️ Recent review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Team

      Run ID: 1ea24d4d-9bc5-4758-8662-0330ef03e21f

      📥 Commits

      Reviewing files that changed from the base of the PR and between 68366ecaeef6c12a13402b558bd4a68d7519442f and d48f28d747b2a187aa085db4ab39ac3ba0de6996.

      📒 Files selected for processing (4)
      • .changeset/fix-metadata-only-sync-duplicate-events.md
      • packages/db/src/collection/state.ts
      • packages/db/tests/collection-metadata-only-sync-commit.test.ts
      • packages/query-db-collection/tests/optimistic-writeback.test.ts

      Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.


      📝 Walkthrough

      Walkthrough

      The collection state now includes metadata-only sync keys when tracking affected rows. Sync commit, cancellation, and pre-sync capture use the shared helper. New regression tests cover duplicate events and consecutive optimistic writebacks.

      Changes

      Metadata-only sync event deduplication

      Layer / File(s)Summary
      Affected-key tracking
      packages/db/src/collection/state.ts
      collectAffectedKeys gathers keys from sync operations and row metadata writes. Sync commit, cancellation, and pre-sync capture use this helper.
      Regression coverage
      packages/db/tests/collection-metadata-only-sync-commit.test.ts, packages/query-db-collection/tests/optimistic-writeback.test.ts, .changeset/fix-metadata-only-sync-duplicate-events.md
      Tests verify unique change batches and two consecutive optimistic writebacks on the same key. The changeset declares a patch release for @tanstack/db.

      Estimated code review effort: 3 (Moderate) | ~20 minutes

      Merge Risk: ⚪ Minimal · up to d48f2

      This localized change prevents duplicate events for metadata-only sync commits and protects optimistic writebacks from corrupting keyed query state; no actionable merge-blocking risk remains after normal checks and review.

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly identifies the primary change: preventing duplicate events for metadata-only sync commits.
      Description check✅ PassedThe description follows the required template. It explains the motivation, implementation, tests, checklist status, release impact, and changeset.
      Linked Issues check✅ PassedThe changes address issue #1767 by aligning affected-key tracking for metadata-only sync transactions. The regression tests cover duplicate event publication and consecutive optimistic writes through …
      Out of Scope Changes check✅ PassedAll changes support the linked issue: the shared helper fixes affected-key tracking, the changeset records the release, and both test files verify the regression paths.
      Docstring Coverage✅ PassedNo functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3…
      Full details: Linked Issues check

      Explanation

      The changes address issue #1767 by aligning affected-key tracking for metadata-only sync transactions. The regression tests cover duplicate event publication and consecutive optimistic writes through the reported writeback path.

      Full details: Docstring Coverage

      Explanation

      No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 3 files. (1 skipped: 1 unsupported.)

      ✨ Finishing Touches
      🧪 Generate unit tests (beta)
      • Create PR with unit tests

      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.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. Closing as superseded by merged #1797, which incorporates and tests one-event-per-key metadata-only sync publication. This branch no longer needs a separate merge.

Sign in to join this conversation.