LoroRepo TypeScript bindings

LoroRepo is the collection-sync layer above Flock. It coordinates document metadata and document bodies so apps can:

• fetch metadata first, then open document bodies on demand,
• reuse one API across centralized servers, Durable Objects, and peer meshes,
• keep repo semantics predictable with explicit soft-delete and purge flows.

What you get

• Metadata-first coordination – repo.listDoc() and repo.watch() expose LWW metadata quickly.
• On-demand documents – openPersistedDoc() gives a repo-managed LoroDoc that can sync once or join a live room; openDetachedDoc() gives an isolated snapshot.
• Pluggable adapters – provide your own TransportAdapter and StorageAdapter (or use built-ins below).
• Consistent events – every event includes by: "local" | "sync" | "live".
• Deletion lifecycle – soft delete (deleteDoc), restore (restoreDoc), and hard purge (purgeDoc) are separate and explicit.

Quick start

import { LoroRepo } from "loro-repo";
import { BroadcastChannelTransportAdapter } from "loro-repo/transport/broadcast-channel";
import { IndexedDBStorageAdaptor } from "loro-repo/storage/indexeddb";

type DocMeta = { title?: string; tags?: string[] };

const repo = await LoroRepo.create<DocMeta>({
  transportAdapter: new BroadcastChannelTransportAdapter({ namespace: "notes" }),
  storageAdapter: new IndexedDBStorageAdaptor({ dbName: "notes-db" }),
});

await repo.sync({ scope: "meta" });
await repo.upsertDocMeta("note:welcome", { title: "Welcome" });

const handle = await repo.openPersistedDoc("note:welcome");
await handle.syncOnce();
const room = await handle.joinRoom();
handle.doc.getText("content").insert(0, "Hello from LoroRepo");
handle.doc.commit();
room.unsubscribe();
await repo.unloadDoc("note:welcome");

Using the API

• Create a repo with await LoroRepo.create<Meta>({ transportAdapter?, storageAdapter? }).
• Swap transport later with await repo.setTransportAdapter(adapter).
• Check adapter availability via repo.hasTransport() and repo.hasStorage().
• Choose sync lanes using repo.sync({ scope: "meta" | "doc" | "full", docIds? }).
• Work with docs through openPersistedDoc, openDetachedDoc, joinDocRoom, unloadDoc, and flush.
• React to changes with repo.watch(listener, { docIds, kinds, metadataFields, by }).
• Shutdown cleanly by calling await repo.destroy().

Built-in adapters

• BroadcastChannelTransportAdapter (src/transport/broadcast-channel.ts)
• WebSocketTransportAdapter (src/transport/websocket.ts)
• IndexedDBStorageAdaptor (src/storage/indexeddb.ts)
• FileSystemStorageAdaptor (src/storage/filesystem.ts)
• SqliteRepoStore (src/storage/sqlite.ts, Node.js only)

SQLite storage (Node.js / Electron)

SqliteRepoStore packs everything a repo needs into a single SQLite database file and is the recommended Node-side storage when the streams transport is in use. Compared to FileSystemStorageAdaptor, it avoids creating many small files for incremental updates, and it lets remote-cursor advances become single-row UPDATEs instead of rewriting a large JSON blob.

A single SqliteRepoStore instance exposes two adapters that share one database connection:

• store.storage — a StorageAdapter for doc snapshots, doc updates, and metadata (Flock) snapshots/updates.
• store.cursorStore — a RemoteCursorStore for the streams transport's remoteCursorStore option.

import { LoroRepo } from "loro-repo";
import { SqliteRepoStore } from "loro-repo/storage/sqlite";
import { StreamsTransportAdapter } from "loro-repo/transport/streams";

const store = new SqliteRepoStore({ path: "./data/repo.db" });

const repo = await LoroRepo.create({
  storageAdapter: store.storage,
  transportAdapter: new StreamsTransportAdapter({
    bucketId: "your-bucket",
    auth: yourAuthProvider,
    remoteCursorStore: store.cursorStore,
    // Required when `remoteCursorStore` persists across restarts. Both hooks
    // run inside `beforeRemoteCursorSave`, so the local doc / Flock state is
    // durable *before* the cursor advances. Skipping them risks a crash that
    // leaves the cursor pointing past data that was never persisted locally.
    onPersistDoc: async (docId, doc) => {
      await store.storage.save({
        type: "doc-snapshot",
        docId,
        snapshot: doc.export({ mode: "snapshot" }),
      });
    },
    onPersistMeta: async (flock) => {
      await store.storage.save({
        type: "meta-snapshot",
        snapshot: flock.exportFile(),
      });
    },
  }),
});

// Shutdown
await repo.destroy();
store.close();

