loro-repo 0.4.0 → 0.5.1

package/dist/index.d.cts

@@ -1,634 +1,10 @@
+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 { 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/flock";
+import { LoroDoc } from "loro-crdt";
 
-//#region src/types.d.ts
-type GlobalBlob = typeof globalThis extends {
-  Blob: infer B;
-} ? B : {
-  readonly size: number;
-  readonly type: string;
-};
-/**
- * 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.
- */
-type JsonValue = string | number | boolean | null | JsonValue[] | {
-  [key: string]: JsonValue;
-};
-/**
- * JSON-compatible object map used throughout metadata APIs.
- */
-type JsonObject = {
-  [key: string]: JsonValue;
-};
-/**
- * Synchronisation lanes available to repo consumers.
- */
-type SyncScope = "meta" | "doc" | "full";
-/**
- * Construction options for creating a `LoroRepo` instance.
- */
-interface LoroRepoOptions<_Meta extends JsonObject = JsonObject> {
-  /**
-   * Transport adapter responsible for fetching and pushing CRDT bundles.
-   * Omit when operating fully offline or within pure tests.
-   */
-  readonly transportAdapter?: TransportAdapter;
-  /**
-   * Storage adapter that hydrates snapshots and persists incremental updates.
-   */
-  readonly storageAdapter?: StorageAdapter;
-  /**
-   * Optional adapter that moves asset payloads while keeping metadata in sync.
-   */
-  readonly assetTransportAdapter?: AssetTransportAdapter;
-  /**
-   * Debounce duration in milliseconds before persisting document frontier metadata
-   * after local edits. Defaults to 1000 ms when omitted.
-   */
-  readonly docFrontierDebounceMs?: number;
-}
-/**
- * Parameters accepted by `LoroRepo.sync`.
- */
-interface RepoSyncOptions {
-  /**
-   * Defines the lanes to sync: metadata only, document bodies, or both.
-   */
-  readonly scope?: SyncScope;
-  /**
-   * Explicit allow-list of document ids for partial synchronisation.
-   */
-  readonly docIds?: ReadonlyArray<string>;
-}
-/**
- * Parameters passed to transport adapters when issuing a sync request.
- */
-interface TransportSyncRequest {
-  /**
-   * Synchronisation scope (metadata-only, document bodies, or both).
-   */
-  readonly scope: SyncScope;
-  /**
-   * Optional document allow-list when syncing specific bodies.
-   */
-  readonly docIds?: ReadonlyArray<string>;
-}
-/**
- * Result returned by transport adapters after fetching updates.
- */
-interface TransportSyncResult {
-  readonly ok: boolean;
-}
-/**
- * Parameters used when joining live collaboration rooms.
- */
-interface TransportJoinParams {
-  readonly roomId?: RoomId;
-  readonly auth?: Uint8Array;
-}
-/**
- * Subscription handle returned by transport adapters after joining a room.
- */
-interface TransportSubscription {
-  readonly unsubscribe: () => void;
-  readonly firstSyncedWithRemote: Promise<void>;
-  readonly connected: boolean;
-}
-/**
- * Abstracts the transport channel that exchanges metadata and document bundles.
- */
-interface TransportAdapter {
-  /**
-   * Establishes connectivity; If failed, the adapter should throw an error.
-   */
-  connect(options?: {
-    timeout?: number;
-  }): Promise<void>;
-  /**
-   * Tears down network resources and stops background polling.
-   */
-  close(): Promise<void>;
-  /**
-   * Indicates whether the adapter currently has an active transport connection.
-   */
-  isConnected(): boolean;
-  /**
-   * Pulls metadata updates and merges them into the supplied Flock replica. If the sync fails, the adapter should throw an error.
-   */
-  syncMeta(flock: Flock, options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  /**
-   * Joins the metadata room and returns an unsubscribe function for realtime updates.
-   */
-  joinMetaRoom(flock: Flock, params?: TransportJoinParams): TransportSubscription;
-  /**
-   * Pulls document body updates and merges them into the provided LoroDoc.
-   */
-  syncDoc(docId: string, loroDoc: LoroDoc, options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  /**
-   * Subscribes to live document updates, returning a cleanup handle.
-   */
-  joinDocRoom(docId: string, loroDoc: LoroDoc, params?: TransportJoinParams): TransportSubscription;
-  /**
-   * Optional callback invoked upon successful join responses.
-   */
-  handleJoinResponse?(response: JoinResponseOk): void;
-  /**
-   * Optional callback surfaced when joining a room fails.
-   */
-  handleJoinError?(error: JoinError): void;
-  /**
-   * Optional callback for update-level failures (e.g., decoding errors).
-   */
-  handleUpdateError?(error: UpdateError): void;
-}
-/**
- * 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.
-   */
-  save(payload: StorageSavePayload): Promise<void>;
-  /**
-   * Optionally deletes an asset payload during garbage collection.
-   */
-  deleteAsset?(assetId: AssetId): Promise<void>;
-  /**
-   * Loads a stored document by hydrating the persisted snapshot and replaying any queued updates.
-   */
-  loadDoc(docId: string): Promise<LoroDoc | undefined>;
-  /**
-   * Loads the repository-level metadata replica, if present.
-   */
-  loadMeta(): Promise<Flock | undefined>;
-  /**
-   * Loads a cached asset payload, if present.
-   */
-  loadAsset(assetId: AssetId): Promise<Uint8Array | undefined>;
-}
-/**
- * Union describing the kinds of payloads persisted via the storage adapter.
- */
-type StorageSavePayload = {
-  readonly type: "doc-snapshot";
-  readonly docId: string;
-  readonly snapshot: Uint8Array;
-} | {
-  readonly type: "doc-update";
-  readonly docId: string;
-  readonly update: Uint8Array;
-} | {
-  readonly type: "asset";
-  readonly assetId: AssetId;
-  readonly data: Uint8Array;
-} | {
-  readonly type: "meta";
-  readonly update: Uint8Array;
-};
-/**
- * Envelope supplied to asset uploads via the transport adapter.
- */
-interface AssetUploadMetadata {
-  readonly mime?: string;
-  readonly policy?: string;
-  readonly tag?: string;
-}
-/**
- * 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.
-   */
-  upload(assetId: AssetId, data: Uint8Array, metadata: AssetUploadMetadata): Promise<void>;
-  /**
-   * Fetches a remote asset payload, returning metadata and a lazy content stream.
-   */
-  fetch(assetId: AssetId): Promise<AssetDownload | undefined>;
-  /**
-   * Optional optimisation that ensures the remote asset exists or is reachable.
-   */
-  ensure?(assetId: AssetId): Promise<boolean>;
-}
-/**
- * Unique identifier for an asset managed by the repo. Set to the SHA-256 digest of the payload.
- */
-type AssetId = string;
-/**
- * Asset reference augmented with a lazy content accessor.
- */
-interface AssetDownload {
-  readonly assetId: AssetId;
-  readonly mime?: string;
-  readonly policy?: string;
-  readonly tag?: string;
-  readonly size: number;
-  readonly createdAt: number;
-  /**
-   * Lazily resolves to a readable stream, used to hydrate local caches.
-   */
-  readonly content: () => Promise<ReadableStream<Uint8Array>>;
-}
-/**
- * Options supplied when linking an asset to a document.
- */
-interface LinkAssetOptions extends AssetUploadMetadata {
-  /**
-   * Optional pre-existing asset id. Must match the SHA-256 digest of the content when provided.
-   */
-  readonly assetId?: AssetId;
-  /**
-   * Optional creation timestamp carried into metadata.
-   */
-  readonly createdAt?: number;
-  /**
-   * Raw payload provided by the caller.
-   */
-  readonly content: AssetContent;
-}
-/**
- * Options accepted by `uploadAsset`.
- */
-interface UploadAssetOptions extends AssetUploadMetadata {
-  /**
-   * Optional pre-assigned asset identifier. Must match the SHA-256 digest of the content when provided.
-   */
-  readonly assetId?: AssetId;
-  /**
-   * Optional timestamp preserved in the stored metadata.
-   */
-  readonly createdAt?: number;
-  /**
-   * Raw payload that will be persisted locally and optionally uploaded.
-   */
-  readonly content: AssetContent;
-}
-/**
- * Options accepted by `gcAssets`.
- */
-interface GarbageCollectionOptions {
-  /**
-   * Minimum duration in milliseconds to keep unreferenced assets before purging.
-   */
-  readonly minKeepMs?: number;
-  /**
-   * Optional batch size for deleting cached assets.
-   */
-  readonly batchSize?: number;
-}
-/**
- * Metadata entry returned by `listDoc`.
- */
-interface RepoDocMeta<Meta extends JsonObject = JsonObject> {
-  /**
-   * Globally unique identifier for the document (e.g. `note:<uuid>`).
-   */
-  readonly docId: string;
-  /**
-   * Merged metadata snapshot respecting the `Meta` contract.
-   */
-  readonly meta: Meta;
-}
-/**
- * Range-scan parameters for `listDoc`.
- */
-interface ListDocQuery {
-  /**
-   * Optional partition-style prefix to scan within the metadata keyspace.
-   */
-  readonly prefix?: string;
-  /**
-   * Inclusive range start for ordered metadata iteration.
-   */
-  readonly start?: string;
-  /**
-   * Exclusive range end for ordered metadata iteration.
-   */
-  readonly end?: string;
-  /**
-   * Maximum number of documents to materialise per call.
-   */
-  readonly limit?: number;
-}
-/**
- * Handle returned by `openCollaborativeDoc` (shared/persistent) or `openDetachedDoc` (isolated snapshot).
- */
-interface RepoDocHandle {
-  /**
-   * Shared collaborative document handle sourced from `loro-crdt`.
-   */
-  readonly doc: LoroDoc;
-  /**
-   * Sync with the transport adaptor once.
-   */
-  readonly syncOnce: () => Promise<void>;
-  /**
-   * Join the realtime collaboration room.
-   */
-  readonly joinRoom: (auth?: Uint8Array) => Promise<TransportSubscription>;
-}
-/**
- * Provenance discriminant attached to every repo event.
- */
-type RepoEventBy = "local" | "sync" | "live";
-/**
- * Unified event envelope types emitted by `watch`.
- */
-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`.
- */
-type RepoEventListener<Meta extends JsonObject = JsonObject> = (event: RepoEvent<Meta>) => void;
-/**
- * Handle returned by `watch`, allowing subscribers to unsubscribe.
- */
-interface RepoWatchHandle {
-  /**
-   * Stops receiving further repo events.
-   */
-  unsubscribe(): void;
-}
-/**
- * Server-side filter applied before emitting repo events.
- */
-interface RepoEventFilter<Meta extends JsonObject = JsonObject> {
-  /**
-   * Restrict events to the supplied set of document identifiers.
-   */
-  readonly docIds?: ReadonlyArray<string>;
-  /**
-   * Restrict events by kind (doc metadata/frontiers, asset lifecycle).
-   */
-  readonly kinds?: ReadonlyArray<RepoEvent<Meta>["kind"]>;
-  /**
-   * Emit metadata events only when the specified fields change.
-   */
-  readonly metadataFields?: ReadonlyArray<string>;
-  /**
-   * Restrict events by their provenance (local edits, explicit sync, or live collaboration).
-   */
-  readonly by?: ReadonlyArray<RepoEventBy>;
-}
-//#endregion
-//#region src/loro-adaptor.d.ts
-type RepoFlockAdaptorConfig = FlockAdaptorConfig;
-//#endregion
-//#region src/transport/websocket.d.ts
-interface WebSocketTransportOptions {
-  /**
-   * WebSocket endpoint provided to the loro-websocket client.
-   */
-  readonly url: string;
-  /**
-   * Optional loro-websocket client configuration.
-   */
-  readonly client?: Omit<LoroWebsocketClientOptions, "url">;
-  /**
-   * Metadata room identifier. When omitted, metadata synchronisation is disabled.
-   */
-  readonly metadataRoomId?: string;
-  /**
-   * Overrides the CRDT type advertised for the metadata room (defaults to `%FLO`).
-   * Only `%FLO` is supported.
-   */
-  readonly metadataCrdtType?: string;
-  /**
-   * Optional adaptor configuration for metadata joins.
-   */
-  readonly metadataAdaptorConfig?: RepoFlockAdaptorConfig;
-  /**
-   * Static auth payload for metadata joins.
-   */
-  readonly metadataAuth?: Uint8Array;
-  /**
-   * Factory that maps document ids to room identifiers. Defaults to the doc id.
-   */
-  readonly docRoomId?: (docId: string) => string;
-  /**
-   * Optional auth provider for document joins.
-   */
-  readonly docAuth?: (docId: string) => Uint8Array | undefined;
-}
-/**
- * loro-websocket backed {@link TransportAdapter} implementation for LoroRepo.
- */
-declare class WebSocketTransportAdapter implements TransportAdapter {
-  private readonly options;
-  private client?;
-  private metadataSession?;
-  private readonly docSessions;
-  constructor(options: WebSocketTransportOptions);
-  connect(_options?: {
-    timeout?: number;
-  }): Promise<void>;
-  close(): Promise<void>;
-  isConnected(): boolean;
-  syncMeta(flock: Flock, options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  joinMetaRoom(flock: Flock, params?: TransportJoinParams): TransportSubscription;
-  syncDoc(docId: string, doc: LoroDoc, options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  joinDocRoom(docId: string, doc: LoroDoc, params?: TransportJoinParams): TransportSubscription;
-  private ensureClient;
-  private ensureMetadataSession;
-  private teardownMetadataSession;
-  private ensureDocSession;
-  private leaveDocSession;
-}
-//#endregion
-//#region src/transport/broadcast-channel.d.ts
-interface BroadcastChannelTransportOptions {
-  /**
-   * Namespace used to derive broadcast channel names. Defaults to `loro-repo`.
-   */
-  readonly namespace?: string;
-  /**
-   * Explicit channel name for metadata broadcasts. When omitted, resolves to `${namespace}-meta`.
-   */
-  readonly metaChannelName?: string;
-}
-/**
- * TransportAdapter that relies on the BroadcastChannel API to fan out metadata
- * and document updates between browser tabs within the same origin.
- */
-declare class BroadcastChannelTransportAdapter implements TransportAdapter {
-  private readonly instanceId;
-  private readonly namespace;
-  private readonly metaChannelName;
-  private connected;
-  private metaState?;
-  private readonly docStates;
-  constructor(options?: BroadcastChannelTransportOptions);
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  isConnected(): boolean;
-  syncMeta(flock: Flock, _options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  joinMetaRoom(flock: Flock, _params?: TransportJoinParams): TransportSubscription;
-  syncDoc(docId: string, doc: LoroDoc, _options?: {
-    timeout?: number;
-  }): Promise<TransportSyncResult>;
-  joinDocRoom(docId: string, doc: LoroDoc, _params?: TransportJoinParams): TransportSubscription;
-  private ensureMetaChannel;
-  private ensureDocChannel;
-  private teardownDocChannel;
-}
-//#endregion
-//#region src/storage/indexeddb.d.ts
-interface IndexedDBStorageAdaptorOptions {
-  readonly dbName?: string;
-  readonly version?: number;
-  readonly docStoreName?: string;
-  readonly docUpdateStoreName?: string;
-  readonly metaStoreName?: string;
-  readonly assetStoreName?: string;
-  readonly metaKey?: string;
-}
-declare class IndexedDBStorageAdaptor implements StorageAdapter {
-  private readonly idb;
-  private readonly dbName;
-  private readonly version;
-  private readonly docStore;
-  private readonly docUpdateStore;
-  private readonly metaStore;
-  private readonly assetStore;
-  private readonly metaKey;
-  private dbPromise?;
-  private closed;
-  constructor(options?: IndexedDBStorageAdaptorOptions);
-  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>;
-  close(): Promise<void>;
-  private ensureDb;
-  private ensureStore;
-  private storeExists;
-  private storeMergedSnapshot;
-  private mergeSnapshots;
-  private appendDocUpdate;
-  private getDocUpdates;
-  private clearDocUpdates;
-  private writeSnapshot;
-  private getBinaryFromDb;
-  private normalizeUpdateQueue;
-  private putBinary;
-  private deleteKey;
-  private getBinary;
-  private runInTransaction;
-  private wrapRequest;
-  private normalizeBinary;
-  private createError;
-}
-//#endregion
-//#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>;
+  readonly options: LoroRepoOptions;
   private _destroyed;
   private readonly transport?;
   private readonly storage?;
@@ -642,7 +18,7 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   private readonly state;
   private readonly syncRunner;
   private constructor();
-  static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions<Meta>): Promise<LoroRepo<Meta>>;
+  static create<Meta extends JsonObject = JsonObject>(options: LoroRepoOptions): Promise<LoroRepo<Meta>>;
   /**
    * Load meta from storage.
    *
@@ -714,5 +90,5 @@ declare class LoroRepo<Meta extends JsonObject = JsonObject> {
   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, RepoEventKind, RepoEventListener, RepoEventType, type RepoSyncOptions, RepoWatchHandle, StorageAdapter, StorageSavePayload, SyncScope, TransportAdapter, type TransportJoinParams, type TransportSubscription, TransportSyncRequest, type TransportSyncResult, UploadAssetOptions, WebSocketTransportAdapter, type WebSocketTransportOptions };
+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 };
 //# sourceMappingURL=index.d.cts.map