@dabble/patches 0.1.1

package/dist/server/PatchServer.d.ts

@@ -0,0 +1,129 @@
+import type { Change, ListVersionsOptions, PatchSnapshot, PatchState, PatchStoreBackend, VersionMetadata } from '../types.js';
+/**
+ * Configuration options for the PatchServer.
+ */
+export interface PatchServerOptions {
+    /**
+     * 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 PatchServer {
+    private readonly store;
+    private readonly sessionTimeoutMillis;
+    constructor(store: PatchStoreBackend, options?: PatchServerOptions);
+    /**
+     * 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<PatchSnapshot>;
+    /**
+     * 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<PatchState>;
+    /**
+     * 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<PatchSnapshot>;
+    /**
+     * 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<PatchState>;
+    /**
+     * 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>;
+}

package/dist/server/PatchServer.js

@@ -0,0 +1,358 @@
+import { createId } from 'crypto-id';
+import { applyPatch } from '../json-patch/applyPatch.js';
+import { transformPatch } from '../json-patch/transformPatch.js';
+import { applyChanges } from '../utils.js';
+/**
+ * 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 class PatchServer {
+    constructor(store, options = {}) {
+        this.store = store;
+        this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1000;
+    }
+    // --- Patches API Methods ---
+    // === Subscription Operations ===
+    /**
+     * 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, ids) {
+        return this.store.addSubscription(clientId, Array.isArray(ids) ? ids : [ids]);
+    }
+    /**
+     * Unsubscribes the connected client from one or more documents.
+     * @param ids Document ID(s) to unsubscribe from.
+     */
+    unsubscribe(clientId, ids) {
+        return this.store.removeSubscription(clientId, Array.isArray(ids) ? ids : [ids]);
+    }
+    // === Document Operations ===
+    /**
+     * 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.
+     */
+    async getDoc(docId, atRev) {
+        return this._getSnapshotAtRevision(docId, atRev);
+    }
+    /**
+     * 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.
+     * @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
+     */
+    async commitChanges(docId, changes) {
+        if (changes.length === 0) {
+            return [[], []];
+        }
+        // Assume all changes share the same baseRev. Client ensures this.
+        const batchId = changes[0].batchId;
+        const baseRev = changes[0].baseRev;
+        if (baseRev === undefined) {
+            throw new Error(`Client changes must include baseRev for doc ${docId}.`);
+        }
+        // Add check for inconsistent baseRev within the batch if needed
+        if (changes.some(c => c.baseRev !== baseRev)) {
+            throw new Error(`Client changes must have consistent baseRev for doc ${docId}.`);
+        }
+        // 1. Load server state details (assuming store methods exist)
+        let { state: currentState, rev: currentRev, changes: currentChanges } = await this._getSnapshotAtRevision(docId);
+        currentState = applyChanges(currentState, currentChanges);
+        currentRev = currentChanges.at(-1)?.rev ?? currentRev;
+        // Basic validation
+        if (baseRev > currentRev) {
+            throw new Error(`Client baseRev (${baseRev}) is ahead of server revision (${currentRev}) for doc ${docId}. Client needs to reload the document.`);
+        }
+        const partOfInitialBatch = batchId && changes[0].rev > 1;
+        if (baseRev === 0 && currentRev > 0 && !partOfInitialBatch) {
+            throw new Error(`Client baseRev is 0 but server has already been created for doc ${docId}. Client needs to load the existing document.`);
+        }
+        // Ensure all new changes' `created` field is in the past, that each `rev` is correct, and that `baseRev` is set
+        let rev = baseRev + 1;
+        changes.forEach(c => {
+            c.created = Math.min(c.created, Date.now());
+            c.rev = rev++;
+            c.baseRev = baseRev;
+        });
+        // 2. Check if we need to create a new version - if the last change was created more than a session ago
+        const lastChange = currentChanges[currentChanges.length - 1];
+        if (lastChange && lastChange.created < Date.now() - this.sessionTimeoutMillis) {
+            await this._createVersion(docId, currentState, currentChanges);
+        }
+        // 3. Load committed changes *after* the client's baseRev for transformation and idempotency checks
+        let committedChanges = await this.store.listChanges(docId, {
+            startAfter: baseRev,
+            withoutBatchId: batchId,
+        });
+        const commitedIds = new Set(committedChanges.map(c => c.id));
+        changes = changes.filter(c => !commitedIds.has(c.id));
+        // If all incoming changes were already committed, return the committed changes found
+        if (changes.length === 0) {
+            return [committedChanges, []];
+        }
+        // 4. Handle offline-session versioning:
+        // - batchId present (multi-batch uploads)
+        // - or the first change is older than the session timeout (single-batch offline)
+        const isOfflineTimestamp = changes[0].created < Date.now() - this.sessionTimeoutMillis;
+        if (isOfflineTimestamp || batchId) {
+            changes = await this.handleOfflineBatches(docId, changes, baseRev, batchId);
+        }
+        // 5. Transform the *entire batch* of incoming (and potentially collapsed offline) changes
+        //    against committed changes that happened *after* the client's baseRev.
+        //    The state used for transformation should be the server state *at the client's baseRev*.
+        let stateAtBaseRev = (await this._getStateAtRevision(docId, baseRev)).state;
+        const committedOps = committedChanges.flatMap(c => c.ops);
+        // Apply transformation based on state at baseRev
+        const transformedChanges = changes
+            .map(change => {
+            // Transform the incoming change's ops against the ops committed since baseRev
+            const transformedOps = transformPatch(stateAtBaseRev, committedOps, change.ops);
+            if (transformedOps.length === 0) {
+                return null; // Change is obsolete after transformation
+            }
+            try {
+                stateAtBaseRev = applyPatch(stateAtBaseRev, change.ops, { strict: true });
+            }
+            catch (error) {
+                console.error(`Error applying change ${change.id} to state:`, error);
+                return null;
+            }
+            // Return a new change object with transformed ops and original metadata
+            return { ...change, ops: transformedOps };
+        })
+            .filter(Boolean);
+        // Persist the newly transformed changes
+        if (transformedChanges.length > 0) {
+            await this.store.saveChanges(docId, transformedChanges);
+        }
+        // Return committed changes and newly transformed changes separately
+        return [committedChanges, transformedChanges];
+    }
+    /**
+     * 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
+     */
+    async handleOfflineBatches(docId, changes, baseRev, batchId) {
+        // Use batchId as groupId for multi-batch uploads; default offline sessions have no groupId
+        const groupId = batchId ?? createId();
+        // Find the last version for this groupId (if any)
+        const [lastVersion] = await this.store.listVersions(docId, {
+            groupId,
+            reverse: true,
+            limit: 1,
+        });
+        let offlineBaseState;
+        let parentId;
+        if (lastVersion) {
+            // Continue from the last version's state
+            // loadVersionState returns a PatchState ({state, rev}); extract the .state
+            const vs = await this.store.loadVersionState(docId, lastVersion.id);
+            offlineBaseState = vs.state ?? vs;
+            parentId = lastVersion.id;
+        }
+        else {
+            // First batch for this batchId: start at baseRev
+            offlineBaseState = (await this._getStateAtRevision(docId, baseRev)).state;
+        }
+        let sessionStartIndex = 0;
+        for (let i = 1; i <= changes.length; i++) {
+            const isLastChange = i === changes.length;
+            const timeDiff = isLastChange ? Infinity : changes[i].created - changes[i - 1].created;
+            // Session ends if timeout exceeded OR it's the last change in the batch
+            if (timeDiff > this.sessionTimeoutMillis || isLastChange) {
+                const sessionChanges = changes.slice(sessionStartIndex, i);
+                if (sessionChanges.length > 0) {
+                    // Check if this is a continuation of the previous session (merge/extend)
+                    const isContinuation = !!lastVersion && sessionChanges[0].created - lastVersion.endDate <= this.sessionTimeoutMillis;
+                    if (isContinuation) {
+                        // Merge/extend the existing version
+                        const mergedState = applyChanges(offlineBaseState, sessionChanges);
+                        await this.store.saveChanges(docId, sessionChanges);
+                        await this.store.updateVersion(docId, lastVersion.id, {}); // metadata already updated above
+                        offlineBaseState = mergedState;
+                        parentId = lastVersion.parentId;
+                    }
+                    else {
+                        // Create a new version for this session
+                        offlineBaseState = applyChanges(offlineBaseState, sessionChanges);
+                        const versionId = createId();
+                        const sessionMetadata = {
+                            id: versionId,
+                            parentId,
+                            groupId,
+                            origin: 'offline',
+                            startDate: sessionChanges[0].created,
+                            endDate: sessionChanges[sessionChanges.length - 1].created,
+                            rev: sessionChanges[sessionChanges.length - 1].rev,
+                            baseRev,
+                        };
+                        await this.store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
+                        parentId = versionId;
+                    }
+                    sessionStartIndex = i;
+                }
+            }
+        }
+        // Collapse all changes into one for transformation
+        return [
+            changes.reduce((firstChange, nextChange) => {
+                firstChange.ops = [...firstChange.ops, ...nextChange.ops];
+                return firstChange;
+            }),
+        ];
+    }
+    /**
+     * Deletes a document.
+     * @param docId The document ID.
+     */
+    deleteDoc(docId) {
+        return this.store.deleteDoc(docId);
+    }
+    // === Version Operations ===
+    /**
+     * 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, name) {
+        let { state, changes } = await this._getSnapshotAtRevision(docId);
+        state = applyChanges(state, changes);
+        const version = await this._createVersion(docId, state, changes, name);
+        if (!version) {
+            throw new Error(`No changes to create a version for doc ${docId}.`);
+        }
+        return version.id;
+    }
+    /**
+     * 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, options) {
+        if (!options.orderBy) {
+            options.orderBy = 'startDate';
+        }
+        return this.store.listVersions(docId, options);
+    }
+    /**
+     * 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, versionId) {
+        return this.store.loadVersionState(docId, versionId);
+    }
+    /**
+     * 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, versionId) {
+        return this.store.loadVersionChanges(docId, versionId);
+    }
+    /**
+     * 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, versionId, name) {
+        return this.store.updateVersion(docId, versionId, { name });
+    }
+    /**
+     * 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).
+     */
+    async _getSnapshotAtRevision(docId, rev) {
+        const versions = await this.store.listVersions(docId, {
+            limit: 1,
+            reverse: true,
+            startAfter: rev ? rev + 1 : undefined,
+            origin: 'main',
+            orderBy: 'rev',
+        });
+        const latestMainVersion = versions[0];
+        const versionState = (latestMainVersion && (await this.store.loadVersionState(docId, latestMainVersion.id))) || null;
+        const versionRev = latestMainVersion?.rev ?? 0;
+        // Get *all* changes since that version up to the target revision (if specified)
+        const changesSinceVersion = await this.store.listChanges(docId, {
+            startAfter: versionRev,
+            endBefore: rev ? rev + 1 : undefined,
+        });
+        return {
+            state: versionState, // State from the base version
+            rev: versionRev, // Revision of the base version's state
+            changes: changesSinceVersion, // Changes that occurred *after* the base version state
+        };
+    }
+    /**
+     * 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.
+     */
+    async _getStateAtRevision(docId, rev) {
+        // Note: _getSnapshotAtRevision now returns the state *of the version* and changes *since* it.
+        // We need to apply the changes to get the state *at* the target revision.
+        const { state: versionState, rev: snapshotRev, changes } = await this._getSnapshotAtRevision(docId, rev);
+        return {
+            // Ensure null is passed if versionState or versionState.state is null/undefined
+            state: applyChanges(versionState?.state ?? null, changes),
+            rev: changes.at(-1)?.rev ?? snapshotRev,
+        };
+    }
+    /**
+     * 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.
+     */
+    async _createVersion(docId, state, changes, name) {
+        if (changes.length === 0)
+            return;
+        const baseRev = changes[0].baseRev;
+        if (baseRev === undefined) {
+            throw new Error(`Client changes must include baseRev for doc ${docId}.`);
+        }
+        const versionId = createId();
+        const sessionMetadata = {
+            id: versionId,
+            name,
+            origin: 'main',
+            startDate: changes[0].created,
+            endDate: changes[changes.length - 1].created,
+            rev: changes[changes.length - 1].rev,
+            baseRev,
+        };
+        await this.store.createVersion(docId, sessionMetadata, state, changes);
+        return sessionMetadata;
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,4 @@
+export { BranchManager } from './BranchManager';
+export { HistoryManager } from './HistoryManager';
+export { PatchServer } from './PatchServer';
+export type { Change, PatchSnapshot, PatchState, VersionMetadata } from '../types';

package/dist/server/index.js

@@ -0,0 +1,3 @@
+export { BranchManager } from './BranchManager';
+export { HistoryManager } from './HistoryManager';
+export { PatchServer } from './PatchServer';

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+import type { JSONPatchOp } from './json-patch/types';
+export interface Change {
+    /** Unique identifier for the change, generated client-side. */
+    id: string;
+    /** The patch operations. */
+    ops: JSONPatchOp[];
+    /** The revision number assigned on the client to the optimistic revision and updated by the server after commit. */
+    rev: number;
+    /** The server revision this change was based on. Required for client->server changes. */
+    baseRev?: number;
+    /** Client-side timestamp when the change was created. */
+    created: number;
+    /** Optional arbitrary metadata associated with the change. */
+    metadata?: Record<string, any>;
+    /** Optional batch identifier for grouping changes that belong to the same client batch (for multi-batch offline/large edits). */
+    batchId?: string;
+}
+/**
+ * Represents the state of a document in the OT protocol.
+ * @property state - The state of the document.
+ * @property rev - The revision number of the state.
+ */
+export interface PatchState<T = any> {
+    state: T;
+    rev: number;
+}
+/**
+ * Represents a snapshot of a document in the OT protocol.
+ * @property state - The state of the document.
+ * @property rev - The revision number of the state.
+ * @property changes - Any unapplied changes since `rev` that may be applied to the `state` to get the latest state.
+ */
+export interface PatchSnapshot<T = any> extends PatchState<T> {
+    changes: Change[];
+}
+/** Status options for a branch */
+export type BranchStatus = 'open' | 'closed' | 'merged' | 'archived' | 'abandoned';
+export interface Branch {
+    /** The ID of the branch document. */
+    id: string;
+    /** The ID of the document this document was branched from. */
+    branchedFromId: string;
+    /** The revision number on the source document where the branch occurred. */
+    branchedRev: number;
+    /** Server-side timestamp when the branch record was created. */
+    created: number;
+    /** Optional user-friendly name for the branch. */
+    name?: string;
+    /** Current status of the branch. */
+    status: BranchStatus;
+    /** Optional arbitrary metadata associated with the branch record. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Metadata, state snapshot, and included changes for a specific version.
+ */
+export interface VersionMetadata {
+    /** Unique identifier (UUID) for this version record. */
+    id: string;
+    name?: string;
+    /** ID of the parent version in the history DAG. Undefined for root versions and for the first branched version. */
+    parentId?: string;
+    /** Identifier linking versions from the same offline batch or branch. */
+    groupId?: string;
+    /** Indicates how the version was created ('main', 'offline', 'branch'). */
+    origin: 'main' | 'offline' | 'branch';
+    /** User-defined name if origin is 'branch'. */
+    branchName?: string;
+    /** Timestamp marking the beginning of the changes included in this version (e.g., first change in session). */
+    startDate: number;
+    /** Timestamp marking the end of the changes included in this version (e.g., last change in session). */
+    endDate: number;
+    /** The revision number this version was created at. */
+    rev: number;
+    /** The revision number on the main timeline before the changes that created this version. If this is an offline/branch version, this is the revision number of the source document where the branch was created and not . */
+    baseRev: number;
+}
+/**
+ * Options for listing committed server changes. *Always* ordered by revision number.
+ */
+export interface ListChangesOptions {
+    /** List changes committed strictly *after* this revision number. */
+    startAfter?: number;
+    /** List changes committed strictly *before* this revision number. */
+    endBefore?: number;
+    /** Maximum number of changes to return. */
+    limit?: number;
+    /** Return changes in descending revision order (latest first). Defaults to false (ascending). */
+    reverse?: boolean;
+    /** Filter out changes that have the given batch ID. */
+    withoutBatchId?: string;
+}
+/**
+ * Options for listing version metadata.
+ */
+export interface ListVersionsOptions {
+    /** List versions whose orderBy field is *after* this value. */
+    startAfter?: number;
+    /** List versions whose orderBy field is strictly *before* this value. */
+    endBefore?: number;
+    /** Maximum number of versions to return. */
+    limit?: number;
+    /** Sort by start date, rev, or baseRev. Defaults to 'rev'. */
+    orderBy?: 'startDate' | 'rev' | 'baseRev';
+    /** Return versions in descending order. Defaults to false (ascending). When reversed, startAfter and endBefore apply to the *reversed* list. */
+    reverse?: boolean;
+    /** Filter by the origin type. */
+    origin?: 'main' | 'offline' | 'branch';
+    /** Filter by the group ID (branch ID or offline batch ID). */
+    groupId?: string;
+}
+/**
+ * Interface for a backend storage system for patch synchronization.
+ * Defines methods needed by PatchServer, HistoryManager, etc.
+ */
+export interface PatchStoreBackend {
+    /** Adds a subscription for a client to one or more documents. */
+    addSubscription(clientId: string, docIds: string[]): Promise<string[]>;
+    /** Removes a subscription for a client from one or more documents. */
+    removeSubscription(clientId: string, docIds: string[]): Promise<string[]>;
+    /** Saves a batch of committed server changes. */
+    saveChanges(docId: string, changes: Change[]): Promise<void>;
+    /** Lists committed server changes based on revision numbers. */
+    listChanges(docId: string, options: ListChangesOptions): Promise<Change[]>;
+    /**
+     * Saves version metadata, its state snapshot, and the original changes that constitute it.
+     * State and changes are stored separately from the core metadata.
+     */
+    createVersion(docId: string, metadata: VersionMetadata, state: any, changes: Change[]): Promise<void>;
+    /** Update a version's metadata. */
+    updateVersion(docId: string, versionId: string, metadata: Partial<VersionMetadata>): Promise<void>;
+    /** Lists version metadata based on filtering/sorting options. */
+    listVersions(docId: string, options: ListVersionsOptions): Promise<VersionMetadata[]>;
+    /** Loads the state snapshot for a specific version ID. */
+    loadVersionState(docId: string, versionId: string): Promise<any | undefined>;
+    /** Loads the original Change objects associated with a specific version ID. */
+    loadVersionChanges(docId: string, versionId: string): Promise<Change[]>;
+    /** Deletes a document. */
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Extends PatchStoreBackend with methods specifically for managing branches.
+ */
+export interface BranchingStoreBackend extends PatchStoreBackend {
+    /** Lists metadata records for branches originating from a document. */
+    listBranches(docId: string): 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>;
+    /**
+     * @deprecated Use updateBranch with status instead.
+     * Marks a branch as closed. Implementations might handle this via updateBranch.
+     */
+    closeBranch(branchId: string): Promise<void>;
+}

package/dist/types.js

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