⚠️ onPersistDoc and onPersistMeta are not optional when you wire a durable remoteCursorStore. The streams transport advances cursors only after beforeRemoteCursorSave resolves; if local persistence does not run there, a crash can leave SQLite with stale doc/meta state while the cursor resumes after data that was never applied locally. The InMemoryRemoteCursorStore default is the only configuration where omitting the hooks is safe, since the cursor itself is lost on restart.

SqliteRepoStoreOptions:

| Option | Default | Description | | --- | --- | --- | | path | ":memory:" | SQLite file path. Use ":memory:" for an ephemeral store. | | database | — | Pass a pre-constructed better-sqlite3 Database to share a connection; the caller owns its lifetime. | | tablePrefix | "" | Optional prefix for all table names, useful when multiple repos share one database. | | wal | true | Enables journal_mode=WAL + synchronous=NORMAL for fast, durable writes. |

The schema (created on first use) is:

docs           (doc_id PK, snapshot, updated_at, snapshot_digest)
doc_updates    (id, doc_id, update_data, created_at)
meta_snapshot  (id=1, snapshot, updated_at)
meta_updates   (id, update_data, created_at)
remote_cursors (stream_url PK, next_offset, server_lower_bound_version, updated_at_ms)

loadDoc / loadMeta opportunistically compact replayed updates into a fresh snapshot inside a single transaction, mirroring the filesystem adapter's behaviour but without any file churn.

Backups in WAL mode

With the default wal: true, SQLite writes to two sidecar files alongside the main DB: <path>-wal and <path>-shm. Recent writes may live only in the WAL until a checkpoint runs. If you copy the database file out for backup, also copy both sidecars or force a checkpoint first — pass a pre-constructed Database via the database option so your code keeps access to the connection and can call pragma("wal_checkpoint(TRUNCATE)") before snapshotting. Otherwise the .db-only copy can miss recent writes.

Installation

better-sqlite3 is declared as an optional peer dependency. Install it explicitly in projects that want SQLite storage, along with @types/better-sqlite3 for TypeScript users (the runtime package ships no .d.ts of its own and the published loro-repo/storage/sqlite types reference it):

pnpm add better-sqlite3
pnpm add -D @types/better-sqlite3
# or: npm install better-sqlite3 && npm install -D @types/better-sqlite3

Node version compatibility

loro-repo itself supports Node ≥ 18. better-sqlite3 versions matter:

| Node version | Use better-sqlite3 | | --- | --- | | 18.x | ^11 (v11 is the last line that supports Node 18) | | ≥ 20 | ^11 or ^12 |

If you're on Node 18, install better-sqlite3@^11 explicitly — picking up v12 will fail at runtime with an unsupported-Node error. The loro-repo implementation only uses APIs present in both lines, so either works.

Browsers should keep using IndexedDBStorageAdaptor (see the previous section). The loro-repo/storage/sqlite entry is the only place that imports better-sqlite3, so importing the main package or any other adapter never pulls native bindings into a browser bundle.

Core API surface

Lifecycle

• await LoroRepo.create<Meta>(options)
• await repo.sync(options?)
• await repo.destroy()

Metadata

• await repo.upsertDocMeta(docId, patch)
• await repo.getDocMeta(docId)
• await repo.listDoc(query?)
• repo.getMeta() / repo.getRawMeta()

Documents

• await repo.openPersistedDoc(docId)
• await repo.openDetachedDoc(docId)
• await repo.joinDocRoom(docId, params?)
• await repo.unloadDoc(docId)
• await repo.flush()

Deletion

• await repo.deleteDoc(docId, { force? })
• await repo.restoreDoc(docId)
• await repo.purgeDoc(docId)

Events

• const handle = repo.watch(listener, filter?)
• handle.unsubscribe()
• doc-existence-changed carries { from, to } over "missing" | "active" | "deleted"
• doc-metadata carries field patches

Doc deletion lifecycle

1. Soft delete (deleteDoc) writes e/<docId> = false and keeps metadata/doc snapshots available.
2. Restore (restoreDoc) writes e/<docId> = true.
3. Hard purge (purgeDoc) removes existence/metadata and drops local doc snapshots.
4. Legacy cleanup: during purge, legacy ts/<docId>, f/<docId>/*, and ld/<docId>/* rows are also removed when present.

Commands

| Command | Purpose | | --- | --- | | pnpm --filter loro-repo typecheck | Runs tsc with noEmit. | | pnpm --filter loro-repo test | Runs Vitest suites. | | pnpm --filter loro-repo check | Runs typecheck + tests. |

Set LORO_WEBSOCKET_E2E=1 when running websocket end-to-end specs.

Examples

• P2P Journal (examples/p2p-journal/) – Vite + React demo with BroadcastChannel + IndexedDB.
• Sync script (examples/sync-example.ts) – metadata/document synchronization walkthrough.

Contributing

Follow Conventional Commits, run pnpm --filter loro-repo check before opening a PR, and keep prd/ docs aligned with behavior changes.