fix(electric): bound refresh wait for on-demand subsets #1575
main fromrefs/pull/1575/head·merged 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 boundedPromise.race()before on-demand subset snapshot requests.
- Adds
.changeset/tame-rn-live-poll-refresh.md- Adds a patch changeset for
@tanstack/electric-db-collection.
- Adds a patch changeset for
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
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@1575commit:
4806c02Size Change: 0 B
Total Size: 125 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size 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 Size Change: 0 B
Total Size: 4.22 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size 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 Code review#
Found 1 issue:
- 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.
🤖 Generated with Claude Code
- If this code review was useful, please react with 👍. Otherwise, react with 👎.- 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
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 load2645+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 exerciseloadSubset’s refresh-error catch path. Make the refresh reject before advancing time, then assertloadSubset()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
kevin-dp(GitHub profile, opens in a new tab) approved these changes
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
📝 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
packages/electric-db-collection/src/electric.ts,.changeset/tame-rn-live-poll-refresh.mdPromise.raceboundsforceDisconnectAndRefresh(), falls through torequestSnapshot, clears its timer infinally, and documents the patch release.packages/electric-db-collection/tests/electric.test.tsEstimated code review effort: 2 (Simple) | ~10 minutes
Sequence Diagram(s)#
Suggested reviewers:
samwillis,kevin-dp,ibarakaiev,amiran-gorgazjan,dawidwraga🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 Generate unit tests (beta)
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