@dabble/patches 0.6.0 → 0.7.0

package/dist/BaseDoc-DkP3tUhT.d.ts

@@ -0,0 +1,206 @@
+import { Signal, Unsubscriber } from './event-signal.js';
+import { JSONPatchOp } from './json-patch/types.js';
+import { Change, PatchesSnapshot, SyncingState, ChangeMutator } from './types.js';
+
+/**
+ * OT (Operational Transformation) document implementation.
+ * Uses a snapshot-based approach with revision tracking and rebasing
+ * for handling concurrent edits.
+ *
+ * The `change()` method (inherited from BaseDoc) captures ops and emits them
+ * via `onChange` - it does NOT apply locally. The OTStrategy handles packaging
+ * ops into Changes, persisting them, and calling `applyChanges()` to update state.
+ *
+ * ## State Model
+ * - `_committedState`: Base state from server (at `_committedRev`)
+ * - `_pendingChanges`: Local changes not yet committed by server
+ * - `_state` (from BaseDoc): Live state = committedState + pendingChanges applied
+ *
+ * ## Wire Efficiency
+ * For Worker-Tab communication, only changes are sent over the wire (not full state).
+ * The unified `applyChanges()` method handles both local and server changes.
+ */
+declare class OTDoc<T extends object = object> extends BaseDoc<T> {
+    /** Base state from the server at the committed revision. */
+    protected _committedState: T;
+    /** Last committed revision number from the server. */
+    protected _committedRev: number;
+    /** Local changes not yet committed by server. */
+    protected _pendingChanges: Change[];
+    /**
+     * Creates an instance of OTDoc.
+     * @param id The unique identifier for this document.
+     * @param snapshot Optional snapshot to initialize from (state, rev, pending changes).
+     */
+    constructor(id: string, snapshot?: PatchesSnapshot<T>);
+    /** Last committed revision number from the server. */
+    get committedRev(): number;
+    /** Are there local changes that haven't been committed yet? */
+    get hasPending(): boolean;
+    /**
+     * Returns the pending changes for this document.
+     * @returns The pending changes.
+     */
+    getPendingChanges(): Change[];
+    /**
+     * Imports document state from a snapshot (e.g., for recovery when out of sync).
+     * Resets state and treats all imported changes as pending.
+     */
+    import(snapshot: PatchesSnapshot<T>): void;
+    /**
+     * Unified entry point for applying changes.
+     * Used for Worker→Tab communication where only changes are sent over the wire.
+     *
+     * The method distinguishes between committed and pending changes using `committedAt`:
+     * - `committedAt > 0`: Server-committed change (apply to committed state)
+     * - `committedAt === 0`: Pending local change (append to pending)
+     *
+     * For server changes, all committed changes come first, followed by rebased pending.
+     *
+     * @param changes Array of changes to apply
+     */
+    applyChanges(changes: Change[]): void;
+    /**
+     * Returns the document snapshot for serialization.
+     */
+    toJSON(): PatchesSnapshot<T>;
+}
+
+/**
+ * Options for creating a PatchesDoc instance
+ */
+interface PatchesDocOptions {
+    /**
+     * Maximum size in bytes for a single change's storage representation.
+     * Changes exceeding this will be split. Used for backends with row size limits.
+     */
+    maxStorageBytes?: number;
+    /**
+     * Custom size calculator for storage limit checks.
+     * Import from '@dabble/patches/compression' for actual compression measurement,
+     * or provide your own function (e.g., ratio estimate).
+     *
+     * @example
+     * import { compressedSizeBase64 } from '@dabble/patches/compression';
+     * { sizeCalculator: compressedSizeBase64, maxStorageBytes: 1_000_000 }
+     */
+    sizeCalculator?: (data: unknown) => number;
+}
+/**
+ * Interface for a document synchronized using JSON patches.
+ *
+ * This is the app-facing interface. The doc captures user changes as JSON Patch
+ * ops and emits them via onChange. The strategy handles packaging ops into Changes,
+ * persisting them, and updating the doc's state.
+ *
+ * This interface is implemented by both OTDoc (Operational Transformation)
+ * and LWWDoc (Last-Write-Wins) implementations via BaseDoc.
+ *
+ * Internal methods (updateSyncing, applyChanges, import) are on BaseDoc, not this interface.
+ */
+interface PatchesDoc<T extends object = object> {
+    /** The unique identifier for this document. */
+    readonly id: string;
+    /** Current local state (committed + pending merged). */
+    readonly state: T;
+    /** Last committed revision number from the server. */
+    readonly committedRev: number;
+    /** Are there local changes that haven't been committed yet? */
+    readonly hasPending: boolean;
+    /** Are we currently syncing this document? */
+    readonly syncing: SyncingState;
+    /**
+     * Subscribe to be notified when the user makes local changes.
+     * Emits the JSON Patch ops captured from the change() call.
+     * The strategy handles packaging these into Changes.
+     */
+    readonly onChange: Signal<(ops: JSONPatchOp[]) => void>;
+    /** Subscribe to be notified whenever state changes from any source. */
+    readonly onUpdate: Signal<(newState: T) => void>;
+    /** Subscribe to be notified when syncing state changes. */
+    readonly onSyncing: Signal<(newSyncing: SyncingState) => void>;
+    /** Subscribe to be notified whenever the state changes (calls immediately with current state). */
+    subscribe(onUpdate: (newValue: T) => void): Unsubscriber;
+    /**
+     * Captures an update to the document, emitting JSON Patch ops via onChange.
+     * Does NOT apply locally - the strategy handles state updates.
+     * @param mutator Function that uses JSONPatch methods with type-safe paths.
+     */
+    change(mutator: ChangeMutator<T>): void;
+}
+
+/**
+ * Abstract base class for document implementations.
+ * Contains shared state and methods used by both OTDoc and LWWDoc.
+ *
+ * The `change()` method captures ops and emits them via `onChange` - it does NOT
+ * apply locally. The strategy handles packaging ops, persisting them, and updating
+ * the doc's state via `applyChanges()`.
+ *
+ * Internal methods (updateSyncing, applyChanges, import) are on this class but not
+ * on the PatchesDoc interface, as they're only used by Strategy and PatchesSync.
+ */
+declare abstract class BaseDoc<T extends object = object> implements PatchesDoc<T> {
+    protected _id: string;
+    protected _state: T;
+    protected _syncing: SyncingState;
+    /**
+     * Subscribe to be notified when the user makes local changes.
+     * Emits the JSON Patch ops captured from the change() call.
+     * The strategy handles packaging these into Changes.
+     */
+    readonly onChange: Signal<(ops: JSONPatchOp[]) => void>;
+    /** Subscribe to be notified whenever state changes from any source. */
+    readonly onUpdate: Signal<(newState: T) => void>;
+    /** Subscribe to be notified when syncing state changes. */
+    readonly onSyncing: Signal<(newSyncing: SyncingState) => void>;
+    /**
+     * Creates an instance of BaseDoc.
+     * @param id The unique identifier for this document.
+     * @param initialState Optional initial state.
+     */
+    constructor(id: string, initialState?: T);
+    /** The unique identifier for this document. */
+    get id(): string;
+    /** Current local state (committed + pending merged). */
+    get state(): T;
+    /** Are we currently syncing this document? */
+    get syncing(): SyncingState;
+    /** Last committed revision number from the server. */
+    abstract get committedRev(): number;
+    /** Are there local changes that haven't been committed yet? */
+    abstract get hasPending(): boolean;
+    /** Subscribe to be notified whenever the state changes (calls immediately with current state). */
+    subscribe(onUpdate: (newValue: T) => void): Unsubscriber;
+    /**
+     * Captures an update to the document, emitting JSON Patch ops via onChange.
+     * Does NOT apply locally - the strategy handles state updates via applyChanges.
+     * @param mutator Function that uses JSONPatch methods with type-safe paths.
+     */
+    change(mutator: ChangeMutator<T>): void;
+    /**
+     * Updates the syncing state of the document.
+     * Called by PatchesSync - not part of the app-facing PatchesDoc interface.
+     * @param newSyncing The new syncing state.
+     */
+    updateSyncing(newSyncing: SyncingState): void;
+    /**
+     * Applies changes to the document state.
+     * Called by Strategy for local changes and broadcasts - not part of PatchesDoc interface.
+     *
+     * For OT: Distinguishes committed (committedAt > 0) vs pending (committedAt === 0) changes.
+     * For LWW: Applies all ops from changes and updates metadata.
+     *
+     * @param changes Array of changes to apply.
+     */
+    abstract applyChanges(changes: Change[]): void;
+    /**
+     * Imports a full snapshot, resetting doc state.
+     * Used for recovery when doc gets out of sync - not part of PatchesDoc interface.
+     *
+     * @param snapshot The snapshot to import.
+     */
+    abstract import(snapshot: PatchesSnapshot<T>): void;
+}
+
+export { BaseDoc as B, OTDoc as O, type PatchesDocOptions as P, type PatchesDoc as a };

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

