loro-repo 0.5.3 → 0.6.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
-import { A as TransportSyncResult, C as StorageAdapter, D as TransportJoinParams, E as TransportAdapter, O as TransportSubscription, S as RepoWatchHandle, T as SyncScope, _ as RepoEventFilter, a as AssetUploadMetadata, b as RepoEventType, c as JsonValue, d as LoroRepoOptions, f as RepoAssetMetadata, g as RepoEventBy, h as RepoEvent, i as AssetTransportAdapter, j as UploadAssetOptions, k as TransportSyncRequest, l as LinkAssetOptions, m as RepoDocMeta, n as AssetDownload, o as GarbageCollectionOptions, p as RepoDocHandle, r as AssetId, s as JsonObject, t as AssetContent, u as ListDocQuery, v as RepoEventKind, w as StorageSavePayload, x as RepoSyncOptions, y as RepoEventListener } from "./types.cjs";
+import { A as TransportConnectionStatus, C as RepoEventType, D as StorageSavePayload, E as StorageAdapter, F as TransportSyncResult, I as UploadAssetOptions, M as TransportRoomStatus, N as TransportSubscription, O as SyncScope, P as TransportSyncRequest, S as RepoEventListener, T as RepoWatchHandle, _ as RepoDocSnapshot, a as AssetUploadMetadata, b as RepoEventFilter, c as GcDeletedDocOptions, d as LinkAssetOptions, f as ListDocQuery, g as RepoDocMeta, h as RepoDocHandle, i as AssetTransportAdapter, j as TransportJoinParams, k as TransportAdapter, l as JsonObject, m as RepoAssetMetadata, n as AssetDownload, o as DeleteDocOptions, p as LoroRepoOptions, r as AssetId, s as GarbageCollectionOptions, t as AssetContent, u as JsonValue, v as RepoEvent, w as RepoSyncOptions, x as RepoEventKind, y as RepoEventBy } from "./types.cjs";
 import { Flock } from "@loro-dev/flock";
-import { LoroDoc } from "loro-crdt";
+import { EphemeralStore, LoroDoc } from "loro-crdt";
 
 //#region src/index.d.ts
 declare class LoroRepo<Meta extends JsonObject = JsonObject> {
@@ -18,6 +18,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   private readonly state;
   private readonly syncRunner;
   private readonly metaPersister;
+  private readonly deletedDocKeepMs;
+  private readonly purgeWatchHandle;
   private constructor();
   static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions): Promise<LoroRepo<Meta>>;
   /**
@@ -27,6 +29,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    * Though we do that implicitly already
    */
   private ready;
+  private computeDocPurgeAfter;
+  private purgeDocKeyspace;
   /**
    * Sync selected data via the transport adaptor
    * @param options
@@ -35,6 +39,10 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   /**
    * 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
    */
@@ -44,11 +52,22 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    * 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
    */
   joinDocRoom(docId: string, params?: TransportJoinParams): Promise<TransportSubscription>;
+  /**
+   * 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.
+   */
+  joinEphemeralRoom(roomId: string): Promise<TransportSubscription & {
+    store: EphemeralStore;
+  }>;
   /**
    * Opens a document that is automatically persisted to the configured storage adapter.
    *
@@ -58,8 +77,31 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    */
   openPersistedDoc(docId: string): Promise<RepoDocHandle>;
   upsertDocMeta(docId: string, patch: Partial<Meta>): Promise<void>;
-  getDocMeta(docId: string): Promise<Meta | undefined>;
+  getDocMeta(docId: string): Promise<RepoDocSnapshot<Meta> | undefined>;
   listDoc(query?: ListDocQuery): Promise<RepoDocMeta<Meta>[]>;
