LoroRepo TypeScript bindings

LoroRepo is the collection-sync layer that sits above Flock. It keeps document metadata, CRDT bodies, and binary assets coordinated so apps can:

• fetch metadata first, then stream document bodies on demand,
• reuse the same API across centralized servers, Durable Objects, or peer-to-peer transports,
• progressively add asset sync, encryption, and garbage collection without changing app code.

What you get

• Metadata-first coordination – repo.listDoc() and repo.watch() expose LWW metadata so UIs can render collections before bodies arrive.
• On-demand documents – openPersistedDoc() hands back a repo-managed LoroDoc that persists locally and can sync once or join live rooms; openDetachedDoc() is a read-only snapshot.
• Binary asset orchestration – linkAsset()/fetchAsset() dedupe SHA-256 addressed blobs across docs, while gcAssets() sweeps unreferenced payloads.
• Pluggable adapters – supply your own TransportAdapter, StorageAdapter, and AssetTransportAdapter (or use the built-ins below) to target servers, CF Durable Objects, or local-first meshes.
• Consistent events – every event includes by: "local" | "sync" | "live" so you can react differently to local edits, explicit sync pulls, or realtime merges.

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" }); // metadata-first

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

const handle = await repo.openPersistedDoc("note:welcome");
await handle.syncOnce(); // optional: fetch body once
const room = await handle.joinRoom(); // optional: live updates
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?, assetTransportAdapter?, docFrontierDebounceMs? }); metadata is hydrated automatically.
• Define your metadata contract once via the generic Meta. All metadata helpers (upsertDocMeta, getDocMeta, listDoc, watch) stay type-safe.
• Choose sync lanes with repo.sync({ scope: "meta" | "doc" | "full", docIds?: string[] }) to pull remote changes on demand.
• Work with documents using openPersistedDoc(docId) for repo-managed docs (persisted snapshots + frontier tracking) and openDetachedDoc(docId) for isolated snapshots; call joinDocRoom/handle.joinRoom for live sync, or unloadDoc/flush to persist and drop cached docs.
• Join realtime rooms by calling joinMetaRoom() / joinDocRoom(docId); the behaviour depends entirely on the transport adapter you injected.
• Manage assets through linkAsset, uploadAsset, fetchAsset (alias ensureAsset), listAssets, and gcAssets({ minKeepMs }).
• React to changes by subscribing with repo.watch(listener, { docIds, kinds, metadataFields, by }).
• Shut down cleanly via await repo.destroy() to flush snapshots and dispose adapters.

Built-in adapters

Adapters are shipped as subpath exports so the default loro-repo entry stays host-agnostic. Import them directly from their paths, e.g. loro-repo/transport/websocket or loro-repo/storage/indexeddb.

• BroadcastChannelTransportAdapter (src/transport/broadcast-channel.ts)
  Same-origin peer-to-peer transport that lets browser tabs exchange metadata/doc deltas through the BroadcastChannel API. Perfect for demos, offline PWAs, or local-first UIs; used in the quick-start snippet and the P2P Journal example. Import via loro-repo/transport/broadcast-channel.

• WebSocketTransportAdapter (src/transport/websocket.ts)
  loro-websocket powered transport for centralized servers or Durable Objects. Provide url, metadataRoomId, and optional auth callbacks and it handles join/sync lifecycles for you:

  import { WebSocketTransportAdapter } from "loro-repo/transport/websocket";
  
  const transport = new WebSocketTransportAdapter({
    url: "wss://sync.example.com/repo",
    metadataRoomId: "workspace:meta",
    docAuth: (docId) => authFor(docId),
  });

• IndexedDBStorageAdaptor (src/storage/indexeddb.ts)
  Browser storage for metadata snapshots, doc snapshots/updates, and cached assets. Swap it out for SQLite/LevelDB/file-system adaptors when running on desktop or server environments. Import via loro-repo/storage/indexeddb.

