@dabble/patches 0.2.10 → 0.2.12

package/dist/server/PatchesBranchManager.js

@@ -0,0 +1,138 @@
+import { createId } from 'crypto-id';
+/**
+ * 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 {
+    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, branchName, 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 = {
+            id: createId(),
+            origin: 'main', // Branch doc versions are 'main' until merged
+            startDate: now,
+            endDate: now,
+            rev,
+            baseRev: rev,
+            name: branchName,
+            groupId: branchDocId,
+            branchName,
+        };
+        await this.store.createVersion(branchDocId, initialVersionMetadata, stateAtRev, []);
+        // 2. Create the branch metadata record
+        const branch = {
+            id: branchDocId,
+            branchedFromId: docId,
+            branchedRev: rev,
+            created: now,
+            name: branchName,
+            status: 'open',
+            ...(metadata && { metadata }),
+        };
+        await this.store.createBranch(branch);
+        return branchDocId;
+    }
+    /**
+     * 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) {
+        // 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 newVersionId = createId();
+            const newVersionMetadata = {
+                ...v,
+                id: newVersionId,
+                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 = newVersionId;
+        }
+        // 5. Flatten all branch changes into a single change for the main doc
+        const now = Date.now();
+        const flattenedChange = {
+            id: createId(12),
+            ops: branchChanges.flatMap(c => c.ops),
+            rev: branchStartRevOnSource + branchChanges.length,
+            baseRev: branchStartRevOnSource,
+            created: now,
+        };
+        // 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;
+    }
+}

package/dist/server/PatchesHistoryManager.d.ts

@@ -0,0 +1,43 @@
+import type { Change, ListVersionsOptions, PatchesStoreBackend, VersionMetadata } from '../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 {
+    private readonly docId;
+    private readonly store;
+    constructor(docId: string, store: PatchesStoreBackend);
+    /**
+     * Lists version metadata for the document, supporting various filters.
+     * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
+     * @returns A list of version metadata objects.
+     */
+    listVersions(options?: ListVersionsOptions): Promise<VersionMetadata[]>;
+    /**
+     * Loads the full document state snapshot for a specific version by its ID.
+     * @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.
+     */
+    getStateAtVersion(versionId: string): Promise<any>;
+    /**
+     * 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 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.
+     */
+    getChangesForVersion(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 options - Options like start/end revision, limit.
+     * @returns The list of committed Change objects.
+     */
+    listServerChanges(options?: {
+        limit?: number;
+        startAfterRev?: number;
+        endBeforeRev?: number;
+        reverse?: boolean;
+    }): Promise<Change[]>;
+}

package/dist/server/PatchesHistoryManager.js

@@ -0,0 +1,59 @@
+/**
+ * Helps retrieve historical information (versions, changes) for a document
+ * using the new versioning model based on IDs and metadata.
+ */
+export class PatchesHistoryManager {
+    constructor(docId, store) {
+        this.docId = docId;
+        this.store = store;
+    }
+    /**
+     * Lists version metadata for the document, supporting various filters.
+     * @param options Filtering and sorting options (e.g., limit, reverse, origin, groupId, date range).
+     * @returns A list of version metadata objects.
+     */
+    async listVersions(options = {}) {
+        return await this.store.listVersions(this.docId, options);
+    }
+    /**
+     * Loads the full document state snapshot for a specific version by its ID.
+     * @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(versionId) {
+        try {
+            return await this.store.loadVersionState(this.docId, versionId);
+        }
+        catch (error) {
+            console.error(`Failed to load state for version ${versionId} of doc ${this.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 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(versionId) {
+        try {
+            return await this.store.loadVersionChanges(this.docId, versionId);
+        }
+        catch (error) {
+            console.error(`Failed to load changes for version ${versionId} of doc ${this.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 options - Options like start/end revision, limit.
+     * @returns The list of committed Change objects.
+     */
+    async listServerChanges(options = {}) {
+        // Added return type
+        return await this.store.listChanges(this.docId, options);
+    }
+}

package/dist/server/PatchesServer.d.ts