@@ -5,6 +5,13 @@ import '../../json-patch/types.js';
 
 /**
  * Applies incoming changes from the server that were *not* initiated by this client.
+ *
+ * Changes must normally be sequential (each change's rev = previous rev + 1). However,
+ * a root-level replace (`{ op: 'replace', path: '' }`) is allowed to skip revisions.
+ * This occurs when an offline-first client syncs with an existing document - the server
+ * returns a synthetic catchup change containing the full current state instead of
+ * returning potentially thousands of individual historical changes.
+ *
  * @param snapshot The current state of the document (the state without pending changes applied) and the pending changes.
  * @param committedChangesFromServer An array of sequential changes from the server.
  * @returns The new committed state, the new committed revision, and the new/rebased pending changes.

package/dist/algorithms/client/applyCommittedChanges.js

@@ -10,9 +10,12 @@ function applyCommittedChanges(snapshot, committedChangesFromServer) {
   const firstChange = newServerChanges[0];
   const lastChange = newServerChanges[newServerChanges.length - 1];
   if (firstChange.rev !== rev + 1) {
-    throw new Error(
-      `Missing changes from the server. Expected rev ${rev + 1}, got ${firstChange.rev}. Request changes since ${rev}.`
-    );
+    const isRootReplaceCatchup = firstChange.ops.length === 1 && firstChange.ops[0].op === "replace" && firstChange.ops[0].path === "";
+    if (!isRootReplaceCatchup) {
+      throw new Error(
+        `Missing changes from the server. Expected rev ${rev + 1}, got ${firstChange.rev}. Request changes since ${rev}.`
+      );
+    }
   }
   try {
     state = applyChanges(state, newServerChanges);

package/dist/algorithms/lww/consolidateOps.d.ts

@@ -0,0 +1,40 @@
+import { JSONPatchOp } from '../../json-patch/types.js';
+
+/**
+ * Combiner for consolidating same-type ops on the same path.
+ */
+type Combiner = {
+    apply: (a: any, b: any) => any;
+    combine: (a: any, b: any) => any;
+};
+/**
+ * Combinable operations - ops that can be merged rather than replaced.
+ * Exported for use by mergeServerWithLocal.
+ */
+declare const combinableOps: Record<string, Combiner>;
+/**
+ * Consolidates two ops on the same path.
+ * - @inc: sums values
+ * - @bit: combines bitmasks
+ * - @max: keeps maximum
+ * - @min: keeps minimum
+ * - replace/remove/other: incoming wins
+ *
+ * Returns null if existing wins (incoming should be dropped).
+ */
+declare function consolidateFieldOp(existing: JSONPatchOp, incoming: JSONPatchOp): JSONPatchOp | null;
+/**
+ * Consolidates new ops with existing pending ops.
+ * Returns ops to save and child paths to delete (when parent overwrites).
+ */
+declare function consolidateOps(existingOps: JSONPatchOp[], newOps: JSONPatchOp[]): {
+    opsToSave: JSONPatchOp[];
+    pathsToDelete: string[];
+    opsToReturn: JSONPatchOp[];
+};
+/**
+ * Any delta ops that aren't combined in consolidateOps need to be converted to replace ops.
+ */
+declare function convertDeltaOps(ops: JSONPatchOp[]): JSONPatchOp[];
+
+export { type Combiner, combinableOps, consolidateFieldOp, consolidateOps, convertDeltaOps };

