@tanstack/offline-transactions 0.0.0

package/dist/cjs/types.cjs.map

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

package/dist/cjs/types.d.cts

@@ -0,0 +1,101 @@
+import { Collection, MutationFnParams, PendingMutation } from '@tanstack/db';
+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>;
+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;
+}
+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;
+}
+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 declare class NonRetriableError extends Error {
+    constructor(message: string);
+}

package/dist/esm/OfflineExecutor.d.ts

@@ -0,0 +1,39 @@
+import { DefaultOnlineDetector } from './connectivity/OnlineDetector.js';
+import { OfflineTransaction as OfflineTransactionAPI } from './api/OfflineTransaction.js';
+import { CreateOfflineActionOptions, CreateOfflineTransactionOptions, OfflineConfig, OfflineTransaction } from './types.js';
+import { Transaction } from '@tanstack/db';
+export declare class OfflineExecutor {
+    private config;
+    private storage;
+    private outbox;
+    private scheduler;
+    private executor;
+    private leaderElection;
+    private onlineDetector;
+    private isLeaderState;
+    private unsubscribeOnline;
+    private unsubscribeLeadership;
+    private pendingTransactionPromises;
+    constructor(config: OfflineConfig);
+    private createStorage;
+    private createLeaderElection;
+    private setupEventListeners;
+    private initialize;
+    private loadAndReplayTransactions;
+    get isOfflineEnabled(): boolean;
+    createOfflineTransaction(options: CreateOfflineTransactionOptions): Transaction | OfflineTransactionAPI;
+    createOfflineAction<T>(options: CreateOfflineActionOptions<T>): (variables: T) => Transaction<Record<string, unknown>>;
+    private persistTransaction;
+    waitForTransactionCompletion(transactionId: string): Promise<any>;
+    resolveTransaction(transactionId: string, result: any): void;
+    rejectTransaction(transactionId: string, error: Error): void;
+    removeFromOutbox(id: string): Promise<void>;
+    peekOutbox(): Promise<Array<OfflineTransaction>>;
+    clearOutbox(): Promise<void>;
+    notifyOnline(): void;
+    getPendingCount(): number;
+    getRunningCount(): number;
+    getOnlineDetector(): DefaultOnlineDetector;
+    dispose(): void;
+}
+export declare function startOfflineExecutor(config: OfflineConfig): OfflineExecutor;

package/dist/esm/OfflineExecutor.js

