@dabble/patches 0.5.22 → 0.7.0

package/dist/server/PatchesServer.js

@@ -1,176 +0,0 @@
-import "../chunk-IZ2YBCUP.js";
-import { commitChanges } from "../algorithms/server/commitChanges.js";
-import { createVersion } from "../algorithms/server/createVersion.js";
-import { getSnapshotAtRevision } from "../algorithms/server/getSnapshotAtRevision.js";
-import { getStateAtRevision } from "../algorithms/server/getStateAtRevision.js";
-import { applyChanges } from "../algorithms/shared/applyChanges.js";
-import { createChange } from "../data/change.js";
-import { signal } from "../event-signal.js";
-import { createJSONPatch } from "../json-patch/createJSONPatch.js";
-import { getISO } from "../utils/dates.js";
-import { CompressedStoreBackend } from "./CompressedStoreBackend.js";
-class PatchesServer {
-  sessionTimeoutMillis;
-  maxStorageBytes;
-  store;
-  /** Notifies listeners whenever a batch of changes is *successfully* committed. */
-  onChangesCommitted = signal();
-  /** Notifies listeners when a document is deleted. */
-  onDocDeleted = signal();
-  constructor(store, options = {}) {
-    this.sessionTimeoutMillis = (options.sessionTimeoutMinutes ?? 30) * 60 * 1e3;
-    this.maxStorageBytes = options.maxStorageBytes;
-    if (options.compressor) {
-      this.store = new CompressedStoreBackend(store, options.compressor);
-    } else {
-      this.store = store;
-    }
-  }
-  /**
-   * Get the state of a document at a specific revision (or the latest state if no revision is provided).
-   * @param docId - The ID of the document.
-   * @param rev - The revision number.
-   * @returns The state of the document at the specified revision.
-   */
-  async getDoc(docId, atRev) {
-    return getStateAtRevision(this.store, docId, atRev);
-  }
-  /**
-   * Get the state of a document at a specific revision.
-   * @param docId - The ID of the document.
-   * @param rev - The revision number.
-   * @returns The state of the document at the specified revision.
-   */
-  async getStateAtRevision(docId, atRev) {
-    return getStateAtRevision(this.store, 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.
-   * @param options - Optional commit settings (e.g., forceCommit for migrations).
-   * @param originClientId - The ID of the client that initiated the commit (used by transport layer for broadcast filtering).
-   * @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, options, originClientId) {
-    const [committedChanges, transformedChanges] = await commitChanges(
-      this.store,
-      docId,
-      changes,
-      this.sessionTimeoutMillis,
-      options,
-      this.maxStorageBytes
-    );
-    if (transformedChanges.length > 0) {
-      try {
-        await this.onChangesCommitted.emit(docId, transformedChanges, originClientId);
-      } catch (error) {
-        console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
-      }
-    }
-    return [committedChanges, transformedChanges];
-  }
-  /**
-   * Make a server-side change to a document.
-   * @param mutator
-   * @returns
-   */
-  async change(docId, mutator, metadata) {
-    const { state, rev } = await this.getDoc(docId);
-    const patch = createJSONPatch(mutator);
-    if (patch.ops.length === 0) {
-      return null;
-    }
-    const change = createChange(rev, rev + 1, patch.ops, metadata);
-    patch.apply(state);
-    await this.commitChanges(docId, [change]);
-    return change;
-  }
-  /**
-   * Deletes a document.
-   * @param docId The document ID.
-   * @param originClientId - The ID of the client that initiated the delete operation.
-   * @param options - Optional deletion settings (e.g., skipTombstone for testing).
-   */
-  async deleteDoc(docId, options, originClientId) {
-    if (this.store.createTombstone && !options?.skipTombstone) {
-      const { rev: lastRev } = await this.getDoc(docId);
-      await this.store.createTombstone({
-        docId,
-        deletedAt: getISO(),
-        lastRev,
-        deletedByClientId: originClientId
-      });
-    }
-    await this.store.deleteDoc(docId);
-    await this.onDocDeleted.emit(docId, options, originClientId);
-  }
-  /**
-   * Removes the tombstone for a deleted document, allowing it to be recreated.
-   * @param docId The document ID.
-   * @returns True if tombstone was found and removed, false if no tombstone existed.
-   */
-  async undeleteDoc(docId) {
-    if (!this.store.removeTombstone) {
-      return false;
-    }
-    const tombstone = await this.store.getTombstone?.(docId);
-    if (!tombstone) {
-      return false;
-    }
-    await this.store.removeTombstone(docId);
-    return true;
-  }
-  // === Version Operations ===
-  /**
-   * Captures the current state of a document as a new version.
-   * @param docId The document ID.
-   * @param metadata Optional metadata for the version.
-   * @returns The ID of the created version.
-   */
-  async captureCurrentVersion(docId, metadata) {
-    assertVersionMetadata(metadata);
-    const { state: initialState, changes } = await getSnapshotAtRevision(this.store, docId);
-    let state = initialState;
-    state = applyChanges(state, changes);
-    const version = await createVersion(this.store, docId, state, changes, metadata);
-    if (!version) {
-      return null;
-    }
-    return version.id;
-  }
-}
-const nonModifiableMetadataFields = /* @__PURE__ */ new Set([
-  "id",
-  "parentId",
-  "groupId",
-  "origin",
-  "branchName",
-  "startedAt",
-  "endedAt",
-  "rev",
-  "baseRev"
-]);
-function assertVersionMetadata(metadata) {
-  if (!metadata) return;
-  for (const key in metadata) {
-    if (nonModifiableMetadataFields.has(key)) {
-      throw new Error(`Cannot modify version field ${key}`);
-    }
-  }
-}
-export {
-  PatchesServer,
-  assertVersionMetadata
-};

package/dist/server/branchUtils.d.ts

@@ -0,0 +1,82 @@
+import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
+import { EditableBranchMetadata, Branch, BranchStatus } from '../types.js';
+import '../event-signal.js';
+import '../net/websocket/AuthorizationProvider.js';
+import './types.js';
+import '../json-patch/types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../net/protocol/types.js';
+
+/**
+ * Standard API definition for branch managers.
+ * Used with JSONRPCServer.register() to expose branch methods.
+ */
+declare const branchManagerApi: ApiDefinition;
+/**
+ * Validates that branch metadata doesn't contain non-modifiable fields.
+ * @throws Error if metadata contains protected fields.
+ */
+declare function assertBranchMetadata(metadata?: EditableBranchMetadata): void;
+/**
+ * Store interface for branch ID generation.
+ */
+interface BranchIdGenerator {
+    createBranchId?: (docId: string) => Promise<string> | string;
+}
+/**
+ * Generates a branch ID, using the store's custom generator if available.
+ * @param store - Store that may have a custom createBranchId method.
+ * @param docId - The source document ID.
+ * @returns A unique branch document ID.
+ */
+declare function generateBranchId(store: BranchIdGenerator, docId: string): Promise<string>;
+/**
+ * Creates a Branch record with standard fields.
+ * @param branchDocId - The branch document ID.
+ * @param sourceDocId - The source document being branched from.
+ * @param branchedAtRev - The revision at which the branch was created.
+ * @param metadata - Optional branch metadata (name, etc.).
+ * @returns A new Branch object.
+ */
+declare function createBranchRecord(branchDocId: string, sourceDocId: string, branchedAtRev: number, metadata?: EditableBranchMetadata): Branch;
+/**
+ * Store interface for branch loading.
+ */
+interface BranchLoader {
+    loadBranch(docId: string): Promise<Branch | null>;
+}
+/**
+ * Validates that a document is not already a branch (prevents branch-of-branch).
+ * @param store - Store with loadBranch capability.
+ * @param docId - The document ID to check.
+ * @throws Error if the document is already a branch.
+ */
+declare function assertNotABranch(store: BranchLoader, docId: string): Promise<void>;
+/**
+ * Validates that a branch exists and is open for merging.
+ * @param branch - The branch to validate (may be null).
+ * @param branchId - The branch ID (for error messages).
+ * @throws Error if branch not found or not open.
+ */
+declare function assertBranchOpenForMerge(branch: Branch | null, branchId: string): asserts branch is Branch;
+/**
+ * Wraps a merge commit operation with standard error handling.
+ * @param branchId - The branch being merged.
+ * @param sourceDocId - The source document being merged into.
+ * @param commitFn - The async function that performs the commit.
+ * @returns The result of the commit function.
+ * @throws Error with standardized message if commit fails.
+ */
+declare function wrapMergeCommit<T>(branchId: string, sourceDocId: string, commitFn: () => Promise<T>): Promise<T>;
+/**
+ * Standard close branch operation.
+ * @param store - Store with updateBranch capability.
+ * @param branchId - The branch to close.
+ * @param status - The status to set (defaults to 'closed').
+ */
+declare function closeBranch(store: {
+    updateBranch(branchId: string, updates: Partial<Pick<Branch, 'status' | 'name'>>): Promise<void>;
+}, branchId: string, status?: Exclude<BranchStatus, 'open'>): Promise<void>;
+
+export { type BranchIdGenerator, type BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, closeBranch, createBranchRecord, generateBranchId, wrapMergeCommit };

package/dist/server/branchUtils.js

@@ -0,0 +1,66 @@
+import "../chunk-IZ2YBCUP.js";
+import { createId } from "crypto-id";
+const branchManagerApi = {
+  listBranches: "read",
+  createBranch: "write",
+  updateBranch: "write",
+  closeBranch: "write",
+  mergeBranch: "write"
+};
+const nonModifiableBranchFields = /* @__PURE__ */ new Set(["id", "docId", "branchedAtRev", "createdAt", "status"]);
+function assertBranchMetadata(metadata) {
+  if (!metadata) return;
+  for (const key in metadata) {
+    if (nonModifiableBranchFields.has(key)) {
+      throw new Error(`Cannot modify branch field ${key}`);
+    }
+  }
+}
+async function generateBranchId(store, docId) {
+  return store.createBranchId ? await Promise.resolve(store.createBranchId(docId)) : createId(22);
+}
+function createBranchRecord(branchDocId, sourceDocId, branchedAtRev, metadata) {
+  return {
+    ...metadata,
+    id: branchDocId,
+    docId: sourceDocId,
+    branchedAtRev,
+    createdAt: Date.now(),
+    status: "open"
+  };
+}
+async function assertNotABranch(store, docId) {
+  const maybeBranch = await store.loadBranch(docId);
+  if (maybeBranch) {
+    throw new Error("Cannot create a branch from another branch.");
+  }
+}
+function assertBranchOpenForMerge(branch, 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.`);
+  }
+}
+async function wrapMergeCommit(branchId, sourceDocId, commitFn) {
+  try {
+    return await commitFn();
+  } catch (error) {
+    console.error(`Failed to merge branch ${branchId} into ${sourceDocId}:`, error);
+    throw new Error(`Merge failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+async function closeBranch(store, branchId, status = "closed") {
+  await store.updateBranch(branchId, { status });
+}
+export {
+  assertBranchMetadata,
+  assertBranchOpenForMerge,
+  assertNotABranch,
+  branchManagerApi,
+  closeBranch,
+  createBranchRecord,
+  generateBranchId,
+  wrapMergeCommit
+};

package/dist/server/index.d.ts

@@ -1,12 +1,23 @@
-export { CompressedStoreBackend } from './CompressedStoreBackend.js';
-export { PatchesBranchManager } from './PatchesBranchManager.js';
+export { LWWServer, LWWServerOptions } from './LWWServer.js';
+export { OTServer, OTServerOptions } from './OTServer.js';
+export { BranchManager } from './BranchManager.js';
+export { LWWBranchManager } from './LWWBranchManager.js';
+export { OTBranchManager, PatchesBranchManager } from './OTBranchManager.js';
+export { LWWMemoryStoreBackend } from './LWWMemoryStoreBackend.js';
 export { PatchesHistoryManager } from './PatchesHistoryManager.js';
-export { PatchesServer, PatchesServerOptions } from './PatchesServer.js';
-export { BranchingStoreBackend, PatchesStoreBackend } from './types.js';
+export { BranchIdGenerator, BranchLoader, assertBranchMetadata, assertBranchOpenForMerge, assertNotABranch, branchManagerApi, createBranchRecord, generateBranchId, wrapMergeCommit } from './branchUtils.js';
+export { CompressedStoreBackend } from './CompressedStoreBackend.js';
+export { createTombstoneIfSupported, isTombstoneStore, removeTombstoneIfExists } from './tombstone.js';
+export { assertVersionMetadata } from './utils.js';
 export { CommitChangesOptions, DeleteDocOptions } from '../types.js';
+export { PatchesServer } from './PatchesServer.js';
+export { BranchingStoreBackend, LWWStoreBackend, LWWVersioningStoreBackend, ListFieldsOptions, OTStoreBackend, PatchesStoreBackend, ServerStoreBackend, TombstoneStoreBackend, VersioningStoreBackend } from './types.js';
+import '../event-signal.js';
+import '../net/protocol/JSONRPCServer.js';
+import '../net/websocket/AuthorizationProvider.js';
+import '../net/protocol/types.js';
+import '../json-patch/types.js';
 import '../compression/index.js';
 import '../algorithms/shared/lz.js';
-import '../json-patch/types.js';
-import '../event-signal.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';

package/dist/server/index.js

@@ -1,11 +1,40 @@
 import "../chunk-IZ2YBCUP.js";
-import { CompressedStoreBackend } from "./CompressedStoreBackend.js";
-import { PatchesBranchManager } from "./PatchesBranchManager.js";
+import { LWWServer } from "./LWWServer.js";
+import { OTServer } from "./OTServer.js";
+import { LWWBranchManager } from "./LWWBranchManager.js";
+import { OTBranchManager, PatchesBranchManager } from "./OTBranchManager.js";
+import { LWWMemoryStoreBackend } from "./LWWMemoryStoreBackend.js";
 import { PatchesHistoryManager } from "./PatchesHistoryManager.js";
-import { PatchesServer } from "./PatchesServer.js";
+import {
+  assertBranchMetadata,
+  assertBranchOpenForMerge,
+  assertNotABranch,
+  branchManagerApi,
+  createBranchRecord,
+  generateBranchId,
+  wrapMergeCommit
+} from "./branchUtils.js";
+import { CompressedStoreBackend } from "./CompressedStoreBackend.js";
+import { createTombstoneIfSupported, isTombstoneStore, removeTombstoneIfExists } from "./tombstone.js";
+import { assertVersionMetadata } from "./utils.js";
 export {
   CompressedStoreBackend,
+  LWWBranchManager,
+  LWWMemoryStoreBackend,
+  LWWServer,
+  OTBranchManager,
+  OTServer,
   PatchesBranchManager,
   PatchesHistoryManager,
-  PatchesServer
+  assertBranchMetadata,
+  assertBranchOpenForMerge,
+  assertNotABranch,
+  assertVersionMetadata,
+  branchManagerApi,
+  createBranchRecord,
+  createTombstoneIfSupported,
+  generateBranchId,
+  isTombstoneStore,
+  removeTombstoneIfExists,
+  wrapMergeCommit
 };

package/dist/server/tombstone.d.ts

@@ -0,0 +1,29 @@
+import { ServerStoreBackend, TombstoneStoreBackend } from './types.js';
+import '../json-patch/types.js';
+import '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+
+/**
+ * Type guard to check if a store implements TombstoneStoreBackend.
+ */
+declare function isTombstoneStore(store: ServerStoreBackend): store is ServerStoreBackend & TombstoneStoreBackend;
+/**
+ * Creates a tombstone for a document if the store supports it.
+ * @param store - The store backend
+ * @param docId - The document ID
+ * @param lastRev - The last revision before deletion
+ * @param clientId - The client that initiated deletion
+ * @param skipTombstone - If true, skip creating the tombstone
+ * @returns true if tombstone was created, false if skipped or store doesn't support it
+ */
+declare function createTombstoneIfSupported(store: ServerStoreBackend, docId: string, lastRev: number, clientId?: string, skipTombstone?: boolean): Promise<boolean>;
+/**
+ * Removes a tombstone for a document if it exists.
+ * @param store - The store backend
+ * @param docId - The document ID
+ * @returns true if tombstone was found and removed, false otherwise
+ */
+declare function removeTombstoneIfExists(store: ServerStoreBackend, docId: string): Promise<boolean>;
+
+export { createTombstoneIfSupported, isTombstoneStore, removeTombstoneIfExists };

package/dist/server/tombstone.js

@@ -0,0 +1,32 @@
+import "../chunk-IZ2YBCUP.js";
+function isTombstoneStore(store) {
+  return "createTombstone" in store && "getTombstone" in store && "removeTombstone" in store;
+}
+async function createTombstoneIfSupported(store, docId, lastRev, clientId, skipTombstone) {
+  if (!isTombstoneStore(store) || skipTombstone) {
+    return false;
+  }
+  await store.createTombstone({
+    docId,
+    deletedAt: Date.now(),
+    lastRev,
+    deletedByClientId: clientId
+  });
+  return true;
+}
+async function removeTombstoneIfExists(store, docId) {
+  if (!isTombstoneStore(store)) {
+    return false;
+  }
+  const tombstone = await store.getTombstone(docId);
+  if (!tombstone) {
+    return false;
+  }
+  await store.removeTombstone(docId);
+  return true;
+}
+export {
+  createTombstoneIfSupported,
+  isTombstoneStore,
+  removeTombstoneIfExists
+};

package/dist/server/types.d.ts

@@ -1,41 +1,137 @@
-import { Change, ListChangesOptions, PatchesState, VersionMetadata, EditableVersionMetadata, ListVersionsOptions, DocumentTombstone, Branch } from '../types.js';
+import { JSONPatchOp } from '../json-patch/types.js';
+import { VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, DocumentTombstone, Branch } from '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
 
 /**
- * Interface for a backend storage system for patch synchronization.
- * Defines methods needed by PatchesServer, PatchesHistoryManager, etc.
+ * Base interface for all server store backends.
+ * Provides the minimal deletion capability that all servers need.
  */
-interface PatchesStoreBackend {
-    /** 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[]>;
-    /** Loads the last version state for a document. Optional method for performance. */
-    loadLastVersionState?: (docId: string) => Promise<PatchesState | undefined>;
-    /** Saves the last version state for a document. Optional method for performance. */
-    saveLastVersionState?: (docId: string, rev: number, state: any) => Promise<void>;
+interface ServerStoreBackend {
+    /** Deletes a document and all its associated data. */
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Interface for version storage, shared between OT and LWW.
+ * OT requires this, LWW can optionally implement it for user-visible versioning.
+ */
+interface VersioningStoreBackend {
     /**
-     * Saves version metadata, its state snapshot, and the original changes that constitute it.
+     * Saves version metadata, its state snapshot, and optionally the original changes.
      * State and changes are stored separately from the core metadata.
+     * @param changes - Optional for LWW (which doesn't store changes), required for OT.
      */
-    createVersion(docId: string, metadata: VersionMetadata, state: any, changes: Change[]): Promise<void>;
-    /** Update a version's metadata. */
-    updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
-    /**
-     * Appends changes to an existing version, updating its state snapshot, endedAt, and endRev.
-     * Used when a session spans multiple batch submissions.
-     */
-    appendVersionChanges(docId: string, versionId: string, changes: Change[], newEndedAt: string, newEndRev: number, newState: any): Promise<void>;
+    createVersion(docId: string, metadata: VersionMetadata, state: any, changes?: Change[]): 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>;
+    /** Update a version's metadata. */
+    updateVersion(docId: string, versionId: string, metadata: EditableVersionMetadata): Promise<void>;
+}
+/**
+ * Interface for OT (Operational Transformation) storage backend.
+ * Extends ServerStoreBackend and VersioningStoreBackend because OT requires versioning
+ * for session tracking and state snapshots.
+ */
+interface OTStoreBackend extends ServerStoreBackend, VersioningStoreBackend {
+    /** 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[]>;
     /** 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>;
+    /**
+     * Appends changes to an existing version, updating its state snapshot, endedAt, and endRev.
+     * Used when a session spans multiple batch submissions.
+     */
+    appendVersionChanges(docId: string, versionId: string, changes: Change[], newEndedAt: number, newEndRev: number, newState: any): Promise<void>;
+}
+/**
+ * Options for listing fields. Use either sinceRev OR paths, not both.
+ */
+type ListFieldsOptions = {
+    sinceRev: number;
+} | {
+    paths: string[];
+};
+/**
+ * Interface for LWW (Last-Write-Wins) storage backend.
+ * LWW stores fields (not changes) and reconstructs state from fields.
+ */
+interface LWWStoreBackend extends ServerStoreBackend {
+    /**
+     * Get the current revision number without reconstructing state.
+     * More efficient than getSnapshot() when only the revision is needed.
+     * @param docId - The document ID.
+     * @returns The current revision number, or 0 if document doesn't exist.
+     */
+    getCurrentRev(docId: string): Promise<number>;
+    /**
+     * Get the latest snapshot of document state.
+     * @param docId - The document ID.
+     * @returns The snapshot state and revision, or null if no snapshot exists.
+     */
+    getSnapshot(docId: string): Promise<{
+        state: any;
+        rev: number;
+    } | null>;
+    /**
+     * Save a snapshot of document state (overwrites previous snapshot).
+     * @param docId - The document ID.
+     * @param state - The document state.
+     * @param rev - The revision number.
+     */
+    saveSnapshot(docId: string, state: any, rev: number): Promise<void>;
+    /**
+     * List field metadata, optionally filtered by paths or revision.
+     *
+     * Options are mutually exclusive:
+     * - `{ sinceRev: number }` - Get fields changed since a revision
+     * - `{ paths: string[] }` - Get fields at specific paths
+     * - No options - Get all fields
+     *
+     * @param docId - The document ID.
+     * @param options - Optional filter options.
+     * @returns Array of field metadata matching the criteria.
+     */
+    listOps(docId: string, options?: ListFieldsOptions): Promise<JSONPatchOp[]>;
+    /**
+     * Save field metadata and atomically increment the revision.
+     *
+     * Implementation requirements:
+     * - Atomically increment the document revision
+     * - Set the rev on all saved fields to the new revision
+     * - Delete children atomically when saving a parent (e.g., saving /obj deletes /obj/name)
+     * - Delete paths in pathsToDelete atomically with saving ops
+     *
+     * @param docId - The document ID.
+     * @param ops - Array of ops to save.
+     * @param pathsToDelete - Optional paths to delete atomically.
+     * @returns The new revision number.
+     */
+    saveOps(docId: string, ops: JSONPatchOp[], pathsToDelete?: string[]): Promise<number>;
+}
+/**
+ * Extended storage interface for LWWServer with versioning support.
+ * Versioning is optional - not all LWW docs need it.
+ */
+interface LWWVersioningStoreBackend extends LWWStoreBackend {
+    /**
+     * Creates a new version snapshot.
+     * @param docId - The document ID.
+     * @param versionId - The version ID.
+     * @param state - The document state snapshot.
+     * @param rev - The revision number.
+     * @param metadata - Optional version metadata.
+     */
+    createVersion(docId: string, versionId: string, state: any, rev: number, metadata?: EditableVersionMetadata): Promise<void>;
+}
+/**
+ * Interface for tombstone storage, providing soft-delete capabilities.
+ * Optional add-on for servers that need to track deleted documents.
+ */
+interface TombstoneStoreBackend {
     /** Creates a tombstone for a deleted document. Called before deleteDoc() to preserve deletion metadata. */
     createTombstone(tombstone: DocumentTombstone): Promise<void>;
     /** Retrieves a tombstone for a document if it exists. Returns undefined if the document was never deleted or tombstone has expired. */
@@ -44,9 +140,10 @@ interface PatchesStoreBackend {
     removeTombstone(docId: string): Promise<void>;
 }
 /**
- * Extends PatchesStoreBackend with methods specifically for managing branches.
+ * Interface for branch storage. Standalone interface that can be composed
+ * with OTStoreBackend or LWWStoreBackend as needed.
  */
-interface BranchingStoreBackend extends PatchesStoreBackend {
+interface BranchingStoreBackend {
     /**
      * Generates a unique ID for a new branch document.
      * If not provided, a random 22-character ID is generated using createId().
@@ -67,5 +164,10 @@ interface BranchingStoreBackend extends PatchesStoreBackend {
      */
     closeBranch(branchId: string): Promise<void>;
 }
+/**
+ * @deprecated Use OTStoreBackend instead.
+ * Alias for backwards compatibility.
+ */
+type PatchesStoreBackend = OTStoreBackend;
 
-export type { BranchingStoreBackend, PatchesStoreBackend };
+export type { BranchingStoreBackend, LWWStoreBackend, LWWVersioningStoreBackend, ListFieldsOptions, OTStoreBackend, PatchesStoreBackend, ServerStoreBackend, TombstoneStoreBackend, VersioningStoreBackend };

package/dist/server/utils.d.ts

@@ -0,0 +1,12 @@
+import { EditableVersionMetadata } from '../types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
+/**
+ * Validates that version metadata does not contain non-modifiable fields.
+ * @throws Error if metadata contains any non-modifiable fields.
+ */
+declare function assertVersionMetadata(metadata?: EditableVersionMetadata): void;
+
+export { assertVersionMetadata };