@loro-dev/flock-sqlite

@loro-dev/flock-sqlite

SQLite-backed implementation of the Flock CRDT surface. This package mirrors the TypeScript bindings while persisting state through unisqlite and stays wire-compatible with the MoonBit-backed bindings.

import { Flock } from "@loro-dev/flock-sqlite";

const flock = await Flock.open({ path: "flock.db" });
await flock.put(["doc", 1], { title: "hello" });
const bundle = await flock.exportJson();

const replica = await Flock.fromJson({ path: "replica.db", bundle });
console.log(await replica.get(["doc", 1])); // { title: "hello" }
await flock.close();
await replica.close();

See prd/003-flock-sqlite.md for the intended semantics (memcomparable keys, export/import, digest, and cross-platform SQLite adapters).

Multi-tab host role (browser)

When running in browsers with multiple tabs open on the same database, unisqlite elects a single tab as the writable host. @loro-dev/flock-sqlite exposes that role so applications can avoid redundant work (e.g. multiple sync links or duplicated persistence pipelines):

const flock = await Flock.open({ path: "flock.db" });

if (flock.getRole() === "host") {
  // Start background sync / persistence only on the host tab.
}

const unsubscribe = flock.subscribeRoleChange((role) => {
  if (role === "host") {
    // Became host.
  } else if (role === "participant") {
    // Lost host.
  } else {
    // "unknown": initializing/closing; treat conservatively.
  }
});

In the same multi-tab scenario, writes/imports are logically host-only:

• Host executes all put/delete/importJson/... and broadcasts a commit to every tab.
• Participant tabs forward write intent to the host and only consume the broadcast commit events (no local transactions).

Subscription events carry clocks so consumers can reason about ordering and incremental sync:

flock.subscribe((batch) => {
  for (const event of batch.events) {
    console.log(event.key, event.clock);
  }
});

Dependency injection (advanced)

For unit testing (or non-browser runtimes), you can inject the multi-tab environment dependencies instead of relying on BroadcastChannel, real timers, or browser-driven role transitions:

import { Flock, type FlockTransportFactory, type FlockRoleProvider, type FlockRuntime } from "@loro-dev/flock-sqlite";

const transportFactory: FlockTransportFactory = (name) => /* ... */;
const roleProvider: FlockRoleProvider = /* ... */;
const runtime: FlockRuntime = /* ... */;

const flock = await Flock.open({
  path: ":memory:",
  multiTab: { transportFactory, roleProvider, runtime, tabId: "tab-a" },
});

This makes the multi-instance routing logic fully testable in Vitest with in-memory SQLite, without Playwright.

txn() / autoDebounceCommit() semantics

txn() and autoDebounceCommit() only batch local write events initiated by this instance (i.e. commits with origin === this tab and source === "local"). Commits broadcast from other tabs are never buffered and always flow to subscribers immediately.

Runtime peers

This adapter relies on unisqlite platform drivers. Install the matching peers for your environment:

• Node: better-sqlite3
• Browser: broadcast-channel and @sqlite.org/sqlite-wasm (when loading WASM from npm/CDN)
• Cloudflare Workers: no extra peers required