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().

Multiple transports

A repo can run several transports at once — e.g. a local IPC transport plus a best-effort cloud transport. Each room joins every transport its route selects, imports fan into the same doc from all of them (CRDT delivery is idempotent and commutative), and per-room statuses are never merged across transports: every (room, transport) pair keeps its own observable state.

const repo = await LoroRepo.create({
  // Optional routing policy; defaults to "all registered transports".
  resolveRoomTransports: ({ kind, id }) => ({
    transportIds: isLocallyOwned(id) ? ["local", "cloud"] : ["cloud"],
  }),
});

await repo.addTransport("local", localAdapter);
// Hot-attach later (e.g. once authenticated); designate it for ephemeral rooms.
await repo.addTransport("cloud", cloudAdapter, { ephemeral: true });

const room = await repo.joinDocRoom("note:welcome");
room.subscription("local").status;         // "joined" | ... | "detached"
room.subscription("cloud").onStatusChange((status) => { /* repair loop */ });

// Enumerate all of one transport's rooms (e.g. to find broken cloud rooms
// and repair them) without maintaining your own registry:
for (const { room: descriptor, subscription } of repo.transportRooms("cloud")) {
  if (subscription.status === "error") void subscription.rejoin();
}

// Room ownership resolved asynchronously? Re-evaluate routes for live rooms:
await repo.refreshTransportRoutes();

// Hot-detach on sign-out; the handles above report "detached" and resume
// automatically after a later addTransport("cloud", ...).
await repo.removeTransport("cloud");

Key points:

• addTransport(id, adapter, options?) / removeTransport(id, { close? }) register and unregister named transports; setTransportAdapter(adapter) remains as sugar for a single transport under DEFAULT_TRANSPORT_ID.
• resolveRoomTransports({ kind: "meta" | "doc" | "flock-doc", id }) decides which transports join each room. It may return ids that are not registered yet (they attach when added) or an empty list (the room stays pending until a later refreshTransportRoutes()).
• Rooms can be joined before ANY transport is registered (offline-first startup): the join resolves as a pending room whose classic surface reads "disconnected", and it attaches automatically when the first transport is added. Only joinEphemeralRoom requires a registered transport.
• Room handles returned by joinMetaRoom / joinDocRoom / joinFlockDocRoom expose stable per-transport subscriptions via subscription(transportId) / subscriptions(). A handle survives removeTransport/addTransport cycles: it reports "detached" while its transport is absent and resumes live statuses after re-attach.
• The classic single-value members (status, onStatusChange, …) keep working while exactly one transport is routed; with several routed transports they throw instead of merging — there is deliberately no API that aggregates multiple transports' room statuses into one value.
• One transport's failure never affects another's subscription state, join lifecycle, or the doc's ability to import from healthy transports. Room attaches and one-shot sync pipelines run concurrently per transport, so a hanging transport cannot stall a healthy one's convergence, and an aborted sync() settles even while one transport is hung. Adapters always receive the one shared meta Flock instance (their session and durable-cursor persistence are keyed on it); concurrent meta syncs stay independent because CRDT imports commute and cache hydration runs on a single local-only path.
• join*Room resolves as soon as ONE routed transport has attached (or the route is empty/pending); the remaining transports keep attaching in the background, observable via their per-transport subscriptions. It rejects only when every routed registered transport failed to attach.
• repo.transportRooms(transportId) enumerates every live room involving a transport together with its stable per-transport subscription.
• repo.sync() resolves with a RepoSyncReport listing per-transport results (report.ok is a convenience aggregate). A partial failure resolves with ok: false; the call rejects only when every attempted transport failed.
• repo.reconnect({ transportIds? }) targets all or specific transports, and ephemeral rooms go to the transport registered with { ephemeral: true }.

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)
flock_docs     (flock_doc_id PK, snapshot, updated_at, snapshot_digest)
flock_doc_updates (id, flock_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)

Post-sync Flock document persistence is version-vector based: no-op syncs do not write, and changed state is appended as a JSON delta rather than a full Flock file. Local changes that arrive while sync persistence is in flight are queued behind that write and flushed from the last durable version. This keeps storage growth proportional to new CRDT operations while preserving restart convergence. Once a cached Flock document has accumulated 102400 persisted delta bytes, the repo asks adapters that support compaction to consolidate those updates. Configure this bound with flockDocCompactionByteThreshold or set it to 0 to disable compaction. The threshold-crossing delta save queues a coalesced per-document compaction rather than awaiting the full snapshot export, so that sync can return once its delta is durable. The adapter compaction starts on a later event-loop turn while remaining serialized with later document persistence, and flush() / destroy() drain the queued work.

loadDoc / loadFlockDoc / loadMeta opportunistically compact replayed updates into a fresh snapshot inside a single transaction, mirroring the filesystem adapter's behaviour but without any file churn. Existing databases need no migration for delta-aware post-sync persistence; previously amplified rows are compacted the next time that Flock document is loaded. Compaction is driven by actual delta volume, not by time or sync count, so no-op syncs never cause full snapshot exports.

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.