loro-repo 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Flock } from "@loro-dev/flock";
 import { Frontiers, LoroDoc } from "loro-crdt";
 import { JoinError, JoinResponseOk, RoomId, UpdateError } from "loro-protocol";
 import { LoroWebsocketClientOptions } from "loro-websocket";
-import { FlockAdaptorConfig } from "loro-adaptors";
+import { FlockAdaptorConfig } from "loro-adaptors/flock";
 
 //#region src/types.d.ts
 type GlobalBlob = typeof globalThis extends {
@@ -56,10 +56,6 @@ interface LoroRepoOptions<_Meta extends JsonObject = JsonObject> {
    * Optional adapter that moves asset payloads while keeping metadata in sync.
    */
   readonly assetTransportAdapter?: AssetTransportAdapter;
-  /**
-   * Factory invoked when a document handle needs to be materialised.
-   */
-  readonly docFactory?: (docId: string) => Promise<LoroDoc>;
   /**
    * Debounce duration in milliseconds before persisting document frontier metadata
    * after local edits. Defaults to 1000 ms when omitted.
@@ -168,6 +164,8 @@ interface TransportAdapter {
  * Persists metadata, documents, and asset payloads on behalf of the repo.
  */
 interface StorageAdapter {
+  init?(): Promise<void>;
+  close?(): void;
   /**
    * Writes document snapshots, queued updates, assets, or meta bundles to durable storage.
    */
@@ -220,6 +218,8 @@ interface AssetUploadMetadata {
  * Moves binary assets between peers or infrastructure-specific storage.
  */
 interface AssetTransportAdapter {
+  init?(): Promise<void>;
+  close?(): void;
   /**
    * Uploads a raw asset payload using transport-managed metadata.
    */
@@ -342,47 +342,57 @@ interface RepoDocHandle {
    */
   readonly doc: LoroDoc;
   /**
-   * Resolves once storage hydration and any queued remote updates complete.
+   * Sync with the transport adaptor once.
    */
-  readonly whenSyncedWithRemote: Promise<void>;
+  readonly syncOnce: () => Promise<void>;
   /**
-   * Unsubscribes listeners and releases resources associated with the document.
+   * Join the realtime collaboration room.
    */
-  close(): Promise<void>;
+  readonly joinRoom: (auth?: Uint8Array) => Promise<TransportSubscription>;
 }
-interface UpsertDocMetaOptions {}
 /**
  * Provenance discriminant attached to every repo event.
  */
 type RepoEventBy = "local" | "sync" | "live";
 /**
- * Unified event envelope emitted by `watch`.
+ * Unified event envelope types emitted by `watch`.
  */
-type RepoEvent<Meta extends JsonObject = JsonObject> = {
-  readonly kind: "doc-metadata";
-  readonly docId: string;
-  readonly patch: Partial<Meta>;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "doc-frontiers";
-  readonly docId: string;
-  readonly frontiers: Frontiers;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-metadata";
-  readonly asset: AssetDownload;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-link";
-  readonly docId: string;
-  readonly assetId: AssetId;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-unlink";
-  readonly docId: string;
-  readonly assetId: AssetId;
-  readonly by: RepoEventBy;
+type RepoEventType<Meta extends JsonObject = JsonObject> = {
+  "doc-metadata": {
+    readonly kind: "doc-metadata";
+    readonly docId: string;
+    readonly patch: Partial<Meta>;
+    readonly by: RepoEventBy;
+  };
+  "doc-frontiers": {
+    readonly kind: "doc-frontiers";
+    readonly docId: string;
+    readonly frontiers: Frontiers;
+    readonly by: RepoEventBy;
+  };
+  "asset-metadata": {
+    readonly kind: "asset-metadata";
+    readonly asset: AssetDownload;
+    readonly by: RepoEventBy;
+  };
+  "asset-link": {
+    readonly kind: "asset-link";
+    readonly docId: string;
+    readonly assetId: AssetId;
+    readonly by: RepoEventBy;
+  };
+  "asset-unlink": {
+    readonly kind: "asset-unlink";
+    readonly docId: string;
+    readonly assetId: AssetId;
+    readonly by: RepoEventBy;
+  };
 };
+/**
+ * Discriminant union of all possible repo event types.
+ */
+type RepoEventKind = keyof RepoEventType;
+type RepoEvent<Meta extends JsonObject = JsonObject> = RepoEventType<Meta>[keyof RepoEventType<Meta>];
 /**
  * Listener signature for `watch`.
  */
@@ -619,40 +629,80 @@ declare class FileSystemStorageAdaptor implements StorageAdapter {
 //#region src/index.d.ts
 declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   readonly options: LoroRepoOptions<Meta>;
+  private _destroyed;
   private readonly transport?;
   private readonly storage?;
-  private readonly docFactory;
   private metaFlock;
   private readonly eventBus;
   private readonly docManager;
   private readonly metadataManager;
   private readonly assetManager;
+  private readonly assetTransport?;
   private readonly flockHydrator;
   private readonly state;
   private readonly syncRunner;
-  constructor(options: LoroRepoOptions<Meta>);
-  ready(): Promise<void>;
+  private constructor();
+  static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions<Meta>): Promise<LoroRepo<Meta>>;
+  /**
+   * Load meta from storage.
+   *
+   * You need to call this before all other operations to make the app functioning correctly.
+   * Though we do that implicitly already
+   */
+  private ready;
+  /**
+   * Sync selected data via the transport adaptor
+   * @param options
+   */
   sync(options?: RepoSyncOptions): Promise<void>;
+  /**
+   * Start syncing the metadata (Flock) room. It will establish a realtime connection to the transport adaptor.
+   * All changes on the room will be synced to the Flock, and all changes on the Flock will be synced to the room.
+   * @param params
+   * @returns
+   */
   joinMetaRoom(params?: TransportJoinParams): Promise<TransportSubscription>;
+  /**
+   * Start syncing the given doc. It will establish a realtime connection to the transport adaptor.
+   * All changes on the doc will be synced to the transport, and all changes on the transport will be synced to the doc.
+   *
+   * All the changes on the room will be reflected on the same doc you get from `repo.openCollaborativeDoc(docId)`
+   * @param docId
+   * @param params
+   * @returns
+   */
   joinDocRoom(docId: string, params?: TransportJoinParams): Promise<TransportSubscription>;
-  close(): Promise<void>;
-  upsertDocMeta(docId: string, patch: Partial<Meta>, _options?: UpsertDocMetaOptions): Promise<void>;
+  /**
+   * Opens a document that is automatically persisted to the configured storage adapter.
+   *
+   * - Edits are saved to storage (debounced).
+   * - Frontiers are synced to the metadata (Flock).
+   * - Realtime collaboration is NOT enabled by default; use `joinDocRoom` to connect.
+   */
+  openPersistedDoc(docId: string): Promise<RepoDocHandle>;
+  upsertDocMeta(docId: string, patch: Partial<Meta>): Promise<void>;
   getDocMeta(docId: string): Promise<Meta | undefined>;
   listDoc(query?: ListDocQuery): Promise<RepoDocMeta<Meta>[]>;
-  getMetaReplica(): Flock;
+  getMeta(): Flock;
   watch(listener: RepoEventListener<Meta>, filter?: RepoEventFilter<Meta>): RepoWatchHandle;
   /**
-   * Opens the repo-managed collaborative document, registers it for persistence,
-   * and schedules a doc-level sync so `whenSyncedWithRemote` resolves after remote backfills.
+   * Opens a detached `LoroDoc` snapshot.
+   *
+   * - **No Persistence**: Edits to this document are NOT saved to storage.
+   * - **No Sync**: This document does not participate in realtime updates.
+   * - **Use Case**: Ideal for read-only history inspection, temporary drafts, or conflict resolution without affecting the main state.
    */
-  openCollaborativeDoc(docId: string): Promise<RepoDocHandle>;
+  openDetachedDoc(docId: string): Promise<LoroDoc>;
   /**
-   * Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
-   * it neither participates in remote subscriptions nor persists edits back to storage.
+   * Explicitly unloads a document from memory.
+   *
+   * - **Persists Immediately**: Forces a save of the document's current state to storage.
+   * - **Frees Memory**: Removes the document from the internal cache.
+   * - **Note**: If the document is currently being synced (via `joinDocRoom`), you should also unsubscribe from the room to fully release resources.
    */
-  openDetachedDoc(docId: string): Promise<RepoDocHandle>;
+  unloadDoc(docId: string): Promise<void>;
+  flush(): Promise<void>;
   uploadAsset(params: UploadAssetOptions): Promise<AssetId>;
-  whenDocInSyncWithRemote(docId: string): Promise<void>;
   linkAsset(docId: string, params: LinkAssetOptions): Promise<AssetId>;
   fetchAsset(assetId: AssetId): Promise<AssetDownload>;
   unlinkAsset(docId: string, assetId: AssetId): Promise<void>;
@@ -660,7 +710,9 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   ensureAsset(assetId: AssetId): Promise<AssetDownload>;
   gcAssets(options?: GarbageCollectionOptions): Promise<number>;
   private persistMeta;
+  get destroyed(): boolean;
+  destroy(): Promise<void>;
 }
 //#endregion
-export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, BroadcastChannelTransportAdapter, type BroadcastChannelTransportOptions, FileSystemStorageAdaptor, type FileSystemStorageAdaptorOptions, GarbageCollectionOptions, IndexedDBStorageAdaptor, type IndexedDBStorageAdaptorOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventListener, type RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, type TransportJoinParams, type TransportSubscription, TransportSyncRequest, type TransportSyncResult, UploadAssetOptions, UpsertDocMetaOptions, WebSocketTransportAdapter, WebSocketTransportOptions };
+export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, BroadcastChannelTransportAdapter, type BroadcastChannelTransportOptions, FileSystemStorageAdaptor, type FileSystemStorageAdaptorOptions, GarbageCollectionOptions, IndexedDBStorageAdaptor, type IndexedDBStorageAdaptorOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, type RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, type TransportJoinParams, type TransportSubscription, TransportSyncRequest, type TransportSyncResult, UploadAssetOptions, WebSocketTransportAdapter, type WebSocketTransportOptions };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 import { Flock } from "@loro-dev/flock";
-import { Frontiers, LoroDoc } from "loro-crdt";
-import { FlockAdaptor, FlockAdaptorConfig, LoroAdaptor } from "loro-adaptors";
+import { LoroAdaptor } from "loro-adaptors/loro";
 import { JoinError, JoinResponseOk, RoomId, UpdateError } from "loro-protocol";
 import { LoroWebsocketClientOptions } from "loro-websocket";
+import { Frontiers, LoroDoc } from "loro-crdt";
+import { FlockAdaptor, FlockAdaptorConfig } from "loro-adaptors/flock";
 
 //#region src/types.d.ts
 type GlobalBlob = typeof globalThis extends {
@@ -56,10 +57,6 @@ interface LoroRepoOptions<_Meta extends JsonObject = JsonObject> {
    * Optional adapter that moves asset payloads while keeping metadata in sync.
    */
   readonly assetTransportAdapter?: AssetTransportAdapter;
-  /**
-   * Factory invoked when a document handle needs to be materialised.
-   */
-  readonly docFactory?: (docId: string) => Promise<LoroDoc>;
   /**
    * Debounce duration in milliseconds before persisting document frontier metadata
    * after local edits. Defaults to 1000 ms when omitted.
@@ -168,6 +165,8 @@ interface TransportAdapter {
  * Persists metadata, documents, and asset payloads on behalf of the repo.
  */
 interface StorageAdapter {
+  init?(): Promise<void>;
+  close?(): void;
   /**
    * Writes document snapshots, queued updates, assets, or meta bundles to durable storage.
    */
@@ -220,6 +219,8 @@ interface AssetUploadMetadata {
  * Moves binary assets between peers or infrastructure-specific storage.
  */
 interface AssetTransportAdapter {
+  init?(): Promise<void>;
+  close?(): void;
   /**
    * Uploads a raw asset payload using transport-managed metadata.
    */
@@ -342,47 +343,57 @@ interface RepoDocHandle {
    */
   readonly doc: LoroDoc;
   /**
-   * Resolves once storage hydration and any queued remote updates complete.
+   * Sync with the transport adaptor once.
    */
-  readonly whenSyncedWithRemote: Promise<void>;
+  readonly syncOnce: () => Promise<void>;
   /**
-   * Unsubscribes listeners and releases resources associated with the document.
+   * Join the realtime collaboration room.
    */
-  close(): Promise<void>;
+  readonly joinRoom: (auth?: Uint8Array) => Promise<TransportSubscription>;
 }
-interface UpsertDocMetaOptions {}
 /**
  * Provenance discriminant attached to every repo event.
  */
 type RepoEventBy = "local" | "sync" | "live";
 /**
- * Unified event envelope emitted by `watch`.
+ * Unified event envelope types emitted by `watch`.
  */
-type RepoEvent<Meta extends JsonObject = JsonObject> = {
-  readonly kind: "doc-metadata";
-  readonly docId: string;
-  readonly patch: Partial<Meta>;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "doc-frontiers";
-  readonly docId: string;
-  readonly frontiers: Frontiers;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-metadata";
-  readonly asset: AssetDownload;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-link";
-  readonly docId: string;
-  readonly assetId: AssetId;
-  readonly by: RepoEventBy;
-} | {
-  readonly kind: "asset-unlink";
-  readonly docId: string;
-  readonly assetId: AssetId;
-  readonly by: RepoEventBy;
+type RepoEventType<Meta extends JsonObject = JsonObject> = {
+  "doc-metadata": {
+    readonly kind: "doc-metadata";
+    readonly docId: string;
+    readonly patch: Partial<Meta>;
+    readonly by: RepoEventBy;
+  };
+  "doc-frontiers": {
+    readonly kind: "doc-frontiers";
+    readonly docId: string;
+    readonly frontiers: Frontiers;
+    readonly by: RepoEventBy;
+  };
+  "asset-metadata": {
+    readonly kind: "asset-metadata";
+    readonly asset: AssetDownload;
+    readonly by: RepoEventBy;
+  };
+  "asset-link": {
+    readonly kind: "asset-link";
+    readonly docId: string;
+    readonly assetId: AssetId;
+    readonly by: RepoEventBy;
+  };
+  "asset-unlink": {
+    readonly kind: "asset-unlink";
+    readonly docId: string;
+    readonly assetId: AssetId;
+    readonly by: RepoEventBy;
+  };
 };
+/**
+ * Discriminant union of all possible repo event types.
+ */
+type RepoEventKind = keyof RepoEventType;
+type RepoEvent<Meta extends JsonObject = JsonObject> = RepoEventType<Meta>[keyof RepoEventType<Meta>];
 /**
  * Listener signature for `watch`.
  */
@@ -619,40 +630,80 @@ declare class FileSystemStorageAdaptor implements StorageAdapter {
 //#region src/index.d.ts
 declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   readonly options: LoroRepoOptions<Meta>;
+  private _destroyed;
   private readonly transport?;
   private readonly storage?;
-  private readonly docFactory;
   private metaFlock;
   private readonly eventBus;
   private readonly docManager;
   private readonly metadataManager;
   private readonly assetManager;
+  private readonly assetTransport?;
   private readonly flockHydrator;
   private readonly state;
   private readonly syncRunner;
-  constructor(options: LoroRepoOptions<Meta>);
-  ready(): Promise<void>;
+  private constructor();
+  static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions<Meta>): Promise<LoroRepo<Meta>>;
+  /**
+   * Load meta from storage.
+   *
+   * You need to call this before all other operations to make the app functioning correctly.
+   * Though we do that implicitly already
+   */
+  private ready;
+  /**
+   * Sync selected data via the transport adaptor
+   * @param options
+   */
   sync(options?: RepoSyncOptions): Promise<void>;
+  /**
+   * Start syncing the metadata (Flock) room. It will establish a realtime connection to the transport adaptor.
+   * All changes on the room will be synced to the Flock, and all changes on the Flock will be synced to the room.
+   * @param params
+   * @returns
+   */
   joinMetaRoom(params?: TransportJoinParams): Promise<TransportSubscription>;
+  /**
+   * Start syncing the given doc. It will establish a realtime connection to the transport adaptor.
+   * All changes on the doc will be synced to the transport, and all changes on the transport will be synced to the doc.
+   *
+   * All the changes on the room will be reflected on the same doc you get from `repo.openCollaborativeDoc(docId)`
+   * @param docId
+   * @param params
+   * @returns
+   */
   joinDocRoom(docId: string, params?: TransportJoinParams): Promise<TransportSubscription>;
-  close(): Promise<void>;
-  upsertDocMeta(docId: string, patch: Partial<Meta>, _options?: UpsertDocMetaOptions): Promise<void>;
+  /**
+   * Opens a document that is automatically persisted to the configured storage adapter.
+   *
+   * - Edits are saved to storage (debounced).
+   * - Frontiers are synced to the metadata (Flock).
+   * - Realtime collaboration is NOT enabled by default; use `joinDocRoom` to connect.
+   */
+  openPersistedDoc(docId: string): Promise<RepoDocHandle>;
+  upsertDocMeta(docId: string, patch: Partial<Meta>): Promise<void>;
   getDocMeta(docId: string): Promise<Meta | undefined>;
   listDoc(query?: ListDocQuery): Promise<RepoDocMeta<Meta>[]>;
-  getMetaReplica(): Flock;
+  getMeta(): Flock;
   watch(listener: RepoEventListener<Meta>, filter?: RepoEventFilter<Meta>): RepoWatchHandle;
   /**
-   * Opens the repo-managed collaborative document, registers it for persistence,
-   * and schedules a doc-level sync so `whenSyncedWithRemote` resolves after remote backfills.
+   * Opens a detached `LoroDoc` snapshot.
+   *
+   * - **No Persistence**: Edits to this document are NOT saved to storage.
+   * - **No Sync**: This document does not participate in realtime updates.
+   * - **Use Case**: Ideal for read-only history inspection, temporary drafts, or conflict resolution without affecting the main state.
    */
-  openCollaborativeDoc(docId: string): Promise<RepoDocHandle>;
+  openDetachedDoc(docId: string): Promise<LoroDoc>;
   /**
-   * Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
-   * it neither participates in remote subscriptions nor persists edits back to storage.
+   * Explicitly unloads a document from memory.
+   *
+   * - **Persists Immediately**: Forces a save of the document's current state to storage.
+   * - **Frees Memory**: Removes the document from the internal cache.
+   * - **Note**: If the document is currently being synced (via `joinDocRoom`), you should also unsubscribe from the room to fully release resources.
    */
-  openDetachedDoc(docId: string): Promise<RepoDocHandle>;
+  unloadDoc(docId: string): Promise<void>;
+  flush(): Promise<void>;
   uploadAsset(params: UploadAssetOptions): Promise<AssetId>;
-  whenDocInSyncWithRemote(docId: string): Promise<void>;
   linkAsset(docId: string, params: LinkAssetOptions): Promise<AssetId>;
   fetchAsset(assetId: AssetId): Promise<AssetDownload>;
   unlinkAsset(docId: string, assetId: AssetId): Promise<void>;
@@ -660,7 +711,9 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   ensureAsset(assetId: AssetId): Promise<AssetDownload>;
   gcAssets(options?: GarbageCollectionOptions): Promise<number>;
   private persistMeta;
+  get destroyed(): boolean;
+  destroy(): Promise<void>;
 }
 //#endregion
-export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, BroadcastChannelTransportAdapter, type BroadcastChannelTransportOptions, FileSystemStorageAdaptor, type FileSystemStorageAdaptorOptions, GarbageCollectionOptions, IndexedDBStorageAdaptor, type IndexedDBStorageAdaptorOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventListener, type RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, type TransportJoinParams, type TransportSubscription, TransportSyncRequest, type TransportSyncResult, UploadAssetOptions, UpsertDocMetaOptions, WebSocketTransportAdapter, WebSocketTransportOptions };
+export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, BroadcastChannelTransportAdapter, type BroadcastChannelTransportOptions, FileSystemStorageAdaptor, type FileSystemStorageAdaptorOptions, GarbageCollectionOptions, IndexedDBStorageAdaptor, type IndexedDBStorageAdaptorOptions, JsonObject, JsonValue, LinkAssetOptions, ListDocQuery, LoroRepo, LoroRepoOptions, RepoAssetMetadata, RepoDocHandle, RepoDocMeta, RepoEvent, RepoEventBy, RepoEventFilter, RepoEventKind, RepoEventListener, RepoEventType, type RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, type TransportJoinParams, type TransportSubscription, TransportSyncRequest, type TransportSyncResult, UploadAssetOptions, WebSocketTransportAdapter, type WebSocketTransportOptions };
 //# sourceMappingURL=index.d.ts.map