@@ -0,0 +1,266 @@
+import { createTransaction, createOptimisticAction } from "@tanstack/db";
+import { IndexedDBAdapter } from "./storage/IndexedDBAdapter.js";
+import { LocalStorageAdapter } from "./storage/LocalStorageAdapter.js";
+import { OutboxManager } from "./outbox/OutboxManager.js";
+import { KeyScheduler } from "./executor/KeyScheduler.js";
+import { TransactionExecutor } from "./executor/TransactionExecutor.js";
+import { WebLocksLeader } from "./coordination/WebLocksLeader.js";
+import { BroadcastChannelLeader } from "./coordination/BroadcastChannelLeader.js";
+import { DefaultOnlineDetector } from "./connectivity/OnlineDetector.js";
+import { OfflineTransaction } from "./api/OfflineTransaction.js";
+import { createOfflineAction } from "./api/OfflineAction.js";
+import { withSpan, withNestedSpan } from "./telemetry/tracer.js";
+class OfflineExecutor {
+  constructor(config) {
+    this.isLeaderState = false;
+    this.unsubscribeOnline = null;
+    this.unsubscribeLeadership = null;
+    this.pendingTransactionPromises = /* @__PURE__ */ new Map();
+    this.config = config;
+    this.storage = this.createStorage();
+    this.outbox = new OutboxManager(this.storage, this.config.collections);
+    this.scheduler = new KeyScheduler();
+    this.executor = new TransactionExecutor(
+      this.scheduler,
+      this.outbox,
+      this.config,
+      this
+    );
+    this.leaderElection = this.createLeaderElection();
+    this.onlineDetector = new DefaultOnlineDetector();
+    this.setupEventListeners();
+    this.initialize();
+  }
+  createStorage() {
+    if (this.config.storage) {
+      return this.config.storage;
+    }
+    try {
+      return new IndexedDBAdapter();
+    } catch (error) {
+      console.warn(
+        `IndexedDB not available, falling back to localStorage:`,
+        error
+      );
+      return new LocalStorageAdapter();
+    }
+  }
+  createLeaderElection() {
+    if (this.config.leaderElection) {
+      return this.config.leaderElection;
+    }
+    if (WebLocksLeader.isSupported()) {
+      return new WebLocksLeader();
+    } else if (BroadcastChannelLeader.isSupported()) {
+      return new BroadcastChannelLeader();
+    } else {
+      return {
+        requestLeadership: () => Promise.resolve(true),
+        releaseLeadership: () => {
+        },
+        isLeader: () => true,
+        onLeadershipChange: () => () => {
+        }
+      };
+    }
+  }
+  setupEventListeners() {
+    this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(
+      (isLeader) => {
+        this.isLeaderState = isLeader;
+        if (this.config.onLeadershipChange) {
+          this.config.onLeadershipChange(isLeader);
+        }
+        if (isLeader) {
+          this.loadAndReplayTransactions();
+        }
+      }
+    );
+    this.unsubscribeOnline = this.onlineDetector.subscribe(() => {
+      if (this.isOfflineEnabled) {
+        this.executor.resetRetryDelays();
+        this.executor.executeAll().catch((error) => {
+          console.warn(
+            `Failed to execute transactions on connectivity change:`,
+            error
+          );
+        });
+      }
+    });
+  }
+  async initialize() {
+    return withSpan(`executor.initialize`, {}, async (span) => {
+      try {
+        const isLeader = await this.leaderElection.requestLeadership();
+        span.setAttribute(`isLeader`, isLeader);
+        if (isLeader) {
+          await this.loadAndReplayTransactions();
+        }
+      } catch (error) {
+        console.warn(`Failed to initialize offline executor:`, error);
+      }
+    });
+  }
+  async loadAndReplayTransactions() {
+    try {
+      await this.executor.loadPendingTransactions();
+      await this.executor.executeAll();
+    } catch (error) {
+      console.warn(`Failed to load and replay transactions:`, error);
+    }
+  }
+  get isOfflineEnabled() {
+    return this.isLeaderState;
+  }
+  createOfflineTransaction(options) {
+    const mutationFn = this.config.mutationFns[options.mutationFnName];
+    if (!mutationFn) {
+      throw new Error(`Unknown mutation function: ${options.mutationFnName}`);
+    }
+    if (!this.isOfflineEnabled) {
+      return createTransaction({
+        autoCommit: options.autoCommit ?? true,
+        mutationFn: (params) => mutationFn({
+          ...params,
+          idempotencyKey: options.idempotencyKey || crypto.randomUUID()
+        }),
+        metadata: options.metadata
+      });
+    }
+    return new OfflineTransaction(
+      options,
+      mutationFn,
+      this.persistTransaction.bind(this),
+      this
+    );
+  }
+  createOfflineAction(options) {
+    const mutationFn = this.config.mutationFns[options.mutationFnName];
+    if (!mutationFn) {
+      throw new Error(`Unknown mutation function: ${options.mutationFnName}`);
+    }
+    return (variables) => {
+      if (!this.isOfflineEnabled) {
+        const action2 = createOptimisticAction({
+          mutationFn: (vars, params) => mutationFn({
+            ...vars,
+            ...params,
+            idempotencyKey: crypto.randomUUID()
+          }),
+          onMutate: options.onMutate
+        });
+        return action2(variables);
+      }
+      const action = createOfflineAction(
+        options,
+        mutationFn,
+        this.persistTransaction.bind(this),
+        this
+      );
+      return action(variables);
+    };
+  }
+  async persistTransaction(transaction) {
+    return withNestedSpan(
+      `executor.persistTransaction`,
+      {
+        "transaction.id": transaction.id,
+        "transaction.mutationFnName": transaction.mutationFnName
+      },
+      async (span) => {
+        if (!this.isOfflineEnabled) {
+          span.setAttribute(`result`, `skipped_not_leader`);
+          this.resolveTransaction(transaction.id, void 0);
+          return;
+        }
+        try {
+          await this.outbox.add(transaction);
+          await this.executor.execute(transaction);
+          span.setAttribute(`result`, `persisted`);
+        } catch (error) {
+          console.error(
+            `Failed to persist offline transaction ${transaction.id}:`,
+            error
+          );
+          span.setAttribute(`result`, `failed`);
+          throw error;
+        }
+      }
+    );
+  }
+  // Method for OfflineTransaction to wait for completion
+  async waitForTransactionCompletion(transactionId) {
+    const existing = this.pendingTransactionPromises.get(transactionId);
+    if (existing) {
+      return existing.promise;
+    }
+    const deferred = {};
+    deferred.promise = new Promise((resolve, reject) => {
+      deferred.resolve = resolve;
+      deferred.reject = reject;
+    });
+    this.pendingTransactionPromises.set(transactionId, deferred);
+    return deferred.promise;
+  }
+  // Method for TransactionExecutor to signal completion
+  resolveTransaction(transactionId, result) {
+    const deferred = this.pendingTransactionPromises.get(transactionId);
+    if (deferred) {
+      deferred.resolve(result);
+      this.pendingTransactionPromises.delete(transactionId);
+    }
+  }
+  // Method for TransactionExecutor to signal failure
+  rejectTransaction(transactionId, error) {
+    const deferred = this.pendingTransactionPromises.get(transactionId);
+    if (deferred) {
+      deferred.reject(error);
+      this.pendingTransactionPromises.delete(transactionId);
+    }
+  }
+  async removeFromOutbox(id) {
+    await this.outbox.remove(id);
+  }
+  async peekOutbox() {
+    return this.outbox.getAll();
+  }
+  async clearOutbox() {
+    await this.outbox.clear();
+    this.executor.clear();
+  }
+  notifyOnline() {
+    this.onlineDetector.notifyOnline();
+  }
+  getPendingCount() {
+    return this.executor.getPendingCount();
+  }
+  getRunningCount() {
+    return this.executor.getRunningCount();
+  }
+  getOnlineDetector() {
+    return this.onlineDetector;
+  }
+  dispose() {
+    if (this.unsubscribeOnline) {
+      this.unsubscribeOnline();
+      this.unsubscribeOnline = null;
+    }
+    if (this.unsubscribeLeadership) {
+      this.unsubscribeLeadership();
+      this.unsubscribeLeadership = null;
+    }
+    this.leaderElection.releaseLeadership();
+    this.onlineDetector.dispose();
+    if (`dispose` in this.leaderElection) {
+      this.leaderElection.dispose();
+    }
+  }
+}
+function startOfflineExecutor(config) {
+  return new OfflineExecutor(config);
+}
+export {
+  OfflineExecutor,
+  startOfflineExecutor
+};
+//# sourceMappingURL=OfflineExecutor.js.map

