loro-repo 0.5.3 → 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;
@@ -177,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 () => {
@@ -504,13 +516,44 @@ var MetadataManager = class {
 		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 [];
@@ -525,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) {
@@ -556,11 +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;
 			this.metaFlock.put([
 				"m",
 				docId,
-				storageKey
+				key
 			], rawValue);
 			next[key] = rawValue;
 			outPatch[key] = rawValue;
@@ -579,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",
@@ -593,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,
@@ -611,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);
@@ -631,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;
@@ -656,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);
@@ -672,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();
@@ -921,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 [];
@@ -1269,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;
@@ -1285,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);
@@ -1297,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();
@@ -1306,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
@@ -1385,7 +1603,7 @@ 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");
 			} finally {
 				unsubscribe();
@@ -1411,62 +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);
 		}).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();
@@ -1486,7 +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.flockHydrator.applyEvents(batch.events, by);
 			})().catch(logAsyncError("meta live monitor sync"));
 		});
 	}
@@ -1592,14 +1853,10 @@ var MetaPersister = class {
 			this.forceFullOnNextFlush = false;
 			return;
 		}
-		try {
-			await this.storage.save({
-				type: "meta",
-				update: encoded
-			});
-		} catch (error) {
-			throw error;
-		}
+		await this.storage.save({
+			type: "meta",
+			update: encoded
+		});
 		this.lastPersistedVersion = currentVersion;
 		this.forceFullOnNextFlush = false;
 	}
@@ -1657,6 +1914,7 @@ var MetaPersister = class {
 //#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;
@@ -1672,6 +1930,8 @@ var LoroRepo = class LoroRepo {
 	state;
 	syncRunner;
 	metaPersister;
+	deletedDocKeepMs;
+	purgeWatchHandle;
 	constructor(options) {
 		this.options = options;
 		this.transport = options.transportAdapter;
@@ -1681,6 +1941,8 @@ 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,
@@ -1723,6 +1985,10 @@ var LoroRepo = class LoroRepo {
 				this.metaFlock.merge(snapshot);
 			}
 		});
+		this.purgeWatchHandle = this.eventBus.watch((event) => this.handlePurgeSignals(event), {
+			kinds: ["doc-soft-deleted", "doc-metadata"],
+			by: ["sync", "live"]
+		});
 	}
 	static async create(options) {
 		const repo = new LoroRepo(options);
@@ -1740,6 +2006,18 @@ var LoroRepo = class LoroRepo {
 		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
 	* @param options 
@@ -1750,6 +2028,10 @@ 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 
 	*/
@@ -1760,6 +2042,10 @@ var LoroRepo = class LoroRepo {
 			get connected() {
 				return subscription.connected;
 			},
+			get status() {
+				return subscription.status;
+			},
+			onStatusChange: subscription.onStatusChange,
 			firstSyncedWithRemote: subscription.firstSyncedWithRemote.then(async () => {
 				await this.metaPersister.flushNow();
 			})
@@ -1770,12 +2056,36 @@ var LoroRepo = class LoroRepo {
 	* 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.
@@ -1807,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;
 	}
@@ -1864,12 +2229,29 @@ var LoroRepo = class LoroRepo {
 	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