@@ -0,0 +1,129 @@
+import type { Change, ListVersionsOptions, PatchesSnapshot, PatchesState, PatchesStoreBackend, VersionMetadata } from '../types.js';
+/**
+ * Configuration options for the PatchesServer.
+ */
+export interface PatchesServerOptions {
+    /**
+     * 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;
+}
+/**
+ * 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.
+ */
+export declare class PatchesServer {
+    private readonly store;
+    private readonly sessionTimeoutMillis;
+    constructor(store: PatchesStoreBackend, options?: PatchesServerOptions);
+    /**
+     * Subscribes the connected client to one or more documents.
+     * @param ids Document ID(s) to subscribe to.
+     * @returns A list of document IDs the client is now successfully subscribed to.
+     */
+    subscribe(clientId: string, ids: string | string[]): Promise<string[]>;
+    /**
+     * Unsubscribes the connected client from one or more documents.
+     * @param ids Document ID(s) to unsubscribe from.
+     */
+    unsubscribe(clientId: string, ids: string | string[]): Promise<string[]>;
+    /**
+     * Get the latest version of a document and changes since the last version.
+     * @param docId - The ID of the document.
+     * @returns The latest version of the document and changes since the last version.
+     */
+    getDoc(docId: string, atRev?: number): Promise<PatchesSnapshot>;
+    /**
+     * 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.
+     * @param docId - The ID of the document.
+     * @param changes - The changes to commit.
+     * @returns A tuple of [committedChanges, transformedChanges] where:
+     *   - 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[]): Promise<[Change[], Change[]]>;
+    /**
+     * Handles offline/large batch versioning logic for multi-batch uploads.
+     * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
+     * @param docId Document ID
+     * @param changes The incoming changes (all with the same batchId)
+     * @param baseRev The base revision for the batch
+     * @param batchId The batch identifier
+     * @returns The collapsed changes for transformation
+     */
+    private handleOfflineBatches;
+    /**
+     * Deletes a document.
+     * @param docId The document ID.
+     */
+    deleteDoc(docId: string): Promise<void>;
+    /**
+     * 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.
+     */
+    createVersion(docId: string, name: string): Promise<string>;
+    /**
+     * Lists version metadata for a document, supporting various filters.
+     * @param docId The document ID.
+     * @param options Filtering and sorting options.
+     * @returns A list of version metadata objects.
+     */
+    listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
+    /**
+     * Get the state snapshot for a specific version ID.
+     * @param docId The document ID.
+     * @param versionId The ID of the version.
+     * @returns The state snapshot for the specified version.
+     */
+    getVersionState(docId: string, versionId: string): Promise<PatchesState>;
+    /**
+     * Get the original Change objects associated with a specific version ID.
+     * @param docId The document ID.
+     * @param versionId The ID of the version.
+     * @returns The original Change objects for the specified version.
+     */
+    getVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    /**
+     * Update the name of a specific version.
+     * @param docId The document ID.
+     * @param versionId The ID of the version.
+     * @param name The new name for the version.
+     */
+    updateVersion(docId: string, versionId: string, name: string): Promise<void>;
+    /**
+     * Retrieves the document state of the version before the given revision and changes after up to that revision or all
+     * changes since that version.
+     * @param docId The document ID.
+     * @param rev The revision number. If not provided, the latest state, its revision, and all changes since are returned.
+     * @returns The document state at the last version before the revision, its revision number, and all changes up to the specified revision (or all changes if no revision is provided).
+     */
+    _getSnapshotAtRevision(docId: string, rev?: number): Promise<PatchesSnapshot>;
+    /**
+     * Gets the state at a specific revision.
+     * @param docId The document ID.
+     * @param rev The revision number. If not provided, the latest state and its revision is returned.
+     * @returns The state at the specified revision *and* its revision number.
+     */
+    _getStateAtRevision(docId: string, rev?: number): Promise<PatchesState>;
+    /**
+     * Creates a new version snapshot of a document's current state.
+     * @param docId The document ID.
+     * @param state The document state at the time of the version.
+     * @param changes The changes since the last version that created the state (the last change's rev is the state's rev and will be the version's rev).
+     * @param name The name of the version.
+     * @returns The ID of the created version.
+     */
+    _createVersion(docId: string, state: any, changes: Change[], name?: string): Promise<VersionMetadata | undefined>;
+}