Skip to content
Source
Sign inSign up
TanStack/db

fix(query-db-collection): use deep equality for object field comparison #967

Mergedsamwillis(GitHub profile, opens in a new tab)merged 3 commits intomain fromrefs/pull/967/headmerged by samwillis(GitHub profile, opens in a new tab)

Summary

Fixes #902 where updating object fields (non-primitives) with refetch: false in onUpdate handlers would cause the value to rollback to the previous state every other update.

Fork of the issue sandbox using the preview package from this PR: https://codesandbox.io/p/devbox/tanstack-db-bug-2-forked-8rltvq?workspaceId=ws_DBfSKcjaDqJaXRdZHw8eJ4

The Bug

When using writeUpdate inside an onUpdate handler with refetch: false, updating an object field like metadata: { createdBy: string } would:

  1. First update: Works correctly
  2. Second update: Shows correct value optimistically, then rolls back to the first update's value after server responds

The bug did not occur when:

  • Updating primitive fields (strings, numbers)
  • Using refetch: true

Root Cause

The query observer callback in query.ts used a shallowEqual function to compare items from syncedData with items from the query cache:

const shallowEqual = (obj1, obj2) => {
  // ...
  return keys1.every((key) => {
    if (typeof obj1[key] === 'function') return true
    return obj1[key] === obj2[key]  // ❌ Reference comparison!
  })
}

For primitive values like name: "user456":

  • "user456" === "user456" → true ✓

For object values like metadata: { createdBy: "user456" }:

  • refA === refB → false ❌ (even if both contain identical values)

When shallowEqual returned false due to different object references, the observer would write a sync operation with the query cache value. Due to timing issues with when the query cache gets updated relative to when sync operations are applied, this could write stale data back to syncedData, causing the rollback.

The Fix

Replace the shallow equality check with deep equality:

import { deepEquals } from "@tanstack/db"

const itemsEqual = (obj1, obj2) => {
  return deepEquals(obj1, obj2)
}

Now objects with identical values are considered equal regardless of whether they're the same JavaScript object reference. This prevents unnecessary sync operations that could overwrite correct data with stale data.

Changes

  • Export deepEquals from @tanstack/db
  • Replace shallowEqual with itemsEqual using deepEquals in query observer

Test Plan

  • Added test case that reproduces the issue
  • All existing tests pass
    1. 🦋 Changeset detected

      Latest commit: fea2fb93d2eb18eaf48940c7b02d5dda3010c1e6

      The changes in this PR will be included in the next version bump.

      This PR includes changesets to release 13 packages
      NameType
      @tanstack/query-db-collectionPatch
      @tanstack/dbPatch
      @tanstack/db-collection-e2ePatch
      @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@967

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/electric-db-collection

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

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: fea2fb9

    3. Size Change: +18 B (+0.02%)

      Total Size: 87.2 kB

      FilenameSizeChange
      ./packages/db/dist/esm/index.js2.66 kB+18 B (+0.68%)
      ℹ️ View Unchanged
      FilenameSize
      ./packages/db/dist/esm/collection/change-events.js1.39 kB
      ./packages/db/dist/esm/collection/changes.js977 B
      ./packages/db/dist/esm/collection/events.js388 B
      ./packages/db/dist/esm/collection/index.js3.24 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.31 kB
      ./packages/db/dist/esm/collection/state.js3.43 kB
      ./packages/db/dist/esm/collection/subscription.js2.55 kB
      ./packages/db/dist/esm/collection/sync.js2.37 kB
      ./packages/db/dist/esm/deferred.js207 B
      ./packages/db/dist/esm/errors.js4.19 kB
      ./packages/db/dist/esm/event-emitter.js748 B
      ./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.87 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.js3.96 kB
      ./packages/db/dist/esm/query/builder/ref-proxy.js917 B
      ./packages/db/dist/esm/query/compiler/evaluators.js1.35 kB
      ./packages/db/dist/esm/query/compiler/expressions.js430 B
      ./packages/db/dist/esm/query/compiler/group-by.js1.8 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.25 kB
      ./packages/db/dist/esm/query/compiler/select.js1.07 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.33 kB
      ./packages/db/dist/esm/query/live/collection-registry.js264 B
      ./packages/db/dist/esm/query/live/collection-subscriber.js1.74 kB
      ./packages/db/dist/esm/query/live/internal.js130 B
      ./packages/db/dist/esm/query/optimizer.js2.56 kB
      ./packages/db/dist/esm/query/predicate-utils.js2.91 kB
      ./packages/db/dist/esm/query/subset-dedupe.js921 B
      ./packages/db/dist/esm/scheduler.js1.3 kB
      ./packages/db/dist/esm/SortedMap.js1.18 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.js881 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/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.35 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.js431 B
      ./packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size

Sign in to join this conversation.