@dabble/patches 0.2.6 → 0.2.8

package/dist/client/Patches.d.ts

@@ -30,35 +30,87 @@ export declare class Patches {
     readonly onUntrackDocs: import("../event-signal.js").Signal<(docIds: string[]) => void>;
     readonly onDeleteDoc: import("../event-signal.js").Signal<(docId: string) => void>;
     constructor(opts: PatchesOptions);
+    /**
+     * Tracks the given document IDs, adding them to the set of tracked documents and notifying listeners.
+     * Tracked docs are kept in sync with the server, even when not open locally.
+     * This allows for background syncing and updates of unopened documents.
+     * @param docIds - Array of document IDs to track.
+     */
     trackDocs(docIds: string[]): Promise<void>;
+    /**
+     * Untracks the given document IDs, removing them from the set of tracked documents and notifying listeners.
+     * Untracked docs will no longer be kept in sync with the server, even if not open locally.
+     * Closes any open docs and removes them from the store.
+     * @param docIds - Array of document IDs to untrack.
+     */
     untrackDocs(docIds: string[]): Promise<void>;
+    /**
+     * Opens a document by ID, loading its state from the store and setting up change listeners.
+     * If the doc is already open, returns the existing instance.
+     * @param docId - The document ID to open.
+     * @param opts - Optional metadata to merge with the doc's metadata.
+     * @returns The opened PatchesDoc instance.
+     */
     openDoc<T extends object>(docId: string, opts?: {
         metadata?: Record<string, any>;
     }): Promise<PatchesDoc<T>>;
-    closeDoc(docId: string): Promise<void>;
+    /**
+     * Closes an open document by ID, removing listeners and optionally untracking it.
+     * @param docId - The document ID to close.
+     * @param options - Optional: set untrack to true to also untrack the doc.
+     */
+    closeDoc(docId: string, { untrack }?: {
+        untrack?: boolean;
+    }): Promise<void>;
+    /**
+     * Deletes a document by ID, closing it if open, untracking it, and removing it from the store.
+     * Emits the onDeleteDoc signal.
+     * @param docId - The document ID to delete.
+     */
     deleteDoc(docId: string): Promise<void>;
     /**
-     * Gets all tracked document IDs that are currently open.
-     * Used by PatchesSync to check which docs need syncing.
+     * Gets all tracked document IDs that are currently open in memory.
+     * Used by PatchesSync to determine which docs need syncing.
+     * @returns Array of open document IDs.
      */
     getOpenDocIds(): string[];
     /**
-     * Retrieves changes for a document that should be sent to the server.
+     * Retrieves local changes for a document that should be sent to the server.
      * Used by PatchesSync during synchronization.
+     * @param docId - The document ID to get changes for.
+     * @returns Array of Change objects to send to the server.
      */
     getDocChanges(docId: string): Change[];
     /**
-     * Handles failure to send changes to the server.
+     * Handles a failure to send changes to the server for a given document.
      * Used by PatchesSync to requeue changes after failures.
+     * @param docId - The document ID for which sending failed.
      */
     handleSendFailure(docId: string): void;
     /**
-     * Apply server changes to a document.
+     * Applies server-confirmed changes to a document.
      * Used by PatchesSync to update documents with server changes.
+     * @param docId - The document ID to apply changes to.
+     * @param changes - Array of Change objects from the server.
      */
     applyServerChanges(docId: string, changes: Change[]): void;
+    /**
+     * Closes all open documents and cleans up listeners and store connections.
+     * Should be called when shutting down the client.
+     */
     close(): void;
+    /**
+     * Sets up a listener for local changes on a PatchesDoc, saving pending changes to the store.
+     * @param docId - The document ID being managed.
+     * @param doc - The PatchesDoc instance to listen to.
+     * @returns An Unsubscriber function to remove the listener.
+     */
     protected _setupLocalDocListener(docId: string, doc: PatchesDoc<any>): Unsubscriber;
+    /**
+     * Internal handler for applying server commits to a document and emitting errors if needed.
+     * @param docId - The document ID to update.
+     * @param changes - Array of Change objects from the server.
+     */
     private _handleServerCommit;
 }
 export {};

package/dist/client/Patches.js

