@dabble/patches 0.2.26 → 0.2.28

package/dist/client/PatchesHistoryClient.d.ts

@@ -27,9 +27,9 @@ export declare class PatchesHistoryClient<T = any> {
     /** Update the name of a specific version. */
     updateVersion(versionId: string, metadata: EditableVersionMetadata): Promise<void>;
     /** Load the state for a specific version */
-    getStateAtVersion(versionId: string): Promise<any>;
+    getVersionState(versionId: string): Promise<any>;
     /** Load the changes for a specific version */
-    getChangesForVersion(versionId: string): Promise<Change[]>;
+    getVersionChanges(versionId: string): Promise<Change[]>;
     /** Scrub to a specific change within a version where changeIndex is 1-based and 0 is the parent version */
     scrubTo(versionId: string, changeIndex: number): Promise<void>;
     /** Clear caches and listeners */

package/dist/client/PatchesHistoryClient.js

@@ -73,7 +73,7 @@ export class PatchesHistoryClient {
         await this.listVersions(); // Refresh the list of versions
     }
     /** Load the state for a specific version */
-    async getStateAtVersion(versionId) {
+    async getVersionState(versionId) {
         let data = this.cache.get(versionId);
         if (!data || data.state === undefined) {
             const { state } = await this.api.getVersionState(this.id, versionId);
@@ -85,7 +85,7 @@ export class PatchesHistoryClient {
         return data.state;
     }
     /** Load the changes for a specific version */
-    async getChangesForVersion(versionId) {
+    async getVersionChanges(versionId) {
         let data = this.cache.get(versionId);
         if (!data || data.changes === undefined) {
             const changes = await this.api.getVersionChanges(this.id, versionId);
@@ -99,8 +99,8 @@ export class PatchesHistoryClient {
         const version = this.versions.find(v => v.id === versionId);
         // Load state and changes for the version
         const [state, changes] = await Promise.all([
-            version?.parentId ? this.getStateAtVersion(version.parentId) : undefined,
-            this.getChangesForVersion(versionId),
+            version?.parentId ? this.getVersionState(version.parentId) : undefined,
+            this.getVersionChanges(versionId),
         ]);
         // Apply changes up to changeIndex to the state (if needed)
         if (changeIndex > 0) {

package/dist/net/error.d.ts

@@ -0,0 +1,4 @@
+export declare class StatusError extends Error {
+    code: number;
+    constructor(code: number, message: string);
+}

package/dist/net/error.js

@@ -0,0 +1,6 @@
+export class StatusError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/net/protocol/JSONRPCServer.js

@@ -95,7 +95,7 @@ export class JSONRPCServer {
                 return respond(response);
             }
             catch (err) {
-                return respond(rpcError(err?.code ?? -32000, err?.message ?? 'Server error', err?.stack));
+                return respond(rpcError(err?.code ?? -32000, err?.message ?? 'Server error', err?.code ? undefined : err?.stack));
             }
         }
         else {

package/dist/net/websocket/RPCServer.d.ts

@@ -39,7 +39,7 @@ export declare class RPCServer {
     getDoc(params: {
         docId: string;
         atRev?: number;
-    }, ctx?: AuthContext): Promise<import("../../types.js").PatchesSnapshot<any>>;
+    }, ctx?: AuthContext): Promise<import("../../types.js").PatchesState<any>>;
     /**
      * Gets changes that occurred for a document after a specific revision number.
      * @param connectionId - The ID of the connection making the request
@@ -84,11 +84,11 @@ export declare class RPCServer {
         versionId: string;
         metadata: EditableVersionMetadata;
     }, ctx?: AuthContext): Promise<void>;
-    getStateAtVersion(params: {
+    getVersionState(params: {
         docId: string;
         versionId: string;
     }, ctx?: AuthContext): Promise<any>;
-    getChangesForVersion(params: {
+    getVersionChanges(params: {
         docId: string;
         versionId: string;
     }, ctx?: AuthContext): Promise<Change[]>;

package/dist/net/websocket/RPCServer.js

@@ -1,3 +1,4 @@
+import { StatusError } from '../error.js';
 import { JSONRPCServer } from '../protocol/JSONRPCServer.js';
 import { allowAll } from './AuthorizationProvider.js';
 export class RPCServer {
@@ -24,8 +25,8 @@ export class RPCServer {
             this.rpc.registerMethod('listVersions', this.listVersions.bind(this));
             this.rpc.registerMethod('createVersion', this.createVersion.bind(this));
             this.rpc.registerMethod('updateVersion', this.updateVersion.bind(this));
-            this.rpc.registerMethod('getVersionState', this.getStateAtVersion.bind(this));
-            this.rpc.registerMethod('getVersionChanges', this.getChangesForVersion.bind(this));
+            this.rpc.registerMethod('getVersionState', this.getVersionState.bind(this));
+            this.rpc.registerMethod('getVersionChanges', this.getVersionChanges.bind(this));
             this.rpc.registerMethod('listServerChanges', this.listServerChanges.bind(this));
         }
         // Branch manager operations (if provided)
@@ -114,13 +115,13 @@ export class RPCServer {
         await this.assertWrite(ctx, docId, 'updateVersion', params);
         return this.history.updateVersion(docId, versionId, metadata);
     }
-    async getStateAtVersion(params, ctx) {
+    async getVersionState(params, ctx) {
         this.assertHistoryEnabled();
         const { docId, versionId } = params;
         await this.assertRead(ctx, docId, 'getStateAtVersion', params);
         return this.history.getStateAtVersion(docId, versionId);
     }
-    async getChangesForVersion(params, ctx) {
+    async getVersionChanges(params, ctx) {
         this.assertHistoryEnabled();
         const { docId, versionId } = params;
         await this.assertRead(ctx, docId, 'getChangesForVersion', params);
@@ -165,7 +166,7 @@ export class RPCServer {
     async assertAccess(ctx, docId, kind, method, params) {
         const ok = await this.auth.canAccess(ctx, docId, kind, method, params);
         if (!ok) {
-            throw new Error(`${kind.toUpperCase()}_FORBIDDEN:${docId}`);
+            throw new StatusError(401, `${kind.toUpperCase()}_FORBIDDEN:${docId}`);
         }
     }
     assertRead(ctx, docId, method, params) {
@@ -176,12 +177,12 @@ export class RPCServer {
     }
     assertHistoryEnabled() {
         if (!this.history) {
-            throw new Error('History is not enabled');
+            throw new StatusError(404, 'History is not enabled');
         }
     }
     assertBranchingEnabled() {
         if (!this.branches) {
-            throw new Error('Branching is not enabled');
+            throw new StatusError(404, 'Branching is not enabled');
         }
     }
 }

package/dist/server/PatchesServer.d.ts

@@ -1,3 +1,4 @@
+import type { JSONPatch } from '../json-patch/JSONPatch.js';
 import type { Change, EditableVersionMetadata, PatchesSnapshot, PatchesState, VersionMetadata } from '../types.js';
 import type { PatchesStoreBackend } from './types.js';
 /**
@@ -25,11 +26,12 @@ export declare class PatchesServer {
     readonly onDocDeleted: import("../event-signal.js").Signal<(docId: string, originClientId?: string) => void>;
     constructor(store: PatchesStoreBackend, options?: PatchesServerOptions);
     /**
-     * Get the latest version of a document and changes since the last version.
+     * Get the state of a document at a specific revision (or the latest state if no revision is provided).
      * @param docId - The ID of the document.
-     * @returns The latest version of the document and changes since the last version.
+     * @param rev - The revision number.
+     * @returns The state of the document at the specified revision.
      */
-    getDoc(docId: string, atRev?: number): Promise<PatchesSnapshot>;
+    getDoc(docId: string, atRev?: number): Promise<PatchesState>;
     /**
      * Get changes that occurred after a specific revision.
      * @param docId - The ID of the document.
@@ -47,6 +49,12 @@ export declare class PatchesServer {
      *   - transformedChanges: The client's changes after being transformed against concurrent changes
      */
     commitChanges(docId: string, changes: Change[], originClientId?: string): Promise<[Change[], Change[]]>;
+    /**
+     * Make a server-side change to a document.
+     * @param mutator
+     * @returns
+     */
+    change<T = Record<string, any>>(docId: string, mutator: (draft: T, patch: JSONPatch) => void, metadata?: Record<string, any>): Promise<Change | null>;
     /**
      * Deletes a document.
      * @param docId The document ID.

package/dist/server/PatchesServer.js

@@ -1,6 +1,7 @@
 import { createId } from 'crypto-id';
 import { signal } from '../event-signal.js';
 import { applyPatch } from '../json-patch/applyPatch.js';
+import { createJSONPatch } from '../json-patch/createJSONPatch.js';
 import { transformPatch } from '../json-patch/transformPatch.js';
 import { applyChanges } from '../utils.js';
 /**
@@ -18,12 +19,13 @@ export class PatchesServer {
         this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1000;
     }
     /**
-     * Get the latest version of a document and changes since the last version.
+     * Get the state of a document at a specific revision (or the latest state if no revision is provided).
      * @param docId - The ID of the document.
-     * @returns The latest version of the document and changes since the last version.
+     * @param rev - The revision number.
+     * @returns The state of the document at the specified revision.
      */
     async getDoc(docId, atRev) {
-        return this._getSnapshotAtRevision(docId, atRev);
+        return this.getStateAtRevision(docId, atRev);
     }
     /**
      * Get changes that occurred after a specific revision.
@@ -55,7 +57,7 @@ export class PatchesServer {
         }
         // Add check for inconsistent baseRev within the batch if needed
         if (changes.some(c => c.baseRev !== baseRev)) {
-            throw new Error(`Client changes must have consistent baseRev for doc ${docId}.`);
+            throw new Error(`Client changes must have consistent baseRev in all changes for doc ${docId}.`);
         }
         // 1. Load server state details (assuming store methods exist)
         let { state: currentState, rev: currentRev, changes: currentChanges } = await this._getSnapshotAtRevision(docId);
@@ -66,14 +68,12 @@ export class PatchesServer {
             throw new Error(`Client baseRev (${baseRev}) is ahead of server revision (${currentRev}) for doc ${docId}. Client needs to reload the document.`);
         }
         const partOfInitialBatch = batchId && changes[0].rev > 1;
-        if (baseRev === 0 && currentRev > 0 && !partOfInitialBatch) {
+        if (baseRev === 0 && currentRev > 0 && !partOfInitialBatch && changes[0].ops[0].path === '') {
             throw new Error(`Client baseRev is 0 but server has already been created for doc ${docId}. Client needs to load the existing document.`);
         }
         // Ensure all new changes' `created` field is in the past, that each `rev` is correct, and that `baseRev` is set
-        let rev = baseRev + 1;
         changes.forEach(c => {
             c.created = Math.min(c.created, Date.now());
-            c.rev = rev++;
             c.baseRev = baseRev;
         });
         // 2. Check if we need to create a new version - if the last change was created more than a session ago
@@ -103,6 +103,7 @@ export class PatchesServer {
         //    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 rev = currentRev + 1;
         const committedOps = committedChanges.flatMap(c => c.ops);
         // Apply transformation based on state at baseRev
         const transformedChanges = changes
@@ -113,14 +114,19 @@ export class PatchesServer {
                 return null; // Change is obsolete after transformation
             }
             try {
+                const previous = stateAtBaseRev;
                 stateAtBaseRev = applyPatch(stateAtBaseRev, change.ops, { strict: true });
+                if (previous === stateAtBaseRev) {
+                    // Changes were no-ops, we can skip this change
+                    return null;
+                }
             }
             catch (error) {
                 console.error(`Error applying change ${change.id} to state:`, error);
                 return null;
             }
             // Return a new change object with transformed ops and original metadata
-            return { ...change, ops: transformedOps };
+            return { ...change, rev: rev++, ops: transformedOps };
         })
             .filter(Boolean);
         // Persist the newly transformed changes
@@ -134,6 +140,31 @@ export class PatchesServer {
         // Return committed changes and newly transformed changes separately
         return [committedChanges, transformedChanges];
     }
+    /**
+     * Make a server-side change to a document.
+     * @param mutator
+     * @returns
+     */
+    async change(docId, mutator, metadata) {
+        const { state, rev } = await this.getDoc(docId);
+        const patch = createJSONPatch(state, mutator);
+        if (patch.ops.length === 0) {
+            return null;
+        }
+        // It's the baseRev that matters for sending.
+        const change = {
+            id: createId(),
+            ops: patch.ops,
+            baseRev: rev,
+            rev: rev + 1,
+            created: Date.now(),
+            ...metadata,
+        };
+        // Apply to local state to ensure no errors are thrown
+        patch.apply(state);
+        await this.commitChanges(docId, [change]);
+        return change;
+    }
     /**
      * Deletes a document.
      * @param docId The document ID.

package/dist/types.d.ts

@@ -7,7 +7,7 @@ export interface Change {
     /** The revision number assigned on the client to the optimistic revision and updated by the server after commit. */
     rev: number;
     /** The server revision this change was based on. Required for client->server changes. */
-    baseRev?: number;
+    baseRev: number;
     /** Client-side timestamp when the change was created. */
     created: number;
     /** Optional batch identifier for grouping changes that belong to the same client batch (for multi-batch offline/large edits). */

package/dist/utils/getJSONByteSize.js

@@ -1,4 +1,3 @@
-import { TextEncoder } from 'util'; // Node.js TextEncoder
 /** Estimate JSON string byte size. */
 export function getJSONByteSize(data) {
     // Basic estimation, might not be perfectly accurate due to encoding nuances

package/dist/utils.d.ts

@@ -1,13 +1,4 @@
 import type { Change, Deferred } from './types.js';
-/**
- * Splits an array of changes into two arrays based on the presence of a baseRev.
- * The first array contains changes before the first change with a baseRev,
- * and the second array contains the change with baseRev and all subsequent changes.
- *
- * @param changes - Array of changes to split
- * @returns A tuple containing [changes before baseRev, changes with and after baseRev]
- */
-export declare function splitChanges(changes: Change[]): [Change[], Change[]];
 /**
  * Applies a sequence of changes to a state object.
  * Each change is applied in sequence using the applyPatch function.

package/dist/utils.js

@@ -1,17 +1,5 @@
 import { applyPatch } from './json-patch/applyPatch.js';
 import { JSONPatch } from './json-patch/JSONPatch.js';
-/**
- * Splits an array of changes into two arrays based on the presence of a baseRev.
- * The first array contains changes before the first change with a baseRev,
- * and the second array contains the change with baseRev and all subsequent changes.
- *
- * @param changes - Array of changes to split
- * @returns A tuple containing [changes before baseRev, changes with and after baseRev]
- */
-export function splitChanges(changes) {
-    const index = changes.findIndex(c => c.baseRev);
-    return [changes.slice(0, index), changes.slice(index)];
-}
 /**
  * Applies a sequence of changes to a state object.
  * Each change is applied in sequence using the applyPatch function.

package/package.json

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