package/dist/esm/OfflineExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineExecutor.js","sources":["../../src/OfflineExecutor.ts"],"sourcesContent":["// Storage adapters\nimport { createOptimisticAction, createTransaction } from \"@tanstack/db\"\nimport { IndexedDBAdapter } from \"./storage/IndexedDBAdapter\"\nimport { LocalStorageAdapter } from \"./storage/LocalStorageAdapter\"\n\n// Core components\nimport { OutboxManager } from \"./outbox/OutboxManager\"\nimport { KeyScheduler } from \"./executor/KeyScheduler\"\nimport { TransactionExecutor } from \"./executor/TransactionExecutor\"\n\n// Coordination\nimport { WebLocksLeader } from \"./coordination/WebLocksLeader\"\nimport { BroadcastChannelLeader } from \"./coordination/BroadcastChannelLeader\"\n\n// Connectivity\nimport { DefaultOnlineDetector } from \"./connectivity/OnlineDetector\"\n\n// API\nimport { OfflineTransaction as OfflineTransactionAPI } from \"./api/OfflineTransaction\"\nimport { createOfflineAction } from \"./api/OfflineAction\"\n\n// TanStack DB primitives\n\n// Replay\nimport { withNestedSpan, withSpan } from \"./telemetry/tracer\"\nimport type {\n  CreateOfflineActionOptions,\n  CreateOfflineTransactionOptions,\n  LeaderElection,\n  OfflineConfig,\n  OfflineTransaction,\n  StorageAdapter,\n} from \"./types\"\nimport type { Transaction } from \"@tanstack/db\"\n\nexport class OfflineExecutor {\n  private config: OfflineConfig\n  private storage: StorageAdapter\n  private outbox: OutboxManager\n  private scheduler: KeyScheduler\n  private executor: TransactionExecutor\n  private leaderElection: LeaderElection\n  private onlineDetector: DefaultOnlineDetector\n  private isLeaderState = false\n  private unsubscribeOnline: (() => void) | null = null\n  private unsubscribeLeadership: (() => void) | null = null\n\n  // Coordination mechanism for blocking transactions\n  private pendingTransactionPromises: Map<\n    string,\n    {\n      promise: Promise<any>\n      resolve: (result: any) => void\n      reject: (error: Error) => void\n    }\n  > = new Map()\n\n  constructor(config: OfflineConfig) {\n    this.config = config\n    this.storage = this.createStorage()\n    this.outbox = new OutboxManager(this.storage, this.config.collections)\n    this.scheduler = new KeyScheduler()\n    this.executor = new TransactionExecutor(\n      this.scheduler,\n      this.outbox,\n      this.config,\n      this\n    )\n    this.leaderElection = this.createLeaderElection()\n    this.onlineDetector = new DefaultOnlineDetector()\n\n    this.setupEventListeners()\n    this.initialize()\n  }\n\n  private createStorage(): StorageAdapter {\n    if (this.config.storage) {\n      return this.config.storage\n    }\n\n    try {\n      return new IndexedDBAdapter()\n    } catch (error) {\n      console.warn(\n        `IndexedDB not available, falling back to localStorage:`,\n        error\n      )\n      return new LocalStorageAdapter()\n    }\n  }\n\n  private createLeaderElection(): LeaderElection {\n    if (this.config.leaderElection) {\n      return this.config.leaderElection\n    }\n\n    if (WebLocksLeader.isSupported()) {\n      return new WebLocksLeader()\n    } else if (BroadcastChannelLeader.isSupported()) {\n      return new BroadcastChannelLeader()\n    } else {\n      // Fallback: always be leader in environments without multi-tab support\n      return {\n        requestLeadership: () => Promise.resolve(true),\n        releaseLeadership: () => {},\n        isLeader: () => true,\n        onLeadershipChange: () => () => {},\n      }\n    }\n  }\n\n  private setupEventListeners(): void {\n    this.unsubscribeLeadership = this.leaderElection.onLeadershipChange(\n      (isLeader) => {\n        this.isLeaderState = isLeader\n\n        if (this.config.onLeadershipChange) {\n          this.config.onLeadershipChange(isLeader)\n        }\n\n        if (isLeader) {\n          this.loadAndReplayTransactions()\n        }\n      }\n    )\n\n    this.unsubscribeOnline = this.onlineDetector.subscribe(() => {\n      if (this.isOfflineEnabled) {\n        // Reset retry delays so transactions can execute immediately when back online\n        this.executor.resetRetryDelays()\n        this.executor.executeAll().catch((error) => {\n          console.warn(\n            `Failed to execute transactions on connectivity change:`,\n            error\n          )\n        })\n      }\n    })\n  }\n\n  private async initialize(): Promise<void> {\n    return withSpan(`executor.initialize`, {}, async (span) => {\n      try {\n        const isLeader = await this.leaderElection.requestLeadership()\n        span.setAttribute(`isLeader`, isLeader)\n\n        if (isLeader) {\n          await this.loadAndReplayTransactions()\n        }\n      } catch (error) {\n        console.warn(`Failed to initialize offline executor:`, error)\n      }\n    })\n  }\n\n  private async loadAndReplayTransactions(): Promise<void> {\n    try {\n      await this.executor.loadPendingTransactions()\n      await this.executor.executeAll()\n    } catch (error) {\n      console.warn(`Failed to load and replay transactions:`, error)\n    }\n  }\n\n  get isOfflineEnabled(): boolean {\n    return this.isLeaderState\n  }\n\n  createOfflineTransaction(\n    options: CreateOfflineTransactionOptions\n  ): Transaction | OfflineTransactionAPI {\n    const mutationFn = this.config.mutationFns[options.mutationFnName]\n\n    if (!mutationFn) {\n      throw new Error(`Unknown mutation function: ${options.mutationFnName}`)\n    }\n\n    // Check leadership immediately and use the appropriate primitive\n    if (!this.isOfflineEnabled) {\n      // Non-leader: use createTransaction directly with the resolved mutation function\n      // We need to wrap it to add the idempotency key\n      return createTransaction({\n        autoCommit: options.autoCommit ?? true,\n        mutationFn: (params) =>\n          mutationFn({\n            ...params,\n            idempotencyKey: options.idempotencyKey || crypto.randomUUID(),\n          }),\n        metadata: options.metadata,\n      })\n    }\n\n    // Leader: use OfflineTransaction wrapper for offline persistence\n    return new OfflineTransactionAPI(\n      options,\n      mutationFn,\n      this.persistTransaction.bind(this),\n      this\n    )\n  }\n\n  createOfflineAction<T>(options: CreateOfflineActionOptions<T>) {\n    const mutationFn = this.config.mutationFns[options.mutationFnName]\n\n    if (!mutationFn) {\n      throw new Error(`Unknown mutation function: ${options.mutationFnName}`)\n    }\n\n    // Return a wrapper that checks leadership status at call time\n    return (variables: T) => {\n      // Check leadership when action is called, not when it's created\n      if (!this.isOfflineEnabled) {\n        // Non-leader: use createOptimisticAction directly\n        const action = createOptimisticAction({\n          mutationFn: (vars, params) =>\n            mutationFn({\n              ...vars,\n              ...params,\n              idempotencyKey: crypto.randomUUID(),\n            }),\n          onMutate: options.onMutate,\n        })\n        return action(variables)\n      }\n\n      // Leader: use the offline action wrapper\n      const action = createOfflineAction(\n        options,\n        mutationFn,\n        this.persistTransaction.bind(this),\n        this\n      )\n      return action(variables)\n    }\n  }\n\n  private async persistTransaction(\n    transaction: OfflineTransaction\n  ): Promise<void> {\n    return withNestedSpan(\n      `executor.persistTransaction`,\n      {\n        \"transaction.id\": transaction.id,\n        \"transaction.mutationFnName\": transaction.mutationFnName,\n      },\n      async (span) => {\n        if (!this.isOfflineEnabled) {\n          span.setAttribute(`result`, `skipped_not_leader`)\n          this.resolveTransaction(transaction.id, undefined)\n          return\n        }\n\n        try {\n          await this.outbox.add(transaction)\n          await this.executor.execute(transaction)\n          span.setAttribute(`result`, `persisted`)\n        } catch (error) {\n          console.error(\n            `Failed to persist offline transaction ${transaction.id}:`,\n            error\n          )\n          span.setAttribute(`result`, `failed`)\n          throw error\n        }\n      }\n    )\n  }\n\n  // Method for OfflineTransaction to wait for completion\n  async waitForTransactionCompletion(transactionId: string): Promise<any> {\n    const existing = this.pendingTransactionPromises.get(transactionId)\n    if (existing) {\n      return existing.promise\n    }\n\n    const deferred: {\n      promise: Promise<any>\n      resolve: (result: any) => void\n      reject: (error: Error) => void\n    } = {} as any\n\n    deferred.promise = new Promise((resolve, reject) => {\n      deferred.resolve = resolve\n      deferred.reject = reject\n    })\n\n    this.pendingTransactionPromises.set(transactionId, deferred)\n    return deferred.promise\n  }\n\n  // Method for TransactionExecutor to signal completion\n  resolveTransaction(transactionId: string, result: any): void {\n    const deferred = this.pendingTransactionPromises.get(transactionId)\n    if (deferred) {\n      deferred.resolve(result)\n      this.pendingTransactionPromises.delete(transactionId)\n    }\n  }\n\n  // Method for TransactionExecutor to signal failure\n  rejectTransaction(transactionId: string, error: Error): void {\n    const deferred = this.pendingTransactionPromises.get(transactionId)\n    if (deferred) {\n      deferred.reject(error)\n      this.pendingTransactionPromises.delete(transactionId)\n    }\n  }\n\n  async removeFromOutbox(id: string): Promise<void> {\n    await this.outbox.remove(id)\n  }\n\n  async peekOutbox(): Promise<Array<OfflineTransaction>> {\n    return this.outbox.getAll()\n  }\n\n  async clearOutbox(): Promise<void> {\n    await this.outbox.clear()\n    this.executor.clear()\n  }\n\n  notifyOnline(): void {\n    this.onlineDetector.notifyOnline()\n  }\n\n  getPendingCount(): number {\n    return this.executor.getPendingCount()\n  }\n\n  getRunningCount(): number {\n    return this.executor.getRunningCount()\n  }\n\n  getOnlineDetector(): DefaultOnlineDetector {\n    return this.onlineDetector\n  }\n\n  dispose(): void {\n    if (this.unsubscribeOnline) {\n      this.unsubscribeOnline()\n      this.unsubscribeOnline = null\n    }\n\n    if (this.unsubscribeLeadership) {\n      this.unsubscribeLeadership()\n      this.unsubscribeLeadership = null\n    }\n\n    this.leaderElection.releaseLeadership()\n    this.onlineDetector.dispose()\n\n    if (`dispose` in this.leaderElection) {\n      ;(this.leaderElection as any).dispose()\n    }\n  }\n}\n\nexport function startOfflineExecutor(config: OfflineConfig): OfflineExecutor {\n  return new OfflineExecutor(config)\n}\n"],"names":["OfflineTransactionAPI","action"],"mappings":"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"}

