@dabble/patches 0.8.7 → 0.8.9

package/dist/server/OTBranchManager.js

@@ -5,7 +5,7 @@ import { createChange } from "../data/change.js";
 import { createVersionMetadata } from "../data/version.js";
 import {
   assertBranchMetadata,
-  assertBranchOpenForMerge,
+  assertBranchExists,
   assertNotABranch,
   branchManagerApi,
   createBranchRecord,
@@ -22,41 +22,56 @@ class OTBranchManager {
   /**
    * Lists all open branches for a document.
    * @param docId - The ID of the document.
+   * @param options - Optional filtering options (e.g. `since` for incremental sync).
    * @returns The branches.
    */
-  async listBranches(docId) {
-    return await this.store.listBranches(docId);
+  async listBranches(docId, options) {
+    return await this.store.listBranches(docId, options);
   }
   /**
    * Creates a new branch for a document.
    * @param docId - The ID of the document to branch from.
    * @param rev - The revision of the document to branch from.
-   * @param branchName - Optional name for the branch.
-   * @param metadata - Additional optional metadata to store with the branch.
    * @returns The ID of the new branch document.
    */
   async createBranch(docId, rev, metadata) {
+    const branchDocId = metadata?.id ?? await generateBranchId(this.store, docId);
+    if (metadata?.id) {
+      const existing = await this.store.loadBranch(branchDocId);
+      if (existing) {
+        if (existing.docId !== docId) {
+          throw new Error(`Branch ${branchDocId} already exists for a different document`);
+        }
+        return branchDocId;
+      }
+    }
     await assertNotABranch(this.store, docId);
-    const { state: stateAtRev } = await getStateAtRevision(this.store, docId, rev);
-    const branchDocId = await generateBranchId(this.store, docId);
     const now = Date.now();
-    const initialChange = createChange(0, 1, [{ op: "replace", path: "", value: stateAtRev }], {
-      createdAt: now,
-      committedAt: now
-    });
-    await this.store.saveChanges(branchDocId, [initialChange]);
-    const initialVersionMetadata = createVersionMetadata({
-      origin: "main",
-      startedAt: now,
-      endedAt: now,
-      endRev: rev,
-      startRev: rev,
-      name: metadata?.name,
-      groupId: branchDocId,
-      branchName: metadata?.name
-    });
-    await this.store.createVersion(branchDocId, initialVersionMetadata, [initialChange]);
-    const branch = createBranchRecord(branchDocId, docId, rev, metadata);
+    let contentStartRev;
+    if (metadata?.contentStartRev) {
+      contentStartRev = metadata.contentStartRev;
+    } else {
+      const { state: stateAtRev } = await getStateAtRevision(this.store, docId, rev);
+      const rootReplace = createChange(0, 1, [{ op: "replace", path: "", value: stateAtRev }], {
+        createdAt: now,
+        committedAt: now
+      });
+      const initChanges = this.maxPayloadBytes ? breakChanges([rootReplace], this.maxPayloadBytes) : [rootReplace];
+      contentStartRev = initChanges[initChanges.length - 1].rev + 1;
+      await this.store.saveChanges(branchDocId, initChanges);
+      const initialVersionMetadata = createVersionMetadata({
+        origin: "main",
+        startedAt: now,
+        endedAt: now,
+        endRev: rev,
+        startRev: rev,
+        name: metadata?.name,
+        groupId: branchDocId,
+        branchName: metadata?.name
+      });
+      await this.store.createVersion(branchDocId, initialVersionMetadata, initChanges);
+    }
+    const branch = createBranchRecord(branchDocId, docId, rev, contentStartRev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
   }
@@ -67,78 +82,65 @@ class OTBranchManager {
    */
   async updateBranch(branchId, metadata) {
     assertBranchMetadata(metadata);
-    await this.store.updateBranch(branchId, metadata);
+    await this.store.updateBranch(branchId, { ...metadata, modifiedAt: Date.now() });
   }
   /**
-   * Closes a branch, marking it as merged or deleted.
-   * @param branchId - The ID of the branch to close.
-   * @param status - The status to set for the branch.
+   * Deletes a branch, replacing the record with a tombstone.
    */
-  async closeBranch(branchId, status) {
-    await this.store.updateBranch(branchId, { status: status ?? "closed" });
+  async deleteBranch(branchId) {
+    await this.store.deleteBranch(branchId);
   }
   /**
    * Merges changes from a branch back into its source document.
+   *
+   * Supports multiple merges — the branch stays open and `lastMergedRev` tracks
+   * which branch revision was last merged. Subsequent merges only pick up new changes.
+   *
+   * All merge changes use `batchId: branchId` so that `commitChanges` never transforms
+   * branch changes against each other (they share the same causal context).
+   *
    * @param branchId - The ID of the branch document to merge.
    * @returns The server commit change(s) applied to the source document.
    * @throws Error if branch not found, already closed/merged, or merge fails.
    */
   async mergeBranch(branchId) {
     const branch = await this.store.loadBranch(branchId);
-    assertBranchOpenForMerge(branch, branchId);
+    assertBranchExists(branch, branchId);
     const sourceDocId = branch.docId;
     const branchStartRevOnSource = branch.branchedAtRev;
-    const branchChanges = await this.store.listChanges(branchId, {});
+    const startAfter = branch.lastMergedRev ?? (branch.contentStartRev ?? 2) - 1;
+    const branchChanges = await this.store.listChanges(branchId, { startAfter });
     if (branchChanges.length === 0) {
-      console.log(`Branch ${branchId} has no changes to merge.`);
-      await this.closeBranch(branchId, "merged");
       return [];
     }
-    const sourceChanges = await this.store.listChanges(sourceDocId, {
-      startAfter: branchStartRevOnSource
-    });
-    const canFastForward = sourceChanges.length === 0;
+    const lastBranchRev = branchChanges[branchChanges.length - 1].rev;
     const branchVersions = await this.store.listVersions(branchId, { origin: "main" });
-    const versionOrigin = canFastForward ? "main" : "branch";
     let lastVersionId;
     for (const v of branchVersions) {
       const newVersionMetadata = createVersionMetadata({
         ...v,
-        origin: versionOrigin,
+        origin: "branch",
         startRev: branchStartRevOnSource,
         groupId: branchId,
         branchName: branch.name,
-        // Keep branchName for traceability
         parentId: lastVersionId
       });
       const changes = await this.store.loadVersionChanges?.(branchId, v.id);
       await this.store.createVersion(sourceDocId, newVersionMetadata, changes);
       lastVersionId = newVersionMetadata.id;
     }
+    const changesToCommit = branchChanges.map((c, i) => ({
+      ...c,
+      baseRev: branchStartRevOnSource,
+      rev: branchStartRevOnSource + i + 1,
+      batchId: branchId
+    }));
     const committedMergeChanges = await wrapMergeCommit(branchId, sourceDocId, async () => {
-      if (canFastForward) {
-        const adjustedChanges = branchChanges.map((c) => ({
-          ...c,
-          baseRev: branchStartRevOnSource,
-          rev: void 0
-          // Let commitChanges assign sequential revs
-        }));
-        return (await this.patchesServer.commitChanges(sourceDocId, adjustedChanges)).changes;
-      } else {
-        const rev = branchStartRevOnSource + branchChanges.length;
-        const flattenedChange = createChange(
-          branchStartRevOnSource,
-          rev,
-          branchChanges.flatMap((c) => c.ops)
-        );
-        let changesToCommit = [flattenedChange];
-        if (this.maxPayloadBytes) {
-          changesToCommit = breakChanges(changesToCommit, this.maxPayloadBytes);
-        }
-        return (await this.patchesServer.commitChanges(sourceDocId, changesToCommit)).changes;
-      }
+      return (await this.patchesServer.commitChanges(sourceDocId, changesToCommit)).changes;
     });
-    await this.closeBranch(branchId, "merged");
+    const currentBranch = await this.store.loadBranch(branchId);
+    const effectiveLastMergedRev = Math.max(lastBranchRev, currentBranch?.lastMergedRev ?? 0);
+    await this.store.updateBranch(branchId, { lastMergedRev: effectiveLastMergedRev, modifiedAt: Date.now() });
     return committedMergeChanges;
   }
 }

package/dist/server/branchUtils.d.ts

@@ -1,5 +1,5 @@
 import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
-import { EditableBranchMetadata, Branch, BranchStatus } from '../types.js';
+import { EditableBranchMetadata, Branch, CreateBranchMetadata } from '../types.js';
 import 'easy-signal';
 import '../net/websocket/AuthorizationProvider.js';
 import './types.js';
@@ -36,10 +36,11 @@ declare function generateBranchId(store: BranchIdGenerator, docId: string): Prom
  * @param branchDocId - The branch document ID.
  * @param sourceDocId - The source document being branched from.
  * @param branchedAtRev - The revision at which the branch was created.
+ * @param contentStartRev - The first revision of user content on the branch (after init changes).
  * @param metadata - Optional branch metadata (name, etc.).
  * @returns A new Branch object.
  */
-declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, metadata?: EditableBranchMetadata): Branch;
+declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, contentStartRev: number, metadata?: CreateBranchMetadata | EditableBranchMetadata): Branch;
 /**
  * Store interface for branch loading.
  */
@@ -54,12 +55,12 @@ interface BranchLoader {
  */
 declare function assertNotABranch(store: BranchLoader, docId: string): Promise<void>;
 /**
- * Validates that a branch exists and is open for merging.
+ * Validates that a branch exists.
  * @param branch - The branch to validate (may be null).
  * @param branchId - The branch ID (for error messages).
- * @throws Error if branch not found or not open.
+ * @throws Error if branch not found.
  */
-declare function assertBranchOpenForMerge(branch: Branch | null, branchId: string): asserts branch is Branch;
+declare function assertBranchExists(branch: Branch | null, branchId: string): asserts branch is Branch;
 /**
  * Wraps a merge commit operation with standard error handling.
  * @param branchId - The branch being merged.
@@ -69,14 +70,5 @@ declare function assertBranchOpenForMerge(branch: Branch | null, branchId: strin
  * @throws Error with standardized message if commit fails.
  */
 declare function wrapMergeCommit<T>(branchId: string, sourceDocId: string, commitFn: () => Promise<T>): Promise<T>;
-/**
- * Standard close branch operation.
- * @param store - Store with updateBranch capability.
- * @param branchId - The branch to close.
- * @param status - The status to set (defaults to 'closed').
- */
-declare function closeBranch(store: {
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name'>>): Promise<void>;
-}, branchId: string, status?: Exclude<BranchStatus, 'open'> | null): Promise<void>;
 
-export { type BranchIdGenerator, type BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, closeBranch, createBranchRecord, generateBranchId, wrapMergeCommit };
+export { type BranchIdGenerator, type BranchLoader, assertBranchExists, assertBranchMetadata, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit };

package/dist/server/branchUtils.js

@@ -4,10 +4,19 @@ const branchManagerApi = {
   listBranches: "read",
   createBranch: "write",
   updateBranch: "write",
-  closeBranch: "write",
+  deleteBranch: "write",
   mergeBranch: "write"
 };
-const nonModifiableBranchFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status"]);
+const nonModifiableBranchFields = /* @__PURE__ */ new Set([
+  "id",
+  "docId",
+  "branchedAtRev",
+  "createdAt",
+  "modifiedAt",
+  "contentStartRev",
+  "pendingOp",
+  "deleted"
+]);
 function assertBranchMetadata(metadata) {
   if (!metadata) return;
   for (const key in metadata) {
@@ -19,14 +28,16 @@ function assertBranchMetadata(metadata) {
 async function generateBranchId(store, docId) {
   return store.createBranchId ? await Promise.resolve(store.createBranchId(docId)) : createId(22);
 }
-function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, metadata) {
+function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, contentStartRev, metadata) {
+  const now = Date.now();
   return {
     ...metadata,
     id: branchDocId,
     docId: sourceDocId,
     branchedAtRev,
-    createdAt: Date.now(),
-    status: "open"
+    contentStartRev,
+    createdAt: now,
+    modifiedAt: now
   };
 }
 async function assertNotABranch(store, docId) {
@@ -35,13 +46,10 @@ async function assertNotABranch(store, docId) {
     throw new Error("Cannot create a branch from another branch.");
   }
 }
-function assertBranchOpenForMerge(branch, branchId) {
+function assertBranchExists(branch, branchId) {
   if (!branch) {
     throw new Error(`Branch with ID ${branchId} not found.`);
   }
-  if (branch.status !== "open") {
-    throw new Error(`Branch ${branchId} is not open (status: ${branch.status}). Cannot merge.`);
-  }
 }
 async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
   try {
@@ -51,15 +59,11 @@ async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
     throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
   }
 }
-async function closeBranch(store, branchId, status) {
-  await store.updateBranch(branchId, { status: status ?? "closed" });
-}
 export {
+  assertBranchExists,
   assertBranchMetadata,
-  assertBranchOpenForMerge,
   assertNotABranch,
   branchManagerApi,
-  closeBranch,
   createBranchRecord,
   generateBranchId,
   wrapMergeCommit

package/dist/server/index.d.ts

@@ -9,7 +9,7 @@ export { buildVersionState, getBaseStateBeforeVersion } from '../algorithms/ot/s
 export { concatStreams, jsonReadable, parseVersionState, readStreamAsString } from './jsonReadable.js';
 export { blockable, blockableResponse, blocking, releaseConcurrency, singleInvocation } from '../utils/concurrency.js';
 export { RevConflictError } from './RevConflictError.js';
-export { BranchIdGenerator, BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit } from './branchUtils.js';
+export { BranchIdGenerator, BranchLoader, assertBranchExists, assertBranchMetadata, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit } from './branchUtils.js';
 export { CompressedStoreBackend } from './CompressedStoreBackend.js';
 export { createTombstoneIfSupported, isTombstoneStore, removeTombstoneIfExists } from './tombstone.js';
 export { assertVersionMetadata } from './utils.js';

package/dist/server/index.js

@@ -11,7 +11,7 @@ import { blockable, blockableResponse, blocking, releaseConcurrency, singleInvoc
 import { RevConflictError } from "./RevConflictError.js";
 import {
   assertBranchMetadata,
-  assertBranchOpenForMerge,
+  assertBranchExists,
   assertNotABranch,
   branchManagerApi,
   createBranchRecord,
@@ -30,8 +30,8 @@ export {
   OTServer,
   PatchesHistoryManager,
   RevConflictError,
+  assertBranchExists,
   assertBranchMetadata,
-  assertBranchOpenForMerge,
   assertNotABranch,
   assertVersionMetadata,
   blockable,

package/dist/server/types.d.ts

@@ -1,5 +1,5 @@
 import { JSONPatchOp } from '../json-patch/types.js';
-import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, Branch } from '../types.js';
+import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, ListBranchesOptions, Branch } from '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
@@ -150,13 +150,19 @@ interface BranchingStoreBackend {
      */
     createBranchId?(docId: string): Promise<string> | string;
     /** Lists metadata records for branches originating from a document. */
-    listBranches(docId: string): Promise<Branch[]>;
+    listBranches(docId: string, options?: ListBranchesOptions): Promise<Branch[]>;
     /** Loads the metadata record for a specific branch ID. */
     loadBranch(branchId: string): Promise<Branch | null>;
     /** Creates or updates the metadata record for a branch. */
     createBranch(branch: Branch): Promise<void>;
-    /** Updates specific fields (status, name, metadata) of an existing branch record. */
-    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name' | 'metadata'>>): Promise<void>;
+    /** Updates mutable fields of an existing branch record (excludes immutable identity fields). */
+    updateBranch(branchId: string, updates: Partial<Omit<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'contentStartRev'>>): Promise<void>;
+    /**
+     * Replaces a branch record with a tombstone containing only `id`, `docId`, `modifiedAt`,
+     * and `deleted: true`. Tombstones are returned by `listBranches` when `since` is provided
+     * so that clients can clean up their local cache.
+     */
+    deleteBranch(branchId: string): Promise<void>;
 }
 
 export type { BranchingStoreBackend, LWWStoreBackend, ListFieldsOptions, OTStoreBackend, ServerStoreBackend, SnapshotResult, TombstoneStoreBackend, VersioningStoreBackend };

package/dist/solid/context.d.ts

@@ -10,6 +10,7 @@ import '../client/ClientAlgorithm.js';
 import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/dist/solid/index.d.ts

@@ -15,6 +15,7 @@ import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/dist/types.d.ts

@@ -81,8 +81,6 @@ interface DocSyncState {
     syncError?: Error;
     isLoaded: boolean;
 }
-/** Status options for a branch */
-type BranchStatus = 'open' | 'closed' | 'merged' | 'archived' | 'abandoned';
 interface Branch {
     /** The ID of the branch document. */
     id: string;
@@ -92,14 +90,53 @@ interface Branch {
     branchedAtRev: number;
     /** Unix timestamp in milliseconds when the branch was created. */
     createdAt: number;
+    /** Unix timestamp in milliseconds when the branch was last modified. Updated on metadata changes. */
+    modifiedAt: number;
     /** Optional user-friendly name for the branch. */
     name?: string;
-    /** Current status of the branch. */
-    status: BranchStatus;
+    /**
+     * The first revision on the branch that contains user content (after initialization changes).
+     * Initialization changes (e.g. the root-replace that seeds the branch with source state)
+     * are at revisions < contentStartRev and are skipped during merge.
+     * Typically 2 for a single-change initialization; higher when the initial state is split
+     * across multiple changes due to size limits.
+     */
+    contentStartRev: number;
+    /**
+     * The branch-side revision through which changes have already been merged.
+     * Set after each merge so subsequent merges only pick up new changes.
+     * Undefined means the branch has never been merged.
+     */
+    lastMergedRev?: number;
+    /** The pending operation to sync to the server. Set by BranchClientStore methods. */
+    pendingOp?: 'create' | 'update' | 'delete';
+    /** True when this branch has been deleted. Stored as a tombstone for incremental sync. */
+    deleted?: true;
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
-type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'status'>;
+type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'modifiedAt' | 'contentStartRev' | 'pendingOp' | 'deleted'>;
+/**
+ * Metadata for creating a new branch.
+ * Allows `id` and `contentStartRev` in addition to the fields allowed by `EditableBranchMetadata`.
+ * - `id`: Client-provided branch document ID. Required for offline branch creation.
+ * - `contentStartRev`: The first revision of user content. Set by the client when creating
+ *   initial changes offline (the server uses this to know where user content begins during merge).
+ */
+type CreateBranchMetadata = Omit<Disallowed<Branch, 'docId' | 'branchedAtRev' | 'createdAt' | 'modifiedAt' | 'pendingOp' | 'deleted'>, 'contentStartRev'> & {
+    contentStartRev?: number;
+};
+/**
+ * Options for listing branches.
+ */
+interface ListBranchesOptions {
+    /**
+     * Only return branches modified after this timestamp (Unix ms).
+     * Enables incremental sync: after the initial full list, subsequent calls can pass the
+     * most recent `modifiedAt` value to fetch only updates.
+     */
+    since?: number;
+}
 /**
  * Represents a tombstone for a deleted document.
  * Tombstones persist after deletion to inform late-connecting clients
@@ -239,4 +276,4 @@ type PathProxy<T = any> = IsAny<T> extends true ? DeepPathProxy : {
  */
 type ChangeMutator<T> = (patch: JSONPatch, root: PathProxy<T>) => void;
 
-export type { Branch, BranchStatus, Change, ChangeInput, ChangeMutator, CommitChangesOptions, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata };
+export type { Branch, Change, ChangeInput, ChangeMutator, CommitChangesOptions, CreateBranchMetadata, DeleteDocOptions, DocSyncState, DocSyncStatus, DocumentTombstone, EditableBranchMetadata, EditableVersionMetadata, ListBranchesOptions, ListChangesOptions, ListVersionsOptions, PatchesSnapshot, PatchesState, PathProxy, VersionMetadata };

package/dist/vue/index.d.ts

@@ -15,6 +15,7 @@ import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/dist/vue/provider.d.ts

@@ -10,6 +10,7 @@ import '../client/ClientAlgorithm.js';
 import '../BaseDoc-BT18xPxU.js';
 import '../client/PatchesStore.js';
 import '../algorithms/ot/shared/changeBatching.js';
+import '../client/BranchClientStore.js';
 import '../net/PatchesConnection.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';

package/package.json

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