@tanstack/offline-transactions 0.0.0

package/src/coordination/BroadcastChannelLeader.ts

@@ -0,0 +1,181 @@
+import { BaseLeaderElection } from "./LeaderElection"
+
+interface LeaderMessage {
+  type: `heartbeat` | `election` | `leadership-claim`
+  tabId: string
+  timestamp: number
+}
+
+export class BroadcastChannelLeader extends BaseLeaderElection {
+  private channelName: string
+  private tabId: string
+  private channel: BroadcastChannel | null = null
+  private heartbeatInterval: number | null = null
+  private electionTimeout: number | null = null
+  private lastLeaderHeartbeat = 0
+  private readonly heartbeatIntervalMs = 5000
+  private readonly electionTimeoutMs = 10000
+
+  constructor(channelName = `offline-executor-leader`) {
+    super()
+    this.channelName = channelName
+    this.tabId = crypto.randomUUID()
+    this.setupChannel()
+  }
+
+  private setupChannel(): void {
+    if (!this.isBroadcastChannelSupported()) {
+      return
+    }
+
+    this.channel = new BroadcastChannel(this.channelName)
+    this.channel.addEventListener(`message`, this.handleMessage)
+  }
+
+  private handleMessage = (event: MessageEvent<LeaderMessage>): void => {
+    const { type, tabId, timestamp } = event.data
+
+    if (tabId === this.tabId) {
+      return
+    }
+
+    switch (type) {
+      case `heartbeat`:
+        if (this.isLeaderState && tabId < this.tabId) {
+          this.releaseLeadership()
+        } else if (!this.isLeaderState) {
+          this.lastLeaderHeartbeat = timestamp
+          this.cancelElection()
+        }
+        break
+
+      case `election`:
+        if (this.isLeaderState) {
+          this.sendHeartbeat()
+        } else if (tabId > this.tabId) {
+          this.startElection()
+        }
+        break
+
+      case `leadership-claim`:
+        if (this.isLeaderState && tabId < this.tabId) {
+          this.releaseLeadership()
+        }
+        break
+    }
+  }
+
+  async requestLeadership(): Promise<boolean> {
+    if (!this.isBroadcastChannelSupported()) {
+      return false
+    }
+
+    if (this.isLeaderState) {
+      return true
+    }
+
+    this.startElection()
+
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        resolve(this.isLeaderState)
+      }, 1000)
+    })
+  }
+
+  private startElection(): void {
+    if (this.electionTimeout) {
+      return
+    }
+
+    this.sendMessage({
+      type: `election`,
+      tabId: this.tabId,
+      timestamp: Date.now(),
+    })
+
+    this.electionTimeout = window.setTimeout(() => {
+      const timeSinceLastHeartbeat = Date.now() - this.lastLeaderHeartbeat
+
+      if (timeSinceLastHeartbeat > this.electionTimeoutMs) {
+        this.claimLeadership()
+      }
+
+      this.electionTimeout = null
+    }, this.electionTimeoutMs)
+  }
+
+  private cancelElection(): void {
+    if (this.electionTimeout) {
+      clearTimeout(this.electionTimeout)
+      this.electionTimeout = null
+    }
+  }
+
+  private claimLeadership(): void {
+    this.notifyLeadershipChange(true)
+    this.sendMessage({
+      type: `leadership-claim`,
+      tabId: this.tabId,
+      timestamp: Date.now(),
+    })
+    this.startHeartbeat()
+  }
+
+  private startHeartbeat(): void {
+    if (this.heartbeatInterval) {
+      return
+    }
+
+    this.sendHeartbeat()
+
+    this.heartbeatInterval = window.setInterval(() => {
+      this.sendHeartbeat()
+    }, this.heartbeatIntervalMs)
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval)
+      this.heartbeatInterval = null
+    }
+  }
+
+  private sendHeartbeat(): void {
+    this.sendMessage({
+      type: `heartbeat`,
+      tabId: this.tabId,
+      timestamp: Date.now(),
+    })
+  }
+
+  private sendMessage(message: LeaderMessage): void {
+    if (this.channel) {
+      this.channel.postMessage(message)
+    }
+  }
+
+  releaseLeadership(): void {
+    this.stopHeartbeat()
+    this.cancelElection()
+    this.notifyLeadershipChange(false)
+  }
+
+  private isBroadcastChannelSupported(): boolean {
+    return typeof BroadcastChannel !== `undefined`
+  }
+
+  static isSupported(): boolean {
+    return typeof BroadcastChannel !== `undefined`
+  }
+
+  dispose(): void {
+    this.releaseLeadership()
+
+    if (this.channel) {
+      this.channel.removeEventListener(`message`, this.handleMessage)
+      this.channel.close()
+      this.channel = null
+    }
+  }
+}

