@tanstack/offline-transactions 1.0.56 → 1.0.59

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,
@@ -21,6 +94,17 @@ function setDataProperty(
     })
 }
 
+function assertOutboxPhase(
+  phase: unknown,
+): asserts phase is `deletion-pending` | `rejection-pending` | undefined {
+  if (
+    phase !== undefined &&
+    phase !== `deletion-pending` &&
+    phase !== `rejection-pending`
+  )
+    throw new Error(`Unsupported transaction outbox phase`)
+}
+
 export class TransactionSerializer {
   private collections: Record<string, Collection<any, any, any, any, any>>
   private collectionIdToKey: Map<string, string>
@@ -37,10 +121,12 @@ export class TransactionSerializer {
   }
 
   serialize(transaction: OfflineTransaction): string {
+    assertOutboxPhase(transaction.outboxPhase)
     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),
       ),
@@ -53,15 +139,22 @@ export class TransactionSerializer {
     // marker-shaped user objects; the encoding tag is not application metadata.
     const {
       valueEncoding,
+      outboxPhase,
       ...parsed
-    }: Omit<SerializedOfflineTransaction, `valueEncoding`> & {
+    }: Omit<SerializedOfflineTransaction, `valueEncoding` | `outboxPhase`> & {
       valueEncoding?: unknown
+      outboxPhase?: unknown
     } = JSON.parse(data)
-    if (valueEncoding !== undefined && valueEncoding !== 2) {
+    if (
+      valueEncoding !== undefined &&
+      valueEncoding !== 2 &&
+      valueEncoding !== 3
+    ) {
       throw new Error(
         `Unsupported transaction value encoding: ${valueEncoding}`,
       )
     }
+    assertOutboxPhase(outboxPhase)
 
     const createdAt = new Date(parsed.createdAt)
     if (isNaN(createdAt.getTime())) {
@@ -72,9 +165,14 @@ export class TransactionSerializer {
 
     return {
       ...parsed,
+      ...(outboxPhase === undefined ? {} : { outboxPhase }),
       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 +197,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 +216,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 +230,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)
+      }
+
+      ancestors.add(value)
+      try {
+        return this.serializeValue(replacement, false, ancestors)
+      } finally {
+        ancestors.delete(value)
       }
-      return !Array.isArray(value) &&
-        Object.prototype.hasOwnProperty.call(value, `__type`)
-        ? { __type: `Object`, value: result }
-        : result
+    }
+    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 +345,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 +376,7 @@ export class TransactionSerializer {
           setDataProperty(
             result,
             key,
-            this.deserializeValue(value[key], escapedObjects),
+            this.deserializeValue(value[key], valueEncoding),
           )
         }
       }

package/src/storage/IndexedDBAdapter.ts

@@ -147,6 +147,7 @@ export class IndexedDBAdapter extends BaseStorageAdapter {
       })
     } catch (error) {
       console.warn(`IndexedDB delete failed:`, error)
+      throw error
     }
   }
 

package/src/storage/LocalStorageAdapter.ts

@@ -84,7 +84,7 @@ export class LocalStorageAdapter extends BaseStorageAdapter {
       return Promise.resolve()
     } catch (error) {
       console.warn(`localStorage delete failed:`, error)
-      return Promise.resolve()
+      return Promise.reject(error)
     }
   }
 

package/src/types.ts

@@ -49,6 +49,8 @@ export interface OfflineTransaction {
   createdAt: Date
   retryCount: number
   nextAttemptAt: number
+  /** Provider work has settled; only durable outbox deletion remains. */
+  outboxPhase?: `deletion-pending` | `rejection-pending`
   lastError?: SerializedError
   metadata?: Record<string, any>
   spanContext?: SerializedSpanContext
@@ -58,7 +60,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>
@@ -67,6 +69,8 @@ export interface SerializedOfflineTransaction {
   createdAt: string
   retryCount: number
   nextAttemptAt: number
+  /** Absent in older records and while mutationFn may still need to run. */
+  outboxPhase?: `deletion-pending` | `rejection-pending`
   lastError?: SerializedError
   metadata?: Record<string, any>
   spanContext?: SerializedSpanContext