@dabble/patches 0.7.6 → 0.7.8

package/dist/net/websocket/WebSocketServer.js

@@ -39,19 +39,17 @@ class WebSocketServer {
   /**
    * Subscribes the client to one or more documents to receive real-time updates.
    * If a document has been deleted (tombstone exists), sends immediate docDeleted notification.
-   * @param params - The subscription parameters
-   * @param params.ids - Document ID or IDs to subscribe to
+   * @param ids - Document ID or IDs to subscribe to
    */
-  async subscribe(params) {
+  async subscribe(ids) {
     const ctx = getAuthContext();
     if (!ctx?.clientId) return [];
-    const { ids } = params;
     const allIds = Array.isArray(ids) ? ids : [ids];
     const allowed = [];
     await Promise.all(
       allIds.map(async (id) => {
         try {
-          if (await this.auth.canAccess(ctx, id, "read", "subscribe", params)) {
+          if (await this.auth.canAccess(ctx, id, "read", "subscribe")) {
             allowed.push(id);
           }
         } catch (err) {
@@ -75,13 +73,11 @@ class WebSocketServer {
   }
   /**
    * Unsubscribes the client from one or more documents.
-   * @param params - The unsubscription parameters
-   * @param params.ids - Document ID or IDs to unsubscribe from
+   * @param ids - Document ID or IDs to unsubscribe from
    */
-  async unsubscribe(params) {
+  async unsubscribe(ids) {
     const ctx = getAuthContext();
     if (!ctx?.clientId) return [];
-    const { ids } = params;
     return this.transport.removeSubscription(ctx.clientId, Array.isArray(ids) ? ids : [ids]);
   }
 }

package/dist/server/LWWBranchManager.d.ts

@@ -64,11 +64,11 @@ declare class LWWBranchManager implements BranchManager {
      * @param branchId - The branch document ID.
      * @param status - The status to set (defaults to 'closed').
      */
-    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
     /**
      * Merges a branch back into its source document.
      *
-     * LWW merge strategy:
+     * LWW merge algorithm:
      * 1. Get all ops changes made on the branch since it was created
      * 2. Apply those changes to the source document
      * 3. Timestamps automatically resolve any conflicts (later wins)

package/dist/server/LWWBranchManager.js

@@ -61,13 +61,13 @@ class LWWBranchManager {
    * @param branchId - The branch document ID.
    * @param status - The status to set (defaults to 'closed').
    */
-  async closeBranch(branchId, status = "closed") {
-    await this.store.updateBranch(branchId, { status });
+  async closeBranch(branchId, status) {
+    await this.store.updateBranch(branchId, { status: status ?? "closed" });
   }
   /**
    * Merges a branch back into its source document.
    *
-   * LWW merge strategy:
+   * LWW merge algorithm:
    * 1. Get all ops changes made on the branch since it was created
    * 2. Apply those changes to the source document
    * 3. Timestamps automatically resolve any conflicts (later wins)

package/dist/server/OTBranchManager.d.ts

@@ -60,7 +60,7 @@ declare class OTBranchManager implements BranchManager {
      * @param branchId - The ID of the branch to close.
      * @param status - The status to set for the branch.
      */
-    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
     /**
      * Merges changes from a branch back into its source document.
      * @param branchId - The ID of the branch document to merge.

package/dist/server/OTBranchManager.js

@@ -70,8 +70,8 @@ class OTBranchManager {
    * @param branchId - The ID of the branch to close.
    * @param status - The status to set for the branch.
    */
-  async closeBranch(branchId, status = "closed") {
-    await this.store.updateBranch(branchId, { status });
+  async closeBranch(branchId, status) {
+    await this.store.updateBranch(branchId, { status: status ?? "closed" });
   }
   /**
    * Merges changes from a branch back into its source document.

package/dist/server/branchUtils.d.ts

@@ -77,6 +77,6 @@ declare function wrapMergeCommit<T>(branchId: string, sourceDocId: string, commi
  */
 declare function closeBranch(store: {
     updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name'>>): Promise<void>;
-}, branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+}, branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
 
 export { type BranchIdGenerator, type BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, closeBranch, createBranchRecord, generateBranchId, wrapMergeCommit };

package/dist/server/branchUtils.js

@@ -51,8 +51,8 @@ async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
     throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
   }
 }
-async function closeBranch(store, branchId, status = "closed") {
-  await store.updateBranch(branchId, { status });
+async function closeBranch(store, branchId, status) {
+  await store.updateBranch(branchId, { status: status ?? "closed" });
 }
 export {
   assertBranchMetadata,

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

@@ -1,5 +1,5 @@
-import { Patches } from '../client/Patches.js';
-import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
+import { Patches, OpenDocOptions } from '../client/Patches.js';
+import { a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
 import '../event-signal.js';
 import '../json-patch/types.js';
 import '../types.js';
@@ -31,7 +31,7 @@ declare class DocManager {
      * @param docId - Document ID to open
      * @returns Promise resolving to PatchesDoc instance
      */
-    openDoc<T extends object>(patches: Patches, docId: string): Promise<PatchesDoc<T>>;
+    openDoc<T extends object>(patches: Patches, docId: string, opts?: OpenDocOptions): Promise<PatchesDoc<T>>;
     /**
      * Closes a document with reference counting.
      *

package/dist/shared/doc-manager.js

@@ -13,7 +13,7 @@ class DocManager {
    * @param docId - Document ID to open
    * @returns Promise resolving to PatchesDoc instance
    */
-  async openDoc(patches, docId) {
+  async openDoc(patches, docId, opts) {
     const currentCount = this.refCounts.get(docId) || 0;
     if (currentCount === 0 && this.pendingOps.has(docId)) {
       const doc = await this.pendingOps.get(docId);
@@ -28,7 +28,7 @@ class DocManager {
       }
       return doc;
     }
-    const openPromise = patches.openDoc(docId);
+    const openPromise = patches.openDoc(docId, opts);
     this.pendingOps.set(docId, openPromise);
     try {
       const doc = await openPromise;

package/dist/solid/context.d.ts

@@ -7,7 +7,7 @@ import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../client/ClientAlgorithm.js';
-import '../BaseDoc-DkP3tUhT.js';
+import '../BaseDoc-_Rsau70J.js';
 import '../client/PatchesStore.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

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

@@ -6,5 +6,5 @@ import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../client/ClientAlgorithm.js';
-import '../BaseDoc-DkP3tUhT.js';
+import '../BaseDoc-_Rsau70J.js';
 import '../client/PatchesStore.js';

package/dist/solid/index.d.ts

@@ -11,7 +11,7 @@ import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../client/ClientAlgorithm.js';
-import '../BaseDoc-DkP3tUhT.js';
+import '../BaseDoc-_Rsau70J.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../net/protocol/types.js';

package/dist/solid/primitives.d.ts

@@ -1,15 +1,18 @@
 import { Accessor } from 'solid-js';
-import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
+import { OpenDocOptions } from '../client/Patches.js';
+import { a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
 import { JSONPatch } from '../json-patch/JSONPatch.js';
 import { ChangeMutator } from '../types.js';
 import '../event-signal.js';
 import '../json-patch/types.js';
+import '../client/ClientAlgorithm.js';
+import '../client/PatchesStore.js';
 import '@dabble/delta';
 
 /**
  * Options for usePatchesDoc primitive (eager mode with docId).
  */
-interface UsePatchesDocOptions {
+interface UsePatchesDocOptions extends OpenDocOptions {
     /**
      * Controls document lifecycle management on cleanup.
      *
@@ -89,8 +92,9 @@ interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<
      * Open a document by path. Closes any previously loaded document first.
      *
      * @param docPath - The document path to open
+     * @param options - Optional algorithm and metadata overrides
      */
-    load: (docPath: string) => Promise<void>;
+    load: (docPath: string, options?: OpenDocOptions) => Promise<void>;
     /**
      * Close the current document, unsubscribe, and reset all state.
      * Calls `patches.closeDoc()` but does not untrack — tracking is managed separately.
@@ -102,8 +106,9 @@ interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<
      *
      * @param docPath - The document path to create
      * @param initialState - Initial state object or JSONPatch to apply
+     * @param options - Optional algorithm and metadata overrides
      */
-    create: (docPath: string, initialState: T | JSONPatch) => Promise<void>;
+    create: (docPath: string, initialState: T | JSONPatch, options?: OpenDocOptions) => Promise<void>;
 }
 /**
  * Solid primitive for reactive Patches document state.
@@ -185,7 +190,7 @@ type MaybeAccessor<T> = T | Accessor<T>;
 /**
  * Props for the Provider component returned by createPatchesDoc.
  */
-interface PatchesDocProviderProps {
+interface PatchesDocProviderProps extends OpenDocOptions {
     docId: MaybeAccessor<string>;
     autoClose?: boolean | 'untrack';
     children: any;

package/dist/solid/primitives.js

@@ -10,47 +10,87 @@ import {
 import { JSONPatch } from "../json-patch/JSONPatch.js";
 import { usePatchesContext } from "./context.js";
 import { getDocManager } from "./doc-manager.js";
-function usePatchesDoc(docIdOrOptions, options) {
-  if (typeof docIdOrOptions === "string" || typeof docIdOrOptions === "function") {
-    return _usePatchesDocEager(docIdOrOptions, options ?? {});
-  }
-  return _usePatchesDocLazy(docIdOrOptions ?? {});
-}
-function _usePatchesDocEager(docId, options) {
-  const { patches } = usePatchesContext();
-  const autoClose = options.autoClose ?? false;
-  const shouldUntrack = autoClose === "untrack";
+function createDocReactiveState(options) {
+  const { initialLoading = true, transformState, changeBehavior } = options;
   const [doc, setDoc] = createSignal(void 0);
   const [data, setData] = createSignal(void 0);
-  const [loading, setLoading] = createSignal(true);
+  const [loading, setLoading] = createSignal(initialLoading);
   const [error, setError] = createSignal(null);
   const [rev, setRev] = createSignal(0);
   const [hasPending, setHasPending] = createSignal(false);
-  const manager = getDocManager(patches);
-  const docIdAccessor = toAccessor(docId);
   function setupDoc(patchesDoc) {
     setDoc(patchesDoc);
     const unsubState = patchesDoc.subscribe((state) => {
+      if (transformState && state) {
+        state = transformState(state, patchesDoc);
+      }
       setData(() => state);
       setRev(patchesDoc.committedRev);
       setHasPending(patchesDoc.hasPending);
     });
-    onCleanup(() => unsubState());
     const unsubSync = patchesDoc.onSyncing((syncState) => {
       setLoading(syncState === "initial" || syncState === "updating");
       setError(syncState instanceof Error ? syncState : null);
     });
-    onCleanup(() => unsubSync());
     setLoading(patchesDoc.syncing !== null);
+    return () => {
+      unsubState();
+      unsubSync();
+    };
   }
+  function resetSignals() {
+    setDoc(void 0);
+    setData(void 0);
+    setLoading(false);
+    setError(null);
+    setRev(0);
+    setHasPending(false);
+  }
+  function change(mutator) {
+    if (changeBehavior === "throw") {
+      const currentDoc = doc();
+      if (!currentDoc) {
+        throw new Error("Cannot make changes: document not loaded yet");
+      }
+      currentDoc.change(mutator);
+    } else {
+      doc()?.change(mutator);
+    }
+  }
+  const baseReturn = {
+    data,
+    loading,
+    error,
+    rev,
+    hasPending,
+    change,
+    doc
+  };
+  return { doc, setDoc, data, setData, loading, setLoading, error, setError, rev, setRev, hasPending, setHasPending, setupDoc, resetSignals, change, baseReturn };
+}
+function usePatchesDoc(docIdOrOptions, options) {
+  if (typeof docIdOrOptions === "string" || typeof docIdOrOptions === "function") {
+    return _usePatchesDocEager(docIdOrOptions, options ?? {});
+  }
+  return _usePatchesDocLazy(docIdOrOptions ?? {});
+}
+function _usePatchesDocEager(docId, options) {
+  const { patches } = usePatchesContext();
+  const { autoClose = false, algorithm, metadata } = options;
+  const shouldUntrack = autoClose === "untrack";
+  const openDocOpts = { algorithm, metadata };
+  const manager = getDocManager(patches);
+  const { setupDoc, setError, setLoading, baseReturn } = createDocReactiveState({ changeBehavior: "throw" });
+  const docIdAccessor = toAccessor(docId);
   if (autoClose) {
     const [docResource] = createResource(docIdAccessor, async (id) => {
-      return await manager.openDoc(patches, id);
+      return await manager.openDoc(patches, id, openDocOpts);
     });
     createEffect(() => {
       const loadedDoc = docResource();
       if (loadedDoc) {
-        setupDoc(loadedDoc);
+        const unsub = setupDoc(loadedDoc);
+        onCleanup(() => unsub());
       }
       const resourceError = docResource.error;
       if (resourceError) {
@@ -72,75 +112,31 @@ function _usePatchesDocEager(docId, options) {
         );
       }
       manager.incrementRefCount(id);
-      setupDoc(patchesDoc);
+      const unsub = setupDoc(patchesDoc);
       onCleanup(() => {
+        unsub();
         manager.decrementRefCount(id);
       });
     });
   }
-  function change(mutator) {
-    const currentDoc = doc();
-    if (!currentDoc) {
-      throw new Error("Cannot make changes: document not loaded yet");
-    }
-    currentDoc.change(mutator);
-  }
-  return {
-    data,
-    loading,
-    error,
-    rev,
-    hasPending,
-    change,
-    doc
-  };
+  return baseReturn;
 }
 function _usePatchesDocLazy(options) {
   const { patches } = usePatchesContext();
   const { idProp } = options;
-  let currentDoc = null;
+  const { setupDoc, resetSignals, setError, setLoading, baseReturn } = createDocReactiveState({
+    initialLoading: false,
+    changeBehavior: "noop",
+    transformState: idProp ? (state, patchesDoc) => ({ ...state, [idProp]: patchesDoc.id }) : void 0
+  });
   let unsubscribe = null;
   const [path, setPath] = createSignal(null);
-  const [doc, setDoc] = createSignal(void 0);
-  const [data, setData] = createSignal(void 0);
-  const [loading, setLoading] = createSignal(false);
-  const [error, setError] = createSignal(null);
-  const [rev, setRev] = createSignal(0);
-  const [hasPending, setHasPending] = createSignal(false);
-  function setupDoc(patchesDoc) {
-    currentDoc = patchesDoc;
-    setDoc(patchesDoc);
-    unsubscribe = patchesDoc.subscribe((state) => {
-      if (state && idProp && currentDoc) {
-        state = { ...state, [idProp]: currentDoc.id };
-      }
-      setData(() => state);
-      setRev(patchesDoc.committedRev);
-      setHasPending(patchesDoc.hasPending);
-    });
-    const unsubSync = patchesDoc.onSyncing((syncState) => {
-      setLoading(syncState === "initial" || syncState === "updating");
-      setError(syncState instanceof Error ? syncState : null);
-    });
-    const origUnsub = unsubscribe;
-    unsubscribe = () => {
-      origUnsub();
-      unsubSync();
-    };
-    setLoading(patchesDoc.syncing !== null);
-  }
   function teardown() {
     unsubscribe?.();
     unsubscribe = null;
-    currentDoc = null;
-    setDoc(void 0);
-    setData(void 0);
-    setLoading(false);
-    setError(null);
-    setRev(0);
-    setHasPending(false);
+    resetSignals();
   }
-  async function load(docPath) {
+  async function load(docPath, options2) {
     if (path()) {
       const prevPath = path();
       teardown();
@@ -148,8 +144,8 @@ function _usePatchesDocLazy(options) {
     }
     setPath(docPath);
     try {
-      const patchesDoc = await patches.openDoc(docPath);
-      setupDoc(patchesDoc);
+      const patchesDoc = await patches.openDoc(docPath, options2);
+      unsubscribe = setupDoc(patchesDoc);
     } catch (err) {
       setError(err);
       setLoading(false);
@@ -163,8 +159,8 @@ function _usePatchesDocLazy(options) {
       await patches.closeDoc(prevPath);
     }
   }
-  async function create(docPath, initialState) {
-    const newDoc = await patches.openDoc(docPath);
+  async function create(docPath, initialState, options2) {
+    const newDoc = await patches.openDoc(docPath, options2);
     newDoc.change((patch, root) => {
       if (initialState instanceof JSONPatch) {
         patch.ops = initialState.ops;
@@ -176,22 +172,7 @@ function _usePatchesDocLazy(options) {
     });
     await patches.closeDoc(docPath);
   }
-  function change(mutator) {
-    currentDoc?.change(mutator);
-  }
-  return {
-    data,
-    loading,
-    error,
-    rev,
-    hasPending,
-    change,
-    doc,
-    path,
-    load,
-    close,
-    create
-  };
+  return { ...baseReturn, path, load, close, create };
 }
 function usePatchesSync() {
   const { sync } = usePatchesContext();
@@ -225,36 +206,18 @@ function createPatchesDoc(name) {
     const manager = getDocManager(patches);
     const autoClose = props.autoClose ?? false;
     const shouldUntrack = autoClose === "untrack";
-    const [doc, setDoc] = createSignal(void 0);
-    const [data, setData] = createSignal(void 0);
-    const [loading, setLoading] = createSignal(true);
-    const [error, setError] = createSignal(null);
-    const [rev, setRev] = createSignal(0);
-    const [hasPending, setHasPending] = createSignal(false);
-    function setupDoc(patchesDoc) {
-      setDoc(patchesDoc);
-      const unsubState = patchesDoc.subscribe((state) => {
-        setData(() => state);
-        setRev(patchesDoc.committedRev);
-        setHasPending(patchesDoc.hasPending);
-      });
-      onCleanup(() => unsubState());
-      const unsubSync = patchesDoc.onSyncing((syncState) => {
-        setLoading(syncState === "initial" || syncState === "updating");
-        setError(syncState instanceof Error ? syncState : null);
-      });
-      onCleanup(() => unsubSync());
-      setLoading(patchesDoc.syncing !== null);
-    }
+    const openDocOpts = { algorithm: props.algorithm, metadata: props.metadata };
+    const { setupDoc, setError, setLoading, baseReturn } = createDocReactiveState({ changeBehavior: "throw" });
     const docIdAccessor = toAccessor(props.docId);
     if (autoClose) {
       const [docResource] = createResource(docIdAccessor, async (id) => {
-        return await manager.openDoc(patches, id);
+        return await manager.openDoc(patches, id, openDocOpts);
       });
       createEffect(() => {
         const loadedDoc = docResource();
         if (loadedDoc) {
-          setupDoc(loadedDoc);
+          const unsub = setupDoc(loadedDoc);
+          onCleanup(() => unsub());
         }
         const resourceError = docResource.error;
         if (resourceError) {
@@ -286,7 +249,8 @@ function createPatchesDoc(name) {
           );
         }
         manager.incrementRefCount(id);
-        setupDoc(patchesDoc);
+        const unsub = setupDoc(patchesDoc);
+        onCleanup(() => unsub());
         return id;
       });
       onCleanup(() => {
@@ -294,23 +258,7 @@ function createPatchesDoc(name) {
         manager.decrementRefCount(id);
       });
     }
-    function change(mutator) {
-      const currentDoc = doc();
-      if (!currentDoc) {
-        throw new Error("Cannot make changes: document not loaded yet");
-      }
-      currentDoc.change(mutator);
-    }
-    const value = {
-      data,
-      loading,
-      error,
-      rev,
-      hasPending,
-      change,
-      doc
-    };
-    return /* @__PURE__ */ React.createElement(Context.Provider, { value, children: props.children });
+    return /* @__PURE__ */ React.createElement(Context.Provider, { value: baseReturn, children: props.children });
   }
   function useDoc() {
     const context = useContext(Context);

package/dist/vue/composables.d.ts

@@ -1,15 +1,18 @@
 import { ShallowRef, Ref, MaybeRef } from 'vue';
-import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
+import { OpenDocOptions } from '../client/Patches.js';
+import { a as PatchesDoc } from '../BaseDoc-_Rsau70J.js';
 import { JSONPatch } from '../json-patch/JSONPatch.js';
 import { ChangeMutator } from '../types.js';
 import '../event-signal.js';
 import '../json-patch/types.js';
+import '../client/ClientAlgorithm.js';
+import '../client/PatchesStore.js';
 import '@dabble/delta';
 
 /**
  * Options for usePatchesDoc composable (eager mode with docId).
  */
-interface UsePatchesDocOptions {
+interface UsePatchesDocOptions extends OpenDocOptions {
     /**
      * Controls document lifecycle management on component unmount.
      *
@@ -89,8 +92,9 @@ interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<
      * Open a document by path. Closes any previously loaded document first.
      *
      * @param docPath - The document path to open
+     * @param options - Optional algorithm and metadata overrides
      */
-    load: (docPath: string) => Promise<void>;
+    load: (docPath: string, options?: OpenDocOptions) => Promise<void>;
     /**
      * Close the current document, unsubscribe, and reset all state.
      * Calls `patches.closeDoc()` but does not untrack — tracking is managed separately.
@@ -102,8 +106,9 @@ interface UsePatchesDocLazyReturn<T extends object> extends UsePatchesDocReturn<
      *
      * @param docPath - The document path to create
      * @param initialState - Initial state object or JSONPatch to apply
+     * @param options - Optional algorithm and metadata overrides
      */
-    create: (docPath: string, initialState: T | JSONPatch) => Promise<void>;
+    create: (docPath: string, initialState: T | JSONPatch, options?: OpenDocOptions) => Promise<void>;
 }
 /**
  * Vue composable for reactive Patches document state.