loro-repo 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { Flock } from "@loro-dev/flock";
-import { LoroDoc } from "loro-crdt";
 import { FlockAdaptor, LoroAdaptor } from "loro-adaptors";
 import { CrdtType, bytesToHex } from "loro-protocol";
 import { LoroWebsocketClient } from "loro-websocket";
+import { LoroDoc } from "loro-crdt";
 import { promises } from "node:fs";
 import * as path from "node:path";
 import { randomUUID } from "node:crypto";
@@ -12,8 +12,47 @@ function createRepoFlockAdaptorFromDoc(flock, config = {}) {
 	return new FlockAdaptor(flock, config);
 }
 
+//#endregion
+//#region src/internal/debug.ts
+const getEnv = () => {
+	if (typeof globalThis !== "object" || globalThis === null) return;
+	return globalThis.process?.env;
+};
+const rawNamespaceConfig = (getEnv()?.LORO_REPO_DEBUG ?? "").trim();
+const normalizedNamespaces = rawNamespaceConfig.length > 0 ? rawNamespaceConfig.split(/[\s,]+/).map((token) => token.toLowerCase()).filter(Boolean) : [];
+const wildcardTokens = new Set([
+	"*",
+	"1",
+	"true",
+	"all"
+]);
+const namespaceSet = new Set(normalizedNamespaces);
+const hasWildcard = namespaceSet.size > 0 && normalizedNamespaces.some((token) => wildcardTokens.has(token));
+const isDebugEnabled = (namespace) => {
+	if (!namespaceSet.size) return false;
+	if (!namespace) return hasWildcard;
+	const normalized = namespace.toLowerCase();
+	if (hasWildcard) return true;
+	if (namespaceSet.has(normalized)) return true;
+	const [root] = normalized.split(":");
+	return namespaceSet.has(root);
+};
+const createDebugLogger = (namespace) => {
+	const normalized = namespace.toLowerCase();
+	return (...args) => {
+		if (!isDebugEnabled(normalized)) return;
+		const prefix = `[loro-repo:${namespace}]`;
+		if (args.length === 0) {
+			console.info(prefix);
+			return;
+		}
+		console.info(prefix, ...args);
+	};
+};
+
 //#endregion
 //#region src/transport/websocket.ts
