Skip to content
Source
Sign inSign up
TanStack/db

fix(electric): bound refresh wait for on-demand subsets #1575

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 4 commits intomain fromrefs/pull/1575/headmerged by KyleAMathews(GitHub profile, opens in a new tab)

Summary

On-demand Electric live queries no longer wait indefinitely for forceDisconnectAndRefresh() before requesting subset snapshots. This prevents React Native/Expo-style native fetch implementations that don't promptly abort long polls from keeping live queries in loading until the Electric live poll naturally times out.

Root Cause

For on-demand sync, @tanstack/electric-db-collection asks Electric for a subset snapshot when a live query needs data. If the underlying ShapeStream is already up-to-date, the collection first calls:

await stream.forceDisconnectAndRefresh()

That is intended to abort an in-flight live long-poll and force a fresh stream round-trip before requestSnapshot(). In browsers this normally returns quickly because fetch aborts the long-poll promptly.

Some native fetch implementations, especially React Native/Expo, may not reject/abort long-poll requests promptly. In that case, forceDisconnectAndRefresh() can remain pending until the long-poll times out. Because the live query tracks the subset load promise, the query can keep reporting loading even after rows are present locally.

Approach

Bound the refresh wait with a small timeout:

await Promise.race([
  stream.forceDisconnectAndRefresh(),
  new Promise<void>((resolve) => {
    timeoutId = setTimeout(
      resolve,
      FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS,
    )
  }),
])

If the refresh finishes quickly, behavior is unchanged. If it does not finish within 250ms, the collection proceeds to requestSnapshot() instead of waiting for the long-poll to finish naturally.

Key Invariants

  • requestSnapshot() still runs after the bounded refresh attempt.
  • Refresh errors still go through the existing handleSnapshotError() path.
  • The timeout is only a fallback for the pre-snapshot refresh; it does not change the snapshot request itself.
  • Browser behavior should remain effectively unchanged because aborting the live poll is expected to complete before the timeout.

Non-goals

  • This does not change Electric's long-poll timeout behavior.
  • This does not attempt to detect React Native/Expo specifically.
  • This does not replace or wrap the user's fetchClient.
  • This does not alter eager or progressive initial sync behavior; the affected path is on-demand subset loading after the stream is already up-to-date.

Trade-offs

A fully awaited refresh is slightly stricter, but it can turn native fetch abort quirks into user-visible multi-second or multi-minute loading states. A bounded wait preserves the intended fast path while making the on-demand path resilient when abort is slow or ignored.

The timeout is intentionally short (250ms) because the refresh is only a pre-snapshot optimization. If it cannot complete quickly, making progress with requestSnapshot() is better than holding the live query in loading until the live poll naturally returns.

Verification

pnpm --filter @tanstack/electric-db-collection build
pnpm --filter @tanstack/electric-db-collection test

Both passed.

Note: in a fresh worktree, running the filtered test before building produced type-resolution errors for e2e suite imports of @tanstack/electric-db-collection. Building the package first fixed that, and the package tests passed.

Files changed

  • packages/electric-db-collection/src/electric.ts
    • Adds FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS.
    • Wraps stream.forceDisconnectAndRefresh() in a bounded Promise.race() before on-demand subset snapshot requests.
  • .changeset/tame-rn-live-poll-refresh.md
    • Adds a patch changeset for @tanstack/electric-db-collection.