package/dist/esm/api/OfflineAction.d.ts

@@ -0,0 +1,3 @@
+import { Transaction } from '@tanstack/db';
+import { CreateOfflineActionOptions, OfflineMutationFn, OfflineTransaction as OfflineTransactionType } from '../types.js';
+export declare function createOfflineAction<T>(options: CreateOfflineActionOptions<T>, mutationFn: OfflineMutationFn, persistTransaction: (tx: OfflineTransactionType) => Promise<void>, executor: any): (variables: T) => Transaction;

package/dist/esm/api/OfflineAction.js

@@ -0,0 +1,47 @@
+import { trace, context, SpanStatusCode } from "@opentelemetry/api";
+import { OfflineTransaction } from "./OfflineTransaction.js";
+function createOfflineAction(options, mutationFn, persistTransaction, executor) {
+  const { mutationFnName, onMutate } = options;
+  console.log(`createOfflineAction 2`, options);
+  return (variables) => {
+    const offlineTransaction = new OfflineTransaction(
+      {
+        mutationFnName,
+        autoCommit: false
+      },
+      mutationFn,
+      persistTransaction,
+      executor
+    );
+    const transaction = offlineTransaction.mutate(() => {
+      console.log(`mutate`);
+      onMutate(variables);
+    });
+    const tracer = trace.getTracer(`@tanstack/offline-transactions`, `0.0.1`);
+    const span = tracer.startSpan(`offlineAction.${mutationFnName}`);
+    const ctx = trace.setSpan(context.active(), span);
+    console.log(`starting offlineAction span`, { tracer, span, ctx });
+    const commitPromise = context.with(ctx, () => {
+      return (async () => {
+        try {
+          await transaction.commit();
+          span.setStatus({ code: SpanStatusCode.OK });
+          span.end();
+          console.log(`ended offlineAction span - success`);
+        } catch (error) {
+          span.recordException(error);
+          span.setStatus({ code: SpanStatusCode.ERROR });
+          span.end();
+          console.log(`ended offlineAction span - error`);
+        }
+      })();
+    });
+    commitPromise.catch(() => {
+    });
+    return transaction;
+  };
+}
+export {
+  createOfflineAction
+};
+//# sourceMappingURL=OfflineAction.js.map

