Restore offline transactions to optimistic store upon restart the app (#1169)

* test: add bug reproduction for optimistic state not restored on page refresh

Add a failing test that demonstrates the issue where offline transactions
do not restore optimistic state to the collection when the page is
refreshed while offline. Users have to manually handle this in beforeRetry
by replaying all transactions into the collection.

The test asserts the expected behavior (optimistic data should be present
after page refresh) and currently fails, demonstrating the bug.

* fix: restore optimistic state on page refresh while offline

When the page is refreshed while offline with pending transactions,
the optimistic state was not being restored to collections. Users had
to manually replay transactions in `beforeRetry` to restore UI state.

This fix:
1. In `loadPendingTransactions()`, creates restoration transactions that
   hold the deserialized mutations and registers them with the collection's
   state manager to display optimistic data immediately

2. Properly reconstructs the mutation `key` during deserialization using
   the collection's `getKeyFromItem()` method, which is needed for
   optimistic state lookup

3. Cleans up restoration transactions when the offline transaction
   completes or fails, allowing sync data to take over

4. Adds `waitForInit()` method to allow waiting for full initialization
   including pending transaction loading

5. Updates `loadAndReplayTransactions()` to not block on execution,
   so initialization completes as soon as optimistic state is restored

* ci: apply automated fixes

* chore: add changeset for optimistic state restoration fix

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: simplify restoration transaction cleanup

- Consolidate restorationTransactions.delete() to single point
- Improve comments on restoration transaction purpose

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: improve error handling and add rollback test

- Add try-catch isolation in restoreOptimisticState to prevent one bad
  transaction from breaking all restoration
- Add defensive null check for mutation.collection in cleanup methods
- Add test for rollback of restored optimistic state on permanent failure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: prevent unhandled promise rejection from restoration transaction cleanup

Add catch handler to restoration transaction's isPersisted promise to prevent
unhandled rejection when rollback() is called during cleanup. The rollback
calls reject(undefined) which would otherwise cause an unhandled rejection error.

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

.changeset/restore-optimistic-state-offline.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/offline-transactions': patch
+---
+
+Fix optimistic state not being restored to collections on page refresh while offline. Pending transactions are now automatically rehydrated from storage and their optimistic mutations applied to the UI immediately on startup, providing a seamless offline experience.

packages/offline-transactions/src/OfflineExecutor.ts

@@ -69,6 +69,9 @@ export class OfflineExecutor {
     }
   > = new Map()
 
+  // Track restoration transactions for cleanup when offline transactions complete
+  private restorationTransactions: Map<string, Transaction> = new Map()
+
   constructor(config: OfflineConfig) {
     this.config = config
     this.scheduler = new KeyScheduler()
@@ -298,8 +301,14 @@ export class OfflineExecutor {
     }
 
     try {
+      // Load pending transactions and restore optimistic state
       await this.executor.loadPendingTransactions()
-      await this.executor.executeAll()
+
+      // Start execution in the background - don't await to avoid blocking initialization
+      // The transactions will execute and complete asynchronously
+      this.executor.executeAll().catch((error) => {
+        console.warn(`Failed to execute transactions:`, error)
+      })
     } catch (error) {
       console.warn(`Failed to load and replay transactions:`, error)
     }
@@ -309,6 +318,14 @@ export class OfflineExecutor {
     return this.mode === `offline` && this.isLeaderState
   }
 
+  /**
+   * Wait for the executor to fully initialize.
+   * This ensures that pending transactions are loaded and optimistic state is restored.
+   */
+  async waitForInit(): Promise<void> {
+    return this.initPromise
+  }
+
   createOfflineTransaction(
     options: CreateOfflineTransactionOptions,
   ): Transaction | OfflineTransactionAPI {
@@ -441,6 +458,9 @@ export class OfflineExecutor {
       deferred.resolve(result)
       this.pendingTransactionPromises.delete(transactionId)
     }
+
+    // Clean up the restoration transaction - the sync will provide authoritative data
+    this.cleanupRestorationTransaction(transactionId)
   }
 
   // Method for TransactionExecutor to signal failure
@@ -450,6 +470,58 @@ export class OfflineExecutor {
       deferred.reject(error)
       this.pendingTransactionPromises.delete(transactionId)
     }
+
+    // Clean up the restoration transaction and rollback optimistic state
+    this.cleanupRestorationTransaction(transactionId, true)
+  }
+
+  // Method for TransactionExecutor to register restoration transactions
+  registerRestorationTransaction(
+    offlineTransactionId: string,
+    restorationTransaction: Transaction,
+  ): void {
+    this.restorationTransactions.set(
+      offlineTransactionId,
+      restorationTransaction,
+    )
+  }
+
+  private cleanupRestorationTransaction(
+    transactionId: string,
+    shouldRollback = false,
+  ): void {
+    const restorationTx = this.restorationTransactions.get(transactionId)
+    if (!restorationTx) {
+      return
+    }
+
+    this.restorationTransactions.delete(transactionId)
+
+    if (shouldRollback) {
+      restorationTx.rollback()
+      return
+    }
+
+    // Mark as completed so recomputeOptimisticState removes it from consideration.
+    // 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)
+    }
   }
 
   async removeFromOutbox(id: string): Promise<void> {

packages/offline-transactions/src/executor/TransactionExecutor.ts

@@ -1,3 +1,4 @@
+import { createTransaction } from '@tanstack/db'
 import { DefaultRetryPolicy } from '../retry/RetryPolicy'
 import { NonRetriableError } from '../types'
 import { withNestedSpan } from '../telemetry/tracer'
@@ -227,6 +228,10 @@ export class TransactionExecutor {
       this.scheduler.schedule(transaction)
     }
 
+    // Restore optimistic state for loaded transactions
+    // This ensures the UI shows the optimistic data while transactions are pending
+    this.restoreOptimisticState(filteredTransactions)
+
     // Reset retry delays for all loaded transactions so they can run immediately
     this.resetRetryDelays()
 
@@ -242,6 +247,71 @@ export class TransactionExecutor {
     }
   }
 
