@loro-dev/flock 4.4.0 → 4.4.2

package/src/index.ts

@@ -29,6 +29,11 @@ import {
   is_in_txn_ffi,
 } from "./_moon_flock";
 
+import {
+  EventBatcher,
+  type EventBatcherRuntime,
+} from "../../packages/flock-sqlite/src/event-batcher";
+
 type RawVersionVector = Record<string, [number, number]>;
 type RawScanRow = { key: KeyPart[]; raw: ExportRecord; value?: Value };
 type RawEventPayload = { data?: Value; metadata?: MetadataMap };
@@ -842,23 +847,26 @@ function isImportOptions(value: unknown): value is ImportOptions {
   );
 }
 
+const defaultEventBatcherRuntime: EventBatcherRuntime = {
+  now: () => Date.now(),
+  setTimeout: (fn, ms) => setTimeout(fn, ms) as unknown,
+  clearTimeout: (handle) => clearTimeout(handle as any),
+};
+
 export class Flock {
   private inner: ReturnType<typeof newFlock>;
   private listeners: Set<(batch: EventBatch) => void> = new Set();
   private nativeUnsubscribe: (() => void) | undefined;
-  /** Debounce state for autoDebounceCommit */
-  private debounceState:
-    | {
-        timeout: number;
-        maxDebounceTime: number;
-        timerId: ReturnType<typeof setTimeout> | undefined;
-        maxTimerId: ReturnType<typeof setTimeout> | undefined;
-        pendingEvents: Event[];
-      }
-    | undefined;
+  private readonly eventBatcher: EventBatcher<Event>;
 
   constructor(peerId?: string) {
     this.inner = newFlock(normalizePeerId(peerId));
+    this.eventBatcher = new EventBatcher<Event>({
+      runtime: defaultEventBatcherRuntime,
+      emit: (source, events) => {
+        this.deliverBatch({ source, events });
+      },
+    });
   }
 
   private static fromInner(inner: ReturnType<typeof newFlock>): Flock {
@@ -984,13 +992,21 @@ export class Flock {
   }
 
   merge(other: Flock): void {
+    this.eventBatcher.beforeImport();
     merge(this.inner, other.inner);
   }
 
   /**
    * Returns the exclusive version vector, which only includes peers that have
-   * at least one entry in the current state. This is consistent with the state
-   * after export and re-import.
+   * at least one entry in the current state.
+   *
+   * Complexity: O(M + V log M + R (log L + log S)).
+   * - M = memtablePeerCount
+   * - V = vvPeerCount
+   * - L = memtableLen
+   * - R = scanned candidate rows in KV_BY_PEER_CLOCK
+   * - S = storage key count in KV_BY_KEY
+   * No full O(memtableSize) pre-scan is performed.
    *
    * Use this version when sending to other peers for incremental sync.
    */
@@ -1069,6 +1085,7 @@ export class Flock {
   }
 
   private importJsonInternal(bundle: ExportBundle): ImportReport {
+    this.eventBatcher.beforeImport();
     const report = import_json_ffi(this.inner, bundle) as
       | RawImportReport
       | undefined;
@@ -1118,6 +1135,7 @@ export class Flock {
   }
 
   importJsonStr(bundle: string): ImportReport {
+    this.eventBatcher.beforeImport();
     const report = import_json_str_ffi(this.inner, bundle) as
       | RawImportReport
       | undefined;
@@ -1190,41 +1208,21 @@ export class Flock {
   }
 
   private handleBatch(batch: EventBatch): void {
-    if (this.debounceState !== undefined) {
-      // Debounce active: accumulate events and reset timer
-      const wasEmpty = this.debounceState.pendingEvents.length === 0;
-      this.debounceState.pendingEvents.push(...batch.events);
-      this.resetDebounceTimer(wasEmpty);
-    } else {
-      // Normal mode: emit immediately
-      this.emitBatch(batch);
-    }
+    const bufferable = batch.source === "local";
+    this.eventBatcher.handleCommitEvents(batch.source, batch.events, bufferable);
   }
 
-  private emitBatch(batch: EventBatch): void {
-    for (const listener of this.listeners) {
-      listener(batch);
-    }
-  }
-
-  private resetDebounceTimer(isFirstEvent: boolean): void {
-    if (this.debounceState === undefined) {
+  private deliverBatch(batch: EventBatch): void {
+    if (this.listeners.size === 0) {
       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
-    if (this.debounceState.maxTimerId === undefined && isFirstEvent) {
-      this.debounceState.maxTimerId = setTimeout(() => {
-        this.commit();
-      }, this.debounceState.maxDebounceTime);
+    const listeners = Array.from(this.listeners);
+    for (const listener of listeners) {
+      try {
+        listener(batch);
+      } catch (error) {
+        void error;
+      }
     }
   }
 
@@ -1273,19 +1271,7 @@ export class Flock {
         "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);
   }
 
   /**
@@ -1293,22 +1279,7 @@ export class Flock {
    * 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.emitBatch({ source: "local", events: pendingEvents });
-    }
+    this.eventBatcher.disableAutoDebounceCommit();
   }
 
   /**
@@ -1317,31 +1288,14 @@ export class Flock {
    * 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.emitBatch({ source: "local", events: 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();
   }
 
   /**
@@ -1359,6 +1313,7 @@ export class Flock {
    * @returns The return value of the callback
    * @throws Error if nested transaction attempted
    * @throws Error if import is called during the transaction (auto-commits first)
+   * @throws Error if called while autoDebounceCommit is active
    *
    * @example
    * ```ts
@@ -1371,6 +1326,11 @@ export class Flock {
    * ```
    */
   txn<T>(callback: () => T): T {
+    if (this.eventBatcher.isAutoDebounceActive()) {
+      throw new Error(
+        "Cannot start transaction while autoDebounceCommit is active",
+      );
+    }
     txn_begin_ffi(this.inner);
     try {
       const result = callback();