package/dist/algorithms/lww/consolidateOps.js

@@ -0,0 +1,103 @@
+import "../../chunk-IZ2YBCUP.js";
+import { applyBitmask, combineBitmasks } from "../../json-patch/ops/bitmask.js";
+const combinableOps = {
+  "@inc": {
+    apply: (a, b) => a + b,
+    combine: (a, b) => a + b
+  },
+  "@bit": {
+    apply: applyBitmask,
+    combine: combineBitmasks
+  },
+  "@max": {
+    apply: (a, b) => a > b ? a : b,
+    combine: (a, b) => a > b ? a : b
+  },
+  "@min": {
+    apply: (a, b) => a < b ? a : b,
+    combine: (a, b) => a < b ? a : b
+  }
+};
+function isExistingNewer(existingTs, incomingTs) {
+  if (incomingTs === void 0) return false;
+  if (existingTs === void 0) return true;
+  return existingTs > incomingTs;
+}
+function consolidateFieldOp(existing, incoming) {
+  const combiner = combinableOps[incoming.op];
+  if (combiner) {
+    const op = existing.op === incoming.op ? incoming.op : existing.op;
+    const value = existing.op === incoming.op ? combiner.combine(existing.value ?? 0, incoming.value ?? 0) : combiner.apply(existing.value ?? 0, incoming.value ?? 0);
+    if (value === existing.value) {
+      return null;
+    }
+    return { ...incoming, op, value };
+  }
+  if (isExistingNewer(existing.ts, incoming.ts)) {
+    return null;
+  }
+  return incoming;
+}
+function consolidateOps(existingOps, newOps) {
+  const opsToSave = [];
+  const pathsToDelete = /* @__PURE__ */ new Set();
+  const existingByPath = new Map(existingOps.map((op) => [op.path, op]));
+  const opsToReturnMap = /* @__PURE__ */ new Map();
+  for (const newOp of newOps) {
+    const existing = existingByPath.get(newOp.path);
+    const fix = parentFixes(newOp.path, existingByPath);
+    if (!Array.isArray(fix)) {
+      if (!opsToReturnMap.has(fix.path)) opsToReturnMap.set(fix.path, fix);
+      continue;
+    } else if (fix.length > 0) {
+      fix.forEach((path) => pathsToDelete.add(path));
+    }
+    if (existing) {
+      const consolidated = consolidateFieldOp(existing, newOp);
+      if (consolidated !== null) {
+        opsToSave.push(consolidated);
+      }
+    } else {
+      for (const existingPath of existingByPath.keys()) {
+        if (existingPath.startsWith(newOp.path + "/")) {
+          pathsToDelete.add(existingPath);
+        }
+      }
+      opsToSave.push(newOp);
+    }
+  }
+  return { opsToSave, pathsToDelete: Array.from(pathsToDelete), opsToReturn: Array.from(opsToReturnMap.values()) };
+}
+function convertDeltaOps(ops) {
+  return ops.map((op) => {
+    const combiner = combinableOps[op.op];
+    const value = typeof op.value === "string" ? "" : 0;
+    if (combiner) return { ...op, op: "replace", value: combiner.apply(value, op.value) };
+    return { ...op, op: "replace", value: op.value };
+  });
+}
+function parentFixes(path, existing) {
+  let parent = path;
+  const pathsToDelete = [];
+  while (parent.lastIndexOf("/") > 0) {
+    parent = parent.substring(0, parent.lastIndexOf("/"));
+    const parentOp = existing.get(parent);
+    if (parentOp) {
+      if (parentOp.value === void 0 || parentOp.op === "remove") {
+        pathsToDelete.push(parent);
+      } else if (!isObject(parentOp.value)) {
+        return parentOp;
+      }
+    }
+  }
+  return pathsToDelete;
+}
+function isObject(value) {
+  return value !== null && typeof value === "object";
+}
+export {
+  combinableOps,
+  consolidateFieldOp,
+  consolidateOps,
+  convertDeltaOps
+};

