loro-repo 0.5.2 → 0.6.0

package/dist/index.cjs

@@ -40,7 +40,7 @@ var RepoEventBus = class {
 		if (filter.kinds && !filter.kinds.includes(event.kind)) return false;
 		if (filter.by && !filter.by.includes(event.by)) return false;
 		const docId = (() => {
-			if (event.kind === "doc-metadata" || event.kind === "doc-frontiers") return event.docId;
+			if (event.kind === "doc-metadata" || event.kind === "doc-frontiers" || event.kind === "doc-soft-deleted" || event.kind === "doc-purging") return event.docId;
 			if (event.kind === "asset-link" || event.kind === "asset-unlink") return event.docId;
 		})();
 		if (filter.docIds && docId && !filter.docIds.includes(docId)) return false;
@@ -68,7 +68,6 @@ var DocManager = class {
 	docFrontierDebounceMs;
 	getMetaFlock;
 	eventBus;
-	persistMeta;
 	docs = /* @__PURE__ */ new Map();
 	docSubscriptions = /* @__PURE__ */ new Map();
 	docFrontierUpdates = /* @__PURE__ */ new Map();
@@ -78,7 +77,6 @@ var DocManager = class {
 		this.docFrontierDebounceMs = options.docFrontierDebounceMs;
 		this.getMetaFlock = options.getMetaFlock;
 		this.eventBus = options.eventBus;
-		this.persistMeta = options.persistMeta;
 	}
 	async openPersistedDoc(docId) {
 		return await this.ensureDoc(docId);
@@ -139,16 +137,13 @@ var DocManager = class {
 			], f.counter);
 			mutated = true;
 		}
-		if (mutated) {
-			for (const [peer, counter] of existingFrontiers) {
-				const docCounterEnd = vv.get(peer);
-				if (docCounterEnd != null && docCounterEnd > counter) metaFlock.delete([
-					"f",
-					docId,
-					peer
-				]);
-			}
-			await this.persistMeta();
+		if (mutated) for (const [peer, counter] of existingFrontiers) {
+			const docCounterEnd = vv.get(peer);
+			if (docCounterEnd != null && docCounterEnd > counter) metaFlock.delete([
+				"f",
+				docId,
+				peer
+			]);
 		}
 		const by = this.eventBus.resolveEventBy(defaultBy);
 		this.eventBus.emit({
@@ -182,6 +177,18 @@ var DocManager = class {
 		this.docs.delete(docId);
 		this.docPersistedVersions.delete(docId);
 	}
+	async dropDoc(docId) {
+		const pending = this.docFrontierUpdates.get(docId);
+		if (pending) {
+			clearTimeout(pending.timeout);
+			this.docFrontierUpdates.delete(docId);
+		}
+		this.docSubscriptions.get(docId)?.();
+		this.docSubscriptions.delete(docId);
+		this.docs.delete(docId);
+		this.docPersistedVersions.delete(docId);
+		if (this.storage?.deleteDoc) await this.storage.deleteDoc(docId);
+	}
 	async flush() {
 		const promises = [];
 		for (const [docId, doc] of this.docs) promises.push((async () => {
@@ -502,22 +509,51 @@ function matchesQuery(docId, _metadata, query) {
 var MetadataManager = class {
 	getMetaFlock;
 	eventBus;
-	persistMeta;
 	state;
 	constructor(options) {
 		this.getMetaFlock = options.getMetaFlock;
 		this.eventBus = options.eventBus;
-		this.persistMeta = options.persistMeta;
 		this.state = options.state;
 	}
 	getDocIds() {
-		return Array.from(this.state.metadata.keys());
+		const ids = new Set(this.state.metadata.keys());
+		const tombstoneRows = this.metaFlock.scan({ prefix: ["ts"] });
+		for (const row of tombstoneRows) {
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const docId = row.key[1];
+			if (typeof docId === "string") ids.add(docId);
+		}
+		return Array.from(ids);
 	}
 	entries() {
 		return this.state.metadata.entries();
 	}
 	get(docId) {
-		return this.state.metadata.get(docId);
+		const metadata = this.state.metadata.get(docId);
+		const deletedAtMs = this.readDeletedAtFromFlock(docId);
+		if (deletedAtMs === void 0 && this.isDocKeyspaceEmpty(docId) || !metadata || deletedAtMs === void 0 && this.isEmpty(metadata)) {
+			if (deletedAtMs === void 0) return void 0;
+			return {
+				meta: {},
+				deletedAtMs
+			};
+		}
+		return {
+			meta: cloneJsonObject(metadata),
+			deletedAtMs
+		};
+	}
+	getDeletedAtMs(docId) {
+		return this.readDeletedAtFromFlock(docId);
+	}
+	markDeleted(docId, deletedAtMs) {
+		this.metaFlock.put(["ts", docId], deletedAtMs);
+		this.emitSoftDeleted(docId, deletedAtMs, "local");
+	}
+	clearDeleted(docId) {
+		const existing = this.readDeletedAtFromFlock(docId);
+		this.metaFlock.delete(["ts", docId]);
+		if (existing !== void 0) this.emitSoftDeleted(docId, void 0, "local");
 	}
 	listDoc(query) {
 		if (query?.limit !== void 0 && query.limit <= 0) return [];
@@ -532,25 +568,49 @@ var MetadataManager = class {
 			kind: "exclusive",
 			key: ["m", endKey]
 		};
-		const rows = this.metaFlock.scan(scanOptions);
 		const seen = /* @__PURE__ */ new Set();
 		const entries = [];
+		const pushDoc = (docId) => {
+			if (seen.has(docId)) return;
+			const metadata = this.state.metadata.get(docId);
+			const deletedAtMs = this.readDeletedAtFromFlock(docId);
+			if (deletedAtMs === void 0 && this.isDocKeyspaceEmpty(docId) || this.isEmpty(metadata) && deletedAtMs === void 0) return;
+			if (!matchesQuery(docId, metadata ?? {}, query)) return;
+			seen.add(docId);
+			entries.push({
+				docId,
+				deletedAtMs,
+				meta: cloneJsonObject(metadata ?? {})
+			});
+		};
+		const rows = this.metaFlock.scan(scanOptions);
 		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)
-			});
+			pushDoc(docId);
 			if (query?.limit !== void 0 && entries.length >= query.limit) break;
 		}
+		if (query?.limit === void 0 || entries.length < query.limit) {
+			const tsScan = { prefix: ["ts"] };
+			if (startKey) tsScan.start = {
+				kind: "inclusive",
+				key: ["ts", startKey]
+			};
+			if (endKey) tsScan.end = {
+				kind: "exclusive",
+				key: ["ts", endKey]
+			};
+			const tsRows = this.metaFlock.scan(tsScan);
+			for (const row of tsRows) {
+				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;
+				pushDoc(docId);
+			}
+		}
 		return entries;
 	}
 	async upsert(docId, patch) {
@@ -563,12 +623,10 @@ var MetadataManager = class {
 			const rawValue = patchObject[key];
 			if (rawValue === void 0) continue;
 			if (jsonEquals(base ? base[key] : void 0, rawValue)) continue;
-			const storageKey = key === "tombstone" ? "$tombstone" : key;
-			console.log("upserting", rawValue);
 			this.metaFlock.put([
 				"m",
 				docId,
-				storageKey
+				key
 			], rawValue);
 			next[key] = rawValue;
 			outPatch[key] = rawValue;
@@ -579,7 +637,6 @@ var MetadataManager = class {
 			return;
 		}
 		this.state.metadata.set(docId, next);
-		await this.persistMeta();
 		this.eventBus.emit({
 			kind: "doc-metadata",
 			docId,
@@ -588,10 +645,10 @@ var MetadataManager = class {
 		});
 	}
 	refreshFromFlock(docId, by) {
-		const previous = this.state.metadata.get(docId);
-		const next = this.readDocMetadataFromFlock(docId);
-		if (!next) {
-			if (previous) {
+		const previousMeta = this.state.metadata.get(docId);
+		const nextMeta = this.readDocMetadataFromFlock(docId);
+		if (!nextMeta) {
+			if (previousMeta) {
 				this.state.metadata.delete(docId);
 				this.eventBus.emit({
 					kind: "doc-metadata",
@@ -602,9 +659,9 @@ var MetadataManager = class {
 			}
 			return;
 		}
-		this.state.metadata.set(docId, next);
-		const patch = diffJsonObjects(previous, next);
-		if (!previous || Object.keys(patch).length > 0) this.eventBus.emit({
+		this.state.metadata.set(docId, nextMeta);
+		const patch = diffJsonObjects(previousMeta, nextMeta);
+		if (!previousMeta || Object.keys(patch).length > 0) this.eventBus.emit({
 			kind: "doc-metadata",
 			docId,
 			patch,
@@ -620,12 +677,16 @@ var MetadataManager = class {
 			const previous = prevMetadata.get(docId);
 			const current = nextMetadata.get(docId);
 			if (!current) {
-				if (previous) this.eventBus.emit({
-					kind: "doc-metadata",
-					docId,
-					patch: {},
-					by
-				});
+				if (previous) {
+					const patch$1 = {};
+					for (const key of Object.keys(previous)) patch$1[key] = null;
+					this.eventBus.emit({
+						kind: "doc-metadata",
+						docId,
+						patch: patch$1,
+						by
+					});
+				}
 				continue;
 			}
 			const patch = diffJsonObjects(previous, current);
@@ -640,6 +701,22 @@ var MetadataManager = class {
 	clear() {
 		this.state.metadata.clear();
 	}
+	purgeMetadata(docId, by) {
+		if (this.state.metadata.delete(docId)) this.eventBus.emit({
+			kind: "doc-metadata",
+			docId,
+			patch: {},
+			by
+		});
+	}
+	emitSoftDeleted(docId, deletedAtMs, by) {
+		this.eventBus.emit({
+			kind: "doc-soft-deleted",
+			docId,
+			deletedAtMs,
+			by
+		});
+	}
 	computeDocRangeKeys(query) {
 		if (!query) return {};
 		const prefix = query.prefix && query.prefix.length > 0 ? query.prefix : void 0;
@@ -665,7 +742,9 @@ var MetadataManager = class {
 		if (!rows.length) return void 0;
 		const docMeta = {};
 		let populated = false;
+		let sawRow = false;
 		for (const row of rows) {
+			sawRow = true;
 			if (!Array.isArray(row.key) || row.key.length < 2) continue;
 			if (row.key.length === 2) {
 				const obj = asJsonObject(row.value);
@@ -681,17 +760,33 @@ var MetadataManager = class {
 			}
 			const fieldKey = row.key[2];
 			if (typeof fieldKey !== "string") continue;
-			if (fieldKey === "$tombstone") {
-				docMeta.tombstone = Boolean(row.value);
-				populated = true;
-				continue;
-			}
 			const jsonValue = cloneJsonValue(row.value);
 			if (jsonValue === void 0) continue;
 			docMeta[fieldKey] = jsonValue;
 			populated = true;
 		}
-		return populated ? docMeta : void 0;
+		if (populated) return docMeta;
+		if (sawRow) return {};
+	}
+	readDeletedAtFromFlock(docId) {
+		const raw = this.metaFlock.get(["ts", docId]);
+		if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+	}
+	isEmpty(metadata) {
+		return !metadata || Object.keys(metadata).length === 0;
+	}
+	isDocKeyspaceEmpty(docId) {
+		if (this.state.metadata.has(docId)) return false;
+		const hasTruthyKey = (prefix) => {
+			const rows = this.metaFlock.scan({ prefix });
+			for (const row of rows) if (row.value !== void 0) return true;
+			return false;
+		};
+		if (this.metaFlock.get(["ts", docId]) !== void 0) return false;
+		if (hasTruthyKey(["m", docId])) return false;
+		if (hasTruthyKey(["f", docId])) return false;
+		if (hasTruthyKey(["ld", docId])) return false;
+		return true;
 	}
 	get metaFlock() {
 		return this.getMetaFlock();
@@ -705,7 +800,6 @@ var AssetManager = class {
 	assetTransport;
 	getMetaFlock;
 	eventBus;
-	persistMeta;
 	state;
 	get docAssets() {
 		return this.state.docAssets;
@@ -724,7 +818,6 @@ var AssetManager = class {
 		this.assetTransport = options.assetTransport;
 		this.getMetaFlock = options.getMetaFlock;
 		this.eventBus = options.eventBus;
-		this.persistMeta = options.persistMeta;
 		this.state = options.state;
 	}
 	async uploadAsset(params) {
@@ -761,7 +854,6 @@ var AssetManager = class {
 			if (metadataMutated) {
 				existing.metadata = metadata$1;
 				this.metaFlock.put(["a", assetId], assetMetaToJson(metadata$1));
-				await this.persistMeta();
 				this.eventBus.emit({
 					kind: "asset-metadata",
 					asset: this.createAssetDownload(assetId, metadata$1, bytes),
@@ -798,7 +890,6 @@ var AssetManager = class {
 		this.markAssetAsOrphan(assetId, metadata);
 		this.updateDocAssetMetadata(assetId, metadata);
 		this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
-		await this.persistMeta();
 		this.eventBus.emit({
 			kind: "asset-metadata",
 			asset: this.createAssetDownload(assetId, metadata, storedBytes),
@@ -857,7 +948,6 @@ var AssetManager = class {
 				existing.metadata = nextMetadata;
 				metadata = nextMetadata;
 				this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
-				await this.persistMeta();
 				this.eventBus.emit({
 					kind: "asset-metadata",
 					asset: this.createAssetDownload(assetId, metadata, bytes),
@@ -904,7 +994,6 @@ var AssetManager = class {
 			docId,
 			assetId
 		], true);
-		await this.persistMeta();
 		this.eventBus.emit({
 			kind: "asset-link",
 			docId,
@@ -929,7 +1018,6 @@ var AssetManager = class {
 			assetId
 		]);
 		this.removeDocAssetReference(assetId, docId);
-		await this.persistMeta();
 		this.eventBus.emit({
 			kind: "asset-unlink",
 			docId,
@@ -937,6 +1025,11 @@ var AssetManager = class {
 			by: "local"
 		});
 	}
+	purgeDocLinks(docId, by) {
+		const keys = Array.from(this.metaFlock.scan({ prefix: ["ld", docId] }), (row) => row.key);
+		for (const key of keys) this.metaFlock.delete(key);
+		this.refreshDocAssetsEntry(docId, by);
+	}
 	async listAssets(docId) {
 		const mapping = this.docAssets.get(docId);
 		if (!mapping) return [];
@@ -1213,7 +1306,6 @@ var AssetManager = class {
 		this.assets.set(assetId, { metadata });
 		this.updateDocAssetMetadata(assetId, metadata);
 		this.metaFlock.put(["a", assetId], assetMetaToJson(metadata));
-		await this.persistMeta();
 		if (this.storage) await this.storage.save({
 			type: "asset",
 			assetId,
@@ -1286,14 +1378,35 @@ var FlockHydrator = class {
 		this.docManager = options.docManager;
 	}
 	hydrateAll(by) {
-		const nextMetadata = this.readAllDocMetadata();
-		this.metadataManager.replaceAll(nextMetadata, by);
+		const { metadata, tombstones } = this.readAllDocMetadata();
+		this.metadataManager.replaceAll(metadata, by);
+		for (const [docId, deletedAtMs] of tombstones) this.metadataManager.emitSoftDeleted(docId, deletedAtMs, by);
 		this.assetManager.hydrateFromFlock(by);
+		const docIds = new Set([
+			...metadata.keys(),
+			...tombstones.keys(),
+			...this.collectDocIds(["f"]),
+			...this.collectDocIds(["ld"])
+		]);
+		for (const docId of docIds) if (this.isDocKeyspaceEmpty(docId)) (async () => {
+			try {
+				this.clearDocKeyspace(docId);
+				this.metadataManager.purgeMetadata(docId, by);
+				await this.docManager.dropDoc(docId);
+			} catch (error) {
+				console.error("Failed to drop purged doc during hydrateAll", {
+					docId,
+					error
+				});
+			}
+		})();
 	}
-	applyEvents(events, by) {
+	async applyEvents(events, by) {
 		if (!events.length) return;
 		const docMetadataIds = /* @__PURE__ */ new Set();
+		const docTombstoneIds = /* @__PURE__ */ new Map();
 		const docAssetIds = /* @__PURE__ */ new Set();
+		const docFrontierIds = /* @__PURE__ */ new Set();
 		const assetIds = /* @__PURE__ */ new Set();
 		for (const event of events) {
 			const key = event.key;
@@ -1302,6 +1415,12 @@ var FlockHydrator = class {
 			if (root === "m") {
 				const docId = key[1];
 				if (typeof docId === "string") docMetadataIds.add(docId);
+			} else if (root === "f") {
+				const docId = key[1];
+				if (typeof docId === "string") docFrontierIds.add(docId);
+			} else if (root === "ts") {
+				const docId = key[1];
+				if (typeof docId === "string") docTombstoneIds.set(docId, this.toDeletedAt(event.value));
 			} else if (root === "a") {
 				const assetId = key[1];
 				if (typeof assetId === "string") assetIds.add(assetId);
@@ -1314,7 +1433,38 @@ var FlockHydrator = class {
 		}
 		for (const assetId of assetIds) this.assetManager.refreshAssetMetadataEntry(assetId, by);
 		for (const docId of docMetadataIds) this.metadataManager.refreshFromFlock(docId, by);
+		for (const [docId, deletedAtMs] of docTombstoneIds) this.metadataManager.emitSoftDeleted(docId, deletedAtMs, by);
 		for (const docId of docAssetIds) this.assetManager.refreshDocAssetsEntry(docId, by);
+		const docIdsToCheck = new Set([
+			...docMetadataIds,
+			...docTombstoneIds.keys(),
+			...docAssetIds,
+			...docFrontierIds
+		]);
+		for (const docId of docIdsToCheck) if (this.isDocKeyspaceEmpty(docId)) try {
+			this.clearDocKeyspace(docId);
+			this.metadataManager.purgeMetadata(docId, by);
+			await this.docManager.dropDoc(docId);
+		} catch (error) {
+			console.error("Failed to drop purged doc during hydration", {
+				docId,
+				error
+			});
+		}
+		for (const docId of docIdsToCheck) {
+			const snapshot = this.metadataManager.get(docId);
+			const tombstone = this.metaFlock.get(["ts", docId]);
+			if (!snapshot && tombstone === void 0) try {
+				this.clearDocKeyspace(docId);
+				this.metadataManager.purgeMetadata(docId, by);
+				await this.docManager.dropDoc(docId);
+			} catch (error) {
+				console.error("Failed to drop purged doc after refresh", {
+					docId,
+					error
+				});
+			}
+		}
 	}
 	readAllDocMetadata() {
 		const nextMetadata = /* @__PURE__ */ new Map();
@@ -1323,35 +1473,86 @@ var FlockHydrator = class {
 			if (!Array.isArray(row.key) || row.key.length < 2) continue;
 			const docId = row.key[1];
 			if (typeof docId !== "string") continue;
-			let docMeta = nextMetadata.get(docId);
-			if (!docMeta) {
-				docMeta = {};
-				nextMetadata.set(docId, docMeta);
-			}
+			if (row.value === void 0 && !this.metadataManager.get(docId)) continue;
 			if (row.key.length === 2) {
 				const obj = asJsonObject(row.value);
 				if (!obj) continue;
+				let docMeta$1 = nextMetadata.get(docId);
+				if (!docMeta$1) {
+					docMeta$1 = {};
+					nextMetadata.set(docId, docMeta$1);
+				}
 				for (const [field, value] of Object.entries(obj)) {
 					const cloned = cloneJsonValue(value);
-					if (cloned !== void 0) docMeta[field] = cloned;
+					if (cloned !== void 0) docMeta$1[field] = cloned;
 				}
 				continue;
 			}
 			const fieldKey = row.key[2];
 			if (typeof fieldKey !== "string") continue;
-			if (fieldKey === "$tombstone") {
-				docMeta.tombstone = Boolean(row.value);
-				continue;
-			}
 			const jsonValue = cloneJsonValue(row.value);
 			if (jsonValue === void 0) continue;
+			let docMeta = nextMetadata.get(docId);
+			if (!docMeta) {
+				docMeta = {};
+				nextMetadata.set(docId, docMeta);
+			}
 			docMeta[fieldKey] = jsonValue;
 		}
-		return nextMetadata;
+		const tombstones = /* @__PURE__ */ new Map();
+		const tombstoneRows = this.metaFlock.scan({ prefix: ["ts"] });
+		for (const row of tombstoneRows) {
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const docId = row.key[1];
+			if (typeof docId !== "string") continue;
+			const tombstone = cloneJsonValue(row.value);
+			if (typeof tombstone === "number" && Number.isFinite(tombstone)) tombstones.set(docId, tombstone);
+		}
+		return {
+			metadata: nextMetadata,
+			tombstones
+		};
+	}
+	toDeletedAt(value) {
+		return typeof value === "number" && Number.isFinite(value) ? value : void 0;
 	}
 	get metaFlock() {
 		return this.getMetaFlock();
 	}
+	isDocKeyspaceEmpty(docId) {
+		if (this.metaFlock.get(["ts", docId]) !== void 0) return false;
+		if (this.hasTruthyKey(["m", docId])) return false;
+		if (this.hasTruthyKey(["f", docId])) return false;
+		if (this.hasTruthyKey(["ld", docId])) return false;
+		return true;
+	}
+	hasTruthyKey(prefix) {
+		const rows = this.metaFlock.scan({ prefix });
+		for (const row of rows) if (row.value !== void 0) return true;
+		return false;
+	}
+	collectDocIds(prefix) {
+		const ids = /* @__PURE__ */ new Set();
+		const rows = this.metaFlock.scan({ prefix });
+		for (const row of rows) {
+			if (!Array.isArray(row.key) || row.key.length < 2) continue;
+			const docId = row.key[1];
+			if (typeof docId === "string") ids.add(docId);
+		}
+		return ids;
+	}
+	clearDocKeyspace(docId) {
+		const prefixes = [
+			["m", docId],
+			["f", docId],
+			["ld", docId]
+		];
+		for (const prefix of prefixes) {
+			const rows = this.metaFlock.scan({ prefix });
+			for (const row of rows) this.metaFlock.delete(row.key);
+		}
+		this.metaFlock.delete(["ts", docId]);
+	}
 };
 
 //#endregion
@@ -1369,7 +1570,6 @@ var SyncRunner = class {
 	flockHydrator;
 	getMetaFlock;
 	replaceMetaFlock;
-	persistMeta;
 	readyPromise;
 	metaRoomSubscription;
 	unsubscribeMetaFlock;
@@ -1384,7 +1584,6 @@ var SyncRunner = class {
 		this.flockHydrator = options.flockHydrator;
 		this.getMetaFlock = options.getMetaFlock;
 		this.replaceMetaFlock = options.mergeFlock;
-		this.persistMeta = options.persistMeta;
 	}
 	async ready() {
 		if (!this.readyPromise) this.readyPromise = this.initialize();
@@ -1404,9 +1603,8 @@ var SyncRunner = class {
 			});
 			try {
 				if (!(await this.transport.syncMeta(this.metaFlock)).ok) throw new Error("Metadata sync failed");
-				if (recordedEvents.length > 0) this.flockHydrator.applyEvents(recordedEvents, "sync");
+				if (recordedEvents.length > 0) await this.flockHydrator.applyEvents(recordedEvents, "sync");
 				else this.flockHydrator.hydrateAll("sync");
-				await this.persistMeta();
 			} finally {
 				unsubscribe();
 				this.eventBus.popEventBy();
@@ -1431,63 +1629,105 @@ var SyncRunner = class {
 		await this.ready();
 		if (!this.transport) throw new Error("Transport adapter not configured");
 		if (!this.transport.isConnected()) await this.transport.connect();
-		if (this.metaRoomSubscription) return this.metaRoomSubscription;
+		const existing = this.metaRoomSubscription;
+		if (existing) {
+			existing.refCount += 1;
+			return this.createMetaLease(existing);
+		}
 		this.ensureMetaLiveMonitor();
-		const subscription = this.transport.joinMetaRoom(this.metaFlock, params);
-		const wrapped = {
-			unsubscribe: () => {
-				subscription.unsubscribe();
-				if (this.metaRoomSubscription === wrapped) this.metaRoomSubscription = void 0;
-				if (this.unsubscribeMetaFlock) {
-					this.unsubscribeMetaFlock();
-					this.unsubscribeMetaFlock = void 0;
-				}
-			},
-			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
-			get connected() {
-				return subscription.connected;
-			}
+		const base = this.transport.joinMetaRoom(this.metaFlock, params);
+		const record = {
+			base,
+			refCount: 1
 		};
-		this.metaRoomSubscription = wrapped;
-		subscription.firstSyncedWithRemote.then(async () => {
+		this.metaRoomSubscription = record;
+		base.firstSyncedWithRemote.then(async () => {
 			const by = this.eventBus.resolveEventBy("live");
 			this.flockHydrator.hydrateAll(by);
-			await this.persistMeta();
 		}).catch(logAsyncError("meta room first sync"));
-		return wrapped;
+		return this.createMetaLease(record);
 	}
 	async joinDocRoom(docId, params) {
 		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;
+		if (existing) {
+			existing.refCount += 1;
+			return this.createDocLease(docId, existing);
+		}
 		const doc = await this.docManager.ensureDoc(docId);
-		const subscription = this.transport.joinDocRoom(docId, doc, params);
-		const wrapped = {
+		const base = this.transport.joinDocRoom(docId, doc, params);
+		const record = {
+			base,
+			refCount: 1
+		};
+		this.docSubscriptions.set(docId, record);
+		base.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
+		return this.createDocLease(docId, record);
+	}
+	createMetaLease(record) {
+		let released = false;
+		return {
 			unsubscribe: () => {
-				subscription.unsubscribe();
-				if (this.docSubscriptions.get(docId) === wrapped) this.docSubscriptions.delete(docId);
+				if (released) return;
+				released = true;
+				const current = this.metaRoomSubscription;
+				if (!current || current !== record) return;
+				current.refCount = Math.max(0, current.refCount - 1);
+				if (current.refCount === 0) {
+					current.base.unsubscribe();
+					this.metaRoomSubscription = void 0;
+					if (this.unsubscribeMetaFlock) {
+						this.unsubscribeMetaFlock();
+						this.unsubscribeMetaFlock = void 0;
+					}
+				}
 			},
-			firstSyncedWithRemote: subscription.firstSyncedWithRemote,
+			firstSyncedWithRemote: record.base.firstSyncedWithRemote,
 			get connected() {
-				return subscription.connected;
-			}
+				return record.base.connected;
+			},
+			get status() {
+				return record.base.status;
+			},
+			onStatusChange: record.base.onStatusChange
+		};
+	}
+	createDocLease(docId, record) {
+		let released = false;
+		return {
+			unsubscribe: () => {
+				if (released) return;
+				released = true;
+				const current = this.docSubscriptions.get(docId);
+				if (!current || current !== record) return;
+				current.refCount = Math.max(0, current.refCount - 1);
+				if (current.refCount === 0) {
+					current.base.unsubscribe();
+					if (this.docSubscriptions.get(docId) === current) this.docSubscriptions.delete(docId);
+				}
+			},
+			firstSyncedWithRemote: record.base.firstSyncedWithRemote,
+			get connected() {
+				return record.base.connected;
+			},
+			get status() {
+				return record.base.status;
+			},
+			onStatusChange: record.base.onStatusChange
 		};
-		this.docSubscriptions.set(docId, wrapped);
-		subscription.firstSyncedWithRemote.catch(logAsyncError(`doc ${docId} first sync`));
-		return wrapped;
 	}
 	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;
+		if (this.metaRoomSubscription) {
+			this.metaRoomSubscription.base.unsubscribe();
+			this.metaRoomSubscription = void 0;
 		}
+		for (const record of this.docSubscriptions.values()) record.base.unsubscribe();
+		this.docSubscriptions.clear();
+		this.unsubscribeMetaFlock?.();
+		this.unsubscribeMetaFlock = void 0;
 		this.eventBus.clear();
 		this.metadataManager.clear();
 		this.assetManager.clear();
@@ -1507,8 +1747,7 @@ var SyncRunner = class {
 			if (batch.source === "local") return;
 			const by = this.eventBus.resolveEventBy("live");
 			(async () => {
-				this.flockHydrator.applyEvents(batch.events, by);
-				await this.persistMeta();
+				await this.flockHydrator.applyEvents(batch.events, by);
 			})().catch(logAsyncError("meta live monitor sync"));
 		});
 	}
@@ -1530,9 +1769,152 @@ function createRepoState() {
 }
 
 //#endregion
-//#region src/index.ts
+//#region src/internal/meta-persister.ts
 const textEncoder = new TextEncoder();
+const DEFAULT_META_PERSIST_DEBOUNCE_MS = 5e3;
+var MetaPersister = class {
+	getMetaFlock;
+	storage;
+	debounceMs;
+	lastPersistedVersion;
+	unsubscribe;
+	flushPromise = Promise.resolve();
+	flushTimer;
+	forceFullOnNextFlush = false;
+	destroyed = false;
+	constructor(options) {
+		this.getMetaFlock = options.getMetaFlock;
+		this.storage = options.storage;
+		const configuredDebounce = options.debounceMs;
+		this.debounceMs = typeof configuredDebounce === "number" && Number.isFinite(configuredDebounce) && configuredDebounce >= 0 ? configuredDebounce : DEFAULT_META_PERSIST_DEBOUNCE_MS;
+	}
+	start(initialVersion) {
+		this.lastPersistedVersion = initialVersion;
+		if (this.unsubscribe) return;
+		this.unsubscribe = this.metaFlock.subscribe(() => {
+			this.scheduleFlush();
+		});
+	}
+	async destroy() {
+		this.destroyed = true;
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		if (this.unsubscribe) {
+			this.unsubscribe();
+			this.unsubscribe = void 0;
+		}
+		await this.flushNow();
+	}
+	async flushNow(forceFull = false) {
+		if (this.flushTimer) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = void 0;
+		}
+		await this.flush(forceFull);
+	}
+	scheduleFlush() {
+		if (this.destroyed) return;
+		if (this.debounceMs === 0) {
+			this.flush();
+			return;
+		}
+		if (this.flushTimer) clearTimeout(this.flushTimer);
+		this.flushTimer = setTimeout(() => {
+			this.flushTimer = void 0;
+			this.flush();
+		}, this.debounceMs);
+	}
+	async flush(forceFull = false) {
+		if (forceFull) this.forceFullOnNextFlush = true;
+		const run = this.flushPromise.catch(() => {}).then(() => this.flushInternal());
+		this.flushPromise = run;
+		await run;
+	}
+	async flushInternal() {
+		const flock = this.metaFlock;
+		const currentVersion = flock.version();
+		if (this.lastPersistedVersion && this.versionsEqual(currentVersion, this.lastPersistedVersion)) {
+			this.forceFullOnNextFlush = false;
+			return;
+		}
+		const baseline = this.forceFullOnNextFlush ? void 0 : this.lastPersistedVersion;
+		const rawBundle = baseline ? flock.exportJson(baseline) : flock.exportJson();
+		const bundle = baseline ? this.stripUnchangedEntries(rawBundle, baseline) : rawBundle;
+		if (Object.keys(bundle.entries).length === 0) {
+			this.forceFullOnNextFlush = false;
+			this.lastPersistedVersion = currentVersion;
+			return;
+		}
+		const encoded = textEncoder.encode(JSON.stringify(bundle));
+		if (!this.storage) {
+			this.lastPersistedVersion = currentVersion;
+			this.forceFullOnNextFlush = false;
+			return;
+		}
+		await this.storage.save({
+			type: "meta",
+			update: encoded
+		});
+		this.lastPersistedVersion = currentVersion;
+		this.forceFullOnNextFlush = false;
+	}
+	get metaFlock() {
+		return this.getMetaFlock();
+	}
+	stripUnchangedEntries(bundle, baseline) {
+		const entries = {};
+		for (const [key, record] of Object.entries(bundle.entries)) {
+			const clock = this.parseClock(record.c);
+			if (!clock) {
+				entries[key] = record;
+				continue;
+			}
+			const baselineEntry = baseline[clock.peerIdHex];
+			if (!baselineEntry) {
+				entries[key] = record;
+				continue;
+			}
+			if (clock.physicalTime > baselineEntry.physicalTime || clock.physicalTime === baselineEntry.physicalTime && clock.logicalCounter > baselineEntry.logicalCounter) entries[key] = record;
+		}
+		return {
+			version: bundle.version,
+			entries
+		};
+	}
+	parseClock(raw) {
+		if (typeof raw !== "string") return void 0;
+		const [physicalTimeStr, logicalCounterStr, peerIdHex] = raw.split(",");
+		if (!physicalTimeStr || !logicalCounterStr || !peerIdHex) return void 0;
+		const physicalTime = Number(physicalTimeStr);
+		const logicalCounter = Number(logicalCounterStr);
+		if (!Number.isFinite(physicalTime) || !Number.isFinite(logicalCounter)) return void 0;
+		return {
+			physicalTime,
+			logicalCounter,
+			peerIdHex
+		};
+	}
+	versionsEqual(a, b) {
+		if (!a || !b) return false;
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys.length !== bKeys.length) return false;
+		for (const key of aKeys) {
+			const aEntry = a[key];
+			const bEntry = b[key];
+			if (!aEntry || !bEntry) return false;
+			if (aEntry.physicalTime !== bEntry.physicalTime || aEntry.logicalCounter !== bEntry.logicalCounter) return false;
+		}
+		return true;
+	}
+};
+
+//#endregion
+//#region src/index.ts
 const DEFAULT_DOC_FRONTIER_DEBOUNCE_MS = 1e3;
+const DEFAULT_DELETED_DOC_KEEP_MS = 720 * 60 * 60 * 1e3;
 var LoroRepo = class LoroRepo {
 	options;
 	_destroyed = false;
@@ -1547,6 +1929,9 @@ var LoroRepo = class LoroRepo {
 	flockHydrator;
 	state;
 	syncRunner;
+	metaPersister;
+	deletedDocKeepMs;
+	purgeWatchHandle;
 	constructor(options) {
 		this.options = options;
 		this.transport = options.transportAdapter;
@@ -1556,17 +1941,17 @@ var LoroRepo = class LoroRepo {
 		this.state = createRepoState();
 		const configuredDebounce = options.docFrontierDebounceMs;
 		const docFrontierDebounceMs = typeof configuredDebounce === "number" && Number.isFinite(configuredDebounce) && configuredDebounce >= 0 ? configuredDebounce : DEFAULT_DOC_FRONTIER_DEBOUNCE_MS;
+		const configuredDeletedKeepMs = options.deletedDocKeepMs;
+		this.deletedDocKeepMs = typeof configuredDeletedKeepMs === "number" && Number.isFinite(configuredDeletedKeepMs) && configuredDeletedKeepMs >= 0 ? configuredDeletedKeepMs : DEFAULT_DELETED_DOC_KEEP_MS;
 		this.docManager = new DocManager({
 			storage: this.storage,
 			docFrontierDebounceMs,
 			getMetaFlock: () => this.metaFlock,
-			eventBus: this.eventBus,
-			persistMeta: () => this.persistMeta()
+			eventBus: this.eventBus
 		});
 		this.metadataManager = new MetadataManager({
 			getMetaFlock: () => this.metaFlock,
 			eventBus: this.eventBus,
-			persistMeta: () => this.persistMeta(),
 			state: this.state
 		});
 		this.assetManager = new AssetManager({
@@ -1574,9 +1959,13 @@ var LoroRepo = class LoroRepo {
 			assetTransport: this.assetTransport,
 			getMetaFlock: () => this.metaFlock,
 			eventBus: this.eventBus,
-			persistMeta: () => this.persistMeta(),
 			state: this.state
 		});
+		this.metaPersister = new MetaPersister({
+			getMetaFlock: () => this.metaFlock,
+			storage: this.storage,
+			debounceMs: options.metaPersistDebounceMs
+		});
 		this.flockHydrator = new FlockHydrator({
 			getMetaFlock: () => this.metaFlock,
 			metadataManager: this.metadataManager,
@@ -1594,8 +1983,11 @@ var LoroRepo = class LoroRepo {
 			getMetaFlock: () => this.metaFlock,
 			mergeFlock: (snapshot) => {
 				this.metaFlock.merge(snapshot);
-			},
-			persistMeta: () => this.persistMeta()
+			}
+		});
+		this.purgeWatchHandle = this.eventBus.watch((event) => this.handlePurgeSignals(event), {
+			kinds: ["doc-soft-deleted", "doc-metadata"],
+			by: ["sync", "live"]
 		});
 	}
 	static async create(options) {
@@ -1612,6 +2004,19 @@ var LoroRepo = class LoroRepo {
 	*/
 	async ready() {
 		await this.syncRunner.ready();
+		this.metaPersister.start(this.metaFlock.version());
+	}
+	computeDocPurgeAfter(docId, minKeepMs) {
+		const deletedAt = this.metadataManager.getDeletedAtMs(docId);
+		if (deletedAt === void 0) return void 0;
+		return deletedAt + minKeepMs;
+	}
+	purgeDocKeyspace(docId) {
+		const metadataKeys = Array.from(this.metaFlock.scan({ prefix: ["m", docId] }), (row) => row.key);
+		for (const key of metadataKeys) this.metaFlock.delete(key);
+		const frontierKeys = Array.from(this.metaFlock.scan({ prefix: ["f", docId] }), (row) => row.key);
+		for (const key of frontierKeys) this.metaFlock.delete(key);
+		this.metaFlock.delete(["ts", docId]);
 	}
 	/**
 	* Sync selected data via the transport adaptor
@@ -1623,23 +2028,64 @@ var LoroRepo = class LoroRepo {
 	/**
 	* 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.
+	*
+	* - Idempotent: repeated calls reuse the same underlying room session; no extra join request is sent for the same repo.
+	* - Reference-counted leave: every call to `joinMetaRoom` returns a subscription that increments an internal counter. The room is
+	*   actually left only after all returned subscriptions have called `unsubscribe`.
 	* @param params 
 	* @returns 
 	*/
 	async joinMetaRoom(params) {
-		return this.syncRunner.joinMetaRoom(params);
+		const subscription = await this.syncRunner.joinMetaRoom(params);
+		return {
+			unsubscribe: subscription.unsubscribe,
+			get connected() {
+				return subscription.connected;
+			},
+			get status() {
+				return subscription.status;
+			},
+			onStatusChange: subscription.onStatusChange,
+			firstSyncedWithRemote: subscription.firstSyncedWithRemote.then(async () => {
+				await this.metaPersister.flushNow();
+			})
+		};
 	}
 	/**
 	* 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)`
+	*
+	* - Idempotent: multiple joins for the same `docId` reuse the existing session; no duplicate transport joins are issued.
+	* - Reference-counted leave: each returned subscription bumps an internal counter and only the final `unsubscribe()` will
+	*   actually leave the room. Earlier unsubscribes simply decrement the counter.
 	* @param docId 
 	* @param params 
 	* @returns 
 	*/
 	async joinDocRoom(docId, params) {
-		return this.syncRunner.joinDocRoom(docId, params);
+		const subscription = await this.syncRunner.joinDocRoom(docId, params);
+		return {
+			...subscription,
+			onStatusChange: subscription.onStatusChange,
+			status: subscription.status
+		};
+	}
+	/**
+	* Joins an ephemeral CRDT room. This is useful for presence-like state that should not be persisted.
+	* The returned store can be used immediately; the first sync promise resolves once the initial handshake completes.
+	*/
+	async joinEphemeralRoom(roomId) {
+		if (!this.transport) throw new Error("Transport adapter not configured");
+		await this.syncRunner.ready();
+		if (!this.transport.isConnected()) await this.transport.connect();
+		const subscription = this.transport.joinEphemeralRoom(roomId);
+		return {
+			...subscription,
+			onStatusChange: subscription.onStatusChange,
+			status: subscription.status
+		};
 	}
 	/**
 	* Opens a document that is automatically persisted to the configured storage adapter.
@@ -1671,6 +2117,61 @@ var LoroRepo = class LoroRepo {
 	async listDoc(query) {
 		return this.metadataManager.listDoc(query);
 	}
+	/**
+	* Mark a document deleted by writing a `ts/*` tombstone entry (timestamp).
+	* The body and metadata remain until purged; callers use the tombstone to
+	* render deleted state or trigger retention workflows. For immediate removal,
+	* call `purgeDoc` instead.
+	*/
+	async deleteDoc(docId, options = {}) {
+		if (this.metadataManager.getDeletedAtMs(docId) !== void 0 && !options.force) return;
+		const deletedAt = options.deletedAt ?? Date.now();
+		this.metadataManager.markDeleted(docId, deletedAt);
+	}
+	/**
+	* Undo a soft delete by removing the tombstone entry. Metadata and document
+	* state remain untouched.
+	*/
+	async restoreDoc(docId) {
+		if (this.metadataManager.getDeletedAtMs(docId) === void 0) return;
+		this.metadataManager.clearDeleted(docId);
+	}
+	/**
+	* Hard-delete a document immediately. Removes doc snapshots/updates via the
+	* storage adapter (if supported), clears metadata/frontiers/link keys from
+	* Flock, and unlinks assets (they become orphaned for asset GC).
+	*/
+	async purgeDoc(docId) {
+		const deletedAtMs = this.metadataManager.getDeletedAtMs(docId);
+		this.eventBus.emit({
+			kind: "doc-purging",
+			docId,
+			deletedAtMs,
+			by: "local"
+		});
+		await this.docManager.dropDoc(docId);
+		this.assetManager.purgeDocLinks(docId, "local");
+		this.purgeDocKeyspace(docId);
+		this.metadataManager.emitSoftDeleted(docId, void 0, "local");
+		this.metadataManager.refreshFromFlock(docId, "local");
+	}
+	/**
+	* Sweep tombstoned documents whose retention window expired. Uses
+	* `deletedDocKeepMs` by default; pass `minKeepMs`/`now` for overrides.
+	*/
+	async gcDeletedDocs(options = {}) {
+		const now = options.now ?? Date.now();
+		const minKeepMs = options.minKeepMs ?? this.deletedDocKeepMs;
+		const docIds = this.metadataManager.getDocIds();
+		let purged = 0;
+		for (const docId of docIds) {
+			const purgeAfter = this.computeDocPurgeAfter(docId, minKeepMs);
+			if (purgeAfter === void 0 || now < purgeAfter) continue;
+			await this.purgeDoc(docId);
+			purged += 1;
+		}
+		return purged;
+	}
 	getMeta() {
 		return this.metaFlock;
 	}
@@ -1699,6 +2200,7 @@ var LoroRepo = class LoroRepo {
 	}
 	async flush() {
 		await this.docManager.flush();
+		await this.metaPersister.flushNow();
 	}
 	async uploadAsset(params) {
 		return this.assetManager.uploadAsset(params);
@@ -1721,26 +2223,35 @@ var LoroRepo = class LoroRepo {
 	async gcAssets(options = {}) {
 		return this.assetManager.gcAssets(options);
 	}
-	async persistMeta() {
-		if (!this.storage) return;
-		const bundle = this.metaFlock.exportJson();
-		const encoded = textEncoder.encode(JSON.stringify(bundle));
-		await this.storage.save({
-			type: "meta",
-			update: encoded
-		});
-	}
 	get destroyed() {
 		return this._destroyed;
 	}
 	async destroy() {
 		if (this._destroyed) return;
 		this._destroyed = true;
+		this.purgeWatchHandle.unsubscribe();
+		await this.metaPersister.destroy();
 		await this.syncRunner.destroy();
 		this.assetTransport?.close?.();
 		this.storage?.close?.();
 		await this.transport?.close();
 	}
+	handlePurgeSignals(event) {
+		const docId = (() => {
+			if (event.kind === "doc-soft-deleted") return event.docId;
+			if (event.kind === "doc-metadata") return event.docId;
+		})();
+		if (!docId) return;
+		const metadataCleared = event.kind === "doc-metadata" && Object.keys(event.patch).length === 0;
+		const tombstoneCleared = event.kind === "doc-soft-deleted" && event.deletedAtMs === void 0;
+		if (!(metadataCleared || tombstoneCleared && this.metadataManager.get(docId) === void 0)) return;
+		this.docManager.dropDoc(docId).catch((error) => {
+			console.error("Failed to drop purged doc", {
+				docId,
+				error
+			});
+		});
+	}
 };
 
 //#endregion