package/dist/esm/api/OfflineAction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineAction.js","sources":["../../../src/api/OfflineAction.ts"],"sourcesContent":["import { SpanStatusCode, context, trace } from \"@opentelemetry/api\"\nimport { OfflineTransaction } from \"./OfflineTransaction\"\nimport type { Transaction } from \"@tanstack/db\"\nimport type {\n  CreateOfflineActionOptions,\n  OfflineMutationFn,\n  OfflineTransaction as OfflineTransactionType,\n} from \"../types\"\n\nexport function createOfflineAction<T>(\n  options: CreateOfflineActionOptions<T>,\n  mutationFn: OfflineMutationFn,\n  persistTransaction: (tx: OfflineTransactionType) => Promise<void>,\n  executor: any\n): (variables: T) => Transaction {\n  const { mutationFnName, onMutate } = options\n  console.log(`createOfflineAction 2`, options)\n\n  return (variables: T): Transaction => {\n    const offlineTransaction = new OfflineTransaction(\n      {\n        mutationFnName,\n        autoCommit: false,\n      },\n      mutationFn,\n      persistTransaction,\n      executor\n    )\n\n    const transaction = offlineTransaction.mutate(() => {\n      console.log(`mutate`)\n      onMutate(variables)\n    })\n\n    // Immediately commit with span instrumentation\n    const tracer = trace.getTracer(`@tanstack/offline-transactions`, `0.0.1`)\n    const span = tracer.startSpan(`offlineAction.${mutationFnName}`)\n    const ctx = trace.setSpan(context.active(), span)\n    console.log(`starting offlineAction span`, { tracer, span, ctx })\n\n    // Execute the commit within the span context\n    // The key is to return the promise synchronously from context.with() so context binds to it\n    const commitPromise = context.with(ctx, () => {\n      // Return the promise synchronously - this is critical for context propagation in browsers\n      return (async () => {\n        try {\n          await transaction.commit()\n          span.setStatus({ code: SpanStatusCode.OK })\n          span.end()\n          console.log(`ended offlineAction span - success`)\n        } catch (error) {\n          span.recordException(error as Error)\n          span.setStatus({ code: SpanStatusCode.ERROR })\n          span.end()\n          console.log(`ended offlineAction span - error`)\n        }\n      })()\n    })\n\n    // Don't await - this is fire-and-forget for optimistic actions\n    // But catch to prevent unhandled rejection\n    commitPromise.catch(() => {\n      // Already handled in try/catch above\n    })\n\n    return transaction\n  }\n}\n"],"names":[],"mappings":";;AASO,SAAS,oBACd,SACA,YACA,oBACA,UAC+B;AAC/B,QAAM,EAAE,gBAAgB,SAAA,IAAa;AACrC,UAAQ,IAAI,yBAAyB,OAAO;AAE5C,SAAO,CAAC,cAA8B;AACpC,UAAM,qBAAqB,IAAI;AAAA,MAC7B;AAAA,QACE;AAAA,QACA,YAAY;AAAA,MAAA;AAAA,MAEd;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAGF,UAAM,cAAc,mBAAmB,OAAO,MAAM;AAClD,cAAQ,IAAI,QAAQ;AACpB,eAAS,SAAS;AAAA,IACpB,CAAC;AAGD,UAAM,SAAS,MAAM,UAAU,kCAAkC,OAAO;AACxE,UAAM,OAAO,OAAO,UAAU,iBAAiB,cAAc,EAAE;AAC/D,UAAM,MAAM,MAAM,QAAQ,QAAQ,OAAA,GAAU,IAAI;AAChD,YAAQ,IAAI,+BAA+B,EAAE,QAAQ,MAAM,KAAK;AAIhE,UAAM,gBAAgB,QAAQ,KAAK,KAAK,MAAM;AAE5C,cAAQ,YAAY;AAClB,YAAI;AACF,gBAAM,YAAY,OAAA;AAClB,eAAK,UAAU,EAAE,MAAM,eAAe,IAAI;AAC1C,eAAK,IAAA;AACL,kBAAQ,IAAI,oCAAoC;AAAA,QAClD,SAAS,OAAO;AACd,eAAK,gBAAgB,KAAc;AACnC,eAAK,UAAU,EAAE,MAAM,eAAe,OAAO;AAC7C,eAAK,IAAA;AACL,kBAAQ,IAAI,kCAAkC;AAAA,QAChD;AAAA,MACF,GAAA;AAAA,IACF,CAAC;AAID,kBAAc,MAAM,MAAM;AAAA,IAE1B,CAAC;AAED,WAAO;AAAA,EACT;AACF;"}

