@loro-dev/flock 4.2.0 → 4.4.0

package/src/index.ts

@@ -23,6 +23,10 @@ import {
   check_consistency_ffi,
   check_invariants_ffi,
   from_json_ffi,
+  txn_begin_ffi,
+  txn_commit_ffi,
+  txn_rollback_ffi,
+  is_in_txn_ffi,
 } from "./_moon_flock";
 
 type RawVersionVector = Record<string, [number, number]>;
@@ -840,6 +844,18 @@ function isImportOptions(value: unknown): value is ImportOptions {
 
 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;
 
   constructor(peerId?: string) {
     this.inner = newFlock(normalizePeerId(peerId));
@@ -1163,13 +1179,218 @@ 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 {
+    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);
+    }
+  }
+
+  private emitBatch(batch: EventBatch): void {
+    for (const listener of this.listeners) {
+      listener(batch);
+    }
+  }
+
+  private resetDebounceTimer(isFirstEvent: boolean): 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
+    if (this.debounceState.maxTimerId === undefined && isFirstEvent) {
+      this.debounceState.maxTimerId = setTimeout(() => {
+        this.commit();
+      }, this.debounceState.maxDebounceTime);
+    }
+  }
+
   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",
+      );
+    }
+    if (this.debounceState !== undefined) {
+      throw new Error("autoDebounceCommit is already active");
     }
-    return unsubscribe as () => void;
+
+    const maxDebounceTime = options?.maxDebounceTime ?? 10000;
+
+    this.debounceState = {
+      timeout,
+      maxDebounceTime,
+      timerId: undefined,
+      maxTimerId: undefined,
+      pendingEvents: [],
+    };
+  }
+
+  /**
+   * Disable auto-debounce mode and emit any pending events immediately.
+   * 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 });
+    }
+  }
+
+  /**
+   * 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 {
+    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 = [];
+    }
+  }
+
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean {
+    return this.debounceState !== undefined;
+  }
+
+  /**
+   * Execute operations within a transaction. All put/delete operations inside
+   * the callback will be batched and emitted as a single EventBatch when the
+   * transaction commits successfully.
+   *
+   * If the callback throws an error, the transaction is rolled back and no
+   * events are emitted. Note: Data changes are NOT rolled back - only event
+   * emission is affected.
+   *
+   * The callback must be synchronous. For async operations, use FlockSQLite.
+   *
+   * @param callback - Synchronous function containing put/delete operations
+   * @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)
+   *
+   * @example
+   * ```ts
+   * flock.txn(() => {
+   *   flock.put(["a"], 1);
+   *   flock.put(["b"], 2);
+   *   flock.put(["c"], 3);
+   * });
+   * // Subscribers receive a single EventBatch with 3 events
+   * ```
+   */
+  txn<T>(callback: () => T): T {
+    txn_begin_ffi(this.inner);
+    try {
+      const result = callback();
+      txn_commit_ffi(this.inner);
+      return result;
+    } catch (e) {
+      // Only rollback if transaction is still active.
+      // import_json auto-commits the transaction before throwing,
+      // so we must check before attempting rollback.
+      if (is_in_txn_ffi(this.inner)) {
+        txn_rollback_ffi(this.inner);
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * Check if a transaction is currently active.
+   */
+  isInTxn(): boolean {
+    return Boolean(is_in_txn_ffi(this.inner));
   }
 }