@tanstack/offline-transactions 0.0.0

package/src/retry/RetryPolicy.ts

@@ -0,0 +1,41 @@
+import { NonRetriableError } from "../types"
+import { BackoffCalculator } from "./BackoffCalculator"
+import type { RetryPolicy } from "../types"
+
+export class DefaultRetryPolicy implements RetryPolicy {
+  private backoffCalculator: BackoffCalculator
+  private maxRetries: number
+
+  constructor(maxRetries = 10, jitter = true) {
+    this.backoffCalculator = new BackoffCalculator(jitter)
+    this.maxRetries = maxRetries
+  }
+
+  calculateDelay(retryCount: number): number {
+    return this.backoffCalculator.calculate(retryCount)
+  }
+
+  shouldRetry(error: Error, retryCount: number): boolean {
+    if (retryCount >= this.maxRetries) {
+      return false
+    }
+
+    if (error instanceof NonRetriableError) {
+      return false
+    }
+
+    if (error.name === `AbortError`) {
+      return false
+    }
+
+    if (error.message.includes(`401`) || error.message.includes(`403`)) {
+      return false
+    }
+
+    if (error.message.includes(`422`) || error.message.includes(`400`)) {
+      return false
+    }
+
+    return true
+  }
+}

package/src/storage/IndexedDBAdapter.ts

@@ -0,0 +1,119 @@
+import { BaseStorageAdapter } from "./StorageAdapter"
+
+export class IndexedDBAdapter extends BaseStorageAdapter {
+  private dbName: string
+  private storeName: string
+  private db: IDBDatabase | null = null
+
+  constructor(dbName = `offline-transactions`, storeName = `transactions`) {
+    super()
+    this.dbName = dbName
+    this.storeName = storeName
+  }
+
+  private async openDB(): Promise<IDBDatabase> {
+    if (this.db) {
+      return this.db
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(this.dbName, 1)
+
+      request.onerror = () => reject(request.error)
+      request.onsuccess = () => {
+        this.db = request.result
+        resolve(this.db)
+      }
+
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName)
+        }
+      }
+    })
+  }
+
+  private async getStore(
+    mode: IDBTransactionMode = `readonly`
+  ): Promise<IDBObjectStore> {
+    const db = await this.openDB()
+    const transaction = db.transaction([this.storeName], mode)
+    return transaction.objectStore(this.storeName)
+  }
+
+  async get(key: string): Promise<string | null> {
+    try {
+      const store = await this.getStore(`readonly`)
+      return new Promise((resolve, reject) => {
+        const request = store.get(key)
+        request.onerror = () => reject(request.error)
+        request.onsuccess = () => resolve(request.result ?? null)
+      })
+    } catch (error) {
+      console.warn(`IndexedDB get failed:`, error)
+      return null
+    }
+  }
+
+  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()
+      })
+    } catch (error) {
+      if (
+        error instanceof DOMException &&
+        error.name === `QuotaExceededError`
+      ) {
+        throw new Error(
+          `Storage quota exceeded. Consider clearing old transactions.`
+        )
+      }
+      throw error
+    }
+  }
+
+  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()
+      })
+    } catch (error) {
+      console.warn(`IndexedDB delete failed:`, error)
+    }
+  }
+
+  async keys(): Promise<Array<string>> {
+    try {
+      const store = await this.getStore(`readonly`)
+      return new Promise((resolve, reject) => {
+        const request = store.getAllKeys()
+        request.onerror = () => reject(request.error)
+        request.onsuccess = () => resolve(request.result as Array<string>)
+      })
+    } catch (error) {
+      console.warn(`IndexedDB keys failed:`, error)
+      return []
+    }
+  }
+
+  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()
+      })
+    } catch (error) {
+      console.warn(`IndexedDB clear failed:`, error)
+    }
+  }
+}

package/src/storage/LocalStorageAdapter.ts