package/dist/esm/api/OfflineTransaction.d.ts

@@ -0,0 +1,18 @@
+import { Transaction } from '@tanstack/db';
+import { CreateOfflineTransactionOptions, OfflineMutationFn, OfflineTransaction as OfflineTransactionType } from '../types.js';
+export declare class OfflineTransaction {
+    private offlineId;
+    private mutationFnName;
+    private autoCommit;
+    private idempotencyKey;
+    private metadata;
+    private transaction;
+    private persistTransaction;
+    private executor;
+    constructor(options: CreateOfflineTransactionOptions, mutationFn: OfflineMutationFn, persistTransaction: (tx: OfflineTransactionType) => Promise<void>, executor: any);
+    mutate(callback: () => void): Transaction;
+    commit(): Promise<Transaction>;
+    rollback(): void;
+    private extractKeys;
+    get id(): string;
+}

package/dist/esm/api/OfflineTransaction.js

@@ -0,0 +1,96 @@
+import { trace, context } from "@opentelemetry/api";
+import { createTransaction } from "@tanstack/db";
+import { NonRetriableError } from "../types.js";
+class OfflineTransaction {
+  // Will be typed properly - reference to OfflineExecutor
+  constructor(options, mutationFn, persistTransaction, executor) {
+    this.transaction = null;
+    this.offlineId = crypto.randomUUID();
+    this.mutationFnName = options.mutationFnName;
+    this.autoCommit = options.autoCommit ?? true;
+    this.idempotencyKey = options.idempotencyKey ?? crypto.randomUUID();
+    this.metadata = options.metadata ?? {};
+    this.persistTransaction = persistTransaction;
+    this.executor = executor;
+  }
+  mutate(callback) {
+    this.transaction = createTransaction({
+      id: this.offlineId,
+      autoCommit: false,
+      mutationFn: async () => {
+        const activeSpan = trace.getSpan(context.active());
+        const spanContext = activeSpan?.spanContext();
+        const offlineTransaction = {
+          id: this.offlineId,
+          mutationFnName: this.mutationFnName,
+          mutations: this.transaction.mutations,
+          keys: this.extractKeys(this.transaction.mutations),
+          idempotencyKey: this.idempotencyKey,
+          createdAt: /* @__PURE__ */ new Date(),
+          retryCount: 0,
+          nextAttemptAt: Date.now(),
+          metadata: this.metadata,
+          spanContext: spanContext ? {
+            traceId: spanContext.traceId,
+            spanId: spanContext.spanId,
+            traceFlags: spanContext.traceFlags,
+            traceState: spanContext.traceState?.serialize()
+          } : void 0,
+          version: 1
+        };
+        const completionPromise = this.executor.waitForTransactionCompletion(
+          this.offlineId
+        );
+        try {
+          await this.persistTransaction(offlineTransaction);
+          await completionPromise;
+        } catch (error) {
+          const normalizedError = error instanceof Error ? error : new Error(String(error));
+          this.executor.rejectTransaction(this.offlineId, normalizedError);
+          throw error;
+        }
+        return;
+      },
+      metadata: this.metadata
+    });
+    this.transaction.mutate(() => {
+      callback();
+    });
+    if (this.autoCommit) {
+      this.commit().catch((error) => {
+        console.error(`Auto-commit failed:`, error);
+        throw error;
+      });
+    }
+    return this.transaction;
+  }
+  async commit() {
+    if (!this.transaction) {
+      throw new Error(`No mutations to commit. Call mutate() first.`);
+    }
+    try {
+      await this.transaction.commit();
+      return this.transaction;
+    } catch (error) {
+      if (error instanceof NonRetriableError) {
+        this.transaction.rollback();
+      }
+      throw error;
+    }
+  }
+  rollback() {
+    if (this.transaction) {
+      this.transaction.rollback();
+    }
+  }
+  extractKeys(mutations) {
+    return mutations.map((mutation) => mutation.globalKey);
+  }
+  get id() {
+    return this.offlineId;
+  }
+}
+export {
+  OfflineTransaction
+};
+//# sourceMappingURL=OfflineTransaction.js.map

