@dabble/patches 0.6.0 → 0.7.1

package/dist/server/types.d.ts

@@ -1,41 +1,122 @@
-import { Change, ListChangesOptions, PatchesState, VersionMetadata, EditableVersionMetadata, ListVersionsOptions, DocumentTombstone, Branch } from '../types.js';
+import { JSONPatchOp } from '../json-patch/types.js';
+import { DocumentTombstone, VersionMetadata, Change, ListVersionsOptions, EditableVersionMetadata, ListChangesOptions, 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>;
+    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>;
+    /** Loads the original Change objects associated with a specific version ID. */
+    loadVersionChanges?(docId: string, versionId: string): Promise<Change[]>;
     /**
      * 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>;
-    /** 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>;
+    appendVersionChanges?(docId: string, versionId: string, changes: Change[], newEndedAt: number, newEndRev: number, newState: any): 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[]>;
+}
+/**
+ * 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>;
+}
+/**
+ * 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 +125,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().
@@ -68,4 +150,4 @@ interface BranchingStoreBackend extends PatchesStoreBackend {
     closeBranch(branchId: string): Promise<void>;
 }
 
-export type { BranchingStoreBackend, PatchesStoreBackend };
+export type { BranchingStoreBackend, LWWStoreBackend, ListFieldsOptions, OTStoreBackend, 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 };

package/dist/server/utils.js

@@ -0,0 +1,23 @@
+import "../chunk-IZ2YBCUP.js";
+const nonModifiableVersionFields = /* @__PURE__ */ new Set([
+  "id",
+  "parentId",
+  "groupId",
+  "origin",
+  "branchName",
+  "startedAt",
+  "endedAt",
+  "rev",
+  "baseRev"
+]);
+function assertVersionMetadata(metadata) {
+  if (!metadata) return;
+  for (const key in metadata) {
+    if (nonModifiableVersionFields.has(key)) {
+      throw new Error(`Cannot modify version field ${key}`);
+    }
+  }
+}
+export {
+  assertVersionMetadata
+};

package/dist/solid/context.d.ts

@@ -2,12 +2,12 @@ import { JSX } from 'solid-js';
 import { Patches } from '../client/Patches.js';
 import { PatchesSync } from '../net/PatchesSync.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../client/PatchesDoc.js';
-import '../algorithms/shared/changeBatching.js';
+import '../client/ClientAlgorithm.js';
+import '../BaseDoc-DkP3tUhT.js';
 import '../client/PatchesStore.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';
@@ -15,6 +15,7 @@ import '../net/websocket/PatchesWebSocket.js';
 import '../net/PatchesClient.js';
 import '../net/websocket/WebSocketTransport.js';
 import '../utils/deferred.js';
+import '../algorithms/ot/shared/changeBatching.js';
 
 /**
  * Context value containing Patches and optional PatchesSync instances.

package/dist/solid/doc-manager.d.ts

@@ -1,12 +1,12 @@
 import { Patches } from '../client/Patches.js';
-import { PatchesDoc } from '../client/PatchesDoc.js';
+import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
+import '../client/ClientAlgorithm.js';
 import '../client/PatchesStore.js';
-import '../algorithms/shared/changeBatching.js';
 
 /**
  * Reference counting manager for PatchesDoc instances.

package/dist/solid/index.d.ts

@@ -4,12 +4,12 @@ export { DocManager, getDocManager } from './doc-manager.js';
 import 'solid-js';
 import '../client/Patches.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../client/PatchesDoc.js';
-import '../algorithms/shared/changeBatching.js';
+import '../client/ClientAlgorithm.js';
+import '../BaseDoc-DkP3tUhT.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../net/protocol/types.js';
@@ -18,3 +18,4 @@ import '../net/websocket/PatchesWebSocket.js';
 import '../net/PatchesClient.js';
 import '../net/websocket/WebSocketTransport.js';
 import '../utils/deferred.js';
+import '../algorithms/ot/shared/changeBatching.js';

package/dist/solid/primitives.d.ts

@@ -1,11 +1,10 @@
 import { Accessor } from 'solid-js';
-import { PatchesDoc } from '../client/PatchesDoc.js';
+import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
 import { ChangeMutator } from '../types.js';
 import '../event-signal.js';
-import '../algorithms/shared/changeBatching.js';
+import '../json-patch/types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
 
 /**
  * Options for usePatchesDoc primitive.

package/dist/types.d.ts

@@ -17,8 +17,8 @@ interface ChangeInput {
     baseRev?: number;
     /** Optional revision number. If omitted, server assigns based on current state. */
     rev?: number;
-    /** Unix timestamp in milliseconds when the change was created. */
-    createdAt: number;
+    /** Unix timestamp in milliseconds when the change was created. If omitted, server sets to current time. */
+    createdAt?: number;
     /** Optional batch identifier for grouping changes that belong to the same client batch (for multi-batch offline/large edits). */
     batchId?: string;
     /** Optional arbitrary metadata associated with the change. */
@@ -33,6 +33,8 @@ interface Change extends ChangeInput {
     baseRev: number;
     /** The revision number assigned by the server after commit. */
     rev: number;
+    /** Unix timestamp in milliseconds when the change was created (always set by server if omitted from input). */
+    createdAt: number;
     /** Unix timestamp in milliseconds when the change was committed. */
     committedAt: number;
 }

package/dist/vue/composables.d.ts

@@ -1,11 +1,10 @@
 import { ShallowRef, Ref, MaybeRef } from 'vue';
-import { PatchesDoc } from '../client/PatchesDoc.js';
+import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
 import { ChangeMutator } from '../types.js';
 import '../event-signal.js';
-import '../algorithms/shared/changeBatching.js';
+import '../json-patch/types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
 
 /**
  * Options for usePatchesDoc composable.

package/dist/vue/doc-manager.d.ts

@@ -1,12 +1,12 @@
 import { Patches } from '../client/Patches.js';
-import { PatchesDoc } from '../client/PatchesDoc.js';
+import { a as PatchesDoc } from '../BaseDoc-DkP3tUhT.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
+import '../client/ClientAlgorithm.js';
 import '../client/PatchesStore.js';
-import '../algorithms/shared/changeBatching.js';
 
 /**
  * Reference counting manager for PatchesDoc instances.

package/dist/vue/index.d.ts

@@ -4,12 +4,12 @@ export { DocManager, getDocManager } from './doc-manager.js';
 import 'vue';
 import '../client/Patches.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../client/PatchesDoc.js';
-import '../algorithms/shared/changeBatching.js';
+import '../client/ClientAlgorithm.js';
+import '../BaseDoc-DkP3tUhT.js';
 import '../client/PatchesStore.js';
 import '../net/PatchesSync.js';
 import '../net/protocol/types.js';
@@ -18,3 +18,4 @@ import '../net/websocket/PatchesWebSocket.js';
 import '../net/PatchesClient.js';
 import '../net/websocket/WebSocketTransport.js';
 import '../utils/deferred.js';
+import '../algorithms/ot/shared/changeBatching.js';

package/dist/vue/provider.d.ts

@@ -2,12 +2,12 @@ import { InjectionKey, App } from 'vue';
 import { Patches } from '../client/Patches.js';
 import { PatchesSync } from '../net/PatchesSync.js';
 import '../event-signal.js';
+import '../json-patch/types.js';
 import '../types.js';
 import '../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../json-patch/types.js';
-import '../client/PatchesDoc.js';
-import '../algorithms/shared/changeBatching.js';
+import '../client/ClientAlgorithm.js';
+import '../BaseDoc-DkP3tUhT.js';
 import '../client/PatchesStore.js';
 import '../net/protocol/types.js';
 import '../net/protocol/JSONRPCClient.js';
@@ -15,6 +15,7 @@ import '../net/websocket/PatchesWebSocket.js';
 import '../net/PatchesClient.js';
 import '../net/websocket/WebSocketTransport.js';
 import '../utils/deferred.js';
+import '../algorithms/ot/shared/changeBatching.js';
 
 /**
  * Injection key for Patches instance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {

package/dist/algorithms/client/collapsePendingChanges.d.ts

@@ -1,30 +0,0 @@
-import { Change } from '../../types.js';
-import '../../json-patch/JSONPatch.js';
-import '@dabble/delta';
-import '../../json-patch/types.js';
-
-/**
- * Collapses redundant pending changes before sync to reduce network traffic.
- *
- * This optimization automatically detects and collapses multiple "replace" operations
- * on the same JSON path with primitive values (boolean, number, string, null) into
- * a single change containing only the final value.
- *
- * Example: If a user toggles a folder's open state 100 times while offline,
- * this collapses those 100 changes into just 1 change with the final state.
- *
- * Safety guarantees:
- * - Only collapses single-op changes (multi-op changes are atomic, preserve intent)
- * - Only collapses "replace" operations (not add, remove, move)
- * - Only collapses primitive values (not objects/arrays)
- * - Detects path invalidation from structural changes (remove, array shifts, move)
- * - Respects the submission bookmark to never collapse already-submitted changes
- *
- * @param changes Array of pending changes to potentially collapse
- * @param afterRev Optional revision bookmark - changes at or before this rev are not collapsed
- *                 (they may have been partially submitted to the server)
- * @returns Collapsed array of changes, maintaining correct ordering
- */
-declare function collapsePendingChanges(changes: Change[], afterRev?: number): Change[];
-
-export { collapsePendingChanges };

package/dist/algorithms/client/collapsePendingChanges.js

@@ -1,78 +0,0 @@
-import "../../chunk-IZ2YBCUP.js";
-function collapsePendingChanges(changes, afterRev) {
-  if (changes.length <= 1) {
-    return changes;
-  }
-  const pathState = /* @__PURE__ */ new Map();
-  const outputSlots = new Array(changes.length).fill(null);
-  for (let i = 0; i < changes.length; i++) {
-    const change = changes[i];
-    if (afterRev !== void 0 && change.rev !== void 0 && change.rev <= afterRev) {
-      outputSlots[i] = change;
-      continue;
-    }
-    updatePathInvalidations(change, pathState);
-    if (!isCollapsibleChange(change)) {
-      outputSlots[i] = change;
-      continue;
-    }
-    const path = change.ops[0].path;
-    const existing = pathState.get(path);
-    if (existing) {
-      outputSlots[existing.lastIndex] = null;
-    }
-    pathState.set(path, { lastChange: change, lastIndex: i });
-    outputSlots[i] = change;
-  }
-  return outputSlots.filter((c) => c !== null);
-}
-function isCollapsibleChange(change) {
-  if (change.ops.length !== 1) {
-    return false;
-  }
-  const op = change.ops[0];
-  if (op.op !== "replace") {
-    return false;
-  }
-  return isPrimitiveValue(op.value);
-}
-function isPrimitiveValue(value) {
-  if (value === null) return true;
-  const type = typeof value;
-  return type === "boolean" || type === "number" || type === "string";
-}
-function updatePathInvalidations(change, pathState) {
-  for (const op of change.ops) {
-    if (op.op === "remove" || op.op === "move") {
-      invalidatePathAndChildren(op.path, pathState);
-      if (op.op === "move" && "from" in op) {
-        invalidatePathAndChildren(op.from, pathState);
-      }
-    }
-    if (op.op === "add" || op.op === "remove") {
-      invalidateShiftedArrayPaths(op.path, pathState);
-    }
-  }
-}
-function invalidatePathAndChildren(opPath, pathState) {
-  for (const trackedPath of pathState.keys()) {
-    if (trackedPath === opPath || trackedPath.startsWith(opPath + "/")) {
-      pathState.delete(trackedPath);
-    }
-  }
-}
-function invalidateShiftedArrayPaths(opPath, pathState) {
-  const segments = opPath.split("/");
-  const lastSegment = segments[segments.length - 1];
-  if (/^\d+$/.test(lastSegment)) {
-    const arrayPath = segments.slice(0, -1).join("/");
-    for (const trackedPath of pathState.keys()) {
-      if (trackedPath.startsWith(arrayPath + "/")) {
-        pathState.delete(trackedPath);
-      }
-    }
-  }
-}
-export {
-  collapsePendingChanges
-};

package/dist/algorithms/client/makeChange.d.ts

@@ -1,9 +0,0 @@
-import { PatchesSnapshot, ChangeMutator, Change } from '../../types.js';
-import { SizeCalculator } from '../shared/changeBatching.js';
-import '../../json-patch/JSONPatch.js';
-import '@dabble/delta';
-import '../../json-patch/types.js';
-
-declare function makeChange<T = any>(snapshot: PatchesSnapshot<T>, mutator: ChangeMutator<T>, changeMetadata?: Record<string, any>, maxStorageBytes?: number, sizeCalculator?: SizeCalculator): Change[];
-
-export { makeChange };

package/dist/algorithms/client/makeChange.js

@@ -1,29 +0,0 @@
-import "../../chunk-IZ2YBCUP.js";
-import { createChange } from "../../data/change.js";
-import { createJSONPatch } from "../../json-patch/createJSONPatch.js";
-import { breakChanges } from "../shared/changeBatching.js";
-import { createStateFromSnapshot } from "./createStateFromSnapshot.js";
-function makeChange(snapshot, mutator, changeMetadata, maxStorageBytes, sizeCalculator) {
-  const pendingChanges = snapshot.changes;
-  const pendingRev = pendingChanges[pendingChanges.length - 1]?.rev ?? snapshot.rev;
-  const state = createStateFromSnapshot(snapshot);
-  const patch = createJSONPatch(mutator);
-  if (patch.ops.length === 0) {
-    return [];
-  }
-  const rev = pendingRev + 1;
-  let newChangesArray = [createChange(snapshot.rev, rev, patch.ops, changeMetadata)];
-  try {
-    patch.apply(state);
-  } catch (error) {
-    console.error("Failed to apply change to state during makeChange:", error);
-    throw new Error(`Failed to apply change to state during makeChange: ${error}`);
-  }
-  if (maxStorageBytes) {
-    newChangesArray = breakChanges(newChangesArray, maxStorageBytes, sizeCalculator);
-  }
-  return newChangesArray;
-}
-export {
-  makeChange
-};

package/dist/algorithms/server/commitChanges.d.ts

@@ -1,19 +0,0 @@
-import { PatchesStoreBackend } from '../../server/types.js';
-import { ChangeInput, CommitChangesOptions, Change } from '../../types.js';
-import '../../json-patch/JSONPatch.js';
-import '@dabble/delta';
-import '../../json-patch/types.js';
-
-/**
- * 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 originClientId - The ID of the client that initiated the commit.
- * @param options - Optional commit settings.
- * @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
- */
-declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxStorageBytes?: number): Promise<[Change[], Change[]]>;
-
-export { CommitChangesOptions, commitChanges };