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

[KyleAMathews]

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.

[coderabbitai]

📝 Walkthrough

Walkthrough

Bounds waiting for Electric stream refreshes to 250ms before on-demand subset loading; if the refresh doesn't finish, the code proceeds to request a snapshot. Timer cleanup is ensured via a finally block. Changeset documents the patch.

Changes

Bounded Electric Stream Refresh

Layer / File(s)	Summary
Release changeset .changeset/tame-rn-live-poll-refresh.md	Changeset entry for @tanstack/electric-db-collection patch documenting the timeout bound on stream refresh waits before on-demand subset loading.
Refresh timeout and cleanup logic packages/electric-db-collection/src/electric.ts	FORCE_DISCONNECT_AND_REFRESH_TIMEOUT_MS constant (250ms) bounds the stream.forceDisconnectAndRefresh() call via Promise.race. If refresh doesn't complete in time, the code proceeds to requestSnapshot. A finally block clears the timeout timer in all cases.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested reviewers

• samwillis

Poem

I nibbled code beneath the moon,
Timed the long poll, hummed a tune—
250 beats, then off we hop,
Snapshot ready, never stop. 🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: bounding the refresh wait timeout for on-demand subsets to prevent loading delays.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description is comprehensive and well-structured, covering changes, root cause, approach, invariants, trade-offs, and verification steps.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

More templates

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

@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: 56f2bf3

[github-actions]

Size Change: 0 B

Total Size: 122 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/collection/change-events.js	1.39 kB
packages/db/dist/esm/collection/changes.js	1.38 kB
packages/db/dist/esm/collection/cleanup-queue.js	810 B
packages/db/dist/esm/collection/events.js	434 B
packages/db/dist/esm/collection/index.js	3.61 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.69 kB
packages/db/dist/esm/collection/mutations.js	2.46 kB
packages/db/dist/esm/collection/state.js	5.33 kB
packages/db/dist/esm/collection/subscription.js	3.74 kB
packages/db/dist/esm/collection/sync.js	2.88 kB
packages/db/dist/esm/collection/transaction-metadata.js	144 B
packages/db/dist/esm/deferred.js	207 B
packages/db/dist/esm/errors.js	5.01 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3.02 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	729 B
packages/db/dist/esm/indexes/basic-index.js	2.05 kB
packages/db/dist/esm/indexes/btree-index.js	2.17 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	538 B
packages/db/dist/esm/local-only.js	890 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	1.4 kB
packages/db/dist/esm/query/builder/index.js	5.84 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.83 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	3.56 kB
packages/db/dist/esm/query/compiler/index.js	6.67 kB
packages/db/dist/esm/query/compiler/joins.js	2.5 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	918 B
packages/db/dist/esm/query/compiler/order-by.js	1.74 kB
packages/db/dist/esm/query/compiler/select.js	1.4 kB
packages/db/dist/esm/query/effect.js	4.77 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir.js	1.25 kB
packages/db/dist/esm/query/live-query-collection.js	360 B
packages/db/dist/esm/query/live/collection-config-builder.js	8.36 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/live/utils.js	1.81 kB
packages/db/dist/esm/query/optimizer.js	2.92 kB
packages/db/dist/esm/query/predicate-utils.js	2.97 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/subset-dedupe.js	960 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	3.02 kB
packages/db/dist/esm/utils.js	927 B
packages/db/dist/esm/utils/array-utils.js	273 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	1.05 kB
packages/db/dist/esm/utils/cursor.js	457 B
packages/db/dist/esm/utils/index-optimization.js	1.54 kB
packages/db/dist/esm/utils/type-guards.js	157 B
packages/db/dist/esm/virtual-props.js	360 B

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

[github-actions]

Size Change: 0 B

Total Size: 4.24 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/index.js	249 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.32 kB
packages/react-db/dist/esm/useLiveQuery.js	1.34 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	567 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

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