@dabble/patches 0.2.10 → 0.2.11

package/dist/persist/IndexedDBStore.js

@@ -0,0 +1,377 @@
+import { signal } from '../event-signal.js';
+import { transformPatch } from '../json-patch/transformPatch.js';
+import { applyChanges, deferred } from '../utils.js';
+const DB_VERSION = 1;
+const SNAPSHOT_INTERVAL = 200;
+/**
+ * Creates a new IndexedDB database with stores:
+ * - snapshots<{ docId: string; rev: number; state: any }> (primary key: docId)
+ * - committedChanges<Change & { docId: string; }> (primary key: [docId, rev])
+ * - pendingChanges<Change & { docId: string; }> (primary key: [docId, rev])
+ * - docs<{ docId: string; committedRev: number; deleted?: boolean }> (primary key: docId)
+ *
+ * Under the hood, this class will store snapshots of the document only for committed state. It will not update the
+ * committed state on *every* received committed change as this can cause issues with IndexedDB with many large updates.
+ * After every 200 committed changes, the class will save the current state to the snapshot store and delete the committed changes that went into it.
+ * A snapshot will not be created if there are pending changes based on revisions older than the 200th committed change until those pending changes are committed.
+ */
+export class IndexedDBStore {
+    constructor(dbName) {
+        this.db = null;
+        /** Subscribe to be notified after local state changes are saved to the database. */
+        this.onPendingChanges = signal();
+        this.dbName = dbName;
+        this.dbPromise = deferred();
+        if (this.dbName) {
+            this.initDB();
+        }
+    }
+    async initDB() {
+        if (!this.dbName)
+            return;
+        const request = indexedDB.open(this.dbName, DB_VERSION);
+        request.onerror = () => this.dbPromise.reject(request.error);
+        request.onsuccess = () => {
+            this.db = request.result;
+            this.dbPromise.resolve(this.db);
+        };
+        request.onupgradeneeded = event => {
+            const db = event.target.result;
+            // Create stores
+            if (!db.objectStoreNames.contains('snapshots')) {
+                db.createObjectStore('snapshots', { keyPath: 'docId' });
+            }
+            if (!db.objectStoreNames.contains('committedChanges')) {
+                db.createObjectStore('committedChanges', { keyPath: ['docId', 'rev'] });
+            }
+            if (!db.objectStoreNames.contains('pendingChanges')) {
+                db.createObjectStore('pendingChanges', { keyPath: ['docId', 'rev'] });
+            }
+            if (!db.objectStoreNames.contains('docs')) {
+                db.createObjectStore('docs', { keyPath: 'docId' });
+            }
+        };
+    }
+    getDB() {
+        return this.dbPromise.promise;
+    }
+    /**
+     * Set the name of the database, loads a new database connection.
+     * @param dbName - The new name of the database.
+     */
+    setName(dbName) {
+        this.dbName = dbName;
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+            this.dbPromise = deferred();
+        }
+        this.initDB();
+    }
+    /**
+     * Closes the database connection. After calling this method, the store
+     * will no longer be usable. A new instance must be created to reopen
+     * the database.
+     */
+    async close() {
+        await this.dbPromise.promise;
+        if (this.db) {
+            this.db.close();
+            this.db = null;
+            this.dbPromise = deferred();
+            this.dbPromise.resolve(null);
+        }
+    }
+    async deleteDB() {
+        if (!this.dbName)
+            return;
+        await this.close();
+        await new Promise((resolve, reject) => {
+            const request = indexedDB.deleteDatabase(this.dbName);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+            request.onblocked = () => reject(request.error);
+        });
+    }
+    async transaction(storeNames, mode) {
+        const db = await this.getDB();
+        const tx = new IDBTransactionWrapper(db.transaction(storeNames, mode));
+        const stores = storeNames.map(name => tx.getStore(name));
+        return [tx, ...stores];
+    }
+    // ─── Snapshots + Reconstruction ────────────────────────────────────────────
+    /**
+     * Rebuilds a document snapshot + pending queue *without* loading
+     * the full PatchesDoc into memory.
+     *
+     * 1. load the last snapshot (state + rev)
+     * 2. load committedChanges[rev > snapshot.rev]
+     * 3. load pendingChanges
+     * 4. apply committed changes, rebase pending
+     * 5. return { state, rev, changes: pending }
+     */
+    async getDoc(docId) {
+        const [tx, docsStore, snapshots, committedChanges, pendingChanges] = await this.transaction(['docs', 'snapshots', 'committedChanges', 'pendingChanges'], 'readonly');
+        const docMeta = await docsStore.get(docId);
+        if (docMeta?.deleted) {
+            await tx.complete();
+            return undefined;
+        }
+        const snapshot = await snapshots.get(docId);
+        const committed = await committedChanges.getAll([docId, snapshot?.rev ?? 0], [docId, Infinity]);
+        const pending = await pendingChanges.getAll([docId, 0], [docId, Infinity]);
+        if (!snapshot && !committed.length && !pending.length)
+            return undefined;
+        // Apply any committed changes to the snapshot state
+        const state = applyChanges(snapshot?.state, committed);
+        // Rebase pending changes if there are any committed changes received since their baseRev
+        const lastCommitted = committed[committed.length - 1];
+        const baseRev = pending[0]?.baseRev;
+        if (lastCommitted && baseRev && baseRev < lastCommitted.rev) {
+            const patch = committed
+                .filter(change => change.rev > baseRev)
+                .map(change => change.ops)
+                .flat();
+            const offset = lastCommitted.rev - baseRev;
+            pending.forEach(change => {
+                change.rev += offset;
+                change.ops = transformPatch(state, patch, change.ops);
+            });
+        }
+        await tx.complete();
+        return {
+            state,
+            rev: committed[committed.length - 1]?.rev ?? snapshot?.rev ?? 0,
+            changes: pending,
+        };
+    }
+    /**
+     * Completely remove all data for this docId and mark it as deleted (tombstone).
+     */
+    async deleteDoc(docId) {
+        const [tx, snapshots, committedChanges, pendingChanges, docsStore] = await this.transaction(['snapshots', 'committedChanges', 'pendingChanges', 'docs'], 'readwrite');
+        const docMeta = (await docsStore.get(docId)) ?? { docId, committedRev: 0 };
+        await docsStore.put({ ...docMeta, deleted: true });
+        await Promise.all([
+            snapshots.delete(docId),
+            committedChanges.delete([docId, 0], [docId, Infinity]),
+            pendingChanges.delete([docId, 0], [docId, Infinity]),
+        ]);
+        await tx.complete();
+    }
+    async confirmDeleteDoc(docId) {
+        const [tx, docsStore] = await this.transaction(['docs'], 'readwrite');
+        await docsStore.delete(docId);
+        await tx.complete();
+    }
+    // ─── Pending Changes ────────────────────────────────────────────────────────
+    /**
+     * Append an array of local changes to the pending queue.
+     * Called *before* you attempt to send them to the server.
+     */
+    async savePendingChanges(docId, changes) {
+        const [tx, pendingChanges, docsStore] = await this.transaction(['pendingChanges', 'docs'], 'readwrite');
+        let docMeta = await docsStore.get(docId);
+        if (!docMeta) {
+            docMeta = { docId, committedRev: 0 };
+            await docsStore.put(docMeta);
+        }
+        else if (docMeta.deleted) {
+            delete docMeta.deleted;
+            await docsStore.put(docMeta);
+            console.warn(`Revived document ${docId} by saving pending changes.`);
+        }
+        await Promise.all(changes.map(change => pendingChanges.put({ ...change, docId })));
+        this.onPendingChanges.emit(docId, changes);
+        await tx.complete();
+    }
+    /** Read back all pending changes for this docId (in order). */
+    async getPendingChanges(docId) {
+        const [tx, pendingChanges] = await this.transaction(['pendingChanges'], 'readonly');
+        const result = await pendingChanges.getAll([docId, 0], [docId, Infinity]);
+        await tx.complete();
+        return result;
+    }
+    // ─── Committed Changes ─────────────────────────────────────────────────────
+    /**
+     * Store server‐confirmed changes.  Will:
+     * - persist them in the committedChanges store
+     * - remove any pending changes whose rev falls within `sentPendingRange`
+     * - optionally compact a new snapshot after N changes (hidden internally)
+     * @param docId - The ID of the document to save the changes for
+     * @param changes - The changes to save
+     * @param sentPendingRange - The range of pending changes to remove, *must* be provided after receiving the changes
+     * from the server in response to a patchesDoc request.
+     */
+    async saveCommittedChanges(docId, changes, sentPendingRange) {
+        const [tx, committedChanges, pendingChanges, snapshots, docsStore] = await this.transaction(['committedChanges', 'pendingChanges', 'snapshots', 'docs'], 'readwrite');
+        // Save committed changes
+        await Promise.all(changes.map(change => committedChanges.put({ ...change, docId })));
+        // Remove pending changes if range provided
+        if (sentPendingRange) {
+            await pendingChanges.delete([docId, sentPendingRange[0]], [docId, sentPendingRange[1]]);
+        }
+        // Check if we should create a snapshot
+        const count = await committedChanges.count([docId, 0], [docId, Infinity]);
+        if (count >= SNAPSHOT_INTERVAL) {
+            // Update the snapshot. A snapshot will not be updated if there are pending changes based on revisions older than
+            // the latest committed change until those pending changes are committed.
+            const [snapshot, committed, firstPending] = await Promise.all([
+                snapshots.get(docId),
+                committedChanges.getAll([docId, 0], [docId, Infinity], SNAPSHOT_INTERVAL),
+                pendingChanges.getFirstFromCursor([docId, 0], [docId, Infinity]),
+            ]);
+            // Update the snapshot
+            const lastRev = committed[committed.length - 1]?.rev;
+            if (!firstPending?.baseRev || firstPending?.baseRev >= lastRev) {
+                const state = applyChanges(snapshot?.state, committed);
+                await Promise.all([
+                    snapshots.put({
+                        docId,
+                        rev: lastRev,
+                        state,
+                    }),
+                    committedChanges.delete([docId, 0], [docId, lastRev]),
+                ]);
+            }
+        }
+        // Update committedRev in the docs store if changes were saved
+        const lastCommittedRev = changes.at(-1)?.rev;
+        if (lastCommittedRev !== undefined) {
+            const docMeta = (await docsStore.get(docId)) ?? { docId, committedRev: 0 };
+            if (lastCommittedRev > docMeta.committedRev) {
+                await docsStore.put({ ...docMeta, committedRev: lastCommittedRev, deleted: undefined });
+            }
+        }
+        await tx.complete();
+    }
+    // --- New method for OfflineStore interface ---
+    async listDocs(includeDeleted = false) {
+        const [tx, docsStore] = await this.transaction(['docs'], 'readonly');
+        const allDocs = await docsStore.getAll();
+        await tx.complete();
+        return includeDeleted ? allDocs : allDocs.filter(doc => !doc.deleted);
+    }
+    // ─── Metadata / Tracking ───────────────────────────────────────────
+    async trackDocs(docIds) {
+        const [tx, docsStore] = await this.transaction(['docs'], 'readwrite');
+        await Promise.all(docIds.map(async (docId) => {
+            const existing = await docsStore.get(docId);
+            if (existing) {
+                // If exists but deleted, undelete it
+                if (existing.deleted) {
+                    await docsStore.put({ ...existing, deleted: undefined });
+                }
+                // Otherwise, it's already tracked and not deleted, do nothing
+            }
+            else {
+                // If doesn't exist, add it
+                await docsStore.put({ docId, committedRev: 0 });
+            }
+        }));
+        await tx.complete();
+    }
+    async untrackDocs(docIds) {
+        const [tx, docsStore, snapshots, committedChanges, pendingChanges] = await this.transaction(['docs', 'snapshots', 'committedChanges', 'pendingChanges'], 'readwrite');
+        await Promise.all(docIds.map(docId => {
+            return Promise.all([
+                docsStore.delete(docId),
+                snapshots.delete(docId),
+                committedChanges.delete([docId, 0], [docId, Infinity]),
+                pendingChanges.delete([docId, 0], [docId, Infinity]),
+            ]);
+        }));
+        await tx.complete();
+    }
+    // ─── Revision Tracking ─────────────────────────────────────────────────────
+    /**
+     * Tell me the last committed revision you have *and* the highest
+     * rev of any change.  Use these to drive:
+     *   - fetch changes:   api.getChangesSince(docId, committedRev)
+     *   - build new patch: newChange.rev = pendingRev; baseRev = committedRev
+     */
+    async getLastRevs(docId) {
+        const [tx, committedChanges, pendingChanges] = await this.transaction(['committedChanges', 'pendingChanges'], 'readonly');
+        const [lastCommitted, lastPending] = await Promise.all([
+            committedChanges.getLastFromCursor([docId, 0], [docId, Infinity]),
+            pendingChanges.getLastFromCursor([docId, 0], [docId, Infinity]),
+        ]);
+        await tx.complete();
+        return [lastCommitted?.rev ?? 0, lastPending?.rev ?? lastCommitted?.rev ?? 0];
+    }
+}
+class IDBTransactionWrapper {
+    constructor(tx) {
+        this.tx = tx;
+        this.promise = new Promise((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    getStore(name) {
+        return new IDBStoreWrapper(this.tx.objectStore(name));
+    }
+    async complete() {
+        return this.promise;
+    }
+}
+class IDBStoreWrapper {
+    constructor(store) {
+        this.store = store;
+    }
+    createRange(lower, upper) {
+        if (lower === undefined && upper === undefined)
+            return undefined;
+        return IDBKeyRange.bound(lower, upper);
+    }
+    async getAll(lower, upper, count) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.getAll(this.createRange(lower, upper), count);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async get(key) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.get(key);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async put(value) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.put(value);
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async delete(keyOrLower, upper) {
+        return new Promise((resolve, reject) => {
+            const key = upper === undefined ? keyOrLower : this.createRange(keyOrLower, upper);
+            const request = this.store.delete(key);
+            request.onsuccess = () => resolve();
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async count(lower, upper) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.count(this.createRange(lower, upper));
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async getFirstFromCursor(lower, upper) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.openCursor(this.createRange(lower, upper));
+            request.onsuccess = () => resolve(request.result?.value);
+            request.onerror = () => reject(request.error);
+        });
+    }
+    async getLastFromCursor(lower, upper) {
+        return new Promise((resolve, reject) => {
+            const request = this.store.openCursor(this.createRange(lower, upper), 'prev');
+            request.onsuccess = () => resolve(request.result?.value);
+            request.onerror = () => reject(request.error);
+        });
+    }
+}

package/dist/persist/PatchesStore.d.ts

@@ -0,0 +1,38 @@
+import type { Change, PatchesSnapshot } from '../types.js';
+/** Represents metadata for a document tracked by the store. */
+export interface TrackedDoc {
+    docId: string;
+    /** The last revision number confirmed by the server. */
+    committedRev: number;
+    /** Optional flag indicating the document has been locally deleted. */
+    deleted?: true;
+}
+/**
+ * Pluggable persistence layer contract used by Patches + PatchesSync.
+ * It is *not* strictly offline; an in‑memory implementation fulfils the same contract.
+ */
+export interface PatchesStore {
+    /**
+     * Ensure these docs exist in the local index (or undelete them).
+     * Called by `trackDocs` before syncing begins.
+     */
+    trackDocs(docIds: string[]): Promise<void>;
+    /**
+     * Drop all local data for these docs without creating a delete tombstone.
+     * Called by `untrackDocs` when the user no longer cares about a doc locally.
+     */
+    untrackDocs(docIds: string[]): Promise<void>;
+    /** List currently tracked docs (optionally including deleted). */
+    listDocs(includeDeleted?: boolean): Promise<TrackedDoc[]>;
+    getDoc(docId: string): Promise<PatchesSnapshot | undefined>;
+    getPendingChanges(docId: string): Promise<Change[]>;
+    getLastRevs(docId: string): Promise<[committedRev: number, pendingRev: number]>;
+    savePendingChanges(docId: string, changes: Change[]): Promise<void>;
+    saveCommittedChanges(docId: string, changes: Change[], sentPendingRange?: [number, number]): Promise<void>;
+    /** Permanently delete document (writes tombstone so server delete happens later). */
+    deleteDoc(docId: string): Promise<void>;
+    /** Confirm that a doc has been deleted (e.g., after a tombstone has been written). */
+    confirmDeleteDoc(docId: string): Promise<void>;
+    /** Close the store */
+    close(): Promise<void>;
+}

package/dist/persist/PatchesStore.js

@@ -0,0 +1 @@
+export {};

package/dist/persist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IndexedDBStore.js';
+export * from './InMemoryStore.js';
+export * from './PatchesStore.js';

package/dist/persist/index.js

@@ -0,0 +1,3 @@
+export * from './IndexedDBStore.js';
+export * from './InMemoryStore.js';
+export * from './PatchesStore.js';

package/dist/server/PatchesBranchManager.d.ts

@@ -0,0 +1,40 @@
+import type { Branch, BranchingStoreBackend, BranchStatus, Change } from '../types.js';
+import type { PatchesServer } from './PatchesServer.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 declare class PatchesBranchManager {
+    private readonly store;
+    private readonly patchesServer;
+    constructor(store: BranchingStoreBackend, patchesServer: PatchesServer);
+    /**
+     * Lists all open branches for a document.
+     * @param docId - The ID of the document.
+     * @returns The branches.
+     */
+    listBranches(docId: string): Promise<Branch[]>;
+    /**
+     * 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.
+     */
+    createBranch(docId: string, rev: number, branchName?: string, metadata?: Record<string, any>): Promise<string>;
+    /**
+     * 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.
+     */
+    closeBranch(branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+    /**
+     * 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.
+     */
+    mergeBranch(branchId: string): Promise<Change[]>;
+}

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[]>;
+}