Skip to content
Source
Sign inSign up
TanStack/db

fix(db): clean up optimistic state when server returns a different key #1465

Closedgoatrenterguy(GitHub profile, opens in a new tab)wants to merge 2 commits intomain fromrefs/pull/1465/headopened

Summary

Fixes #1442. When an onInsert/onUpdate/onDelete handler syncs server data back to the collection (via writeInsert, writeUpdate, writeUpsert, writeDelete, or refetch), the optimistic state under the original client key is now correctly removed if the server returns a different key.

Root Cause

Introduced in 9952921e (Virtual props implementation #1213). The pendingOptimisticDirectUpserts set was added to keep optimistic state visible between transaction completion and sync confirmation for correct $synced tracking. However, in recomputeOptimisticState(), completed direct transactions unconditionally re-add their mutation keys to this set on every call — even after commitPendingTransactions already cleared the key. The set is additive and never fully cleared, so entries persist forever when the server confirms under a different key.

Approach

Two coordinated mechanisms in packages/db/src/collection/state.ts:

Mechanism A — Prevent re-adding keys for transactions with sync writes:

  • directTransactionsWithSyncWrites: Set<string> tracks transaction IDs whose handlers committed immediate sync writes (via writeInsert/writeUpdate/writeDelete)
  • processedCompletedTransactions: Set<string> ensures keys are added to pendingOptimisticDirectUpserts at most once per transaction (add-once guard)
  • Together, these prevent recomputeOptimisticState from re-adding keys after sync already confirmed the data

Mechanism B — Orphan cleanup for refetch-with-different-key:

  • After commitPendingTransactions processes sync, keys in pendingOptimisticDirectUpserts that belong to completed direct transactions but aren't in syncedData are removed
  • scheduleTransactionCleanup processes queued syncs before deleting the transaction, so the orphan cleanup can find the completed transaction to identify its keys

The else branch in the completed-transaction loop is split into three cases (direct+first-time, non-direct, direct+already-processed) to prevent concurrent direct transactions from clobbering each other's entries.

FlowResult
writeInsert + different keyfixed — Mechanism A prevents re-adding
writeInsert + same keyfixed — add-once guard prevents re-adding after line 990 clears it
writeUpdate in onUpdate handlerfixed — same mechanism as writeInsert
writeBatch with different keysfixed — same mechanism
refetch + different keyfixed — Mechanism B removes orphaned key
No writeInsert + default refetchsafe — unchanged behavior
No writeInsert + refetch: falsesafe — key survives until external sync

Test plan

Five new tests in packages/query-db-collection/tests/query.test.ts:

  • should not duplicate items when writeInsert uses a different key than the optimistic insert
  • should mark item as synced when writeInsert uses the same key as the optimistic insert
  • should not duplicate items when refetch returns a different key than the optimistic insert
  • should clean up optimistic state when writeUpdate is called in onUpdate handler
  • should not duplicate items when writeBatch uses different keys than the optimistic inserts

Full test suites pass:

  • @tanstack/db: 94 files, 2275 passed, 0 failed
  • @tanstack/query-db-collection: 2 files, 200 passed, 0 failed
    1. More templates

      @tanstack/angular-db

      npm i https://pkg.pr.new/@tanstack/angular-db@1465

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1465

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1465

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1465

      @tanstack/db

      npm i https://pkg.pr.new/@tanstack/db@1465

      @tanstack/db-ivm

      npm i https://pkg.pr.new/@tanstack/db-ivm@1465

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1465

      @tanstack/electric-db-collection

      npm i https://pkg.pr.new/@tanstack/electric-db-collection@1465

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1465

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1465

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1465

      @tanstack/offline-transactions

      npm i https://pkg.pr.new/@tanstack/offline-transactions@1465

      @tanstack/powersync-db-collection

      npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1465

      @tanstack/query-db-collection

      npm i https://pkg.pr.new/@tanstack/query-db-collection@1465

      @tanstack/react-db

      npm i https://pkg.pr.new/@tanstack/react-db@1465

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1465

      @tanstack/rxdb-db-collection

      npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1465

      @tanstack/solid-db

      npm i https://pkg.pr.new/@tanstack/solid-db@1465

      @tanstack/svelte-db

      npm i https://pkg.pr.new/@tanstack/svelte-db@1465

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1465

      @tanstack/trailbase-db-collection

      npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1465

      @tanstack/vue-db

      npm i https://pkg.pr.new/@tanstack/vue-db@1465

      commit: 3b32e48

    2. Closing as superseded by #1547, which fixed the concrete stale optimistic-row bug reported in #1442 and shipped in @tanstack/db 0.6.7. The linked issue is already closed with confirmation from the original reproducer.\n\nThe broader problem of correlating a temporary client key with a different server-assigned key cannot be inferred safely by collection core from the absence or arrival of rows. That identity mapping must come explicitly from the mutation/backend or adapter contract; otherwise delayed sync, filtering, deletion, and an unrelated insert are indistinguishable. The additional transaction-tracking heuristics in this candidate therefore should not be retained as a generic reconciliation mechanism.\n\nThanks @goatrenterguy for the detailed diagnosis, tests, and exploration—the concrete failure helped drive the smaller fix in #1547.

Sign in to join this conversation.