@dabble/patches 0.7.8 → 0.7.10

package/dist/{BaseDoc-_Rsau70J.d.ts → BaseDoc-BfVJNeCi.d.ts}

@@ -1,6 +1,6 @@
 import { Signal, Unsubscriber } from './event-signal.js';
 import { JSONPatchOp } from './json-patch/types.js';
-import { Change, PatchesSnapshot, SyncingState, ChangeMutator } from './types.js';
+import { Change, PatchesSnapshot, SyncedDoc, DocSyncStatus, ChangeMutator } from './types.js';
 
 /**
  * OT (Operational Transformation) document implementation.
@@ -96,9 +96,9 @@ interface PatchesDocOptions {
  * This interface is implemented by both OTDoc (Operational Transformation)
  * and LWWDoc (Last-Write-Wins) implementations via BaseDoc.
  *
- * Internal methods (updateSyncing, applyChanges, import) are on BaseDoc, not this interface.
+ * Internal methods (updateSyncStatus, applyChanges, import) are on BaseDoc, not this interface.
  */
-interface PatchesDoc<T extends object = object> {
+interface PatchesDoc<T extends object = object> extends SyncedDoc {
     /** The unique identifier for this document. */
     readonly id: string;
     /** Current local state (committed + pending merged). */
@@ -107,8 +107,12 @@ interface PatchesDoc<T extends object = object> {
     readonly committedRev: number;
     /** Are there local changes that haven't been committed yet? */
     readonly hasPending: boolean;
-    /** Are we currently syncing this document? */
-    readonly syncing: SyncingState;
+    /** Current sync status of this document. */
+    readonly syncStatus: DocSyncStatus;
+    /** Error from the last failed sync attempt, if any. */
+    readonly syncError: Error | null;
+    /** Whether the document has completed its initial load. Sticky: once true, never reverts to false. */
+    readonly isLoaded: boolean;
     /**
      * Subscribe to be notified when the user makes local changes.
      * Emits the JSON Patch ops captured from the change() call.
@@ -117,8 +121,8 @@ interface PatchesDoc<T extends object = object> {
     readonly onChange: Signal<(ops: JSONPatchOp[]) => void>;
     /** Subscribe to be notified whenever state changes from any source. */
     readonly onUpdate: Signal<(newState: T) => void>;
-    /** Subscribe to be notified when syncing state changes. */
-    readonly onSyncing: Signal<(newSyncing: SyncingState) => void>;
+    /** Subscribe to be notified when sync status changes. */
+    readonly onSyncStatus: Signal<(newStatus: DocSyncStatus) => void>;
     /** Subscribe to be notified whenever the state changes (calls immediately with current state). */
     subscribe(onUpdate: (newValue: T) => void): Unsubscriber;
     /**
@@ -137,13 +141,15 @@ interface PatchesDoc<T extends object = object> {
  * apply locally. The algorithm handles packaging ops, persisting them, and updating
  * the doc's state via `applyChanges()`.
  *
- * Internal methods (updateSyncing, applyChanges, import) are on this class but not
+ * Internal methods (updateSyncStatus, applyChanges, import) are on this class but not
  * on the PatchesDoc interface, as they're only used by Algorithm and PatchesSync.
  */
 declare abstract class BaseDoc<T extends object = object> implements PatchesDoc<T> {
     protected _id: string;
     protected _state: T;
-    protected _syncing: SyncingState;
+    protected _syncStatus: DocSyncStatus;
+    protected _syncError: Error | null;
+    protected _isLoaded: boolean;
     /**
      * Subscribe to be notified when the user makes local changes.
      * Emits the JSON Patch ops captured from the change() call.
@@ -152,8 +158,8 @@ declare abstract class BaseDoc<T extends object = object> implements PatchesDoc<
     readonly onChange: Signal<(ops: JSONPatchOp[]) => void>;
     /** Subscribe to be notified whenever state changes from any source. */
     readonly onUpdate: Signal<(newState: T) => void>;
-    /** Subscribe to be notified when syncing state changes. */
-    readonly onSyncing: Signal<(newSyncing: SyncingState) => void>;
+    /** Subscribe to be notified when sync status changes. */
+    readonly onSyncStatus: Signal<(newStatus: DocSyncStatus) => void>;
     /**
      * Creates an instance of BaseDoc.
      * @param id The unique identifier for this document.
@@ -164,8 +170,12 @@ declare abstract class BaseDoc<T extends object = object> implements PatchesDoc<
     get id(): string;
     /** Current local state (committed + pending merged). */
     get state(): T;
-    /** Are we currently syncing this document? */
-    get syncing(): SyncingState;
+    /** Current sync status of this document. */
+    get syncStatus(): DocSyncStatus;
+    /** Error from the last failed sync attempt, if any. */
+    get syncError(): Error | null;
+    /** Whether the document has completed its initial load. Sticky: once true, never reverts to false. */
+    get isLoaded(): boolean;
     /** Last committed revision number from the server. */
     abstract get committedRev(): number;
     /** Are there local changes that haven't been committed yet? */
@@ -179,11 +189,14 @@ declare abstract class BaseDoc<T extends object = object> implements PatchesDoc<
      */
     change(mutator: ChangeMutator<T>): void;
     /**
-     * Updates the syncing state of the document.
+     * Updates the sync status of the document.
      * Called by PatchesSync - not part of the app-facing PatchesDoc interface.
-     * @param newSyncing The new syncing state.
+     * @param status The new sync status.
+     * @param error Optional error when status is 'error'.
      */
-    updateSyncing(newSyncing: SyncingState): void;
+    updateSyncStatus(status: DocSyncStatus, error?: Error): void;
+    /** Latches _isLoaded to true when the doc has data or sync has resolved. */
+    protected _checkLoaded(): void;
     /**
      * Applies changes to the document state.
      * Called by Algorithm for local changes and broadcasts - not part of PatchesDoc interface.

package/dist/client/BaseDoc.d.ts

@@ -1,6 +1,6 @@
 import '../event-signal.js';
 import '../json-patch/types.js';
 import '../types.js';
-export { B as BaseDoc } from '../BaseDoc-_Rsau70J.js';
+export { B as BaseDoc } from '../BaseDoc-BfVJNeCi.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/BaseDoc.js

@@ -1,10 +1,13 @@
 import "../chunk-IZ2YBCUP.js";
 import { signal } from "../event-signal.js";
 import { createJSONPatch } from "../json-patch/createJSONPatch.js";
+import { isDocLoaded } from "../shared/utils.js";
 class BaseDoc {
   _id;
   _state;
-  _syncing = null;
+  _syncStatus = "unsynced";
+  _syncError = null;
+  _isLoaded = false;
   /**
    * Subscribe to be notified when the user makes local changes.
    * Emits the JSON Patch ops captured from the change() call.
@@ -13,8 +16,8 @@ class BaseDoc {
   onChange = signal();
   /** Subscribe to be notified whenever state changes from any source. */
   onUpdate = signal();
-  /** Subscribe to be notified when syncing state changes. */
-  onSyncing = signal();
+  /** Subscribe to be notified when sync status changes. */
+  onSyncStatus = signal();
   /**
    * Creates an instance of BaseDoc.
    * @param id The unique identifier for this document.
@@ -32,9 +35,17 @@ class BaseDoc {
   get state() {
     return this._state;
   }
-  /** Are we currently syncing this document? */
-  get syncing() {
-    return this._syncing;
+  /** Current sync status of this document. */
+  get syncStatus() {
+    return this._syncStatus;
+  }
+  /** Error from the last failed sync attempt, if any. */
+  get syncError() {
+    return this._syncError;
+  }
+  /** Whether the document has completed its initial load. Sticky: once true, never reverts to false. */
+  get isLoaded() {
+    return this._isLoaded;
   }
   /** Subscribe to be notified whenever the state changes (calls immediately with current state). */
   subscribe(onUpdate) {
@@ -56,13 +67,22 @@ class BaseDoc {
   }
   // --- Internal methods (not on PatchesDoc interface) ---
   /**
-   * Updates the syncing state of the document.
+   * Updates the sync status of the document.
    * Called by PatchesSync - not part of the app-facing PatchesDoc interface.
-   * @param newSyncing The new syncing state.
+   * @param status The new sync status.
+   * @param error Optional error when status is 'error'.
    */
-  updateSyncing(newSyncing) {
-    this._syncing = newSyncing;
-    this.onSyncing.emit(newSyncing);
+  updateSyncStatus(status, error) {
+    this._syncStatus = status;
+    this._syncError = status === "error" ? error ?? null : null;
+    this._checkLoaded();
+    this.onSyncStatus.emit(status);
+  }
+  /** Latches _isLoaded to true when the doc has data or sync has resolved. */
+  _checkLoaded() {
+    if (!this._isLoaded && isDocLoaded(this)) {
+      this._isLoaded = true;
+    }
   }
 }
 export {

package/dist/client/ClientAlgorithm.d.ts

@@ -1,6 +1,6 @@
 import { JSONPatchOp } from '../json-patch/types.js';
 import { PatchesSnapshot, Change } from '../types.js';
-import { a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
+import { a as PatchesDoc } from '../BaseDoc-BfVJNeCi.js';
 import { PatchesStore, TrackedDoc } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/LWWAlgorithm.d.ts

@@ -2,7 +2,7 @@ import { JSONPatchOp } from '../json-patch/types.js';
 import { PatchesSnapshot, Change } from '../types.js';
 import { ClientAlgorithm } from './ClientAlgorithm.js';
 import { LWWClientStore } from './LWWClientStore.js';
-import { a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
+import { a as PatchesDoc } from '../BaseDoc-BfVJNeCi.js';
 import { TrackedDoc } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/LWWDoc.d.ts

@@ -1,5 +1,5 @@
 import { PatchesSnapshot, Change } from '../types.js';
-import { B as BaseDoc } from '../BaseDoc-_Rsau70J.js';
+import { B as BaseDoc } from '../BaseDoc-BfVJNeCi.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';

package/dist/client/LWWDoc.js

@@ -21,6 +21,7 @@ class LWWDoc extends BaseDoc {
         }
       }
     }
+    this._checkLoaded();
   }
   /** Last committed revision number from the server. */
   get committedRev() {
@@ -45,6 +46,7 @@ class LWWDoc extends BaseDoc {
         }
       }
     }
+    this._checkLoaded();
     this.onUpdate.emit(this._state);
   }
   /**
@@ -78,6 +80,7 @@ class LWWDoc extends BaseDoc {
     }
     this._committedRev = lastCommittedRev;
     this._hasPending = hasPending ?? hasPendingChanges;
+    this._checkLoaded();
     this.onUpdate.emit(this._state);
   }
 }

package/dist/client/OTAlgorithm.d.ts

@@ -2,7 +2,7 @@ import { JSONPatchOp } from '../json-patch/types.js';
 import { PatchesSnapshot, Change } from '../types.js';
 import { ClientAlgorithm } from './ClientAlgorithm.js';
 import { OTClientStore } from './OTClientStore.js';
-import { P as PatchesDocOptions, a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
+import { P as PatchesDocOptions, a as PatchesDoc } from '../BaseDoc-BfVJNeCi.js';
 import { TrackedDoc } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/OTDoc.d.ts

@@ -1,5 +1,5 @@
 import '../types.js';
-export { O as OTDoc } from '../BaseDoc-_Rsau70J.js';
+export { O as OTDoc } from '../BaseDoc-BfVJNeCi.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';

package/dist/client/OTDoc.js

@@ -23,6 +23,7 @@ class OTDoc extends BaseDoc {
     if (this._pendingChanges.length > 0) {
       this._state = applyChangesToState(this._committedState, this._pendingChanges);
     }
+    this._checkLoaded();
   }
   /** Last committed revision number from the server. */
   get committedRev() {
@@ -48,6 +49,7 @@ class OTDoc extends BaseDoc {
     this._committedRev = snapshot.rev;
     this._pendingChanges = snapshot.changes;
     this._state = createStateFromSnapshot(snapshot);
+    this._checkLoaded();
     this.onUpdate.emit(this._state);
   }
   /**
@@ -79,6 +81,7 @@ class OTDoc extends BaseDoc {
       this._state = applyChangesToState(this._state, changes);
       this._pendingChanges.push(...changes);
     }
+    this._checkLoaded();
     this.onUpdate.emit(this._state);
   }
   /**

package/dist/client/Patches.d.ts

@@ -2,7 +2,7 @@ import { Unsubscriber, Signal } from '../event-signal.js';
 import { JSONPatchOp } from '../json-patch/types.js';
 import { Change } from '../types.js';
 import { ClientAlgorithm } from './ClientAlgorithm.js';
-import { P as PatchesDocOptions, a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
+import { P as PatchesDocOptions, a as PatchesDoc } from '../BaseDoc-BfVJNeCi.js';
 import { AlgorithmName } from './PatchesStore.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/PatchesDoc.d.ts

@@ -1,6 +1,6 @@
 import '../event-signal.js';
 import '../json-patch/types.js';
 import '../types.js';
-export { O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from '../BaseDoc-_Rsau70J.js';
+export { O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from '../BaseDoc-BfVJNeCi.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/factories.d.ts

@@ -1,6 +1,6 @@
 import { AlgorithmName } from './PatchesStore.js';
 import { Patches } from './Patches.js';
-import { P as PatchesDocOptions } from '../BaseDoc-_Rsau70J.js';
+import { P as PatchesDocOptions } from '../BaseDoc-BfVJNeCi.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-export { B as BaseDoc, O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from '../BaseDoc-_Rsau70J.js';
+export { B as BaseDoc, O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from '../BaseDoc-BfVJNeCi.js';
 export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches } from './factories.js';
 export { IDBStoreWrapper, IDBTransactionWrapper, IndexedDBStore } from './IndexedDBStore.js';
 export { OTIndexedDBStore } from './OTIndexedDBStore.js';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { Delta } from '@dabble/delta';
-export { B as BaseDoc, O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from './BaseDoc-_Rsau70J.js';
+export { B as BaseDoc, O as OTDoc, a as PatchesDoc, O as PatchesDocClass, P as PatchesDocOptions } from './BaseDoc-BfVJNeCi.js';
 export { IndexedDBFactoryOptions, MultiAlgorithmFactoryOptions, MultiAlgorithmIndexedDBFactoryOptions, PatchesFactoryOptions, createLWWIndexedDBPatches, createLWWPatches, createMultiAlgorithmIndexedDBPatches, createMultiAlgorithmPatches, createOTIndexedDBPatches, createOTPatches } from './client/factories.js';
 export { IDBStoreWrapper, IDBTransactionWrapper, IndexedDBStore } from './client/IndexedDBStore.js';
 export { OTIndexedDBStore } from './client/OTIndexedDBStore.js';
@@ -29,7 +29,7 @@ export { createPathProxy, pathProxy } from './json-patch/pathProxy.js';
 export { transformPatch } from './json-patch/transformPatch.js';
 export { JSONPatch, PathLike, WriteOptions } from './json-patch/JSONPatch.js';
 export { ApplyJSONPatchOptions, JSONPatchOpHandlerMap as JSONPatchCustomTypes, JSONPatchOp } from './json-patch/types.js';
-export { Branch, BranchStatus, Change, ChangeInput, ChangeMutator, CommitChangesOptions, DeleteDocOptions, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, SyncingState, VersionMetadata } from './types.js';
+export { Branch, BranchStatus, Change, ChangeInput, ChangeMutator, CommitChangesOptions, DeleteDocOptions, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, SyncedDoc, VersionMetadata } from './types.js';
 export { add } from './json-patch/ops/add.js';
 export { copy } from './json-patch/ops/copy.js';
 export { increment } from './json-patch/ops/increment.js';

package/dist/net/PatchesSync.d.ts

@@ -1,24 +1,26 @@
 import { Signal } from '../event-signal.js';
 import { ConnectionState } from './protocol/types.js';
-import { SyncingState, Change } from '../types.js';
+import { DocSyncStatus, SyncedDoc, Change } from '../types.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
 import { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
 import { WebSocketOptions } from './websocket/WebSocketTransport.js';
 import { SizeCalculator } from '../algorithms/ot/shared/changeBatching.js';
+import { ClientAlgorithm } from '../client/ClientAlgorithm.js';
 import { Patches } from '../client/Patches.js';
 import { AlgorithmName } from '../client/PatchesStore.js';
-import { ClientAlgorithm } from '../client/ClientAlgorithm.js';
+export { isDocLoaded } from '../shared/utils.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../json-patch/types.js';
 import './PatchesClient.js';
 import '../utils/deferred.js';
-import '../BaseDoc-_Rsau70J.js';
+import '../BaseDoc-BfVJNeCi.js';
 
 interface PatchesSyncState {
     online: boolean;
     connected: boolean;
-    syncing: SyncingState;
+    syncStatus: DocSyncStatus;
+    syncError: Error | null;
 }
 interface PatchesSyncOptions {
     subscribeFilter?: (docIds: string[]) => string[];
@@ -30,6 +32,7 @@ interface PatchesSyncOptions {
     /** Custom size calculator for storage limit. Falls back to patches.docOptions.sizeCalculator. */
     sizeCalculator?: SizeCalculator;
 }
+
 /**
  * Handles WebSocket connection, document subscriptions, and syncing logic between
  * the Patches instance and the server.
@@ -50,6 +53,7 @@ declare class PatchesSync {
     /** Maps docId to the algorithm name used for that doc */
     protected docAlgorithms: Map<string, AlgorithmName>;
     protected _state: PatchesSyncState;
+    protected _syncedDocs: Record<string, SyncedDoc>;
     /**
      * Signal emitted when the sync state changes.
      */
@@ -65,6 +69,10 @@ declare class PatchesSync {
      * Provides the pending changes that were discarded so the application can handle them.
      */
     readonly onRemoteDocDeleted: Signal<(docId: string, pendingChanges: Change[]) => void>;
+    /**
+     * Signal emitted when the synced doc map changes.
+     */
+    readonly onSyncedDocsChange: Signal<(synced: Record<string, SyncedDoc>) => void>;
     constructor(patches: Patches, url: string, options?: PatchesSyncOptions | undefined);
     /**
      * Gets the algorithm for a document. Uses the open doc's algorithm if available,
@@ -83,6 +91,11 @@ declare class PatchesSync {
      * Gets the current sync state.
      */
     get state(): PatchesSyncState;
+    /**
+     * Map of all tracked documents and their current sync status.
+     * Updated immutably — new object reference on every change.
+     */
+    get syncedDocs(): Record<string, SyncedDoc>;
     /**
      * Gets the JSON-RPC client for making custom RPC calls.
      * Useful for application-specific methods not part of the Patches protocol.
@@ -142,6 +155,31 @@ declare class PatchesSync {
      * Cleans up local state and notifies the application with any pending changes that were lost.
      */
     protected _handleRemoteDocDeleted(docId: string): Promise<void>;
+    /**
+     * Adds, updates, or removes a synced doc entry immutably and emits onSyncedChange.
+     * - Pass a full SyncedDoc to add a new entry or overwrite an existing one.
+     * - Pass a Partial<SyncedDoc> to merge into an existing entry (no-ops if doc not in map).
+     * - Pass undefined to remove the entry.
+     * No-ops if nothing actually changed.
+     */
+    protected _updateSyncedDoc(docId: string, updates: Partial<SyncedDoc> | undefined, emit?: boolean): void;
+    protected _emitSyncedChange(): void;
+    /**
+     * Resets any docs with status 'syncing' back to a stable state on disconnect.
+     * Uses hasPending to decide: pending docs become 'synced' (they have local data),
+     * docs with no pending and no committed rev become 'unsynced'.
+     */
+    protected _resetSyncingStatuses(): void;
+    /**
+     * Applies the subscribeFilter option to a list of doc IDs, returning the subset
+     * that should be sent to ws.subscribe/unsubscribe. Returns the full list if no filter is set.
+     */
+    protected _filterSubscribeIds(docIds: string[]): string[];
+    /**
+     * Returns the set of doc IDs currently subscribed on the server, derived by
+     * applying the subscribe filter to the full tracked set.
+     */
+    protected _getActiveSubscriptions(): Set<string>;
     /**
      * Helper to detect DOC_DELETED (410) errors from the server.
      */