• FileSystemStorageAdaptor (src/storage/filesystem.ts)
  Node-friendly persistence layer that writes metadata snapshots, doc snapshots/updates, and assets to the local file system. Point it at a writable directory (defaults to .loro-repo in your current working folder) when building Electron apps, desktop sync daemons, or tests that need durable state without IndexedDB. Import via loro-repo/storage/filesystem.

• Asset transports
  Bring your own AssetTransportAdapter (HTTP uploads, peer meshes, S3, etc.). LoroRepo dedupes via SHA-256 assetIds while your adaptor decides how to encrypt/store the bytes.

Core API surface

Lifecycle

• await LoroRepo.create<Meta>({ transportAdapter?, storageAdapter?, assetTransportAdapter?, docFrontierDebounceMs? }) – hydrate metadata and initialise adapters.
• await repo.sync({ scope: "meta" | "doc" | "full", docIds?: string[] }) – pull remote updates on demand.
• await repo.destroy() – persist pending work and dispose adapters.

Metadata

• await repo.upsertDocMeta(docId, patch) – LWW merge with your Meta type.
• await repo.getDocMeta(docId) – clone the stored metadata (or undefined).
• await repo.listDoc(query?) – list docs by prefix/range/limit (RepoDocMeta<Meta>[]).
• repo.getMeta() – access raw Flock if you need advanced scans.

Documents

• await repo.openPersistedDoc(docId) – returns { doc, syncOnce, joinRoom }; mutations persist locally and frontiers are written to metadata.
• await repo.openDetachedDoc(docId) – isolated snapshot handle (no persistence, no live sync) ideal for read-only tasks.
• await repo.joinDocRoom(docId, params?) or await handle.joinRoom(auth?) – spawn a realtime session through your transport; use subscription.unsubscribe() when done.
• await repo.unloadDoc(docId) – flush pending work for a doc and evict it from memory.
• await repo.flush() – persist all loaded docs and flush pending frontier updates.

Assets

• await repo.linkAsset(docId, { content, mime?, tag?, policy?, assetId?, createdAt? }) – upload + link, returning the SHA-256 assetId.
• await repo.uploadAsset(options) – upload without linking to a doc (pre-warm caches).
• await repo.fetchAsset(assetId) / ensureAsset(assetId) – fetch metadata + lazy content() stream (prefers cached blobs).
• await repo.listAssets(docId) – view linked assets (RepoAssetMetadata[]).
• await repo.unlinkAsset(docId, assetId) – drop a link; GC picks up orphans.
• await repo.gcAssets({ minKeepMs, batchSize }) – sweep stale unlinked blobs via the storage adapter.

Events

• const handle = repo.watch(listener, { docIds, kinds, metadataFields, by }) – subscribe to RepoEvent unions (metadata/frontiers/asset lifecycle) with provenance.
• handle.unsubscribe() – stop receiving events.

Realtime metadata

• await repo.joinMetaRoom(params?) – opt into live metadata sync via the transport adapter; call subscription.unsubscribe() to leave.

Commands

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

Set LORO_WEBSOCKET_E2E=1 when you want to run the websocket end-to-end spec.

Examples

• P2P Journal (examples/p2p-journal/) – Vite + React demo that pairs BroadcastChannelTransportAdapter with IndexedDBStorageAdaptor for tab-to-tab sync.
• Sync script (examples/sync-example.ts) – Node-based walkthrough that sets up two repos, a memory transport hub, and an in-memory filesystem to illustrate metadata-first fetch, selective doc sync, and asset flows.

Contributing

Follow Conventional Commits, run pnpm --filter loro-repo check before opening a PR, and reference the “LoroRepo Product Requirements” doc when explaining behavioural changes (metadata-first fetch, pluggable adapters, progressive encryption/GC). Keep generated artifacts in sync and avoid committing build outputs such as target/. If you add a new workflow or feature, link the relevant prd/ entry so the intent stays discoverable.