Fix syncedData not updating on manual writes in mutationFn #1130
+138
−5
Conversation
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
…nsactions
Manual write operations (writeInsert, writeUpdate, writeDelete, writeUpsert)
were not updating syncedData when called from within a mutation handler
(e.g., onUpdate with refetch: false). This caused an "off by one" bug where
the cache would show stale data until the next sync operation.
Root cause: commitPendingTransactions() skipped processing sync transactions
when a persisting user transaction was active, but manual writes need to
update syncedData synchronously.
Fix: Add an `immediate` flag to sync transactions. When begin() is called
with { immediate: true }, the transaction bypasses the persisting transaction
check and is processed immediately. Manual write operations now use this flag.
Changes:
- Add `immediate?: boolean` to PendingSyncedTransaction interface
- Update begin() to accept optional { immediate?: boolean } parameter
- Modify commitPendingTransactions() to process immediate transactions
regardless of persisting transaction state
- Update performWriteOperations() to use begin({ immediate: true })
- Add regression test for writeUpsert in onUpdate with refetch: false
🦋 Changeset detectedLatest commit: d75453c The changes in this PR will be included in the next version bump. This PR includes changesets to release 12 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 |
More templates
@tanstack/angular-db
@tanstack/db
@tanstack/db-ivm
@tanstack/electric-db-collection
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: +46 B (+0.05%) Total Size: 90.6 kB
ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 3.47 kB ℹ️ View Unchanged
|
Co-Authored-By: Claude Opus 4.5 <[email protected]>
Co-Authored-By: Claude Opus 4.5 <[email protected]>
When hasImmediateSync or hasTruncateSync is true, we process ALL committed sync transactions, not just the immediate ones. This preserves causal ordering - if we only processed the immediate transaction, earlier non-immediate ones would apply later and could overwrite newer state. Co-Authored-By: Claude Opus 4.5 <[email protected]>
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.
Summary
Manual write operations (
writeUpsert,writeInsert,writeUpdate,writeDelete) now correctly updatesyncedDatawhen called from within mutation handlers that include async operations. Previously,syncedDatawould appear stale until the next sync cycle.Root Cause
The bug occurs in this sequence:
collection.update()which creates a transactiononUpdatehandler fires and makes an async API call (await fetch(...))await, the transaction transitions topersistingstatewriteUpsert()to updatesyncedDatawith server responsecommitPendingTransactions()seeshasPersistingTransaction=trueand skips processing the sync transactionThe guard
if (!hasPersistingTransaction || hasTruncateSync)exists to prevent sync operations from overwriting in-flight optimistic updates. But manual writes are different—they're intentionally updatingsyncedDatato match server state, and should be processed immediately.Approach
Added an
immediateflag to sync transactions that bypasses the persisting-transaction check:The condition becomes:
Key Invariants
writeUpsert, etc.) must updatesyncedDatasynchronously, regardless of transaction stateNon-goals
immediateflagimmediatein the public API beyond the existing write utilitiesTrade-offs
Alternative considered: Process only the immediate transaction, leaving other committed sync transactions queued.
Rejected because this would break ordering: if you have [syncA, syncB(immediate)] and only process syncB, then syncA would apply later and could overwrite syncB's changes with stale data. Processing all committed transactions together maintains the queue's causal ordering.
Alternative considered: Process all sync transactions immediately regardless of persisting state.
Rejected because this could cause race conditions where a slow sync response overwrites optimistic state that's still being persisted. The
immediateflag is surgical—it only triggers when there's an intentional manual write.Verification
pnpm test -- packages/query-db-collection/tests/query.test.tsThe new test
should update syncedData immediately when writeUpsert is called after async API in onUpdate handlerreproduces the exact bug scenario.Files Changed
packages/db/src/types.tsimmediateoption tobegin()signature with JSDocpackages/db/src/collection/sync.tsimmediateoption through to pending transactionpackages/db/src/collection/state.tshasImmediateSyncflag, process when true; added comment explaining ordering semanticspackages/query-db-collection/src/manual-sync.tsbegin({ immediate: true })for write operationspackages/query-db-collection/tests/query.test.ts🤖 Generated with Claude Code