Skip to content
Source
Sign inSign up
TanStack/db

Fix syncedData not updating on manual writes in mutationFn #1130

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 5 commits intomain fromrefs/pull/1130/headmerged 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:

  1. User calls collection.update() which creates a transaction
  2. The onUpdate handler fires and makes an async API call (await fetch(...))
  3. During the await, the transaction transitions to persisting state
  4. Handler calls writeUpsert() to update syncedData with server response
  5. Bug: commitPendingTransactions() sees hasPersistingTransaction=true and 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

  1. Manual writes (writeUpsert, etc.) must update syncedData synchronously, regardless of transaction state
  2. 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.
  3. 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 immediate flag
  • Did not expose immediate in 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

FileChanges
packages/db/src/types.tsAdded immediate option to begin() signature with JSDoc
packages/db/src/collection/sync.tsPass immediate option through to pending transaction
packages/db/src/collection/state.tsTrack hasImmediateSync flag, process when true; added comment explaining ordering semantics
packages/query-db-collection/src/manual-sync.tsUse begin({ immediate: true }) for write operations
packages/query-db-collection/tests/query.test.tsRegression test for the async-onUpdate scenario

🤖 Generated with Claude Code

    1. 🦋 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
      NameType
      @tanstack/dbPatch
      @tanstack/query-db-collectionPatch
      @tanstack/angular-dbPatch
      @tanstack/electric-db-collectionPatch
      @tanstack/offline-transactionsPatch
      @tanstack/powersync-db-collectionPatch
      @tanstack/react-dbPatch
      @tanstack/rxdb-db-collectionPatch
      @tanstack/solid-dbPatch
      @tanstack/svelte-dbPatch
      @tanstack/trailbase-db-collectionPatch
      @tanstack/vue-dbPatch

      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

    2. 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@1130

      commit: d75453c

    3. Size Change: +46 B (+0.05%)

      Total Size: 90.6 kB

      FilenameSizeChange
      ./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%)
      ℹ️ View Unchanged
      FilenameSize
      ./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
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 3.47 kB

      ℹ️ View Unchanged
      FilenameSize
      ./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
      compressed-size-action::react-db-package-size
    5. I tested the PR and it solves my issue. I no longer have this "off-by-one" cache problem.

    6. OutdatedResolvedby kevin-dp(GitHub profile, opens in a new tab)
    7. claude[bot](GitHub profile, opens in a new tab)replied on packages/db/src/collection/state.ts line 454

      Claude finished @kevin-dp's task in 46s —— View job


      Tasks

      • Read the current code to locate the boolean checks
      • Simplify t.truncate === true to t.truncate
      • Simplify t.immediate === true to t.immediate
      • Commit and push changes

      Summary

      Simplified the boolean checks in packages/db/src/collection/state.ts:

      • Changed if (t.truncate === true) to if (t.truncate) on line 451
      • Changed if (t.immediate === true) to if (t.immediate) on line 454

      Both changes follow the convention that boolean values don't need explicit equality checks. | Branch

    8. kevin-dp(GitHub profile, opens in a new tab) approved these changes

Sign in to join this conversation.