@dabble/patches 0.6.0 → 0.7.1

package/dist/server/{PatchesBranchManager.js → OTBranchManager.js}

@@ -1,14 +1,24 @@
 import "../chunk-IZ2YBCUP.js";
-import { createId } from "crypto-id";
-import { breakChanges } from "../algorithms/shared/changeBatching.js";
+import { getStateAtRevision } from "../algorithms/ot/server/getStateAtRevision.js";
+import { breakChanges } from "../algorithms/ot/shared/changeBatching.js";
 import { createChange } from "../data/change.js";
 import { createVersionMetadata } from "../data/version.js";
-class PatchesBranchManager {
+import {
+  assertBranchMetadata,
+  assertBranchOpenForMerge,
+  assertNotABranch,
+  branchManagerApi,
+  createBranchRecord,
+  generateBranchId,
+  wrapMergeCommit
+} from "./branchUtils.js";
+class OTBranchManager {
   constructor(store, patchesServer, maxPayloadBytes) {
     this.store = store;
     this.patchesServer = patchesServer;
     this.maxPayloadBytes = maxPayloadBytes;
   }
+  static api = branchManagerApi;
   /**
    * Lists all open branches for a document.
    * @param docId - The ID of the document.
@@ -26,12 +36,9 @@ class PatchesBranchManager {
    * @returns The ID of the new branch document.
    */
   async createBranch(docId, rev, metadata) {
-    const maybeBranch = await this.store.loadBranch(docId);
-    if (maybeBranch) {
-      throw new Error("Cannot create a branch from another branch.");
-    }
-    const stateAtRev = (await this.patchesServer.getStateAtRevision(docId, rev)).state;
-    const branchDocId = this.store.createBranchId ? await Promise.resolve(this.store.createBranchId(docId)) : createId(22);
+    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 initialVersionMetadata = createVersionMetadata({
       origin: "main",
@@ -45,14 +52,7 @@ class PatchesBranchManager {
       branchName: metadata?.name
     });
     await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
-    const branch = {
-      ...metadata,
-      id: branchDocId,
-      docId,
-      branchedAtRev: rev,
-      createdAt: now,
-      status: "open"
-    };
+    const branch = createBranchRecord(branchDocId, docId, rev, metadata);
     await this.store.createBranch(branch);
     return branchDocId;
   }
@@ -81,12 +81,7 @@ class PatchesBranchManager {
    */
   async mergeBranch(branchId) {
     const branch = await this.store.loadBranch(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.`);
-    }
+    assertBranchOpenForMerge(branch, branchId);
     const sourceDocId = branch.docId;
     const branchStartRevOnSource = branch.branchedAtRev;
     const branchChanges = await this.store.listChanges(branchId, {});
@@ -113,12 +108,11 @@ class PatchesBranchManager {
         parentId: lastVersionId
       });
       const state = await this.store.loadVersionState(branchId, v.id);
-      const changes = await this.store.loadVersionChanges(branchId, v.id);
+      const changes = await this.store.loadVersionChanges?.(branchId, v.id);
       await this.store.createVersion(sourceDocId, newVersionMetadata, state, changes);
       lastVersionId = newVersionMetadata.id;
     }
-    let committedMergeChanges = [];
-    try {
+    const committedMergeChanges = await wrapMergeCommit(branchId, sourceDocId, async () => {
       if (canFastForward) {
         const adjustedChanges = branchChanges.map((c) => ({
           ...c,
@@ -126,7 +120,7 @@ class PatchesBranchManager {
           rev: void 0
           // Let commitChanges assign sequential revs
         }));
-        [, committedMergeChanges] = await this.patchesServer.commitChanges(sourceDocId, adjustedChanges);
+        return this.patchesServer.commitChanges(sourceDocId, adjustedChanges);
       } else {
         const rev = branchStartRevOnSource + branchChanges.length;
         const flattenedChange = createChange(
@@ -138,26 +132,17 @@ class PatchesBranchManager {
         if (this.maxPayloadBytes) {
           changesToCommit = breakChanges(changesToCommit, this.maxPayloadBytes);
         }
-        [, committedMergeChanges] = await this.patchesServer.commitChanges(sourceDocId, changesToCommit);
+        return this.patchesServer.commitChanges(sourceDocId, changesToCommit);
       }
-    } catch (error) {
-      console.error(`Failed to merge branch ${branchId} into ${sourceDocId}:`, error);
-      throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    });
     await this.closeBranch(branchId, "merged");
     return committedMergeChanges;
   }
 }
-const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status"]);
-function assertBranchMetadata(metadata) {
-  if (!metadata) return;
-  for (const key in metadata) {
-    if (nonModifiableMetadataFields.has(key)) {
-      throw new Error(`Cannot modify branch field ${key}`);
-    }
-  }
-}
+import { assertBranchMetadata as assertBranchMetadata2 } from "./branchUtils.js";
+const PatchesBranchManager = OTBranchManager;
 export {
+  OTBranchManager,
   PatchesBranchManager,
-  assertBranchMetadata
+  assertBranchMetadata2 as assertBranchMetadata
 };

package/dist/server/OTServer.d.ts

@@ -0,0 +1,108 @@
+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 { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+import '../net/websocket/AuthorizationProvider.js';
+import '../net/protocol/types.js';
+
+/**
+ * Configuration options for the OTServer.
+ */
+interface OTServerOptions {
+    /**
+     * The maximum time difference in minutes between consecutive changes
+     * to be considered part of the same editing session for versioning.
+     * Defaults to 30 minutes.
+     */
+    sessionTimeoutMinutes?: number;
+    /**
+     * Maximum size in bytes for a single change's storage representation.
+     * Useful for databases with row size limits.
+     */
+    maxStorageBytes?: number;
+}
+/**
+ * Handles the server-side Operational Transformation (OT) logic,
+ * coordinating batches of changes, managing versioning based on sessions (including offline),
+ * and persisting data using a backend store.
+ *
+ * For compression support, wrap your store with CompressedStoreBackend before passing it:
+ * @example
+ * import { OTServer, CompressedStoreBackend } from '@dabble/patches/server';
+ * import { base64Compressor } from '@dabble/patches/compression';
+ *
+ * const compressedStore = new CompressedStoreBackend(store, base64Compressor);
+ * const server = new OTServer(compressedStore);
+ */
+declare class OTServer implements PatchesServer {
+    /**
+     * Static API definition for use with JSONRPCServer.register().
+     * Maps method names to required access levels.
+     */
+    static api: ApiDefinition;
+    private readonly sessionTimeoutMillis;
+    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>;
+    /** Notifies listeners when a document is deleted. */
+    readonly onDocDeleted: Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
+    constructor(store: OTStoreBackend, options?: OTServerOptions);
+    /**
+     * Get the current state of a document.
+     * @param docId - The ID of the document.
+     * @returns The current state of the document.
+     */
+    getDoc(docId: string): Promise<PatchesState>;
+    /**
+     * Get changes that occurred after a specific revision.
+     * @param docId - The ID of the document.
+     * @param rev - The revision number.
+     * @returns The changes that occurred after the specified revision.
+     */
+    getChangesSince(docId: string, rev: number): Promise<Change[]>;
+    /**
+     * Commits a set of changes to a document, applying operational transformation as needed.
+     *
+     * Returns all changes the client needs to apply: both catchup changes (from other
+     * clients) and the client's own transformed changes. Only the new changes are
+     * broadcast to other clients.
+     *
+     * @param docId - The ID of the document.
+     * @param changes - The changes to commit.
+     * @param options - Optional commit settings (e.g., forceCommit for migrations).
+     * @returns Combined array of catchup changes followed by the client's committed changes.
+     */
+    commitChanges(docId: string, changes: ChangeInput[], options?: CommitChangesOptions): Promise<Change[]>;
+    /**
+     * Make a server-side change to a document.
+     * @param mutator
+     * @returns
+     */
+    change<T = Record<string, any>>(docId: string, mutator: ChangeMutator<T>, metadata?: Record<string, any>): Promise<Change | null>;
+    /**
+     * Deletes a document.
+     * @param docId The document ID.
+     * @param options - Optional deletion settings (e.g., skipTombstone for testing).
+     */
+    deleteDoc(docId: string, options?: DeleteDocOptions): Promise<void>;
+    /**
+     * Removes the tombstone for a deleted document, allowing it to be recreated.
+     * @param docId The document ID.
+     * @returns True if tombstone was found and removed, false if no tombstone existed.
+     */
+    undeleteDoc(docId: string): Promise<boolean>;
+    /**
+     * Captures the current state of a document as a new version.
+     * @param docId The document ID.
+     * @param metadata Optional metadata for the version.
+     * @returns The ID of the created version.
+     */
+    captureCurrentVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string | null>;
+}
+
+export { CommitChangesOptions, OTServer, type OTServerOptions };

package/dist/server/OTServer.js

@@ -0,0 +1,141 @@
+import "../chunk-IZ2YBCUP.js";
+import { commitChanges } from "../algorithms/ot/server/commitChanges.js";
+import { createVersion } from "../algorithms/ot/server/createVersion.js";
+import { getSnapshotAtRevision } from "../algorithms/ot/server/getSnapshotAtRevision.js";
+import { getStateAtRevision } from "../algorithms/ot/server/getStateAtRevision.js";
+import { applyChanges } from "../algorithms/ot/shared/applyChanges.js";
+import { createChange } from "../data/change.js";
+import { signal } from "../event-signal.js";
+import { createJSONPatch } from "../json-patch/createJSONPatch.js";
+import { getClientId } from "../net/serverContext.js";
+import { createTombstoneIfSupported, removeTombstoneIfExists } from "./tombstone.js";
+import { assertVersionMetadata } from "./utils.js";
+class OTServer {
+  /**
+   * Static API definition for use with JSONRPCServer.register().
+   * Maps method names to required access levels.
+   */
+  static api = {
+    getDoc: "read",
+    getChangesSince: "read",
+    commitChanges: "write",
+    deleteDoc: "write",
+    undeleteDoc: "write"
+  };
+  sessionTimeoutMillis;
+  maxStorageBytes;
+  store;
+  /** Notifies listeners whenever a batch of changes is *successfully* committed. */
+  onChangesCommitted = signal();
+  /** Notifies listeners when a document is deleted. */
+  onDocDeleted = signal();
+  constructor(store, options = {}) {
+    this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1e3;
+    this.maxStorageBytes = options.maxStorageBytes;
+    this.store = store;
+  }
+  /**
+   * Get the current state of a document.
+   * @param docId - The ID of the document.
+   * @returns The current state of the document.
+   */
+  async getDoc(docId) {
+    return getStateAtRevision(this.store, docId);
+  }
+  /**
+   * Get changes that occurred after a specific revision.
+   * @param docId - The ID of the document.
+   * @param rev - The revision number.
+   * @returns The changes that occurred after the specified revision.
+   */
+  getChangesSince(docId, rev) {
+    return this.store.listChanges(docId, { startAfter: rev });
+  }
+  /**
+   * Commits a set of changes to a document, applying operational transformation as needed.
+   *
+   * Returns all changes the client needs to apply: both catchup changes (from other
+   * clients) and the client's own transformed changes. Only the new changes are
+   * broadcast to other clients.
+   *
+   * @param docId - The ID of the document.
+   * @param changes - The changes to commit.
+   * @param options - Optional commit settings (e.g., forceCommit for migrations).
+   * @returns Combined array of catchup changes followed by the client's committed changes.
+   */
+  async commitChanges(docId, changes, options) {
+    const { catchupChanges, newChanges } = await commitChanges(
+      this.store,
+      docId,
+      changes,
+      this.sessionTimeoutMillis,
+      options,
+      this.maxStorageBytes
+    );
+    if (newChanges.length > 0) {
+      try {
+        await this.onChangesCommitted.emit(docId, newChanges, getClientId());
+      } catch (error) {
+        console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
+      }
+    }
+    return [...catchupChanges, ...newChanges];
+  }
+  /**
+   * 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(mutator);
+    if (patch.ops.length === 0) {
+      return null;
+    }
+    const change = createChange(rev, rev + 1, patch.ops, metadata);
+    patch.apply(state);
+    await this.commitChanges(docId, [change]);
+    return change;
+  }
+  /**
+   * Deletes a document.
+   * @param docId The document ID.
+   * @param options - Optional deletion settings (e.g., skipTombstone for testing).
+   */
+  async deleteDoc(docId, options) {
+    const clientId = getClientId();
+    const { rev } = await this.getDoc(docId);
+    await createTombstoneIfSupported(this.store, docId, rev, clientId, options?.skipTombstone);
+    await this.store.deleteDoc(docId);
+    await this.onDocDeleted.emit(docId, options, clientId);
+  }
+  /**
+   * Removes the tombstone for a deleted document, allowing it to be recreated.
+   * @param docId The document ID.
+   * @returns True if tombstone was found and removed, false if no tombstone existed.
+   */
+  async undeleteDoc(docId) {
+    return removeTombstoneIfExists(this.store, docId);
+  }
+  // === Version Operations ===
+  /**
+   * Captures the current state of a document as a new version.
+   * @param docId The document ID.
+   * @param metadata Optional metadata for the version.
+   * @returns The ID of the created version.
+   */
+  async captureCurrentVersion(docId, metadata) {
+    assertVersionMetadata(metadata);
+    const { state: initialState, changes } = await getSnapshotAtRevision(this.store, docId);
+    let state = initialState;
+    state = applyChanges(state, changes);
+    const version = await createVersion(this.store, docId, state, changes, metadata);
+    if (!version) {
+      return null;
+    }
+    return version.id;
+  }
+}
+export {
+  OTServer
+};

package/dist/server/PatchesHistoryManager.d.ts

@@ -1,21 +1,26 @@
-import { ListVersionsOptions, VersionMetadata, EditableVersionMetadata, Change, ListChangesOptions } from '../types.js';
+import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
+import { ListVersionsOptions, VersionMetadata, EditableVersionMetadata, Change } from '../types.js';
 import { PatchesServer } from './PatchesServer.js';
+import { VersioningStoreBackend } from './types.js';
+import '../event-signal.js';
+import '../net/websocket/AuthorizationProvider.js';
+import '../json-patch/types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../event-signal.js';
-import './types.js';
-import '../compression/index.js';
-import '../algorithms/shared/lz.js';
+import '../net/protocol/types.js';
 
 /**
  * Helps retrieve historical information (versions, changes) for a document
- * using the new versioning model based on IDs and metadata.
+ * using the versioning model based on IDs and metadata.
+ *
+ * Works with any PatchesServer that implements captureCurrentVersion
+ * (both OTServer and LWWServer with VersioningStoreBackend).
  */
 declare class PatchesHistoryManager {
-    private readonly patches;
-    private readonly store;
-    constructor(patches: PatchesServer);
+    protected readonly patches: PatchesServer;
+    static api: ApiDefinition;
+    protected readonly store: VersioningStoreBackend;
+    constructor(patches: PatchesServer, store: VersioningStoreBackend);
     /**
      * Lists version metadata for the document, supporting various filters.
      * @param docId - The ID of the document.
@@ -55,13 +60,13 @@ declare class PatchesHistoryManager {
      */
     getChangesForVersion(docId: string, versionId: string): Promise<Change[]>;
     /**
-     * Lists committed server changes for the document, typically used for server-side processing
-     * or deep history analysis based on raw revisions.
-     * @param docId - The ID of the document.
-     * @param options - Options like start/end revision, limit.
-     * @returns The list of committed Change objects.
+     * Alias for getStateAtVersion for RPC API compatibility.
+     */
+    getVersionState(docId: string, versionId: string): Promise<any>;
+    /**
+     * Alias for getChangesForVersion for RPC API compatibility.
      */
-    listServerChanges(docId: string, options?: ListChangesOptions): Promise<Change[]>;
+    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
 }
 
 export { PatchesHistoryManager };

package/dist/server/PatchesHistoryManager.js

@@ -1,10 +1,17 @@
 import "../chunk-IZ2YBCUP.js";
-import { assertVersionMetadata } from "./PatchesServer.js";
+import { assertVersionMetadata } from "./utils.js";
 class PatchesHistoryManager {
-  constructor(patches) {
+  constructor(patches, store) {
     this.patches = patches;
-    this.store = patches.store;
+    this.store = store;
   }
+  static api = {
+    listVersions: "read",
+    createVersion: "write",
+    updateVersion: "write",
+    getVersionState: "read",
+    getVersionChanges: "read"
+  };
   store;
   /**
    * Lists version metadata for the document, supporting various filters.
@@ -63,21 +70,26 @@ class PatchesHistoryManager {
    */
   async getChangesForVersion(docId, versionId) {
     try {
-      return await this.store.loadVersionChanges(docId, versionId);
+      return await this.store.loadVersionChanges?.(docId, versionId) ?? [];
     } catch (error) {
       console.error(`Failed to load changes for version ${versionId} of doc ${docId}.`, error);
       throw new Error(`Could not load changes for version ${versionId}.`);
     }
   }
+  // ---------------------------------------------------------------------------
+  // Alias methods for RPC API compatibility
+  // ---------------------------------------------------------------------------
   /**
-   * Lists committed server changes for the document, typically used for server-side processing
-   * or deep history analysis based on raw revisions.
-   * @param docId - The ID of the document.
-   * @param options - Options like start/end revision, limit.
-   * @returns The list of committed Change objects.
+   * Alias for getStateAtVersion for RPC API compatibility.
+   */
+  async getVersionState(docId, versionId) {
+    return this.getStateAtVersion(docId, versionId);
+  }
+  /**
+   * Alias for getChangesForVersion for RPC API compatibility.
    */
-  async listServerChanges(docId, options = {}) {
-    return await this.store.listChanges(docId, options);
+  async getVersionChanges(docId, versionId) {
+    return this.getChangesForVersion(docId, versionId);
   }
 }
 export {