@loro-dev/flock-sqlite 0.8.0 → 0.9.1

package/package.json

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

package/src/event-batcher.ts

@@ -0,0 +1,264 @@
+export type TimeoutHandle = unknown;
+
+export type EventBatcherRuntime = {
+  now(): number;
+  setTimeout(fn: () => void, ms: number): TimeoutHandle;
+  clearTimeout(handle: TimeoutHandle): void;
+};
+
+export class EventBatcher<TEvent> {
+  private outbox: Array<{ source: string; events: TEvent[] }> = [];
+  private outboxCursor = 0;
+  private draining = false;
+  private txnEventSink: TEvent[] | undefined;
+  private debounceState:
+    | {
+        timeout: number;
+        maxDebounceTime: number;
+        timerId: TimeoutHandle;
+        deadlineAt: number | undefined;
+        pendingEvents: TEvent[];
+      }
+    | undefined;
+
+  private readonly runtime: EventBatcherRuntime;
+  private readonly emit: (source: string, events: TEvent[]) => void;
+
+  constructor(options: {
+    runtime: EventBatcherRuntime;
+    emit: (source: string, events: TEvent[]) => void;
+  }) {
+    this.runtime = options.runtime;
+    this.emit = options.emit;
+    this.txnEventSink = undefined;
+    this.debounceState = undefined;
+  }
+
+  handleCommitEvents(
+    source: string,
+    events: TEvent[],
+    bufferable: boolean,
+  ): void {
+    if (events.length === 0) {
+      return;
+    }
+
+    if (bufferable && this.txnEventSink) {
+      this.txnEventSink.push(...events);
+      return;
+    }
+    if (bufferable && this.debounceState) {
+      this.bufferLocalEvents(events);
+      return;
+    }
+
+    this.enqueueBatch({ source, events });
+  }
+
+  beforeImport(): void {
+    if (this.debounceState !== undefined) {
+      this.commit();
+    }
+  }
+
+  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: TEvent[] = [];
+    this.txnEventSink = eventSink;
+
+    try {
+      const result = await callback();
+      if (eventSink.length > 0) {
+        this.txnEventSink = undefined;
+        this.enqueueBatch({ source: "local", events: eventSink });
+      }
+      return result;
+    } finally {
+      this.txnEventSink = undefined;
+    }
+  }
+
+  isInTxn(): boolean {
+    return this.txnEventSink !== undefined;
+  }
+
+  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,
+      deadlineAt: undefined,
+      pendingEvents: [],
+    };
+  }
+
+  disableAutoDebounceCommit(): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+
+    const eventsToEmit = this.takeDebouncedEvents();
+    this.debounceState = undefined;
+    if (eventsToEmit.length > 0) {
+      this.enqueueBatch({ source: "local", events: eventsToEmit });
+    }
+  }
+
+  commit(): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+    this.flushDebouncedEvents();
+  }
+
+  isAutoDebounceActive(): boolean {
+    return this.debounceState !== undefined;
+  }
+
+  close(): 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) {
+        const eventsToEmit = pending.slice();
+        pending.length = 0;
+        this.enqueueBatch({ source: "local", events: eventsToEmit });
+      }
+    }
+  }
+
+  private enqueueBatch(batch: { source: string; events: TEvent[] }): void {
+    this.outbox.push(batch);
+    this.drainOutbox();
+  }
+
+  private drainOutbox(): void {
+    if (this.draining) {
+      return;
+    }
+    this.draining = true;
+    try {
+      while (this.outboxCursor < this.outbox.length) {
+        const batch = this.outbox[this.outboxCursor];
+        this.outboxCursor += 1;
+        this.deliverBatch(batch);
+      }
+    } finally {
+      this.outbox = [];
+      this.outboxCursor = 0;
+      this.draining = false;
+    }
+  }
+
+  private deliverBatch(batch: { source: string; events: TEvent[] }): void {
+    try {
+      this.emit(batch.source, batch.events);
+    } catch (error) {
+      void error;
+    }
+  }
+
+  private bufferLocalEvents(events: TEvent[]): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+    if (events.length === 0) {
+      return;
+    }
+    const state = this.debounceState;
+    const now = this.runtime.now();
+    if (state.pendingEvents.length === 0) {
+      state.deadlineAt = now + state.maxDebounceTime;
+    }
+    state.pendingEvents.push(...events);
+    this.scheduleDebounceFlush(now);
+  }
+
+  private scheduleDebounceFlush(now: number): void {
+    if (this.debounceState === undefined) {
+      return;
+    }
+    const state = this.debounceState;
+    if (state.pendingEvents.length === 0) {
+      return;
+    }
+    if (state.timeout <= 0) {
+      this.flushDebouncedEvents();
+      return;
+    }
+
+    const deadlineAt = state.deadlineAt ?? now + state.maxDebounceTime;
+    state.deadlineAt = deadlineAt;
+    const dueAt = Math.min(now + state.timeout, deadlineAt);
+
+    if (dueAt <= now) {
+      this.flushDebouncedEvents();
+      return;
+    }
+
+    if (state.timerId !== undefined) {
+      this.runtime.clearTimeout(state.timerId);
+    }
+
+    state.timerId = this.runtime.setTimeout(() => {
+      this.flushDebouncedEvents();
+    }, Math.max(0, dueAt - now));
+  }
+
+  private takeDebouncedEvents(): TEvent[] {
+    if (this.debounceState === undefined) {
+      return [];
+    }
+    const state = this.debounceState;
+
+    if (state.timerId !== undefined) {
+      this.runtime.clearTimeout(state.timerId);
+      state.timerId = undefined;
+    }
+    state.deadlineAt = undefined;
+
+    if (state.pendingEvents.length === 0) {
+      return [];
+    }
+
+    const eventsToEmit = state.pendingEvents;
+    state.pendingEvents = [];
+    return eventsToEmit;
+  }
+
+  private flushDebouncedEvents(): void {
+    const eventsToEmit = this.takeDebouncedEvents();
+    if (eventsToEmit.length === 0) {
+      return;
+    }
+    this.enqueueBatch({ source: "local", events: eventsToEmit });
+  }
+}