Fix syncedData not updating on manual writes in mutationFn #1130
main fromrefs/pull/1130/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Summary#
Manual write operations (writeUpsert, writeInsert, writeUpdate, writeDelete) now correctly update syncedData when called from within mutation handlers that include async operations. Previously, syncedData would appear stale until the next sync cycle.
Root Cause#
The bug occurs in this sequence:
- User calls
collection.update()which creates a transaction - The
onUpdatehandler fires and makes an async API call (await fetch(...)) - During the
await, the transaction transitions topersistingstate - Handler calls
writeUpsert()to updatesyncedDatawith server response - Bug:
commitPendingTransactions()seeshasPersistingTransaction=trueand skips processing the sync transaction
The guard if (!hasPersistingTransaction || hasTruncateSync) exists to prevent sync operations from overwriting in-flight optimistic updates. But manual writes are different—they're intentionally updating syncedData to match server state, and should be processed immediately.
Approach#
Added an immediate flag to sync transactions that bypasses the persisting-transaction check:
// sync.ts - begin() now accepts options
begin: (options?: { immediate?: boolean }) => {
this.state.pendingSyncedTransactions.push({
committed: false,
operations: [],
deletedKeys: new Set(),
immediate: options?.immediate, // new
})
}
// manual-sync.ts - write operations use immediate: true
ctx.begin({ immediate: true })
The condition becomes:
if (!hasPersistingTransaction || hasTruncateSync || hasImmediateSync) {
// Process sync transactions
}
Key Invariants#
- Manual writes (
writeUpsert, etc.) must updatesyncedDatasynchronously, regardless of transaction state - When an immediate (or truncate) transaction triggers processing, all committed sync transactions are processed together to preserve causal ordering. This prevents earlier non-immediate transactions from being applied later and overwriting newer state.
- Without an immediate/truncate transaction, sync operations wait for persisting transactions to complete
Non-goals#
- Did not change the general sync flow behavior—only manual writes get the
immediateflag - Did not expose
immediatein the public API beyond the existing write utilities
Trade-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 immediate flag is surgical—it only triggers when there's an intentional manual write.
Verification#
pnpm test -- packages/query-db-collection/tests/query.test.ts
The new test should update syncedData immediately when writeUpsert is called after async API in onUpdate handler reproduces the exact bug scenario.
Files Changed#
| File | Changes |
|---|---|
packages/db/src/types.ts | Added immediate option to begin() signature with JSDoc |
packages/db/src/collection/sync.ts | Pass immediate option through to pending transaction |
packages/db/src/collection/state.ts | Track hasImmediateSync flag, process when true; added comment explaining ordering semantics |
packages/query-db-collection/src/manual-sync.ts | Use begin({ immediate: true }) for write operations |
packages/query-db-collection/tests/query.test.ts | Regression test for the async-onUpdate scenario |
🤖 Generated with Claude Code
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1130@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1130@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1130@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1130@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1130@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1130@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1130@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1130@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1130@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1130@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1130@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1130@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1130commit:
d75453cSize Change: +46 B (+0.05%)
Total Size: 90.6 kB
Filename Size Change ./packages/db/dist/esm/collection/state.js3.49 kB +30 B (+0.87%) ./packages/db/dist/esm/collection/sync.js2.4 kB +16 B (+0.67%) compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size ./packages/db/dist/esm/collection/change-events.js1.39 kB ./packages/db/dist/esm/collection/changes.js1.19 kB ./packages/db/dist/esm/collection/events.js388 B ./packages/db/dist/esm/collection/index.js3.32 kB ./packages/db/dist/esm/collection/indexes.js1.1 kB ./packages/db/dist/esm/collection/lifecycle.js1.67 kB ./packages/db/dist/esm/collection/mutations.js2.34 kB ./packages/db/dist/esm/collection/subscription.js3.62 kB ./packages/db/dist/esm/deferred.js207 B ./packages/db/dist/esm/errors.js4.49 kB ./packages/db/dist/esm/event-emitter.js748 B ./packages/db/dist/esm/index.js2.69 kB ./packages/db/dist/esm/indexes/auto-index.js742 B ./packages/db/dist/esm/indexes/base-index.js766 B ./packages/db/dist/esm/indexes/btree-index.js1.93 kB ./packages/db/dist/esm/indexes/lazy-index.js1.1 kB ./packages/db/dist/esm/indexes/reverse-index.js513 B ./packages/db/dist/esm/local-only.js837 B ./packages/db/dist/esm/local-storage.js2.1 kB ./packages/db/dist/esm/optimistic-action.js359 B ./packages/db/dist/esm/paced-mutations.js496 B ./packages/db/dist/esm/proxy.js3.75 kB ./packages/db/dist/esm/query/builder/functions.js733 B ./packages/db/dist/esm/query/builder/index.js4.08 kB ./packages/db/dist/esm/query/builder/ref-proxy.js1.05 kB ./packages/db/dist/esm/query/compiler/evaluators.js1.42 kB ./packages/db/dist/esm/query/compiler/expressions.js430 B ./packages/db/dist/esm/query/compiler/group-by.js1.87 kB ./packages/db/dist/esm/query/compiler/index.js1.96 kB ./packages/db/dist/esm/query/compiler/joins.js2 kB ./packages/db/dist/esm/query/compiler/order-by.js1.45 kB ./packages/db/dist/esm/query/compiler/select.js1.06 kB ./packages/db/dist/esm/query/expression-helpers.js1.43 kB ./packages/db/dist/esm/query/ir.js673 B ./packages/db/dist/esm/query/live-query-collection.js360 B ./packages/db/dist/esm/query/live/collection-config-builder.js5.4 kB ./packages/db/dist/esm/query/live/collection-registry.js264 B ./packages/db/dist/esm/query/live/collection-subscriber.js1.93 kB ./packages/db/dist/esm/query/live/internal.js145 B ./packages/db/dist/esm/query/optimizer.js2.56 kB ./packages/db/dist/esm/query/predicate-utils.js2.97 kB ./packages/db/dist/esm/query/subset-dedupe.js921 B ./packages/db/dist/esm/scheduler.js1.3 kB ./packages/db/dist/esm/SortedMap.js1.3 kB ./packages/db/dist/esm/strategies/debounceStrategy.js247 B ./packages/db/dist/esm/strategies/queueStrategy.js428 B ./packages/db/dist/esm/strategies/throttleStrategy.js246 B ./packages/db/dist/esm/transactions.js2.9 kB ./packages/db/dist/esm/utils.js924 B ./packages/db/dist/esm/utils/browser-polyfills.js304 B ./packages/db/dist/esm/utils/btree.js5.61 kB ./packages/db/dist/esm/utils/comparison.js852 B ./packages/db/dist/esm/utils/cursor.js457 B ./packages/db/dist/esm/utils/index-optimization.js1.51 kB ./packages/db/dist/esm/utils/type-guards.js157 B Size Change: 0 B
Total Size: 3.47 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size ./packages/react-db/dist/esm/index.js225 B ./packages/react-db/dist/esm/useLiveInfiniteQuery.js1.17 kB ./packages/react-db/dist/esm/useLiveQuery.js1.12 kB ./packages/react-db/dist/esm/useLiveSuspenseQuery.js559 B ./packages/react-db/dist/esm/usePacedMutations.js401 B I tested the PR and it solves my issue. I no longer have this "off-by-one" cache problem.
- @@ -437,10 +443,12 @@437443 committedSyncedTransactions,438444 uncommittedSyncedTransactions,439445 hasTruncateSync,446+ hasImmediateSync,440447 } = this.pendingSyncedTransactions.reduce(441448 (acc, t) => {442449 if (t.committed) {443450 acc.committedSyncedTransactions.push(t)444451 if (t.truncate === true) {445452 acc.hasTruncateSync = true446453 }454+ if (t.immediate === true) {
@claude Since
t.immediateis of typebooleanthis can be shortened toif (t.immediate) {. Similarly, fix the same thing 3 lines above for thet.truncatecheck.Claude finished @kevin-dp's task in 46s —— View job
Tasks#
- Read the current code to locate the boolean checks
- Simplify
t.truncate === truetot.truncate - Simplify
t.immediate === truetot.immediate - Commit and push changes
Summary#
Simplified the boolean checks in
packages/db/src/collection/state.ts:- Changed
if (t.truncate === true)toif (t.truncate)on line 451 - Changed
if (t.immediate === true)toif (t.immediate)on line 454
Both changes follow the convention that boolean values don't need explicit equality checks. | Branch
claude[bot](GitHub profile, opens in a new tab)replied on
packages/db/src/collection/state.tsline 454Claude finished @kevin-dp's task in 46s —— View job
Tasks#
- Read the current code to locate the boolean checks
- Simplify
t.truncate === truetot.truncate - Simplify
t.immediate === truetot.immediate - Commit and push changes
Summary#
Simplified the boolean checks in
packages/db/src/collection/state.ts:- Changed
if (t.truncate === true)toif (t.truncate)on line 451 - Changed
if (t.immediate === true)toif (t.immediate)on line 454
Both changes follow the convention that boolean values don't need explicit equality checks. | Branch
kevin-dp(GitHub profile, opens in a new tab) approved these changes
KyleAMathews(GitHub profile, opens in a new tab) closed this
🎉 This PR has been released!
Thank you for your contribution!
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: a3ba9cae2704f99de2b11ccd8ee91ee769b28ee7
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