loro-repo 0.3.0 → 0.4.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.

package/dist/index.cjs

@@ -6,16 +6,12 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
 	}
 	return to;
 };
@@ -26,18 +22,27 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 let __loro_dev_flock = require("@loro-dev/flock");
-let loro_adaptors = require("loro-adaptors");
+__loro_dev_flock = __toESM(__loro_dev_flock);
+let loro_adaptors_loro = require("loro-adaptors/loro");
+loro_adaptors_loro = __toESM(loro_adaptors_loro);
 let loro_protocol = require("loro-protocol");
+loro_protocol = __toESM(loro_protocol);
 let loro_websocket = require("loro-websocket");
+loro_websocket = __toESM(loro_websocket);
 let loro_crdt = require("loro-crdt");
+loro_crdt = __toESM(loro_crdt);
+let loro_adaptors_flock = require("loro-adaptors/flock");
+loro_adaptors_flock = __toESM(loro_adaptors_flock);
 let node_fs = require("node:fs");
+node_fs = __toESM(node_fs);
 let node_path = require("node:path");
 node_path = __toESM(node_path);
 let node_crypto = require("node:crypto");
+node_crypto = __toESM(node_crypto);
 
 //#region src/loro-adaptor.ts
 function createRepoFlockAdaptorFromDoc(flock, config = {}) {
-	return new loro_adaptors.FlockAdaptor(flock, config);
+	return new loro_adaptors_flock.FlockAdaptor(flock, config);
 }
 
 //#endregion
@@ -391,7 +396,7 @@ var WebSocketTransportAdapter = class {
 			});
 			await this.leaveDocSession(docId).catch(() => {});
 		}