package/dist/algorithms/lww/index.d.ts

@@ -0,0 +1,2 @@
+export { Combiner, combinableOps, consolidateFieldOp, consolidateOps, convertDeltaOps } from './consolidateOps.js';
+import '../../json-patch/types.js';

package/dist/algorithms/lww/index.js

@@ -0,0 +1 @@
+export * from "./consolidateOps.js";

package/dist/algorithms/lww/mergeServerWithLocal.d.ts

@@ -0,0 +1,22 @@
+import { JSONPatchOp } from '../../json-patch/types.js';
+import { Change } from '../../types.js';
+import '../../json-patch/JSONPatch.js';
+import '@dabble/delta';
+
+/**
+ * Merges server changes with local ops (sending + pending) for doc display.
+ *
+ * For paths that server touched:
+ * - If local has a delta op (@inc, @bit, @max, @min), apply it to server value
+ * - If local has a non-delta op, keep server value (already committed)
+ *
+ * For paths server didn't touch:
+ * - Keep local ops so they still apply to doc state
+ *
+ * @param serverChanges Changes received from server
+ * @param localOps Local ops (sendingChange.ops + pendingOps) from the store
+ * @returns Changes to apply to the doc
+ */
+declare function mergeServerWithLocal(serverChanges: Change[], localOps: JSONPatchOp[]): Change[];
+
+export { mergeServerWithLocal };

