@dabble/patches 0.7.21 → 0.7.23

package/dist/algorithms/lww/consolidateOps.js

@@ -60,6 +60,8 @@ function consolidateOps(existingOps, newOps) {
       const consolidated = consolidateFieldOp(existing, newOp);
       if (consolidated !== null) {
         opsToSave.push(consolidated);
+      } else if (!isSoftOp(newOp) && !combinableOps[newOp.op]) {
+        if (!opsToReturnMap.has(existing.path)) opsToReturnMap.set(existing.path, existing);
       }
     } else {
       if (isSoftOp(newOp)) {

package/dist/algorithms/ot/client/applyCommittedChanges.js

@@ -17,13 +17,7 @@ function applyCommittedChanges(snapshot, committedChangesFromServer) {
       );
     }
   }
-  try {
-    state = applyChanges(state, newServerChanges);
-  } catch (error) {
-    console.error("Failed to apply server changes to committed state:", error);
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    throw new Error(`Critical sync error applying server changes: ${errorMessage}`);
-  }
+  state = applyChanges(state, newServerChanges);
   rev = lastChange.rev;
   if (changes && changes.length > 0) {
     changes = rebaseChanges(newServerChanges, changes);

package/dist/algorithms/ot/server/buildVersionState.d.ts

@@ -0,0 +1,51 @@
+import { OTStoreBackend } from '../../../server/types.js';
+import { VersionMetadata, Change, PatchesState } from '../../../types.js';
+import '../../../json-patch/types.js';
+import '../../../json-patch/JSONPatch.js';
+import '@dabble/delta';
+
+/**
+ * Computes the document state at `version.startRev - 1`: the state just before
+ * this version's changes begin.
+ *
+ * Uses `version.parentId` (via `store.loadVersion`) when available for
+ * an efficient cached lookup. After loading the parent state, bridges any gap
+ * between the parent's `endRev` and `version.startRev` by applying intermediate
+ * changes. When no parentId exists (first version ever), builds from scratch.
+ *
+ * @param store - The store backend.
+ * @param docId - The document ID.
+ * @param version - The version whose pre-state to compute.
+ * @returns `{ state, rev }` at `version.startRev - 1`.
+ */
+declare function getBaseStateBeforeVersion(store: OTStoreBackend, docId: string, version: VersionMetadata): Promise<PatchesState>;
+/**
+ * Returns the document state immediately before a version's changes begin,
+ * as a ReadableStream.
+ *
+ * Fast path: when the parent state needs no modification (no gap between the
+ * parent's `endRev` and `version.startRev`), the raw bytes are streamed
+ * directly from the store without parsing.
+ *
+ * Slow path: when there is a gap, the parent state is parsed, intermediate
+ * changes are applied, and the result is re-serialized.
+ *
+ * @param store - The store backend.
+ * @param docId - The document ID.
+ * @param version - The version whose pre-state to compute.
+ * @returns A ReadableStream of the JSON state at `version.startRev - 1`.
+ */
+declare function getStateBeforeVersionAsStream(store: OTStoreBackend, docId: string, version: VersionMetadata): Promise<ReadableStream<string>>;
+/**
+ * Builds the document state for a version by computing the base state
+ * (via `getBaseStateBeforeVersion`) and applying the version's changes on top.
+ *
+ * @param store - The store backend to load previous version state from.
+ * @param docId - The document ID.
+ * @param version - The version metadata.
+ * @param changes - The changes included in this version.
+ * @returns The built state for the version.
+ */
+declare function buildVersionState(store: OTStoreBackend, docId: string, version: VersionMetadata, changes: Change[]): Promise<any>;
+
+export { buildVersionState, getBaseStateBeforeVersion, getStateBeforeVersionAsStream };

package/dist/algorithms/ot/server/buildVersionState.js

@@ -0,0 +1,67 @@
+import "../../../chunk-IZ2YBCUP.js";
+import { jsonReadable, parseVersionState } from "../../../server/jsonReadable.js";
+import { applyChanges } from "../shared/applyChanges.js";
+async function getBaseStateBeforeVersion(store, docId, version) {
+  let baseState = null;
+  let baseRev = 0;
+  if (version.parentId) {
+    const [rawState, parentMeta] = await Promise.all([
+      store.loadVersionState(docId, version.parentId),
+      store.loadVersion(docId, version.parentId)
+    ]);
+    if (parentMeta && rawState !== void 0) {
+      baseState = await parseVersionState(rawState);
+      baseRev = parentMeta.endRev;
+    }
+  }
+  if (baseRev < version.startRev - 1) {
+    const gapChanges = await store.listChanges(docId, {
+      startAfter: baseRev,
+      endBefore: version.startRev
+    });
+    if (gapChanges.length > 0) {
+      baseState = applyChanges(baseState, gapChanges);
+    }
+  }
+  return { state: baseState, rev: version.startRev - 1 };
+}
+async function getStateBeforeVersionAsStream(store, docId, version) {
+  if (version.parentId) {
+    const [rawState, parentMeta] = await Promise.all([
+      store.loadVersionState(docId, version.parentId),
+      store.loadVersion(docId, version.parentId)
+    ]);
+    if (parentMeta && rawState !== void 0) {
+      const baseRev = parentMeta.endRev;
+      if (baseRev >= version.startRev - 1) {
+        return typeof rawState === "string" ? jsonReadable(rawState) : rawState;
+      }
+      const baseState = await parseVersionState(rawState);
+      const gapChanges = await store.listChanges(docId, {
+        startAfter: baseRev,
+        endBefore: version.startRev
+      });
+      const state = gapChanges.length > 0 ? applyChanges(baseState, gapChanges) : baseState;
+      return jsonReadable(JSON.stringify(state));
+    }
+  }
+  if (version.startRev > 1) {
+    const gapChanges = await store.listChanges(docId, {
+      startAfter: 0,
+      endBefore: version.startRev
+    });
+    if (gapChanges.length > 0) {
+      return jsonReadable(JSON.stringify(applyChanges(null, gapChanges)));
+    }
+  }
+  return jsonReadable("null");
+}
+async function buildVersionState(store, docId, version, changes) {
+  const { state: baseState } = await getBaseStateBeforeVersion(store, docId, version);
+  return applyChanges(baseState, changes);
+}
+export {
+  buildVersionState,
+  getBaseStateBeforeVersion,
+  getStateBeforeVersionAsStream
+};

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

@@ -12,32 +12,34 @@ import '../../../net/protocol/types.js';
 /**
  * Commits a set of changes to a document, applying operational transformation as needed.
  *
- * ## Offline-First Catchup Optimization
+ * ## Stateless Design
  *
- * 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:
+ * This function never loads or builds document state. It uses `getCurrentRev` to get the
+ * current revision and transforms changes against committed changes only (no state parameter
+ * passed to transformPatch). Bad ops become noops during transformation.
  *
- * 1. Transforming the client's changes against all N existing changes
- * 2. Returning all N changes as catchup for the client to apply
+ * ## Version Creation
  *
- * 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 }`
+ * Versions are created (metadata + changes saved to store) when session timeouts are
+ * detected. After saving, `onVersionCreated` is emitted so subscribers can build and
+ * persist state out of band.
  *
- * 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.
+ * ## Conflict Retry
+ *
+ * When a store's `saveChanges` throws `RevConflictError` (e.g. because another server
+ * instance committed the same revision), the function retries: re-reads `currentRev`,
+ * re-fetches committed changes, re-transforms, and re-saves. The retry naturally resolves
+ * because the fresh `currentRev` includes the conflicting commit.
  *
  * @param store - The backend store for persistence.
  * @param docId - The ID of the document.
  * @param changes - The changes to commit.
  * @param sessionTimeoutMillis - Timeout for session-based versioning.
  * @param options - Optional commit settings.
- * @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)
+ *   - catchupChanges: Changes the client missed
  *   - newChanges: The client's changes after transformation
  */
-declare function commitChanges(store: OTStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxStorageBytes?: number): Promise<CommitResult>;
+declare function commitChanges(store: OTStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions): Promise<CommitResult>;
 
 export { CommitChangesOptions, CommitResult, commitChanges };

package/dist/algorithms/ot/server/commitChanges.js

@@ -1,34 +1,26 @@
 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";
-import { getSnapshotAtRevision } from "./getSnapshotAtRevision.js";
-import { getStateAtRevision } from "./getStateAtRevision.js";
+import { RevConflictError } from "../../../server/RevConflictError.js";
+import { createVersionAtRev } from "./createVersion.js";
 import { handleOfflineSessionsAndBatches } from "./handleOfflineSessionsAndBatches.js";
 import { transformIncomingChanges } from "./transformIncomingChanges.js";
-async function commitChanges(store, docId, changes, sessionTimeoutMillis, options, maxStorageBytes) {
+const MAX_CONFLICT_RETRIES = 5;
+async function commitChanges(store, docId, changes, sessionTimeoutMillis, options) {
   if (changes.length === 0) {
     return { catchupChanges: [], newChanges: [] };
   }
   const batchId = changes[0].batchId;
-  const { state: initialState, rev: initialRev, changes: currentChanges } = await getSnapshotAtRevision(store, docId);
-  const currentState = applyChanges(initialState, currentChanges);
-  const currentRev = currentChanges.at(-1)?.rev ?? initialRev;
-  let baseRev = changes[0].baseRev ?? currentRev;
+  const initialRev = await store.getCurrentRev(docId);
+  let baseRev = changes[0].baseRev ?? initialRev;
   const batchedContinuation = batchId && changes[0].rev > 1;
-  const clientBaseRev = changes[0].baseRev ?? currentRev;
-  let needsSyntheticCatchup = false;
-  if (changes[0].baseRev === 0 && currentRev > 0 && !batchedContinuation) {
+  let docReloadRequired;
+  if (changes[0].baseRev === 0 && initialRev > 0 && !batchedContinuation) {
     const hasRootOp = changes.some((c) => c.ops.some((op) => op.path === ""));
     if (!hasRootOp) {
-      needsSyntheticCatchup = true;
-      baseRev = currentRev;
-      changes = changes.filter((c) => {
+      docReloadRequired = true;
+      baseRev = initialRev;
+      for (const c of changes) {
         c.baseRev = baseRev;
-        c.ops = filterSoftWritesAgainstState(c.ops, currentState);
-        return c.ops.length > 0;
-      });
+      }
     }
   }
   const serverNow = Date.now();
@@ -45,72 +37,63 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
     }
     c.createdAt = c.createdAt ? Math.min(c.createdAt, serverNow) : serverNow;
   });
-  if (baseRev > currentRev) {
+  if (baseRev > initialRev) {
     throw new Error(
-      `Client baseRev (${baseRev}) is ahead of server revision (${currentRev}) for doc ${docId}. Client needs to reload the document.`
+      `Client baseRev (${baseRev}) is ahead of server revision (${initialRev}) for doc ${docId}. Client needs to reload the document.`
     );
   }
-  if (changes[0].baseRev === 0 && currentRev > 0 && !batchedContinuation && changes[0].ops[0]?.path === "") {
+  if (changes[0].baseRev === 0 && initialRev > 0 && !batchedContinuation && changes[0].ops[0]?.path === "") {
     throw new Error(
-      `Document ${docId} already exists (rev ${currentRev}). Cannot apply root-level replace (path: '') with baseRev 0 - this would overwrite the existing document. Load the existing document first, or use nested paths instead of replacing at root.`
+      `Document ${docId} already exists (rev ${initialRev}). Cannot apply root-level replace (path: '') with baseRev 0 - this would overwrite the existing document. Load the existing document first, or use nested paths instead of replacing at root.`
     );
   }
-  const lastChange = currentChanges[currentChanges.length - 1];
+  const [lastChange] = await store.listChanges(docId, { reverse: true, limit: 1 });
   const compareTime = options?.historicalImport ? changes[0].createdAt ?? serverNow : serverNow;
   if (lastChange && compareTime - lastChange.createdAt > sessionTimeoutMillis) {
-    await createVersion(store, docId, currentState, currentChanges);
-  }
-  const committedChanges = await store.listChanges(docId, {
-    startAfter: baseRev,
-    withoutBatchId: batchId
-  });
-  const committedIds = new Set(committedChanges.map((c) => c.id));
-  let incomingChanges = changes.filter((c) => !committedIds.has(c.id));
-  if (incomingChanges.length === 0) {
-    return { catchupChanges: committedChanges, newChanges: [] };
+    await createVersionAtRev(store, docId, lastChange.rev);
   }
-  const isOfflineTimestamp = serverNow - incomingChanges[0].createdAt > sessionTimeoutMillis;
-  if (isOfflineTimestamp || batchId) {
-    const canFastForward = committedChanges.length === 0;
-    const origin = options?.historicalImport ? "main" : canFastForward ? "main" : "offline-branch";
-    incomingChanges = await handleOfflineSessionsAndBatches(
-      store,
-      sessionTimeoutMillis,
-      docId,
-      incomingChanges,
-      baseRev,
-      batchId,
-      origin,
-      maxStorageBytes
-    );
-    if (canFastForward) {
-      await store.saveChanges(docId, incomingChanges);
-      return { catchupChanges: [], newChanges: incomingChanges };
+  let offlineSessionsHandled = false;
+  for (let attempt = 0; attempt < MAX_CONFLICT_RETRIES; attempt++) {
+    try {
+      const currentRev = attempt === 0 ? initialRev : await store.getCurrentRev(docId);
+      const committedChanges = await store.listChanges(docId, {
+        startAfter: baseRev,
+        withoutBatchId: batchId
+      });
+      const committedIds = new Set(committedChanges.map((c) => c.id));
+      const incomingChanges = changes.filter((c) => !committedIds.has(c.id));
+      if (incomingChanges.length === 0) {
+        return { catchupChanges: committedChanges, newChanges: [], docReloadRequired };
+      }
+      const isOfflineTimestamp = serverNow - incomingChanges[0].createdAt > sessionTimeoutMillis;
+      if (isOfflineTimestamp || batchId) {
+        const canFastForward = committedChanges.length === 0;
+        if (!offlineSessionsHandled) {
+          const origin = options?.historicalImport ? "main" : canFastForward ? "main" : "offline-branch";
+          await handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, incomingChanges, origin);
+          offlineSessionsHandled = true;
+        }
+        if (canFastForward) {
+          await store.saveChanges(docId, incomingChanges);
+          return { catchupChanges: [], newChanges: incomingChanges, docReloadRequired };
+        }
+      }
+      const transformedChanges = transformIncomingChanges(
+        incomingChanges,
+        committedChanges,
+        currentRev,
+        options?.forceCommit
+      );
+      if (transformedChanges.length > 0) {
+        await store.saveChanges(docId, transformedChanges);
+      }
+      return { catchupChanges: committedChanges, newChanges: transformedChanges, docReloadRequired };
+    } catch (error) {
+      if (error instanceof RevConflictError && attempt < MAX_CONFLICT_RETRIES - 1) continue;
+      throw error;
     }
   }
-  const stateAtBaseRev = (await getStateAtRevision(store, docId, baseRev)).state;
-  const transformedChanges = transformIncomingChanges(
-    incomingChanges,
-    stateAtBaseRev,
-    committedChanges,
-    currentRev,
-    options?.forceCommit
-  );
-  if (transformedChanges.length > 0) {
-    await store.saveChanges(docId, 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 };
+  throw new Error(`commitChanges: exhausted ${MAX_CONFLICT_RETRIES} retries for doc ${docId}`);
 }
 export {
   commitChanges

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

@@ -1,18 +1,47 @@
 import { OTStoreBackend } from '../../../server/types.js';
-import { Change, EditableVersionMetadata, VersionMetadata } from '../../../types.js';
+import { EditableVersionMetadata, VersionMetadata, Change } from '../../../types.js';
 import '../../../json-patch/types.js';
 import '../../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 
 /**
- * Creates a new version snapshot of a document's state from changes.
+ * Options for creating a version.
+ */
+interface CreateVersionOptions {
+    /** The origin of the version. Defaults to 'main'. */
+    origin?: 'main' | 'offline-branch';
+    /** ID of the parent version in the history chain. */
+    parentId?: string;
+    /** Optional additional metadata for the version. */
+    metadata?: EditableVersionMetadata;
+}
+/**
+ * Creates a version for all changes since the last version up to (and including) `endRev`.
+ *
+ * Looks up the last existing version to determine `startRev`, then loads all
+ * changes from there to `endRev` from the change log. This ensures the version
+ * covers the complete session, not just a single change.
+ *
+ * @param store The storage backend.
+ * @param docId The document ID.
+ * @param endRev The revision to end the version at (inclusive).
+ * @param options Options including origin and metadata.
+ * @returns The created version metadata, or undefined if no changes were found.
+ */
+declare function createVersionAtRev(store: OTStoreBackend, docId: string, endRev: number, options?: CreateVersionOptions): Promise<VersionMetadata | undefined>;
+/**
+ * Creates a new version record from changes.
+ *
+ * Saves metadata and changes to the store via `store.createVersion`. The store
+ * implementation is responsible for building and persisting version state — inline
+ * or queued — and must throw if that fails.
+ *
  * @param store The storage backend to save the version to.
  * @param docId The document ID.
- * @param state The document state at the time of the version.
- * @param changes The changes since the last version that created the state.
- * @param metadata Optional additional metadata for the version.
+ * @param changes The changes since the last version.
+ * @param options Options including origin and metadata.
  * @returns The created version metadata, or undefined if no changes provided.
  */
-declare function createVersion(store: OTStoreBackend, docId: string, state: any, changes: Change[], metadata?: EditableVersionMetadata): Promise<VersionMetadata | undefined>;
+declare function createVersion(store: OTStoreBackend, docId: string, changes: Change[], options?: CreateVersionOptions): Promise<VersionMetadata | undefined>;
 
-export { createVersion };
+export { type CreateVersionOptions, createVersion, createVersionAtRev };

package/dist/algorithms/ot/server/createVersion.js

@@ -1,22 +1,41 @@
 import "../../../chunk-IZ2YBCUP.js";
 import { createVersionMetadata } from "../../../data/version.js";
-async function createVersion(store, docId, state, changes, metadata) {
+async function createVersionAtRev(store, docId, endRev, options) {
+  const [lastVersion] = await store.listVersions(docId, {
+    limit: 1,
+    reverse: true,
+    orderBy: "endRev"
+  });
+  const startAfterRev = lastVersion?.endRev ?? 0;
+  const changes = await store.listChanges(docId, {
+    startAfter: startAfterRev,
+    endBefore: endRev + 1
+  });
+  if (changes.length === 0) return void 0;
+  return createVersion(store, docId, changes, {
+    ...options,
+    parentId: options?.parentId ?? lastVersion?.id
+  });
+}
+async function createVersion(store, docId, changes, options) {
   if (changes.length === 0) return;
   const startRev = changes[0].rev;
   if (startRev === void 0) {
     throw new Error(`Client changes must include rev for doc ${docId}.`);
   }
   const sessionMetadata = createVersionMetadata({
-    origin: "main",
+    origin: options?.origin ?? "main",
     startedAt: changes[0].createdAt,
     endedAt: changes[changes.length - 1].createdAt,
     endRev: changes[changes.length - 1].rev,
     startRev,
-    ...metadata
+    ...options?.parentId !== void 0 && { parentId: options.parentId },
+    ...options?.metadata
   });
-  await store.createVersion(docId, sessionMetadata, state, changes);
+  await store.createVersion(docId, sessionMetadata, changes);
   return sessionMetadata;
 }
 export {
-  createVersion
+  createVersion,
+  createVersionAtRev
 };

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

@@ -7,10 +7,22 @@ import '@dabble/delta';
 /**
  * Retrieves the document state of the version before the given revision and changes after up to that revision or all
  * changes since that version.
+ *
+ * Note: This is NOT used in the hot path (commitChanges). It's used by explicit operations
+ * like captureCurrentVersion and createBranch that need the parsed state.
+ *
  * @param docId The document ID.
  * @param rev The revision number. If not provided, the latest state, its revision, and all changes since are returned.
  * @returns The document state at the last version before the revision, its revision number, and all changes up to the specified revision (or all changes if no revision is provided).
  */
 declare function getSnapshotAtRevision(store: OTStoreBackend, docId: string, rev?: number): Promise<PatchesSnapshot>;
+/**
+ * Returns a ReadableStream that streams the snapshot JSON envelope piece-by-piece:
+ * `{"state":...,"rev":N,"changes":[...]}`.
+ *
+ * The version state (typically the largest payload) flows through as a raw
+ * string from the store without parsing. Changes are stringified from the array.
+ */
+declare function getSnapshotStream(store: OTStoreBackend, docId: string): Promise<ReadableStream<string>>;
 
-export { getSnapshotAtRevision };
+export { getSnapshotAtRevision, getSnapshotStream };

package/dist/algorithms/ot/server/getSnapshotAtRevision.js

@@ -1,28 +1,39 @@
 import "../../../chunk-IZ2YBCUP.js";
-async function getSnapshotAtRevision(store, docId, rev) {
+import { concatStreams, parseVersionState } from "../../../server/jsonReadable.js";
+async function getLatestMainVersion(store, docId, beforeRev) {
   const versions = await store.listVersions(docId, {
     limit: 1,
     reverse: true,
-    startAfter: rev ? rev + 1 : void 0,
+    startAfter: beforeRev ? beforeRev + 1 : void 0,
     origin: "main",
     orderBy: "endRev"
   });
-  const latestMainVersion = versions[0];
-  const versionState = latestMainVersion && await store.loadVersionState(docId, latestMainVersion.id) || null;
-  const versionRev = latestMainVersion?.endRev ?? 0;
+  const version = versions[0];
+  return {
+    rawState: version ? await store.loadVersionState(docId, version.id) : void 0,
+    versionRev: version?.endRev ?? 0
+  };
+}
+async function getSnapshotAtRevision(store, docId, rev) {
+  const { rawState, versionRev } = await getLatestMainVersion(store, docId, rev);
+  const versionState = rawState ? await parseVersionState(rawState) : null;
   const changesSinceVersion = await store.listChanges(docId, {
     startAfter: versionRev,
     endBefore: rev ? rev + 1 : void 0
   });
   return {
     state: versionState,
-    // State from the base version
     rev: versionRev,
-    // Revision of the base version's state
     changes: changesSinceVersion
-    // Changes that occurred *after* the base version state
   };
 }
+async function getSnapshotStream(store, docId) {
+  const { rawState, versionRev } = await getLatestMainVersion(store, docId);
+  const statePayload = rawState ?? "null";
+  const changes = await store.listChanges(docId, { startAfter: versionRev });
+  return concatStreams(`{"state":`, statePayload, `,"rev":${versionRev},"changes":`, JSON.stringify(changes), "}");
+}
 export {
-  getSnapshotAtRevision
+  getSnapshotAtRevision,
+  getSnapshotStream
 };

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

@@ -6,20 +6,20 @@ import '@dabble/delta';
 
 /**
  * Handles offline/large batch versioning logic for multi-batch uploads.
- * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
  *
- * Each session's `isOffline` metadata is determined per-session by comparing `committedAt` and
- * `createdAt` on the first change — if the gap exceeds `sessionTimeoutMillis`, the session is
- * marked offline.
+ * Detects session boundaries from timestamps and creates versions for each session.
+ * Changes are never collapsed — they're preserved individually.
  *
+ * Each session version gets a `parentId` linking it to the preceding version:
+ * - Session 1's parent: the last main-timeline version before the batch's first change
+ * - Session N's parent (N > 1): the immediately preceding session's version
+ *
+ * @param store Store backend for version creation
+ * @param sessionTimeoutMillis Timeout for detecting session boundaries
  * @param docId Document ID
- * @param changes The incoming changes (all with the same batchId)
- * @param baseRev The base revision for the batch
- * @param batchId The batch identifier
- * @param origin The origin to use for created versions (default: 'offline-branch')
- * @param maxStorageBytes If set, break collapsed changes that exceed this size
- * @returns The changes (collapsed into one if divergent, unchanged if fast-forward)
+ * @param changes The incoming changes
+ * @param origin The origin for version metadata
  */
-declare function handleOfflineSessionsAndBatches(store: OTStoreBackend, sessionTimeoutMillis: number, docId: string, changes: Change[], baseRev: number, batchId?: string, origin?: 'main' | 'offline-branch', maxStorageBytes?: number): Promise<Change[]>;
+declare function handleOfflineSessionsAndBatches(store: OTStoreBackend, sessionTimeoutMillis: number, docId: string, changes: Change[], origin?: 'main' | 'offline-branch'): Promise<void>;
 
 export { handleOfflineSessionsAndBatches };