+const debug = createDebugLogger("transport:websocket");
 function withTimeout(promise, timeoutMs) {
 	if (!timeoutMs || timeoutMs <= 0) return promise;
 	return new Promise((resolve, reject) => {
@@ -58,30 +97,51 @@ var WebSocketTransportAdapter = class {
 	}
 	async connect(_options) {
 		const client = this.ensureClient();
-		await client.connect();
-		await client.waitConnected();
+		debug("connect requested", { status: client.getStatus() });
+		try {
+			await client.connect();
+			debug("client.connect resolved");
+			await client.waitConnected();
+			debug("client.waitConnected resolved", { status: client.getStatus() });
+		} catch (error) {
+			debug("connect failed", error);
+			throw error;
+		}
 	}
 	async close() {
+		debug("close requested", {
+			docSessions: this.docSessions.size,
+			metadataSession: Boolean(this.metadataSession)
+		});
 		for (const [docId] of this.docSessions) await this.leaveDocSession(docId).catch(() => {});
 		this.docSessions.clear();
 		await this.teardownMetadataSession().catch(() => {});
 		if (this.client) {
-			this.client.destroy();
+			const client = this.client;
 			this.client = void 0;
+			client.destroy();
+			debug("websocket client destroyed");
 		}
+		debug("close completed");
 	}
 	isConnected() {
 		return this.client?.getStatus() === "connected";
 	}
 	async syncMeta(flock, options) {
-		if (!this.options.metadataRoomId) return { ok: true };
+		if (!this.options.metadataRoomId) {
+			debug("syncMeta skipped; metadata room not configured");
+			return { ok: true };
+		}
+		debug("syncMeta requested", { roomId: this.options.metadataRoomId });
 		try {
 			await withTimeout((await this.ensureMetadataSession(flock, {
 				roomId: this.options.metadataRoomId,
 				auth: this.options.metadataAuth
 			})).firstSynced, options?.timeout);
+			debug("syncMeta completed", { roomId: this.options.metadataRoomId });
 			return { ok: true };
-		} catch {
+		} catch (error) {
+			debug("syncMeta failed", error);
 			return { ok: false };
 		}
 	}
@@ -90,6 +150,10 @@ var WebSocketTransportAdapter = class {
 		const roomId = normalizeRoomId(params?.roomId, fallback);
 		if (!roomId) throw new Error("Metadata room id not configured");
 		const auth = params?.auth ?? this.options.metadataAuth;
+		debug("joinMetaRoom requested", {
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
 		const ensure = this.ensureMetadataSession(flock, {
 			roomId,
 			auth
@@ -100,7 +164,14 @@ var WebSocketTransportAdapter = class {
 			unsubscribe: () => {
 				ensure.then((session) => {
 					session.refCount = Math.max(0, session.refCount - 1);
-					if (session.refCount === 0) this.teardownMetadataSession(session).catch(() => {});
+					debug("metadata session refCount decremented", {
+						roomId: session.roomId,
+						refCount: session.refCount
+					});
+					if (session.refCount === 0) {
+						debug("tearing down metadata session due to refCount=0", { roomId: session.roomId });
+						this.teardownMetadataSession(session).catch(() => {});
+					}
 				});
 			},
 			firstSyncedWithRemote: firstSynced,
@@ -110,18 +181,37 @@ var WebSocketTransportAdapter = class {
 		};
 		ensure.then((session) => {
 			session.refCount += 1;
+			debug("metadata session refCount incremented", {
+				roomId: session.roomId,
+				refCount: session.refCount
+			});
 		});
 		return subscription;
 	}
 	async syncDoc(docId, doc, options) {
+		debug("syncDoc requested", { docId });
 		try {
-			await withTimeout((await this.ensureDocSession(docId, doc, {})).firstSynced, options?.timeout);
+			const session = await this.ensureDocSession(docId, doc, {});
+			await withTimeout(session.firstSynced, options?.timeout);
+			debug("syncDoc completed", {
+				docId,
+				roomId: session.roomId
+			});
 			return { ok: true };
-		} catch {
+		} catch (error) {
+			debug("syncDoc failed", {
+				docId,
+				error
+			});
 			return { ok: false };
 		}
 	}
 	joinDocRoom(docId, doc, params) {
+		debug("joinDocRoom requested", {
+			docId,
+			roomParamType: params?.roomId ? typeof params.roomId === "string" ? "string" : "uint8array" : void 0,
+			hasAuthOverride: Boolean(params?.auth && params.auth.length)
+		});
 		const ensure = this.ensureDocSession(docId, doc, params ?? {});
 		const firstSynced = ensure.then((session) => session.firstSynced);
 		const getConnected = () => this.isConnected();
@@ -129,6 +219,11 @@ var WebSocketTransportAdapter = class {
 			unsubscribe: () => {
 				ensure.then((session) => {
 					session.refCount = Math.max(0, session.refCount - 1);
+					debug("doc session refCount decremented", {
+						docId,
+						roomId: session.roomId,
+						refCount: session.refCount
+					});
 					if (session.refCount === 0) this.leaveDocSession(docId).catch(() => {});
 				});
 			},
@@ -139,12 +234,24 @@ var WebSocketTransportAdapter = class {
 		};
 		ensure.then((session) => {
 			session.refCount += 1;
+			debug("doc session refCount incremented", {
+				docId,
+				roomId: session.roomId,
+				refCount: session.refCount
+			});
 		});
 		return subscription;
 	}
 	ensureClient() {
-		if (this.client) return this.client;
+		if (this.client) {
+			debug("reusing websocket client", { status: this.client.getStatus() });
+			return this.client;
+		}
 		const { url, client: clientOptions } = this.options;
+		debug("creating websocket client", {
+			url,
+			clientOptionsKeys: clientOptions ? Object.keys(clientOptions) : []
+		});
 		const client = new LoroWebsocketClient({
 			url,
 			...clientOptions
@@ -153,22 +260,49 @@ var WebSocketTransportAdapter = class {
 		return client;
 	}
 	async ensureMetadataSession(flock, params) {
+		debug("ensureMetadataSession invoked", {
+			roomId: params.roomId,
+			hasAuth: Boolean(params.auth && params.auth.length)
+		});
 		const client = this.ensureClient();
 		await client.waitConnected();
-		if (this.metadataSession && this.metadataSession.flock === flock && this.metadataSession.roomId === params.roomId && bytesEqual(this.metadataSession.auth, params.auth)) return this.metadataSession;
-		if (this.metadataSession) await this.teardownMetadataSession(this.metadataSession).catch(() => {});
+		debug("websocket client ready for metadata session", { status: client.getStatus() });
+		if (this.metadataSession && this.metadataSession.flock === flock && this.metadataSession.roomId === params.roomId && bytesEqual(this.metadataSession.auth, params.auth)) {
+			debug("reusing metadata session", {
+				roomId: this.metadataSession.roomId,
+				refCount: this.metadataSession.refCount
+			});
+			return this.metadataSession;
+		}
+		if (this.metadataSession) {
+			debug("tearing down previous metadata session", { roomId: this.metadataSession.roomId });
+			await this.teardownMetadataSession(this.metadataSession).catch(() => {});
+		}
 		const configuredType = this.options.metadataCrdtType;
 		if (configuredType && configuredType !== CrdtType.Flock) throw new Error(`metadataCrdtType must be ${CrdtType.Flock} when syncing Flock metadata`);
 		const adaptor = createRepoFlockAdaptorFromDoc(flock, this.options.metadataAdaptorConfig ?? {});
+		debug("joining metadata room", {
+			roomId: params.roomId,
+			hasAuth: Boolean(params.auth && params.auth.length)
+		});
 		const room = await client.join({
 			roomId: params.roomId,
 			crdtAdaptor: adaptor,
 			auth: params.auth
 		});
+		const firstSynced = room.waitForReachingServerVersion();
+		firstSynced.then(() => {
+			debug("metadata session firstSynced resolved", { roomId: params.roomId });
+		}, (error) => {
+			debug("metadata session firstSynced rejected", {
+				roomId: params.roomId,
+				error
+			});
+		});
 		const session = {
 			adaptor,
 			room,
-			firstSynced: room.waitForReachingServerVersion(),
+			firstSynced,
 			flock,
 			roomId: params.roomId,
 			auth: params.auth,
@@ -180,34 +314,83 @@ var WebSocketTransportAdapter = class {
 	async teardownMetadataSession(session) {
 		const target = session ?? this.metadataSession;
 		if (!target) return;
+		debug("teardownMetadataSession invoked", { roomId: target.roomId });
 		if (this.metadataSession === target) this.metadataSession = void 0;
 		const { adaptor, room } = target;
 		try {
 			await room.leave();
-		} catch {
+			debug("metadata room left", { roomId: target.roomId });
+		} catch (error) {
+			debug("metadata room leave failed; destroying", {
+				roomId: target.roomId,
+				error
+			});
 			await room.destroy().catch(() => {});
 		}
 		adaptor.destroy();
+		debug("metadata session destroyed", { roomId: target.roomId });
 	}
 	async ensureDocSession(docId, doc, params) {
+		debug("ensureDocSession invoked", { docId });
 		const client = this.ensureClient();
 		await client.waitConnected();
+		debug("websocket client ready for doc session", {
+			docId,
+			status: client.getStatus()
+		});
 		const existing = this.docSessions.get(docId);
 		const derivedRoomId = this.options.docRoomId?.(docId) ?? docId;
 		const roomId = normalizeRoomId(params.roomId, derivedRoomId);
 		const auth = params.auth ?? this.options.docAuth?.(docId);
-		if (existing && existing.doc === doc && existing.roomId === roomId) return existing;
-		if (existing) await this.leaveDocSession(docId).catch(() => {});
+		debug("doc session params resolved", {
+			docId,
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
+		if (existing && existing.doc === doc && existing.roomId === roomId) {
+			debug("reusing doc session", {
+				docId,
+				roomId,
+				refCount: existing.refCount
+			});
+			return existing;
+		}
+		if (existing) {
+			debug("doc session mismatch; leaving existing session", {
+				docId,
+				previousRoomId: existing.roomId,
+				nextRoomId: roomId
+			});
+			await this.leaveDocSession(docId).catch(() => {});
+		}
 		const adaptor = new LoroAdaptor(doc);
+		debug("joining doc room", {
+			docId,
+			roomId,
+			hasAuth: Boolean(auth && auth.length)
+		});
 		const room = await client.join({
 			roomId,
 			crdtAdaptor: adaptor,
 			auth
 		});
+		const firstSynced = room.waitForReachingServerVersion();
+		firstSynced.then(() => {
+			debug("doc session firstSynced resolved", {
+				docId,
+				roomId
+			});
+		}, (error) => {
+			debug("doc session firstSynced rejected", {
+				docId,
+				roomId,
+				error
+			});
+		});
 		const session = {
 			adaptor,
 			room,
-			firstSynced: room.waitForReachingServerVersion(),
+			firstSynced,
 			doc,
 			roomId,
 			refCount: 0
@@ -217,14 +400,34 @@ var WebSocketTransportAdapter = class {
 	}
 	async leaveDocSession(docId) {
 		const session = this.docSessions.get(docId);
-		if (!session) return;
+		if (!session) {
+			debug("leaveDocSession invoked but no session found", { docId });
+			return;
+		}
 		this.docSessions.delete(docId);
+		debug("leaving doc session", {
+			docId,
+			roomId: session.roomId
+		});
 		try {
 			await session.room.leave();
-		} catch {
+			debug("doc room left", {
+				docId,
+				roomId: session.roomId
+			});
+		} catch (error) {
+			debug("doc room leave failed; destroying", {
+				docId,
+				roomId: session.roomId,
+				error
+			});
 			await session.room.destroy().catch(() => {});
 		}
 		session.adaptor.destroy();
+		debug("doc session destroyed", {
+			docId,
+			roomId: session.roomId
+		});
 	}
 };
 
@@ -929,24 +1132,6 @@ var RepoEventBus = class {
 	}
 };
 
-//#endregion
-//#region src/internal/doc-handle.ts
-var RepoDocHandleImpl = class {
-	doc;
-	whenSyncedWithRemote;
-	docId;
-	onClose;
-	constructor(docId, doc, whenSyncedWithRemote, onClose) {
-		this.docId = docId;
-		this.doc = doc;
-		this.whenSyncedWithRemote = whenSyncedWithRemote;
-		this.onClose = onClose;
-	}
-	async close() {
-		await this.onClose(this.docId, this.doc);
-	}
-};
-
 //#endregion
 //#region src/utils.ts
 async function streamToUint8Array(stream) {
@@ -1109,37 +1294,24 @@ function toReadableStream(bytes) {
 		controller.close();
 	} });
 }
-function emptyFrontiers() {
-	return [];
-}
-function getDocFrontiers(doc) {
-	const candidate = doc;
-	if (typeof candidate.frontiers === "function") {
-		const result = candidate.frontiers();
-		if (result) return result;
-	}
-	return emptyFrontiers();
-}
-function versionVectorToJson(vv) {
-	const map = vv.toJSON();
-	const record = {};
-	if (map instanceof Map) {
-		const entries = Array.from(map.entries()).sort(([a], [b]) => String(a).localeCompare(String(b)));
-		for (const [peer, counter] of entries) {
-			if (typeof counter !== "number" || !Number.isFinite(counter)) continue;
-			const key = typeof peer === "string" ? peer : JSON.stringify(peer);
-			record[key] = counter;
-		}
-	}
-	return record;
-}
-function canonicalizeVersionVector(vv) {
-	const json = versionVectorToJson(vv);
+function canonicalizeFrontiers(frontiers) {
+	const json = [...frontiers].sort((a, b) => {
+		if (a.peer < b.peer) return -1;
+		if (a.peer > b.peer) return 1;
+		return a.counter - b.counter;
+	}).map((f) => ({
+		peer: f.peer,
+		counter: f.counter
+	}));
 	return {
 		json,
 		key: stableStringify(json)
 	};
 }
+function includesFrontiers(vv, frontiers) {
+	for (const { peer, counter } of frontiers) if ((vv.get(peer) ?? 0) <= counter) return false;
+	return true;
+}
 function matchesQuery(docId, _metadata, query) {
 	if (!query) return true;
 	if (query.prefix && !docId.startsWith(query.prefix)) return false;
@@ -1161,14 +1333,12 @@ function logAsyncError(context) {
 //#region src/internal/doc-manager.ts
 var DocManager = class {
 	storage;
-	docFactory;
 	docFrontierDebounceMs;
 	getMetaFlock;
 	eventBus;
 	persistMeta;
 	state;
 	docs = /* @__PURE__ */ new Map();
-	docRefs = /* @__PURE__ */ new Map();
 	docSubscriptions = /* @__PURE__ */ new Map();
 	docFrontierUpdates = /* @__PURE__ */ new Map();
 	docPersistedVersions = /* @__PURE__ */ new Map();
@@ -1177,21 +1347,17 @@ var DocManager = class {
 	}
 	constructor(options) {
 		this.storage = options.storage;
-		this.docFactory = options.docFactory;
 		this.docFrontierDebounceMs = options.docFrontierDebounceMs;
 		this.getMetaFlock = options.getMetaFlock;
 		this.eventBus = options.eventBus;
 		this.persistMeta = options.persistMeta;
 		this.state = options.state;
 	}
-	async openCollaborativeDoc(docId, whenSyncedWithRemote) {
-		const doc = await this.ensureDoc(docId);
-		const refs = this.docRefs.get(docId) ?? 0;
-		this.docRefs.set(docId, refs + 1);
-		return new RepoDocHandleImpl(docId, doc, whenSyncedWithRemote, async () => this.onDocHandleClose(docId, doc));
+	async openCollaborativeDoc(docId) {
+		return await this.ensureDoc(docId);
 	}
 	async openDetachedDoc(docId) {
-		return new RepoDocHandleImpl(docId, await this.materializeDetachedDoc(docId), Promise.resolve(), async () => {});
+		return await this.materializeDetachedDoc(docId);
 	}
 	async ensureDoc(docId) {
 		const cached = this.docs.get(docId);
@@ -1207,7 +1373,7 @@ var DocManager = class {
 				return stored;
 			}
 		}
-		const created = await this.docFactory(docId);
+		const created = new LoroDoc();
 		this.registerDoc(docId, created);
 		return created;
 	}
@@ -1233,27 +1399,42 @@ var DocManager = class {
 		}
 	}
 	async updateDocFrontiers(docId, doc, defaultBy) {
-		const { json, key } = canonicalizeVersionVector(doc.version());
+		const frontiers = doc.oplogFrontiers();
+		const { json, key } = canonicalizeFrontiers(frontiers);
 		const existingKeys = this.docFrontierKeys.get(docId) ?? /* @__PURE__ */ new Set();
 		let mutated = false;
-		if (existingKeys.size !== 1 || !existingKeys.has(key)) {
-			const metaFlock = this.metaFlock;
-			for (const entry of existingKeys) metaFlock.delete([
-				"f",
-				docId,
-				entry
-			]);
+		const metaFlock = this.metaFlock;
+		const vv = doc.version();
+		for (const entry of existingKeys) {
+			if (entry === key) continue;
+			let oldFrontiers;
+			try {
+				oldFrontiers = JSON.parse(entry);
+			} catch {
+				continue;
+			}
+			if (includesFrontiers(vv, oldFrontiers)) {
+				metaFlock.delete([
+					"f",
+					docId,
+					entry
+				]);
+				mutated = true;
+			}
+		}
+		if (!existingKeys.has(key)) {
 			metaFlock.put([
 				"f",
 				docId,
 				key
 			], json);
-			this.docFrontierKeys.set(docId, new Set([key]));
 			mutated = true;
 		}
-		if (mutated) await this.persistMeta();
+		if (mutated) {
+			this.refreshDocFrontierKeys(docId);
+			await this.persistMeta();
+		}
 		const by = this.eventBus.resolveEventBy(defaultBy);
-		const frontiers = getDocFrontiers(doc);
 		this.eventBus.emit({
 			kind: "doc-frontiers",
 			docId,
@@ -1274,20 +1455,33 @@ var DocManager = class {
 		}
 		return true;
 	}
+	async unloadDoc(docId) {
+		const doc = this.docs.get(docId);
+		if (!doc) return;
+		await this.flushScheduledDocFrontierUpdate(docId);
+		await this.persistDocUpdate(docId, doc);
+		await this.updateDocFrontiers(docId, doc, "local");
+		this.docSubscriptions.get(docId)?.();
+		this.docSubscriptions.delete(docId);
+		this.docs.delete(docId);
+		this.docPersistedVersions.delete(docId);
+	}
+	async flush() {
+		const promises$1 = [];
+		for (const [docId, doc] of this.docs) promises$1.push((async () => {
+			await this.persistDocUpdate(docId, doc);
+			await this.flushScheduledDocFrontierUpdate(docId);
+		})());
+		await Promise.all(promises$1);
+	}
 	async close() {
+		await this.flush();
 		for (const unsubscribe of this.docSubscriptions.values()) try {
 			unsubscribe();
 		} catch {}
 		this.docSubscriptions.clear();
-		const pendingDocIds = Array.from(this.docFrontierUpdates.keys());
-		for (const docId of pendingDocIds) try {
-			await this.flushScheduledDocFrontierUpdate(docId);
-		} catch (error) {
-			logAsyncError(`doc ${docId} frontier flush on close`)(error);
-		}
 		this.docFrontierUpdates.clear();
 		this.docs.clear();
-		this.docRefs.clear();
 		this.docPersistedVersions.clear();
 		this.docFrontierKeys.clear();
 	}
@@ -1311,6 +1505,7 @@ var DocManager = class {
 		const keys = /* @__PURE__ */ new Set();
 		for (const row of rows) {
 			if (!Array.isArray(row.key) || row.key.length < 3) continue;
+			if (row.value === void 0 || row.value === null) continue;
 			const frontierKey = row.key[2];
 			if (typeof frontierKey === "string") keys.add(frontierKey);
 		}
@@ -1365,22 +1560,10 @@ var DocManager = class {
 			}
 		})().catch(logAsyncError(`doc ${docId} frontier debounce`));
 	}
-	async onDocHandleClose(docId, doc) {
-		const refs = this.docRefs.get(docId) ?? 0;
-		if (refs <= 1) {
-			this.docRefs.delete(docId);
-			this.docSubscriptions.get(docId)?.();
-			this.docSubscriptions.delete(docId);
-			this.docs.delete(docId);
-			this.docPersistedVersions.delete(docId);
-		} else this.docRefs.set(docId, refs - 1);
-		await this.persistDocUpdate(docId, doc);
-		if (!await this.flushScheduledDocFrontierUpdate(docId)) await this.updateDocFrontiers(docId, doc, "local");
-	}
 	async materializeDetachedDoc(docId) {
 		const snapshot = await this.exportDocSnapshot(docId);
 		if (snapshot) return LoroDoc.fromSnapshot(snapshot);
-		return this.docFactory(docId);
+		return new LoroDoc();
 	}
 	async exportDocSnapshot(docId) {
 		const cached = this.docs.get(docId);
@@ -1390,7 +1573,7 @@ var DocManager = class {
 	}
 	async persistDocUpdate(docId, doc) {
 		const previousVersion = this.docPersistedVersions.get(docId);
-		const nextVersion = doc.version();
+		const nextVersion = doc.oplogVersion();
 		if (!this.storage) {
 			this.docPersistedVersions.set(docId, nextVersion);
 			return;
@@ -1400,14 +1583,11 @@ var DocManager = class {
 			this.docPersistedVersions.set(docId, nextVersion);
 			return;
 		}
+		if (previousVersion.compare(nextVersion) === 0) return;
 		const update = doc.export({
 			mode: "update",
 			from: previousVersion
 		});
-		if (!update.length) {
-			this.docPersistedVersions.set(docId, nextVersion);
-			return;
-		}
 		this.docPersistedVersions.set(docId, nextVersion);
 		try {
 			await this.storage.save({
@@ -1429,7 +1609,14 @@ var DocManager = class {
 				return;
 			}
 			const flushed = this.flushScheduledDocFrontierUpdate(docId);
-			const updated = this.updateDocFrontiers(docId, doc, by);
+			const updated = (async () => {
+				this.eventBus.pushEventBy(by);
+				try {
+					await this.updateDocFrontiers(docId, doc, by);
+				} finally {
+					this.eventBus.popEventBy();
+				}
+			})();
 			await Promise.all([
 				persist,
 				flushed,
@@ -1462,17 +1649,38 @@ var MetadataManager = class {
 		const metadata = this.state.metadata.get(docId);
 		return metadata ? cloneJsonObject(metadata) : void 0;
 	}
-	list(query) {
+	listDoc(query) {
+		if (query?.limit !== void 0 && query.limit <= 0) return [];
+		const { startKey, endKey } = this.computeDocRangeKeys(query);
+		if (startKey && endKey && startKey >= endKey) return [];
+		const scanOptions = { prefix: ["m"] };
+		if (startKey) scanOptions.start = {
+			kind: "inclusive",
+			key: ["m", startKey]
+		};
+		if (endKey) scanOptions.end = {
+			kind: "exclusive",
+			key: ["m", endKey]
+		};
+		const rows = this.metaFlock.scan(scanOptions);
+		const seen = /* @__PURE__ */ new Set();
 		const entries = [];
-		for (const [docId, metadata] of this.state.metadata.entries()) {
+		for (const row of rows) {
+			if (query?.limit !== void 0 && entries.length >= query.limit) break;
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const docId = row.key[1];
+			if (typeof docId !== "string") continue;
+			if (seen.has(docId)) continue;
+			seen.add(docId);
+			const metadata = this.state.metadata.get(docId);
+			if (!metadata) continue;
 			if (!matchesQuery(docId, metadata, query)) continue;
 			entries.push({
 				docId,
 				meta: cloneJsonObject(metadata)
 			});
+			if (query?.limit !== void 0 && entries.length >= query.limit) break;
 		}
-		entries.sort((a, b) => a.docId < b.docId ? -1 : a.docId > b.docId ? 1 : 0);
-		if (query?.limit !== void 0) return entries.slice(0, query.limit);
 		return entries;
 	}
 	async upsert(docId, patch) {
@@ -1566,6 +1774,26 @@ var MetadataManager = class {
 	clear() {
 		this.state.metadata.clear();
 	}
+	computeDocRangeKeys(query) {
+		if (!query) return {};
+		const prefix = query.prefix && query.prefix.length > 0 ? query.prefix : void 0;
+		let startKey = query.start;
+		if (prefix) startKey = !startKey || prefix > startKey ? prefix : startKey;
+		let endKey = query.end;
+		const prefixEnd = this.nextLexicographicString(prefix);
+		if (prefixEnd) endKey = !endKey || prefixEnd < endKey ? prefixEnd : endKey;
+		return {
+			startKey,
+			endKey
+		};
+	}
+	nextLexicographicString(value) {
+		if (!value) return void 0;
+		for (let i = value.length - 1; i >= 0; i -= 1) {
+			const code = value.charCodeAt(i);
+			if (code < 65535) return `${value.slice(0, i)}${String.fromCharCode(code + 1)}`;
+		}
+	}
 	readDocMetadataFromFlock(docId) {
 		const rows = this.metaFlock.scan({ prefix: ["m", docId] });
 		if (!rows.length) return void 0;
@@ -2304,6 +2532,9 @@ var FlockHydrator = class {
 
 //#endregion
 //#region src/internal/sync-runner.ts
+/**
+* Sync data between storage and transport layer
+*/
 var SyncRunner = class {
 	storage;
 	transport;
@@ -2318,6 +2549,7 @@ var SyncRunner = class {
 	readyPromise;
 	metaRoomSubscription;
 	unsubscribeMetaFlock;
+	docSubscriptions = /* @__PURE__ */ new Map();
 	constructor(options) {
 		this.storage = options.storage;
 		this.transport = options.transport;
@@ -2327,7 +2559,7 @@ var SyncRunner = class {
 		this.assetManager = options.assetManager;
 		this.flockHydrator = options.flockHydrator;
 		this.getMetaFlock = options.getMetaFlock;
-		this.replaceMetaFlock = options.replaceMetaFlock;
+		this.replaceMetaFlock = options.mergeFlock;
 		this.persistMeta = options.persistMeta;
 	}
 	async ready() {
@@ -2404,15 +2636,30 @@ var SyncRunner = class {
 		await this.ready();
 		if (!this.transport) throw new Error("Transport adapter not configured");
 		if (!this.transport.isConnected()) await this.transport.connect();
+		const existing = this.docSubscriptions.get(docId);
+		if (existing) return existing;
 		const doc = await this.docManager.ensureDoc(docId);
 		const subscription = this.transport.joinDocRoom(docId, doc, params);
+		const wrapped = {
+			unsubscribe: () => {
+				subscription.unsubscribe();
+				if (this.docSubscriptions.get(docId) === wrapped) this.docSubscriptions.delete(docId);
+			},
+			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
+			get connected() {
+				return subscription.connected;
+			}
+		};
+		this.docSubscriptions.set(docId, wrapped);
 		subscription.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
-		return subscription;
+		return wrapped;
 	}
-	async close() {
+	async destroy() {
 		await this.docManager.close();
 		this.metaRoomSubscription?.unsubscribe();
 		this.metaRoomSubscription = void 0;
+		for (const sub of this.docSubscriptions.values()) sub.unsubscribe();
+		this.docSubscriptions.clear();
 		if (this.unsubscribeMetaFlock) {
 			this.unsubscribeMetaFlock();
 			this.unsubscribeMetaFlock = void 0;
@@ -2463,16 +2710,17 @@ function createRepoState() {
 //#region src/index.ts
 const textEncoder = new TextEncoder();
 const DEFAULT_DOC_FRONTIER_DEBOUNCE_MS = 1e3;
-var LoroRepo = class {
+var LoroRepo = class LoroRepo {
 	options;
+	_destroyed = false;
 	transport;
 	storage;
-	docFactory;
 	metaFlock = new Flock();
 	eventBus;
 	docManager;
 	metadataManager;
 	assetManager;
+	assetTransport;
 	flockHydrator;
 	state;
 	syncRunner;
@@ -2480,14 +2728,13 @@ var LoroRepo = class {
 		this.options = options;
 		this.transport = options.transportAdapter;
 		this.storage = options.storageAdapter;
-		this.docFactory = options.docFactory ?? (async () => new LoroDoc());
+		this.assetTransport = options.assetTransportAdapter;
 		this.eventBus = new RepoEventBus();
 		this.state = createRepoState();
 		const configuredDebounce = options.docFrontierDebounceMs;
 		const docFrontierDebounceMs = typeof configuredDebounce === "number" && Number.isFinite(configuredDebounce) && configuredDebounce >= 0 ? configuredDebounce : DEFAULT_DOC_FRONTIER_DEBOUNCE_MS;
 		this.docManager = new DocManager({
 			storage: this.storage,
-			docFactory: this.docFactory,
 			docFrontierDebounceMs,
 			getMetaFlock: () => this.metaFlock,
 			eventBus: this.eventBus,
@@ -2502,7 +2749,7 @@ var LoroRepo = class {
 		});
 		this.assetManager = new AssetManager({
 			storage: this.storage,
-			assetTransport: options.assetTransportAdapter,
+			assetTransport: this.assetTransport,
 			getMetaFlock: () => this.metaFlock,
 			eventBus: this.eventBus,
 			persistMeta: () => this.persistMeta(),
@@ -2523,96 +2770,133 @@ var LoroRepo = class {
 			assetManager: this.assetManager,
 			flockHydrator: this.flockHydrator,
 			getMetaFlock: () => this.metaFlock,
-			replaceMetaFlock: (snapshot) => {
-				this.metaFlock = snapshot;
+			mergeFlock: (snapshot) => {
+				this.metaFlock.merge(snapshot);
 			},
 			persistMeta: () => this.persistMeta()
 		});
 	}
+	static async create(options) {
+		const repo = new LoroRepo(options);
+		await repo.storage?.init?.();
+		await repo.ready();
+		return repo;
+	}
+	/**
+	* Load meta from storage.
+	* 
+	* You need to call this before all other operations to make the app functioning correctly.
+	* Though we do that implicitly already
+	*/
 	async ready() {
 		await this.syncRunner.ready();
 	}
+	/**
+	* Sync selected data via the transport adaptor
+	* @param options 
+	*/
 	async sync(options = {}) {
 		await this.syncRunner.sync(options);
 	}
+	/**
+	* Start syncing the metadata (Flock) room. It will establish a realtime connection to the transport adaptor.
+	* All changes on the room will be synced to the Flock, and all changes on the Flock will be synced to the room.
+	* @param params 
+	* @returns 
+	*/
 	async joinMetaRoom(params) {
 		return this.syncRunner.joinMetaRoom(params);
 	}
+	/**
+	* Start syncing the given doc. It will establish a realtime connection to the transport adaptor.
+	* All changes on the doc will be synced to the transport, and all changes on the transport will be synced to the doc.
+	* 
+	* All the changes on the room will be reflected on the same doc you get from `repo.openCollaborativeDoc(docId)`
+	* @param docId 
+	* @param params 
+	* @returns 
+	*/
 	async joinDocRoom(docId, params) {
 		return this.syncRunner.joinDocRoom(docId, params);
 	}
-	async close() {
-		await this.syncRunner.close();
+	/**
+	* Opens a document that is automatically persisted to the configured storage adapter.
+	* 
+	* - Edits are saved to storage (debounced).
+	* - Frontiers are synced to the metadata (Flock).
+	* - Realtime collaboration is NOT enabled by default; use `joinDocRoom` to connect.
+	*/
+	async openPersistedDoc(docId) {
+		return {
+			doc: await this.docManager.openCollaborativeDoc(docId),
+			syncOnce: () => {
+				return this.sync({
+					scope: "doc",
+					docIds: [docId]
+				});
+			},
+			joinRoom: (auth) => {
+				return this.syncRunner.joinDocRoom(docId, { auth });
+			}
+		};
 	}
-	async upsertDocMeta(docId, patch, _options = {}) {
-		await this.ready();
+	async upsertDocMeta(docId, patch) {
 		await this.metadataManager.upsert(docId, patch);
 	}
 	async getDocMeta(docId) {
-		await this.ready();
 		return this.metadataManager.get(docId);
 	}
 	async listDoc(query) {
-		await this.ready();
-		return this.metadataManager.list(query);
+		return this.metadataManager.listDoc(query);
 	}
-	getMetaReplica() {
+	getMeta() {
 		return this.metaFlock;
 	}
 	watch(listener, filter = {}) {
 		return this.eventBus.watch(listener, filter);
 	}
 	/**
-	* Opens the repo-managed collaborative document, registers it for persistence,
-	* and schedules a doc-level sync so `whenSyncedWithRemote` resolves after remote backfills.
+	* Opens a detached `LoroDoc` snapshot.
+	* 
+	* - **No Persistence**: Edits to this document are NOT saved to storage.
+	* - **No Sync**: This document does not participate in realtime updates.
+	* - **Use Case**: Ideal for read-only history inspection, temporary drafts, or conflict resolution without affecting the main state.
 	*/
-	async openCollaborativeDoc(docId) {
-		await this.ready();
-		const whenSyncedWithRemote = this.whenDocInSyncWithRemote(docId);
-		return this.docManager.openCollaborativeDoc(docId, whenSyncedWithRemote);
+	async openDetachedDoc(docId) {
+		return this.docManager.openDetachedDoc(docId);
 	}
 	/**
-	* Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
-	* it neither participates in remote subscriptions nor persists edits back to storage.
+	* Explicitly unloads a document from memory.
+	* 
+	* - **Persists Immediately**: Forces a save of the document's current state to storage.
+	* - **Frees Memory**: Removes the document from the internal cache.
+	* - **Note**: If the document is currently being synced (via `joinDocRoom`), you should also unsubscribe from the room to fully release resources.
 	*/
-	async openDetachedDoc(docId) {
-		await this.ready();
-		return this.docManager.openDetachedDoc(docId);
+	async unloadDoc(docId) {
+		await this.docManager.unloadDoc(docId);
+	}
+	async flush() {
+		await this.docManager.flush();
 	}
 	async uploadAsset(params) {
-		await this.ready();
 		return this.assetManager.uploadAsset(params);
 	}
-	async whenDocInSyncWithRemote(docId) {
-		await this.ready();
-		await this.docManager.ensureDoc(docId);
-		await this.sync({
-			scope: "doc",
-			docIds: [docId]
-		});
-	}
 	async linkAsset(docId, params) {
-		await this.ready();
 		return this.assetManager.linkAsset(docId, params);
 	}
 	async fetchAsset(assetId) {
-		await this.ready();
 		return this.assetManager.fetchAsset(assetId);
 	}
 	async unlinkAsset(docId, assetId) {
-		await this.ready();
 		await this.assetManager.unlinkAsset(docId, assetId);
 	}
 	async listAssets(docId) {
-		await this.ready();
 		return this.assetManager.listAssets(docId);
 	}
 	async ensureAsset(assetId) {
-		await this.ready();
 		return this.assetManager.ensureAsset(assetId);
 	}
 	async gcAssets(options = {}) {
-		await this.ready();
 		return this.assetManager.gcAssets(options);
 	}
 	async persistMeta() {
@@ -2624,6 +2908,17 @@ var LoroRepo = class {
 			update: encoded
 		});
 	}
+	get destroyed() {
+		return this._destroyed;
+	}
+	async destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		await this.syncRunner.destroy();
+		this.assetTransport?.close?.();
+		this.storage?.close?.();
+		await this.transport?.close();
+	}
 };
 
 //#endregion