@loro-dev/flock-wasm 0.1.0

package/bundler/event-batcher.d.ts

@@ -0,0 +1,37 @@
+export type TimeoutHandle = unknown;
+export type EventBatcherRuntime = {
+    now(): number;
+    setTimeout(fn: () => void, ms: number): TimeoutHandle;
+    clearTimeout(handle: TimeoutHandle): void;
+};
+export declare class EventBatcher<TEvent> {
+    private outbox;
+    private outboxCursor;
+    private draining;
+    private txnEventSink;
+    private debounceState;
+    private readonly runtime;
+    private readonly emit;
+    constructor(options: {
+        runtime: EventBatcherRuntime;
+        emit: (source: string, events: TEvent[]) => void;
+    });
+    handleCommitEvents(source: string, events: TEvent[], bufferable: boolean): void;
+    beforeImport(): void;
+    txn<T>(callback: () => Promise<T>): Promise<T>;
+    isInTxn(): boolean;
+    autoDebounceCommit(timeout: number, options?: {
+        maxDebounceTime?: number;
+    }): void;
+    disableAutoDebounceCommit(): void;
+    commit(): void;
+    isAutoDebounceActive(): boolean;
+    close(): void;
+    private enqueueBatch;
+    private drainOutbox;
+    private deliverBatch;
+    private bufferLocalEvents;
+    private scheduleDebounceFlush;
+    private takeDebouncedEvents;
+    private flushDebouncedEvents;
+}

package/bundler/event-batcher.js

@@ -0,0 +1,204 @@
+export class EventBatcher {
+    outbox = [];
+    outboxCursor = 0;
+    draining = false;
+    txnEventSink;
+    debounceState;
+    runtime;
+    emit;
+    constructor(options) {
+        this.runtime = options.runtime;
+        this.emit = options.emit;
+        this.txnEventSink = undefined;
+        this.debounceState = undefined;
+    }
+    handleCommitEvents(source, events, bufferable) {
+        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() {
+        if (this.debounceState !== undefined) {
+            this.commit();
+        }
+    }
+    async txn(callback) {
+        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 = [];
+        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() {
+        return this.txnEventSink !== undefined;
+    }
+    autoDebounceCommit(timeout, options) {
+        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() {
+        if (this.debounceState === undefined) {
+            return;
+        }
+        const eventsToEmit = this.takeDebouncedEvents();
+        this.debounceState = undefined;
+        if (eventsToEmit.length > 0) {
+            this.enqueueBatch({ source: "local", events: eventsToEmit });
+        }
+    }
+    commit() {
+        if (this.debounceState === undefined) {
+            return;
+        }
+        this.flushDebouncedEvents();
+    }
+    isAutoDebounceActive() {
+        return this.debounceState !== undefined;
+    }
+    close() {
+        // 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 });
+            }
+        }
+    }
+    enqueueBatch(batch) {
+        this.outbox.push(batch);
+        this.drainOutbox();
+    }
+    drainOutbox() {
+        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;
+        }
+    }
+    deliverBatch(batch) {
+        try {
+            this.emit(batch.source, batch.events);
+        }
+        catch (error) {
+            void error;
+        }
+    }
+    bufferLocalEvents(events) {
+        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);
+    }
+    scheduleDebounceFlush(now) {
+        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));
+    }
+    takeDebouncedEvents() {
+        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;
+    }
+    flushDebouncedEvents() {
+        const eventsToEmit = this.takeDebouncedEvents();
+        if (eventsToEmit.length === 0) {
+            return;
+        }
+        this.enqueueBatch({ source: "local", events: eventsToEmit });
+    }
+}

package/bundler/flock_wasm.d.ts

