@tanstack/offline-transactions 1.0.56 → 1.0.58

package/src/executor/TransactionExecutor.ts

@@ -56,6 +56,7 @@ export class TransactionExecutor {
     } finally {
       this.isExecuting = false
       this.executionPromise = null
+      this.scheduleNextRetry()
     }
   }
 
@@ -73,9 +74,6 @@ export class TransactionExecutor {
 
       await this.executeTransaction(transaction)
     }
-
-    // Schedule next retry after execution completes
-    this.scheduleNextRetry()
   }
 
   private async executeTransaction(
@@ -97,18 +95,9 @@ export class TransactionExecutor {
             span.setAttribute(`retry.attempt`, transaction.retryCount)
           }
 
+          let result: void
           try {
-            const result = await this.runMutationFn(transaction)
-
-            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)
+            result = await this.runMutationFn(transaction)
           } catch (error) {
             const err =
               error instanceof Error ? error : new Error(String(error))
@@ -119,6 +108,20 @@ export class TransactionExecutor {
             ;(err as any)[HANDLED_EXECUTION_ERROR] = true
             throw err
           }
+
+          let removalError: unknown
+          try {
+            // Replay can still see this ID until durable deletion settles.
+            await this.outbox.remove(transaction.id)
+          } catch (error) {
+            removalError = error
+          } finally {
+            this.scheduler.markCompleted(transaction)
+          }
+
+          span.setAttribute(`result`, `success`)
+          this.offlineExecutor.resolveTransaction(transaction.id, result)
+          if (removalError !== undefined) throw removalError
         },
       )
     } catch (error) {
@@ -180,8 +183,14 @@ export class TransactionExecutor {
         span.setAttribute(`shouldRetry`, shouldRetry)
 
         if (!shouldRetry) {
-          this.scheduler.markCompleted(transaction)
-          await this.outbox.remove(transaction.id)
+          let removalError: unknown
+          try {
+            await this.outbox.remove(transaction.id)
+          } catch (cleanupError) {
+            removalError = cleanupError
+          } finally {
+            this.scheduler.markCompleted(transaction)
+          }
           console.warn(
             `Transaction ${transaction.id} failed permanently:`,
             error,
@@ -190,6 +199,7 @@ export class TransactionExecutor {
           span.setAttribute(`result`, `permanent_failure`)
           // Signal permanent failure to the waiting transaction
           this.offlineExecutor.rejectTransaction(transaction.id, error)
+          if (removalError !== undefined) throw removalError
           return
         }
 
@@ -211,7 +221,6 @@ export class TransactionExecutor {
         span.setAttribute(`retryDelay`, delay)
         span.setAttribute(`nextRetryCount`, updatedTransaction.retryCount)
 
-        this.scheduler.markFailed(transaction)
         this.scheduler.updateTransaction(updatedTransaction)
 
         try {
@@ -221,45 +230,64 @@ export class TransactionExecutor {
           span.recordException(persistError as Error)
           span.setAttribute(`result`, `persist_failed`)
           throw persistError
+        } finally {
+          this.scheduler.markFailed(transaction)
         }
-
-        // Schedule retry timer
-        this.scheduleNextRetry()
       },
     )
   }
 
   async loadPendingTransactions(): Promise<void> {
-    const transactions = await this.outbox.getAll()
-    let filteredTransactions = transactions
-
-    if (this.config.beforeRetry) {
-      filteredTransactions = this.config.beforeRetry(transactions)
-    }
+    let removedIds: Array<string> = []
+    await this.outbox.withAll((transactions) => {
+      const { isOfflineEnabled } = this.offlineExecutor
+      if (!isOfflineEnabled) return
+      let filteredTransactions = transactions
+
+      if (this.config.beforeRetry) {
+        filteredTransactions = this.config.beforeRetry(transactions)
+      }
 
-    // The outbox read or retry hook may outlive this owner's right to replay.
-    if (!this.offlineExecutor.isOfflineEnabled) return
+      // The retry hook is user code and may synchronously revoke replay rights.
+      if (!this.offlineExecutor.isOfflineEnabled) return
 
-    const newlyLoaded = filteredTransactions.filter((transaction) =>
-      this.scheduler.schedule(transaction),
-    )
+      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(newlyLoaded)
+      const retainedIds = new Set(filteredTransactions.map(({ id }) => id))
+      removedIds = transactions
+        .filter(({ id }) => !retainedIds.has(id))
+        .map(({ id }) => id)
+      removedIds = this.scheduler.removePendingTransactions(removedIds)
 
-    // Reset retry delays for all loaded transactions so they can run immediately
-    this.resetRetryDelays()
+      // Restore optimistic state for loaded transactions
+      // This ensures the UI shows the optimistic data while transactions are pending
+      this.restoreOptimisticState(newlyLoaded)
 
-    // Schedule retry timer for loaded transactions
-    this.scheduleNextRetry()
+      // Reset retry delays for all loaded transactions so they can run immediately
+      this.resetRetryDelays()
 
-    const removedTransactions = transactions.filter(
-      (tx) => !filteredTransactions.some((filtered) => filtered.id === tx.id),
-    )
+      // Schedule retry timer for loaded transactions
+      this.scheduleNextRetry()
+    })
 
-    if (removedTransactions.length > 0) {
-      await this.outbox.removeMany(removedTransactions.map((tx) => tx.id))
+    if (removedIds.length > 0) {
+      const error = new NonRetriableError(`Transaction excluded by beforeRetry`)
+      await Promise.all(
+        removedIds.map(async (id) => {
+          try {
+            await this.outbox.remove(id)
+            this.offlineExecutor.rejectTransaction(id, error)
+          } catch (cleanupError) {
+            console.warn(
+              `Failed to remove transaction excluded by beforeRetry:`,
+              id,
+              cleanupError,
+            )
+          }
+        }),
+      )
     }
   }
 

package/src/outbox/OutboxManager.ts

@@ -1,5 +1,8 @@
 import { withSpan } from '../telemetry/tracer'
-import { TransactionSerializer } from './TransactionSerializer'
+import {
+  MissingTemporalConstructorError,
+  TransactionSerializer,
+} from './TransactionSerializer'
 import type { OfflineTransaction, StorageAdapter } from '../types'
 import type { Collection } from '@tanstack/db'
 
@@ -7,6 +10,9 @@ export class OutboxManager {
   private storage: StorageAdapter
   private serializer: TransactionSerializer
   private keyPrefix = `tx:`
+  private removalRevision = 0
+  private activeReads = new Set<{ revision: number }>()
+  private removedAtRevision = new Map<string, number>()
 
   constructor(
     storage: StorageAdapter,
@@ -21,6 +27,25 @@ export class OutboxManager {
     return `${this.keyPrefix}${id}`
   }
 
+  private recordRemovals(ids: Iterable<string>): void {
+    this.removalRevision++
+    if (this.activeReads.size === 0) return
+    for (const id of ids) this.removedAtRevision.set(id, this.removalRevision)
+    this.pruneRemovalHistory()
+  }
+
+  private pruneRemovalHistory(): void {
+    if (this.activeReads.size === 0) {
+      this.removedAtRevision.clear()
+      return
+    }
+    let oldestRead = Number.POSITIVE_INFINITY
+    for (const read of this.activeReads)
+      oldestRead = Math.min(oldestRead, read.revision)
+    for (const [id, revision] of this.removedAtRevision)
+      if (revision <= oldestRead) this.removedAtRevision.delete(id)
+  }
+
   async add(transaction: OfflineTransaction): Promise<void> {
     return withSpan(
       `outbox.add`,
@@ -52,6 +77,10 @@ export class OutboxManager {
         span.setAttribute(`result`, `found`)
         return transaction
       } catch (error) {
+        if (error instanceof MissingTemporalConstructorError) {
+          error.message = `transaction ${id}: ${error.message}`
+          throw error
+        }
         console.warn(`Failed to deserialize transaction ${id}:`, error)
         span.setAttribute(`result`, `deserialize_error`)
         return null
@@ -60,35 +89,57 @@ export class OutboxManager {
   }
 
   async getAll(): Promise<Array<OfflineTransaction>> {
-    return withSpan(`outbox.getAll`, {}, async (span) => {
-      const keys = await this.storage.keys()
-      const transactionKeys = keys.filter((key) =>
-        key.startsWith(this.keyPrefix),
-      )
-
-      span.setAttribute(`transactionCount`, transactionKeys.length)
-
-      const transactions: Array<OfflineTransaction> = []
-
-      for (const key of transactionKeys) {
-        const data = await this.storage.get(key)
-        if (data) {
-          try {
-            const transaction = this.serializer.deserialize(data)
-            transactions.push(transaction)
-          } catch (error) {
-            console.warn(
-              `Failed to deserialize transaction from key ${key}:`,
-              error,
-            )
+    return this.withAll((transactions) => transactions)
+  }
+
+  async withAll<T>(
+    consume: (transactions: Array<OfflineTransaction>) => T,
+  ): Promise<T> {
+    const read = { revision: this.removalRevision }
+    this.activeReads.add(read)
+    try {
+      return await withSpan(`outbox.getAll`, {}, async (span) => {
+        const keys = await this.storage.keys()
+        const transactionKeys = keys.filter((key) =>
+          key.startsWith(this.keyPrefix),
+        )
+
+        span.setAttribute(`transactionCount`, transactionKeys.length)
+
+        const transactions: Array<OfflineTransaction> = []
+
+        for (const key of transactionKeys) {
+          const data = await this.storage.get(key)
+          if (data) {
+            try {
+              const transaction = this.serializer.deserialize(data)
+              transactions.push(transaction)
+            } catch (error) {
+              if (error instanceof MissingTemporalConstructorError) {
+                error.message = `transaction ${key.slice(this.keyPrefix.length)}: ${error.message}`
+                throw error
+              }
+              console.warn(
+                `Failed to deserialize transaction from key ${key}:`,
+                error,
+              )
+            }
           }
         }
-      }
 
-      return transactions.sort(
-        (a, b) => a.createdAt.getTime() - b.createdAt.getTime(),
-      )
-    })
+        const currentTransactions = transactions
+          .filter(
+            ({ id }) => (this.removedAtRevision.get(id) ?? 0) <= read.revision,
+          )
+          .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
+        // Keep the read registered until replay admission completes. A durable
+        // removal cannot land between filtering and this synchronous consumer.
+        return consume(currentTransactions)
+      })
+    } finally {
+      this.activeReads.delete(read)
+      this.pruneRemovalHistory()
+    }
   }
 
   async getByKeys(keys: Array<string>): Promise<Array<OfflineTransaction>> {
@@ -119,6 +170,7 @@ export class OutboxManager {
     return withSpan(`outbox.remove`, { 'transaction.id': id }, async () => {
       const key = this.getStorageKey(id)
       await this.storage.delete(key)
+      this.recordRemovals([id])
     })
   }
 
@@ -132,7 +184,9 @@ export class OutboxManager {
     const keys = await this.storage.keys()
     const transactionKeys = keys.filter((key) => key.startsWith(this.keyPrefix))
 
-    await Promise.all(transactionKeys.map((key) => this.storage.delete(key)))
+    await this.removeMany(
+      transactionKeys.map((key) => key.slice(this.keyPrefix.length)),
+    )
   }
 
   async count(): Promise<number> {

package/src/outbox/TransactionSerializer.ts

@@ -6,6 +6,79 @@ import type {
 } from '../types'
 import type { Collection, PendingMutation } from '@tanstack/db'
 
+const temporalConstructorNames = [
+  `Duration`,
+  `Instant`,
+  `PlainDate`,
+  `PlainDateTime`,
+  `PlainMonthDay`,
+  `PlainTime`,
+  `PlainYearMonth`,
+  `ZonedDateTime`,
+] as const
+
+type TemporalConstructorName = (typeof temporalConstructorNames)[number]
+type TemporalConstructor = {
+  from: (value: string) => unknown
+  prototype?: { toString?: () => string }
+}
+
+function getTemporalConstructorName(
+  type: unknown,
+): TemporalConstructorName | undefined {
+  if (typeof type !== `string` || !type.startsWith(`Temporal.`)) return
+  const constructorName = type.slice(
+    `Temporal.`.length,
+  ) as TemporalConstructorName
+  return temporalConstructorNames.includes(constructorName)
+    ? constructorName
+    : undefined
+}
+
+function requireTemporalConstructor(
+  name: TemporalConstructorName,
+): TemporalConstructor {
+  const constructor = (
+    globalThis as {
+      Temporal?: Partial<Record<TemporalConstructorName, TemporalConstructor>>
+    }
+  ).Temporal?.[name]
+  if (typeof constructor?.from !== `function`)
+    throw new MissingTemporalConstructorError(
+      `Missing global Temporal.${name} constructor`,
+    )
+  return constructor
+}
+
+function serializeTemporalValue(
+  value: object,
+  name: TemporalConstructorName,
+): string | undefined {
+  const constructor = requireTemporalConstructor(name)
+  const toString = constructor.prototype?.toString
+  if (typeof toString !== `function` || toString === Object.prototype.toString)
+    return
+  try {
+    const serialized = toString.call(value)
+    return typeof serialized === `string` ? serialized : undefined
+  } catch {
+    // Temporal prototype methods brand-check their receiver. A matching
+    // Symbol.toStringTag without the corresponding internal slots is user data.
+    return
+  }
+}
+
+function mayBeNativeScalar(value: object): boolean {
+  const prototype = Object.getPrototypeOf(value)
+  return (
+    prototype !== null &&
+    prototype !== Object.prototype &&
+    !Array.isArray(value)
+  )
+}
+
+export class MissingTemporalConstructorError extends Error {}
+
 function setDataProperty(
   object: Record<string, unknown>,
   key: string,
@@ -39,8 +112,9 @@ export class TransactionSerializer {
   serialize(transaction: OfflineTransaction): string {
     const serialized: SerializedOfflineTransaction = {
       ...transaction,
-      valueEncoding: 2,
+      valueEncoding: 3,
       createdAt: transaction.createdAt.toISOString(),
+      metadata: this.serializeValue(transaction.metadata, `metadata`),
       mutations: transaction.mutations.map((mutation) =>
         this.serializeMutation(mutation),
       ),
@@ -57,7 +131,11 @@ export class TransactionSerializer {
     }: Omit<SerializedOfflineTransaction, `valueEncoding`> & {
       valueEncoding?: unknown
     } = JSON.parse(data)
-    if (valueEncoding !== undefined && valueEncoding !== 2) {
+    if (
+      valueEncoding !== undefined &&
+      valueEncoding !== 2 &&
+      valueEncoding !== 3
+    ) {
       throw new Error(
         `Unsupported transaction value encoding: ${valueEncoding}`,
       )
@@ -73,8 +151,12 @@ export class TransactionSerializer {
     return {
       ...parsed,
       createdAt,
+      metadata:
+        valueEncoding === 3
+          ? this.deserializeValue(parsed.metadata, valueEncoding)
+          : parsed.metadata,
       mutations: parsed.mutations.map((mutationData) =>
-        this.deserializeMutation(mutationData, valueEncoding === 2),
+        this.deserializeMutation(mutationData, valueEncoding),
       ),
     }
   }
@@ -99,14 +181,14 @@ export class TransactionSerializer {
 
   private deserializeMutation(
     data: SerializedMutation,
-    escapedObjects: boolean,
+    valueEncoding: 2 | 3 | undefined,
   ): 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, escapedObjects)
+    const modified = this.deserializeValue(data.modified, valueEncoding)
 
     // Extract the key from the modified data using the collection's getKey function
     // This is needed for optimistic state restoration to work correctly
@@ -118,8 +200,8 @@ export class TransactionSerializer {
       globalKey: data.globalKey,
       type: data.type as any,
       modified,
-      original: this.deserializeValue(data.original, escapedObjects),
-      changes: this.deserializeValue(data.changes, escapedObjects) ?? {},
+      original: this.deserializeValue(data.original, valueEncoding),
+      changes: this.deserializeValue(data.changes, valueEncoding) ?? {},
       collection,
       // These fields would need to be reconstructed by the executor
       mutationId: ``, // Will be regenerated
@@ -132,32 +214,104 @@ export class TransactionSerializer {
     } as PendingMutation
   }
 
-  private serializeValue(value: any): any {
-    if (value === null || value === undefined) {
-      return value
-    }
+  private serializeValue(
+    value: any,
+    jsonKey?: string | false,
+    ancestors = new WeakSet<object>(),
+  ): any {
+    if (value === null || typeof value !== `object`) return value
 
-    if (value instanceof Date) {
+    if (jsonKey !== false && value instanceof Date) {
       return { __type: `Date`, value: value.toISOString() }
     }
 
-    if (typeof value === `object`) {
-      const result: any = Array.isArray(value) ? [] : {}
-      for (const key in value) {
-        if (Object.prototype.hasOwnProperty.call(value, key)) {
-          setDataProperty(result, key, this.serializeValue(value[key]))
+    const temporalConstructorName =
+      jsonKey !== false && mayBeNativeScalar(value)
+        ? getTemporalConstructorName(value[Symbol.toStringTag])
+        : undefined
+    if (temporalConstructorName) {
+      const temporalValue = serializeTemporalValue(
+        value,
+        temporalConstructorName,
+      )
+      if (temporalValue !== undefined)
+        return {
+          __type: `Temporal`,
+          type: `Temporal.${temporalConstructorName}`,
+          value: temporalValue,
         }
+    }
+
+    if (ancestors.has(value))
+      throw new TypeError(`Converting circular structure to JSON`)
+
+    const toJSON = typeof jsonKey === `string` && value.toJSON
+    if (typeof toJSON === `function`) {
+      const replacement = toJSON.call(value, jsonKey)
+      if (replacement === value) {
+        return this.serializeValue(replacement, false, ancestors)
       }
-      return !Array.isArray(value) &&
-        Object.prototype.hasOwnProperty.call(value, `__type`)
-        ? { __type: `Object`, value: result }
-        : result
+
+      ancestors.add(value)
+      try {
+        return this.serializeValue(replacement, false, ancestors)
+      } finally {
+        ancestors.delete(value)
+      }
+    }
+    if (
+      jsonKey !== undefined &&
+      (value instanceof Boolean ||
+        value instanceof BigInt ||
+        value instanceof Number ||
+        value instanceof String)
+    ) {
+      return value.valueOf()
     }
 
-    return value
+    ancestors.add(value)
+
+    const isArray = Array.isArray(value)
+    const result: any = isArray ? [] : {}
+    try {
+      if (isArray) {
+        const length = value.length
+        for (let index = 0; index < length; index++) {
+          const key = String(index)
+          setDataProperty(
+            result,
+            key,
+            this.serializeValue(
+              value[index],
+              jsonKey === undefined ? undefined : key,
+              ancestors,
+            ),
+          )
+        }
+      } else {
+        for (const key of Object.keys(value)) {
+          setDataProperty(
+            result,
+            key,
+            this.serializeValue(
+              value[key],
+              jsonKey === undefined ? undefined : key,
+              ancestors,
+            ),
+          )
+        }
+      }
+    } finally {
+      ancestors.delete(value)
+    }
+    if (jsonKey === false && typeof result.toJSON === `function`)
+      delete result.toJSON
+    return !isArray && Object.prototype.hasOwnProperty.call(value, `__type`)
+      ? { __type: `Object`, value: result }
+      : result
   }
 
-  private deserializeValue(value: any, escapedObjects: boolean): any {
+  private deserializeValue(value: any, valueEncoding: 2 | 3 | undefined): any {
     if (value === null || value === undefined) {
       return value
     }
@@ -175,9 +329,22 @@ export class TransactionSerializer {
       return date
     }
 
+    if (
+      valueEncoding === 3 &&
+      typeof value === `object` &&
+      value.__type === `Temporal`
+    ) {
+      const constructorName = getTemporalConstructorName(value.type)
+      if (!constructorName)
+        throw new Error(`Corrupted Temporal marker: invalid type field`)
+      if (typeof value.value !== `string`)
+        throw new Error(`Corrupted Temporal marker: missing value field`)
+      return requireTemporalConstructor(constructorName).from(value.value)
+    }
+
     if (typeof value === `object`) {
       // Unwrap once, then decode only the fields: the object's own __type is data.
-      if (escapedObjects && value.__type === `Object`) {
+      if (valueEncoding !== undefined && value.__type === `Object`) {
         if (
           value.value === null ||
           typeof value.value !== `object` ||
@@ -193,7 +360,7 @@ export class TransactionSerializer {
           setDataProperty(
             result,
             key,
-            this.deserializeValue(value[key], escapedObjects),
+            this.deserializeValue(value[key], valueEncoding),
           )
         }
       }

package/src/types.ts

@@ -58,7 +58,7 @@ export interface OfflineTransaction {
 // Serialized representation for storage
 export interface SerializedOfflineTransaction {
   /** Absent for the original Date-marker format. */
-  valueEncoding?: 2
+  valueEncoding?: 2 | 3
   id: string
   mutationFnName: string
   mutations: Array<SerializedMutation>