@@ -0,0 +1,79 @@
+import { BaseStorageAdapter } from "./StorageAdapter"
+
+export class LocalStorageAdapter extends BaseStorageAdapter {
+  private prefix: string
+
+  constructor(prefix = `offline-tx:`) {
+    super()
+    this.prefix = prefix
+  }
+
+  private getKey(key: string): string {
+    return `${this.prefix}${key}`
+  }
+
+  get(key: string): Promise<string | null> {
+    try {
+      return Promise.resolve(localStorage.getItem(this.getKey(key)))
+    } catch (error) {
+      console.warn(`localStorage get failed:`, error)
+      return Promise.resolve(null)
+    }
+  }
+
+  set(key: string, value: string): Promise<void> {
+    try {
+      localStorage.setItem(this.getKey(key), value)
+      return Promise.resolve()
+    } catch (error) {
+      if (
+        error instanceof DOMException &&
+        error.name === `QuotaExceededError`
+      ) {
+        return Promise.reject(
+          new Error(
+            `Storage quota exceeded. Consider clearing old transactions.`
+          )
+        )
+      }
+      return Promise.reject(error)
+    }
+  }
+
+  delete(key: string): Promise<void> {
+    try {
+      localStorage.removeItem(this.getKey(key))
+      return Promise.resolve()
+    } catch (error) {
+      console.warn(`localStorage delete failed:`, error)
+      return Promise.resolve()
+    }
+  }
+
+  keys(): Promise<Array<string>> {
+    try {
+      const keys: Array<string> = []
+      for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i)
+        if (key && key.startsWith(this.prefix)) {
+          keys.push(key.slice(this.prefix.length))
+        }
+      }
+      return Promise.resolve(keys)
+    } catch (error) {
+      console.warn(`localStorage keys failed:`, error)
+      return Promise.resolve([])
+    }
+  }
+
+  async clear(): Promise<void> {
+    try {
+      const keys = await this.keys()
+      for (const key of keys) {
+        localStorage.removeItem(this.getKey(key))
+      }
+    } catch (error) {
+      console.warn(`localStorage clear failed:`, error)
+    }
+  }
+}

package/src/storage/StorageAdapter.ts

@@ -0,0 +1,11 @@
+import type { StorageAdapter } from "../types"
+
+export abstract class BaseStorageAdapter implements StorageAdapter {
+  abstract get(key: string): Promise<string | null>
+  abstract set(key: string, value: string): Promise<void>
+  abstract delete(key: string): Promise<void>
+  abstract keys(): Promise<Array<string>>
+  abstract clear(): Promise<void>
+}
+
+export { type StorageAdapter }

package/src/telemetry/tracer.ts

@@ -0,0 +1,156 @@
+import {
+  trace,
+  type Span,
+  SpanStatusCode,
+  context,
+  type SpanContext,
+} from "@opentelemetry/api"
+
+const TRACER = trace.getTracer("@tanstack/offline-transactions", "0.0.1")
+
+export interface SpanAttrs {
+  [key: string]: string | number | boolean | undefined
+}
+
+interface WithSpanOptions {
+  parentContext?: SpanContext
+}
+
+function getParentContext(options?: WithSpanOptions) {
+  if (options?.parentContext) {
+    const parentSpan = trace.wrapSpanContext(options.parentContext)
+    return trace.setSpan(context.active(), parentSpan)
+  }
+
+  return context.active()
+}
+
+/**
+ * Lightweight span wrapper with error handling.
+ * Uses OpenTelemetry API which is no-op when tracing is disabled.
+ *
+ * By default, creates spans at the current context level (siblings).
+ * Use withNestedSpan if you want parent-child relationships.
+ */
+export async function withSpan<T>(
+  name: string,
+  attrs: SpanAttrs,
+  fn: (span: Span) => Promise<T>,
+  options?: WithSpanOptions
+): Promise<T> {
+  const parentCtx = getParentContext(options)
+  const span = TRACER.startSpan(name, undefined, parentCtx)
+
+  // Filter out undefined attributes
+  const filteredAttrs: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value !== undefined) {
+      filteredAttrs[key] = value
+    }
+  }
+
+  span.setAttributes(filteredAttrs)
+
+  try {
+    const result = await fn(span)
+    span.setStatus({ code: SpanStatusCode.OK })
+    return result
+  } catch (error) {
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : String(error),
+    })
+    span.recordException(error as Error)
+    throw error
+  } finally {
+    span.end()
+  }
+}
+
+/**
+ * Like withSpan but propagates context so child spans nest properly.
+ * Use this when you want operations inside fn to be child spans.
+ */
+export async function withNestedSpan<T>(
+  name: string,
+  attrs: SpanAttrs,
+  fn: (span: Span) => Promise<T>,
+  options?: WithSpanOptions
+): Promise<T> {
+  const parentCtx = getParentContext(options)
+  const span = TRACER.startSpan(name, undefined, parentCtx)
+
+  // Filter out undefined attributes
+  const filteredAttrs: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value !== undefined) {
+      filteredAttrs[key] = value
+    }
+  }
+
+  span.setAttributes(filteredAttrs)
+
+  // Set the span as active context so child spans nest properly
+  const ctx = trace.setSpan(parentCtx, span)
+
+  try {
+    // Execute the function within the span's context
+    const result = await context.with(ctx, () => fn(span))
+    span.setStatus({ code: SpanStatusCode.OK })
+    return result
+  } catch (error) {
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : String(error),
+    })
+    span.recordException(error as Error)
+    throw error
+  } finally {
+    span.end()
+  }
+}
+
+/**
+ * Creates a synchronous span for non-async operations
+ */
+export function withSyncSpan<T>(
+  name: string,
+  attrs: SpanAttrs,
+  fn: (span: Span) => T,
+  options?: WithSpanOptions
+): T {
+  const parentCtx = getParentContext(options)
+  const span = TRACER.startSpan(name, undefined, parentCtx)
+
+  // Filter out undefined attributes
+  const filteredAttrs: Record<string, string | number | boolean> = {}
+  for (const [key, value] of Object.entries(attrs)) {
+    if (value !== undefined) {
+      filteredAttrs[key] = value
+    }
+  }
+
+  span.setAttributes(filteredAttrs)
+
+  try {
+    const result = fn(span)
+    span.setStatus({ code: SpanStatusCode.OK })
+    return result
+  } catch (error) {
+    span.setStatus({
+      code: SpanStatusCode.ERROR,
+      message: error instanceof Error ? error.message : String(error),
+    })
+    span.recordException(error as Error)
+    throw error
+  } finally {
+    span.end()
+  }
+}
+
+/**
+ * Get the current tracer instance
+ */
+export function getTracer() {
+  return TRACER
+}