package/dist/algorithms/lww/mergeServerWithLocal.js

@@ -0,0 +1,32 @@
+import "../../chunk-IZ2YBCUP.js";
+import { combinableOps } from "./consolidateOps.js";
+function mergeServerWithLocal(serverChanges, localOps) {
+  if (localOps.length === 0) return serverChanges;
+  const localByPath = new Map(localOps.map((op) => [op.path, op]));
+  const serverPaths = /* @__PURE__ */ new Set();
+  const mergedChanges = serverChanges.map((change) => {
+    const mergedOps = change.ops.map((serverOp) => {
+      serverPaths.add(serverOp.path);
+      const local = localByPath.get(serverOp.path);
+      if (!local) return serverOp;
+      const combiner = combinableOps[local.op];
+      if (!combiner) return serverOp;
+      const mergedValue = combiner.apply(serverOp.value ?? 0, local.value ?? 0);
+      const mergedOp = serverOp.op === "remove" ? "replace" : serverOp.op;
+      return { ...serverOp, op: mergedOp, value: mergedValue };
+    });
+    return { ...change, ops: mergedOps };
+  });
+  const untouchedLocalOps = localOps.filter((op) => !serverPaths.has(op.path));
+  if (untouchedLocalOps.length > 0 && mergedChanges.length > 0) {
+    const lastChange = mergedChanges[mergedChanges.length - 1];
+    mergedChanges[mergedChanges.length - 1] = {
+      ...lastChange,
+      ops: [...lastChange.ops, ...untouchedLocalOps]
+    };
+  }
+  return mergedChanges;
+}
+export {
+  mergeServerWithLocal
+};

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

@@ -1,19 +1,43 @@
+import { CommitResult } from '../../server/PatchesServer.js';
 import { PatchesStoreBackend } from '../../server/types.js';
-import { ChangeInput, CommitChangesOptions, Change } from '../../types.js';
+import { ChangeInput, CommitChangesOptions } from '../../types.js';
+import '../../net/protocol/JSONRPCServer.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 '../../net/protocol/types.js';
 
 /**
  * Commits a set of changes to a document, applying operational transformation as needed.
+ *
+ * ## Offline-First Catchup Optimization
+ *
+ * When a client that has never synced (baseRev: 0) commits changes to an existing document,
+ * the server applies an optimization to avoid expensive transformation through potentially
+ * thousands of historical changes. Instead of:
+ *
+ * 1. Transforming the client's changes against all N existing changes
+ * 2. Returning all N changes as catchup for the client to apply
+ *
+ * The server:
+ * 1. Rebases the client's baseRev to the current revision (treats changes as if made at head)
+ * 2. Returns a synthetic catchup change with `{ op: 'replace', path: '', value: currentState }`
+ *
+ * This single root-level replace gives the client the full current document state efficiently.
+ * The client's `applyCommittedChanges` recognizes this pattern and allows the revision jump.
+ *
+ * @param store - The backend store for persistence.
  * @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 sessionTimeoutMillis - Timeout for session-based versioning.
  * @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
+ * @param maxStorageBytes - Optional max bytes per change for storage limits.
+ * @returns A CommitResult containing:
+ *   - catchupChanges: Changes the client missed (or a synthetic root-replace for offline-first clients)
+ *   - newChanges: The client's changes after transformation
  */
-declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxStorageBytes?: number): Promise<[Change[], Change[]]>;
+declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxStorageBytes?: number): Promise<CommitResult>;
 
-export { CommitChangesOptions, commitChanges };
+export { CommitChangesOptions, CommitResult, commitChanges };

package/dist/algorithms/server/commitChanges.js

@@ -1,4 +1,5 @@
 import "../../chunk-IZ2YBCUP.js";
+import { createId } from "crypto-id";
 import { filterSoftWritesAgainstState } from "../../json-patch/utils/softWrites.js";
 import { applyChanges } from "../shared/applyChanges.js";
 import { createVersion } from "./createVersion.js";
