@dabble/patches 0.7.2 → 0.7.4

package/dist/client/LWWBatcher.d.ts

@@ -0,0 +1,84 @@
+import { JSONPatch } from '../json-patch/JSONPatch.js';
+import { JSONPatchOp } from '../json-patch/types.js';
+import { ChangeMutator, ChangeInput } from '../types.js';
+import '@dabble/delta';
+
+/**
+ * A utility for batching LWW operations before sending them to the server.
+ *
+ * Accumulates operations, consolidates them using LWW rules (@inc merging,
+ * last-write-wins for replace ops, etc.), and produces a ChangeInput when flushed.
+ *
+ * Useful for migration scripts and batch operations where you want to accumulate
+ * many changes efficiently without creating wasteful Change objects for each operation.
+ *
+ * @template T The type of the document being modified
+ *
+ * @example
+ * ```ts
+ * const batcher = new LWWBatcher<MyDocType>();
+ *
+ * // Option 1: Add ops directly
+ * batcher.add([
+ *   { op: '@inc', path: '/counter', value: 5 },
+ *   { op: '@inc', path: '/counter', value: 3 }
+ * ]);
+ *
+ * // Option 2: Use change() like LWWDoc
+ * batcher.change((patch, doc) => {
+ *   patch.increment(doc.counter, 5);
+ *   patch.replace(doc.name, 'Alice');
+ * });
+ *
+ * // Get consolidated change to send
+ * const changeInput = batcher.flush();
+ * // Returns: { id: '...', ops: [...consolidated...], createdAt: 123456789 }
+ * ```
+ */
+declare class LWWBatcher<T extends object = object> {
+    private ops;
+    /**
+     * Adds operations to the batch.
+     * Operations are consolidated with existing ops using LWW rules.
+     *
+     * @param newOps Array of JSON Patch operations to add (timestamps optional)
+     */
+    add(newOps: JSONPatchOp[] | JSONPatch, timestamp?: number): void;
+    /**
+     * Captures operations using a mutator function (like LWWDoc.change).
+     * The mutator receives a JSONPatch instance and a type-safe path proxy.
+     *
+     * @param mutator Function that uses JSONPatch methods with type-safe paths
+     *
+     * @example
+     * ```ts
+     * batcher.change((patch, doc) => {
+     *   patch.increment(doc.counter, 5);
+     *   patch.replace(doc.user.name, 'Alice');
+     *   patch.bitSet(doc.flags, 0b0010);
+     * });
+     * ```
+     */
+    change(mutator: ChangeMutator<T>, timestamp?: number): void;
+    /**
+     * Returns the consolidated operations as a ChangeInput object and clears the batch.
+     *
+     * @param metadata Optional metadata to include in the ChangeInput
+     * @returns A ChangeInput with id, ops, and createdAt (no rev/baseRev)
+     */
+    flush(metadata?: Record<string, any>): ChangeInput;
+    /**
+     * Clears all batched operations without creating a ChangeInput.
+     */
+    clear(): void;
+    /**
+     * Returns true if the batch has no pending operations.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns the current number of batched operations.
+     */
+    get size(): number;
+}
+
+export { LWWBatcher };

package/dist/client/LWWBatcher.js

