@dabble/patches 0.6.0 → 0.7.1

package/dist/server/LWWMemoryStoreBackend.js

@@ -0,0 +1,182 @@
+import "../chunk-IZ2YBCUP.js";
+class LWWMemoryStoreBackend {
+  docs = /* @__PURE__ */ new Map();
+  tombstones = /* @__PURE__ */ new Map();
+  versions = /* @__PURE__ */ new Map();
+  branches = /* @__PURE__ */ new Map();
+  getOrCreateDoc(docId) {
+    let doc = this.docs.get(docId);
+    if (!doc) {
+      doc = { snapshot: null, ops: [], rev: 0 };
+      this.docs.set(docId, doc);
+    }
+    return doc;
+  }
+  // === Revision ===
+  async getCurrentRev(docId) {
+    return this.docs.get(docId)?.rev ?? 0;
+  }
+  // === Snapshot ===
+  async getSnapshot(docId) {
+    return this.docs.get(docId)?.snapshot ?? null;
+  }
+  async saveSnapshot(docId, state, rev) {
+    const doc = this.getOrCreateDoc(docId);
+    doc.snapshot = { state, rev };
+    doc.ops = doc.ops.filter((op) => (op.rev ?? 0) > rev);
+  }
+  // === Ops ===
+  async saveOps(docId, newOps, pathsToDelete) {
+    const doc = this.getOrCreateDoc(docId);
+    const newRev = ++doc.rev;
+    if (pathsToDelete) {
+      for (const path of pathsToDelete) {
+        doc.ops = doc.ops.filter((op) => op.path !== path);
+      }
+    }
+    for (const op of newOps) {
+      op.rev = newRev;
+      const childPrefix = op.path + "/";
+      doc.ops = doc.ops.filter((existing) => existing.path !== op.path && !existing.path.startsWith(childPrefix));
+      doc.ops.push(op);
+    }
+    return newRev;
+  }
+  async listOps(docId, options) {
+    const doc = this.docs.get(docId);
+    if (!doc) {
+      return [];
+    }
+    if (!options) {
+      return [...doc.ops];
+    }
+    if ("sinceRev" in options) {
+      return doc.ops.filter((op) => (op.rev ?? 0) > options.sinceRev);
+    }
+    if ("paths" in options) {
+      const pathSet = new Set(options.paths);
+      return doc.ops.filter((op) => pathSet.has(op.path));
+    }
+    return [];
+  }
+  // === Deletion ===
+  async deleteDoc(docId) {
+    this.docs.delete(docId);
+  }
+  // === Tombstones ===
+  async createTombstone(tombstone) {
+    this.tombstones.set(tombstone.docId, tombstone);
+  }
+  async getTombstone(docId) {
+    return this.tombstones.get(docId);
+  }
+  async removeTombstone(docId) {
+    this.tombstones.delete(docId);
+  }
+  // === Versioning ===
+  async createVersion(docId, metadata, state, _changes) {
+    const versions = this.versions.get(docId) || [];
+    versions.push({ metadata, state });
+    this.versions.set(docId, versions);
+  }
+  async listVersions(docId, options) {
+    const versions = this.versions.get(docId) || [];
+    let result = versions.map((v) => v.metadata);
+    if (!options) return result;
+    if (options.origin) {
+      result = result.filter((v) => v.origin === options.origin);
+    }
+    if (options.groupId) {
+      result = result.filter((v) => v.groupId === options.groupId);
+    }
+    const orderBy = options.orderBy || "endRev";
+    result.sort((a, b) => {
+      const aVal = a[orderBy];
+      const bVal = b[orderBy];
+      return aVal - bVal;
+    });
+    if (options.reverse) {
+      result.reverse();
+    }
+    if (options.startAfter !== void 0) {
+      const startVal = options.startAfter;
+      result = result.filter((v) => v[orderBy] > startVal);
+    }
+    if (options.endBefore !== void 0) {
+      const endVal = options.endBefore;
+      result = result.filter((v) => v[orderBy] < endVal);
+    }
+    if (options.limit !== void 0) {
+      result = result.slice(0, options.limit);
+    }
+    return result;
+  }
+  async loadVersionState(docId, versionId) {
+    const versions = this.versions.get(docId) || [];
+    const version = versions.find((v) => v.metadata.id === versionId);
+    return version?.state;
+  }
+  async updateVersion(docId, versionId, metadata) {
+    const versions = this.versions.get(docId) || [];
+    const version = versions.find((v) => v.metadata.id === versionId);
+    if (version) {
+      Object.assign(version.metadata, metadata);
+    }
+  }
+  // === Branching ===
+  async listBranches(docId) {
+    const result = [];
+    for (const branch of this.branches.values()) {
+      if (branch.docId === docId) {
+        result.push(branch);
+      }
+    }
+    return result;
+  }
+  async loadBranch(branchId) {
+    return this.branches.get(branchId) || null;
+  }
+  async createBranch(branch) {
+    this.branches.set(branch.id, branch);
+  }
+  async updateBranch(branchId, updates) {
+    const branch = this.branches.get(branchId);
+    if (branch) {
+      Object.assign(branch, updates);
+    }
+  }
+  async closeBranch(branchId) {
+    await this.updateBranch(branchId, { status: "closed" });
+  }
+  // === Testing utilities ===
+  /**
+   * Clears all data from the store. Useful for test cleanup.
+   */
+  clear() {
+    this.docs.clear();
+    this.tombstones.clear();
+    this.versions.clear();
+    this.branches.clear();
+  }
+  /**
+   * Gets the raw document data for inspection in tests.
+   */
+  getDocData(docId) {
+    return this.docs.get(docId);
+  }
+  /**
+   * Gets the versions for a document for inspection in tests.
+   */
+  getVersions(docId) {
+    return this.versions.get(docId);
+  }
+  /**
+   * Gets all branches for inspection in tests.
+   */
+  getBranches() {
+    return this.branches;
+  }
+}
+export {
+  LWWMemoryStoreBackend
+};