package/src/coordination/LeaderElection.ts

@@ -0,0 +1,35 @@
+import type { LeaderElection } from "../types"
+
+export abstract class BaseLeaderElection implements LeaderElection {
+  protected isLeaderState = false
+  protected listeners: Set<(isLeader: boolean) => void> = new Set()
+
+  abstract requestLeadership(): Promise<boolean>
+  abstract releaseLeadership(): void
+
+  isLeader(): boolean {
+    return this.isLeaderState
+  }
+
+  onLeadershipChange(callback: (isLeader: boolean) => void): () => void {
+    this.listeners.add(callback)
+
+    return () => {
+      this.listeners.delete(callback)
+    }
+  }
+
+  protected notifyLeadershipChange(isLeader: boolean): void {
+    if (this.isLeaderState !== isLeader) {
+      this.isLeaderState = isLeader
+
+      for (const listener of this.listeners) {
+        try {
+          listener(isLeader)
+        } catch (error) {
+          console.warn(`Leadership change listener error:`, error)
+        }
+      }
+    }
+  }
+}

package/src/coordination/WebLocksLeader.ts

@@ -0,0 +1,82 @@
+import { BaseLeaderElection } from "./LeaderElection"
+
+export class WebLocksLeader extends BaseLeaderElection {
+  private lockName: string
+  private releaseLock: (() => void) | null = null
+
+  constructor(lockName = `offline-executor-leader`) {
+    super()
+    this.lockName = lockName
+  }
+
+  async requestLeadership(): Promise<boolean> {
+    if (!this.isWebLocksSupported()) {
+      return false
+    }
+
+    if (this.isLeaderState) {
+      return true
+    }
+
+    try {
+      // First try to acquire the lock with ifAvailable
+      const available = await navigator.locks.request(
+        this.lockName,
+        {
+          mode: `exclusive`,
+          ifAvailable: true,
+        },
+        (lock) => {
+          return lock !== null
+        }
+      )
+
+      if (!available) {
+        return false
+      }
+
+      // Lock is available, now acquire it for real and hold it
+      navigator.locks.request(
+        this.lockName,
+        {
+          mode: `exclusive`,
+        },
+        async (lock) => {
+          if (lock) {
+            this.notifyLeadershipChange(true)
+            // Hold the lock until released
+            return new Promise<void>((resolve) => {
+              this.releaseLock = () => {
+                this.notifyLeadershipChange(false)
+                resolve()
+              }
+            })
+          }
+        }
+      )
+
+      return true
+    } catch (error) {
+      if (error instanceof Error && error.name === `AbortError`) {
+        return false
+      }
+      console.warn(`Web Locks leadership request failed:`, error)
+      return false
+    }
+  }
+
+  releaseLeadership(): void {
+    if (this.releaseLock) {
+      this.releaseLock()
+      this.releaseLock = null
+    }
+  }
+
+  private isWebLocksSupported(): boolean {
+    return typeof navigator !== `undefined` && `locks` in navigator
+  }
+
+  static isSupported(): boolean {
+    return typeof navigator !== `undefined` && `locks` in navigator
+  }
+}