@@ -0,0 +1,86 @@
+import "../chunk-IZ2YBCUP.js";
+import { consolidateOps } from "../algorithms/lww/consolidateOps.js";
+import { createChange } from "../data/change.js";
+import { createJSONPatch } from "../json-patch/createJSONPatch.js";
+class LWWBatcher {
+  ops = /* @__PURE__ */ new Map();
+  /**
+   * Adds operations to the batch.
+   * Operations are consolidated with existing ops using LWW rules.
+   *
+   * @param newOps Array of JSON Patch operations to add (timestamps optional)
+   */
+  add(newOps, timestamp = Date.now()) {
+    if (!Array.isArray(newOps)) {
+      newOps = newOps.ops;
+    }
+    if (newOps.length === 0) {
+      return;
+    }
+    if (timestamp) {
+      newOps = newOps.map((op) => op.ts ? op : { ...op, ts: timestamp });
+    }
+    const existingOps = Array.from(this.ops.values());
+    const { opsToSave, pathsToDelete } = consolidateOps(existingOps, newOps);
+    for (const path of pathsToDelete) {
+      this.ops.delete(path);
+    }
+    for (const op of opsToSave) {
+      this.ops.set(op.path, op);
+    }
+  }
+  /**
+   * Captures operations using a mutator function (like LWWDoc.change).
+   * The mutator receives a JSONPatch instance and a type-safe path proxy.
+   *
+   * @param mutator Function that uses JSONPatch methods with type-safe paths
+   *
+   * @example
+   * ```ts
+   * batcher.change((patch, doc) => {
+   *   patch.increment(doc.counter, 5);
+   *   patch.replace(doc.user.name, 'Alice');
+   *   patch.bitSet(doc.flags, 0b0010);
+   * });
+   * ```
+   */
+  change(mutator, timestamp) {
+    const patch = createJSONPatch(mutator);
+    if (patch.ops.length > 0) {
+      this.add(patch.ops, timestamp);
+    }
+  }
+  /**
+   * Returns the consolidated operations as a ChangeInput object and clears the batch.
+   *
+   * @param metadata Optional metadata to include in the ChangeInput
+   * @returns A ChangeInput with id, ops, and createdAt (no rev/baseRev)
+   */
+  flush(metadata) {
+    const ops = Array.from(this.ops.values());
+    const change = createChange(ops, metadata);
+    this.clear();
+    return change;
+  }
+  /**
+   * Clears all batched operations without creating a ChangeInput.
+   */
+  clear() {
+    this.ops.clear();
+  }
+  /**
+   * Returns true if the batch has no pending operations.
+   */
+  isEmpty() {
+    return this.ops.size === 0;
+  }
+  /**
+   * Returns the current number of batched operations.
+   */
+  get size() {
+    return this.ops.size;
+  }
+}
+export {
+  LWWBatcher
+};

package/dist/client/index.d.ts

@@ -7,6 +7,7 @@ export { InMemoryStore } from './InMemoryStore.js';
 export { LWWInMemoryStore } from './LWWInMemoryStore.js';
 export { LWWDoc } from './LWWDoc.js';
 export { LWWAlgorithm } from './LWWAlgorithm.js';
+export { LWWBatcher } from './LWWBatcher.js';
 export { OTAlgorithm } from './OTAlgorithm.js';
 export { Patches, PatchesOptions } from './Patches.js';
 export { PatchesHistoryClient } from './PatchesHistoryClient.js';

package/dist/client/index.js

@@ -7,6 +7,7 @@ export * from "./InMemoryStore.js";
 export * from "./LWWInMemoryStore.js";
 export * from "./LWWDoc.js";
 export * from "./LWWAlgorithm.js";
+export * from "./LWWBatcher.js";
 export * from "./OTDoc.js";
 export * from "./OTAlgorithm.js";
 export * from "./Patches.js";

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { InMemoryStore } from './client/InMemoryStore.js';
 export { LWWInMemoryStore } from './client/LWWInMemoryStore.js';
 export { LWWDoc } from './client/LWWDoc.js';
 export { LWWAlgorithm } from './client/LWWAlgorithm.js';
+export { LWWBatcher } from './client/LWWBatcher.js';
 export { OTAlgorithm } from './client/OTAlgorithm.js';
 export { Patches, PatchesOptions } from './client/Patches.js';
 export { PatchesHistoryClient } from './client/PatchesHistoryClient.js';

package/dist/net/PatchesClient.d.ts

@@ -1,5 +1,5 @@
 import { Signal } from '../event-signal.js';
-import { Change, PatchesState, ChangeInput, CommitChangesOptions, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot } from '../types.js';
+import { Change, CommitChangesOptions, PatchesState, ChangeInput, DeleteDocOptions, EditableVersionMetadata, ListVersionsOptions, VersionMetadata, PatchesSnapshot } from '../types.js';
 import { JSONRPCClient } from './protocol/JSONRPCClient.js';
 import { PatchesAPI, ClientTransport } from './protocol/types.js';
 import '../json-patch/JSONPatch.js';