package/dist/server/LWWServer.d.ts

@@ -0,0 +1,130 @@
+import { Signal } from '../event-signal.js';
+import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
+import { Change, DeleteDocOptions, PatchesState, ChangeInput, CommitChangesOptions, ChangeMutator, EditableVersionMetadata } from '../types.js';
+import { PatchesServer } from './PatchesServer.js';
+import { LWWStoreBackend } from './types.js';
+import '../net/websocket/AuthorizationProvider.js';
+import '../json-patch/types.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../net/protocol/types.js';
+
+/**
+ * Configuration options for LWWServer.
+ */
+interface LWWServerOptions {
+    /**
+     * Number of revisions between automatic snapshots.
+     * Defaults to 200.
+     */
+    snapshotInterval?: number;
+}
+/**
+ * Last-Write-Wins (LWW) server implementation.
+ *
+ * Unlike OTServer which stores changes and uses Operational Transformation,
+ * LWWServer stores fields with timestamps. Conflicts are resolved by comparing
+ * timestamps - the later timestamp wins.
+ *
+ * Key differences from OT:
+ * - Stores fields, not changes
+ * - No transformation needed
+ * - Simpler conflict resolution
+ * - Better suited for settings, preferences, status data
+ *
+ * @example
+ * ```typescript
+ * import { LWWServer } from '@dabble/patches/server';
+ *
+ * const store = new MyLWWStoreBackend();
+ * const server = new LWWServer(store);
+ *
+ * // Commit changes with timestamps
+ * const changes = await server.commitChanges('doc1', [{
+ *   id: 'change1',
+ *   ops: [{ op: 'replace', path: '/name', value: 'Alice', ts: Date.now() }],
+ * }]);
+ * ```
+ */
+declare class LWWServer implements PatchesServer {
+    /**
+     * Static API definition for use with JSONRPCServer.register().
+     * Maps method names to required access levels.
+     */
+    static api: ApiDefinition;
+    readonly store: LWWStoreBackend;
+    private readonly snapshotInterval;
+    /** Notifies listeners whenever a batch of changes is successfully committed. */
+    readonly onChangesCommitted: Signal<(docId: string, changes: Change[], originClientId?: string) => void>;
+    /** Notifies listeners when a document is deleted. */
+    readonly onDocDeleted: Signal<(docId: string, options?: DeleteDocOptions, originClientId?: string) => void>;
+    constructor(store: LWWStoreBackend, options?: LWWServerOptions);
+    /**
+     * Get the current state of a document.
+     * Reconstructs state from snapshot + ops changed since snapshot.
+     *
+     * @param docId - The document ID.
+     * @returns The document state and revision, or `{ state: {}, rev: 0 }` if not found.
+     */
+    getDoc(docId: string): Promise<PatchesState>;
+    /**
+     * Get changes that occurred after a specific revision.
+     * LWW doesn't store changes, so this synthesizes a change from ops.
+     *
+     * @param docId - The document ID.
+     * @param rev - The revision number to get changes after.
+     * @returns Array containing 0 or 1 synthesized changes.
+     */
+    getChangesSince(docId: string, rev: number): Promise<Change[]>;
+    /**
+     * Commit changes to a document using LWW conflict resolution.
+     *
+     * Uses the consolidateOps algorithm to:
+     * 1. Handle parent hierarchy validation (returns correction ops)
+     * 2. Consolidate incoming ops with existing ops using LWW rules
+     * 3. Convert delta ops (@inc, @bit, etc.) to concrete replace ops
+     *
+     * @param docId - The document ID.
+     * @param changes - The changes to commit (always 1 for LWW).
+     * @param _options - Optional commit options (ignored for LWW).
+     * @returns Array containing 0-1 changes with catchup ops and new rev.
+     */
+    commitChanges(docId: string, changes: ChangeInput[], _options?: CommitChangesOptions): Promise<Change[]>;
+    /**
+     * Delete a document and emit deletion signal.
+     * Creates a tombstone if the store supports it.
+     *
+     * @param docId - The document ID.
+     * @param options - Optional deletion options.
+     */
+    deleteDoc(docId: string, options?: DeleteDocOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    undeleteDoc(docId: string): Promise<boolean>;
+    /**
+     * Make a server-side change to a document.
+     * @param docId - The document ID.
+     * @param mutator - A function that receives a JSONPatch and PathProxy to define the changes.
+     * @param metadata - Optional metadata for the change.
+     * @returns The created change, or null if no operations were generated.
+     */
+    change<T = Record<string, any>>(docId: string, mutator: ChangeMutator<T>, metadata?: Record<string, any>): Promise<Change | null>;
+    /**
+     * Captures the current state of a document as a new version.
+     * Only works if store implements VersioningStoreBackend.
+     *
+     * @param docId - The document ID.
+     * @param metadata - Optional metadata for the version.
+     * @returns The ID of the created version, or null if no document exists.
+     */
+    captureCurrentVersion(docId: string, metadata?: EditableVersionMetadata): Promise<string | null>;
+    /**
+     * Type guard to check if the store supports versioning.
+     */
+    private isVersioningStore;
+}
+
+export { LWWServer, type LWWServerOptions };

package/dist/server/LWWServer.js

@@ -0,0 +1,214 @@
+import "../chunk-IZ2YBCUP.js";
+import { createVersionMetadata } from "../data/version.js";
+import { consolidateOps, convertDeltaOps } from "../algorithms/lww/consolidateOps.js";
+import { createChange } from "../data/change.js";
+import { signal } from "../event-signal.js";
+import { createJSONPatch } from "../json-patch/createJSONPatch.js";
+import { JSONPatch } from "../json-patch/JSONPatch.js";
+import { getClientId } from "../net/serverContext.js";
+import { createTombstoneIfSupported, removeTombstoneIfExists } from "./tombstone.js";
+import { assertVersionMetadata } from "./utils.js";
+class LWWServer {
+  /**
+   * Static API definition for use with JSONRPCServer.register().
+   * Maps method names to required access levels.
+   */
+  static api = {
+    getDoc: "read",
+    getChangesSince: "read",
+    commitChanges: "write",
+    deleteDoc: "write",
+    undeleteDoc: "write"
+  };
+  store;
+  snapshotInterval;
+  /** 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.store = store;
+    this.snapshotInterval = options.snapshotInterval ?? 200;
+  }
+  /**
+   * Get the current state of a document.
+   * Reconstructs state from snapshot + ops changed since snapshot.
+   *
+   * @param docId - The document ID.
+   * @returns The document state and revision, or `{ state: {}, rev: 0 }` if not found.
+   */
+  async getDoc(docId) {
+    const snapshot = await this.store.getSnapshot(docId);
+    const baseState = snapshot?.state ?? {};
+    const baseRev = snapshot?.rev ?? 0;
+    const ops = await this.store.listOps(docId, { sinceRev: baseRev });
+    if (ops.length === 0) {
+      return { state: baseState, rev: baseRev };
+    }
+    const state = new JSONPatch(ops).apply(baseState);
+    const rev = Math.max(baseRev, ...ops.map((op) => op.rev ?? 0));
+    return { state, rev };
+  }
+  /**
+   * Get changes that occurred after a specific revision.
+   * LWW doesn't store changes, so this synthesizes a change from ops.
+   *
+   * @param docId - The document ID.
+   * @param rev - The revision number to get changes after.
+   * @returns Array containing 0 or 1 synthesized changes.
+   */
+  async getChangesSince(docId, rev) {
+    const ops = await this.store.listOps(docId, { sinceRev: rev });
+    if (ops.length === 0) {
+      return [];
+    }
+    const sortedOps = [...ops].sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+    const maxRev = Math.max(...ops.map((op) => op.rev ?? 0));
+    const maxTs = Math.max(...ops.map((op) => op.ts ?? 0));
+    return [createChange(rev, maxRev, sortedOps, { committedAt: maxTs || Date.now() })];
+  }
+  /**
+   * Commit changes to a document using LWW conflict resolution.
+   *
+   * Uses the consolidateOps algorithm to:
+   * 1. Handle parent hierarchy validation (returns correction ops)
+   * 2. Consolidate incoming ops with existing ops using LWW rules
+   * 3. Convert delta ops (@inc, @bit, etc.) to concrete replace ops
+   *
+   * @param docId - The document ID.
+   * @param changes - The changes to commit (always 1 for LWW).
+   * @param _options - Optional commit options (ignored for LWW).
+   * @returns Array containing 0-1 changes with catchup ops and new rev.
+   */
+  async commitChanges(docId, changes, _options) {
+    if (changes.length === 0) {
+      return [];
+    }
+    const change = changes[0];
+    const serverNow = Date.now();
+    const clientRev = change.rev;
+    const newOps = change.ops.map((op) => op.ts ? op : { ...op, ts: serverNow });
+    const existingOps = await this.store.listOps(docId);
+    const { opsToSave, pathsToDelete, opsToReturn } = consolidateOps(existingOps, newOps);
+    const opsToStore = convertDeltaOps(opsToSave);
+    const currentRev = await this.store.getCurrentRev(docId);
+    let newRev = currentRev;
+    if (opsToStore.length > 0 || pathsToDelete.length > 0) {
+      newRev = await this.store.saveOps(docId, opsToStore, pathsToDelete);
+    }
+    if (newRev > 0 && newRev % this.snapshotInterval === 0) {
+      const { state } = await this.getDoc(docId);
+      await this.store.saveSnapshot(docId, state, newRev);
+    }
+    const responseOps = [...opsToReturn];
+    if (clientRev !== void 0) {
+      const opsSince = await this.store.listOps(docId, { sinceRev: clientRev });
+      const sentPaths = new Set(change.ops.map((o) => o.path));
+      const catchupOps = opsSince.filter((op) => !isPathOrChild(op.path, sentPaths)).sort((a, b) => (a.ts ?? 0) - (b.ts ?? 0));
+      responseOps.push(...catchupOps);
+    }
+    const responseChange = createChange(clientRev ?? 0, newRev, responseOps, {
+      id: change.id,
+      committedAt: serverNow
+    });
+    if (opsToStore.length > 0) {
+      try {
+        const broadcastChange = createChange(currentRev, newRev, opsToStore, {
+          id: change.id,
+          committedAt: serverNow
+        });
+        await this.onChangesCommitted.emit(docId, [broadcastChange], getClientId());
+      } catch (error) {
+        console.error(`Failed to notify clients about committed changes for doc ${docId}:`, error);
+      }
+    }
+    return [responseChange];
+  }
+  /**
+   * Delete a document and emit deletion signal.
+   * Creates a tombstone if the store supports it.
+   *
+   * @param docId - The document ID.
+   * @param options - Optional deletion options.
+   */
+  async deleteDoc(docId, options) {
+    const clientId = getClientId();
+    const rev = await this.store.getCurrentRev(docId);
+    await createTombstoneIfSupported(this.store, docId, rev, clientId, options?.skipTombstone);
+    await this.store.deleteDoc(docId);
+    await this.onDocDeleted.emit(docId, options, clientId);
+  }
+  /**
+   * 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) {
+    return removeTombstoneIfExists(this.store, docId);
+  }
+  /**
+   * Make a server-side change to a document.
+   * @param docId - The document ID.
+   * @param mutator - A function that receives a JSONPatch and PathProxy to define the changes.
+   * @param metadata - Optional metadata for the change.
+   * @returns The created change, or null if no operations were generated.
+   */
+  async change(docId, mutator, metadata) {
+    const { state, rev } = await this.getDoc(docId);
+    const patch = createJSONPatch(mutator);
+    if (patch.ops.length === 0) {
+      return null;
+    }
+    const serverNow = Date.now();
+    const opsWithTs = patch.ops.map((op) => ({ ...op, ts: serverNow }));
+    const change = createChange(rev, rev + 1, opsWithTs, metadata);
+    patch.apply(state);
+    await this.commitChanges(docId, [change]);
+    return change;
+  }
+  /**
+   * Captures the current state of a document as a new version.
+   * Only works if store implements VersioningStoreBackend.
+   *
+   * @param docId - The document ID.
+   * @param metadata - Optional metadata for the version.
+   * @returns The ID of the created version, or null if no document exists.
+   */
+  async captureCurrentVersion(docId, metadata) {
+    assertVersionMetadata(metadata);
+    if (!this.isVersioningStore(this.store)) {
+      throw new Error("LWW versioning requires a store that implements VersioningStoreBackend");
+    }
+    const { state, rev } = await this.getDoc(docId);
+    if (rev === 0) {
+      return null;
+    }
+    const versionMetadata = createVersionMetadata({
+      origin: "main",
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+      startRev: rev,
+      endRev: rev,
+      ...metadata
+    });
+    await this.store.createVersion(docId, versionMetadata, state);
+    return versionMetadata.id;
+  }
+  /**
+   * Type guard to check if the store supports versioning.
+   */
+  isVersioningStore(store) {
+    return "createVersion" in store;
+  }
+}
+function isPathOrChild(path, sentPaths) {
+  for (const sent of sentPaths) {
+    if (path === sent || path.startsWith(sent + "/")) {
+      return true;
+    }
+  }
+  return false;
+}
+export {
+  LWWServer
+};

package/dist/server/{PatchesBranchManager.d.ts → OTBranchManager.d.ts}

@@ -1,23 +1,39 @@
+import { ApiDefinition } from '../net/protocol/JSONRPCServer.js';
 import { Branch, EditableBranchMetadata, BranchStatus, Change } from '../types.js';
+import { BranchManager } from './BranchManager.js';
 import { PatchesServer } from './PatchesServer.js';
-import { BranchingStoreBackend } from './types.js';
+import { OTStoreBackend, BranchingStoreBackend } from './types.js';
+export { assertBranchMetadata } from './branchUtils.js';
+import '../event-signal.js';
+import '../net/websocket/AuthorizationProvider.js';
+import '../json-patch/types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../event-signal.js';
-import '../compression/index.js';
-import '../algorithms/shared/lz.js';
+import '../net/protocol/types.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.
+ * Combined store backend type for OT branch management.
+ * Requires both OT operations and branch metadata operations.
  */
-declare class PatchesBranchManager {
+type OTBranchStore = OTStoreBackend & BranchingStoreBackend;
+/**
+ * OT-specific branch manager implementation.
+ *
+ * Manages branches for documents using Operational Transformation semantics:
+ * - Creates branches at specific revision points
+ * - Uses fast-forward merge when possible (no concurrent changes on source)
+ * - Falls back to flattened merge for divergent histories
+ *
+ * A branch is a document that originates from another document at a specific revision.
+ * Its first version represents the source document's state at that revision.
+ * Branches allow parallel development with the ability to merge changes back.
+ */
+declare class OTBranchManager implements BranchManager {
     private readonly store;
     private readonly patchesServer;
     private readonly maxPayloadBytes?;
-    constructor(store: BranchingStoreBackend, patchesServer: PatchesServer, maxPayloadBytes?: number | undefined);
+    static api: ApiDefinition;
+    constructor(store: OTBranchStore, patchesServer: PatchesServer, maxPayloadBytes?: number | undefined);
     /**
      * Lists all open branches for a document.
      * @param docId - The ID of the document.
@@ -53,6 +69,10 @@ declare class PatchesBranchManager {
      */
     mergeBranch(branchId: string): Promise<Change[]>;
 }
-declare function assertBranchMetadata(metadata?: EditableBranchMetadata): void;
 
-export { PatchesBranchManager, assertBranchMetadata };
+/**
+ * @deprecated Use OTBranchManager instead. This alias will be removed in a future version.
+ */
+declare const PatchesBranchManager: typeof OTBranchManager;
+
+export { OTBranchManager, PatchesBranchManager };