Open History to see the last commit
1// Storage adapters
2import {
3 createOptimisticAction,
4 createTransaction,
5 safeRandomUUID,
6} from '@tanstack/db'
7import { IndexedDBAdapter } from './storage/IndexedDBAdapter'
8import { LocalStorageAdapter } from './storage/LocalStorageAdapter'
9
10// Core components
11import { OutboxManager } from './outbox/OutboxManager'
12import { KeyScheduler } from './executor/KeyScheduler'
13import { TransactionExecutor } from './executor/TransactionExecutor'
14
15// Coordination
16import { WebLocksLeader } from './coordination/WebLocksLeader'
17import { BroadcastChannelLeader } from './coordination/BroadcastChannelLeader'
18
19// Connectivity
20import { WebOnlineDetector } from './connectivity/OnlineDetector'
21
22// API
23import { OfflineTransaction as OfflineTransactionAPI } from './api/OfflineTransaction'
24import { createOfflineAction } from './api/OfflineAction'
25
26// TanStack DB primitives
27
28// Replay
29import { withNestedSpan, withSpan } from './telemetry/tracer'
30import type {
31 CreateOfflineActionOptions,
32 CreateOfflineTransactionOptions,
33 LeaderElection,
34 OfflineConfig,
35 OfflineMode,
36 OfflineTransaction,
37 OnlineDetector,
38 StorageAdapter,
39 StorageDiagnostic,
40} from './types'
41import type { Transaction } from '@tanstack/db'
42
43export class OfflineExecutor {
44 private config: OfflineConfig
45
46 // @ts-expect-error - Set during async initialization in initialize()
47 private storage: StorageAdapter | null
48 private outbox: OutboxManager | null
49 private scheduler: KeyScheduler
50 private executor: TransactionExecutor | null
51 private leaderElection: LeaderElection | null
52 private onlineDetector: OnlineDetector
53 private isLeaderState = false
54 private unsubscribeOnline: (() => void) | null = null
55 private unsubscribeLeadership: (() => void) | null = null
56
57 // Public diagnostic properties
58 public readonly mode: OfflineMode
59 public readonly storageDiagnostic: StorageDiagnostic
60
61 // Track initialization completion
62 private initPromise: Promise<void>
63 private initResolve!: () => void
64 private initReject!: (error: Error) => void
65
66 // Coordination mechanism for blocking transactions
67 private pendingTransactionPromises: Map<
68 string,
69 {
70 promise: Promise<any>
71 resolve: (result: any) => void
72 reject: (error: Error) => void
73 }
74 > = new Map()
75
76 // Track restoration transactions for cleanup when offline transactions complete
77 private restorationTransactions: Map<string, Transaction> = new Map()
78
79 constructor(config: OfflineConfig) {
80 this.config = config
81 this.scheduler = new KeyScheduler()
82 this.onlineDetector = config.onlineDetector ?? new WebOnlineDetector()
83
84 // Initialize as pending - will be set by async initialization
85 this.storage = null
86 this.outbox = null
87 this.executor = null
88 this.leaderElection = null
89
90 // Temporary diagnostic - will be updated by async initialization
91 this.mode = `offline`
92 this.storageDiagnostic = {
93 code: `STORAGE_AVAILABLE`,
94 mode: `offline`,
95 message: `Initializing storage...`,
96 }
97
98 // Create initialization promise
99 this.initPromise = new Promise((resolve, reject) => {
100 this.initResolve = resolve
101 this.initReject = reject
102 })
103
104 this.initialize()
105 }
106
107 /**
108 * Probe storage availability and create appropriate adapter.
109 * Returns null if no storage is available (online-only mode).
110 */
111 private async createStorage(): Promise<{
112 storage: StorageAdapter | null
113 diagnostic: StorageDiagnostic
114 }> {
115 // If user provided custom storage, use it without probing
116 if (this.config.storage) {
117 return {
118 storage: this.config.storage,
119 diagnostic: {
120 code: `STORAGE_AVAILABLE`,
121 mode: `offline`,
122 message: `Using custom storage adapter`,
123 },
124 }
125 }
126
127 // Probe IndexedDB first
128 const idbProbe = await IndexedDBAdapter.probe()
129 if (idbProbe.available) {
130 return {
131 storage: new IndexedDBAdapter(),
132 diagnostic: {
133 code: `STORAGE_AVAILABLE`,
134 mode: `offline`,
135 message: `Using IndexedDB for offline storage`,
136 },
137 }
138 }
139
140 // IndexedDB failed, try localStorage
141 const lsProbe = LocalStorageAdapter.probe()
142 if (lsProbe.available) {
143 return {
144 storage: new LocalStorageAdapter(),
145 diagnostic: {
146 code: `INDEXEDDB_UNAVAILABLE`,
147 mode: `offline`,
148 message: `IndexedDB unavailable, using localStorage fallback`,
149 error: idbProbe.error,
150 },
151 }
152 }
153
154 // Both failed - determine the diagnostic code
155 const isSecurityError =
156 idbProbe.error?.name === `SecurityError` ||
157 lsProbe.error?.name === `SecurityError`
158 const isQuotaError =
159 idbProbe.error?.name === `QuotaExceededError` ||
160 lsProbe.error?.name === `QuotaExceededError`
161
162 let code: StorageDiagnostic[`code`]
163 let message: string
164
165 if (isSecurityError) {
166 code = `STORAGE_BLOCKED`
167 message = `Storage blocked (private mode or security restrictions). Running in online-only mode.`
168 } else if (isQuotaError) {
169 code = `QUOTA_EXCEEDED`
170 message = `Storage quota exceeded. Running in online-only mode.`
171 } else {
172 code = `UNKNOWN_ERROR`
173 message = `Storage unavailable due to unknown error. Running in online-only mode.`
174 }
175
176 return {
177 storage: null,
178 diagnostic: {
179 code,
180 mode: `online-only`,
181 message,
182 error: idbProbe.error || lsProbe.error,
183 },
184 }
185 }
186
187 private createLeaderElection(): LeaderElection {
188 if (this.config.leaderElection) {
189 return this.config.leaderElection
190 }
191
192 if (WebLocksLeader.isSupported()) {
193 return new WebLocksLeader()
194 } else if (BroadcastChannelLeader.isSupported()) {
195 return new BroadcastChannelLeader()
196 } else {
197 // Fallback: always be leader in environments without multi-tab support
198 return {
199 requestLeadership: () => Promise.resolve(true),
200 releaseLeadership: () => {},
201 isLeader: () => true,
202 onLeadershipChange: () => () => {},
203 }
204 }
205 }
206
207 private setupEventListeners(): void {
208 // Only set up leader election listeners if we have storage
209 if (this.leaderElection) {
210 this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(
211 (isLeader) => {
212 this.isLeaderState = isLeader
213
214 if (this.config.onLeadershipChange) {
215 this.config.onLeadershipChange(isLeader)
216 }
217
218 if (isLeader) {
219 this.loadAndReplayTransactions()
220 }
221 },
222 )
223 }
224
225 this.unsubscribeOnline = this.onlineDetector.subscribe(() => {
226 if (this.isOfflineEnabled && this.executor) {
227 this.executor.resetRetryDelays()
228
229 if (this.scheduler.getPendingCount() > 0) {
230 const barrierPromise = this.executor.executeAll()
231
232 for (const collection of Object.values(this.config.collections)) {
233 collection.deferDataRefresh = barrierPromise
234 }
235
236 barrierPromise
237 .catch((error) => {
238 console.warn(
239 `Failed to execute transactions on connectivity change:`,
240 error,
241 )
242 })
243 .finally(() => {
244 for (const collection of Object.values(this.config.collections)) {
245 if (collection.deferDataRefresh === barrierPromise) {
246 collection.deferDataRefresh = null
247 }
248 }
249 })
250 } else {
251 this.executor.executeAll().catch((error) => {
252 console.warn(
253 `Failed to execute transactions on connectivity change:`,
254 error,
255 )
256 })
257 }
258 }
259 })
260 }
261
262 private async initialize(): Promise<void> {
263 return withSpan(`executor.initialize`, {}, async (span) => {
264 try {
265 // Probe storage and create adapter
266 const { storage, diagnostic } = await this.createStorage()
267
268 // Cast to writable to set readonly properties
269 ;(this as any).storage = storage
270 ;(this as any).storageDiagnostic = diagnostic
271 ;(this as any).mode = diagnostic.mode
272
273 span.setAttribute(`storage.mode`, diagnostic.mode)
274 span.setAttribute(`storage.code`, diagnostic.code)
275
276 if (!storage) {
277 // Online-only mode - notify callback and skip offline setup
278 if (this.config.onStorageFailure) {
279 this.config.onStorageFailure(diagnostic)
280 }
281 span.setAttribute(`result`, `online-only`)
282 this.initResolve()
283 return
284 }
285
286 // Storage available - set up offline components
287 this.outbox = new OutboxManager(storage, this.config.collections)
288 this.executor = new TransactionExecutor(
289 this.scheduler,
290 this.outbox,
291 this.config,
292 this,
293 )
294 this.leaderElection = this.createLeaderElection()
295
296 // Request leadership first
297 const isLeader = await this.leaderElection.requestLeadership()
298 this.isLeaderState = isLeader
299 span.setAttribute(`isLeader`, isLeader)
300
301 // Set up event listeners after leadership is established
302 // This prevents the callback from being called multiple times
303 this.setupEventListeners()
304
305 // Notify initial leadership state
306 if (this.config.onLeadershipChange) {
307 this.config.onLeadershipChange(isLeader)
308 }
309
310 if (isLeader) {
311 await this.loadAndReplayTransactions()
312 }
313 span.setAttribute(`result`, `offline-enabled`)
314 this.initResolve()
315 } catch (error) {
316 console.warn(`Failed to initialize offline executor:`, error)
317 span.setAttribute(`result`, `failed`)
318 this.initReject(
319 error instanceof Error ? error : new Error(String(error)),
320 )
321 }
322 })
323 }
324
325 private async loadAndReplayTransactions(): Promise<void> {
326 if (!this.executor) {
327 return
328 }
329
330 try {
331 // Load pending transactions and restore optimistic state
332 await this.executor.loadPendingTransactions()
333
334 // Start execution in the background - don't await to avoid blocking initialization
335 // The transactions will execute and complete asynchronously
336 this.executor.executeAll().catch((error) => {
337 console.warn(`Failed to execute transactions:`, error)
338 })
339 } catch (error) {
340 console.warn(`Failed to load and replay transactions:`, error)
341 }
342 }
343
344 get isOfflineEnabled(): boolean {
345 return this.mode === `offline` && this.isLeaderState
346 }
347
348 /**
349 * Wait for the executor to fully initialize.
350 * This ensures that pending transactions are loaded and optimistic state is restored.
351 */
352 async waitForInit(): Promise<void> {
353 return this.initPromise
354 }
355
356 createOfflineTransaction(
357 options: CreateOfflineTransactionOptions,
358 ): Transaction | OfflineTransactionAPI {
359 const mutationFn = this.config.mutationFns[options.mutationFnName]
360
361 if (!mutationFn) {
362 throw new Error(`Unknown mutation function: ${options.mutationFnName}`)
363 }
364
365 // Check leadership immediately and use the appropriate primitive
366 if (!this.isOfflineEnabled) {
367 // Non-leader: use createTransaction directly with the resolved mutation function
368 // We need to wrap it to add the idempotency key
369 return createTransaction({
370 autoCommit: options.autoCommit ?? true,
371 mutationFn: (params) =>
372 mutationFn({
373 ...params,
374 idempotencyKey: options.idempotencyKey || safeRandomUUID(),
375 }),
376 metadata: options.metadata,
377 })
378 }
379
380 // Leader: use OfflineTransaction wrapper for offline persistence
381 return new OfflineTransactionAPI(
382 options,
383 mutationFn,
384 this.persistTransaction.bind(this),
385 this,
386 )
387 }
388
389 createOfflineAction<T>(options: CreateOfflineActionOptions<T>) {
390 const mutationFn = this.config.mutationFns[options.mutationFnName]
391
392 if (!mutationFn) {
393 throw new Error(`Unknown mutation function: ${options.mutationFnName}`)
394 }
395
396 // Return a wrapper that checks leadership status at call time
397 return (variables: T) => {
398 // Check leadership when action is called, not when it's created
399 if (!this.isOfflineEnabled) {
400 // Non-leader: use createOptimisticAction directly
401 const action = createOptimisticAction({
402 mutationFn: (vars, params) =>
403 mutationFn({
404 ...vars,
405 ...params,
406 idempotencyKey: safeRandomUUID(),
407 }),
408 onMutate: options.onMutate,
409 })
410 return action(variables)
411 }
412
413 // Leader: use the offline action wrapper
414 const action = createOfflineAction(
415 options,
416 mutationFn,
417 this.persistTransaction.bind(this),
418 this,
419 )
420 return action(variables)
421 }
422 }
423
424 private async persistTransaction(
425 transaction: OfflineTransaction,
426 ): Promise<void> {
427 // Wait for initialization to complete
428 await this.initPromise
429
430 return withNestedSpan(
431 `executor.persistTransaction`,
432 {
433 'transaction.id': transaction.id,
434 'transaction.mutationFnName': transaction.mutationFnName,
435 },
436 async (span) => {
437 if (!this.isOfflineEnabled || !this.outbox || !this.executor) {
438 span.setAttribute(`result`, `skipped_not_leader`)
439 this.resolveTransaction(transaction.id, undefined)
440 return
441 }
442
443 try {
444 await this.outbox.add(transaction)
445 await this.executor.execute(transaction)
446 span.setAttribute(`result`, `persisted`)
447 } catch (error) {
448 console.error(
449 `Failed to persist offline transaction ${transaction.id}:`,
450 error,
451 )
452 span.setAttribute(`result`, `failed`)
453 throw error
454 }
455 },
456 )
457 }
458
459 // Method for OfflineTransaction to wait for completion
460 async waitForTransactionCompletion(transactionId: string): Promise<any> {
461 const existing = this.pendingTransactionPromises.get(transactionId)
462 if (existing) {
463 return existing.promise
464 }
465
466 const deferred: {
467 promise: Promise<any>
468 resolve: (result: any) => void
469 reject: (error: Error) => void
470 } = {} as any
471
472 deferred.promise = new Promise((resolve, reject) => {
473 deferred.resolve = resolve
474 deferred.reject = reject
475 })
476
477 this.pendingTransactionPromises.set(transactionId, deferred)
478 return deferred.promise
479 }
480
481 // Method for TransactionExecutor to signal completion
482 resolveTransaction(transactionId: string, result: any): void {
483 const deferred = this.pendingTransactionPromises.get(transactionId)
484 if (deferred) {
485 deferred.resolve(result)
486 this.pendingTransactionPromises.delete(transactionId)
487 }
488
489 // Clean up the restoration transaction - the sync will provide authoritative data
490 this.cleanupRestorationTransaction(transactionId)
491 }
492
493 // Method for TransactionExecutor to signal failure
494 rejectTransaction(transactionId: string, error: Error): void {
495 const deferred = this.pendingTransactionPromises.get(transactionId)
496 if (deferred) {
497 deferred.reject(error)
498 this.pendingTransactionPromises.delete(transactionId)
499 }
500
501 // Clean up the restoration transaction and rollback optimistic state
502 this.cleanupRestorationTransaction(transactionId, true)
503 }
504
505 // Method for TransactionExecutor to register restoration transactions
506 registerRestorationTransaction(
507 offlineTransactionId: string,
508 restorationTransaction: Transaction,
509 ): void {
510 this.restorationTransactions.set(
511 offlineTransactionId,
512 restorationTransaction,
513 )
514 }
515
516 private cleanupRestorationTransaction(
517 transactionId: string,
518 shouldRollback = false,
519 ): void {
520 const restorationTx = this.restorationTransactions.get(transactionId)
521 if (!restorationTx) {
522 return
523 }
524
525 this.restorationTransactions.delete(transactionId)
526
527 if (shouldRollback) {
528 restorationTx.rollback()
529 return
530 }
531
532 // Mark as completed so recomputeOptimisticState removes it from consideration.
533 // The actual data will come from the sync.
534 restorationTx.setState(`completed`)
535
536 // Remove from each collection's transaction map and recompute
537 const touchedCollections = new Set<string>()
538 for (const mutation of restorationTx.mutations) {
539 // Defensive check for corrupted deserialized data
540 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
541 if (!mutation.collection) {
542 continue
543 }
544 const collectionId = mutation.collection.id
545 if (touchedCollections.has(collectionId)) {
546 continue
547 }
548 touchedCollections.add(collectionId)
549 mutation.collection._state.transactions.delete(restorationTx.id)
550 mutation.collection._state.recomputeOptimisticState(false)
551 }
552 }
553
554 async removeFromOutbox(id: string): Promise<void> {
555 if (!this.outbox) {
556 return
557 }
558 await this.outbox.remove(id)
559 }
560
561 async peekOutbox(): Promise<Array<OfflineTransaction>> {
562 if (!this.outbox) {
563 return []
564 }
565 return this.outbox.getAll()
566 }
567
568 async clearOutbox(): Promise<void> {
569 if (!this.outbox || !this.executor) {
570 return
571 }
572 await this.outbox.clear()
573 this.executor.clear()
574 }
575
576 getPendingCount(): number {
577 if (!this.executor) {
578 return 0
579 }
580 return this.executor.getPendingCount()
581 }
582
583 getRunningCount(): number {
584 if (!this.executor) {
585 return 0
586 }
587 return this.executor.getRunningCount()
588 }
589
590 getOnlineDetector(): OnlineDetector {
591 return this.onlineDetector
592 }
593
594 isOnline(): boolean {
595 return this.onlineDetector.isOnline()
596 }
597
598 dispose(): void {
599 for (const collection of Object.values(this.config.collections)) {
600 collection.deferDataRefresh = null
601 }
602
603 if (this.unsubscribeOnline) {
604 this.unsubscribeOnline()
605 this.unsubscribeOnline = null
606 }
607
608 if (this.unsubscribeLeadership) {
609 this.unsubscribeLeadership()
610 this.unsubscribeLeadership = null
611 }
612
613 if (this.leaderElection) {
614 this.leaderElection.releaseLeadership()
615
616 if (`dispose` in this.leaderElection) {
617 ;(this.leaderElection as any).dispose()
618 }
619 }
620
621 this.onlineDetector.dispose()
622 }
623}
624
625export function startOfflineExecutor(config: OfflineConfig): OfflineExecutor {
626 return new OfflineExecutor(config)
627}