fix(db): clean up optimistic state when server returns a different key #1465
main fromrefs/pull/1465/head·opened 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 (viawriteInsert/writeUpdate/writeDelete)processedCompletedTransactions: Set<string>ensures keys are added topendingOptimisticDirectUpsertsat most once per transaction (add-once guard)- Together, these prevent
recomputeOptimisticStatefrom re-adding keys after sync already confirmed the data
Mechanism B — Orphan cleanup for refetch-with-different-key:
- After
commitPendingTransactionsprocesses sync, keys inpendingOptimisticDirectUpsertsthat belong to completed direct transactions but aren't insyncedDataare removed scheduleTransactionCleanupprocesses 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.
| Flow | Result |
|---|---|
| writeInsert + different key | fixed — Mechanism A prevents re-adding |
| writeInsert + same key | fixed — add-once guard prevents re-adding after line 990 clears it |
| writeUpdate in onUpdate handler | fixed — same mechanism as writeInsert |
| writeBatch with different keys | fixed — same mechanism |
| refetch + different key | fixed — Mechanism B removes orphaned key |
| No writeInsert + default refetch | safe — unchanged behavior |
| No writeInsert + refetch: false | safe — 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
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.
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
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:
3b32e48