@@ -8,7 +9,7 @@ import { handleOfflineSessionsAndBatches } from "./handleOfflineSessionsAndBatch
 import { transformIncomingChanges } from "./transformIncomingChanges.js";
 async function commitChanges(store, docId, changes, sessionTimeoutMillis, options, maxStorageBytes) {
   if (changes.length === 0) {
-    return [[], []];
+    return { catchupChanges: [], newChanges: [] };
   }
   const batchId = changes[0].batchId;
   const { state: initialState, rev: initialRev, changes: currentChanges } = await getSnapshotAtRevision(store, docId);
@@ -16,9 +17,12 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
   const currentRev = currentChanges.at(-1)?.rev ?? initialRev;
   let baseRev = changes[0].baseRev ?? currentRev;
   const batchedContinuation = batchId && changes[0].rev > 1;
+  const clientBaseRev = changes[0].baseRev ?? currentRev;
+  let needsSyntheticCatchup = false;
   if (changes[0].baseRev === 0 && currentRev > 0 && !batchedContinuation) {
     const hasRootOp = changes.some((c) => c.ops.some((op) => op.path === ""));
     if (!hasRootOp) {
+      needsSyntheticCatchup = true;
       baseRev = currentRev;
       changes = changes.filter((c) => {
         c.baseRev = baseRev;
@@ -52,7 +56,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
     );
   }
   const lastChange = currentChanges[currentChanges.length - 1];
-  const compareTime = options?.historicalImport ? changes[0].createdAt : serverNow;
+  const compareTime = options?.historicalImport ? changes[0].createdAt ?? serverNow : serverNow;
   if (lastChange && compareTime - lastChange.createdAt > sessionTimeoutMillis) {
     await createVersion(store, docId, currentState, currentChanges);
   }
@@ -63,7 +67,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
   const committedIds = new Set(committedChanges.map((c) => c.id));
   let incomingChanges = changes.filter((c) => !committedIds.has(c.id));
   if (incomingChanges.length === 0) {
-    return [committedChanges, []];
+    return { catchupChanges: committedChanges, newChanges: [] };
   }
   const isOfflineTimestamp = serverNow - incomingChanges[0].createdAt > sessionTimeoutMillis;
   if (isOfflineTimestamp || batchId) {
@@ -83,7 +87,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
     );
     if (canFastForward) {
       await store.saveChanges(docId, incomingChanges);
-      return [[], incomingChanges];
+      return { catchupChanges: [], newChanges: incomingChanges };
     }
   }
   const stateAtBaseRev = (await getStateAtRevision(store, docId, baseRev)).state;
@@ -97,7 +101,18 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
   if (transformedChanges.length > 0) {
     await store.saveChanges(docId, transformedChanges);
   }
-  return [committedChanges, transformedChanges];
+  if (needsSyntheticCatchup && clientBaseRev === 0) {
+    const syntheticCatchup = {
+      id: `catchup-${createId(8)}`,
+      baseRev: clientBaseRev,
+      rev: currentRev,
+      ops: [{ op: "replace", path: "", value: currentState }],
+      createdAt: serverNow,
+      committedAt: serverNow
+    };
+    return { catchupChanges: [syntheticCatchup], newChanges: transformedChanges };
+  }
+  return { catchupChanges: committedChanges, newChanges: transformedChanges };
 }
 export {
   commitChanges

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

@@ -1,8 +1,8 @@
 import { PatchesStoreBackend } from '../../server/types.js';
 import { Change, EditableVersionMetadata, VersionMetadata } from '../../types.js';
+import '../../json-patch/types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../../json-patch/types.js';
 
 /**
  * Creates a new version snapshot of a document's state from changes.

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

@@ -1,8 +1,8 @@
 import { PatchesStoreBackend } from '../../server/types.js';
 import { PatchesSnapshot } from '../../types.js';
+import '../../json-patch/types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../../json-patch/types.js';
 
 /**
  * Retrieves the document state of the version before the given revision and changes after up to that revision or all

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

@@ -1,8 +1,8 @@
 import { PatchesStoreBackend } from '../../server/types.js';
 import { PatchesState } from '../../types.js';
+import '../../json-patch/types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../../json-patch/types.js';
 
 /**
  * Gets the state at a specific revision.

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

@@ -1,8 +1,8 @@
 import { PatchesStoreBackend } from '../../server/types.js';
 import { Change } from '../../types.js';
+import '../../json-patch/types.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
-import '../../json-patch/types.js';
 
 /**
  * Handles offline/large batch versioning logic for multi-batch uploads.

package/dist/client/BaseDoc.d.ts

@@ -0,0 +1,6 @@
+import '../event-signal.js';
+import '../json-patch/types.js';
+import '../types.js';
+export { B as BaseDoc } from '../BaseDoc-DkP3tUhT.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';