fix(offline-transactions): infinite retries by default and online-status gating #1301
main fromrefs/pull/1301/head·merged by KyleAMathews(GitHub profile, opens in a new tab) Fix offline transaction retry behavior and add online-status gating#
Transactions were being permanently dropped after 10 failed retries, and retry attempts were wasted while the device was offline. Both issues are now fixed — retries are infinite by default and gated on connectivity.
Root Cause#
Two separate issues in @tanstack/offline-transactions:
DefaultRetryPolicyhardcodedmaxRetries = 10— After 10 transient failures (e.g., a brief server outage), transactions were treated as permanent failures, removed from the outbox, and lost.No online-status awareness in the execution loop — The executor would attempt transactions regardless of connectivity, burning through retries against an unreachable server.
Approach#
Infinite retries by default: Changed DefaultRetryPolicy from maxRetries = 10 to maxRetries = Infinity. Retriable errors (anything that isn't NonRetriableError, AbortError, or a 4xx status) will keep retrying with exponential backoff until the server responds.
Online-status gating: Added isOnline() checks at two points:
TransactionExecutor.runExecution()— breaks out of the batch loop when offlineTransactionExecutor.scheduleNextRetry()— skips scheduling retry timers when offline
When the device comes back online, the OnlineDetector subscription handler resets retry delays and triggers execution immediately.
OnlineDetector.isOnline() is now required on the interface. Both existing implementations (WebOnlineDetector, ReactNativeOnlineDetector) already provided it. Making it required eliminates typeof guards with dangerous return true fallbacks.
OfflineExecutor.notifyOnline() removed — this method was redundant with the OnlineDetector subscription. The detector is the single source of truth for connectivity. Users who need imperative control over online status should implement a custom OnlineDetector.
Key Invariants#
- Retriable errors never stop retrying (only
NonRetriableErrorand specific status codes are permanent) - No transaction execution is attempted while
isOnline()returns false - The
OnlineDetectoris the single source of truth for connectivity — no force flags or override mechanisms
Non-goals#
- Configurable
maxRetries/retryDelay/retryPolicy— stripped from the PR to avoid unnecessary API surface. Can be added when there's demand. - Retry timer suppression test coverage for online→offline→online transitions — the guard logic is simple and the offline→online path is tested.
Trade-offs#
Breaking interface changes shipped as patch: OnlineDetector.isOnline() is now required and OfflineExecutor.notifyOnline() is removed. This is technically a breaking change, but this package is pre-1.0 with very few users, making a patch appropriate.
Verification#
pnpm --filter @tanstack/offline-transactions test
Files changed#
- src/retry/RetryPolicy.ts — Default
maxRetrieschanged from 10 toInfinity - src/executor/TransactionExecutor.ts — Online gating in execution loop and retry scheduling;
TransactionSignalerinterface replacesanytype - src/OfflineExecutor.ts — Removed
notifyOnline(); addedisOnline()method; subscription handler triggers execution on connectivity change - src/connectivity/ReactNativeOnlineDetector.ts — Added
isOnline(), initialNetInfo.fetch(), extractedtoConnectivityState() - src/types.ts —
OnlineDetector.isOnline()now required; addedTransactionSignalerinterface - tests/offline-e2e.test.ts — Regression test for >10 retries; offline execution gating test
- tests/harness.ts — Simplified config passthrough with spread
- README.md — Updated API reference, removed speculative retry config sections
🤖 Generated with Claude Code
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1301@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1301@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1301@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1301@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1301@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1301@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1301@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1301@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1301@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1301@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1301@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1301@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1301commit:
df57939Size Change: 0 B
Total Size: 92.6 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size ./packages/db/dist/esm/collection/change-events.js1.39 kB ./packages/db/dist/esm/collection/changes.js1.22 kB ./packages/db/dist/esm/collection/events.js388 B ./packages/db/dist/esm/collection/index.js3.32 kB ./packages/db/dist/esm/collection/indexes.js1.1 kB ./packages/db/dist/esm/collection/lifecycle.js1.75 kB ./packages/db/dist/esm/collection/mutations.js2.34 kB ./packages/db/dist/esm/collection/state.js3.49 kB ./packages/db/dist/esm/collection/subscription.js3.71 kB ./packages/db/dist/esm/collection/sync.js2.41 kB ./packages/db/dist/esm/deferred.js207 B ./packages/db/dist/esm/errors.js4.7 kB ./packages/db/dist/esm/event-emitter.js748 B ./packages/db/dist/esm/index.js2.7 kB ./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.js2.17 kB ./packages/db/dist/esm/indexes/lazy-index.js1.1 kB ./packages/db/dist/esm/indexes/reverse-index.js538 B ./packages/db/dist/esm/local-only.js808 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.js4.1 kB ./packages/db/dist/esm/query/builder/ref-proxy.js1.05 kB ./packages/db/dist/esm/query/compiler/evaluators.js1.43 kB ./packages/db/dist/esm/query/compiler/expressions.js430 B ./packages/db/dist/esm/query/compiler/group-by.js2.23 kB ./packages/db/dist/esm/query/compiler/index.js2.04 kB ./packages/db/dist/esm/query/compiler/joins.js2.11 kB ./packages/db/dist/esm/query/compiler/order-by.js1.45 kB ./packages/db/dist/esm/query/compiler/select.js1.09 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.55 kB ./packages/db/dist/esm/query/live/collection-registry.js264 B ./packages/db/dist/esm/query/live/collection-subscriber.js2.42 kB ./packages/db/dist/esm/query/live/internal.js145 B ./packages/db/dist/esm/query/optimizer.js2.62 kB ./packages/db/dist/esm/query/predicate-utils.js2.97 kB ./packages/db/dist/esm/query/subset-dedupe.js921 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.js2.9 kB ./packages/db/dist/esm/utils.js924 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.js952 B ./packages/db/dist/esm/utils/cursor.js457 B ./packages/db/dist/esm/utils/index-optimization.js1.51 kB ./packages/db/dist/esm/utils/type-guards.js157 B Size Change: 0 B
Total Size: 3.8 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size ./packages/react-db/dist/esm/index.js225 B ./packages/react-db/dist/esm/useLiveInfiniteQuery.js1.27 kB ./packages/react-db/dist/esm/useLiveQuery.js1.34 kB ./packages/react-db/dist/esm/useLiveSuspenseQuery.js559 B ./packages/react-db/dist/esm/usePacedMutations.js401 B kevin-dp(GitHub profile, opens in a new tab) approved these changes
packages/offline-transactions/src/connectivity/ReactNativeOnlineDetector.ts line 123Outdated@@ -98,7 +107,17 @@98107 this.notifyListeners()99108 }100109110+ isOnline(): boolean {111+ return this.wasConnected112+ }113+101114 dispose(): void {102115 this.stopListening()103116 this.listeners.clear()104117 }118+119+ private toConnectivityState(state: {120+ isConnected: boolean | null121+ isInternetReachable: boolean | null122+ }): boolean {123+ return state.isConnected === true && state.isInternetReachable !== falsecould write
state.isConnectedinstead of=== true.Done, simplified to
!!state.isConnected.KyleAMathews(GitHub profile, opens in a new tab)replied on
packages/offline-transactions/src/connectivity/ReactNativeOnlineDetector.tsline 123Done, simplified to
!!state.isConnected.KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
🦋 Changeset detected#
Latest commit: 15475d6fec395c6f6ab3cf84dcd56b064287efbc
The changes in this PR will be included in the next version bump.
This PR includes changesets to release 1 package
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