loro-repo 0.5.3 → 0.6.0

package/README.md

@@ -69,8 +69,23 @@ Adapters are shipped as subpath exports so the default `loro-repo` entry stays h
     url: "wss://sync.example.com/repo",
     metadataRoomId: "workspace:meta",
     docAuth: (docId) => authFor(docId),
+    onStatusChange: (status) => setConnectionBadge(status),
+    onRoomStatusChange: ({ roomId, status }) =>
+      console.info(`room ${roomId} -> ${status}`),
   });
+
+  // Force an immediate reconnect (resets backoff) when the UI exposes a retry button.
+  await transport.reconnect({ resetBackoff: true });
+
+  // Per-room status callbacks surface reconnect cycles: connecting | joined | reconnecting | disconnected | error.
+  const live = await repo.joinDocRoom("doc:123", {
+    onStatusChange: (status) => setRoomState(status),
+  });
+  // Subscriptions also expose status + onStatusChange hooks:
+  live.onStatusChange((status) => setRoomBadge(status));
+  console.log(live.status); // e.g. "joined"
   ```
+  Auto-reconnect (via `loro-websocket@0.5.0`) is enabled by default with exponential backoff (0.5s → 15s + jitter), pings to detect half-open sockets, offline pause/resume, and automatic rejoin of previously joined rooms. Observe the lifecycle through `onStatusChange` (adapter-level), `onRoomStatusChange` (all rooms), or per-join `onStatusChange` callbacks; feed ping RTTs to telemetry with `onLatency`. Manual controls: `connect({ resetBackoff })` to restart after a fatal close and `reconnect()` / `reconnect({ resetBackoff: true })` to trigger a retry immediately. Frames now use the loro-protocol v1 format (introduced in `loro-protocol@0.3.x`), so your server endpoint must speak the v1 WebSocket dialect.
 
 - `IndexedDBStorageAdaptor` (`src/storage/indexeddb.ts`)  
   Browser storage for metadata snapshots, doc snapshots/updates, and cached assets. Swap it out for SQLite/LevelDB/file-system adaptors when running on desktop or server environments. Import via `loro-repo/storage/indexeddb`.
@@ -90,7 +105,7 @@ Adapters are shipped as subpath exports so the default `loro-repo` entry stays h
 
 **Metadata**
 - `await repo.upsertDocMeta(docId, patch)` – LWW merge with your `Meta` type.
-- `await repo.getDocMeta(docId)` – clone the stored metadata (or `undefined`).
+- `await repo.getDocMeta(docId)` – resolve to `{ meta, deletedAtMs? }` for the stored doc (or `undefined` when it doesn’t exist).
 - `await repo.listDoc(query?)` – list docs by prefix/range/limit (`RepoDocMeta<Meta>[]`).
 - `repo.getMeta()` – access raw `Flock` if you need advanced scans.
 
@@ -101,6 +116,13 @@ Adapters are shipped as subpath exports so the default `loro-repo` entry stays h
 - `await repo.unloadDoc(docId)` – flush pending work for a doc and evict it from memory.
 - `await repo.flush()` – persist all loaded docs and flush pending frontier updates.
 
+**Deletion & retention**
+- Tombstoning is explicit and enforced: tombstoned docs stay visible, readable, and joinable; a configurable retention window (default 30 days) governs when they can be purged.
+- `await repo.deleteDoc(docId, { deletedAt?, force? })` – soft-delete by writing a tombstone (`ts/*`); repeats are no-ops unless `force: true` overwrites the timestamp.
+- `await repo.restoreDoc(docId)` – remove the tombstone so the doc can be opened again (idempotent when not deleted).
+- `await repo.purgeDoc(docId)` – hard-delete immediately: removes doc bodies, metadata/frontiers, tombstone, and doc→asset links; emits unlink + metadata clear events.
+- `await repo.gcDeletedDocs({ minKeepMs?, now? })` – sweep tombstoned docs whose retention window expired; returns the count purged.
+
 **Assets**
 - `await repo.linkAsset(docId, { content, mime?, tag?, policy?, assetId?, createdAt? })` – upload + link, returning the SHA-256 assetId.
 - `await repo.uploadAsset(options)` – upload without linking to a doc (pre-warm caches).
@@ -116,6 +138,23 @@ Adapters are shipped as subpath exports so the default `loro-repo` entry stays h
 **Realtime metadata**
 - `await repo.joinMetaRoom(params?)` – opt into live metadata sync via the transport adapter; call `subscription.unsubscribe()` to leave.
 
+### Doc deletion lifecycle (soft vs. hard)
+
+The repo separates logical deletion from storage reclamation so UIs stay responsive while bytes are cleaned up safely:
+
+1) **Soft delete (safe delete)** — `deleteDoc` writes a tombstone at `ts/<docId>` but keeps metadata (`m/*`), frontiers (`f/*`), doc snapshots/updates, and asset links intact. Tombstoned docs remain readable and joinable; the tombstone is a visibility/retention hint, not an access ban. UIs can still surface the doc (often with a “deleted” badge) and choose whether to join the room. Watchers see `doc-soft-deleted` events with provenance (`by: "local" | "sync" | "live"`).
+
+2) **Retention window** — A tombstoned doc waits for `deletedDocKeepMs` (default 30 days; configurable when creating the repo). Run `gcDeletedDocs()` periodically (or pass `{ minKeepMs, now }`) to purge anything past its keep window; each purge internally calls `purgeDoc`.
+
+3) **Hard delete (`purgeDoc` / `gcDeletedDocs`)** — Removes all local state and triggers storage deletion when supported:
+   - Clears metadata/frontiers/link rows (`m/*`, `f/*`, `ld/*`) and the tombstone from the Flock.
+   - `DocManager.dropDoc` evicts cached docs and calls `storage.deleteDoc` (FileSystem/IndexedDB adaptors delete the snapshot plus pending updates).
+   - Asset links are removed; assets that become orphaned are marked, and `gcAssets` later removes the binary via `storage.deleteAsset` once its own keep window elapses.
+
+4) **Remote purge propagation** — If a sync/live event shows a peer cleared doc metadata (empty `doc-metadata` patch) or removed the tombstone while no metadata remains, `handlePurgeSignals` invokes `dropDoc` locally. This keeps your storage aligned with the authoritative replica even if you never called `purgeDoc` yourself.
+
+5) **What does *not* delete storage** — Soft delete alone never removes bytes. `unloadDoc` only flushes snapshots; it does not delete them. Storage reclaim happens only through `purgeDoc`, `gcDeletedDocs`, or the remote-purge path described above.
+
 ## Commands
 
 | Command | Purpose |