Summary by CodeRabbit

  • Bug Fixes
    • Improved live query loading when stream refreshes take too long or fail to stop promptly.
    • On-demand data requests now proceed after a brief refresh timeout instead of waiting for long-poll operations to finish.
    • Prevented delayed refresh results from interfering with subsequent snapshot requests.
  • Tests
    • Added coverage for delayed, rejected, and promptly completed stream refreshes, including timer cleanup.
    1. Review Change Stack

      📝 Walkthrough

      Walkthrough

      Bounds Electric stream refresh waits to 250ms before on-demand subset loading requests a snapshot. Timers are cleared after refresh completion, timeout, or rejection, with tests covering each path.

      Changes

      Bounded Electric Stream Refresh

      Layer / File(s)Summary
      Refresh timeout and cleanup logic
      packages/electric-db-collection/src/electric.ts, .changeset/tame-rn-live-poll-refresh.md
      A 250ms Promise.race bounds forceDisconnectAndRefresh(), falls through to requestSnapshot, clears its timer in finally, and documents the patch release.
      Timeout and cleanup validation
      packages/electric-db-collection/tests/electric.test.ts
      Fake-timer tests cover delayed fulfillment, late rejection, early resolution, snapshot invocation, and timer cleanup.

      Estimated code review effort: 2 (Simple) | ~10 minutes

      Sequence Diagram(s)

      sequenceDiagram
        participant LoadSubset
        participant ElectricStream
        participant SnapshotRequest
        LoadSubset->>ElectricStream: forceDisconnectAndRefresh()
        alt resolves within 250ms
          ElectricStream-->>LoadSubset: refresh completes
        else timeout
          LoadSubset->>SnapshotRequest: requestSnapshot()
        end
        LoadSubset->>LoadSubset: clear timeout

      Suggested reviewers: samwillis, kevin-dp, ibarakaiev, amiran-gorgazjan, dawidwraga

      🚥 Pre-merge checks | ✅ 5
      ✅ Passed checks (5 passed)
      Check nameStatusExplanation
      Title check✅ PassedThe title clearly and concisely summarizes the main change: bounding the refresh wait for on-demand subsets.
      Description check✅ PassedThe description covers the change, motivation, implementation, verification, and release impact, even if it doesn't use the exact template headings.
      Docstring Coverage✅ PassedDocstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
      Linked Issues check✅ PassedCheck skipped because no linked issues were found for this pull request.
      Out of Scope Changes check✅ PassedCheck skipped because no linked issues were found for this pull request.
      ✨ Finishing Touches
      📝 Generate docstrings
      • Create stacked PR
      • Commit on current branch
      🧪 Generate unit tests (beta)
      • Create PR with unit tests
      • Commit unit tests in branch `electric-rn-refresh-timeout`

      Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

      ❤️ Share
      Comment `@coderabbitai help` to get the list of available commands.
    2. More templates

      @tanstack/angular-db

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

      @tanstack/browser-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1575

      @tanstack/capacitor-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1575

      @tanstack/cloudflare-durable-objects-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1575

      @tanstack/db

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

      @tanstack/db-ivm

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

      @tanstack/db-sqlite-persistence-core

      npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1575

      @tanstack/electric-db-collection

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

      @tanstack/electron-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1575

      @tanstack/expo-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1575

      @tanstack/node-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1575

      @tanstack/offline-transactions

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

      @tanstack/powersync-db-collection

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

      @tanstack/query-db-collection

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

      @tanstack/react-db

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

      @tanstack/react-native-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1575

      @tanstack/rxdb-db-collection

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

      @tanstack/solid-db

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

      @tanstack/svelte-db

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

      @tanstack/tauri-db-sqlite-persistence

      npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1575

      @tanstack/trailbase-db-collection

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

      @tanstack/vue-db

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

      commit: 4806c02

    3. Size Change: 0 B

      Total Size: 125 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/db/dist/esm/collection/change-events.js1.43 kB
      packages/db/dist/esm/collection/changes.js1.38 kB
      packages/db/dist/esm/collection/cleanup-queue.js810 B
      packages/db/dist/esm/collection/events.js434 B
      packages/db/dist/esm/collection/index.js3.62 kB
      packages/db/dist/esm/collection/indexes.js1.99 kB
      packages/db/dist/esm/collection/lifecycle.js1.69 kB
      packages/db/dist/esm/collection/mutations.js2.47 kB
      packages/db/dist/esm/collection/state.js5.48 kB
      packages/db/dist/esm/collection/subscription.js3.74 kB
      packages/db/dist/esm/collection/sync.js2.88 kB
      packages/db/dist/esm/collection/transaction-metadata.js144 B
      packages/db/dist/esm/deferred.js207 B
      packages/db/dist/esm/errors.js5.1 kB
      packages/db/dist/esm/event-emitter.js748 B
      packages/db/dist/esm/index.js3.16 kB
      packages/db/dist/esm/indexes/auto-index.js829 B
      packages/db/dist/esm/indexes/base-index.js767 B
      packages/db/dist/esm/indexes/basic-index.js2.06 kB
      packages/db/dist/esm/indexes/btree-index.js2.19 kB
      packages/db/dist/esm/indexes/index-registry.js820 B
      packages/db/dist/esm/indexes/reverse-index.js557 B
      packages/db/dist/esm/live-query-adapter.js318 B
      packages/db/dist/esm/local-only.js916 B
      packages/db/dist/esm/local-storage.js2.12 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.js1.47 kB
      packages/db/dist/esm/query/builder/index.js5.84 kB
      packages/db/dist/esm/query/builder/ref-proxy.js1.24 kB
      packages/db/dist/esm/query/compiler/evaluators.js1.89 kB
      packages/db/dist/esm/query/compiler/expressions.js430 B
      packages/db/dist/esm/query/compiler/group-by.js3.56 kB
      packages/db/dist/esm/query/compiler/index.js6.67 kB
      packages/db/dist/esm/query/compiler/joins.js2.5 kB
      packages/db/dist/esm/query/compiler/lazy-targets.js923 B
      packages/db/dist/esm/query/compiler/order-by.js1.74 kB
      packages/db/dist/esm/query/compiler/select.js1.53 kB
      packages/db/dist/esm/query/effect.js4.77 kB
      packages/db/dist/esm/query/expression-helpers.js1.43 kB
      packages/db/dist/esm/query/ir.js1.25 kB
      packages/db/dist/esm/query/live-query-collection.js360 B
      packages/db/dist/esm/query/live/collection-config-builder.js9.1 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/live/utils.js1.81 kB
      packages/db/dist/esm/query/optimizer.js2.92 kB
      packages/db/dist/esm/query/predicate-utils.js2.97 kB
      packages/db/dist/esm/query/query-once.js359 B
      packages/db/dist/esm/query/subset-dedupe.js960 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.js3.04 kB
      packages/db/dist/esm/utils.js927 B
      packages/db/dist/esm/utils/array-utils.js273 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.js1.11 kB
      packages/db/dist/esm/utils/cursor.js457 B
      packages/db/dist/esm/utils/index-optimization.js2.39 kB
      packages/db/dist/esm/utils/type-guards.js157 B
      packages/db/dist/esm/utils/uuid.js449 B
      packages/db/dist/esm/virtual-props.js360 B
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 4.22 kB

      ℹ️ View Unchanged
      FilenameSize
      packages/react-db/dist/esm/index.js249 B
      packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB
      packages/react-db/dist/esm/useLiveQuery.js1.33 kB
      packages/react-db/dist/esm/useLiveQueryEffect.js355 B
      packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B
      packages/react-db/dist/esm/usePacedMutations.js401 B
      compressed-size-action::react-db-package-size
    5. Code review

      Found 1 issue:

      1. The new 250ms refresh-timeout path has no deterministic regression coverage. Existing tests cover refresh fulfillment and rejection, but not a refresh that remains pending past the bound, fallthrough to requestSnapshot(), late settlement, or timer cleanup. AGENTS.md explicitly requires regression tests for bug fixes and async race conditions.

      https://github.com/TanStack/db/blob/56f2bf3cdb988e6a261783e929f7698ef89f4787/packages/electric-db-collection/src/electric.ts#L488-L507

      🤖 Generated with Claude Code

      - If this code review was useful, please react with 👍. Otherwise, react with 👎.
    6. Actionable comments posted: 1

      🤖 Prompt for all review comments with AI agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      Inline comments:
      In `@packages/electric-db-collection/tests/electric.test.ts`:
      - Around line 2619-2650: Update the test case around loadSubset so rejectRefresh
      is invoked before advancing the fake timer, ensuring the refresh rejection wins
      the race and exercises the refresh-error catch path. Then await the refresh
      rejection and loadSubset, and retain assertions that exactly one snapshot
      request occurs and no timers remain.
      🪄 Autofix (Beta)

      Fix all unresolved CodeRabbit comments on this PR:

      • Push a commit to this branch (recommended)
      • Create a new PR with the fixes

      ℹ️ Review info
      ⚙️ Run configuration

      Configuration used: defaults

      Review profile: CHILL

      Plan: Pro

      Run ID: 357c4487-85be-40aa-9f43-e3ba95034a67

      📥 Commits

      Reviewing files that changed from the base of the PR and between 56f2bf3cdb988e6a261783e929f7698ef89f4787 and 4806c0251e56647a96127434cb972edb9294252b.

      📒 Files selected for processing (1)
      • packages/electric-db-collection/tests/electric.test.ts
      packages/electric-db-collection/tests/electric.test.ts lines 2619 to 2650
      @@ -2567,0 +2630,21 @@
      2630+ electricCollectionOptions({
      2631+ id: `on-demand-refresh-timeout-rejection-test`,
      2632+ shapeOptions: {
      2633+ url: `http://test-url`,
      2634+ params: { table: `test_table` },
      2635+ },
      2636+ syncMode: `on-demand`,
      2637+ getKey: (item: Row) => item.id as number,
      2638+ startSync: true,
      2639+ }),
      2640+ )
      2641+
      2642+ const load = testCollection._sync.loadSubset({ limit: 10 })
      2643+ await vi.advanceTimersByTimeAsync(250)
      2644+ await load
      2645+
      2646+ rejectRefresh(new Error(`late refresh failure`))
      2647+ await expect(refresh).rejects.toThrow(`late refresh failure`)
      2648+ await Promise.resolve()
      2649+ expect(mockRequestSnapshot).toHaveBeenCalledTimes(1)
      2650+ expect(vi.getTimerCount()).toBe(0)

      🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

      Cover rejection before the timeout wins.

      This rejects only after the 250 ms timeout settled Promise.race, so it does not exercise loadSubset’s refresh-error catch path. Make the refresh reject before advancing time, then assert loadSubset() still requests one snapshot and clears the pending timeout.

      🤖 Prompt for AI Agents
      Verify each finding against current code. Fix only still-valid issues, skip the
      rest with a brief reason, keep changes minimal, and validate.
      
      In `@packages/electric-db-collection/tests/electric.test.ts` around lines 2619 -
      2650, Update the test case around loadSubset so rejectRefresh is invoked before
      advancing the fake timer, ensuring the refresh rejection wins the race and
      exercises the refresh-error catch path. Then await the refresh rejection and
      loadSubset, and retain assertions that exactly one snapshot request occurs and
      no timers remain.

      Source: Coding guidelines

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

Sign in to join this conversation.