@@ -0,0 +1,313 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Initializes the WASM module.
+ *
+ * This function is automatically called when the WASM module is loaded.
+ * It sets up the panic hook to route Rust panics to the JavaScript console.
+ */
+export function start(): void;
+/**
+ * Drains the pending callback queue, invoking all enqueued callbacks.
+ *
+ * This function is exported to JavaScript and can be called manually,
+ * but is typically invoked automatically via microtasks.
+ *
+ * Callbacks are invoked sequentially. If any callback throws an error,
+ * the error is propagated to JavaScript after the current batch completes.
+ */
+export function callPendingEvents(): void;
+/**
+ * The main WASM-exposed flock instance.
+ *
+ * Wraps the underlying [`flock::Flock`] and provides JavaScript-compatible
+ * methods for all CRDT operations including put, get, delete, scan, merge,
+ * import/export, and event subscription.
+ */
+export class RawFlock {
+  free(): void;
+  /**
+   * Commits the current transaction.
+   *
+   * Flushes all buffered operations and delivers batched events.
+   *
+   * # Errors
+   *
+   * Returns an error if no transaction is active or if commit fails.
+   */
+  txnCommit(): void;
+  exportFile(): Uint8Array;
+  /**
+   * Exports the current state as a JSON bundle.
+   *
+   * # Arguments
+   *
+   * * `from` - Optional version vector for incremental export
+   * * `prune_tombstones_before` - Optional timestamp to prune tombstones older than this
+   * * `peer_id` - Optional peer ID filter to only export entries from this peer
+   *
+   * # Returns
+   *
+   * An export bundle containing entries and version information.
+   *
+   * # Errors
+   *
+   * Returns an error if arguments are invalid or serialization fails.
+   */
+  exportJson(from: any, prune_tombstones_before: any, peer_id: any): any;
+  /**
+   * Imports a JSON bundle into this flock instance.
+   *
+   * # Arguments
+   *
+   * * `bundle` - The export bundle to import
+   *
+   * # Returns
+   *
+   * An import report containing counts of accepted and skipped entries.
+   *
+   * # Errors
+   *
+   * Returns an error if the bundle is invalid or import fails.
+   */
+  importJson(bundle: any): any;
+  /**
+   * Sets a new peer ID for this flock instance.
+   *
+   * # Arguments
+   *
+   * * `peer_id` - The new peer ID to set
+   *
+   * # Errors
+   *
+   * Returns an error if the peer ID is invalid.
+   */
+  setPeerId(peer_id: string): void;
+  /**
+   * Unsubscribes from change events.
+   *
+   * # Arguments
+   *
+   * * `id` - The subscription ID returned from `subscribe`
+   *
+   * # Returns
+   *
+   * `true` if a subscription was removed, `false` if the ID was not found.
+   */
+  unsubscribe(id: number): boolean;
+  /**
+   * Rolls back the current transaction.
+   *
+   * Discards all buffered operations since `txnBegin` was called.
+   * Note: Data changes are not rolled back, only event emission is affected.
+   */
+  txnRollback(): void;
+  /**
+   * Stores a value with associated metadata at the specified key.
+   *
+   * # Arguments
+   *
+   * * `key` - The key as a JSON array
+   * * `value` - The value to store
+   * * `metadata` - Optional metadata object to associate with this entry
+   * * `now` - Optional timestamp in milliseconds
+   *
+   * # Errors
+   *
+   * Returns an error if any argument is invalid or the operation fails.
+   */
+  putWithMeta(key: any, value: any, metadata: any, now: any): void;
+  /**
+   * Returns the inclusive version vector for this flock.
+   *
+   * The inclusive version includes all peers ever seen, even if their
+   * entries have been overridden by other peers.
+   *
+   * # Errors
+   *
+   * Returns an error if serialization fails.
+   */
+  inclusiveVersion(): any;
+  /**
+   * Returns the maximum physical time across all entries in this flock.
+   *
+   * This is useful for determining a safe timestamp for tombstone pruning.
+   */
+  getMaxPhysicalTime(): number;
+  /**
+   * Retrieves the value at the specified key.
+   *
+   * Returns `undefined` if the key doesn't exist or has been deleted.
+   *
+   * # Arguments
+   *
+   * * `key` - The key as a JSON array
+   *
+   * # Errors
+   *
+   * Returns an error if serialization of the result fails.
+   */
+  get(key: any): any;
+  /**
+   * Creates a new WASM flock instance with the given peer ID.
+   *
+   * The instance is created in buffered mode with memtable enabled.
+   * Use transactions (`txnBegin` + `txnCommit`) to flush buffered writes explicitly.
+   *
+   * # Arguments
+   *
+   * * `peer_id` - The unique identifier for this peer
+   *
+   * # Errors
+   *
+   * Returns an error if the peer ID is invalid or if instance creation fails.
+   */
+  constructor(peer_id: string);
+  /**
+   * Stores a value at the specified key.
+   *
+   * # Arguments
+   *
+   * * `key` - The key as a JSON array
+   * * `value` - The value to store (any JSON-serializable value)
+   * * `now` - Optional timestamp in milliseconds (uses current time if undefined)
+   *
+   * # Errors
+   *
+   * Returns an error if the key or value is invalid, or if the operation fails.
+   */
+  put(key: any, value: any, now: any): void;
+  /**
+   * Scans entries within the specified bounds and prefix.
+   *
+   * # Arguments
+   *
+   * * `start` - Optional start bound (inclusive/exclusive/unbounded)
+   * * `end` - Optional end bound
+   * * `prefix` - Optional key prefix to filter by
+   *
+   * # Returns
+   *
+   * An array of scan rows containing keys, values, and raw records.
+   *
+   * # Errors
+   *
+   * Returns an error if scan bounds are invalid or serialization fails.
+   */
+  scan(start: any, end: any, prefix: any): any;
+  /**
+   * Merges state from another flock instance into this one.
+   *
+   * # Arguments
+   *
+   * * `other` - The other flock instance to merge from
+   *
+   * # Returns
+   *
+   * An import report containing counts of accepted and skipped entries.
+   *
+   * # Errors
+   *
+   * Returns an error if the merge operation fails.
+   */
+  merge(other: RawFlock): any;
+  /**
+   * Deletes the value at the specified key (creates a tombstone).
+   *
+   * # Arguments
+   *
+   * * `key` - The key as a JSON array
+   * * `now` - Optional timestamp in milliseconds
+   *
+   * # Errors
+   *
+   * Returns an error if the key is invalid or the operation fails.
+   */
+  delete(key: any, now: any): void;
+  /**
+   * Returns the current peer ID of this flock instance.
+   */
+  peerId(): string;
+  /**
+   * Returns the exclusive version vector for this flock.
+   *
+   * The exclusive version only includes peers that have at least one entry
+   * in the current state (excluding tombstones and overridden entries).
+   *
+   * # Errors
+   *
+   * Returns an error if serialization fails.
+   */
+  version(): any;
+  /**
+   * Creates a new flock instance from a file bytes array.
+   *
+   * # Arguments
+   *
+   * * `peer_id` - The peer ID for the new instance
+   * * `bytes` - The file contents as a Uint8Array
+   *
+   * # Errors
+   *
+   * Returns an error if the file format is invalid or loading fails.
+   */
+  static fromFile(peer_id: string, bytes: Uint8Array): RawFlock;
+  /**
+   * Creates a new flock instance from a JSON export bundle.
+   *
+   * # Arguments
+   *
+   * * `bundle` - The export bundle as a JavaScript object
+   * * `peer_id` - The peer ID for the new instance
+   *
+   * # Errors
+   *
+   * Returns an error if the bundle is invalid or import fails.
+   */
+  static fromJson(bundle: any, peer_id: string): RawFlock;
+  /**
+   * Retrieves complete entry information including data, metadata, and clock.
+   *
+   * Returns `undefined` if the key doesn't exist.
+   *
+   * # Arguments
+   *
+   * * `key` - The key as a JSON array
+   *
+   * # Errors
+   *
+   * Returns an error if serialization of the result fails.
+   */
+  getEntry(key: any): any;
+  /**
+   * Returns whether a transaction is currently active.
+   */
+  isInTxn(): boolean;
+  /**
+   * Subscribes to change events from this flock instance.
+   *
+   * # Arguments
+   *
+   * * `listener` - A JavaScript function that will be called with event batches
+   *
+   * # Returns
+   *
+   * A subscription ID that can be used to unsubscribe later.
+   *
+   * # Errors
+   *
+   * Returns an error if the subscription fails or the ID overflows.
+   */
+  subscribe(listener: Function): number;
+  /**
+   * Begins a transaction.
+   *
+   * All subsequent put/delete operations will be buffered until `txnCommit`
+   * is called. Events will be batched and delivered as a single batch on commit.
+   *
+   * # Errors
+   *
+   * Returns an error if a transaction is already active or if begin fails.
+   */
+  txnBegin(): void;
+}

package/bundler/flock_wasm.js

@@ -0,0 +1,5 @@
+import * as wasm from "./flock_wasm_bg.wasm";
+export * from "./flock_wasm_bg.js";
+import { __wbg_set_wasm } from "./flock_wasm_bg.js";
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();