loro-repo 0.1.0 → 0.3.0

package/README.md

@@ -74,6 +74,9 @@ await handle.close();
 - `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.
 
+- `FileSystemStorageAdaptor` (`src/storage/filesystem.ts`)  
+  Node-friendly persistence layer that writes metadata snapshots, doc snapshots/updates, and assets to the local file system. Point it at a writable directory (defaults to `.loro-repo` in your current working folder) when building Electron apps, desktop sync daemons, or tests that need durable state without IndexedDB.
+
 - Asset transports  
   Bring your own `AssetTransportAdapter` (HTTP uploads, peer meshes, S3, etc.). LoroRepo dedupes via SHA-256 assetIds while your adaptor decides how to encrypt/store the bytes.
 

package/dist/{index.d.cts → index-DsCaL9JX.d.cts}

@@ -15,6 +15,14 @@ type GlobalBlob = typeof globalThis extends {
  * Binary content accepted by asset ingestion helpers.
  */
 type AssetContent = GlobalBlob | ArrayBufferView | ReadableStream<Uint8Array>;
+interface RepoAssetMetadata {
+  readonly assetId: AssetId;
+  readonly size: number;
+  readonly createdAt: number;
+  readonly mime?: string;
+  readonly policy?: string;
+  readonly tag?: string;
+}
 /**
  * JSON-compatible leaf value used for document metadata.
  */
@@ -48,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.
@@ -160,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.
    */
@@ -212,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.
    */
@@ -334,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`.
  */
@@ -565,106 +583,136 @@ declare class IndexedDBStorageAdaptor implements StorageAdapter {
   private createError;
 }
 //#endregion
-//#region src/index.d.ts
-interface RepoAssetMetadata {
-  readonly assetId: AssetId;
-  readonly size: number;
-  readonly createdAt: number;
-  readonly mime?: string;
-  readonly policy?: string;
-  readonly tag?: string;
+//#region src/storage/filesystem.d.ts
+interface FileSystemStorageAdaptorOptions {
+  /**
+   * Base directory where metadata, document snapshots, and assets will be stored.
+   * Defaults to `.loro-repo` inside the current working directory.
+   */
+  readonly baseDir?: string;
+  /**
+   * Subdirectory dedicated to document persistence. Defaults to `docs`.
+   */
+  readonly docsDirName?: string;
+  /**
+   * Subdirectory dedicated to asset blobs. Defaults to `assets`.
+   */
+  readonly assetsDirName?: string;
+  /**
+   * File name for the metadata snapshot bundle. Defaults to `meta.json`.
+   */
+  readonly metaFileName?: string;
+}
+declare class FileSystemStorageAdaptor implements StorageAdapter {
+  private readonly baseDir;
+  private readonly docsDir;
+  private readonly assetsDir;
+  private readonly metaPath;
+  private readonly initPromise;
+  private updateCounter;
+  constructor(options?: FileSystemStorageAdaptorOptions);
+  save(payload: StorageSavePayload): Promise<void>;
+  deleteAsset(assetId: AssetId): Promise<void>;
+  loadDoc(docId: string): Promise<LoroDoc | undefined>;
+  loadMeta(): Promise<Flock | undefined>;
+  loadAsset(assetId: AssetId): Promise<Uint8Array | undefined>;
+  private ensureLayout;
+  private writeDocSnapshot;
+  private enqueueDocUpdate;
+  private writeAsset;
+  private docDir;
+  private docSnapshotPath;
+  private docUpdatesDir;
+  private assetPath;
 }
+//#endregion
+//#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 assetTransport?;
-  private readonly docFactory;
   private metaFlock;
-  private readonly metadata;
-  private readonly docs;
-  private readonly docRefs;
-  private readonly docSubscriptions;
-  private readonly docAssets;
-  private readonly assets;
-  private readonly orphanedAssets;
-  private readonly assetToDocRefs;
-  private readonly docFrontierKeys;
-  private readonly docFrontierUpdates;
-  private readonly docPersistedVersions;
-  private readonly docFrontierDebounceMs;
-  private readonly watchers;
-  private readonly eventByStack;
-  private metaRoomSubscription?;
-  private unsubscribeMetaFlock?;
-  private readyPromise?;
-  constructor(options: LoroRepoOptions<Meta>);
-  ready(): Promise<void>;
-  private initialize;
+  private readonly eventBus;
+  private readonly docManager;
+  private readonly metadataManager;
+  private readonly assetManager;
+  private readonly assetTransport?;
+  private readonly flockHydrator;
+  private readonly state;
+  private readonly syncRunner;
+  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>;
-  private refreshDocMetadataEntry;
-  private refreshDocAssetsEntry;
-  private refreshAssetMetadataEntry;
-  private refreshDocFrontierKeys;
-  private readDocMetadataFromFlock;
-  private readDocAssetsFromFlock;
-  private readAssetMetadataFromFlock;
-  private handleAssetRemoval;
-  private emit;
+  /**
+   * 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>;
   listAssets(docId: string): Promise<RepoAssetMetadata[]>;
   ensureAsset(assetId: AssetId): Promise<AssetDownload>;
-  private createAssetDownload;
-  private materializeAsset;
-  private updateDocAssetMetadata;
   gcAssets(options?: GarbageCollectionOptions): Promise<number>;
-  private onDocHandleClose;
-  private ensureDoc;
-  private materializeDetachedDoc;
-  private exportDocSnapshot;
   private persistMeta;
-  private persistDoc;
-  private persistDocUpdate;
-  private pushEventBy;
-  private popEventBy;
-  private resolveEventBy;
-  private ensureMetaLiveMonitor;
-  private applyMetaFlockEvents;
-  private registerDoc;
-  private ensureDocSubscription;
-  private rememberAsset;
-  private scheduleDocFrontierUpdate;
-  private mergeRepoEventBy;
-  private runScheduledDocFrontierUpdate;
-  private flushScheduledDocFrontierUpdate;
-  private onDocEvent;
-  private getAssetMetadata;
-  private updateDocFrontiers;
-  private hydrateMetadataFromFlock;
-  private shouldNotify;
+  get destroyed(): boolean;
+  destroy(): Promise<void>;
 }
 //#endregion
-export { AssetContent, AssetDownload, AssetId, AssetTransportAdapter, AssetUploadMetadata, BroadcastChannelTransportAdapter, type BroadcastChannelTransportOptions, 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 };
-//# sourceMappingURL=index.d.cts.map
+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, WebSocketTransportOptions };
+//# sourceMappingURL=index-DsCaL9JX.d.cts.map