@tanstack/offline-transactions 1.1.0 → 1.1.1

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,65 +35,81 @@ export class OfflineTransaction {
   }
 
   mutate(callback: () => void): Transaction {
-    // Repeated calls add to the same transaction: one offline transaction is
-    // one transaction, and its id is unique among live transactions.
-    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
   }
 
@@ -100,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 {

package/src/executor/KeyScheduler.ts

@@ -1,4 +1,3 @@
-import { withSyncSpan } from '../telemetry/tracer'
 import type { OfflineTransaction } from '../types'
 
 export class KeyScheduler {
@@ -6,56 +5,28 @@ export class KeyScheduler {
   private activeTransactionId: string | undefined
 
   schedule(transaction: OfflineTransaction): boolean {
-    return withSyncSpan(
-      `scheduler.schedule`,
-      {
-        'transaction.id': transaction.id,
-        queueLength: this.pendingTransactions.length,
-      },
-      () => {
-        if (
-          this.pendingTransactions.some(
-            (pending) => pending.id === transaction.id,
-          )
-        ) {
-          return false
-        }
-        this.pendingTransactions.push(transaction)
-        // Sort by creation time to maintain FIFO order
-        this.pendingTransactions.sort(
-          (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
-        )
-        return true
-      },
+    if (
+      this.pendingTransactions.some((pending) => pending.id === transaction.id)
+    ) {
+      return false
+    }
+    this.pendingTransactions.push(transaction)
+    // Sort by creation time to maintain FIFO order
+    this.pendingTransactions.sort(
+      (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
     )
+    return true
   }
 
   getNext(): OfflineTransaction | undefined {
-    return withSyncSpan(
-      `scheduler.getNext`,
-      { pendingCount: this.pendingTransactions.length },
-      (span) => {
-        if (
-          this.activeTransactionId !== undefined ||
-          this.pendingTransactions.length === 0
-        ) {
-          span.setAttribute(`result`, `empty`)
-          return undefined
-        }
-
-        const firstTransaction = this.pendingTransactions[0]!
-
-        if (!this.isReadyToRun(firstTransaction)) {
-          span.setAttribute(`result`, `waiting_for_first`)
-          span.setAttribute(`transaction.id`, firstTransaction.id)
-          return undefined
-        }
-
-        span.setAttribute(`result`, `found`)
-        span.setAttribute(`transaction.id`, firstTransaction.id)
-        return firstTransaction
-      },
-    )
+    if (
+      this.activeTransactionId !== undefined ||
+      this.pendingTransactions.length === 0
+    ) {
+      return undefined
+    }
+    const firstTransaction = this.pendingTransactions[0]!
+    return this.isReadyToRun(firstTransaction) ? firstTransaction : undefined
   }
 
   private isReadyToRun(transaction: OfflineTransaction): boolean {

package/src/executor/TransactionExecutor.ts

@@ -2,7 +2,6 @@ import { DuplicateTransactionIdError, createTransaction } from '@tanstack/db'
 import { OutboxTransactionNotFoundError } from '../outbox/OutboxManager'
 import { DefaultRetryPolicy } from '../retry/RetryPolicy'
 import { NonRetriableError } from '../types'
-import { withNestedSpan } from '../telemetry/tracer'
 import type { KeyScheduler } from './KeyScheduler'
 import type { OutboxManager } from '../outbox/OutboxManager'
 import type {
@@ -91,72 +90,48 @@ export class TransactionExecutor {
     transaction: OfflineTransaction,
   ): Promise<void> {
     try {
-      await withNestedSpan(
-        `transaction.execute`,
-        {
-          'transaction.id': transaction.id,
-          'transaction.mutationFnName': transaction.mutationFnName,
-          'transaction.retryCount': transaction.retryCount,
-          'transaction.keyCount': transaction.keys.length,
-        },
-        async (span) => {
-          const terminalError =
-            transaction.outboxPhase === `rejection-pending`
-              ? this.getTerminalError(transaction)
-              : undefined
-          this.scheduler.markStarted(transaction)
-
-          if (transaction.retryCount > 0) {
-            span.setAttribute(`retry.attempt`, transaction.retryCount)
-          }
-
-          if (!transaction.outboxPhase) {
-            try {
-              await this.runMutationFn(transaction)
-            } catch (error) {
-              const err = toError(error)
+      const terminalError =
+        transaction.outboxPhase === `rejection-pending`
+          ? this.getTerminalError(transaction)
+          : undefined
+      this.scheduler.markStarted(transaction)
 
-              span.setAttribute(`result`, `error`)
+      if (!transaction.outboxPhase) {
+        try {
+          await this.runMutationFn(transaction)
+        } catch (error) {
+          const err = toError(error)
 
-              await this.handleError(transaction, err)
-              ;(err as any)[HANDLED_EXECUTION_ERROR] = true
-              throw err
-            }
-          }
+          await this.handleError(transaction, err)
+          ;(err as any)[HANDLED_EXECUTION_ERROR] = true
+          throw err
+        }
+      }
 
-          // A successful provider call can outlive this executor. Persist that
-          // fact before removal so a restarted executor only retries deletion.
-          const deletionPending: OfflineTransaction = transaction.outboxPhase
-            ? transaction
-            : { ...transaction, outboxPhase: `deletion-pending` }
-          try {
-            await this.removeSettledTransaction(
-              deletionPending,
-              !transaction.outboxPhase,
-            )
-          } catch (error) {
-            const storageError = error as Error
-            span.recordException(storageError)
-            span.setAttribute(`result`, `outbox_failure`)
-            this.offlineExecutor.rejectTransaction(
-              transaction.id,
-              terminalError ?? storageError,
-            )
-            throw storageError
-          }
+      // A successful provider call can outlive this executor. Persist that
+      // fact before removal so a restarted executor only retries deletion.
+      const deletionPending: OfflineTransaction = transaction.outboxPhase
+        ? transaction
+        : { ...transaction, outboxPhase: `deletion-pending` }
+      try {
+        await this.removeSettledTransaction(
+          deletionPending,
+          !transaction.outboxPhase,
+        )
+      } catch (error) {
+        const storageError = error as Error
+        this.offlineExecutor.rejectTransaction(
+          transaction.id,
+          terminalError ?? storageError,
+        )
+        throw storageError
+      }
 
-          if (terminalError) {
-            span.setAttribute(`result`, `permanent_failure`)
-            this.offlineExecutor.rejectTransaction(
-              transaction.id,
-              terminalError,
-            )
-          } else {
-            span.setAttribute(`result`, `success`)
-            this.offlineExecutor.resolveTransaction(transaction.id, undefined)
-          }
-        },
-      )
+      if (terminalError) {
+        this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+      } else {
+        this.offlineExecutor.resolveTransaction(transaction.id, undefined)
+      }
     } catch (error) {
       if (
         error !== null &&
@@ -201,129 +176,97 @@ export class TransactionExecutor {
     transaction: OfflineTransaction,
     error: Error,
   ): Promise<void> {
-    return withNestedSpan(
-      `transaction.handleError`,
-      {
-        'transaction.id': transaction.id,
-        'error.name': error.name,
-        'error.message': error.message,
-      },
-      async (span) => {
-        let shouldRetry: boolean
-        let hookFailure: Error | undefined
-        if (error instanceof NonRetriableError) {
-          shouldRetry = false
-        } else {
-          let decision: boolean | undefined
-          try {
-            decision = this.config.shouldRetry?.(error, transaction.retryCount)
-            if (decision !== undefined && typeof decision !== `boolean`) {
-              // An async hook is invalid, but its rejection must stay row-local.
-              void Promise.resolve(decision).catch(() => {})
-              throw new TypeError(
-                `OfflineConfig.shouldRetry must return true, false, or undefined`,
-              )
-            }
-          } catch (hookError) {
-            hookFailure = toError(hookError)
-          }
-          if (hookFailure) {
-            shouldRetry = false
-          } else {
-            shouldRetry =
-              decision ??
-              this.retryPolicy.shouldRetry(error, transaction.retryCount)
-          }
-        }
-
-        span.setAttribute(`shouldRetry`, shouldRetry)
-
-        if (!shouldRetry) {
-          const terminalError = hookFailure ?? error
-          const rejectionPending: OfflineTransaction = {
-            ...transaction,
-            outboxPhase: `rejection-pending`,
-            lastError: {
-              name: terminalError.name,
-              message: terminalError.message,
-              stack: terminalError.stack,
-            },
-          }
-          if (hookFailure) {
-            span.recordException(hookFailure)
-            console.warn(
-              `Retry decision failed for transaction ${transaction.id}:`,
-              hookFailure,
-              `Named mutation function error:`,
-              error,
-            )
-          } else {
-            console.warn(
-              `Transaction ${transaction.id} failed permanently:`,
-              error,
-            )
-          }
-          try {
-            await this.removeSettledTransaction(rejectionPending, true)
-          } catch (storageError) {
-            span.recordException(storageError as Error)
-            span.setAttribute(`result`, `outbox_failure`)
-            this.offlineExecutor.rejectTransaction(
-              transaction.id,
-              terminalError,
-            )
-            throw storageError
-          }
-
-          span.setAttribute(
-            `result`,
-            hookFailure ? `retry_decision_failure` : `permanent_failure`,
+    let shouldRetry: boolean
+    let hookFailure: Error | undefined
+    if (error instanceof NonRetriableError) {
+      shouldRetry = false
+    } else {
+      let decision: boolean | undefined
+      try {
+        decision = this.config.shouldRetry?.(error, transaction.retryCount)
+        if (decision !== undefined && typeof decision !== `boolean`) {
+          // An async hook is invalid, but its rejection must stay row-local.
+          void Promise.resolve(decision).catch(() => {})
+          throw new TypeError(
+            `OfflineConfig.shouldRetry must return true, false, or undefined`,
           )
-          this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
-          return
         }
+      } catch (hookError) {
+        hookFailure = toError(hookError)
+      }
+      if (hookFailure) {
+        shouldRetry = false
+      } else {
+        shouldRetry =
+          decision ??
+          this.retryPolicy.shouldRetry(error, transaction.retryCount)
+      }
+    }
 
-        const delay = Math.max(
-          0,
-          this.retryPolicy.calculateDelay(transaction.retryCount),
+    if (!shouldRetry) {
+      const terminalError = hookFailure ?? error
+      const rejectionPending: OfflineTransaction = {
+        ...transaction,
+        outboxPhase: `rejection-pending`,
+        lastError: {
+          name: terminalError.name,
+          message: terminalError.message,
+          stack: terminalError.stack,
+        },
+      }
+      if (hookFailure) {
+        console.warn(
+          `Retry decision failed for transaction ${transaction.id}:`,
+          hookFailure,
+          `Named mutation function error:`,
+          error,
         )
-        const updatedTransaction: OfflineTransaction = {
-          ...transaction,
-          retryCount: transaction.retryCount + 1,
-          nextAttemptAt: Date.now() + delay,
-          lastError: {
-            name: error.name,
-            message: error.message,
-            stack: error.stack,
-          },
-        }
-
-        span.setAttribute(`retryDelay`, delay)
-        span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
+      } else {
+        console.warn(`Transaction ${transaction.id} failed permanently:`, error)
+      }
+      try {
+        await this.removeSettledTransaction(rejectionPending, true)
+      } catch (storageError) {
+        this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+        throw storageError
+      }
 
-        this.scheduler.updateTransaction(updatedTransaction)
+      this.offlineExecutor.rejectTransaction(transaction.id, terminalError)
+      return
+    }
 
-        try {
-          await this.outbox.update(transaction.id, updatedTransaction)
-          span.setAttribute(`result`, `scheduled_retry`)
-        } catch (persistError) {
-          // Public removal can finish while the named mutation function runs.
-          // The removed row cannot be retried, but its caller still owns the
-          // provider failure and later queued work must be able to run.
-          if (persistError instanceof OutboxTransactionNotFoundError) {
-            this.scheduler.markCompleted(transaction)
-            span.setAttribute(`result`, `outbox_removed`)
-            this.offlineExecutor.rejectTransaction(transaction.id, error)
-            return
-          }
-          span.recordException(persistError as Error)
-          span.setAttribute(`result`, `persist_failed`)
-          throw persistError
-        } finally {
-          this.scheduler.markFailed(transaction)
-        }
-      },
+    const delay = Math.max(
+      0,
+      this.retryPolicy.calculateDelay(transaction.retryCount),
     )
+    const updatedTransaction: OfflineTransaction = {
+      ...transaction,
+      retryCount: transaction.retryCount + 1,
+      nextAttemptAt: Date.now() + delay,
+      lastError: {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      },
+    }
+
+    this.scheduler.updateTransaction(updatedTransaction)
+
+    try {
+      await this.outbox.update(transaction.id, updatedTransaction)
+    } catch (persistError) {
+      // Public removal can finish while the named mutation function runs.
+      // The removed row cannot be retried, but its caller still owns the
+      // provider failure and later queued work must be able to run.
+      if (persistError instanceof OutboxTransactionNotFoundError) {
+        this.scheduler.markCompleted(transaction)
+        this.offlineExecutor.rejectTransaction(transaction.id, error)
+        return
+      }
+      throw persistError
+    } finally {
+      this.scheduler.markFailed(transaction)
+    }
   }
 
   private async removeSettledTransaction(
@@ -453,13 +396,6 @@ export class TransactionExecutor {
           mutationFn: async () => {},
         })
 
-        // Prevent unhandled promise rejection when cleanup calls rollback()
-        // We don't care about this promise - it's just for holding mutations
-        restorationTx.isPersisted.promise.catch(() => {
-          // Intentionally ignored - restoration transactions are cleaned up
-          // via cleanupRestorationTransaction, not through normal commit flow
-        })
-
         restorationTx.applyMutations(offlineTx.mutations)
 
         // Register with each affected Collection. If one cannot track it, roll