npm package: @loro-dev/flock-sqlite
Description: SQLite-backed Flock CRDT replica for Node, browsers, and Cloudflare Workers.
Author: Loro contributors
Latest version: 0.9.1

# @loro-dev/flock-sqlite

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

```ts
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):

```ts
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:

```ts
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:

```ts
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