@dabble/patches 0.7.1 → 0.7.3

package/dist/client/IndexedDBStore.js

@@ -58,7 +58,7 @@ class IndexedDBStore {
       this.db.close();
       this.db = null;
       this.dbPromise = deferred();
-      this.dbPromise.resolve(null);
+      this.dbPromise.reject(new Error("Store has been closed"));
     }
   }
   async deleteDB() {

package/dist/client/LWWAlgorithm.js

@@ -26,7 +26,7 @@ class LWWAlgorithm {
     const committedRev = doc?.committedRev ?? await this.store.getCommittedRev(docId);
     const changes = [createChange(committedRev, committedRev + 1, timedOps, metadata)];
     if (doc) {
-      doc.applyChanges(changes);
+      doc.applyChanges(changes, true);
     }
     return changes;
   }
@@ -52,7 +52,8 @@ class LWWAlgorithm {
     const localOps = [...sendingChange?.ops ?? [], ...pendingOps];
     const mergedChanges = mergeServerWithLocal(serverChanges, localOps);
     if (doc) {
-      doc.applyChanges(mergedChanges);
+      const hasPending = localOps.length > 0;
+      doc.applyChanges(mergedChanges, hasPending);
     }
     return mergedChanges;
   }

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): 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>): 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,85 @@
+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) {
+    if (!Array.isArray(newOps)) {
+      newOps = newOps.ops;
+    }
+    if (newOps.length === 0) {
+      return;
+    }
+    const timestamp = Date.now();
+    const timedOps = newOps.map((op) => op.ts ? op : { ...op, ts: timestamp });
+    const existingOps = Array.from(this.ops.values());
+    const { opsToSave, pathsToDelete } = consolidateOps(existingOps, timedOps);
+    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) {
+    const patch = createJSONPatch(mutator);
+    if (patch.ops.length > 0) {
+      this.add(patch.ops);
+    }
+  }
+  /**
+   * 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/LWWDoc.d.ts

@@ -49,8 +49,10 @@ declare class LWWDoc<T extends object = object> extends BaseDoc<T> {
      * - `committedAt === 0`: Pending local change (marks hasPending = true)
      *
      * @param changes Array of changes to apply
+     * @param hasPending If provided, overrides the inferred pending state.
+     *   Used by LWWAlgorithm which knows the true pending state from the store.
      */
-    applyChanges(changes: Change[]): void;
+    applyChanges(changes: Change[], hasPending?: boolean): void;
 }
 
 export { LWWDoc };

package/dist/client/LWWDoc.js