+  /**
+   * Restore optimistic state from loaded transactions.
+   * Creates internal transactions to hold the mutations so the collection's
+   * state manager can show optimistic data while waiting for sync.
+   */
+  private restoreOptimisticState(
+    transactions: Array<OfflineTransaction>,
+  ): void {
+    for (const offlineTx of transactions) {
+      if (offlineTx.mutations.length === 0) {
+        continue
+      }
+
+      try {
+        // Create a restoration transaction that holds mutations for optimistic state display.
+        // It will never commit - the real mutation is handled by the offline executor.
+        const restorationTx = createTransaction({
+          id: offlineTx.id,
+          autoCommit: false,
+          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's state manager
+        const touchedCollections = new Set<string>()
+        for (const mutation of offlineTx.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.set(
+            restorationTx.id,
+            restorationTx,
+          )
+          mutation.collection._state.recomputeOptimisticState(true)
+        }
+
+        this.offlineExecutor.registerRestorationTransaction(
+          offlineTx.id,
+          restorationTx,
+        )
+      } catch (error) {
+        console.warn(
+          `Failed to restore optimistic state for transaction ${offlineTx.id}:`,
+          error,
+        )
+      }
+    }
+  }
+
   clear(): void {
     this.scheduler.clear()
     this.clearRetryTimer()

packages/offline-transactions/src/outbox/TransactionSerializer.ts

@@ -77,18 +77,24 @@ export class TransactionSerializer {
       throw new Error(`Collection with id ${data.collectionId} not found`)
     }
 
+    const modified = this.deserializeValue(data.modified)
+
+    // Extract the key from the modified data using the collection's getKey function
+    // This is needed for optimistic state restoration to work correctly
+    const key = modified ? collection.getKeyFromItem(modified) : null
+
     // Create a partial PendingMutation - we can't fully reconstruct it but
     // we provide what we can. The executor will need to handle the rest.
     return {
       globalKey: data.globalKey,
       type: data.type as any,
-      modified: this.deserializeValue(data.modified),
+      modified,
       original: this.deserializeValue(data.original),
       changes: this.deserializeValue(data.changes) ?? {},
       collection,
       // These fields would need to be reconstructed by the executor
       mutationId: ``, // Will be regenerated
-      key: null, // Will be extracted from the data
+      key,
       metadata: undefined,
       syncMetadata: {},
       optimistic: true,

packages/offline-transactions/tests/TransactionSerializer.test.ts

@@ -6,6 +6,7 @@ import type { PendingMutation } from '@tanstack/db'
 describe(`TransactionSerializer`, () => {
   const mockCollection = {
     id: `test-collection`,
+    getKeyFromItem: (item: any) => item.id,
   }
 
   const createSerializer = () => {

packages/offline-transactions/tests/harness.ts

@@ -248,12 +248,10 @@ export function createTestOfflineEnvironment(
   const executor = startOfflineExecutor(config)
 
   const waitForLeader = async () => {
-    const start = Date.now()
-    while (!executor.isOfflineEnabled) {
-      if (Date.now() - start > 1000) {
-        throw new Error(`Executor did not become leader within timeout`)
-      }
-      await new Promise((resolve) => setTimeout(resolve, 10))
+    // Wait for full initialization including loading pending transactions
+    await executor.waitForInit()
+    if (!executor.isOfflineEnabled) {
+      throw new Error(`Executor did not become leader`)
     }
   }