@@ -16,7 +16,7 @@ declare class PatchesClient implements PatchesAPI {
     rpc: JSONRPCClient;
     transport: ClientTransport;
     /** Signal emitted when the server pushes document changes. */
-    readonly onChangesCommitted: Signal<(docId: string, changes: Change[]) => void>;
+    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], options?: CommitChangesOptions) => void>;
     /** Signal emitted when a document is deleted (either by another client or discovered on subscribe). */
     readonly onDocDeleted: Signal<(docId: string) => void>;
     /**

package/dist/net/PatchesClient.js

@@ -18,8 +18,8 @@ class PatchesClient {
     this.transport = transport;
     this.rpc = new JSONRPCClient(transport);
     this.rpc.on("changesCommitted", (params) => {
-      const { docId, changes } = params;
-      this.onChangesCommitted.emit(docId, changes);
+      const { docId, changes, options } = params;
+      this.onChangesCommitted.emit(docId, changes, options);
     });
     this.rpc.on("docDeleted", (params) => {
       this.onDocDeleted.emit(params.docId);

package/dist/net/protocol/types.d.ts

@@ -140,6 +140,7 @@ interface PatchesAPI {
 interface PatchesNotificationParams {
     docId: string;
     changes: Change[];
+    options?: CommitChangesOptions;
 }
 interface AwarenessUpdateNotificationParams {
     docId: string;

package/dist/server/LWWServer.d.ts

@@ -1,6 +1,6 @@
 import { Signal } from '../event-signal.js';
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { Change, DeleteDocOptions, PatchesState, ChangeInput, CommitChangesOptions, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { Change, CommitChangesOptions, DeleteDocOptions, PatchesState, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
 import { PatchesServer } from './PatchesServer.js';
 import { LWWStoreBackend } from './types.js';
 import '../net/websocket/AuthorizationProvider.js';
@@ -55,7 +55,7 @@ declare class LWWServer implements PatchesServer {
     readonly store: LWWStoreBackend;
     private readonly snapshotInterval;
     /** Notifies listeners whenever a batch of changes is successfully committed. */
-    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
+    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], options?: CommitChangesOptions, originClientId?: string) => void>;
     /** Notifies listeners when a document is deleted. */
     readonly onDocDeleted: Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
     constructor(store: LWWStoreBackend, options?: LWWServerOptions);
@@ -86,10 +86,10 @@ declare class LWWServer implements PatchesServer {
      *
      * @param docId - The document ID.
      * @param changes - The changes to commit (always 1 for LWW).
-     * @param _options - Optional commit options (ignored for LWW).
+     * @param options - Optional commit options (ignored for LWW).
      * @returns Array containing 0-1 changes with catchup ops and new rev.
      */
-    commitChanges(docId: string, changes: ChangeInput[], _options?: CommitChangesOptions): Promise<Change[]>;
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
     /**
      * Delete a document and emit deletion signal.
      * Creates a tombstone if the store supports it.

package/dist/server/LWWServer.js

@@ -77,10 +77,10 @@ class LWWServer {
    *
    * @param docId - The document ID.
    * @param changes - The changes to commit (always 1 for LWW).
-   * @param _options - Optional commit options (ignored for LWW).
+   * @param options - Optional commit options (ignored for LWW).
    * @returns Array containing 0-1 changes with catchup ops and new rev.
    */
-  async commitChanges(docId, changes, _options) {
+  async commitChanges(docId, changes, options) {
     if (changes.length === 0) {
       return [];
     }
@@ -117,7 +117,7 @@ class LWWServer {
           id: change.id,
           committedAt: serverNow
         });
-        await this.onChangesCommitted.emit(docId, [broadcastChange], getClientId());
+        await this.onChangesCommitted.emit(docId, [broadcastChange], options, getClientId());
       } catch (error) {
         console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
       }

package/dist/server/OTServer.d.ts

@@ -1,7 +1,7 @@
 import { Signal } from '../event-signal.js';
 import { PatchesServer } from './PatchesServer.js';
 import { OTStoreBackend } from './types.js';
-import { Change, DeleteDocOptions, PatchesState, ChangeInput, CommitChangesOptions, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { Change, CommitChangesOptions, DeleteDocOptions, PatchesState, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
@@ -48,7 +48,7 @@ declare class OTServer implements PatchesServer {
     private readonly maxStorageBytes?;
     readonly store: OTStoreBackend;
     /** Notifies listeners whenever a batch of changes is *successfully* committed. */
-    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
+    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], options?: CommitChangesOptions, originClientId?: string) => void>;
     /** Notifies listeners when a document is deleted. */
     readonly onDocDeleted: Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
     constructor(store: OTStoreBackend, options?: OTServerOptions);

package/dist/server/OTServer.js

@@ -74,7 +74,7 @@ class OTServer {
     );
     if (newChanges.length > 0) {
       try {
-        await this.onChangesCommitted.emit(docId, newChanges, getClientId());
+        await this.onChangesCommitted.emit(docId, newChanges, options, getClientId());
       } catch (error) {
         console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
       }

package/package.json

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