@@ -57,8 +57,10 @@ class LWWDoc extends BaseDoc {
    * - `committedAt === 0`: Pending local change (marks hasPending = true)
    *
    * @param changes Array of changes to apply
+   * @param hasPending If provided, overrides the inferred pending state.
+   *   Used by LWWAlgorithm which knows the true pending state from the store.
    */
-  applyChanges(changes) {
+  applyChanges(changes, hasPending) {
     if (changes.length === 0) return;
     for (const change of changes) {
       for (const op of change.ops) {
@@ -75,7 +77,7 @@ class LWWDoc extends BaseDoc {
       }
     }
     this._committedRev = lastCommittedRev;
-    this._hasPending = hasPendingChanges;
+    this._hasPending = hasPending ?? hasPendingChanges;
     this.onUpdate.emit(this._state);
   }
 }

package/dist/client/Patches.d.ts

@@ -50,6 +50,11 @@ declare class Patches {
     /** Emitted when a doc has pending changes ready to send */
     readonly onChange: Signal<(docId: string) => void>;
     constructor(opts: PatchesOptions);
+    /**
+     * Loads tracked docs from all registered algorithm stores.
+     * Extracted as a protected method so subclasses can override initialization behavior.
+     */
+    protected init(): void;
     /**
      * Gets an algorithm by name, throwing if not found.
      */

package/dist/client/Patches.js

@@ -37,8 +37,22 @@ class Patches {
       throw new Error(`Default algorithm '${this.defaultAlgorithm}' not found in algorithms map`);
     }
     this.docOptions = opts.docOptions ?? {};
-    this._getAlgorithm(this.defaultAlgorithm).listDocs().then((docs) => {
-      this.trackDocs(docs.map(({ docId }) => docId));
+    this.init();
+  }
+  /**
+   * Loads tracked docs from all registered algorithm stores.
+   * Extracted as a protected method so subclasses can override initialization behavior.
+   */
+  init() {
+    const algorithms = Object.values(this.algorithms).filter(Boolean);
+    Promise.all(
+      algorithms.map(
+        (algorithm) => algorithm.listDocs().then((docs) => {
+          this.trackDocs(docs.map(({ docId }) => docId));
+        })
+      )
+    ).catch((err) => {
+      console.error("Failed to load tracked docs during initialization:", err);
     });
   }
   /**

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/compression/index.js

@@ -1,10 +1,5 @@
 import "../chunk-IZ2YBCUP.js";
-import {
-  compressToBase64,
-  compressToUint8Array,
-  decompressFromBase64,
-  decompressFromUint8Array
-} from "./lz.js";
+import { compressToBase64, compressToUint8Array, decompressFromBase64, decompressFromUint8Array } from "./lz.js";
 const compressedSizeBase64 = (data) => {
   if (data === void 0) return 0;
   try {

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/index.d.ts

@@ -6,7 +6,6 @@ export { AccessLevel, ApiDefinition, ConnectionSignalSubscriber, JSONRPCServer,
 export { getAuthContext, getClientId } from './serverContext.js';
 export { AwarenessUpdateNotificationParams, ClientTransport, ConnectionState, JsonRpcNotification, JsonRpcRequest, JsonRpcResponse, ListOptions, Message, PatchesAPI, PatchesNotificationParams, ServerTransport, SignalNotificationParams } from './protocol/types.js';
 export { rpcError, rpcNotification, rpcResponse } from './protocol/utils.js';
-export { PatchesState, SyncingState } from './types.js';
 export { Access, AuthContext, AuthorizationProvider, allowAll, assertNotDeleted, denyAll } from './websocket/AuthorizationProvider.js';
 export { onlineState } from './websocket/onlineState.js';
 export { PatchesWebSocket } from './websocket/PatchesWebSocket.js';

package/dist/net/protocol/JSONRPCServer.js

@@ -152,9 +152,11 @@ class JSONRPCServer {
     }
     const args = Array.isArray(params) ? params : params === void 0 ? [] : [params];
     setAuthContext(ctx);
-    const response = handler(...args);
-    clearAuthContext();
-    return response;
+    try {
+      return await handler(...args);
+    } finally {
+      clearAuthContext();
+    }
   }
 }
 export {

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/net/webrtc/WebRTCAwareness.js

@@ -64,9 +64,8 @@ class WebRTCAwareness {
    * @param value - The new local awareness state to set and broadcast
    */
   set localState(value) {
-    value.id = this.myId;
-    this._localState = value;
-    this.transport.send(JSON.stringify(value));
+    this._localState = { ...value, id: this.myId };
+    this.transport.send(JSON.stringify(this._localState));
   }
   /**
    * Handles a new peer connection by sending the local state to the new peer.

package/dist/net/websocket/WebSocketTransport.js

@@ -169,9 +169,12 @@ class WebSocketTransport {
     if (!this.onlineUnsubscriber) {
       this.onlineUnsubscriber = onlineState.onOnlineChange((isOnline) => {
         if (isOnline && this.shouldBeConnected && !this.connecting && this.state !== "connected") {
-          const { resolve, reject } = this.connectionDeferred;
+          const oldDeferred = this.connectionDeferred;
           this.connectionDeferred = null;
-          this.connect().then(resolve, reject);
+          const connectPromise = this.connect();
+          if (oldDeferred) {
+            connectPromise.then(oldDeferred.resolve, oldDeferred.reject);
+          }
         } else if (!isOnline && this.ws) {
           this.ws.close();
         }

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);
       }
@@ -127,8 +127,7 @@ class OTServer {
   async captureCurrentVersion(docId, metadata) {
     assertVersionMetadata(metadata);
     const { state: initialState, changes } = await getSnapshotAtRevision(this.store, docId);
-    let state = initialState;
-    state = applyChanges(state, changes);
+    const state = applyChanges(initialState, changes);
     const version = await createVersion(this.store, docId, state, changes, metadata);
     if (!version) {
       return null;

package/dist/shared/doc-manager.d.ts

@@ -0,0 +1,89 @@
+import { Patches } from '../client/Patches.js';
+import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
+import '../event-signal.js';
+import '../json-patch/types.js';
+import '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../client/ClientAlgorithm.js';
+import '../client/PatchesStore.js';
+
+/**
+ * Reference counting manager for PatchesDoc instances.
+ *
+ * Tracks how many components are using each document and only opens/closes
+ * documents when the reference count goes to/from zero.
+ *
+ * This prevents the footgun where multiple components open the same doc but the
+ * first one to unmount closes it for everyone else.
+ */
+declare class DocManager {
+    private refCounts;
+    private pendingOps;
+    /**
+     * Opens a document with reference counting.
+     *
+     * - If this is the first reference, calls patches.openDoc()
+     * - If doc is already open, returns existing instance and increments count
+     * - Handles concurrent opens to the same doc safely
+     *
+     * @param patches - Patches instance
+     * @param docId - Document ID to open
+     * @returns Promise resolving to PatchesDoc instance
+     */
+    openDoc<T extends object>(patches: Patches, docId: string): Promise<PatchesDoc<T>>;
+    /**
+     * Closes a document with reference counting.
+     *
+     * - Decrements the reference count
+     * - Only calls patches.closeDoc() when count reaches zero
+     * - Safe to call even if doc was never opened
+     *
+     * @param patches - Patches instance
+     * @param docId - Document ID to close
+     * @param untrack - Whether to also untrack the doc when closing (default: false)
+     */
+    closeDoc(patches: Patches, docId: string, untrack?: boolean): Promise<void>;
+    /**
+     * Increments the reference count for a document without opening it.
+     *
+     * Used in explicit mode to track usage and prevent premature closes
+     * from autoClose mode.
+     *
+     * @param docId - Document ID
+     */
+    incrementRefCount(docId: string): void;
+    /**
+     * Decrements the reference count for a document without closing it.
+     *
+     * Used in explicit mode to release usage tracking.
+     *
+     * @param docId - Document ID
+     */
+    decrementRefCount(docId: string): void;
+    /**
+     * Gets the current reference count for a document.
+     *
+     * Useful for debugging or advanced use cases.
+     *
+     * @param docId - Document ID
+     * @returns Current reference count (0 if not tracked)
+     */
+    getRefCount(docId: string): number;
+    /**
+     * Clears all reference counts without closing documents.
+     *
+     * Use with caution - this is mainly for testing or cleanup scenarios
+     * where you want to reset the manager state.
+     */
+    reset(): void;
+}
+/**
+ * Gets or creates a DocManager for a Patches instance.
+ *
+ * @param patches - Patches instance
+ * @returns DocManager for this Patches instance
+ */
+declare function getDocManager(patches: Patches): DocManager;
+
+export { DocManager, getDocManager };