package/src/types.ts

@@ -0,0 +1,133 @@
+import type {
+  Collection,
+  MutationFnParams,
+  PendingMutation,
+} from "@tanstack/db"
+
+// Extended mutation function that includes idempotency key
+export type OfflineMutationFnParams<
+  T extends object = Record<string, unknown>,
+> = MutationFnParams<T> & {
+  idempotencyKey: string
+}
+
+export type OfflineMutationFn<T extends object = Record<string, unknown>> = (
+  params: OfflineMutationFnParams<T>
+) => Promise<any>
+
+// Simplified mutation structure for serialization
+export interface SerializedMutation {
+  globalKey: string
+  type: string
+  modified: any
+  original: any
+  collectionId: string
+}
+
+export interface SerializedError {
+  name: string
+  message: string
+  stack?: string
+}
+
+export interface SerializedSpanContext {
+  traceId: string
+  spanId: string
+  traceFlags: number
+  traceState?: string
+}
+
+// In-memory representation with full PendingMutation objects
+export interface OfflineTransaction {
+  id: string
+  mutationFnName: string
+  mutations: Array<PendingMutation>
+  keys: Array<string>
+  idempotencyKey: string
+  createdAt: Date
+  retryCount: number
+  nextAttemptAt: number
+  lastError?: SerializedError
+  metadata?: Record<string, any>
+  spanContext?: SerializedSpanContext
+  version: 1
+}
+
+// Serialized representation for storage
+export interface SerializedOfflineTransaction {
+  id: string
+  mutationFnName: string
+  mutations: Array<SerializedMutation>
+  keys: Array<string>
+  idempotencyKey: string
+  createdAt: Date
+  retryCount: number
+  nextAttemptAt: number
+  lastError?: SerializedError
+  metadata?: Record<string, any>
+  spanContext?: SerializedSpanContext
+  version: 1
+}
+
+export interface OfflineConfig {
+  collections: Record<string, Collection>
+  mutationFns: Record<string, OfflineMutationFn>
+  storage?: StorageAdapter
+  maxConcurrency?: number
+  jitter?: boolean
+  beforeRetry?: (
+    transactions: Array<OfflineTransaction>
+  ) => Array<OfflineTransaction>
+  onUnknownMutationFn?: (name: string, tx: OfflineTransaction) => void
+  onLeadershipChange?: (isLeader: boolean) => void
+  leaderElection?: LeaderElection
+  otel?: {
+    endpoint: string
+    headers?: Record<string, string>
+  }
+}
+
+export interface StorageAdapter {
+  get: (key: string) => Promise<string | null>
+  set: (key: string, value: string) => Promise<void>
+  delete: (key: string) => Promise<void>
+  keys: () => Promise<Array<string>>
+  clear: () => Promise<void>
+}
+
+export interface RetryPolicy {
+  calculateDelay: (retryCount: number) => number
+  shouldRetry: (error: Error, retryCount: number) => boolean
+}
+
+export interface LeaderElection {
+  requestLeadership: () => Promise<boolean>
+  releaseLeadership: () => void
+  isLeader: () => boolean
+  onLeadershipChange: (callback: (isLeader: boolean) => void) => () => void
+}
+
+export interface OnlineDetector {
+  subscribe: (callback: () => void) => () => void
+  notifyOnline: () => void
+}
+
+export interface CreateOfflineTransactionOptions {
+  id?: string
+  mutationFnName: string
+  autoCommit?: boolean
+  idempotencyKey?: string
+  metadata?: Record<string, any>
+}
+
+export interface CreateOfflineActionOptions<T> {
+  mutationFnName: string
+  onMutate: (variables: T) => void
+}
+
+export class NonRetriableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = `NonRetriableError`
+  }
+}