[fix] synced data not appearing in derived collection during pending optimistic mutation (issue #1017)

[claude]

Summary

Fixes the issue where synced data from a source collection does not appear in a derived (live query) collection while there is a pending optimistic mutation.

Root Cause

When a sync transaction commits while there's a persisting user transaction (optimistic mutation), commitPendingTransactions() was designed to delay processing the sync transaction. However, this also prevented change events from being emitted to subscribers, making the synced data invisible to live query collections.

The issue manifests in applications that use optimistic updates with live queries - synced data arriving during a pending mutation becomes invisible until the mutation completes.

The Fix

Add an else branch to commitPendingTransactions() that emits change events for committed sync operations without modifying syncedData. This approach:

1. Preserves existing behavior: The source collection's state (syncedData) remains unchanged during the persisting transaction, which is the expected behavior per existing tests
2. Enables live query visibility: Subscribers receive events about the new synced data, making it visible immediately in derived collections
3. Avoids conflicts: Skips emitting events for keys that have pending optimistic mutations (optimisticUpserts/optimisticDeletes)

When the persisting transaction completes, the normal reconciliation flow processes the queued sync transactions and updates syncedData.

How to Test

pnpm --filter "@tanstack/db"test -- tests/query/live-query-collection.test.ts -t "synced data visibility"

The test creates:

1. A source collection with controllable sync
2. A derived collection via createLiveQueryCollection
3. An optimistic action that keeps a mutation pending
4. Syncs new data while the mutation is pending
5. Asserts both items are visible in the derived collection

Related

• FixesSynced data does not appear in a derived (live query) collection while there is a pending optimistic mutation. #1017
• Repro PR: [repro] synced data not appearing in derived collection during pending optimistic mutation (issue #1017) #1166

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: 815bf4f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• offline-transactions-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 815bf4f

[github-actions]

Size Change: +159 B (+0.18%)

Total Size: 90.9 kB

Filename	Size	Change
./packages/db/dist/esm/collection/state.js	3.65 kB	+159 B (+4.56%)	🔍

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	1.39 kB
./packages/db/dist/esm/collection/changes.js	1.19 kB
./packages/db/dist/esm/collection/events.js	388 B
./packages/db/dist/esm/collection/index.js	3.32 kB
./packages/db/dist/esm/collection/indexes.js	1.1 kB
./packages/db/dist/esm/collection/lifecycle.js	1.67 kB
./packages/db/dist/esm/collection/mutations.js	2.34 kB
./packages/db/dist/esm/collection/subscription.js	3.62 kB
./packages/db/dist/esm/collection/sync.js	2.41 kB
./packages/db/dist/esm/deferred.js	207 B
./packages/db/dist/esm/errors.js	4.7 kB
./packages/db/dist/esm/event-emitter.js	748 B
./packages/db/dist/esm/index.js	2.69 kB
./packages/db/dist/esm/indexes/auto-index.js	742 B
./packages/db/dist/esm/indexes/base-index.js	766 B
./packages/db/dist/esm/indexes/btree-index.js	1.93 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.1 kB
./packages/db/dist/esm/indexes/reverse-index.js	513 B
./packages/db/dist/esm/local-only.js	837 B
./packages/db/dist/esm/local-storage.js	2.1 kB
./packages/db/dist/esm/optimistic-action.js	359 B
./packages/db/dist/esm/paced-mutations.js	496 B
./packages/db/dist/esm/proxy.js	3.75 kB
./packages/db/dist/esm/query/builder/functions.js	733 B
./packages/db/dist/esm/query/builder/index.js	4.08 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	1.05 kB
./packages/db/dist/esm/query/compiler/evaluators.js	1.42 kB
./packages/db/dist/esm/query/compiler/expressions.js	430 B
./packages/db/dist/esm/query/compiler/group-by.js	1.81 kB
./packages/db/dist/esm/query/compiler/index.js	1.96 kB
./packages/db/dist/esm/query/compiler/joins.js	2 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.45 kB
./packages/db/dist/esm/query/compiler/select.js	1.06 kB
./packages/db/dist/esm/query/expression-helpers.js	1.43 kB
./packages/db/dist/esm/query/ir.js	673 B
./packages/db/dist/esm/query/live-query-collection.js	360 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.42 kB
./packages/db/dist/esm/query/live/collection-registry.js	264 B
./packages/db/dist/esm/query/live/collection-subscriber.js	1.93 kB
./packages/db/dist/esm/query/live/internal.js	145 B
./packages/db/dist/esm/query/optimizer.js	2.56 kB
./packages/db/dist/esm/query/predicate-utils.js	2.97 kB
./packages/db/dist/esm/query/subset-dedupe.js	921 B
./packages/db/dist/esm/scheduler.js	1.3 kB
./packages/db/dist/esm/SortedMap.js	1.3 kB
./packages/db/dist/esm/strategies/debounceStrategy.js	247 B
./packages/db/dist/esm/strategies/queueStrategy.js	428 B
./packages/db/dist/esm/strategies/throttleStrategy.js	246 B
./packages/db/dist/esm/transactions.js	2.9 kB
./packages/db/dist/esm/utils.js	924 B
./packages/db/dist/esm/utils/browser-polyfills.js	304 B
./packages/db/dist/esm/utils/btree.js	5.61 kB
./packages/db/dist/esm/utils/comparison.js	852 B
./packages/db/dist/esm/utils/cursor.js	457 B
./packages/db/dist/esm/utils/index-optimization.js	1.51 kB
./packages/db/dist/esm/utils/type-guards.js	157 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 3.7 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	225 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.17 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.34 kB
./packages/react-db/dist/esm/useLiveSuspenseQuery.js	559 B
./packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}

[kevin-dp]

I'm closing this PR because we want to solve the issue differently. This solution tries to maintain the current semantics but we discussed that we may change the semantics such that we don't delay incoming synced operations:

collections should always apply synced changes — they should always reflect the state of the backend — but live queries can have the ability to opt out of updates — this would be a new option for a query and if you opt out you'd get returned an object that updates when the query updates and a function to apply those to the query.

cc @KyleAMathews@samwillis