loro-repo 0.3.0 → 0.5.0

package/README.md

@@ -9,7 +9,7 @@ LoroRepo is the collection-sync layer that sits above Flock. It keeps document m
 ## 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.
+- **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.
@@ -22,36 +22,37 @@ import {
   BroadcastChannelTransportAdapter,
   IndexedDBStorageAdaptor,
 } from "loro-repo";
-import { LoroDoc } from "loro-crdt";
 
 type DocMeta = { title?: string; tags?: string[] };
 
-const repo = new LoroRepo<DocMeta>({
+const repo = await LoroRepo.create<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;
+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();
-await handle.close();
+room.unsubscribe();
+await repo.unloadDoc("note:welcome");
 ```
 
 ## Using the API
 
-- **Define your metadata contract** once via `new LoroRepo<Meta>()`. All metadata helpers (`upsertDocMeta`, `getDocMeta`, `listDoc`, `watch`) stay type-safe.
+- **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.close()` to flush snapshots and dispose adapters.
+- **Shut down cleanly** via `await repo.destroy()` to flush snapshots and dispose adapters.
 
 ## Built-in adapters
 
@@ -83,22 +84,22 @@ await handle.close();
 ## 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 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.close()` – persist pending work and dispose adapters.
+- `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.getMetaReplica()` – access raw `Flock` if you need advanced scans.
+- `repo.getMeta()` – access raw `Flock` if you need advanced scans.
 
 **Documents**
-- `await repo.openCollaborativeDoc(docId)` – returns `{ doc, whenSyncedWithRemote, close }`; mutations persist and sync automatically.
+- `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.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.
+- `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.