loro-repo 0.0.0

package/README.md

@@ -0,0 +1,132 @@
+# 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** – `openCollaborativeDoc()` gives you a repo-managed `LoroDoc` that persists and syncs automatically; `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
+
+```ts
+import {
+  LoroRepo,
+  BroadcastChannelTransportAdapter,
+  IndexedDBStorageAdaptor,
+} from "loro-repo";
+import { LoroDoc } from "loro-crdt";
+
+type DocMeta = { title?: string; tags?: string[] };
+
+const repo = new LoroRepo<DocMeta>({
+  transportAdapter: new BroadcastChannelTransportAdapter({ namespace: "notes" }),
+  storageAdapter: new IndexedDBStorageAdaptor({ dbName: "notes-db" }),
+  docFactory: async () => new LoroDoc(),
+});
+
+await repo.ready();
+await repo.sync({ scope: "meta" }); // metadata-first
+
+await repo.upsertDocMeta("note:welcome", { title: "Welcome" });
+
+const handle = await repo.openCollaborativeDoc("note:welcome");
+await handle.whenSyncedWithRemote;
+handle.doc.getText("content").insert(0, "Hello from LoroRepo");
+handle.doc.commit();
+await handle.close();
+```
+
+## Using the API
+
+- **Define your metadata contract** once via `new LoroRepo<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.
+- **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.close()` to flush snapshots and dispose adapters.
+
+## Built-in adapters
+
+- `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.
+
+- `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:
+
+  ```ts
+  import { WebSocketTransportAdapter } from "loro-repo";
+
+  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.
+
+- 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**
+- `new LoroRepo<Meta>(options)` – wire adapters (`transportAdapter`, `storageAdapter`, `assetTransportAdapter`, `docFactory`, `docFrontierDebounceMs`).
+- `await repo.ready()` – hydrate metadata snapshot before touching docs.
+- `await repo.sync({ scope: "meta" | "doc" | "full", docIds?: string[] })` – pull remote updates on demand.
+- `await repo.close()` – 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.getMetaReplica()` – access raw `Flock` if you need advanced scans.
+
+**Documents**
+- `await repo.openCollaborativeDoc(docId)` – returns `{ doc, whenSyncedWithRemote, close }`; mutations persist and sync automatically.
+- `await repo.openDetachedDoc(docId)` – isolated snapshot handle (no persistence, no live sync) ideal for read-only tasks.
+- `await repo.whenDocInSyncWithRemote(docId)` – ensure a document caught up without opening it.
+- `await repo.joinDocRoom(docId, params?)` – spawn a realtime session through your transport; use `subscription.unsubscribe()` when done.
+
+**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.