@loro-dev/flock 4.3.0 → 4.4.1

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,11 +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;
+  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 {
@@ -1167,14 +1187,105 @@ export class Flock {
       }));
   }
 
+  private ensureNativeSubscription(): void {
+    if (this.nativeUnsubscribe !== undefined) {
+      return;
+    }
+    this.nativeUnsubscribe = subscribe_ffi(this.inner, (payload: unknown) => {
+      const batch = decodeEventBatch(payload);
+      this.handleBatch(batch);
+    }) as () => void;
+  }
+
+  private handleBatch(batch: EventBatch): void {
+    const bufferable = batch.source === "local";
+    this.eventBatcher.handleCommitEvents(batch.source, batch.events, bufferable);
+  }
+
+  private deliverBatch(batch: EventBatch): void {
+    if (this.listeners.size === 0) {
+      return;
+    }
+    const listeners = Array.from(this.listeners);
+    for (const listener of listeners) {
+      try {
+        listener(batch);
+      } catch (error) {
+        void error;
+      }
+    }
+  }
+
   subscribe(listener: (batch: EventBatch) => void): () => void {
-    const unsubscribe = subscribe_ffi(this.inner, (payload: unknown) => {
-      listener(decodeEventBatch(payload));
-    });
-    if (typeof unsubscribe !== "function") {
-      throw new TypeError("subscribe ffi did not return a function");
+    this.listeners.add(listener);
+    this.ensureNativeSubscription();
+
+    return () => {
+      this.listeners.delete(listener);
+      // Optionally clean up native subscription when no listeners remain
+      if (this.listeners.size === 0 && this.nativeUnsubscribe !== undefined) {
+        this.nativeUnsubscribe();
+        this.nativeUnsubscribe = undefined;
+      }
+    };
+  }
+
+  /**
+   * Enable auto-debounce mode. Events will be accumulated and emitted after
+   * the specified timeout of inactivity. Each new operation resets the timer.
+   *
+   * Use `commit()` to force immediate emission of pending events.
+   * Use `disableAutoDebounceCommit()` to disable and emit pending events.
+   *
+   * @param timeout - Debounce timeout in milliseconds
+   * @param options - Optional configuration object with maxDebounceTime (default: 10000ms)
+   * @throws Error if called while a transaction is active
+   * @throws Error if autoDebounceCommit is already active
+   *
+   * @example
+   * ```ts
+   * flock.autoDebounceCommit(100);
+   * flock.put(["a"], 1);
+   * flock.put(["b"], 2);
+   * // No events emitted yet...
+   * // After 100ms of inactivity, subscribers receive single EventBatch
+   * // If operations keep coming, commit happens after maxDebounceTime (10s default)
+   * ```
+   */
+  autoDebounceCommit(
+    timeout: number,
+    options?: { maxDebounceTime?: number },
+  ): void {
+    if (this.isInTxn()) {
+      throw new Error(
+        "Cannot enable autoDebounceCommit while transaction is active",
+      );
     }
-    return unsubscribe as () => void;
+    this.eventBatcher.autoDebounceCommit(timeout, options);
+  }
+
+  /**
+   * Disable auto-debounce mode and emit any pending events immediately.
+   * No-op if autoDebounceCommit is not active.
+   */
+  disableAutoDebounceCommit(): void {
+    this.eventBatcher.disableAutoDebounceCommit();
+  }
+
+  /**
+   * Force immediate emission of any pending debounced events.
+   * Does not disable auto-debounce mode - new operations will continue to be debounced.
+   * No-op if autoDebounceCommit is not active or no events are pending.
+   */
+  commit(): void {
+    this.eventBatcher.commit();
+  }
+
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean {
+    return this.eventBatcher.isAutoDebounceActive();
   }
 
   /**
@@ -1192,6 +1303,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
@@ -1204,6 +1316,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();