package/dist/esm/api/OfflineTransaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineTransaction.js","sources":["../../../src/api/OfflineTransaction.ts"],"sourcesContent":["import { context, trace } from \"@opentelemetry/api\"\nimport { createTransaction } from \"@tanstack/db\"\nimport { NonRetriableError } from \"../types\"\nimport type { PendingMutation, Transaction } from \"@tanstack/db\"\nimport type {\n  CreateOfflineTransactionOptions,\n  OfflineMutationFn,\n  OfflineTransaction as OfflineTransactionType,\n} from \"../types\"\n\nexport class OfflineTransaction {\n  private offlineId: string\n  private mutationFnName: string\n  private autoCommit: boolean\n  private idempotencyKey: string\n  private metadata: Record<string, any>\n  private transaction: Transaction | null = null\n  private persistTransaction: (tx: OfflineTransactionType) => Promise<void>\n  private executor: any // Will be typed properly - reference to OfflineExecutor\n\n  constructor(\n    options: CreateOfflineTransactionOptions,\n    mutationFn: OfflineMutationFn,\n    persistTransaction: (tx: OfflineTransactionType) => Promise<void>,\n    executor: any\n  ) {\n    this.offlineId = crypto.randomUUID()\n    this.mutationFnName = options.mutationFnName\n    this.autoCommit = options.autoCommit ?? true\n    this.idempotencyKey = options.idempotencyKey ?? crypto.randomUUID()\n    this.metadata = options.metadata ?? {}\n    this.persistTransaction = persistTransaction\n    this.executor = executor\n  }\n\n  mutate(callback: () => void): Transaction {\n    this.transaction = createTransaction({\n      id: this.offlineId,\n      autoCommit: false,\n      mutationFn: async () => {\n        // This is the blocking mutationFn that waits for the executor\n        // First persist the transaction to the outbox\n        const activeSpan = trace.getSpan(context.active())\n        const spanContext = activeSpan?.spanContext()\n\n        const offlineTransaction: OfflineTransactionType = {\n          id: this.offlineId,\n          mutationFnName: this.mutationFnName,\n          mutations: this.transaction!.mutations,\n          keys: this.extractKeys(this.transaction!.mutations),\n          idempotencyKey: this.idempotencyKey,\n          createdAt: new Date(),\n          retryCount: 0,\n          nextAttemptAt: Date.now(),\n          metadata: this.metadata,\n          spanContext: spanContext\n            ? {\n                traceId: spanContext.traceId,\n                spanId: spanContext.spanId,\n                traceFlags: spanContext.traceFlags,\n                traceState: spanContext.traceState?.serialize(),\n              }\n            : undefined,\n          version: 1,\n        }\n\n        const completionPromise = this.executor.waitForTransactionCompletion(\n          this.offlineId\n        )\n\n        try {\n          await this.persistTransaction(offlineTransaction)\n          // Now block and wait for the executor to complete the real mutation\n          await completionPromise\n        } catch (error) {\n          const normalizedError =\n            error instanceof Error ? error : new Error(String(error))\n          this.executor.rejectTransaction(this.offlineId, normalizedError)\n          throw error\n        }\n\n        return\n      },\n      metadata: this.metadata,\n    })\n\n    this.transaction.mutate(() => {\n      callback()\n    })\n\n    if (this.autoCommit) {\n      // Auto-commit for direct OfflineTransaction usage\n      this.commit().catch((error) => {\n        console.error(`Auto-commit failed:`, error)\n        throw error\n      })\n    }\n\n    return this.transaction\n  }\n\n  async commit(): Promise<Transaction> {\n    if (!this.transaction) {\n      throw new Error(`No mutations to commit. Call mutate() first.`)\n    }\n\n    try {\n      // Commit the TanStack DB transaction\n      // This will trigger the mutationFn which handles persistence and waiting\n      await this.transaction.commit()\n      return this.transaction\n    } catch (error) {\n      // Only rollback for NonRetriableError - other errors should allow retry\n      if (error instanceof NonRetriableError) {\n        this.transaction.rollback()\n      }\n      throw error\n    }\n  }\n\n  rollback(): void {\n    if (this.transaction) {\n      this.transaction.rollback()\n    }\n  }\n\n  private extractKeys(mutations: Array<PendingMutation>): Array<string> {\n    return mutations.map((mutation) => mutation.globalKey)\n  }\n\n  get id(): string {\n    return this.offlineId\n  }\n}\n"],"names":[],"mappings":";;;AAUO,MAAM,mBAAmB;AAAA;AAAA,EAU9B,YACE,SACA,YACA,oBACA,UACA;AATF,SAAQ,cAAkC;AAUxC,SAAK,YAAY,OAAO,WAAA;AACxB,SAAK,iBAAiB,QAAQ;AAC9B,SAAK,aAAa,QAAQ,cAAc;AACxC,SAAK,iBAAiB,QAAQ,kBAAkB,OAAO,WAAA;AACvD,SAAK,WAAW,QAAQ,YAAY,CAAA;AACpC,SAAK,qBAAqB;AAC1B,SAAK,WAAW;AAAA,EAClB;AAAA,EAEA,OAAO,UAAmC;AACxC,SAAK,cAAc,kBAAkB;AAAA,MACnC,IAAI,KAAK;AAAA,MACT,YAAY;AAAA,MACZ,YAAY,YAAY;AAGtB,cAAM,aAAa,MAAM,QAAQ,QAAQ,QAAQ;AACjD,cAAM,cAAc,YAAY,YAAA;AAEhC,cAAM,qBAA6C;AAAA,UACjD,IAAI,KAAK;AAAA,UACT,gBAAgB,KAAK;AAAA,UACrB,WAAW,KAAK,YAAa;AAAA,UAC7B,MAAM,KAAK,YAAY,KAAK,YAAa,SAAS;AAAA,UAClD,gBAAgB,KAAK;AAAA,UACrB,+BAAe,KAAA;AAAA,UACf,YAAY;AAAA,UACZ,eAAe,KAAK,IAAA;AAAA,UACpB,UAAU,KAAK;AAAA,UACf,aAAa,cACT;AAAA,YACE,SAAS,YAAY;AAAA,YACrB,QAAQ,YAAY;AAAA,YACpB,YAAY,YAAY;AAAA,YACxB,YAAY,YAAY,YAAY,UAAA;AAAA,UAAU,IAEhD;AAAA,UACJ,SAAS;AAAA,QAAA;AAGX,cAAM,oBAAoB,KAAK,SAAS;AAAA,UACtC,KAAK;AAAA,QAAA;AAGP,YAAI;AACF,gBAAM,KAAK,mBAAmB,kBAAkB;AAEhD,gBAAM;AAAA,QACR,SAAS,OAAO;AACd,gBAAM,kBACJ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;AAC1D,eAAK,SAAS,kBAAkB,KAAK,WAAW,eAAe;AAC/D,gBAAM;AAAA,QACR;AAEA;AAAA,MACF;AAAA,MACA,UAAU,KAAK;AAAA,IAAA,CAChB;AAED,SAAK,YAAY,OAAO,MAAM;AAC5B,eAAA;AAAA,IACF,CAAC;AAED,QAAI,KAAK,YAAY;AAEnB,WAAK,OAAA,EAAS,MAAM,CAAC,UAAU;AAC7B,gBAAQ,MAAM,uBAAuB,KAAK;AAC1C,cAAM;AAAA,MACR,CAAC;AAAA,IACH;AAEA,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAM,SAA+B;AACnC,QAAI,CAAC,KAAK,aAAa;AACrB,YAAM,IAAI,MAAM,8CAA8C;AAAA,IAChE;AAEA,QAAI;AAGF,YAAM,KAAK,YAAY,OAAA;AACvB,aAAO,KAAK;AAAA,IACd,SAAS,OAAO;AAEd,UAAI,iBAAiB,mBAAmB;AACtC,aAAK,YAAY,SAAA;AAAA,MACnB;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,WAAiB;AACf,QAAI,KAAK,aAAa;AACpB,WAAK,YAAY,SAAA;AAAA,IACnB;AAAA,EACF;AAAA,EAEQ,YAAY,WAAkD;AACpE,WAAO,UAAU,IAAI,CAAC,aAAa,SAAS,SAAS;AAAA,EACvD;AAAA,EAEA,IAAI,KAAa;AACf,WAAO,KAAK;AAAA,EACd;AACF;"}

package/dist/esm/connectivity/OnlineDetector.d.ts

@@ -0,0 +1,15 @@
+import { OnlineDetector } from '../types.js';
+export declare class DefaultOnlineDetector implements OnlineDetector {
+    private listeners;
+    private isListening;
+    constructor();
+    private startListening;
+    private stopListening;
+    private handleOnline;
+    private handleVisibilityChange;
+    private notifyListeners;
+    subscribe(callback: () => void): () => void;
+    notifyOnline(): void;
+    isOnline(): boolean;
+    dispose(): void;
+}