@tanstack/offline-transactions 1.0.54 → 1.0.56

package/src/OfflineExecutor.ts

@@ -51,6 +51,7 @@ export class OfflineExecutor {
   private leaderElection: LeaderElection | null
   private onlineDetector: OnlineDetector
   private isLeaderState = false
+  private disposed = false
   private unsubscribeOnline: (() => void) | null = null
   private unsubscribeLeadership: (() => void) | null = null
 
@@ -209,14 +210,19 @@ export class OfflineExecutor {
     if (this.leaderElection) {
       this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(
         (isLeader) => {
+          // A custom elector may repeat the initial result while replay is active.
+          if (this.disposed || isLeader === this.isLeaderState) return
           this.isLeaderState = isLeader
+          if (!isLeader) this.executor?.pause()
 
           if (this.config.onLeadershipChange) {
             this.config.onLeadershipChange(isLeader)
           }
 
           if (isLeader) {
-            this.loadAndReplayTransactions()
+            this.loadAndReplayTransactions().catch((error) => {
+              console.warn(`Failed to load and replay transactions:`, error)
+            })
           }
         },
       )
@@ -264,6 +270,10 @@ export class OfflineExecutor {
       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
@@ -295,6 +305,13 @@ export class OfflineExecutor {
 
         // 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)
 
@@ -327,22 +344,17 @@ export class OfflineExecutor {
       return
     }
 
-    try {
-      // Load pending transactions and restore optimistic state
-      await this.executor.loadPendingTransactions()
+    // Startup must observe a failed read instead of reporting an empty outbox.
+    await this.executor.loadPendingTransactions()
 
-      // 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)
-    }
+    // Replay completion is separate from initialization and durable admission.
+    this.executor.executeAll().catch((error) => {
+      console.warn(`Failed to execute transactions:`, error)
+    })
   }
 
   get isOfflineEnabled(): boolean {
-    return this.mode === `offline` && this.isLeaderState
+    return !this.disposed && this.mode === `offline` && this.isLeaderState
   }
 
   /**
@@ -442,7 +454,11 @@ export class OfflineExecutor {
 
         try {
           await this.outbox.add(transaction)
-          await this.executor.execute(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(
@@ -596,6 +612,8 @@ export class OfflineExecutor {
   }
 
   dispose(): void {
+    this.disposed = true
+    this.executor?.pause()
     for (const collection of Object.values(this.config.collections)) {
       collection.deferDataRefresh = null
     }

package/src/api/OfflineTransaction.ts

@@ -58,8 +58,13 @@ export class OfflineTransaction {
         )
 
         try {
-          await this.persistTransaction(offlineTransaction)
-          // Now block and wait for the executor to complete the real mutation
+          // 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 =

package/src/executor/KeyScheduler.ts

@@ -5,19 +5,27 @@ export class KeyScheduler {
   private pendingTransactions: Array<OfflineTransaction> = []
   private isRunning = false
 
-  schedule(transaction: OfflineTransaction): void {
-    withSyncSpan(
+  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
       },
     )
   }

package/src/executor/TransactionExecutor.ts

@@ -61,7 +61,7 @@ export class TransactionExecutor {
 
   private async runExecution(): Promise<void> {
     while (this.scheduler.getPendingCount() > 0) {
-      if (!this.isOnline()) {
+      if (!this.canExecute()) {
         break
       }
 
@@ -100,8 +100,12 @@ export class TransactionExecutor {
           try {
             const result = await this.runMutationFn(transaction)
 
-            this.scheduler.markCompleted(transaction)
-            await this.outbox.remove(transaction.id)
+            try {
+              // Replay can still see this ID until durable deletion settles.
+              await this.outbox.remove(transaction.id)
+            } finally {
+              this.scheduler.markCompleted(transaction)
+            }
 
             span.setAttribute(`result`, `success`)
             this.offlineExecutor.resolveTransaction(transaction.id, result)
@@ -233,13 +237,16 @@ export class TransactionExecutor {
       filteredTransactions = this.config.beforeRetry(transactions)
     }
 
-    for (const transaction of filteredTransactions) {
-      this.scheduler.schedule(transaction)
-    }
+    // The outbox read or retry hook may outlive this owner's right to replay.
+    if (!this.offlineExecutor.isOfflineEnabled) return
+
+    const newlyLoaded = filteredTransactions.filter((transaction) =>
+      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)
+    this.restoreOptimisticState(newlyLoaded)
 
     // Reset retry delays for all loaded transactions so they can run immediately
     this.resetRetryDelays()
@@ -326,6 +333,11 @@ export class TransactionExecutor {
     this.clearRetryTimer()
   }
 
+  pause(): void {
+    // Retain queued work and let the issued call finish its acknowledgment.
+    this.clearRetryTimer()
+  }
+
   getPendingCount(): number {
     return this.scheduler.getPendingCount()
   }
@@ -334,18 +346,17 @@ export class TransactionExecutor {
     // Clear existing timer
     this.clearRetryTimer()
 
-    if (!this.isOnline()) {
+    if (!this.canExecute()) {
       return
     }
 
-    // Find the earliest retry time among pending transactions
-    const earliestRetryTime = this.getEarliestRetryTime()
+    const nextRetryTime = this.getNextRetryTime()
 
-    if (earliestRetryTime === null) {
+    if (nextRetryTime === null) {
       return // No transactions pending retry
     }
 
-    const delay = Math.max(0, earliestRetryTime - Date.now())
+    const delay = Math.max(0, nextRetryTime - Date.now())
 
     this.retryTimer = setTimeout(() => {
       this.executeAll().catch((error) => {
@@ -354,14 +365,15 @@ export class TransactionExecutor {
     }, delay)
   }
 
-  private getEarliestRetryTime(): number | null {
+  private getNextRetryTime(): number | null {
     const allTransactions = this.scheduler.getAllPendingTransactions()
 
     if (allTransactions.length === 0) {
       return null
     }
 
-    return Math.min(...allTransactions.map((tx) => tx.nextAttemptAt))
+    // Later transactions cannot overtake the FIFO head, even if they are ready.
+    return allTransactions[0]!.nextAttemptAt
   }
 
   private clearRetryTimer(): void {
@@ -371,8 +383,10 @@ export class TransactionExecutor {
     }
   }
 
-  private isOnline(): boolean {
-    return this.offlineExecutor.isOnline()
+  private canExecute(): boolean {
+    return (
+      this.offlineExecutor.isOfflineEnabled && this.offlineExecutor.isOnline()
+    )
   }
 
   getRunningCount(): number {

package/src/outbox/TransactionSerializer.ts

@@ -6,6 +6,21 @@ import type {
 } from '../types'
 import type { Collection, PendingMutation } from '@tanstack/db'
 
+function setDataProperty(
+  object: Record<string, unknown>,
+  key: string,
+  value: unknown,
+): void {
+  if (key !== `__proto__`) object[key] = value
+  else
+    Object.defineProperty(object, key, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    })
+}
+
 export class TransactionSerializer {
   private collections: Record<string, Collection<any, any, any, any, any>>
   private collectionIdToKey: Map<string, string>
@@ -24,6 +39,7 @@ export class TransactionSerializer {
   serialize(transaction: OfflineTransaction): string {
     const serialized: SerializedOfflineTransaction = {
       ...transaction,
+      valueEncoding: 2,
       createdAt: transaction.createdAt.toISOString(),
       mutations: transaction.mutations.map((mutation) =>
         this.serializeMutation(mutation),
@@ -33,9 +49,19 @@ export class TransactionSerializer {
   }
 
   deserialize(data: string): OfflineTransaction {
-    // Parse without a reviver - let deserializeValue handle dates in mutation data
-    // using the { __type: 'Date' } marker system
-    const parsed: SerializedOfflineTransaction = JSON.parse(data)
+    // Old records retain their Date-marker meaning. New records also escape
+    // marker-shaped user objects; the encoding tag is not application metadata.
+    const {
+      valueEncoding,
+      ...parsed
+    }: Omit<SerializedOfflineTransaction, `valueEncoding`> & {
+      valueEncoding?: unknown
+    } = JSON.parse(data)
+    if (valueEncoding !== undefined && valueEncoding !== 2) {
+      throw new Error(
+        `Unsupported transaction value encoding: ${valueEncoding}`,
+      )
+    }
 
     const createdAt = new Date(parsed.createdAt)
     if (isNaN(createdAt.getTime())) {
@@ -48,7 +74,7 @@ export class TransactionSerializer {
       ...parsed,
       createdAt,
       mutations: parsed.mutations.map((mutationData) =>
-        this.deserializeMutation(mutationData),
+        this.deserializeMutation(mutationData, valueEncoding === 2),
       ),
     }
   }
@@ -71,13 +97,16 @@ export class TransactionSerializer {
     }
   }
 
-  private deserializeMutation(data: SerializedMutation): PendingMutation {
+  private deserializeMutation(
+    data: SerializedMutation,
+    escapedObjects: boolean,
+  ): PendingMutation {
     const collection = this.collections[data.collectionId]
     if (!collection) {
       throw new Error(`Collection with id ${data.collectionId} not found`)
     }
 
-    const modified = this.deserializeValue(data.modified)
+    const modified = this.deserializeValue(data.modified, escapedObjects)
 
     // Extract the key from the modified data using the collection's getKey function
     // This is needed for optimistic state restoration to work correctly
@@ -89,8 +118,8 @@ export class TransactionSerializer {
       globalKey: data.globalKey,
       type: data.type as any,
       modified,
-      original: this.deserializeValue(data.original),
-      changes: this.deserializeValue(data.changes) ?? {},
+      original: this.deserializeValue(data.original, escapedObjects),
+      changes: this.deserializeValue(data.changes, escapedObjects) ?? {},
       collection,
       // These fields would need to be reconstructed by the executor
       mutationId: ``, // Will be regenerated
@@ -116,16 +145,19 @@ export class TransactionSerializer {
       const result: any = Array.isArray(value) ? [] : {}
       for (const key in value) {
         if (Object.prototype.hasOwnProperty.call(value, key)) {
-          result[key] = this.serializeValue(value[key])
+          setDataProperty(result, key, this.serializeValue(value[key]))
         }
       }
-      return result
+      return !Array.isArray(value) &&
+        Object.prototype.hasOwnProperty.call(value, `__type`)
+        ? { __type: `Object`, value: result }
+        : result
     }
 
     return value
   }
 
-  private deserializeValue(value: any): any {
+  private deserializeValue(value: any, escapedObjects: boolean): any {
     if (value === null || value === undefined) {
       return value
     }
@@ -144,10 +176,25 @@ export class TransactionSerializer {
     }
 
     if (typeof value === `object`) {
+      // Unwrap once, then decode only the fields: the object's own __type is data.
+      if (escapedObjects && value.__type === `Object`) {
+        if (
+          value.value === null ||
+          typeof value.value !== `object` ||
+          Array.isArray(value.value)
+        ) {
+          throw new Error(`Corrupted Object marker: expected an object value`)
+        }
+        value = value.value
+      }
       const result: any = Array.isArray(value) ? [] : {}
       for (const key in value) {
         if (Object.prototype.hasOwnProperty.call(value, key)) {
-          result[key] = this.deserializeValue(value[key])
+          setDataProperty(
+            result,
+            key,
+            this.deserializeValue(value[key], escapedObjects),
+          )
         }
       }
       return result

package/src/storage/IndexedDBAdapter.ts

@@ -89,6 +89,23 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
     return transaction.objectStore(this.storeName)
   }
 
+  private waitForWrite(
+    store: IDBObjectStore,
+    write: () => void,
+  ): Promise<void> {
+    const transaction = store.transaction
+    return new Promise((resolve, reject) => {
+      // A successful request can still be rolled back by its transaction.
+      transaction.oncomplete = () => resolve()
+      transaction.onabort = () =>
+        reject(
+          transaction.error ??
+            new DOMException(`IndexedDB transaction aborted`, `AbortError`),
+        )
+      write()
+    })
+  }
+
   async get(key: string): Promise<string | null> {
     try {
       const store = await this.getStore(`readonly`)
@@ -106,10 +123,8 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
   async set(key: string, value: string): Promise<void> {
     try {
       const store = await this.getStore(`readwrite`)
-      return new Promise((resolve, reject) => {
-        const request = store.put(value, key)
-        request.onerror = () => reject(request.error)
-        request.onsuccess = () => resolve()
+      return this.waitForWrite(store, () => {
+        store.put(value, key)
       })
     } catch (error) {
       if (
@@ -127,10 +142,8 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
   async delete(key: string): Promise<void> {
     try {
       const store = await this.getStore(`readwrite`)
-      return new Promise((resolve, reject) => {
-        const request = store.delete(key)
-        request.onerror = () => reject(request.error)
-        request.onsuccess = () => resolve()
+      return this.waitForWrite(store, () => {
+        store.delete(key)
       })
     } catch (error) {
       console.warn(`IndexedDB delete failed:`, error)
@@ -154,10 +167,8 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
   async clear(): Promise<void> {
     try {
       const store = await this.getStore(`readwrite`)
-      return new Promise((resolve, reject) => {
-        const request = store.clear()
-        request.onerror = () => reject(request.error)
-        request.onsuccess = () => resolve()
+      return this.waitForWrite(store, () => {
+        store.clear()
       })
     } catch (error) {
       console.warn(`IndexedDB clear failed:`, error)

package/src/types.ts

@@ -57,6 +57,8 @@ export interface OfflineTransaction {
 
 // Serialized representation for storage
 export interface SerializedOfflineTransaction {
+  /** Absent for the original Date-marker format. */
+  valueEncoding?: 2
   id: string
   mutationFnName: string
   mutations: Array<SerializedMutation>
@@ -131,6 +133,7 @@ export interface LeaderElection {
 }
 
 export interface TransactionSignaler {
+  readonly isOfflineEnabled: boolean
   resolveTransaction: (transactionId: string, result: any) => void
   rejectTransaction: (transactionId: string, error: Error) => void
   registerRestorationTransaction: (