package/src/executor/KeyScheduler.ts

@@ -0,0 +1,123 @@
+import { withSyncSpan } from "../telemetry/tracer"
+import type { OfflineTransaction } from "../types"
+
+export class KeyScheduler {
+  private pendingTransactions: Array<OfflineTransaction> = []
+  private isRunning = false
+
+  schedule(transaction: OfflineTransaction): void {
+    withSyncSpan(
+      `scheduler.schedule`,
+      {
+        "transaction.id": transaction.id,
+        queueLength: this.pendingTransactions.length,
+      },
+      () => {
+        this.pendingTransactions.push(transaction)
+        // Sort by creation time to maintain FIFO order
+        this.pendingTransactions.sort(
+          (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
+        )
+      }
+    )
+  }
+
+  getNextBatch(_maxConcurrency: number): Array<OfflineTransaction> {
+    return withSyncSpan(
+      `scheduler.getNextBatch`,
+      { pendingCount: this.pendingTransactions.length },
+      (span) => {
+        // For sequential processing, we ignore maxConcurrency and only process one transaction at a time
+        if (this.isRunning || this.pendingTransactions.length === 0) {
+          span.setAttribute(`result`, `empty`)
+          return []
+        }
+
+        // Find the first transaction that's ready to run
+        const readyTransaction = this.pendingTransactions.find((tx) =>
+          this.isReadyToRun(tx)
+        )
+
+        if (readyTransaction) {
+          span.setAttribute(`result`, `found`)
+          span.setAttribute(`transaction.id`, readyTransaction.id)
+        } else {
+          span.setAttribute(`result`, `none_ready`)
+        }
+
+        return readyTransaction ? [readyTransaction] : []
+      }
+    )
+  }
+
+  private isReadyToRun(transaction: OfflineTransaction): boolean {
+    return Date.now() >= transaction.nextAttemptAt
+  }
+
+  markStarted(_transaction: OfflineTransaction): void {
+    this.isRunning = true
+  }
+
+  markCompleted(transaction: OfflineTransaction): void {
+    this.removeTransaction(transaction)
+    this.isRunning = false
+  }
+
+  markFailed(_transaction: OfflineTransaction): void {
+    this.isRunning = false
+  }
+
+  private removeTransaction(transaction: OfflineTransaction): void {
+    const index = this.pendingTransactions.findIndex(
+      (tx) => tx.id === transaction.id
+    )
+    if (index >= 0) {
+      this.pendingTransactions.splice(index, 1)
+    }
+  }
+
+  updateTransaction(transaction: OfflineTransaction): void {
+    const index = this.pendingTransactions.findIndex(
+      (tx) => tx.id === transaction.id
+    )
+    if (index >= 0) {
+      this.pendingTransactions[index] = transaction
+      // Re-sort to maintain FIFO order after update
+      this.pendingTransactions.sort(
+        (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
+      )
+    }
+  }
+
+  getPendingCount(): number {
+    return this.pendingTransactions.length
+  }
+
+  getRunningCount(): number {
+    return this.isRunning ? 1 : 0
+  }
+
+  clear(): void {
+    this.pendingTransactions = []
+    this.isRunning = false
+  }
+
+  getAllPendingTransactions(): Array<OfflineTransaction> {
+    return [...this.pendingTransactions]
+  }
+
+  updateTransactions(updatedTransactions: Array<OfflineTransaction>): void {
+    for (const updatedTx of updatedTransactions) {
+      const index = this.pendingTransactions.findIndex(
+        (tx) => tx.id === updatedTx.id
+      )
+      if (index >= 0) {
+        this.pendingTransactions[index] = updatedTx
+      }
+    }
+    // Re-sort to maintain FIFO order after updates
+    this.pendingTransactions.sort(
+      (a, b) => a.createdAt.getTime() - b.createdAt.getTime()
+    )
+  }
+}