@@ -15,6 +15,11 @@ export class Patches {
         this.onTrackDocs = signal();
         this.onUntrackDocs = signal();
         this.onDeleteDoc = signal();
+        /**
+         * Internal handler for applying server commits to a document and emitting errors if needed.
+         * @param docId - The document ID to update.
+         * @param changes - Array of Change objects from the server.
+         */
         this._handleServerCommit = (docId, changes) => {
             const managedDoc = this.docs.get(docId);
             if (managedDoc) {
@@ -36,6 +41,12 @@ export class Patches {
         });
     }
     // --- Public API Methods ---
+    /**
+     * Tracks the given document IDs, adding them to the set of tracked documents and notifying listeners.
+     * Tracked docs are kept in sync with the server, even when not open locally.
+     * This allows for background syncing and updates of unopened documents.
+     * @param docIds - Array of document IDs to track.
+     */
     async trackDocs(docIds) {
         docIds = docIds.filter(id => !this.trackedDocs.has(id));
         if (!docIds.length)
@@ -44,6 +55,12 @@ export class Patches {
         this.onTrackDocs.emit(docIds);
         await this.store.trackDocs(docIds);
     }
+    /**
+     * Untracks the given document IDs, removing them from the set of tracked documents and notifying listeners.
+     * Untracked docs will no longer be kept in sync with the server, even if not open locally.
+     * Closes any open docs and removes them from the store.
+     * @param docIds - Array of document IDs to untrack.
+     */
     async untrackDocs(docIds) {
         docIds = docIds.filter(id => this.trackedDocs.has(id));
         if (!docIds.length)
@@ -56,6 +73,13 @@ export class Patches {
         // Remove from store
         await this.store.untrackDocs(docIds);
     }
+    /**
+     * Opens a document by ID, loading its state from the store and setting up change listeners.
+     * If the doc is already open, returns the existing instance.
+     * @param docId - The document ID to open.
+     * @param opts - Optional metadata to merge with the doc's metadata.
+     * @returns The opened PatchesDoc instance.
+     */
     async openDoc(docId, opts = {}) {
         const existing = this.docs.get(docId);
         if (existing)
@@ -76,16 +100,26 @@ export class Patches {
         this.docs.set(docId, { doc, onChangeUnsubscriber: unsub });
         return doc;
     }
-    async closeDoc(docId) {
+    /**
+     * Closes an open document by ID, removing listeners and optionally untracking it.
+     * @param docId - The document ID to close.
+     * @param options - Optional: set untrack to true to also untrack the doc.
+     */
+    async closeDoc(docId, { untrack = false } = {}) {
         const managed = this.docs.get(docId);
         if (managed) {
             managed.onChangeUnsubscriber();
             this.docs.delete(docId);
-            // Note: We do NOT call untrackDocs here automatically.
-            // Closing a doc just removes it from memory; it remains tracked
-            // for background sync unless explicitly untracked.
+            if (untrack) {
+                await this.untrackDocs([docId]);
+            }
         }
     }
+    /**
+     * Deletes a document by ID, closing it if open, untracking it, and removing it from the store.
+     * Emits the onDeleteDoc signal.
+     * @param docId - The document ID to delete.
+     */
     async deleteDoc(docId) {
         // Close if open locally
         if (this.docs.has(docId)) {
@@ -100,15 +134,18 @@ export class Patches {
         this.onDeleteDoc.emit(docId);
     }
     /**
-     * Gets all tracked document IDs that are currently open.
-     * Used by PatchesSync to check which docs need syncing.
+     * Gets all tracked document IDs that are currently open in memory.
+     * Used by PatchesSync to determine which docs need syncing.
+     * @returns Array of open document IDs.
      */
     getOpenDocIds() {
         return Array.from(this.docs.keys());
     }
     /**
-     * Retrieves changes for a document that should be sent to the server.
+     * Retrieves local changes for a document that should be sent to the server.
      * Used by PatchesSync during synchronization.
+     * @param docId - The document ID to get changes for.
+     * @returns Array of Change objects to send to the server.
      */
     getDocChanges(docId) {
         const doc = this.docs.get(docId)?.doc;
@@ -124,8 +161,9 @@ export class Patches {
         }
     }
     /**
-     * Handles failure to send changes to the server.
+     * Handles a failure to send changes to the server for a given document.
      * Used by PatchesSync to requeue changes after failures.
+     * @param docId - The document ID for which sending failed.
      */
     handleSendFailure(docId) {
         const doc = this.docs.get(docId)?.doc;
@@ -134,12 +172,18 @@ export class Patches {
         }
     }
     /**
-     * Apply server changes to a document.
+     * Applies server-confirmed changes to a document.
      * Used by PatchesSync to update documents with server changes.
+     * @param docId - The document ID to apply changes to.
+     * @param changes - Array of Change objects from the server.
      */
     applyServerChanges(docId, changes) {
         this._handleServerCommit(docId, changes);
     }
+    /**
+     * Closes all open documents and cleans up listeners and store connections.
+     * Should be called when shutting down the client.
+     */
     close() {
         // Clean up local PatchesDoc listeners
         this.docs.forEach(managed => managed.onChangeUnsubscriber());
@@ -148,6 +192,12 @@ export class Patches {
         void this.store.close();
     }
     // --- Internal Handlers ---
+    /**
+     * Sets up a listener for local changes on a PatchesDoc, saving pending changes to the store.
+     * @param docId - The document ID being managed.
+     * @param doc - The PatchesDoc instance to listen to.
+     * @returns An Unsubscriber function to remove the listener.
+     */
     _setupLocalDocListener(docId, doc) {
         return doc.onChange(async () => {
             const changes = doc.getUpdatesForServer();

package/dist/client/PatchesDoc.d.ts

@@ -30,8 +30,6 @@ export declare class PatchesDoc<T extends object = object> {
     get id(): string | null;
     /** Current local state (committed + sending + pending). */
     get state(): T;
-    /** Alias for state. */
-    get value(): T;
     /** Last committed revision number from the server. */
     get committedRev(): number;
     /** Are there changes currently awaiting server confirmation? */

package/dist/client/PatchesDoc.js

@@ -37,10 +37,6 @@ export class PatchesDoc {
     get state() {
         return this._state;
     }
-    /** Alias for state. */
-    get value() {
-        return this._state;
-    }
     /** Last committed revision number from the server. */
     get committedRev() {
         return this._committedRev;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {