loro-repo 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,670 @@
+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";
+
+//#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>;
+/**
+ * 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;
+  /**
+   * 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.
+   */
+  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 {
+  /**
+   * 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 {
+  /**
+   * 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;
+  /**
+   * Resolves once storage hydration and any queued remote updates complete.
+   */
+  readonly whenSyncedWithRemote: Promise<void>;
+  /**
+   * Unsubscribes listeners and releases resources associated with the document.
+   */
+  close(): Promise<void>;
+}
+interface UpsertDocMetaOptions {}
+/**
+ * Provenance discriminant attached to every repo event.
+ */
+type RepoEventBy = "local" | "sync" | "live";
+/**
+ * Unified event envelope 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;
+};
+/**
+ * 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/index.d.ts
+interface RepoAssetMetadata {
+  readonly assetId: AssetId;
+  readonly size: number;
+  readonly createdAt: number;
+  readonly mime?: string;
+  readonly policy?: string;
+  readonly tag?: string;
+}
+declare class LoroRepo<Meta extends JsonObject = JsonObject> {
+  readonly options: LoroRepoOptions<Meta>;
+  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;
+  sync(options?: RepoSyncOptions): Promise<void>;
+  private refreshDocMetadataEntry;
+  private refreshDocAssetsEntry;
+  private refreshAssetMetadataEntry;
+  private refreshDocFrontierKeys;
+  private readDocMetadataFromFlock;
+  private readDocAssetsFromFlock;
+  private readAssetMetadataFromFlock;
+  private handleAssetRemoval;
+  private emit;
+  joinMetaRoom(params?: TransportJoinParams): Promise<TransportSubscription>;
+  joinDocRoom(docId: string, params?: TransportJoinParams): Promise<TransportSubscription>;
+  close(): Promise<void>;
+  upsertDocMeta(docId: string, patch: Partial<Meta>, _options?: UpsertDocMetaOptions): Promise<void>;
+  getDocMeta(docId: string): Promise<Meta | undefined>;
+  listDoc(query?: ListDocQuery): Promise<RepoDocMeta<Meta>[]>;
+  getMetaReplica(): 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.
+   */
+  openCollaborativeDoc(docId: string): Promise<RepoDocHandle>;
+  /**
+   * Opens a detached `LoroDoc` snapshot that never registers with the repo, meaning
+   * it neither participates in remote subscriptions nor persists edits back to storage.
+   */
+  openDetachedDoc(docId: string): Promise<RepoDocHandle>;
+  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;
+}
+//#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