@loro-dev/flock-sqlite 0.4.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loro-dev/flock-sqlite",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "SQLite-backed Flock CRDT replica for Node, browsers, and Cloudflare Workers.",
   "type": "module",
   "exports": {
@@ -62,7 +62,7 @@
     "tsdown": "^0.15.4",
     "typescript": "^5.9.2",
     "vitest": "^3.2.4",
-    "@loro-dev/flock": "4.2.0"
+    "@loro-dev/flock": "4.4.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/index.ts

@@ -627,6 +627,24 @@ 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 constructor(
     db: UniStoreConnection,
@@ -641,6 +659,8 @@ export class FlockSQLite {
     this.maxHlc = maxHlc;
     this.listeners = new Set();
     this.tables = tables;
+    this.txnEventSink = undefined;
+    this.debounceState = undefined;
   }
 
   static async open(options: FlockSQLiteOptions): Promise<FlockSQLite> {
@@ -662,6 +682,20 @@ export class FlockSQLite {
   }
 
   async close(): Promise<void> {
+    // Commit any pending debounced events
+    if (this.debounceState !== undefined) {
+      this.disableAutoDebounceCommit();
+    }
+
+    // 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);
+      }
+    }
+
     await this.db.close();
   }
 
@@ -908,14 +942,48 @@ export class FlockSQLite {
         source: operation.source,
       };
       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]);
       }
     }
     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 }>,
@@ -1473,6 +1541,23 @@ export class FlockSQLite {
   }
 
   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();
+    }
+
     if (bundle.version !== 0) {
       throw new TypeError("Unsupported bundle version");
     }
@@ -1597,6 +1682,170 @@ export class FlockSQLite {
       this.listeners.delete(listener);
     };
   }
+
+  /**
+   * 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 or rejects, the transaction is rolled back and no
+   * events are emitted. Note: Database operations are NOT rolled back - only
+   * event emission is affected.
+   *
+   * @param callback - Async function containing put/delete operations
+   * @returns The return value of the callback
+   * @throws Error if nested transaction attempted
+   * @throws Error if called while autoDebounceCommit is active
+   *
+   * @example
+   * ```ts
+   * await flock.txn(async () => {
+   *   await flock.put(["a"], 1);
+   *   await flock.put(["b"], 2);
+   *   await flock.put(["c"], 3);
+   * });
+   * // Subscribers receive a single EventBatch with 3 events
+   * ```
+   */
+  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;
+    }
+  }
+
+  /**
+   * Check if a transaction is currently active.
+   */
+  isInTxn(): boolean {
+    return this.txnEventSink !== 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.
+   *
+   * Import operations will automatically call `commit()` before proceeding.
+   *
+   * @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);
+   * await flock.put(["a"], 1);
+   * await 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.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: [],
+    };
+  }
+
+  /**
+   * 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.emitEvents("local", 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.emitEvents("local", pendingEvents);
+      this.debounceState.pendingEvents = [];
+    }
+  }
+
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean {
+    return this.debounceState !== undefined;
+  }
 }
 
 export type {