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? }).
• Add transports later with await repo.addTransport(id, adapter, options?).
• Check adapter availability via repo.hasTransport() and repo.hasStorage().
• Choose sync lanes using repo.sync({ scope: "meta" | "doc" | "full", docIds? }). The default is "meta" — metadata is bounded, document bodies are not, so pulling bodies is opt-in. Passing docIds/flockDocIds widens the scope on its own. Bodies planned automatically skip soft-deleted documents and are released after the sync unless retainLoadedDocs says otherwise.
• Acquire replicas with repo.acquireDoc(id) / repo.acquireFlockDoc(id) when a document is used across awaits; the lease keeps the repository from evicting it, and must be release()d.
• 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; the transportAdapter construction option registers 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)

Per-room Streams payload protection

StreamsTransportAdapter can select one streams-crdt provider config for each durable room. The resolver receives only logical room identity:

• Meta Flock: { kind: "meta" }
• Loro document: { kind: "doc", docId }
• named Flock document: { kind: "flock", flockDocId }

The resolver never receives the Durable Streams bucket or stream ID. The adapter privately maps its structured { bucketId, streamId } address to the opaque streamUrl expected by streams-crdt. That URL is transport routing, not cryptographic identity. The provider returned for a logical room owns key lookup and AEAD implementation, while the adapter always binds streams-crdt's envelope AAD to a caller-supplied stable application namespace plus the logical room identity. The binding is versioned, domain-separated, and length-prefixed; it never contains the bucket, stream ID, or URL.

const transport = new StreamsTransportAdapter({
  bucketId: "workspace-data",
  metaStreamId: "workspace:123:meta",
  docStreamId: (docId) => `workspace:123:doc:${docId}`,
  flockDocStreamId: (flockDocId) => `workspace:123:flock:${flockDocId}`,
  auth: yourAuthProvider,
  // Stable application/workspace identity, not a physical stream route.
  payloadProtectionNamespace: "acme-notes/workspace-123",
  payloadProtection: (room) => ({
    mode: "protected",
    config: lodyCrypto.providerConfigForRoom(room),
  }),
});

Once payloadProtection is present, the resolver is total. Every room must return either { mode: "protected", config } or { mode: "plaintext" }. Returning undefined, throwing, or returning an invalid selection fails that room before a StreamsCrdt is created. Protected selections also set upstream payloadProtectionRequired and force readPolicy: "encrypted-only" plus writePolicy: "encrypt". A protected config cannot opt into allow-plaintext reads or plaintext writes. Use the honest top-level { mode: "plaintext" } selection for a public room. Omit payloadProtection entirely to preserve the existing plaintext API and wire behavior.

The resolved config and the provider instance used by seal() are fixed for one room session. In particular, seal() must keep using that session's write epoch; it must not switch dynamically through a mutable vault handle. open() may use the opaque authenticated header to look up historical read keys.

To replace the write provider safely without recreating the whole repo, the application owns a grouped barrier:

1. stop producing writes for the affected room set;
2. await one Promise.all of waitUntilSynced() for every active subscription;
3. only after every wait succeeds, unsubscribe every lease in that set;
4. await restartRoomSessions(rooms) to join any in-progress teardown, then update the application-owned config and rejoin.

The final live lease already starts that room's teardown, so restartRoomSessions is not the atomic drain barrier. It refuses any room that still has a live lease, pending live acquisition, or in-flight one-shot sync; it also fences new joins and one-shot syncs until the selected teardown completes. A successful return therefore leaves no old-generation session that can reappear before the caller switches config. The restart preserves CRDT state and remote cursors and makes the next sync/join call the resolver again. If any waitUntilSynced() fails, keep all leases and the old write providers in place; do not partially release the room set.

Use a non-owning provider handle into an application-owned vault. The adapter wraps the provider only to add its logical-room AAD and fixed encrypted-only policies. Resolver-configured one-shot sessions release that wrapper after each operation, and live sessions release it after their final lease closes. The adapter does not inspect or dispose provider state, and it never stores it in repo metadata, documents, cursor storage, logs, or surfaced error causes.

The same protected StreamsCrdt instance handles updates, snapshots, bootstrap/catch-up, and live reads. A protection failure therefore occurs before CRDT import and before beforeRemoteCursorSave; the adapter keeps the existing "persist CRDT state, then advance cursor" boundary. Each room owns an independent instance, so one room's failure does not stop other rooms.

This API requires @loro-dev/streams-crdt@^0.15.0, specifically its common protected-payload boundary and payloadProtectionRequired guard. No 0.12.x encryption compatibility shim is retained; the adapter passes the published 0.15 opaque streamUrl transport target directly.

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 persistence bundle.

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

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

const repo = await LoroRepo.create({
  storageAdapter: store.storage,
});

await repo.addTransport(
  "streams",
  new StreamsTransportAdapter({
    bucketId: "your-bucket",
    auth: yourAuthProvider,
    // Binds the durable cursor store to the repo's durability barriers: the
    // cursor only advances after the covered doc / Flock / meta state is
    // durably written through `store.storage`.
    persistence: createRepoStreamsPersistence(repo, store.cursorStore),
  }),
);

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

⚠️ A durable cursor store must arrive together with its durability barriers, which is what the persistence bundle enforces: the streams transport advances a cursor only after the matching persist* barrier resolves, so a crash can never leave the cursor pointing past state that was never written locally. Configuring a durable store without a barrier for a lane (the failure mode the deprecated remoteCursorStore + onPersist* options allowed) is now rejected at that lane's first join/sync. Sessions that genuinely keep nothing across restarts should say so with persistence: { mode: "ephemeral" }.

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

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.