+  /**
+   * 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.
+   */
+  deleteDoc(docId: string, options?: DeleteDocOptions): Promise<void>;
+  /**
+   * Undo a soft delete by removing the tombstone entry. Metadata and document
+   * state remain untouched.
+   */
+  restoreDoc(docId: string): Promise<void>;
+  /**
+   * 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).
+   */
+  purgeDoc(docId: string): Promise<void>;
+  /**
+   * Sweep tombstoned documents whose retention window expired. Uses
+   * `deletedDocKeepMs` by default; pass `minKeepMs`/`now` for overrides.
+   */
+  gcDeletedDocs(options?: GcDeletedDocOptions): Promise<number>;
   getMeta(): Flock;
   watch(listener: RepoEventListener<Meta>, filter?: RepoEventFilter<Meta>): RepoWatchHandle;
   /**
@@ -88,7 +130,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   gcAssets(options?: GarbageCollectionOptions): Promise<number>;
   get destroyed(): boolean;
   destroy(): Promise<void>;
+  private handlePurgeSignals;
 }
 //#endregion
-export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, GarbageCollectionOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportJoinParams, TransportSubscription, TransportSyncRequest, TransportSyncResult, UploadAssetOptions };
+export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, DeleteDocOptions, GarbageCollectionOptions, GcDeletedDocOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, UploadAssetOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { A as TransportSyncResult, C as StorageAdapter, D as TransportJoinParams, E as TransportAdapter, O as TransportSubscription, S as RepoWatchHandle, T as SyncScope, _ as RepoEventFilter, a as AssetUploadMetadata, b as RepoEventType, c as JsonValue, d as LoroRepoOptions, f as RepoAssetMetadata, g as RepoEventBy, h as RepoEvent, i as AssetTransportAdapter, j as UploadAssetOptions, k as TransportSyncRequest, l as LinkAssetOptions, m as RepoDocMeta, n as AssetDownload, o as GarbageCollectionOptions, p as RepoDocHandle, r as AssetId, s as JsonObject, t as AssetContent, u as ListDocQuery, v as RepoEventKind, w as StorageSavePayload, x as RepoSyncOptions, y as RepoEventListener } from "./types.js";
+import { A as TransportConnectionStatus, C as RepoEventType, D as StorageSavePayload, E as StorageAdapter, F as TransportSyncResult, I as UploadAssetOptions, M as TransportRoomStatus, N as TransportSubscription, O as SyncScope, P as TransportSyncRequest, S as RepoEventListener, T as RepoWatchHandle, _ as RepoDocSnapshot, a as AssetUploadMetadata, b as RepoEventFilter, c as GcDeletedDocOptions, d as LinkAssetOptions, f as ListDocQuery, g as RepoDocMeta, h as RepoDocHandle, i as AssetTransportAdapter, j as TransportJoinParams, k as TransportAdapter, l as JsonObject, m as RepoAssetMetadata, n as AssetDownload, o as DeleteDocOptions, p as LoroRepoOptions, r as AssetId, s as GarbageCollectionOptions, t as AssetContent, u as JsonValue, v as RepoEvent, w as RepoSyncOptions, x as RepoEventKind, y as RepoEventBy } from "./types.js";
 import { Flock } from "@loro-dev/flock";
-import { LoroDoc } from "loro-crdt";
+import { EphemeralStore, LoroDoc } from "loro-crdt";
 
 //#region src/index.d.ts
 declare class LoroRepo<Meta extends JsonObject = JsonObject> {
@@ -18,6 +18,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   private readonly state;
   private readonly syncRunner;
   private readonly metaPersister;
+  private readonly deletedDocKeepMs;
+  private readonly purgeWatchHandle;
   private constructor();
   static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions): Promise<LoroRepo<Meta>>;
   /**
@@ -27,6 +29,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    * Though we do that implicitly already
    */
   private ready;
+  private computeDocPurgeAfter;
+  private purgeDocKeyspace;
   /**
    * Sync selected data via the transport adaptor
    * @param options
@@ -35,6 +39,10 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   /**
    * 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
    */
@@ -44,11 +52,22 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    * 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
    */
   joinDocRoom(docId: string, params?: TransportJoinParams): Promise<TransportSubscription>;
+  /**
+   * 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.
+   */
+  joinEphemeralRoom(roomId: string): Promise<TransportSubscription & {
+    store: EphemeralStore;
+  }>;
   /**
    * Opens a document that is automatically persisted to the configured storage adapter.
    *
@@ -58,8 +77,31 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
    */
   openPersistedDoc(docId: string): Promise<RepoDocHandle>;
   upsertDocMeta(docId: string, patch: Partial<Meta>): Promise<void>;
-  getDocMeta(docId: string): Promise<Meta | undefined>;
+  getDocMeta(docId: string): Promise<RepoDocSnapshot<Meta> | undefined>;
   listDoc(query?: ListDocQuery): Promise<RepoDocMeta<Meta>[]>;
+  /**
+   * 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.
+   */
+  deleteDoc(docId: string, options?: DeleteDocOptions): Promise<void>;
+  /**
+   * Undo a soft delete by removing the tombstone entry. Metadata and document
+   * state remain untouched.
+   */
+  restoreDoc(docId: string): Promise<void>;
+  /**
+   * 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).
+   */
+  purgeDoc(docId: string): Promise<void>;
+  /**
+   * Sweep tombstoned documents whose retention window expired. Uses
+   * `deletedDocKeepMs` by default; pass `minKeepMs`/`now` for overrides.
+   */
+  gcDeletedDocs(options?: GcDeletedDocOptions): Promise<number>;
   getMeta(): Flock;
   watch(listener: RepoEventListener<Meta>, filter?: RepoEventFilter<Meta>): RepoWatchHandle;
   /**
@@ -88,7 +130,8 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   gcAssets(options?: GarbageCollectionOptions): Promise<number>;
   get destroyed(): boolean;
   destroy(): Promise<void>;
+  private handlePurgeSignals;
 }
 //#endregion
-export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, GarbageCollectionOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportJoinParams, TransportSubscription, TransportSyncRequest, TransportSyncResult, UploadAssetOptions };
+export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, DeleteDocOptions, GarbageCollectionOptions, GcDeletedDocOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoDocSnapshot, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, TransportConnectionStatus, TransportJoinParams, TransportRoomStatus, TransportSubscription, TransportSyncRequest, TransportSyncResult, UploadAssetOptions };
 //# sourceMappingURL=index.d.ts.map