@loro-dev/flock-sqlite 0.8.0 → 0.9.1

package/src/index.ts

@@ -1,5 +1,7 @@
 import { openStore, type UniStoreConnection } from "@loro-dev/unisqlite";
 import { computeDigest, type DigestRow } from "./digest";
+import { EventBatcher } from "./event-batcher";
+import { LruSet } from "./lru";
 import {
   compareBytes,
   decodeKeyParts,
@@ -7,6 +9,21 @@ import {
   keyToString,
   prefixUpperBound,
 } from "./key-encoding";
+import type {
+  FlockCommit,
+  FlockWriteRequest,
+  RequestId,
+  TabId,
+} from "./multi-tab";
+import {
+  createBroadcastChannelTransport,
+  createDefaultRuntime,
+  type FlockRoleProvider,
+  type FlockRuntime,
+  type FlockTransport,
+  type FlockTransportFactory,
+} from "./multi-tab-env";
+import { createWriteCoordinator, type WriteCoordinator } from "./write-coordinator";
 import type {
   EntryClock,
   Event,
@@ -25,6 +42,8 @@ import type {
   PutHooks,
   PutWithMetaOptions,
   EventListener,
+  FlockSQLiteRole,
+  RoleChangeListener,
   ScanBound,
   ScanOptions,
   ScanRow,
@@ -51,6 +70,13 @@ type KvRow = {
 
 type ExportQueryRow = KvRow;
 
+type PendingEvent = {
+  key: KeyPart[];
+  payload: ExportPayload;
+  source: string;
+  clock: EntryClock;
+};
+
 type PutOperation = {
   key: KeyPart[];
   payload: ExportPayload;
@@ -58,7 +84,7 @@ type PutOperation = {
   skipSameValue: boolean;
   source: string;
   clock?: EntryClock;
-  eventSink?: Array<{ key: KeyPart[]; payload: ExportPayload; source: string }>;
+  eventSink: PendingEvent[];
 };
 
 type EncodableVersionVectorEntry = {
@@ -68,7 +94,7 @@ type EncodableVersionVectorEntry = {
   counter: number;
 };
 
-export interface VersionVector extends VersionVectorType {}
+export interface VersionVector extends VersionVectorType { }
 
 const textEncoder = new TextEncoder();
 const textDecoder = new TextDecoder();
@@ -585,6 +611,16 @@ export type FlockSQLiteOptions = {
   peerId?: string;
   connection?: UniStoreConnection;
   tablePrefix?: string;
+  /**
+   * Advanced: Inject multi-tab environment dependencies.
+   * Defaults to BroadcastChannel + UniSQLite role + real timers when available.
+   */
+  multiTab?: {
+    transportFactory?: FlockTransportFactory;
+    roleProvider?: FlockRoleProvider;
+    runtime?: FlockRuntime;
+    tabId?: string;
+  };
 };
 
 type TableNames = {
@@ -620,6 +656,89 @@ function buildTableNames(prefix: string): TableNames {
   };
 }
 
+function normalizeRole(role: unknown): FlockSQLiteRole | undefined {
+  if (role === "host" || role === "participant" || role === "unknown") {
+    return role;
+  }
+  return undefined;
+}
+
+function resolveRole(db: UniStoreConnection): FlockSQLiteRole {
+  const role = (db as unknown as { getRole?: () => unknown }).getRole?.();
+  const normalized = normalizeRole(role);
+  if (normalized) {
+    return normalized;
+  }
+
+  // Back-compat with older UniSQLite versions that only expose getSQLiteInfo().
+  const info = (db as unknown as { getSQLiteInfo?: () => unknown }).getSQLiteInfo?.();
+  if (info && typeof info === "object") {
+    const { isHost, isReady } = info as { isHost?: unknown; isReady?: unknown };
+    if (isHost === true && isReady === true) {
+      return "host";
+    }
+    if (isReady === false) {
+      return "unknown";
+    }
+    if (isReady === true) {
+      return "participant";
+    }
+  }
+
+  // Non-browser adapters typically behave like a stable host.
+  return "host";
+}
+
+function createDefaultRoleProvider(db: UniStoreConnection): FlockRoleProvider {
+  const subscribeRoleChange = (
+    db as unknown as {
+      subscribeRoleChange?: (listener: (role: unknown) => void) => () => void;
+    }
+  ).subscribeRoleChange;
+
+  return {
+    getRole: () => resolveRole(db),
+    subscribeRoleChange:
+      typeof subscribeRoleChange === "function"
+        ? (listener) =>
+          subscribeRoleChange.call(db, (role) => {
+            const normalized = normalizeRole(role);
+            if (!normalized) {
+              return;
+            }
+            listener(normalized);
+          })
+        : undefined,
+  };
+}
+
+const MAX_SEEN_COMMITS = 2048;
+
+function buildFlockChannelName(path: string, tablePrefix: string): string {
+  if (tablePrefix) {
+    return `flock:rpc:${path}:${tablePrefix}`;
+  }
+  return `flock:rpc:${path}`;
+}
+
+function resolveTabIdWithRuntime(
+  db: UniStoreConnection,
+  runtime: FlockRuntime,
+  override?: string,
+): TabId {
+  if (typeof override === "string" && override.length > 0) {
+    return override;
+  }
+  const info = (db as unknown as { getSQLiteInfo?: () => unknown }).getSQLiteInfo?.();
+  if (info && typeof info === "object") {
+    const tabId = (info as { tabId?: unknown }).tabId;
+    if (typeof tabId === "string" && tabId.length > 0) {
+      return tabId;
+    }
+  }
+  return runtime.randomUUID();
+}
+
 export class FlockSQLite {
   private db: UniStoreConnection;
   private peerIdValue: string;
@@ -627,24 +746,11 @@ export class FlockSQLite {
   private maxHlc: { physicalTime: number; logicalCounter: number };
   private listeners: Set<EventListener>;
   private tables: TableNames;
-  /** Transaction state: undefined when not in transaction, array when accumulating */
-  private txnEventSink:
-    | Array<{ key: KeyPart[]; payload: ExportPayload; source: string }>
-    | undefined;
-  /** Debounce state for autoDebounceCommit */
-  private debounceState:
-    | {
-        timeout: number;
-        maxDebounceTime: number;
-        timerId: ReturnType<typeof setTimeout> | undefined;
-        maxTimerId: ReturnType<typeof setTimeout> | undefined;
-        pendingEvents: Array<{
-          key: KeyPart[];
-          payload: ExportPayload;
-          source: string;
-        }>;
-      }
-    | undefined;
+  private readonly runtime: FlockRuntime;
+  private readonly eventBatcher: EventBatcher<PendingEvent>;
+  private readonly coordinator: WriteCoordinator;
+  private readonly seenCommitIds: LruSet<string>;
+  private closed: boolean;
 
   private constructor(
     db: UniStoreConnection,
@@ -652,6 +758,10 @@ export class FlockSQLite {
     vv: Map<string, VersionVectorEntry>,
     maxHlc: { physicalTime: number; logicalCounter: number },
     tables: TableNames,
+    tabId: TabId,
+    runtime: FlockRuntime,
+    transport: FlockTransport | undefined,
+    roleProvider: FlockRoleProvider,
   ) {
     this.db = db;
     this.peerIdValue = peerId;
@@ -659,8 +769,22 @@ export class FlockSQLite {
     this.maxHlc = maxHlc;
     this.listeners = new Set();
     this.tables = tables;
-    this.txnEventSink = undefined;
-    this.debounceState = undefined;
+    this.runtime = runtime;
+    this.eventBatcher = new EventBatcher({
+      runtime,
+      emit: (source, events) => this.emitEvents(source, events),
+    });
+    this.seenCommitIds = new LruSet(MAX_SEEN_COMMITS);
+    this.coordinator = createWriteCoordinator({
+      runtime,
+      tabId,
+      transport,
+      roleProvider,
+      ingestCommit: (commit, bufferable) => this.applyCommit(commit, bufferable),
+      executeWriteRequest: (payload, origin, requestId) =>
+        this.executeWriteRequest(payload, origin, requestId),
+    });
+    this.closed = false;
   }
 
   static async open(options: FlockSQLiteOptions): Promise<FlockSQLite> {
@@ -670,7 +794,24 @@ export class FlockSQLite {
     await FlockSQLite.ensureSchema(db, tables);
     const peerId = await FlockSQLite.resolvePeerId(db, tables, options.peerId);
     const { vv, maxHlc } = await FlockSQLite.loadVersionState(db, tables);
-    return new FlockSQLite(db, peerId, vv, maxHlc, tables);
+    const runtime = options.multiTab?.runtime ?? createDefaultRuntime();
+    const roleProvider = options.multiTab?.roleProvider ?? createDefaultRoleProvider(db);
+    const channelName = buildFlockChannelName(options.path, prefix);
+    const transportFactory: FlockTransportFactory =
+      options.multiTab?.transportFactory ?? createBroadcastChannelTransport;
+    const transport = transportFactory(channelName);
+    const tabId = resolveTabIdWithRuntime(db, runtime, options.multiTab?.tabId);
+    return new FlockSQLite(
+      db,
+      peerId,
+      vv,
+      maxHlc,
+      tables,
+      tabId,
+      runtime,
+      transport,
+      roleProvider,
+    );
   }
 
   static async fromJson(
@@ -682,21 +823,114 @@ export class FlockSQLite {
   }
 
   async close(): Promise<void> {
-    // Commit any pending debounced events
-    if (this.debounceState !== undefined) {
-      this.disableAutoDebounceCommit();
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    this.coordinator.close();
+    this.eventBatcher.close();
+
+    await this.db.close();
+  }
+
+  getRole(): FlockSQLiteRole {
+    return this.coordinator.getRole();
+  }
+
+  isHost(): boolean {
+    return this.coordinator.isHost();
+  }
+
+  subscribeRoleChange(listener: RoleChangeListener): () => void {
+    return this.coordinator.subscribeRoleChange(listener);
+  }
+
+  private dispatchWriteRequest<T>(
+    payload: FlockWriteRequest,
+  ): Promise<{ commit: FlockCommit; result: T }> {
+    return this.coordinator.dispatchWriteRequest(payload);
+  }
+
+  private applyCommit(commit: FlockCommit, bufferable: boolean): void {
+    if (this.seenCommitIds.has(commit.commitId)) {
+      return;
     }
+    this.seenCommitIds.add(commit.commitId);
 
-    // Commit any transaction events (edge case: close during txn)
-    if (this.txnEventSink !== undefined) {
-      const pending = this.txnEventSink;
-      this.txnEventSink = undefined;
-      if (pending.length > 0) {
-        this.emitEvents("local", pending);
+    if (commit.meta?.peerId) {
+      try {
+        this.peerIdValue = normalizePeerId(commit.meta.peerId);
+      } catch {
+        // Ignore invalid peer ids; they should only come from user input.
       }
     }
 
-    await this.db.close();
+    const pendingEvents: PendingEvent[] = commit.events.map((event) => ({
+      key: cloneJson(event.key),
+      payload: clonePayload(event.payload),
+      source: commit.source,
+      clock: { ...event.clock },
+    }));
+
+    for (const event of pendingEvents) {
+      this.bumpVersion(event.clock);
+    }
+
+    if (pendingEvents.length === 0) {
+      return;
+    }
+
+    this.eventBatcher.handleCommitEvents(
+      commit.source,
+      pendingEvents,
+      bufferable,
+    );
+  }
+
+  private async executeWriteRequest(
+    payload: FlockWriteRequest,
+    origin: TabId,
+    requestId: RequestId,
+  ): Promise<{ commit: FlockCommit; result: unknown }> {
+    const events: PendingEvent[] = [];
+    let result: unknown = undefined;
+    let meta: FlockCommit["meta"] | undefined;
+
+    if (payload.kind === "apply") {
+      await this.applyOperation({
+        key: payload.key,
+        payload: payload.payload,
+        now: payload.now,
+        skipSameValue: payload.skipSameValue,
+        source: payload.source,
+        eventSink: events,
+      });
+    } else if (payload.kind === "putMvr") {
+      await this.putMvrInternal(payload.key, payload.value, payload.now, events);
+    } else if (payload.kind === "import") {
+      result = await this.importBundleInternal(payload.bundle, events);
+    } else if (payload.kind === "setPeerId") {
+      await this.setPeerIdInternal(payload.peerId);
+      meta = { peerId: this.peerIdValue };
+    } else {
+      const neverPayload: never = payload;
+      throw new Error(`Unsupported write payload ${String(neverPayload)}`);
+    }
+
+    const commitId = `c:${origin}:${requestId}`;
+    const commit: FlockCommit = {
+      commitId,
+      origin,
+      source: payload.source,
+      events: events.map((event) => ({
+        key: event.key.slice(),
+        clock: { ...event.clock },
+        payload: clonePayload(event.payload),
+      })),
+      ...(meta ? { meta } : {}),
+    };
+
+    return { commit, result };
   }
 
   private static async ensureSchema(
@@ -787,9 +1021,9 @@ export class FlockSQLite {
     const maxHlc =
       first && Number.isFinite(first.physical) && Number.isFinite(first.logical)
         ? {
-            physicalTime: Number(first.physical),
-            logicalCounter: Number(first.logical),
-          }
+          physicalTime: Number(first.physical),
+          logicalCounter: Number(first.logical),
+        }
         : { physicalTime: 0, logicalCounter: 0 };
     return { vv, maxHlc };
   }
@@ -818,7 +1052,7 @@ export class FlockSQLite {
   }
 
   private allocateClock(now?: number): EntryClock {
-    const timestamp = now ?? Date.now();
+    const timestamp = now ?? this.runtime.now();
     let physical = this.maxHlc.physicalTime;
     let logical = this.maxHlc.logicalCounter;
     if (timestamp > physical) {
@@ -935,58 +1169,21 @@ export class FlockSQLite {
     if (usedClock) {
       this.bumpVersion(usedClock);
     }
-    if (applied) {
-      const eventPayload = {
+    if (applied && usedClock) {
+      const eventPayload: PendingEvent = {
         key: operation.key.slice(),
         payload,
         source: operation.source,
+        clock: usedClock,
       };
-      if (operation.eventSink) {
-        // Explicit event sink provided (e.g., import)
-        operation.eventSink.push(eventPayload);
-      } else if (this.txnEventSink) {
-        // In transaction: accumulate events
-        this.txnEventSink.push(eventPayload);
-      } else if (this.debounceState) {
-        // Debounce active: accumulate and reset timer
-        this.debounceState.pendingEvents.push(eventPayload);
-        this.resetDebounceTimer();
-      } else {
-        // Normal: emit immediately
-        this.emitEvents(operation.source, [eventPayload]);
-      }
+      operation.eventSink.push(eventPayload);
     }
     return applied;
   }
 
-  private resetDebounceTimer(): void {
-    if (this.debounceState === undefined) {
-      return;
-    }
-
-    if (this.debounceState.timerId !== undefined) {
-      clearTimeout(this.debounceState.timerId);
-    }
-
-    this.debounceState.timerId = setTimeout(() => {
-      this.commit();
-    }, this.debounceState.timeout);
-
-    // Start max debounce timer on first pending event
-    // Note: this is called after the event is pushed, so length === 1 means first event
-    if (
-      this.debounceState.maxTimerId === undefined &&
-      this.debounceState.pendingEvents.length === 1
-    ) {
-      this.debounceState.maxTimerId = setTimeout(() => {
-        this.commit();
-      }, this.debounceState.maxDebounceTime);
-    }
-  }
-
   private emitEvents(
     source: string,
-    events: Array<{ key: KeyPart[]; payload: ExportPayload }>,
+    events: PendingEvent[],
   ): void {
     if (this.listeners.size === 0 || events.length === 0) {
       return;
@@ -996,6 +1193,7 @@ export class FlockSQLite {
       events: events.map(
         (event): Event => ({
           key: cloneJson(event.key),
+          clock: { ...event.clock },
           value:
             event.payload.data !== undefined
               ? cloneJson(event.payload.data)
@@ -1005,18 +1203,24 @@ export class FlockSQLite {
         }),
       ),
     };
-    this.listeners.forEach((listener) => {
-      listener(batch);
-    });
+    const listeners = Array.from(this.listeners);
+    for (const listener of listeners) {
+      try {
+        listener(batch);
+      } catch (error) {
+        console.error(error);
+      }
+    }
   }
 
   async put(key: KeyPart[], value: Value, now?: number): Promise<void> {
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: { data: cloneJson(value) },
       now,
       skipSameValue: true,
-      source: "local",
     });
   }
 
@@ -1040,31 +1244,34 @@ export class FlockSQLite {
       if (finalPayload.data === undefined) {
         throw new TypeError("putWithMeta requires a data value");
       }
-      await this.applyOperation({
+      await this.dispatchWriteRequest<void>({
+        kind: "apply",
+        source: "local",
         key,
         payload: finalPayload,
         now: options.now,
         skipSameValue: true,
-        source: "local",
       });
       return;
     }
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: basePayload,
       now: options.now,
       skipSameValue: true,
-      source: "local",
     });
   }
 
   async delete(key: KeyPart[], now?: number): Promise<void> {
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: {},
       now,
       skipSameValue: true,
-      source: "local",
     });
   }
 
@@ -1073,12 +1280,13 @@ export class FlockSQLite {
    * This will refresh the timestamp.
    */
   async forcePut(key: KeyPart[], value: Value, now?: number): Promise<void> {
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: { data: cloneJson(value) },
       now,
       skipSameValue: false,
-      source: "local",
     });
   }
 
@@ -1106,21 +1314,23 @@ export class FlockSQLite {
       if (finalPayload.data === undefined) {
         throw new TypeError("forcePutWithMeta requires a data value");
       }
-      await this.applyOperation({
+      await this.dispatchWriteRequest<void>({
+        kind: "apply",
+        source: "local",
         key,
         payload: finalPayload,
         now: options.now,
         skipSameValue: false,
-        source: "local",
       });
       return;
     }
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: basePayload,
       now: options.now,
       skipSameValue: false,
-      source: "local",
     });
   }
 
@@ -1129,12 +1339,13 @@ export class FlockSQLite {
    * This will refresh the timestamp.
    */
   async forceDelete(key: KeyPart[], now?: number): Promise<void> {
-    await this.applyOperation({
+    await this.dispatchWriteRequest<void>({
+      kind: "apply",
+      source: "local",
       key,
       payload: {},
       now,
       skipSameValue: false,
-      source: "local",
     });
   }
 
@@ -1143,6 +1354,15 @@ export class FlockSQLite {
   }
 
   async setPeerId(peerId: string): Promise<void> {
+    const normalized = normalizePeerId(peerId);
+    await this.dispatchWriteRequest<void>({
+      kind: "setPeerId",
+      source: "meta",
+      peerId: normalized,
+    });
+  }
+
+  private async setPeerIdInternal(peerId: string): Promise<void> {
     const normalized = normalizePeerId(peerId);
     await this.db.exec(`DELETE FROM ${this.tables.meta}`);
     await this.db.run(`INSERT INTO ${this.tables.meta}(peer_id) VALUES (?)`, [
@@ -1209,15 +1429,49 @@ export class FlockSQLite {
     if (value === null || typeof value === "object") {
       throw new TypeError("putMvr only accepts scalar values");
     }
+    await this.dispatchWriteRequest<void>({
+      kind: "putMvr",
+      source: "local",
+      key,
+      value,
+      now,
+    });
+  }
+
+  private async putMvrInternal(
+    key: KeyPart[],
+    value: Value,
+    now: number | undefined,
+    eventSink: PendingEvent[],
+  ): Promise<void> {
+    if (value === null || typeof value === "object") {
+      throw new TypeError("putMvr only accepts scalar values");
+    }
+
     const existing = await this.scan({ prefix: key });
     for (const row of existing) {
       if (row.raw.d === true) {
-        await this.delete(row.key, now);
+        await this.applyOperation({
+          key: row.key,
+          payload: {},
+          now,
+          skipSameValue: true,
+          source: "local",
+          eventSink,
+        });
       }
     }
+
     const composite = key.slice();
     composite.push(value);
-    await this.put(composite, true, now);
+    await this.applyOperation({
+      key: composite,
+      payload: { data: true },
+      now,
+      skipSameValue: true,
+      source: "local",
+      eventSink,
+    });
   }
 
   private buildScanBounds(options: ScanOptions): {
@@ -1306,9 +1560,9 @@ export class FlockSQLite {
     }
     const postFilter = prefixFilter
       ? (
-          (pf: Uint8Array) => (bytes: Uint8Array) =>
-            keyMatchesPrefix(bytes, pf)
-        )(prefixFilter)
+        (pf: Uint8Array) => (bytes: Uint8Array) =>
+          keyMatchesPrefix(bytes, pf)
+      )(prefixFilter)
       : undefined;
     return { where, params, postFilter };
   }
@@ -1540,34 +1794,15 @@ export class FlockSQLite {
     return this.exportInternal(arg, pruneTombstonesBefore);
   }
 
-  private async importInternal(bundle: ExportBundle): Promise<ImportReport> {
-    // Force commit if in transaction - this is an error condition
-    if (this.txnEventSink !== undefined) {
-      const pending = this.txnEventSink;
-      this.txnEventSink = undefined;
-      if (pending.length > 0) {
-        this.emitEvents("local", pending);
-      }
-      throw new Error(
-        "import called during transaction - transaction was auto-committed",
-      );
-    }
-
-    // Force commit if in debounce mode
-    if (this.debounceState !== undefined) {
-      this.commit();
-    }
-
+  private async importBundleInternal(
+    bundle: ExportBundle,
+    eventSink: PendingEvent[],
+  ): Promise<ImportReport> {
     if (bundle.version !== 0) {
       throw new TypeError("Unsupported bundle version");
     }
     let accepted = 0;
     const skipped: Array<{ key: KeyPart[]; reason: string }> = [];
-    const appliedEvents: Array<{
-      key: KeyPart[];
-      payload: ExportPayload;
-      source: string;
-    }> = [];
     for (const [keyString, record] of Object.entries(bundle.entries)) {
       let keyParts: KeyPart[];
       try {
@@ -1589,12 +1824,9 @@ export class FlockSQLite {
         clock,
         skipSameValue: false,
         source: "import",
-        eventSink: appliedEvents,
+        eventSink,
       });
     }
-    if (appliedEvents.length > 0) {
-      this.emitEvents("import", appliedEvents);
-    }
     return { accepted, skipped };
   }
 
@@ -1633,13 +1865,24 @@ export class FlockSQLite {
           }
         }
       }
-      const baseReport = await this.importInternal(working);
+      this.eventBatcher.beforeImport();
+      const { result: baseReport } = await this.dispatchWriteRequest<ImportReport>({
+        kind: "import",
+        source: "import",
+        bundle: working,
+      });
       return {
         accepted: baseReport.accepted,
         skipped: skipped.concat(baseReport.skipped),
       };
     }
-    return this.importInternal(arg);
+    this.eventBatcher.beforeImport();
+    const { result } = await this.dispatchWriteRequest<ImportReport>({
+      kind: "import",
+      source: "import",
+      bundle: arg,
+    });
+    return result;
   }
 
   async importJsonStr(json: string): Promise<ImportReport> {
@@ -1708,39 +1951,14 @@ export class FlockSQLite {
    * ```
    */
   async txn<T>(callback: () => Promise<T>): Promise<T> {
-    if (this.txnEventSink !== undefined) {
-      throw new Error("Nested transactions are not supported");
-    }
-    if (this.debounceState !== undefined) {
-      throw new Error(
-        "Cannot start transaction while autoDebounceCommit is active",
-      );
-    }
-
-    const eventSink: Array<{
-      key: KeyPart[];
-      payload: ExportPayload;
-      source: string;
-    }> = [];
-    this.txnEventSink = eventSink;
-
-    try {
-      const result = await callback();
-      // Commit: emit all accumulated events as single batch
-      if (eventSink.length > 0) {
-        this.emitEvents("local", eventSink);
-      }
-      return result;
-    } finally {
-      this.txnEventSink = undefined;
-    }
+    return this.eventBatcher.txn(callback);
   }
 
   /**
    * Check if a transaction is currently active.
    */
   isInTxn(): boolean {
-    return this.txnEventSink !== undefined;
+    return this.eventBatcher.isInTxn();
   }
 
   /**
@@ -1771,24 +1989,7 @@ export class FlockSQLite {
     timeout: number,
     options?: { maxDebounceTime?: number },
   ): void {
-    if (this.txnEventSink !== undefined) {
-      throw new Error(
-        "Cannot enable autoDebounceCommit while transaction is active",
-      );
-    }
-    if (this.debounceState !== undefined) {
-      throw new Error("autoDebounceCommit is already active");
-    }
-
-    const maxDebounceTime = options?.maxDebounceTime ?? 10000;
-
-    this.debounceState = {
-      timeout,
-      maxDebounceTime,
-      timerId: undefined,
-      maxTimerId: undefined,
-      pendingEvents: [],
-    };
+    this.eventBatcher.autoDebounceCommit(timeout, options);
   }
 
   /**
@@ -1796,22 +1997,7 @@ export class FlockSQLite {
    * No-op if autoDebounceCommit is not active.
    */
   disableAutoDebounceCommit(): void {
-    if (this.debounceState === undefined) {
-      return;
-    }
-
-    const { timerId, maxTimerId, pendingEvents } = this.debounceState;
-    if (timerId !== undefined) {
-      clearTimeout(timerId);
-    }
-    if (maxTimerId !== undefined) {
-      clearTimeout(maxTimerId);
-    }
-    this.debounceState = undefined;
-
-    if (pendingEvents.length > 0) {
-      this.emitEvents("local", pendingEvents);
-    }
+    this.eventBatcher.disableAutoDebounceCommit();
   }
 
   /**
@@ -1820,37 +2006,21 @@ export class FlockSQLite {
    * No-op if autoDebounceCommit is not active or no events are pending.
    */
   commit(): void {
-    if (this.debounceState === undefined) {
-      return;
-    }
-
-    const { timerId, maxTimerId, pendingEvents } = this.debounceState;
-    if (timerId !== undefined) {
-      clearTimeout(timerId);
-      this.debounceState.timerId = undefined;
-    }
-    if (maxTimerId !== undefined) {
-      clearTimeout(maxTimerId);
-      this.debounceState.maxTimerId = undefined;
-    }
-
-    if (pendingEvents.length > 0) {
-      this.emitEvents("local", pendingEvents);
-      this.debounceState.pendingEvents = [];
-    }
+    this.eventBatcher.commit();
   }
 
   /**
    * Check if auto-debounce mode is currently active.
    */
   isAutoDebounceActive(): boolean {
-    return this.debounceState !== undefined;
+    return this.eventBatcher.isAutoDebounceActive();
   }
 }
 
 export type {
   Event,
   EventBatch,
+  FlockSQLiteRole,
   ExportBundle,
   ExportHooks,
   ExportOptions,
@@ -1872,4 +2042,11 @@ export type {
 };
 
 export { FlockSQLite as Flock };
-export type { EventListener };
+export type { EventListener, RoleChangeListener };
+export type {
+  FlockRoleProvider,
+  FlockRuntime,
+  FlockTransport,
+  FlockTransportFactory,
+  TimeoutHandle,
+} from "./multi-tab-env";