-		const adaptor = new loro_adaptors.LoroAdaptor(doc);
+		const adaptor = new loro_adaptors_loro.LoroAdaptor(doc);
 		debug("joining doc room", {
 			docId,
 			roomId,
@@ -1895,13 +1900,11 @@ var AssetManager = class {
 		if (params.assetId && params.assetId !== assetId) throw new Error("Provided assetId does not match content digest");
 		const existing = this.assets.get(assetId);
 		if (existing) {
-			if (!existing.data) {
-				const clone = bytes.slice();
-				existing.data = clone;
-				if (this.storage) await this.storage.save({
+			if (this.storage) {
+				if (!await this.storage.loadAsset(assetId)) await this.storage.save({
 					type: "asset",
 					assetId,
-					data: clone.slice()
+					data: bytes.slice()
 				});
 			}
 			let metadataMutated = false;
@@ -1928,7 +1931,7 @@ var AssetManager = class {
 				await this.persistMeta();
 				this.eventBus.emit({
 					kind: "asset-metadata",
-					asset: this.createAssetDownload(assetId, metadata$1, existing.data),
+					asset: this.createAssetDownload(assetId, metadata$1, bytes),
 					by: "local"
 				});
 			}
@@ -1958,7 +1961,8 @@ var AssetManager = class {
 			assetId,
 			data: storedBytes.slice()
 		});
-		this.rememberAsset(metadata, storedBytes);
+		this.rememberAsset(metadata);
+		this.markAssetAsOrphan(assetId, metadata);
 		this.updateDocAssetMetadata(assetId, metadata);
 		this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 		await this.persistMeta();
@@ -1979,13 +1983,11 @@ var AssetManager = class {
 		const existing = this.assets.get(assetId);
 		if (existing) {
 			metadata = existing.metadata;
-			if (!existing.data) {
-				const clone = bytes.slice();
-				existing.data = clone;
-				if (this.storage) await this.storage.save({
+			if (this.storage) {
+				if (!await this.storage.loadAsset(assetId)) await this.storage.save({
 					type: "asset",
 					assetId,
-					data: clone.slice()
+					data: bytes.slice()
 				});
 			}
 			let nextMetadata = metadata;
@@ -2025,11 +2027,11 @@ var AssetManager = class {
 				await this.persistMeta();
 				this.eventBus.emit({
 					kind: "asset-metadata",
-					asset: this.createAssetDownload(assetId, metadata, existing.data),
+					asset: this.createAssetDownload(assetId, metadata, bytes),
 					by: "local"
 				});
 			} else metadata = existing.metadata;
-			storedBytes = existing.data;
+			storedBytes = bytes;
 			this.rememberAsset(metadata);
 		} else {
 			metadata = {
@@ -2055,7 +2057,7 @@ var AssetManager = class {
 				assetId,
 				data: storedBytes.slice()
 			});
-			this.rememberAsset(metadata, storedBytes);
+			this.rememberAsset(metadata);
 			this.updateDocAssetMetadata(assetId, metadata);
 			this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 			created = true;
@@ -2063,9 +2065,7 @@ var AssetManager = class {
 		const mapping = this.docAssets.get(docId) ?? /* @__PURE__ */ new Map();
 		mapping.set(assetId, metadata);
 		this.docAssets.set(docId, mapping);
-		const refs = this.assetToDocRefs.get(assetId) ?? /* @__PURE__ */ new Set();
-		refs.add(docId);
-		this.assetToDocRefs.set(assetId, refs);
+		this.addDocReference(assetId, docId);
 		this.metaFlock.put([
 			"ld",
 			docId,
@@ -2095,20 +2095,7 @@ var AssetManager = class {
 			docId,
 			assetId
 		]);
-		const refs = this.assetToDocRefs.get(assetId);
-		if (refs) {
-			refs.delete(docId);
-			if (refs.size === 0) {
-				this.assetToDocRefs.delete(assetId);
-				const record = this.assets.get(assetId);
-				if (record) this.orphanedAssets.set(assetId, {
-					metadata: record.metadata,
-					deletedAt: Date.now()
-				});
-				this.metaFlock.delete(["a", assetId]);
-				this.assets.delete(assetId);
-			}
-		}
+		this.removeDocAssetReference(assetId, docId);
 		await this.persistMeta();
 		this.eventBus.emit({
 			kind: "asset-unlink",
@@ -2195,12 +2182,11 @@ var AssetManager = class {
 			this.handleAssetRemoval(assetId, by);
 			return;
 		}
-		const existingData = previous?.data;
-		this.rememberAsset(metadata, existingData);
+		this.rememberAsset(metadata);
 		this.updateDocAssetMetadata(assetId, cloneRepoAssetMetadata(metadata));
 		if (!previous || !assetMetadataEqual(previous.metadata, metadata)) this.eventBus.emit({
 			kind: "asset-metadata",
-			asset: this.createAssetDownload(assetId, metadata, existingData),
+			asset: this.createAssetDownload(assetId, metadata),
 			by
 		});
 	}
@@ -2215,11 +2201,7 @@ var AssetManager = class {
 			if (typeof assetId !== "string") continue;
 			const metadata = assetMetaFromJson(row.value);
 			if (!metadata) continue;
-			const existing = this.assets.get(assetId);
-			nextAssets.set(assetId, {
-				metadata,
-				data: existing?.data
-			});
+			nextAssets.set(assetId, { metadata });
 		}
 		const nextDocAssets = /* @__PURE__ */ new Map();
 		const linkRows = this.metaFlock.scan({ prefix: ["ld"] });
@@ -2255,12 +2237,18 @@ var AssetManager = class {
 			this.assetToDocRefs.set(assetId, refs);
 		}
 		this.assets.clear();
-		for (const record of nextAssets.values()) this.rememberAsset(record.metadata, record.data);
+		for (const record of nextAssets.values()) this.rememberAsset(record.metadata);
+		for (const assetId of nextAssets.keys()) {
+			const refs = this.assetToDocRefs.get(assetId);
+			if (!refs || refs.size === 0) {
+				if (!this.orphanedAssets.has(assetId)) this.markAssetAsOrphan(assetId, nextAssets.get(assetId).metadata);
+			} else this.orphanedAssets.delete(assetId);
+		}
 		for (const [assetId, record] of nextAssets) {
 			const previous = prevAssets.get(assetId)?.metadata;
 			if (!assetMetadataEqual(previous, record.metadata)) this.eventBus.emit({
 				kind: "asset-metadata",
-				asset: this.createAssetDownload(assetId, record.metadata, record.data),
+				asset: this.createAssetDownload(assetId, record.metadata),
 				by
 			});
 		}
@@ -2356,36 +2344,24 @@ var AssetManager = class {
 		};
 	}
 	async materializeAsset(assetId) {
-		let record = this.assets.get(assetId);
-		if (record?.data) return {
-			metadata: record.metadata,
-			bytes: record.data.slice()
-		};
+		const record = this.assets.get(assetId);
 		if (record && this.storage) {
 			const stored = await this.storage.loadAsset(assetId);
-			if (stored) {
-				const clone = stored.slice();
-				record.data = clone.slice();
-				return {
-					metadata: record.metadata,
-					bytes: clone
-				};
-			}
+			if (stored) return {
+				metadata: record.metadata,
+				bytes: stored
+			};
 		}
 		if (!record && this.storage) {
 			const stored = await this.storage.loadAsset(assetId);
 			if (stored) {
 				const metadata$1 = this.getAssetMetadata(assetId);
 				if (!metadata$1) throw new Error(`Missing metadata for asset ${assetId}`);
-				const clone = stored.slice();
-				this.assets.set(assetId, {
-					metadata: metadata$1,
-					data: clone.slice()
-				});
+				this.assets.set(assetId, { metadata: metadata$1 });
 				this.updateDocAssetMetadata(assetId, metadata$1);
 				return {
 					metadata: metadata$1,
-					bytes: clone
+					bytes: stored
 				};
 			}
 		}
@@ -2401,10 +2377,7 @@ var AssetManager = class {
 			...remote.policy ? { policy: remote.policy } : {},
 			...remote.tag ? { tag: remote.tag } : {}
 		};
-		this.assets.set(assetId, {
-			metadata,
-			data: remoteBytes.slice()
-		});
+		this.assets.set(assetId, { metadata });
 		this.updateDocAssetMetadata(assetId, metadata);
 		this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
 		await this.persistMeta();
@@ -2426,18 +2399,14 @@ var AssetManager = class {
 			if (assets) assets.set(assetId, metadata);
 		}
 	}
-	rememberAsset(metadata, bytes) {
-		const data = bytes ? bytes.slice() : this.assets.get(metadata.assetId)?.data;
-		this.assets.set(metadata.assetId, {
-			metadata,
-			data
-		});
-		this.orphanedAssets.delete(metadata.assetId);
+	rememberAsset(metadata) {
+		this.assets.set(metadata.assetId, { metadata });
 	}
 	addDocReference(assetId, docId) {
 		const refs = this.assetToDocRefs.get(assetId) ?? /* @__PURE__ */ new Set();
 		refs.add(docId);
 		this.assetToDocRefs.set(assetId, refs);
+		this.orphanedAssets.delete(assetId);
 	}
 	removeDocAssetReference(assetId, docId) {
 		const refs = this.assetToDocRefs.get(assetId);