@tanstack/electron-db-sqlite-persistence 0.1.33 → 0.2.1

package/README.md

@@ -2,10 +2,13 @@
 
 Thin Electron bridge for TanStack DB SQLite persistence.
 
+Start with the [SQLite Persistence guide](../../docs/guides/sqlite-persistence.md) for Collection setup and lifecycle behavior.
+
 ## Public API
 
 - `exposeElectronSQLitePersistence(...)` (main process)
 - `createElectronSQLitePersistence(...)` (renderer process)
+- `ElectronCollectionCoordinator`
 - `persistedCollectionOptions(...)` (re-exported from core)
 
 Use `@tanstack/electron-db-sqlite-persistence/main` and
@@ -64,8 +67,77 @@ export const todosCollection = createCollection(
 )
 ```
 
+## Multi-renderer ownership
+
+Pass an `ElectronCollectionCoordinator` when multiple renderers share the same
+database. Coordinators using the same `dbName` elect a writer independently for
+each collection.
+
+```ts
+import {
+  ElectronCollectionCoordinator,
+  createElectronSQLitePersistence,
+} from '@tanstack/electron-db-sqlite-persistence'
+
+const coordinator = new ElectronCollectionCoordinator({
+  dbName: `tanstack-db`,
+})
+
+const persistence = createElectronSQLitePersistence({
+  ipcRenderer,
+  coordinator,
+})
+
+// On teardown:
+// coordinator.dispose()
+```
+
+The persisted sync wrapper routes every source transaction with durable effects
+through the coordinator's required
+`requestApplyCommittedTx(collectionId, tx)` method. The elected renderer applies
+the complete `PersistedTx` through its resolved per-collection renderer adapter,
+which forwards it over IPC to the main-process persistence owner. Resolution
+remains specific to the collection id, mode, and `schemaVersion`.
+
+Truncation, row changes, row metadata, collection metadata, and stream position
+stay in the same transaction. Electron does not feature-detect a partial route
+or fall back to row-only mutation RPC. A custom coordinator that omits
+`requestApplyCommittedTx` is rejected while the collection is configured,
+before its sync source can publish rows. An effect-free source commit neither
+publishes nor consumes a coordinator sequence.
+
+If a mutating RPC loses its response, Electron coordination replays it only
+while the requester still knows the same non-null leader id and term. An
+unknown initial route or any leader/term change rejects with
+`IndeterminateCommitError`; the application must reconcile the outcome. The
+coordinator does not retry that mutation against an unknown or replacement
+leader.
+
+Remote-subset requests use the same crash-only boundary. The coordinator
+projects a live `LoadSubsetOptions` input to the exported
+`TransportedLoadSubsetOptions` type before either local completion or renderer
+transport. Live `signal` and `subscription` fields do not cross the boundary.
+Unsupported nested values throw `RemoteSubsetWireValueError` with the exact
+value path before publication; Electron does not add codecs, coercion, or a
+fallback representation.
+
+Electron uses the same explicit lease lifecycle as Browser coordination. The
+same request object reuses one acquisition identity, distinct equal objects
+remain independent, and release unloads the exact transported options once.
+Leadership loss unloads the retiring renderer's leases; still-live requester
+leases replay against the next leader. A second owner registration for one
+collection throws `DuplicateRemoteSubsetOwnerError`, and there is no adapter
+fallback for a missing owner. Remote follower transport/admission failures
+reject and retain demand for its normal retry without entering the follower's
+local owner lifecycle. Terminal release identities expire after the existing
+RPC dedupe horizon while delayed duplicates inside that horizon remain
+idempotent.
+
 ## Notes
 
 - The renderer API mirrors other runtimes: one shared `create...Persistence`.
 - Collection mode (`sync-present` vs `sync-absent`) and `schemaVersion` are
   resolved per collection and forwarded across IPC automatically.
+- Without an `ElectronCollectionCoordinator`, single-renderer mode uses
+  `SingleProcessCoordinator`: it is always leader, but still routes complete
+  transactions to the collection's resolved IPC adapter.

package/dist/cjs/electron-coordinator.cjs

@@ -1,542 +1,13 @@
 "use strict";
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const dbSqlitePersistenceCore = require("@tanstack/db-sqlite-persistence-core");
-const HEARTBEAT_INTERVAL_MS = 3e3;
-const RPC_TIMEOUT_MS = 1e4;
-const RPC_RETRY_ATTEMPTS = 2;
-const RPC_RETRY_DELAY_MS = 200;
-const WRITER_LOCK_BUSY_RETRY_MS = 50;
-const WRITER_LOCK_MAX_RETRIES = 20;
-class ElectronCollectionCoordinator {
+const broadcastCoordinator = require("@tanstack/db-sqlite-persistence-core/broadcast-coordinator");
+class ElectronCollectionCoordinator extends broadcastCoordinator.BroadcastCollectionCoordinator {
   constructor(options) {
-    this.nodeId = dbSqlitePersistenceCore.safeRandomUUID();
-    this.collections = /* @__PURE__ */ new Map();
-    this.pendingRPCs = /* @__PURE__ */ new Map();
-    this.appliedEnvelopeIds = /* @__PURE__ */ new Map();
-    this.disposed = false;
-    this.dbName = options.dbName;
-    this.adapter = options.adapter ?? null;
-    this.channel = new BroadcastChannel(`tsdb:coord:${this.dbName}`);
-    this.channel.onmessage = (event) => {
-      this.onChannelMessage(event.data);
-    };
-  }
-  /** Method indirection to prevent TypeScript from narrowing `disposed` across awaits */
-  isDisposed() {
-    return this.disposed;
-  }
-  requireAdapter() {
-    if (!this.adapter) {
-      throw new Error(
-        `ElectronCollectionCoordinator: adapter not set. Call setAdapter() before using leader-side operations.`
-      );
-    }
-    return this.adapter;
-  }
-  /**
-   * Set or replace the persistence adapter used for leader-side RPC handling.
-   * Called by `createElectronSQLitePersistence` to wire the internally-created
-   * adapter into the coordinator.
-   */
-  setAdapter(adapter) {
-    this.adapter = adapter;
-  }
-  // -----------------------------------------------------------------------
-  // PersistedCollectionCoordinator interface
-  // -----------------------------------------------------------------------
-  getNodeId() {
-    return this.nodeId;
-  }
-  subscribe(collectionId, onMessage) {
-    const state = this.ensureCollectionState(collectionId);
-    state.subscribers.add(onMessage);
-    return () => {
-      state.subscribers.delete(onMessage);
-    };
-  }
-  publish(_collectionId, message) {
-    this.channel.postMessage(message);
-  }
-  isLeader(collectionId) {
-    return this.collections.get(collectionId)?.isLeader ?? false;
-  }
-  async ensureLeadership(collectionId) {
-    const state = this.ensureCollectionState(collectionId);
-    if (state.isLeader) return;
-    await this.acquireLeadership(collectionId, state);
-  }
-  async requestEnsureRemoteSubset(collectionId, options) {
-    if (this.isLeader(collectionId)) return;
-    const response = await this.sendRPC(collectionId, {
-      type: `rpc:ensureRemoteSubset:req`,
-      rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-      options
+    super({
+      ...options,
+      coordinatorName: `ElectronCollectionCoordinator`
     });
-    if (!response.ok) {
-      throw new Error(
-        `ensureRemoteSubset failed: ${response.error ?? `unknown error`}`
-      );
-    }
-  }
-  async requestEnsurePersistedIndex(collectionId, signature, spec) {
-    if (this.isLeader(collectionId)) {
-      await this.requireAdapter().ensureIndex(collectionId, signature, spec);
-      return;
-    }
-    const response = await this.sendRPC(collectionId, {
-      type: `rpc:ensurePersistedIndex:req`,
-      rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-      signature,
-      spec
-    });
-    if (!response.ok) {
-      throw new Error(
-        `ensurePersistedIndex failed: ${response.error ?? `unknown error`}`
-      );
-    }
-  }
-  async requestApplyLocalMutations(collectionId, mutations) {
-    if (this.isLeader(collectionId)) {
-      return this.handleApplyLocalMutations(collectionId, {
-        type: `rpc:applyLocalMutations:req`,
-        rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-        envelopeId: dbSqlitePersistenceCore.safeRandomUUID(),
-        mutations
-      });
-    }
-    return this.sendRPC(collectionId, {
-      type: `rpc:applyLocalMutations:req`,
-      rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-      envelopeId: dbSqlitePersistenceCore.safeRandomUUID(),
-      mutations
-    });
-  }
-  async pullSince(collectionId, fromRowVersion) {
-    if (this.isLeader(collectionId)) {
-      return this.handlePullSince(collectionId, {
-        type: `rpc:pullSince:req`,
-        rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-        fromRowVersion
-      });
-    }
-    return this.sendRPC(collectionId, {
-      type: `rpc:pullSince:req`,
-      rpcId: dbSqlitePersistenceCore.safeRandomUUID(),
-      fromRowVersion
-    });
-  }
-  // -----------------------------------------------------------------------
-  // Lifecycle
-  // -----------------------------------------------------------------------
-  dispose() {
-    this.disposed = true;
-    for (const [collectionId, state] of this.collections) {
-      this.releaseLeadership(collectionId, state);
-    }
-    for (const [, pending] of this.pendingRPCs) {
-      clearTimeout(pending.timer);
-      pending.reject(new Error(`coordinator disposed`));
-    }
-    this.pendingRPCs.clear();
-    this.channel.close();
-    this.collections.clear();
-  }
-  // -----------------------------------------------------------------------
-  // Leadership via Web Locks
-  // -----------------------------------------------------------------------
-  ensureCollectionState(collectionId) {
-    let state = this.collections.get(collectionId);
-    if (!state) {
-      state = {
-        isLeader: false,
-        lockAbortController: null,
-        heartbeatTimer: null,
-        latestTerm: 0,
-        latestSeq: 0,
-        latestRowVersion: 0,
-        subscribers: /* @__PURE__ */ new Set()
-      };
-      this.collections.set(collectionId, state);
-      void this.acquireLeadership(collectionId, state);
-    }
-    return state;
   }
-  async acquireLeadership(collectionId, state) {
-    if (this.disposed || state.isLeader) return;
-    const lockName = `tsdb:leader:${this.dbName}:${collectionId}`;
-    const abortController = new AbortController();
-    state.lockAbortController = abortController;
-    try {
-      await navigator.locks.request(
-        lockName,
-        { signal: abortController.signal },
-        async () => {
-          if (this.isDisposed()) return;
-          try {
-            const adapter = this.requireAdapter();
-            if (adapter.getStreamPosition) {
-              const pos = await adapter.getStreamPosition(collectionId);
-              state.latestTerm = pos.latestTerm;
-              state.latestSeq = pos.latestSeq;
-              state.latestRowVersion = pos.latestRowVersion;
-            }
-            state.latestTerm++;
-            state.isLeader = true;
-            this.emitHeartbeat(collectionId, state);
-            state.heartbeatTimer = setInterval(() => {
-              this.emitHeartbeat(collectionId, state);
-            }, HEARTBEAT_INTERVAL_MS);
-            await new Promise((resolve) => {
-              const onAbort = () => {
-                abortController.signal.removeEventListener(`abort`, onAbort);
-                resolve();
-              };
-              if (abortController.signal.aborted) {
-                resolve();
-                return;
-              }
-              abortController.signal.addEventListener(`abort`, onAbort);
-            });
-          } finally {
-            state.isLeader = false;
-            if (state.heartbeatTimer) {
-              clearInterval(state.heartbeatTimer);
-              state.heartbeatTimer = null;
-            }
-          }
-        }
-      );
-    } catch (error) {
-      if (error instanceof DOMException && error.name === `AbortError`) {
-        return;
-      }
-      console.warn(`Failed to acquire leadership for ${collectionId}:`, error);
-    }
-    if (!this.isDisposed()) {
-      void this.acquireLeadership(collectionId, state);
-    }
-  }
-  releaseLeadership(_collectionId, state) {
-    if (state.lockAbortController) {
-      state.lockAbortController.abort();
-      state.lockAbortController = null;
-    }
-    if (state.heartbeatTimer) {
-      clearInterval(state.heartbeatTimer);
-      state.heartbeatTimer = null;
-    }
-    state.isLeader = false;
-  }
-  emitHeartbeat(collectionId, state) {
-    const envelope = {
-      v: 1,
-      dbName: this.dbName,
-      collectionId,
-      senderId: this.nodeId,
-      ts: Date.now(),
-      payload: {
-        type: `leader:heartbeat`,
-        term: state.latestTerm,
-        leaderId: this.nodeId,
-        latestSeq: state.latestSeq,
-        latestRowVersion: state.latestRowVersion
-      }
-    };
-    this.channel.postMessage(envelope);
-  }
-  // -----------------------------------------------------------------------
-  // BroadcastChannel message handling
-  // -----------------------------------------------------------------------
-  onChannelMessage(data) {
-    if (!isProtocolEnvelope(data)) return;
-    const envelope = data;
-    if (envelope.senderId === this.nodeId) return;
-    const payload = envelope.payload;
-    if (!payload || typeof payload !== `object`) return;
-    const type = payload.type;
-    if (type && type.endsWith(`:res`)) {
-      const rpcId = payload.rpcId;
-      if (rpcId && this.pendingRPCs.has(rpcId)) {
-        const pending = this.pendingRPCs.get(rpcId);
-        this.pendingRPCs.delete(rpcId);
-        clearTimeout(pending.timer);
-        pending.resolve(payload);
-        return;
-      }
-    }
-    if (type && type.endsWith(`:req`)) {
-      const collectionId = envelope.collectionId;
-      if (this.isLeader(collectionId)) {
-        void this.handleRPCRequest(collectionId, payload);
-      }
-      return;
-    }
-    const state = this.collections.get(envelope.collectionId);
-    if (state) {
-      for (const subscriber of state.subscribers) {
-        subscriber(envelope);
-      }
-    }
-  }
-  // -----------------------------------------------------------------------
-  // RPC - Outbound (follower side)
-  // -----------------------------------------------------------------------
-  async sendRPC(collectionId, request) {
-    let lastError;
-    for (let attempt = 0; attempt <= RPC_RETRY_ATTEMPTS; attempt++) {
-      if (attempt > 0) {
-        await sleep(RPC_RETRY_DELAY_MS * attempt);
-      }
-      try {
-        return await this.sendRPCOnce(collectionId, request);
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-      }
-    }
-    throw lastError ?? new Error(`RPC failed after retries`);
-  }
-  sendRPCOnce(collectionId, request) {
-    return new Promise((resolve, reject) => {
-      const rpcId = request.rpcId;
-      const timer = setTimeout(() => {
-        this.pendingRPCs.delete(rpcId);
-        reject(
-          new Error(`RPC ${request.type} timed out after ${RPC_TIMEOUT_MS}ms`)
-        );
-      }, RPC_TIMEOUT_MS);
-      this.pendingRPCs.set(rpcId, {
-        resolve,
-        reject,
-        timer
-      });
-      const envelope = {
-        v: 1,
-        dbName: this.dbName,
-        collectionId,
-        senderId: this.nodeId,
-        ts: Date.now(),
-        payload: request
-      };
-      this.channel.postMessage(envelope);
-    });
-  }
-  // -----------------------------------------------------------------------
-  // RPC - Inbound (leader side)
-  // -----------------------------------------------------------------------
-  async handleRPCRequest(collectionId, request) {
-    let response;
-    try {
-      switch (request.type) {
-        case `rpc:ensureRemoteSubset:req`:
-          response = await this.handleEnsureRemoteSubset(collectionId, request);
-          break;
-        case `rpc:ensurePersistedIndex:req`:
-          response = await this.handleEnsurePersistedIndex(
-            collectionId,
-            request
-          );
-          break;
-        case `rpc:applyLocalMutations:req`:
-          response = await this.handleApplyLocalMutations(collectionId, request);
-          break;
-        case `rpc:pullSince:req`:
-          response = await this.handlePullSince(collectionId, request);
-          break;
-        default:
-          return;
-      }
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      response = {
-        type: request.type.replace(`:req`, `:res`),
-        rpcId: request.rpcId,
-        ok: false,
-        error: errorMessage
-      };
-    }
-    const envelope = {
-      v: 1,
-      dbName: this.dbName,
-      collectionId,
-      senderId: this.nodeId,
-      ts: Date.now(),
-      payload: response
-    };
-    this.channel.postMessage(envelope);
-  }
-  handleEnsureRemoteSubset(_collectionId, request) {
-    return {
-      type: `rpc:ensureRemoteSubset:res`,
-      rpcId: request.rpcId,
-      ok: true
-    };
-  }
-  async handleEnsurePersistedIndex(collectionId, request) {
-    await this.withWriterLock(
-      () => this.requireAdapter().ensureIndex(
-        collectionId,
-        request.signature,
-        request.spec
-      )
-    );
-    return {
-      type: `rpc:ensurePersistedIndex:res`,
-      rpcId: request.rpcId,
-      ok: true
-    };
-  }
-  async handleApplyLocalMutations(collectionId, request) {
-    if (this.appliedEnvelopeIds.has(request.envelopeId)) {
-      return {
-        type: `rpc:applyLocalMutations:res`,
-        rpcId: request.rpcId,
-        ok: false,
-        code: `CONFLICT`,
-        error: `envelope ${request.envelopeId} already applied`
-      };
-    }
-    const state = this.collections.get(collectionId);
-    if (!state || !state.isLeader) {
-      return {
-        type: `rpc:applyLocalMutations:res`,
-        rpcId: request.rpcId,
-        ok: false,
-        code: `NOT_LEADER`,
-        error: `not the leader for ${collectionId}`
-      };
-    }
-    state.latestSeq++;
-    state.latestRowVersion++;
-    const term = state.latestTerm;
-    const seq = state.latestSeq;
-    const rowVersion = state.latestRowVersion;
-    const tx = {
-      txId: dbSqlitePersistenceCore.safeRandomUUID(),
-      term,
-      seq,
-      rowVersion,
-      mutations: request.mutations.map((m) => ({
-        type: m.type,
-        key: m.key,
-        value: m.value
-      }))
-    };
-    await this.withWriterLock(
-      () => this.requireAdapter().applyCommittedTx(collectionId, tx)
-    );
-    this.appliedEnvelopeIds.set(request.envelopeId, Date.now());
-    this.pruneAppliedEnvelopeIds();
-    const changedRows = request.mutations.filter((m) => m.type !== `delete`).map((m) => ({ key: m.key, value: m.value }));
-    const deletedKeys = request.mutations.filter((m) => m.type === `delete`).map((m) => m.key);
-    const txCommitted = {
-      v: 1,
-      dbName: this.dbName,
-      collectionId,
-      senderId: this.nodeId,
-      ts: Date.now(),
-      payload: {
-        type: `tx:committed`,
-        term,
-        seq,
-        txId: tx.txId,
-        latestRowVersion: rowVersion,
-        requiresFullReload: false,
-        changedRows,
-        deletedKeys
-      }
-    };
-    this.channel.postMessage(txCommitted);
-    for (const subscriber of state.subscribers) {
-      subscriber(txCommitted);
-    }
-    return {
-      type: `rpc:applyLocalMutations:res`,
-      rpcId: request.rpcId,
-      ok: true,
-      term,
-      seq,
-      latestRowVersion: rowVersion,
-      acceptedMutationIds: request.mutations.map((m) => m.mutationId)
-    };
-  }
-  async handlePullSince(collectionId, request) {
-    const state = this.collections.get(collectionId);
-    const adapter = this.requireAdapter();
-    if (!adapter.pullSince) {
-      return {
-        type: `rpc:pullSince:res`,
-        rpcId: request.rpcId,
-        ok: true,
-        latestTerm: state?.latestTerm ?? 0,
-        latestSeq: state?.latestSeq ?? 0,
-        latestRowVersion: state?.latestRowVersion ?? 0,
-        requiresFullReload: true
-      };
-    }
-    const result = await adapter.pullSince(collectionId, request.fromRowVersion);
-    if (result.requiresFullReload) {
-      return {
-        type: `rpc:pullSince:res`,
-        rpcId: request.rpcId,
-        ok: true,
-        latestTerm: state?.latestTerm ?? 0,
-        latestSeq: state?.latestSeq ?? 0,
-        latestRowVersion: result.latestRowVersion,
-        requiresFullReload: true
-      };
-    }
-    return {
-      type: `rpc:pullSince:res`,
-      rpcId: request.rpcId,
-      ok: true,
-      latestTerm: state?.latestTerm ?? 0,
-      latestSeq: state?.latestSeq ?? 0,
-      latestRowVersion: result.latestRowVersion,
-      requiresFullReload: false,
-      changedKeys: result.changedKeys,
-      deletedKeys: result.deletedKeys
-    };
-  }
-  // -----------------------------------------------------------------------
-  // DB Writer Lock
-  // -----------------------------------------------------------------------
-  async withWriterLock(fn) {
-    const lockName = `tsdb:writer:${this.dbName}`;
-    for (let attempt = 0; attempt <= WRITER_LOCK_MAX_RETRIES; attempt++) {
-      try {
-        return await navigator.locks.request(lockName, async () => fn());
-      } catch (error) {
-        if (error instanceof DOMException && error.name === `AbortError`) {
-          throw error;
-        }
-        if (attempt < WRITER_LOCK_MAX_RETRIES) {
-          await sleep(WRITER_LOCK_BUSY_RETRY_MS * Math.min(attempt + 1, 5));
-          continue;
-        }
-        throw error;
-      }
-    }
-    throw new Error(`writer lock acquisition failed`);
-  }
-  // -----------------------------------------------------------------------
-  // Helpers
-  // -----------------------------------------------------------------------
-  pruneAppliedEnvelopeIds() {
-    const cutoff = Date.now() - 6e4;
-    for (const [id, ts] of this.appliedEnvelopeIds) {
-      if (ts < cutoff) {
-        this.appliedEnvelopeIds.delete(id);
-      }
-    }
-  }
-}
-function isProtocolEnvelope(data) {
-  if (!data || typeof data !== `object`) return false;
-  const record = data;
-  return record.v === 1 && typeof record.dbName === `string` && typeof record.collectionId === `string` && typeof record.senderId === `string` && typeof record.ts === `number`;
-}
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
 }
 exports.ElectronCollectionCoordinator = ElectronCollectionCoordinator;
 //# sourceMappingURL=electron-coordinator.cjs.map