@tanstack/offline-transactions 1.0.65 → 1.1.1

package/dist/esm/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n  Transaction,\n} from '@tanstack/db'\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>,\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  changes: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  /** Provider work has settled; only durable outbox deletion remains. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  /** Absent for the original Date-marker format. */\n  valueEncoding?: 2 | 3\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: string\n  retryCount: number\n  nextAttemptAt: number\n  /** Absent in older records and while mutationFn may still need to run. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Storage diagnostics and mode\nexport type OfflineMode = `offline` | `online-only`\n\nexport type StorageDiagnosticCode =\n  | `STORAGE_AVAILABLE`\n  | `INDEXEDDB_UNAVAILABLE`\n  | `LOCALSTORAGE_UNAVAILABLE`\n  | `STORAGE_BLOCKED`\n  | `QUOTA_EXCEEDED`\n  | `UNKNOWN_ERROR`\n\nexport interface StorageDiagnostic {\n  code: StorageDiagnosticCode\n  mode: OfflineMode\n  message: string\n  error?: Error\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection<any, any, any, any, any>>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>,\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  onStorageFailure?: (diagnostic: StorageDiagnostic) => void\n  leaderElection?: LeaderElection\n  /**\n   * Custom online detector implementation.\n   * Defaults to WebOnlineDetector for browser environments.\n   * The '@tanstack/offline-transactions/react-native' entry point uses ReactNativeOnlineDetector automatically.\n   */\n  onlineDetector?: OnlineDetector\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface TransactionSignaler {\n  readonly isOfflineEnabled: boolean\n  resolveTransaction: (transactionId: string, result: any) => void\n  rejectTransaction: (transactionId: string, error: Error) => void\n  registerRestorationTransaction: (\n    offlineTransactionId: string,\n    restorationTransaction: Transaction,\n  ) => void\n  isOnline: () => boolean\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n  isOnline: () => boolean\n  dispose: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AAyKO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}
+{"version":3,"file":"types.js","sources":["../../src/types.ts"],"sourcesContent":["import type {\n  Collection,\n  MutationFnParams,\n  PendingMutation,\n  Transaction,\n} from '@tanstack/db'\n\n// Extended mutation function that includes idempotency key\nexport type OfflineMutationFnParams<\n  T extends object = Record<string, unknown>,\n> = MutationFnParams<T> & {\n  idempotencyKey: string\n}\n\nexport type OfflineMutationFn<T extends object = Record<string, unknown>> = (\n  params: OfflineMutationFnParams<T>,\n) => Promise<any>\n\n// Simplified mutation structure for serialization\nexport interface SerializedMutation {\n  globalKey: string\n  type: string\n  modified: any\n  original: any\n  changes: any\n  collectionId: string\n}\n\nexport interface SerializedError {\n  name: string\n  message: string\n  stack?: string\n}\n\nexport interface SerializedSpanContext {\n  traceId: string\n  spanId: string\n  traceFlags: number\n  traceState?: string\n}\n\n// In-memory representation with full PendingMutation objects\nexport interface OfflineTransaction {\n  id: string\n  mutationFnName: string\n  mutations: Array<PendingMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: Date\n  retryCount: number\n  nextAttemptAt: number\n  /** Provider work has settled; only durable outbox deletion remains. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Serialized representation for storage\nexport interface SerializedOfflineTransaction {\n  /** Absent for the original Date-marker format. */\n  valueEncoding?: 2 | 3\n  id: string\n  mutationFnName: string\n  mutations: Array<SerializedMutation>\n  keys: Array<string>\n  idempotencyKey: string\n  createdAt: string\n  retryCount: number\n  nextAttemptAt: number\n  /** Absent in older records and while mutationFn may still need to run. */\n  outboxPhase?: `deletion-pending` | `rejection-pending`\n  lastError?: SerializedError\n  metadata?: Record<string, any>\n  spanContext?: SerializedSpanContext\n  version: 1\n}\n\n// Storage diagnostics and mode\nexport type OfflineMode = `offline` | `online-only`\n\nexport type StorageDiagnosticCode =\n  | `STORAGE_AVAILABLE`\n  | `INDEXEDDB_UNAVAILABLE`\n  | `LOCALSTORAGE_UNAVAILABLE`\n  | `STORAGE_BLOCKED`\n  | `QUOTA_EXCEEDED`\n  | `UNKNOWN_ERROR`\n\nexport interface StorageDiagnostic {\n  code: StorageDiagnosticCode\n  mode: OfflineMode\n  message: string\n  error?: Error\n}\n\nexport interface OfflineConfig {\n  collections: Record<string, Collection<any, any, any, any, any>>\n  mutationFns: Record<string, OfflineMutationFn>\n  storage?: StorageAdapter\n  maxConcurrency?: number\n  jitter?: boolean\n  /**\n   * Override retry decisions for errors from all named mutation functions.\n   * Return synchronously; undefined uses the default decision. Put any\n   * function-specific context needed by this shared hook on the Error.\n   * NonRetriableError always stops retry.\n   * A throw or invalid return fails only that outbox row and rejects its\n   * waiters with the hook failure. Queued work runs after terminal cleanup.\n   * The default policy still supplies the delay and configured jitter.\n   */\n  shouldRetry?: (error: Error, retryCount: number) => boolean | undefined\n  beforeRetry?: (\n    transactions: Array<OfflineTransaction>,\n  ) => Array<OfflineTransaction>\n  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void\n  onLeadershipChange?: (isLeader: boolean) => void\n  onStorageFailure?: (diagnostic: StorageDiagnostic) => void\n  leaderElection?: LeaderElection\n  /**\n   * Custom online detector implementation.\n   * Defaults to WebOnlineDetector for browser environments.\n   * The '@tanstack/offline-transactions/react-native' entry point uses ReactNativeOnlineDetector automatically.\n   */\n  onlineDetector?: OnlineDetector\n}\n\nexport interface StorageAdapter {\n  get: (key: string) => Promise<string | null>\n  set: (key: string, value: string) => Promise<void>\n  delete: (key: string) => Promise<void>\n  keys: () => Promise<Array<string>>\n  clear: () => Promise<void>\n}\n\nexport interface RetryPolicy {\n  calculateDelay: (retryCount: number) => number\n  shouldRetry: (error: Error, retryCount: number) => boolean\n}\n\nexport interface LeaderElection {\n  requestLeadership: () => Promise<boolean>\n  releaseLeadership: () => void\n  isLeader: () => boolean\n  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void\n}\n\nexport interface TransactionSignaler {\n  readonly isOfflineEnabled: boolean\n  resolveTransaction: (transactionId: string, result: any) => void\n  rejectTransaction: (transactionId: string, error: Error) => void\n  registerRestorationTransaction: (\n    offlineTransactionId: string,\n    restorationTransaction: Transaction,\n  ) => void\n  isOnline: () => boolean\n}\n\nexport interface OnlineDetector {\n  subscribe: (callback: () => void) => () => void\n  notifyOnline: () => void\n  isOnline: () => boolean\n  dispose: () => void\n}\n\nexport interface CreateOfflineTransactionOptions {\n  id?: string\n  mutationFnName: string\n  autoCommit?: boolean\n  idempotencyKey?: string\n  metadata?: Record<string, any>\n}\n\nexport interface CreateOfflineActionOptions<T> {\n  mutationFnName: string\n  onMutate: (variables: T) => void\n}\n\nexport class NonRetriableError extends Error {\n  constructor(message: string) {\n    super(message)\n    this.name = `NonRetriableError`\n  }\n}\n"],"names":[],"mappings":"AAmLO,MAAM,0BAA0B,MAAM;AAAA,EAC3C,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/offline-transactions",
-  "version": "1.0.65",
+  "version": "1.1.1",
   "description": "Offline-first transaction capabilities for TanStack DB",
   "author": "TanStack",
   "license": "MIT",
@@ -52,7 +52,7 @@
     "skills"
   ],
   "dependencies": {
-    "@tanstack/db": "0.12.3"
+    "@tanstack/db": "0.14.0"
   },
   "peerDependencies": {
     "@react-native-community/netinfo": ">=11.0.0",

package/skills/offline/SKILL.md

@@ -165,6 +165,7 @@ interface OfflineConfig {
   storage?: StorageAdapter // Custom storage (default: auto-detect)
   maxConcurrency?: number // Parallel execution limit
   jitter?: boolean // Add jitter to retry delays
+  shouldRetry?: (error: Error, retryCount: number) => boolean | undefined // Override retry decision
   beforeRetry?: (txs) => txs // Transform/filter before retry
   onUnknownMutationFn?: (name, tx) => void // Handle orphaned transactions
   onLeadershipChange?: (isLeader) => void // Leadership state callback
@@ -206,7 +207,55 @@ const executor = startOfflineExecutor({
 })
 ```
 
-Throwing `NonRetriableError` stops retry and removes the transaction from the outbox. Use for permanent failures (validation errors, conflicts, 4xx responses).
+Throwing `NonRetriableError` stops retry and removes the transaction from the outbox. Use it for failures known to be permanent under the server contract, such as validation errors or a 409 that means an unrecoverable duplicate. A recoverable 401 can instead reach `shouldRetry`.
+
+### Retry decisions
+
+Set `shouldRetry` to override the default decision for a named mutation function
+error. The hook receives the named mutation function's `Error` and retry count
+(`0` on the first failure). The same `Error` instance is passed through; a
+non-`Error` rejection is converted to an `Error` and may lose custom fields.
+Return `true` to retry, `false` to stop, or `undefined` to use the
+default decision. For example, return `true` for a recoverable 401 and
+`undefined` otherwise. `NonRetriableError` always stops without calling the
+hook. The default backoff and configured jitter still determine retry timing.
+The hook is synchronous and shared by all named mutation functions. An async
+hook returns a Promise, which fails its outbox row. Put function-specific
+context on the thrown error when retry rules differ between functions.
+If the hook throws or returns another value, the executor records a terminal
+rejection for that row, removes it from the outbox, and rejects its waiting
+promises with the hook failure. Other queued rows continue after the failed
+row's deletion is acknowledged. New commits may join the queue during cleanup,
+but cannot run ahead of that deletion. A fresh executor does not replay the
+failed row. The named mutation function error is logged; the hook failure is
+the caller-facing and stored error. Stored errors retain `name`, `message`, and
+`stack`, but a restart does not restore an arbitrary error subclass or its
+custom fields.
+If marker storage or deletion fails, the caller still receives the hook error
+while the executor stops with the storage error and retains queued work. A
+saved terminal marker skips the named mutation function after restart; an
+unmarked row can replay.
+To decide from an HTTP status, throw an error carrying `response.status` in
+the named mutation function and inspect its numeric status in `shouldRetry`.
+
+```ts
+class HttpError extends Error {
+  constructor(readonly status: number) {
+    super(`HTTP ${status}`)
+    this.name = 'HttpError'
+  }
+}
+
+function throwOnHttpFailure(response: Response): void {
+  if (!response.ok) throw new HttpError(response.status)
+}
+
+const retryOnRecoverable401 = (error: Error): boolean | undefined =>
+  error instanceof HttpError && error.status === 401 ? true : undefined
+```
+
+Call `throwOnHttpFailure(response)` in the named mutation function and pass
+`shouldRetry: retryOnRecoverable401` in the executor config.
 
 ### Idempotency keys
 
@@ -339,18 +388,37 @@ mutationFns: {
 Correct:
 
 ```ts
+class HttpError extends Error {
+  constructor(readonly status: number) {
+    super(`HTTP ${status}`)
+    this.name = 'HttpError'
+  }
+}
+
 mutationFns: {
   createTodo: async ({ transaction }) => {
     const res = await fetch('/api/todos', { ... })
-    if (res.status >= 400 && res.status < 500) {
-      throw new NonRetriableError(`Client error: ${res.status}`)
+    if (res.status === 422) {
+      throw new NonRetriableError('Invalid todo')
+    }
+    if (res.status === 409) {
+      throw new NonRetriableError('Duplicate detected')
+    }
+    // This todo API also treats these responses as permanent.
+    if ([404, 405, 410].includes(res.status)) {
+      throw new NonRetriableError(`Todo endpoint rejected: ${res.status}`)
     }
-    if (!res.ok) throw new Error('Server error')
+    if (!res.ok) throw new HttpError(res.status)
   },
 }
 ```
 
-Without distinguishing retriable from permanent errors, 4xx responses (validation, auth, not found) will retry forever until max retries, wasting resources and filling logs.
+Classify failures according to whether the app can recover. The default policy
+stops when an error message contains 400, 401, 403, or 422; it can retry other
+errors indefinitely. This example marks 404, 405, and 410 as permanent for the
+todo API while leaving 408 and 429 available for retry. Use `shouldRetry` when
+a 401 can recover after credentials refresh, and use `NonRetriableError` for
+known permanent failures.
 
 See also: db-core/mutations-optimistic/SKILL.md — for the underlying mutation primitives.
 

package/src/OfflineExecutor.ts

@@ -26,7 +26,6 @@ import { createOfflineAction } from './api/OfflineAction'
 // TanStack DB primitives
 
 // Replay
-import { withNestedSpan, withSpan } from './telemetry/tracer'
 import { NonRetriableError } from './types'
 import type {
   CreateOfflineActionOptions,
@@ -41,6 +40,9 @@ import type {
 } from './types'
 import type { Transaction } from '@tanstack/db'
 
+/** How many settled ids an executor remembers to reject late waiters. */
+const SETTLED_TRANSACTIONS_REMEMBERED = 1000
+
 export class OfflineExecutor {
   private config: OfflineConfig
 
@@ -75,6 +77,12 @@ export class OfflineExecutor {
     }
   > = new Map()
 
+  /**
+   * Ids this executor settled, oldest first. A waiter for one of them has
+   * nothing left to wait for. An unknown id can still arrive from another tab.
+   */
+  private readonly settledTransactions = new Set<string>()
+
   // Track restoration transactions for cleanup when offline transactions complete
   private restorationTransactions: Map<string, Transaction> = new Map()
 
@@ -268,77 +276,66 @@ export class OfflineExecutor {
   }
 
   private async initialize(): Promise<void> {
-    return withSpan(`executor.initialize`, {}, async (span) => {
-      try {
-        // Probe storage and create adapter
-        const { storage, diagnostic } = await this.createStorage()
-        if (this.disposed) {
-          this.initResolve()
-          return
-        }
-
-        // Cast to writable to set readonly properties
-        ;(this as any).storage = storage
-        ;(this as any).storageDiagnostic = diagnostic
-        ;(this as any).mode = diagnostic.mode
+    try {
+      // Probe storage and create adapter
+      const { storage, diagnostic } = await this.createStorage()
+      if (this.disposed) {
+        this.initResolve()
+        return
+      }
 
-        span.setAttribute(`storage.mode`, diagnostic.mode)
-        span.setAttribute(`storage.code`, diagnostic.code)
+      // Cast to writable to set readonly properties
+      ;(this as any).storage = storage
+      ;(this as any).storageDiagnostic = diagnostic
+      ;(this as any).mode = diagnostic.mode
 
-        if (!storage) {
-          // Online-only mode - notify callback and skip offline setup
-          if (this.config.onStorageFailure) {
-            this.config.onStorageFailure(diagnostic)
-          }
-          span.setAttribute(`result`, `online-only`)
-          this.initResolve()
-          return
+      if (!storage) {
+        // Online-only mode - notify callback and skip offline setup
+        if (this.config.onStorageFailure) {
+          this.config.onStorageFailure(diagnostic)
         }
+        this.initResolve()
+        return
+      }
 
-        // Storage available - set up offline components
-        this.outbox = new OutboxManager(storage, this.config.collections)
-        this.executor = new TransactionExecutor(
-          this.scheduler,
-          this.outbox,
-          this.config,
-          this,
-        )
-        this.leaderElection = this.createLeaderElection()
-
-        // Request leadership first
-        const isLeader = await this.leaderElection.requestLeadership()
-        // Disposal may have run while leadership was pending.
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (this.disposed) {
-          this.leaderElection.releaseLeadership()
-          this.initResolve()
-          return
-        }
-        this.isLeaderState = isLeader
-        span.setAttribute(`isLeader`, isLeader)
+      // Storage available - set up offline components
+      this.outbox = new OutboxManager(storage, this.config.collections)
+      this.executor = new TransactionExecutor(
+        this.scheduler,
+        this.outbox,
+        this.config,
+        this,
+      )
+      this.leaderElection = this.createLeaderElection()
 
-        // Set up event listeners after leadership is established
-        // This prevents the callback from being called multiple times
-        this.setupEventListeners()
+      // Request leadership first
+      const isLeader = await this.leaderElection.requestLeadership()
+      // Disposal may have run while leadership was pending.
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+      if (this.disposed) {
+        this.leaderElection.releaseLeadership()
+        this.initResolve()
+        return
+      }
+      this.isLeaderState = isLeader
 
-        // Notify initial leadership state
-        if (this.config.onLeadershipChange) {
-          this.config.onLeadershipChange(isLeader)
-        }
+      // Set up event listeners after leadership is established
+      // This prevents the callback from being called multiple times
+      this.setupEventListeners()
 
-        if (isLeader) {
-          await this.loadAndReplayTransactions()
-        }
-        span.setAttribute(`result`, `offline-enabled`)
-        this.initResolve()
-      } catch (error) {
-        console.warn(`Failed to initialize offline executor:`, error)
-        span.setAttribute(`result`, `failed`)
-        this.initReject(
-          error instanceof Error ? error : new Error(String(error)),
-        )
+      // Notify initial leadership state
+      if (this.config.onLeadershipChange) {
+        this.config.onLeadershipChange(isLeader)
       }
-    })
+
+      if (isLeader) {
+        await this.loadAndReplayTransactions()
+      }
+      this.initResolve()
+    } catch (error) {
+      console.warn(`Failed to initialize offline executor:`, error)
+      this.initReject(error instanceof Error ? error : new Error(String(error)))
+    }
   }
 
   private async loadAndReplayTransactions(): Promise<void> {
@@ -441,37 +438,33 @@ export class OfflineExecutor {
     // Wait for initialization to complete
     await this.initPromise
 
-    return withNestedSpan(
-      `executor.persistTransaction`,
-      {
-        'transaction.id': transaction.id,
-        'transaction.mutationFnName': transaction.mutationFnName,
-      },
-      async (span) => {
-        if (!this.isOfflineEnabled || !this.outbox || !this.executor) {
-          span.setAttribute(`result`, `rejected_not_admitted`)
-          throw new NonRetriableError(`Offline transaction was not admitted`)
-        }
+    if (!this.isOfflineEnabled || !this.outbox || !this.executor) {
+      throw new NonRetriableError(`Offline transaction was not admitted`)
+    }
 
-        try {
-          this.executor.assertHealthy()
-          await this.outbox.add(transaction)
-          // A shared queue error belongs to its execution, not every caller
-          // that durably admitted a transaction. Per-ID signals settle callers.
-          this.executor.execute(transaction).catch((error) => {
-            console.warn(`Failed to execute transactions:`, error)
-          })
-          span.setAttribute(`result`, `persisted`)
-        } catch (error) {
-          console.error(
-            `Failed to persist offline transaction ${transaction.id}:`,
-            error,
-          )
-          span.setAttribute(`result`, `failed`)
-          throw error
-        }
-      },
-    )
+    try {
+      this.executor.assertHealthy()
+      await this.outbox.add(transaction)
+      // A shared queue error belongs to its execution, not every caller
+      // that durably admitted a transaction. Per-ID signals settle callers.
+      this.executor.execute(transaction).catch((error) => {
+        console.warn(`Failed to execute transactions:`, error)
+      })
+    } catch (error) {
+      console.error(
+        `Failed to persist offline transaction ${transaction.id}:`,
+        error,
+      )
+      throw error
+    }
+  }
+
+  private rememberSettled(transactionId: string): void {
+    this.settledTransactions.add(transactionId)
+    if (this.settledTransactions.size > SETTLED_TRANSACTIONS_REMEMBERED)
+      this.settledTransactions.delete(
+        this.settledTransactions.values().next().value!,
+      )
   }
 
   // Method for OfflineTransaction to wait for completion
@@ -480,6 +473,10 @@ export class OfflineExecutor {
     if (existing) {
       return existing.promise
     }
+    if (this.settledTransactions.has(transactionId))
+      throw new Error(
+        `Offline transaction ${transactionId} already settled; wait for it before it settles`,
+      )
 
     const deferred: {
       promise: Promise<any>
@@ -498,6 +495,7 @@ export class OfflineExecutor {
 
   // Method for TransactionExecutor to signal completion
   resolveTransaction(transactionId: string, result: any): void {
+    this.rememberSettled(transactionId)
     const deferred = this.pendingTransactionPromises.get(transactionId)
     if (deferred) {
       deferred.resolve(result)
@@ -510,6 +508,7 @@ export class OfflineExecutor {
 
   // Method for TransactionExecutor to signal failure
   rejectTransaction(transactionId: string, error: Error): void {
+    this.rememberSettled(transactionId)
     const deferred = this.pendingTransactionPromises.get(transactionId)
     if (deferred) {
       deferred.reject(error)
@@ -547,26 +546,11 @@ export class OfflineExecutor {
       return
     }
 
-    // Mark as completed so recomputeOptimisticState removes it from consideration.
-    // The actual data will come from the sync.
+    // Mark as completed: every Collection that tracked it recomputes and
+    // releases it. The actual data will come from the sync.
     restorationTx.setState(`completed`)
-
-    // Remove from each collection's transaction map and recompute
-    const touchedCollections = new Set<string>()
-    for (const mutation of restorationTx.mutations) {
-      // Defensive check for corrupted deserialized data
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (!mutation.collection) {
-        continue
-      }
-      const collectionId = mutation.collection.id
-      if (touchedCollections.has(collectionId)) {
-        continue
-      }
-      touchedCollections.add(collectionId)
-      mutation.collection._state.transactions.delete(restorationTx.id)
-      mutation.collection._state.recomputeOptimisticState(false)
-    }
+    restorationTx.isPersisted.resolve(restorationTx)
+    restorationTx.touchCollection()
   }
 
   async removeFromOutbox(id: string): Promise<void> {

package/src/api/OfflineAction.ts

@@ -22,44 +22,26 @@ export function createOfflineAction<T>(
   executor: any,
 ): (variables: T) => Transaction {
   const { mutationFnName, onMutate } = options
-  console.log(`createOfflineAction 2`, options)
 
   return (variables: T): Transaction => {
     const offlineTransaction = new OfflineTransaction(
       {
         mutationFnName,
-        autoCommit: false,
+        // The transaction commits after onMutate and reports a failure
+        // through `when('settled')`.
+        autoCommit: true,
       },
       mutationFn,
       persistTransaction,
       executor,
     )
 
-    const transaction = offlineTransaction.mutate(() => {
-      console.log(`mutate`)
+    return offlineTransaction.mutate(() => {
       const maybePromise = onMutate(variables) as unknown
 
       if (isPromiseLike(maybePromise)) {
         throw new OnMutateMustBeSynchronousError()
       }
     })
-
-    // Immediately commit
-    const commitPromise = (async () => {
-      try {
-        await transaction.commit()
-        console.log(`offlineAction committed - success`)
-      } catch {
-        console.log(`offlineAction commit failed - error`)
-      }
-    })()
-
-    // Don't await - this is fire-and-forget for optimistic actions
-    // But catch to prevent unhandled rejection
-    commitPromise.catch(() => {
-      // Already handled in try/catch above
-    })
-
-    return transaction
   }
 }

package/src/api/OfflineTransaction.ts

@@ -1,5 +1,4 @@
 import { createTransaction, safeRandomUUID } from '@tanstack/db'
-import { NonRetriableError } from '../types'
 import type { PendingMutation, Transaction } from '@tanstack/db'
 import type {
   CreateOfflineTransactionOptions,
@@ -10,10 +9,12 @@ import type {
 export class OfflineTransaction {
   private offlineId: string
   private mutationFnName: string
-  private autoCommit: boolean
+  private autoCommit: boolean | undefined
   private idempotencyKey: string
   private metadata: Record<string, any>
   private transaction: Transaction | null = null
+  /** The mutation function ran, so the executor settles the waiter. */
+  private persisting = false
   private persistTransaction: (tx: OfflineTransactionType) => Promise<void>
   private executor: any // Will be typed properly - reference to OfflineExecutor
 
@@ -25,7 +26,8 @@ export class OfflineTransaction {
   ) {
     this.offlineId = safeRandomUUID()
     this.mutationFnName = options.mutationFnName
-    this.autoCommit = options.autoCommit ?? true
+    // The TanStack DB transaction applies the default.
+    this.autoCommit = options.autoCommit
     this.idempotencyKey = options.idempotencyKey ?? safeRandomUUID()
     this.metadata = options.metadata ?? {}
     this.persistTransaction = persistTransaction
@@ -33,63 +35,81 @@ export class OfflineTransaction {
   }
 
   mutate(callback: () => void): Transaction {
-    this.transaction = createTransaction({
-      id: this.offlineId,
-      autoCommit: false,
-      mutationFn: async () => {
-        // This is the blocking mutationFn that waits for the executor
-        // First persist the transaction to the outbox
-        const offlineTransaction: OfflineTransactionType = {
-          id: this.offlineId,
-          mutationFnName: this.mutationFnName,
-          mutations: this.transaction!.mutations,
-          keys: this.extractKeys(this.transaction!.mutations),
-          idempotencyKey: this.idempotencyKey,
-          createdAt: new Date(),
-          retryCount: 0,
-          nextAttemptAt: Date.now(),
-          metadata: this.metadata,
-          spanContext: undefined,
-          version: 1,
-        }
+    // One offline transaction is one transaction, and its id is unique among
+    // live transactions. Repeated calls add to it while it is pending. With
+    // autoCommit, it commits after this callback and reports a failure
+    // through `when('settled')`, so a later call throws: it is no longer pending.
+    if (!this.transaction) {
+      this.transaction = createTransaction({
+        id: this.offlineId,
+        autoCommit: this.autoCommit,
+        mutationFn: async () => {
+          this.persisting = true
+          // This is the blocking mutationFn that waits for the executor
+          // First persist the transaction to the outbox
+          const offlineTransaction: OfflineTransactionType = {
+            id: this.offlineId,
+            mutationFnName: this.mutationFnName,
+            mutations: this.transaction!.mutations,
+            keys: this.extractKeys(this.transaction!.mutations),
+            idempotencyKey: this.idempotencyKey,
+            createdAt: new Date(),
+            retryCount: 0,
+            nextAttemptAt: Date.now(),
+            metadata: this.metadata,
+            spanContext: undefined,
+            version: 1,
+          }
 
-        const completionPromise = this.executor.waitForTransactionCompletion(
-          this.offlineId,
-        )
+          const completionPromise = this.executor.waitForTransactionCompletion(
+            this.offlineId,
+          )
 
-        try {
-          // Persistence also drives the shared queue. This transaction can finish
-          // before that queue drains; observe both promises from the outset.
-          await Promise.race([
-            this.persistTransaction(offlineTransaction),
-            completionPromise,
-          ])
-          // A queue pause (offline or retry) is not transaction completion.
-          await completionPromise
-        } catch (error) {
-          const normalizedError =
-            error instanceof Error ? error : new Error(String(error))
-          this.executor.rejectTransaction(this.offlineId, normalizedError)
-          throw error
-        }
+          try {
+            // Persistence also drives the shared queue. This transaction can finish
+            // before that queue drains; observe both promises from the outset.
+            await Promise.race([
+              this.persistTransaction(offlineTransaction),
+              completionPromise,
+            ])
+            // A queue pause (offline or retry) is not transaction completion.
+            await completionPromise
+          } catch (error) {
+            const normalizedError =
+              error instanceof Error ? error : new Error(String(error))
+            this.executor.rejectTransaction(this.offlineId, normalizedError)
+            throw error
+          }
 
-        return
-      },
-      metadata: this.metadata,
-    })
+          return
+        },
+        metadata: this.metadata,
+      })
+      // A transaction without mutations completes, and one rolled back before
+      // it commits fails, without its mutation function, so the executor never
+      // settles its waiter. Settle that waiter here with the same outcome. Once
+      // the mutation function runs, only the executor settles it.
+      void this.transaction.when(`settled`).then(
+        () => {
+          if (!this.persisting)
+            this.executor.resolveTransaction(this.offlineId, undefined)
+        },
+        (error: unknown) => {
+          if (!this.persisting)
+            this.executor.rejectTransaction(
+              this.offlineId,
+              error instanceof Error
+                ? error
+                : new Error(`Offline transaction was rolled back`),
+            )
+        },
+      )
+    }
 
     this.transaction.mutate(() => {
       callback()
     })
 
-    if (this.autoCommit) {
-      // Auto-commit for direct OfflineTransaction usage
-      this.commit().catch((error) => {
-        console.error(`Auto-commit failed:`, error)
-        throw error
-      })
-    }
-
     return this.transaction
   }
 
@@ -98,18 +118,12 @@ export class OfflineTransaction {
       throw new Error(`No mutations to commit. Call mutate() first.`)
     }
 
-    try {
-      // Commit the TanStack DB transaction
-      // This will trigger the mutationFn which handles persistence and waiting
-      await this.transaction.commit()
-      return this.transaction
-    } catch (error) {
-      // Only rollback for NonRetriableError - other errors should allow retry
-      if (error instanceof NonRetriableError) {
-        this.transaction.rollback()
-      }
-      throw error
-    }
+    // The mutationFn persists the transaction and waits for the executor. A
+    // commit that rejects has already rolled the transaction back. A sibling's
+    // failure can also roll it back while it waits, and then commit() resolves,
+    // so `when('settled')` is the receipt.
+    await this.transaction.commit()
+    return this.transaction
   }
 
   rollback(): void {