@dabble/patches 0.4.4 → 0.4.6

package/dist/server/PatchesBranchManager.js

@@ -1,151 +1,141 @@
-import { createId } from 'crypto-id';
-import { createChange } from '../data/change.js';
-import { createVersionMetadata } from '../data/version.js';
-/**
- * Helps manage branches for a document. A branch is a document that is branched from another document. Its first
- * version will be the point-in-time of the original document at the time of the branch. Branches allow for parallel
- * development of a document with the ability to merge changes back into the original document later.
- */
-export class PatchesBranchManager {
-    store;
-    patchesServer;
-    constructor(store, patchesServer) {
-        this.store = store;
-        this.patchesServer = patchesServer;
+import "../chunk-IZ2YBCUP.js";
+import { createId } from "crypto-id";
+import { createChange } from "../data/change.js";
+import { createVersionMetadata } from "../data/version.js";
+class PatchesBranchManager {
+  constructor(store, patchesServer) {
+    this.store = store;
+    this.patchesServer = patchesServer;
+  }
+  /**
+   * Lists all open branches for a document.
+   * @param docId - The ID of the document.
+   * @returns The branches.
+   */
+  async listBranches(docId) {
+    return await this.store.listBranches(docId);
+  }
+  /**
+   * 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 maybeBranch = await this.store.loadBranch(docId);
+    if (maybeBranch) {
+      throw new Error("Cannot create a branch from another branch.");
     }
-    /**
-     * Lists all open branches for a document.
-     * @param docId - The ID of the document.
-     * @returns The branches.
-     */
-    async listBranches(docId) {
-        return await this.store.listBranches(docId);
+    const stateAtRev = (await this.patchesServer.getStateAtRevision(docId, rev)).state;
+    const branchDocId = createId();
+    const now = Date.now();
+    const initialVersionMetadata = createVersionMetadata({
+      origin: "main",
+      // Branch doc versions are 'main' until merged
+      startDate: now,
+      endDate: now,
+      rev,
+      baseRev: rev,
+      name: metadata?.name,
+      groupId: branchDocId,
+      branchName: metadata?.name
+    });
+    await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
+    const branch = {
+      ...metadata,
+      id: branchDocId,
+      branchedFromId: docId,
+      branchedRev: rev,
+      created: now,
+      status: "open"
+    };
+    await this.store.createBranch(branch);
+    return branchDocId;
+  }
+  /**
+   * Updates a branch's metadata.
+   * @param branchId - The ID of the branch to update.
+   * @param metadata - The metadata to update.
+   */
+  async updateBranch(branchId, metadata) {
+    assertBranchMetadata(metadata);
+    await this.store.updateBranch(branchId, metadata);
+  }
+  /**
+   * 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.
+   */
+  async closeBranch(branchId, status = "closed") {
+    await this.store.updateBranch(branchId, { status });
+  }
+  /**
+   * Merges changes from a branch back into its source document.
+   * @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);
+    if (!branch) {
+      throw new Error(`Branch with ID ${branchId} not found.`);
     }
-    /**
-     * 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) {
-        // Prevent branching off a branch
-        const maybeBranch = await this.store.loadBranch(docId);
-        if (maybeBranch) {
-            throw new Error('Cannot create a branch from another branch.');
-        }
-        // 1. Get the state at the branch point
-        const stateAtRev = (await this.patchesServer.getStateAtRevision(docId, rev)).state;
-        const branchDocId = createId();
-        const now = Date.now();
-        // Create an initial version at the branch point rev (for snapshotting/large docs)
-        const initialVersionMetadata = createVersionMetadata({
-            origin: 'main', // Branch doc versions are 'main' until merged
-            startDate: now,
-            endDate: now,
-            rev,
-            baseRev: rev,
-            name: metadata?.name,
-            groupId: branchDocId,
-            branchName: metadata?.name,
-        });
-        await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
-        // 2. Create the branch metadata record
-        const branch = {
-            ...metadata,
-            id: branchDocId,
-            branchedFromId: docId,
-            branchedRev: rev,
-            created: now,
-            status: 'open',
-        };
-        await this.store.createBranch(branch);
-        return branchDocId;
+    if (branch.status !== "open") {
+      throw new Error(`Branch ${branchId} is not open (status: ${branch.status}). Cannot merge.`);
     }
-    /**
-     * Updates a branch's metadata.
-     * @param branchId - The ID of the branch to update.
-     * @param metadata - The metadata to update.
-     */
-    async updateBranch(branchId, metadata) {
-        assertBranchMetadata(metadata);
-        await this.store.updateBranch(branchId, metadata);
+    const sourceDocId = branch.branchedFromId;
+    const branchStartRevOnSource = branch.branchedRev;
+    const branchChanges = await this.store.listChanges(branchId, {});
+    if (branchChanges.length === 0) {
+      console.log(`Branch ${branchId} has no changes to merge.`);
+      await this.closeBranch(branchId, "merged");
+      return [];
     }
-    /**
-     * 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.
-     */
-    async closeBranch(branchId, status = 'closed') {
-        await this.store.updateBranch(branchId, { status });
+    const branchVersions = await this.store.listVersions(branchId, { origin: "main" });
+    let lastVersionId;
+    for (const v of branchVersions) {
+      const newVersionMetadata = createVersionMetadata({
+        ...v,
+        origin: "branch",
+        baseRev: branchStartRevOnSource,
+        groupId: branchId,
+        branchName: branch.name,
+        parentId: lastVersionId
+      });
+      const state = await this.store.loadVersionState(branchId, v.id);
+      const changes = await this.store.loadVersionChanges(branchId, v.id);
+      await this.store.createVersion(sourceDocId, newVersionMetadata, state, changes);
+      lastVersionId = newVersionMetadata.id;
     }
-    /**
-     * Merges changes from a branch back into its source document.
-     * @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) {
-        // 1. Load branch metadata
-        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.`);
-        }
-        const sourceDocId = branch.branchedFromId;
-        const branchStartRevOnSource = branch.branchedRev;
-        // 2. Get all committed server changes made on the branch document since it was created.
-        const branchChanges = await this.store.listChanges(branchId, {});
-        if (branchChanges.length === 0) {
-            console.log(`Branch ${branchId} has no changes to merge.`);
-            await this.closeBranch(branchId, 'merged');
-            return [];
-        }
-        // 3. Get all versions from the branch doc (skip offline versions)
-        const branchVersions = await this.store.listVersions(branchId, { origin: 'main' });
-        // 4. For each version, create a corresponding version in the main doc with updated fields
-        let lastVersionId;
-        for (const v of branchVersions) {
-            const newVersionMetadata = createVersionMetadata({
-                ...v,
-                origin: 'branch',
-                baseRev: branchStartRevOnSource,
-                groupId: branchId,
-                branchName: branch.name,
-                parentId: lastVersionId,
-            });
-            const state = await this.store.loadVersionState(branchId, v.id);
-            const changes = await this.store.loadVersionChanges(branchId, v.id);
-            await this.store.createVersion(sourceDocId, newVersionMetadata, state, changes);
-            lastVersionId = newVersionMetadata.id;
-        }
-        // 5. Flatten all branch changes into a single change for the main doc
-        const rev = branchStartRevOnSource + branchChanges.length;
-        const flattenedChange = createChange(branchStartRevOnSource, rev, branchChanges.flatMap(c => c.ops));
-        // 6. Commit the flattened change to the main doc
-        let committedMergeChanges = [];
-        try {
-            [, committedMergeChanges] = await this.patchesServer.commitChanges(sourceDocId, [flattenedChange]);
-        }
-        catch (error) {
-            console.error(`Failed to merge branch ${branchId} into ${sourceDocId}:`, error);
-            throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
-        }
-        // 7. Merge succeeded. Update the branch status.
-        await this.closeBranch(branchId, 'merged');
-        return committedMergeChanges;
+    const rev = branchStartRevOnSource + branchChanges.length;
+    const flattenedChange = createChange(
+      branchStartRevOnSource,
+      rev,
+      branchChanges.flatMap((c) => c.ops)
+    );
+    let committedMergeChanges = [];
+    try {
+      [, committedMergeChanges] = await this.patchesServer.commitChanges(sourceDocId, [flattenedChange]);
+    } 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 = new Set(['id', 'branchedFromId', 'branchedRev', 'created', 'status']);
-export function assertBranchMetadata(metadata) {
-    if (!metadata)
-        return;
-    for (const key in metadata) {
-        if (nonModifiableMetadataFields.has(key)) {
-            throw new Error(`Cannot modify branch field ${key}`);
-        }
+const nonModifiableMetadataFields = /* @__PURE__ */ new Set(["id", "branchedFromId", "branchedRev", "created", "status"]);
+function assertBranchMetadata(metadata) {
+  if (!metadata) return;
+  for (const key in metadata) {
+    if (nonModifiableMetadataFields.has(key)) {
+      throw new Error(`Cannot modify branch field ${key}`);
     }
+  }
 }
+export {
+  PatchesBranchManager,
+  assertBranchMetadata
+};

package/dist/server/PatchesHistoryManager.d.ts

@@ -1,10 +1,16 @@
-import type { Change, EditableVersionMetadata, ListChangesOptions, ListVersionsOptions, VersionMetadata } from '../types.js';
-import { type PatchesServer } from './PatchesServer.js';
+import { ListVersionsOptions, VersionMetadata, EditableVersionMetadata, Change, ListChangesOptions } from '../types.js';
+import { PatchesServer } from './PatchesServer.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+import '../event-signal.js';
+import './types.js';
+
 /**
  * Helps retrieve historical information (versions, changes) for a document
  * using the new versioning model based on IDs and metadata.
  */
-export declare class PatchesHistoryManager {
+declare class PatchesHistoryManager {
     private readonly patches;
     private readonly store;
     constructor(patches: PatchesServer);
@@ -55,3 +61,5 @@ export declare class PatchesHistoryManager {
      */
     listServerChanges(docId: string, options?: ListChangesOptions): Promise<Change[]>;
 }
+
+export { PatchesHistoryManager };

package/dist/server/PatchesHistoryManager.js

@@ -1,88 +1,85 @@
-import { assertVersionMetadata } from './PatchesServer.js';
-/**
- * Helps retrieve historical information (versions, changes) for a document
- * using the new versioning model based on IDs and metadata.
- */
-export class PatchesHistoryManager {
-    patches;
-    store;
-    constructor(patches) {
-        this.patches = patches;
-        this.store = patches.store;
+import "../chunk-IZ2YBCUP.js";
+import { assertVersionMetadata } from "./PatchesServer.js";
+class PatchesHistoryManager {
+  constructor(patches) {
+    this.patches = patches;
+    this.store = patches.store;
+  }
+  store;
+  /**
+   * Lists version metadata for the document, supporting various filters.
+   * @param docId - The ID of the document.
+   * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
+   * @returns A list of version metadata objects.
+   */
+  async listVersions(docId, options = {}) {
+    if (!options.orderBy) {
+      options.orderBy = "startDate";
     }
-    /**
-     * Lists version metadata for the document, supporting various filters.
-     * @param docId - The ID of the document.
-     * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
-     * @returns A list of version metadata objects.
-     */
-    async listVersions(docId, options = {}) {
-        if (!options.orderBy) {
-            options.orderBy = 'startDate';
-        }
-        return await this.store.listVersions(docId, options);
+    return await this.store.listVersions(docId, options);
+  }
+  /**
+   * Create a new named version snapshot of a document's current state.
+   * @param docId The document ID.
+   * @param name The name of the version.
+   * @returns The ID of the created version.
+   */
+  async createVersion(docId, metadata) {
+    assertVersionMetadata(metadata);
+    return await this.patches.captureCurrentVersion(docId, metadata);
+  }
+  /**
+   * Updates the name of a specific version.
+   * @param docId - The ID of the document.
+   * @param versionId - The ID of the version to update.
+   * @param name - The new name for the version.
+   */
+  async updateVersion(docId, versionId, metadata) {
+    assertVersionMetadata(metadata);
+    return this.store.updateVersion(docId, versionId, metadata);
+  }
+  /**
+   * Loads the full document state snapshot for a specific version by its ID.
+   * @param docId - The ID of the document.
+   * @param versionId - The unique ID of the version.
+   * @returns The document state at that version.
+   * @throws Error if the version ID is not found or state loading fails.
+   */
+  async getStateAtVersion(docId, versionId) {
+    try {
+      return await this.store.loadVersionState(docId, versionId);
+    } catch (error) {
+      console.error(`Failed to load state for version ${versionId} of doc ${docId}.`, error);
+      throw new Error(`Could not load state for version ${versionId}.`);
     }
-    /**
-     * Create a new named version snapshot of a document's current state.
-     * @param docId The document ID.
-     * @param name The name of the version.
-     * @returns The ID of the created version.
-     */
-    async createVersion(docId, metadata) {
-        assertVersionMetadata(metadata);
-        return await this.patches.captureCurrentVersion(docId, metadata);
-    }
-    /**
-     * Updates the name of a specific version.
-     * @param docId - The ID of the document.
-     * @param versionId - The ID of the version to update.
-     * @param name - The new name for the version.
-     */
-    async updateVersion(docId, versionId, metadata) {
-        assertVersionMetadata(metadata);
-        return this.store.updateVersion(docId, versionId, metadata);
-    }
-    /**
-     * Loads the full document state snapshot for a specific version by its ID.
-     * @param docId - The ID of the document.
-     * @param versionId - The unique ID of the version.
-     * @returns The document state at that version.
-     * @throws Error if the version ID is not found or state loading fails.
-     */
-    async getStateAtVersion(docId, versionId) {
-        try {
-            return await this.store.loadVersionState(docId, versionId);
-        }
-        catch (error) {
-            console.error(`Failed to load state for version ${versionId} of doc ${docId}.`, error);
-            throw new Error(`Could not load state for version ${versionId}.`);
-        }
-    }
-    /**
-     * Loads the list of original client changes that were included in a specific version.
-     * Useful for replaying/scrubbing through the operations within an offline or online session.
-     * @param docId - The ID of the document.
-     * @param versionId - The unique ID of the version.
-     * @returns An array of Change objects.
-     * @throws Error if the version ID is not found or change loading fails.
-     */
-    async getChangesForVersion(docId, versionId) {
-        try {
-            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}.`);
-        }
-    }
-    /**
-     * 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.
-     */
-    async listServerChanges(docId, options = {}) {
-        return await this.store.listChanges(docId, options);
+  }
+  /**
+   * Loads the list of original client changes that were included in a specific version.
+   * Useful for replaying/scrubbing through the operations within an offline or online session.
+   * @param docId - The ID of the document.
+   * @param versionId - The unique ID of the version.
+   * @returns An array of Change objects.
+   * @throws Error if the version ID is not found or change loading fails.
+   */
+  async getChangesForVersion(docId, versionId) {
+    try {
+      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}.`);
     }
+  }
+  /**
+   * 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.
+   */
+  async listServerChanges(docId, options = {}) {
+    return await this.store.listChanges(docId, options);
+  }
 }
+export {
+  PatchesHistoryManager
+};

package/dist/server/PatchesServer.d.ts

@@ -1,10 +1,14 @@
-import type { JSONPatch } from '../json-patch/JSONPatch.js';
-import type { Change, EditableVersionMetadata, PatchesState, PathProxy } from '../types.js';
-import type { PatchesStoreBackend } from './types.js';
+import { Signal } from '../event-signal.js';
+import { Change, PatchesState, ChangeInput, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { PatchesStoreBackend } from './types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
 /**
  * Configuration options for the PatchesServer.
  */
-export interface PatchesServerOptions {
+interface PatchesServerOptions {
     /**
      * The maximum time difference in minutes between consecutive changes
      * to be considered part of the same editing session for versioning.
@@ -17,13 +21,13 @@ export interface PatchesServerOptions {
  * coordinating batches of changes, managing versioning based on sessions (including offline),
  * and persisting data using a backend store.
  */
-export declare class PatchesServer {
+declare class PatchesServer {
     readonly store: PatchesStoreBackend;
     private readonly sessionTimeoutMillis;
     /** Notifies listeners whenever a batch of changes is *successfully* committed. */
-    readonly onChangesCommitted: import("../event-signal.js").Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
+    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
     /** Notifies listeners when a document is deleted. */
-    readonly onDocDeleted: import("../event-signal.js").Signal<(docId: string, originClientId?: string) => void>;
+    readonly onDocDeleted: Signal<(docId: string, originClientId?: string) => void>;
     constructor(store: PatchesStoreBackend, options?: PatchesServerOptions);
     /**
      * Get the state of a document at a specific revision (or the latest state if no revision is provided).
@@ -55,13 +59,13 @@ export declare class PatchesServer {
      *   - committedChanges: Changes that were already committed to the server after the client's base revision
      *   - transformedChanges: The client's changes after being transformed against concurrent changes
      */
-    commitChanges(docId: string, changes: Change[], originClientId?: string): Promise<[Change[], Change[]]>;
+    commitChanges(docId: string, changes: ChangeInput[], originClientId?: string): Promise<[Change[], Change[]]>;
     /**
      * Make a server-side change to a document.
      * @param mutator
      * @returns
      */
-    change<T = Record<string, any>>(docId: string, mutator: (patch: JSONPatch, root: PathProxy<T>) => void, metadata?: Record<string, any>): Promise<Change | null>;
+    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.
@@ -76,4 +80,6 @@ export declare class PatchesServer {
      */
     captureCurrentVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string>;
 }
-export declare function assertVersionMetadata(metadata?: EditableVersionMetadata): void;
+declare function assertVersionMetadata(metadata?: EditableVersionMetadata): void;
+
+export { PatchesServer, type PatchesServerOptions, assertVersionMetadata };