@dabble/patches 0.2.15 → 0.2.17

package/dist/server/PatchesServer.d.ts

@@ -1,4 +1,4 @@
-import type { Change, ListVersionsOptions, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
+import type { Change, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
 import type { PatchesStoreBackend } from './types.js';
 /**
  * Configuration options for the PatchesServer.
@@ -17,18 +17,21 @@ export interface PatchesServerOptions {
  * and persisting data using a backend store.
  */
 export declare class PatchesServer {
-    private readonly store;
+    readonly store: PatchesStoreBackend;
     private readonly sessionTimeoutMillis;
     constructor(store: PatchesStoreBackend, options?: PatchesServerOptions);
     /**
      * Subscribes the connected client to one or more documents.
+     * @param clientId - The ID of the client.
      * @param ids Document ID(s) to subscribe to.
      * @returns A list of document IDs the client is now successfully subscribed to.
      */
     subscribe(clientId: string, ids: string | string[]): Promise<string[]>;
     /**
      * Unsubscribes the connected client from one or more documents.
+     * @param clientId - The ID of the client.
      * @param ids Document ID(s) to unsubscribe from.
+     * @returns A list of document IDs the client is now successfully unsubscribed from.
      */
     unsubscribe(clientId: string, ids: string | string[]): Promise<string[]>;
     /**
@@ -53,16 +56,6 @@ export declare class PatchesServer {
      *   - transformedChanges: The client's changes after being transformed against concurrent changes
      */
     commitChanges(docId: string, changes: Change[]): Promise<[Change[], Change[]]>;
-    /**
-     * Handles offline/large batch versioning logic for multi-batch uploads.
-     * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
-     * @param docId Document ID
-     * @param changes The incoming changes (all with the same batchId)
-     * @param baseRev The base revision for the batch
-     * @param batchId The batch identifier
-     * @returns The collapsed changes for transformation
-     */
-    private handleOfflineBatches;
     /**
      * Deletes a document.
      * @param docId The document ID.
@@ -76,33 +69,12 @@ export declare class PatchesServer {
      */
     createVersion(docId: string, name: string): Promise<string>;
     /**
-     * Lists version metadata for a document, supporting various filters.
-     * @param docId The document ID.
-     * @param options Filtering and sorting options.
-     * @returns A list of version metadata objects.
-     */
-    listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
-    /**
-     * Get the state snapshot for a specific version ID.
-     * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @returns The state snapshot for the specified version.
-     */
-    getVersionState(docId: string, versionId: string): Promise<PatchesState>;
-    /**
-     * Get the original Change objects associated with a specific version ID.
-     * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @returns The original Change objects for the specified version.
-     */
-    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
-    /**
-     * Update the name of a specific version.
+     * Gets the state at a specific revision.
      * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @param name The new name for the version.
+     * @param rev The revision number. If not provided, the latest state and its revision is returned.
+     * @returns The state at the specified revision *and* its revision number.
      */
-    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+    getStateAtRevision(docId: string, rev?: number): Promise<PatchesState>;
     /**
      * Retrieves the document state of the version before the given revision and changes after up to that revision or all
      * changes since that version.
@@ -110,14 +82,7 @@ export declare class PatchesServer {
      * @param rev The revision number. If not provided, the latest state, its revision, and all changes since are returned.
      * @returns The document state at the last version before the revision, its revision number, and all changes up to the specified revision (or all changes if no revision is provided).
      */
-    _getSnapshotAtRevision(docId: string, rev?: number): Promise<PatchesSnapshot>;
-    /**
-     * Gets the state at a specific revision.
-     * @param docId The document ID.
-     * @param rev The revision number. If not provided, the latest state and its revision is returned.
-     * @returns The state at the specified revision *and* its revision number.
-     */
-    _getStateAtRevision(docId: string, rev?: number): Promise<PatchesState>;
+    protected _getSnapshotAtRevision(docId: string, rev?: number): Promise<PatchesSnapshot>;
     /**
      * Creates a new version snapshot of a document's current state.
      * @param docId The document ID.
@@ -126,5 +91,15 @@ export declare class PatchesServer {
      * @param name The name of the version.
      * @returns The ID of the created version.
      */
-    _createVersion(docId: string, state: any, changes: Change[], name?: string): Promise<VersionMetadata | undefined>;
+    protected _createVersion(docId: string, state: any, changes: Change[], name?: string): Promise<VersionMetadata | undefined>;
+    /**
+     * Handles offline/large batch versioning logic for multi-batch uploads.
+     * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
+     * @param docId Document ID
+     * @param changes The incoming changes (all with the same batchId)
+     * @param baseRev The base revision for the batch
+     * @param batchId The batch identifier
+     * @returns The collapsed changes for transformation
+     */
+    protected _handleOfflineBatches(docId: string, changes: Change[], baseRev: number, batchId?: string): Promise<Change[]>;
 }

package/dist/server/PatchesServer.js

@@ -16,6 +16,7 @@ export class PatchesServer {
     // === Subscription Operations ===
     /**
      * Subscribes the connected client to one or more documents.
+     * @param clientId - The ID of the client.
      * @param ids Document ID(s) to subscribe to.
      * @returns A list of document IDs the client is now successfully subscribed to.
      */
@@ -24,7 +25,9 @@ export class PatchesServer {
     }
     /**
      * Unsubscribes the connected client from one or more documents.
+     * @param clientId - The ID of the client.
      * @param ids Document ID(s) to unsubscribe from.
+     * @returns A list of document IDs the client is now successfully unsubscribed from.
      */
     unsubscribe(clientId, ids) {
         return this.store.removeSubscription(clientId, Array.isArray(ids) ? ids : [ids]);
@@ -109,12 +112,12 @@ export class PatchesServer {
         // - or the first change is older than the session timeout (single-batch offline)
         const isOfflineTimestamp = changes[0].created < Date.now() - this.sessionTimeoutMillis;
         if (isOfflineTimestamp || batchId) {
-            changes = await this.handleOfflineBatches(docId, changes, baseRev, batchId);
+            changes = await this._handleOfflineBatches(docId, changes, baseRev, batchId);
         }
         // 5. Transform the *entire batch* of incoming (and potentially collapsed offline) changes
         //    against committed changes that happened *after* the client's baseRev.
         //    The state used for transformation should be the server state *at the client's baseRev*.
-        let stateAtBaseRev = (await this._getStateAtRevision(docId, baseRev)).state;
+        let stateAtBaseRev = (await this.getStateAtRevision(docId, baseRev)).state;
         const committedOps = committedChanges.flatMap(c => c.ops);
         // Apply transformation based on state at baseRev
         const transformedChanges = changes
@@ -142,84 +145,6 @@ export class PatchesServer {
         // Return committed changes and newly transformed changes separately
         return [committedChanges, transformedChanges];
     }
-    /**
-     * Handles offline/large batch versioning logic for multi-batch uploads.
-     * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
-     * @param docId Document ID
-     * @param changes The incoming changes (all with the same batchId)
-     * @param baseRev The base revision for the batch
-     * @param batchId The batch identifier
-     * @returns The collapsed changes for transformation
-     */
-    async handleOfflineBatches(docId, changes, baseRev, batchId) {
-        // Use batchId as groupId for multi-batch uploads; default offline sessions have no groupId
-        const groupId = batchId ?? createId();
-        // Find the last version for this groupId (if any)
-        const [lastVersion] = await this.store.listVersions(docId, {
-            groupId,
-            reverse: true,
-            limit: 1,
-        });
-        let offlineBaseState;
-        let parentId;
-        if (lastVersion) {
-            // Continue from the last version's state
-            // loadVersionState returns a PatchState ({state, rev}); extract the .state
-            const vs = await this.store.loadVersionState(docId, lastVersion.id);
-            offlineBaseState = vs.state ?? vs;
-            parentId = lastVersion.id;
-        }
-        else {
-            // First batch for this batchId: start at baseRev
-            offlineBaseState = (await this._getStateAtRevision(docId, baseRev)).state;
-        }
-        let sessionStartIndex = 0;
-        for (let i = 1; i <= changes.length; i++) {
-            const isLastChange = i === changes.length;
-            const timeDiff = isLastChange ? Infinity : changes[i].created - changes[i - 1].created;
-            // Session ends if timeout exceeded OR it's the last change in the batch
-            if (timeDiff > this.sessionTimeoutMillis || isLastChange) {
-                const sessionChanges = changes.slice(sessionStartIndex, i);
-                if (sessionChanges.length > 0) {
-                    // Check if this is a continuation of the previous session (merge/extend)
-                    const isContinuation = !!lastVersion && sessionChanges[0].created - lastVersion.endDate <= this.sessionTimeoutMillis;
-                    if (isContinuation) {
-                        // Merge/extend the existing version
-                        const mergedState = applyChanges(offlineBaseState, sessionChanges);
-                        await this.store.saveChanges(docId, sessionChanges);
-                        await this.store.updateVersion(docId, lastVersion.id, {}); // metadata already updated above
-                        offlineBaseState = mergedState;
-                        parentId = lastVersion.parentId;
-                    }
-                    else {
-                        // Create a new version for this session
-                        offlineBaseState = applyChanges(offlineBaseState, sessionChanges);
-                        const versionId = createId();
-                        const sessionMetadata = {
-                            id: versionId,
-                            parentId,
-                            groupId,
-                            origin: 'offline',
-                            startDate: sessionChanges[0].created,
-                            endDate: sessionChanges[sessionChanges.length - 1].created,
-                            rev: sessionChanges[sessionChanges.length - 1].rev,
-                            baseRev,
-                        };
-                        await this.store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
-                        parentId = versionId;
-                    }
-                    sessionStartIndex = i;
-                }
-            }
-        }
-        // Collapse all changes into one for transformation
-        return [
-            changes.reduce((firstChange, nextChange) => {
-                firstChange.ops = [...firstChange.ops, ...nextChange.ops];
-                return firstChange;
-            }),
-        ];
-    }
     /**
      * Deletes a document.
      * @param docId The document ID.
@@ -244,43 +169,20 @@ export class PatchesServer {
         return version.id;
     }
     /**
-     * Lists version metadata for a document, supporting various filters.
-     * @param docId The document ID.
-     * @param options Filtering and sorting options.
-     * @returns A list of version metadata objects.
-     */
-    listVersions(docId, options) {
-        if (!options.orderBy) {
-            options.orderBy = 'startDate';
-        }
-        return this.store.listVersions(docId, options);
-    }
-    /**
-     * Get the state snapshot for a specific version ID.
-     * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @returns The state snapshot for the specified version.
-     */
-    getVersionState(docId, versionId) {
-        return this.store.loadVersionState(docId, versionId);
-    }
-    /**
-     * Get the original Change objects associated with a specific version ID.
-     * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @returns The original Change objects for the specified version.
-     */
-    getVersionChanges(docId, versionId) {
-        return this.store.loadVersionChanges(docId, versionId);
-    }
-    /**
-     * Update the name of a specific version.
+     * Gets the state at a specific revision.
      * @param docId The document ID.
-     * @param versionId The ID of the version.
-     * @param name The new name for the version.
+     * @param rev The revision number. If not provided, the latest state and its revision is returned.
+     * @returns The state at the specified revision *and* its revision number.
      */
-    updateVersion(docId, versionId, name) {
-        return this.store.updateVersion(docId, versionId, { name });
+    async getStateAtRevision(docId, rev) {
+        // Note: _getSnapshotAtRevision now returns the state *of the version* and changes *since* it.
+        // We need to apply the changes to get the state *at* the target revision.
+        const { state: versionState, rev: snapshotRev, changes } = await this._getSnapshotAtRevision(docId, rev);
+        return {
+            // Ensure null is passed if versionState or versionState.state is null/undefined
+            state: applyChanges(versionState?.state ?? null, changes),
+            rev: changes.at(-1)?.rev ?? snapshotRev,
+        };
     }
     /**
      * Retrieves the document state of the version before the given revision and changes after up to that revision or all
@@ -311,22 +213,6 @@ export class PatchesServer {
             changes: changesSinceVersion, // Changes that occurred *after* the base version state
         };
     }
-    /**
-     * Gets the state at a specific revision.
-     * @param docId The document ID.
-     * @param rev The revision number. If not provided, the latest state and its revision is returned.
-     * @returns The state at the specified revision *and* its revision number.
-     */
-    async _getStateAtRevision(docId, rev) {
-        // Note: _getSnapshotAtRevision now returns the state *of the version* and changes *since* it.
-        // We need to apply the changes to get the state *at* the target revision.
-        const { state: versionState, rev: snapshotRev, changes } = await this._getSnapshotAtRevision(docId, rev);
-        return {
-            // Ensure null is passed if versionState or versionState.state is null/undefined
-            state: applyChanges(versionState?.state ?? null, changes),
-            rev: changes.at(-1)?.rev ?? snapshotRev,
-        };
-    }
     /**
      * Creates a new version snapshot of a document's current state.
      * @param docId The document ID.
@@ -355,4 +241,82 @@ export class PatchesServer {
         await this.store.createVersion(docId, sessionMetadata, state, changes);
         return sessionMetadata;
     }
+    /**
+     * Handles offline/large batch versioning logic for multi-batch uploads.
+     * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
+     * @param docId Document ID
+     * @param changes The incoming changes (all with the same batchId)
+     * @param baseRev The base revision for the batch
+     * @param batchId The batch identifier
+     * @returns The collapsed changes for transformation
+     */
+    async _handleOfflineBatches(docId, changes, baseRev, batchId) {
+        // Use batchId as groupId for multi-batch uploads; default offline sessions have no groupId
+        const groupId = batchId ?? createId();
+        // Find the last version for this groupId (if any)
+        const [lastVersion] = await this.store.listVersions(docId, {
+            groupId,
+            reverse: true,
+            limit: 1,
+        });
+        let offlineBaseState;
+        let parentId;
+        if (lastVersion) {
+            // Continue from the last version's state
+            // loadVersionState returns a PatchState ({state, rev}); extract the .state
+            const vs = await this.store.loadVersionState(docId, lastVersion.id);
+            offlineBaseState = vs.state ?? vs;
+            parentId = lastVersion.id;
+        }
+        else {
+            // First batch for this batchId: start at baseRev
+            offlineBaseState = (await this.getStateAtRevision(docId, baseRev)).state;
+        }
+        let sessionStartIndex = 0;
+        for (let i = 1; i <= changes.length; i++) {
+            const isLastChange = i === changes.length;
+            const timeDiff = isLastChange ? Infinity : changes[i].created - changes[i - 1].created;
+            // Session ends if timeout exceeded OR it's the last change in the batch
+            if (timeDiff > this.sessionTimeoutMillis || isLastChange) {
+                const sessionChanges = changes.slice(sessionStartIndex, i);
+                if (sessionChanges.length > 0) {
+                    // Check if this is a continuation of the previous session (merge/extend)
+                    const isContinuation = !!lastVersion && sessionChanges[0].created - lastVersion.endDate <= this.sessionTimeoutMillis;
+                    if (isContinuation) {
+                        // Merge/extend the existing version
+                        const mergedState = applyChanges(offlineBaseState, sessionChanges);
+                        await this.store.saveChanges(docId, sessionChanges);
+                        await this.store.updateVersion(docId, lastVersion.id, {}); // metadata already updated above
+                        offlineBaseState = mergedState;
+                        parentId = lastVersion.parentId;
+                    }
+                    else {
+                        // Create a new version for this session
+                        offlineBaseState = applyChanges(offlineBaseState, sessionChanges);
+                        const versionId = createId();
+                        const sessionMetadata = {
+                            id: versionId,
+                            parentId,
+                            groupId,
+                            origin: 'offline',
+                            startDate: sessionChanges[0].created,
+                            endDate: sessionChanges[sessionChanges.length - 1].created,
+                            rev: sessionChanges[sessionChanges.length - 1].rev,
+                            baseRev,
+                        };
+                        await this.store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
+                        parentId = versionId;
+                    }
+                    sessionStartIndex = i;
+                }
+            }
+        }
+        // Collapse all changes into one for transformation
+        return [
+            changes.reduce((firstChange, nextChange) => {
+                firstChange.ops = [...firstChange.ops, ...nextChange.ops];
+                return firstChange;
+            }),
+        ];
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {
@@ -25,10 +25,6 @@
     "./net": {
       "import": "./dist/net/index.js",
       "types": "./dist/net/index.d.ts"
-    },
-    "./persist": {
-      "import": "./dist/persist/index.js",
-      "types": "./dist/persist/index.d.ts"
     }
   },
   "files": [
@@ -75,4 +71,4 @@
     "vite-plugin-dts": "^4.5.3",
     "vitest": "^3.1.3"
   }
-}
+}

package/dist/net/AbstractTransport.d.ts

@@ -1,47 +0,0 @@
-import type { ConnectionState, Transport } from '../net/protocol/types.js';
-/**
- * Abstract base class that implements common functionality for various transport implementations.
- * Provides state management and event signaling for connection state changes and message reception.
- * Concrete transport implementations must extend this class and implement the abstract methods.
- */
-export declare abstract class AbstractTransport implements Transport {
-    private _state;
-    /**
-     * Signal that emits when the connection state changes.
-     * Subscribers will receive the new connection state as an argument.
-     */
-    readonly onStateChange: import("../event-signal.js").Signal<(state: ConnectionState) => void>;
-    /**
-     * Signal that emits when a message is received from the transport.
-     * Subscribers will receive the message data as a string.
-     */
-    readonly onMessage: import("../event-signal.js").Signal<(data: string) => void>;
-    /**
-     * Gets the current connection state of the transport.
-     * @returns The current connection state ('connecting', 'connected', 'disconnected', or 'error')
-     */
-    get state(): ConnectionState;
-    /**
-     * Sets the connection state and emits a state change event.
-     * This method is protected and should only be called by subclasses.
-     * @param state - The new connection state
-     */
-    protected set state(state: ConnectionState);
-    /**
-     * Establishes the connection for this transport.
-     * Must be implemented by concrete subclasses.
-     * @returns A promise that resolves when the connection is established
-     */
-    abstract connect(): Promise<void>;
-    /**
-     * Terminates the connection for this transport.
-     * Must be implemented by concrete subclasses.
-     */
-    abstract disconnect(): void;
-    /**
-     * Sends data through this transport.
-     * Must be implemented by concrete subclasses.
-     * @param data - The string data to send
-     */
-    abstract send(data: string): void;
-}

package/dist/net/AbstractTransport.js

@@ -1,39 +0,0 @@
-import { signal } from '../event-signal.js';
-/**
- * Abstract base class that implements common functionality for various transport implementations.
- * Provides state management and event signaling for connection state changes and message reception.
- * Concrete transport implementations must extend this class and implement the abstract methods.
- */
-export class AbstractTransport {
-    constructor() {
-        this._state = 'disconnected';
-        /**
-         * Signal that emits when the connection state changes.
-         * Subscribers will receive the new connection state as an argument.
-         */
-        this.onStateChange = signal();
-        /**
-         * Signal that emits when a message is received from the transport.
-         * Subscribers will receive the message data as a string.
-         */
-        this.onMessage = signal();
-    }
-    /**
-     * Gets the current connection state of the transport.
-     * @returns The current connection state ('connecting', 'connected', 'disconnected', or 'error')
-     */
-    get state() {
-        return this._state;
-    }
-    /**
-     * Sets the connection state and emits a state change event.
-     * This method is protected and should only be called by subclasses.
-     * @param state - The new connection state
-     */
-    set state(state) {
-        if (state === this._state)
-            return;
-        this._state = state;
-        this.onStateChange.emit(state);
-    }
-}

package/dist/persist/index.d.ts

@@ -1,3 +0,0 @@
-export * from './IndexedDBStore.js';
-export * from './InMemoryStore.js';
-export * from './PatchesStore.js';

package/dist/persist/index.js

@@ -1,3 +0,0 @@
-export * from './IndexedDBStore.js';
-export * from './InMemoryStore.js';
-export * from './PatchesStore.js';