Skip to content
Source
Sign inSign up
TanStack/db

fix(offline-transactions): infinite retries by default and online-status gating #1301

MergedKyleAMathews(GitHub profile, opens in a new tab)merged 6 commits intomain fromrefs/pull/1301/headmerged 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:

  1. DefaultRetryPolicy hardcoded maxRetries = 10 — After 10 transient failures (e.g., a brief server outage), transactions were treated as permanent failures, removed from the outbox, and lost.

  2. 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 offline
  • TransactionExecutor.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 NonRetriableError and specific status codes are permanent)
  • No transaction execution is attempted while isOnline() returns false
  • The OnlineDetector is 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 maxRetries changed from 10 to Infinity
  • src/executor/TransactionExecutor.ts — Online gating in execution loop and retry scheduling; TransactionSignaler interface replaces any type
  • src/OfflineExecutor.ts — Removed notifyOnline(); added isOnline() method; subscription handler triggers execution on connectivity change
  • src/connectivity/ReactNativeOnlineDetector.ts — Added isOnline(), initial NetInfo.fetch(), extracted toConnectivityState()
  • src/types.ts — OnlineDetector.isOnline() now required; added TransactionSignaler interface
  • 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. 🦋 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
      NameType
      @tanstack/offline-transactionsPatch

      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@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@1301

      commit: df57939

    3. Size Change: 0 B

      Total Size: 92.6 kB

      ℹ️ View Unchanged
      FilenameSize
      ./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
      compressed-size-action::db-package-size
    4. Size Change: 0 B

      Total Size: 3.8 kB

      ℹ️ View Unchanged
      FilenameSize
      ./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
      compressed-size-action::react-db-package-size
    5. 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 }
      100109
      110+ isOnline(): boolean {
      111+ return this.wasConnected
      112+ }
      113+
      101114 dispose(): void {
      102115 this.stopListening()
      103116 this.listeners.clear()
      104117 }
      118+
      119+ private toConnectivityState(state: {
      120+ isConnected: boolean | null
      121+ isInternetReachable: boolean | null
      122+ }): boolean {
      123+ return state.isConnected === true && state.isInternetReachable !== false

      could write state.isConnected instead of === true.

      Done, simplified to !!state.isConnected.

    6. KyleAMathews(GitHub profile, opens in a new tab)replied on packages/offline-transactions/src/connectivity/ReactNativeOnlineDetector.ts line 123

      Done, simplified to !!state.isConnected.

Sign in to join this conversation.