@loro-dev/flock 4.2.0 → 4.4.0

package/dist/index.d.mts

@@ -120,6 +120,10 @@ type EventBatch = {
 };
 declare class Flock {
   private inner;
+  private listeners;
+  private nativeUnsubscribe;
+  /** Debounce state for autoDebounceCommit */
+  private debounceState;
   constructor(peerId?: string);
   private static fromInner;
   static fromJson(bundle: ExportBundle, peerId: string): Flock;
@@ -186,7 +190,82 @@ declare class Flock {
   putMvr(key: KeyPart[], value: Value, now?: number): void;
   getMvr(key: KeyPart[]): Value[];
   scan(options?: ScanOptions): ScanRow[];
+  private ensureNativeSubscription;
+  private handleBatch;
+  private emitBatch;
+  private resetDebounceTimer;
   subscribe(listener: (batch: EventBatch) => void): () => void;
+  /**
+   * 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;
+  /**
+   * Disable auto-debounce mode and emit any pending events immediately.
+   * No-op if autoDebounceCommit is not active.
+   */
+  disableAutoDebounceCommit(): void;
+  /**
+   * 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;
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean;
+  /**
+   * 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;
+  /**
+   * Check if a transaction is currently active.
+   */
+  isInTxn(): boolean;
 }
 //#endregion
 export { EntryClock, EntryInfo, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry, decodeVersionVector, encodeVersionVector };

package/dist/index.d.ts

@@ -120,6 +120,10 @@ type EventBatch = {
 };
 declare class Flock {
   private inner;
+  private listeners;
+  private nativeUnsubscribe;
+  /** Debounce state for autoDebounceCommit */
+  private debounceState;
   constructor(peerId?: string);
   private static fromInner;
   static fromJson(bundle: ExportBundle, peerId: string): Flock;
@@ -186,7 +190,82 @@ declare class Flock {
   putMvr(key: KeyPart[], value: Value, now?: number): void;
   getMvr(key: KeyPart[]): Value[];
   scan(options?: ScanOptions): ScanRow[];
+  private ensureNativeSubscription;
+  private handleBatch;
+  private emitBatch;
+  private resetDebounceTimer;
   subscribe(listener: (batch: EventBatch) => void): () => void;
+  /**
+   * 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;
+  /**
+   * Disable auto-debounce mode and emit any pending events immediately.
+   * No-op if autoDebounceCommit is not active.
+   */
+  disableAutoDebounceCommit(): void;
+  /**
+   * 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;
+  /**
+   * Check if auto-debounce mode is currently active.
+   */
+  isAutoDebounceActive(): boolean;
+  /**
+   * 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;
+  /**
+   * Check if a transaction is currently active.
+   */
+  isInTxn(): boolean;
 }
 //#endregion
 export { EntryClock, EntryInfo, Event, EventBatch, EventPayload, ExportBundle, ExportHookContext, ExportHooks, ExportPayload, ExportRecord, Flock, ImportAccept, ImportDecision, ImportHookContext, ImportHooks, ImportPayload, ImportReport, ImportSkip, KeyPart, MetadataMap, PutHookContext, PutHooks, PutPayload, PutWithMetaOptions, ScanBound, ScanOptions, ScanRow, Value, VersionVector, VersionVectorEntry, decodeVersionVector, encodeVersionVector };