@dabble/patches 0.2.31 → 0.3.0

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

@@ -0,0 +1,8 @@
+import type { Change, PatchesSnapshot } from '../../types';
+/**
+ * Applies incoming changes from the server that were *not* initiated by this client.
+ * @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.
+ */
+export declare function applyCommittedChanges(snapshot: PatchesSnapshot, committedChangesFromServer: Change[]): PatchesSnapshot;

package/dist/algorithms/client/applyCommittedChanges.js

@@ -0,0 +1,40 @@
+import { applyChanges } from '../shared/applyChanges';
+import { rebaseChanges } from '../shared/rebaseChanges';
+/**
+ * Applies incoming changes from the server that were *not* initiated by this client.
+ * @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.
+ */
+export function applyCommittedChanges(snapshot, committedChangesFromServer) {
+    let { state, rev, changes } = snapshot;
+    // Filter out any server changes that are already reflected in the current snapshot's revision.
+    // Server changes should always have a rev.
+    const newServerChanges = committedChangesFromServer.filter(change => change.rev > rev);
+    if (newServerChanges.length === 0) {
+        // No new changes to apply, return the snapshot as is.
+        return { state, rev, changes };
+    }
+    const firstChange = newServerChanges[0];
+    const lastChange = newServerChanges[newServerChanges.length - 1];
+    // Ensure the new server changes are sequential to the current snapshot's revision.
+    if (firstChange.rev !== rev + 1) {
+        throw new Error(`Missing changes from the server. Expected rev ${rev + 1}, got ${firstChange.rev}. Request changes since ${rev}.`);
+    }
+    // 1. Apply to committed state
+    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}`);
+    }
+    // 2. Update committed revision to the latest one from the applied server changes.
+    rev = lastChange.rev;
+    // 3. Rebase pending local changes against the newly applied server changes.
+    if (changes && changes.length > 0) {
+        changes = rebaseChanges(newServerChanges, changes);
+    }
+    return { state, rev, changes };
+}

package/dist/{utils → algorithms/client}/batching.d.ts

@@ -1,3 +1,3 @@
-import type { Change } from '../types.js';
+import type { Change } from '../../types.js';
 /** Break changes into batches based on maxPayloadBytes. */
 export declare function breakIntoBatches(changes: Change[], maxPayloadBytes?: number): Change[][];

package/dist/{utils → algorithms/client}/batching.js

@@ -1,6 +1,6 @@
 import { createId } from 'crypto-id';
-import { breakChange } from './breakChange.js'; // Import from new file
-import { getJSONByteSize } from './getJSONByteSize.js'; // Import from new file
+import { breakChange } from './breakChange.js';
+import { getJSONByteSize } from './getJSONByteSize.js';
 /** Break changes into batches based on maxPayloadBytes. */
 export function breakIntoBatches(changes, maxPayloadBytes) {
     if (!maxPayloadBytes || getJSONByteSize(changes) < maxPayloadBytes) {

package/dist/{utils → algorithms/client}/breakChange.d.ts

@@ -1,7 +1,6 @@
-import type { Change } from '../types.js';
+import type { Change } from '../../types.js';
 /**
- * Break a single Change into multiple Changes so that
- * JSON.stringify(change).length never exceeds `maxBytes`.
+ * Break a single Change into multiple Changes so that the JSON string size never exceeds `maxBytes`.
  *
  * - Splits first by JSON-Patch *ops*
  * - If an individual op is still too big and is a "@txt" op,

package/dist/algorithms/client/breakChange.js

@@ -0,0 +1,258 @@
+import { createChange } from '../../data/change.js';
+import { getJSONByteSize } from './getJSONByteSize.js';
+/**
+ * Break a single Change into multiple Changes so that the JSON string size never exceeds `maxBytes`.
+ *
+ * - Splits first by JSON-Patch *ops*
+ * - If an individual op is still too big and is a "@txt" op,
+ *   split its Delta payload into smaller Deltas
+ */
+export function breakChange(orig, maxBytes) {
+    if (getJSONByteSize(orig) <= maxBytes)
+        return [orig];
+    // First pass: split by ops
+    const byOps = [];
+    let group = [];
+    let rev = orig.rev;
+    const flush = () => {
+        if (!group.length)
+            return;
+        byOps.push(deriveNewChange(orig, rev++, group));
+        group = [];
+    };
+    for (const op of orig.ops) {
+        const tentative = group.concat(op);
+        if (getJSONByteSize({ ...orig, ops: tentative }) > maxBytes)
+            flush();
+        // Handle the case where a single op is too large
+        if (group.length === 0 && getJSONByteSize({ ...orig, ops: [op] }) > maxBytes) {
+            // We have a single op that's too big - can only be @txt op with large delta
+            if (op.op === '@txt' && op.value) {
+                const pieces = breakTextOp(orig, op, maxBytes, rev);
+                byOps.push(...pieces);
+                // Only update rev if we got results from breakTextOp
+                if (pieces.length > 0) {
+                    rev = pieces[pieces.length - 1].rev + 1; // Update rev for next changes
+                }
+                continue;
+            }
+            else if (op.op === 'replace' || op.op === 'add') {
+                // For replace/add operations with large value payloads, try to split the value if it's a string or array
+                const pieces = breakLargeValueOp(orig, op, maxBytes, rev);
+                byOps.push(...pieces);
+                if (pieces.length > 0) {
+                    rev = pieces[pieces.length - 1].rev + 1;
+                }
+                continue;
+            }
+            else {
+                // Non-splittable op that's too large, include it anyway with a warning
+                console.warn(`Warning: Single operation of type ${op.op} exceeds maxBytes. Including it anyway.`);
+                group.push(op);
+                continue;
+            }
+        }
+        group.push(op);
+    }
+    flush();
+    return byOps;
+}
+/**
+ * Break a large @txt operation into multiple smaller operations
+ */
+function breakTextOp(origChange, textOp, maxBytes, startRev) {
+    const results = [];
+    let rev = startRev;
+    const baseSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: '' }] });
+    const budget = maxBytes - baseSize;
+    const buffer = 20;
+    const maxLength = Math.max(1, budget - buffer);
+    let deltaOps = [];
+    if (textOp.value) {
+        if (Array.isArray(textOp.value)) {
+            deltaOps = textOp.value;
+        }
+        else if (textOp.value.ops && Array.isArray(textOp.value.ops)) {
+            deltaOps = textOp.value.ops;
+        }
+        else if (typeof textOp.value === 'object') {
+            deltaOps = [textOp.value];
+        }
+    }
+    let currentOpsForNextChangePiece = [];
+    let retainToPrefixCurrentPiece = 0; // Retain that should prefix the ops in currentOpsForNextChangePiece
+    const flushCurrentChangePiece = () => {
+        if (!currentOpsForNextChangePiece.length)
+            return;
+        const opsToFlush = [...currentOpsForNextChangePiece];
+        if (retainToPrefixCurrentPiece > 0) {
+            if (!opsToFlush[0]?.retain) {
+                // Only add if not already starting with a retain
+                opsToFlush.unshift({ retain: retainToPrefixCurrentPiece });
+            }
+            else {
+                // If it starts with retain, assume it's the intended one from deltaOps.
+                // This might need adjustment if a small retain op is batched after a large retain prefix.
+                // For now, this prioritizes an existing retain op at the start of the batch.
+            }
+        }
+        results.push(deriveNewChange(origChange, rev++, [{ ...textOp, value: opsToFlush }]));
+        currentOpsForNextChangePiece = [];
+        // retainToPrefixCurrentPiece is NOT reset here, it carries over for the start of the next piece IF it's non-zero from a previous retain op.
+    };
+    for (const op of deltaOps) {
+        // Try adding current op (with its necessary prefix) to the current batch
+        const testBatchOps = [...currentOpsForNextChangePiece];
+        if (retainToPrefixCurrentPiece > 0 && testBatchOps.length === 0) {
+            // If batch is empty, it needs the prefix
+            testBatchOps.push({ retain: retainToPrefixCurrentPiece });
+        }
+        testBatchOps.push(op);
+        const testBatchSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: testBatchOps }] });
+        if (currentOpsForNextChangePiece.length > 0 && testBatchSize > maxBytes) {
+            flushCurrentChangePiece();
+            // After flush, retainToPrefixCurrentPiece still holds the value for the *start* of the new piece (current op)
+        }
+        // Check if the op itself (with its prefix) is too large for a new piece
+        const opStandaloneOps = retainToPrefixCurrentPiece > 0 ? [{ retain: retainToPrefixCurrentPiece }, op] : [op];
+        const opStandaloneSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: opStandaloneOps }] });
+        if (currentOpsForNextChangePiece.length === 0 && opStandaloneSize > maxBytes) {
+            if (op.insert && typeof op.insert === 'string') {
+                const insertChunks = splitLargeInsertText(op.insert, maxLength, op.attributes);
+                for (let i = 0; i < insertChunks.length; i++) {
+                    const chunkOp = insertChunks[i];
+                    const opsForThisChunk = [];
+                    if (i === 0 && retainToPrefixCurrentPiece > 0) {
+                        // Prefix only the first chunk
+                        opsForThisChunk.push({ retain: retainToPrefixCurrentPiece });
+                    }
+                    opsForThisChunk.push(chunkOp);
+                    results.push(deriveNewChange(origChange, rev++, [{ ...textOp, value: opsForThisChunk }]));
+                }
+                retainToPrefixCurrentPiece = 0; // An insert consumes the preceding retain for the next original op
+            }
+            else {
+                // Non-splittable large op (e.g., large retain)
+                console.warn(`Warning: Single delta op too large, including with prefix: ${JSON.stringify(op)}`);
+                results.push(deriveNewChange(origChange, rev++, [{ ...textOp, value: opStandaloneOps }]));
+                retainToPrefixCurrentPiece = op.retain || 0;
+            }
+        }
+        else {
+            // Op fits into current batch (or starts a new one that fits)
+            currentOpsForNextChangePiece.push(op);
+            if (op.retain) {
+                retainToPrefixCurrentPiece += op.retain; // Accumulate retain for the next op or flush
+            }
+            else {
+                // Insert or delete
+                retainToPrefixCurrentPiece = 0; // Consumes retain for the next op
+            }
+        }
+    }
+    if (currentOpsForNextChangePiece.length > 0) {
+        flushCurrentChangePiece();
+    }
+    return results;
+}
+/**
+ * Split a large insert string into multiple delta insert operations.
+ * Each operation will have the original attributes.
+ */
+function splitLargeInsertText(text, maxChunkLength, attributes) {
+    const results = [];
+    if (maxChunkLength <= 0) {
+        console.warn('splitLargeInsertText: maxChunkLength is invalid, returning original text as one chunk.');
+        return [{ insert: text, attributes }];
+    }
+    for (let i = 0; i < text.length; i += maxChunkLength) {
+        const chunkText = text.slice(i, i + maxChunkLength);
+        results.push({ insert: chunkText, attributes: attributes ? { ...attributes } : undefined });
+    }
+    return results;
+}
+/**
+ * Attempt to break a large value in a replace/add operation
+ */
+function breakLargeValueOp(origChange, op, maxBytes, startRev) {
+    const results = [];
+    let rev = startRev;
+    const baseOpSize = getJSONByteSize({ ...op, value: '' });
+    const baseChangeSize = getJSONByteSize({ ...origChange, ops: [{ ...op, value: '' }] }) - baseOpSize;
+    const valueBudget = maxBytes - baseChangeSize - 50;
+    if (typeof op.value === 'string' && op.value.length > 100) {
+        const text = op.value;
+        const targetChunkSize = Math.max(1, valueBudget);
+        const numChunks = Math.ceil(text.length / targetChunkSize);
+        const chunkSize = Math.ceil(text.length / numChunks);
+        for (let i = 0; i < text.length; i += chunkSize) {
+            const chunk = text.slice(i, i + chunkSize);
+            const newOp = { op: 'add' };
+            if (i === 0) {
+                newOp.op = op.op;
+                newOp.path = op.path;
+                newOp.value = chunk;
+            }
+            else {
+                newOp.op = 'patch';
+                newOp.path = op.path;
+                newOp.appendString = chunk;
+            }
+            results.push(deriveNewChange(origChange, rev++, [newOp]));
+        }
+        return results;
+    }
+    else if (Array.isArray(op.value) && op.value.length > 1) {
+        const originalArray = op.value;
+        let currentChunk = [];
+        let chunkStartIndex = 0;
+        for (let i = 0; i < originalArray.length; i++) {
+            const item = originalArray[i];
+            const tentativeChunk = [...currentChunk, item];
+            const tentativeOp = { ...op, value: tentativeChunk };
+            const tentativeChangeSize = getJSONByteSize({ ...origChange, ops: [tentativeOp] });
+            if (currentChunk.length > 0 && tentativeChangeSize > maxBytes) {
+                const chunkOp = {};
+                if (chunkStartIndex === 0) {
+                    chunkOp.op = op.op;
+                    chunkOp.path = op.path;
+                    chunkOp.value = currentChunk;
+                }
+                else {
+                    chunkOp.op = 'patch';
+                    chunkOp.path = op.path;
+                    chunkOp.appendArray = currentChunk;
+                }
+                results.push(deriveNewChange(origChange, rev++, [chunkOp]));
+                currentChunk = [item];
+                chunkStartIndex = i;
+            }
+            else {
+                currentChunk.push(item);
+            }
+        }
+        if (currentChunk.length > 0) {
+            const chunkOp = {};
+            if (chunkStartIndex === 0) {
+                chunkOp.op = op.op;
+                chunkOp.path = op.path;
+                chunkOp.value = currentChunk;
+            }
+            else {
+                chunkOp.op = 'patch';
+                chunkOp.path = op.path;
+                chunkOp.appendArray = currentChunk;
+            }
+            results.push(deriveNewChange(origChange, rev++, [chunkOp]));
+        }
+        return results;
+    }
+    console.warn(`Warning: Single operation of type ${op.op} (path: ${op.path}) could not be split further by breakLargeValueOp despite exceeding maxBytes. Including as is.`);
+    return [deriveNewChange(origChange, rev++, [op])]; // Return original op in a new change if not splittable by this func
+}
+function deriveNewChange(origChange, rev, ops) {
+    // Filter out metadata that shouldn't be part of the new change object
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { id: _id, ops: _o, rev: _r, baseRev: _br, created: _c, batchId: _bi, ...metadata } = origChange;
+    return createChange(origChange.baseRev, rev, ops, metadata);
+}

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

@@ -0,0 +1,7 @@
+import type { PatchesSnapshot } from '../../types.js';
+/**
+ * Creates the in-memory state from a snapshot.
+ * @param snapshot The snapshot to create a state from.
+ * @returns The new state.
+ */
+export declare function createStateFromSnapshot<T = any>(snapshot: PatchesSnapshot<T>): T;

package/dist/algorithms/client/createStateFromSnapshot.js

@@ -0,0 +1,9 @@
+import { applyChanges } from '../shared/applyChanges.js';
+/**
+ * Creates the in-memory state from a snapshot.
+ * @param snapshot The snapshot to create a state from.
+ * @returns The new state.
+ */
+export function createStateFromSnapshot(snapshot) {
+    return applyChanges(snapshot.state, snapshot.changes);
+}

package/dist/algorithms/client/getJSONByteSize.js

@@ -0,0 +1,12 @@
+/** Estimate JSON string byte size. */
+export function getJSONByteSize(data) {
+    try {
+        const stringified = JSON.stringify(data);
+        return stringified ? new TextEncoder().encode(stringified).length : 0;
+    }
+    catch (e) {
+        // Handle circular structures (from JSON.stringify) or other errors.
+        console.error('Error calculating JSON size:', e);
+        throw new Error('Error calculating JSON size: ' + e);
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { JSONPatch } from '../..';
+import type { Change, PatchesSnapshot } from '../../types';
+export declare function makeChange<T = any>(snapshot: PatchesSnapshot<T>, mutator: (draft: T, patch: JSONPatch) => void, changeMetadata?: Record<string, any>, maxPayloadBytes?: number): Change[];

package/dist/algorithms/client/makeChange.js

@@ -0,0 +1,37 @@
+import { createChange } from '../../data/change';
+import { createJSONPatch } from '../../json-patch/createJSONPatch';
+import { breakChange } from './breakChange';
+import { createStateFromSnapshot } from './createStateFromSnapshot';
+export function makeChange(snapshot, mutator, changeMetadata, maxPayloadBytes) {
+    const pendingChanges = snapshot.changes;
+    const pendingRev = pendingChanges[pendingChanges.length - 1]?.rev ?? snapshot.rev;
+    const state = createStateFromSnapshot(snapshot); // Current state including pending
+    const patch = createJSONPatch(state, mutator);
+    if (patch.ops.length === 0) {
+        return [];
+    }
+    // Optimistic rev for local sorting, based on the latest known rev (committed or pending)
+    const rev = pendingRev + 1;
+    // Create the initial change. BaseRev is always the last *committed* revision from the snapshot.
+    let newChangesArray = [createChange(snapshot.rev, rev, patch.ops, changeMetadata)];
+    // Optimistically apply the patch to the current state (which includes pending changes)
+    // This state is temporary for validation/splitting and not stored back directly in PatchesDoc from here.
+    try {
+        // Note: The 'state' variable here is the one derived from createStateFromSnapshot (committed + pending).
+        // Applying the new patch to it is for the purpose of creating the correct Change object(s).
+        // PatchesDoc.change will apply these returned changes to its own _state later.
+        patch.apply(state); // This line primarily serves to ensure the patch is valid against the current view.
+    }
+    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 (maxPayloadBytes) {
+        // If the single change (or its parts) exceed maxPayloadBytes, break it down.
+        // breakChange will handle creating multiple Change objects if necessary,
+        // maintaining the original baseRev but incrementing revs for the pieces.
+        newChangesArray = breakChange(newChangesArray[0], maxPayloadBytes);
+    }
+    // PatchesDoc.change will take this returned array and push its contents onto its internal snapshot.
+    return newChangesArray;
+}

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

@@ -0,0 +1,12 @@
+import type { PatchesStoreBackend } from '../../server/types';
+import type { Change } from '../../types';
+/**
+ * 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.
+ * @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
+ */
+export declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: Change[], sessionTimeoutMillis: number): Promise<[Change[], Change[]]>;

package/dist/algorithms/server/commitChanges.js

@@ -0,0 +1,80 @@
+import { applyChanges } from '../shared/applyChanges';
+import { createVersion } from './createVersion';
+import { getSnapshotAtRevision } from './getSnapshotAtRevision';
+import { getStateAtRevision } from './getStateAtRevision';
+import { handleOfflineSessionsAndBatches } from './handleOfflineSessionsAndBatches';
+import { transformIncomingChanges } from './transformIncomingChanges';
+/**
+ * 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.
+ * @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
+ */
+export async function commitChanges(store, docId, changes, sessionTimeoutMillis) {
+    if (changes.length === 0) {
+        return [[], []];
+    }
+    // Assume all changes share the same baseRev. Client ensures
+    const batchId = changes[0].batchId;
+    const baseRev = changes[0].baseRev;
+    if (baseRev === undefined) {
+        throw new Error(`Client changes must include baseRev for doc ${docId}.`);
+    }
+    // Add check for inconsistent baseRev within the batch if needed
+    if (changes.some(c => c.baseRev !== baseRev)) {
+        throw new Error(`Client changes must have consistent baseRev in all changes for doc ${docId}.`);
+    }
+    // 1. Load server state details (assuming store methods exist)
+    const { state: initialState, rev: initialRev, changes: currentChanges } = await getSnapshotAtRevision(store, docId);
+    const currentState = applyChanges(initialState, currentChanges);
+    const currentRev = currentChanges.at(-1)?.rev ?? initialRev;
+    // Basic validation
+    if (baseRev > currentRev) {
+        throw new Error(`Client baseRev (${baseRev}) is ahead of server revision (${currentRev}) for doc ${docId}. Client needs to reload the document.`);
+    }
+    const partOfInitialBatch = batchId && changes[0].rev > 1;
+    if (baseRev === 0 && currentRev > 0 && !partOfInitialBatch && changes[0].ops[0].path === '') {
+        throw new Error(`Client baseRev is 0 but server has already been created for doc ${docId}. Client needs to load the existing document.`);
+    }
+    // Ensure all new changes' `created` field is in the past, that each `rev` is correct, and that `baseRev` is set
+    changes.forEach(c => {
+        c.created = Math.min(c.created, Date.now());
+        c.baseRev = baseRev;
+    });
+    // 2. Check if we need to create a new version - if the last change was created more than a session ago
+    const lastChange = currentChanges[currentChanges.length - 1];
+    if (lastChange && lastChange.created < Date.now() - sessionTimeoutMillis) {
+        await createVersion(store, docId, currentState, currentChanges);
+    }
+    // 3. Load committed changes *after* the client's baseRev for transformation and idempotency checks
+    const committedChanges = await store.listChanges(docId, {
+        startAfter: baseRev,
+        withoutBatchId: batchId,
+    });
+    const committedIds = new Set(committedChanges.map(c => c.id));
+    changes = changes.filter(c => !committedIds.has(c.id));
+    // If all incoming changes were already committed, return the committed changes found
+    if (changes.length === 0) {
+        return [committedChanges, []];
+    }
+    // 4. Handle offline-session versioning:
+    // - batchId present (multi-batch uploads)
+    // - or the first change is older than the session timeout (single-batch offline)
+    const isOfflineTimestamp = changes[0].created < Date.now() - sessionTimeoutMillis;
+    if (isOfflineTimestamp || batchId) {
+        changes = await handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId);
+    }
+    // 5. Transform the *entire batch* of incoming (and potentially collapsed offline) changes
+    //    against committed changes that happened *after* the client's baseRev.
+    //    The state used for transformation should be the server state *at the client's baseRev*.
+    const stateAtBaseRev = (await getStateAtRevision(store, docId, baseRev)).state;
+    const transformedChanges = transformIncomingChanges(changes, stateAtBaseRev, committedChanges, currentRev);
+    if (transformedChanges.length > 0) {
+        await store.saveChanges(docId, transformedChanges);
+    }
+    // Return committed changes and newly transformed changes separately
+    return [committedChanges, transformedChanges];
+}

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

@@ -0,0 +1,12 @@
+import type { Change, EditableVersionMetadata, VersionMetadata } from '../../types';
+import type { PatchesStoreBackend } from '../../server/types';
+/**
+ * Creates a new version snapshot of a document's state from changes.
+ * @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.
+ * @returns The created version metadata, or undefined if no changes provided.
+ */
+export declare function createVersion(store: PatchesStoreBackend, docId: string, state: any, changes: Change[], metadata?: EditableVersionMetadata): Promise<VersionMetadata | undefined>;

package/dist/algorithms/server/createVersion.js

@@ -0,0 +1,28 @@
+import { createVersionMetadata } from '../../data/version.js';
+/**
+ * Creates a new version snapshot of a document's state from changes.
+ * @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.
+ * @returns The created version metadata, or undefined if no changes provided.
+ */
+export async function createVersion(store, docId, state, changes, metadata) {
+    if (changes.length === 0)
+        return;
+    const baseRev = changes[0].baseRev;
+    if (baseRev === undefined) {
+        throw new Error(`Client changes must include baseRev for doc ${docId}.`);
+    }
+    const sessionMetadata = createVersionMetadata({
+        origin: 'main',
+        startDate: changes[0].created,
+        endDate: changes[changes.length - 1].created,
+        rev: changes[changes.length - 1].rev,
+        baseRev,
+        ...metadata,
+    });
+    await store.createVersion(docId, sessionMetadata, state, changes);
+    return sessionMetadata;
+}

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

@@ -0,0 +1,10 @@
+import type { PatchesStoreBackend } from '../../server';
+import type { PatchesSnapshot } from '../../types';
+/**
+ * Retrieves the document state of the version before the given revision and changes after up to that revision or all
+ * changes since that version.
+ * @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).
+ */
+export declare function getSnapshotAtRevision(store: PatchesStoreBackend, docId: string, rev?: number): Promise<PatchesSnapshot>;

package/dist/algorithms/server/getSnapshotAtRevision.js

@@ -0,0 +1,29 @@
+/**
+ * Retrieves the document state of the version before the given revision and changes after up to that revision or all
+ * changes since that version.
+ * @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).
+ */
+export async function getSnapshotAtRevision(store, docId, rev) {
+    const versions = await store.listVersions(docId, {
+        limit: 1,
+        reverse: true,
+        startAfter: rev ? rev + 1 : undefined,
+        origin: 'main',
+        orderBy: 'rev',
+    });
+    const latestMainVersion = versions[0];
+    const versionState = (latestMainVersion && (await store.loadVersionState(docId, latestMainVersion.id))) || null;
+    const versionRev = latestMainVersion?.rev ?? 0;
+    // Get *all* changes since that version up to the target revision (if specified)
+    const changesSinceVersion = await store.listChanges(docId, {
+        startAfter: versionRev,
+        endBefore: rev ? rev + 1 : undefined,
+    });
+    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
+    };
+}

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

@@ -0,0 +1,9 @@
+import type { PatchesStoreBackend } from '../../server';
+import type { PatchesState } from '../../types';
+/**
+ * Gets the state at a specific revision.
+ * @param docId The document ID.
+ * @param rev The revision number. If not provided, the latest state and its revision is returned.
+ * @returns The state at the specified revision *and* its revision number.
+ */
+export declare function getStateAtRevision(store: PatchesStoreBackend, docId: string, rev?: number): Promise<PatchesState>;

package/dist/algorithms/server/getStateAtRevision.js

@@ -0,0 +1,18 @@
+import { applyChanges } from '../shared/applyChanges';
+import { getSnapshotAtRevision } from './getSnapshotAtRevision';
+/**
+ * Gets the state at a specific revision.
+ * @param docId The document ID.
+ * @param rev The revision number. If not provided, the latest state and its revision is returned.
+ * @returns The state at the specified revision *and* its revision number.
+ */
+export async function getStateAtRevision(store, docId, rev) {
+    // Note: _getSnapshotAtRevision now returns the state *of the version* and changes *since* it.
+    // We need to apply the changes to get the state *at* the target revision.
+    const { state: versionState, rev: snapshotRev, changes } = await getSnapshotAtRevision(store, docId, rev);
+    return {
+        // Ensure null is passed if versionState or versionState.state is null/undefined
+        state: applyChanges(versionState?.state ?? null, changes),
+        rev: changes.at(-1)?.rev ?? snapshotRev,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { PatchesStoreBackend } from '../../server';
+import type { Change } from '../../types';
+/**
+ * Handles offline/large batch versioning logic for multi-batch uploads.
+ * Groups changes into sessions, merges with previous batch if needed, and creates/extends versions.
+ * @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
+ * @returns The collapsed changes for transformation
+ */
+export declare function handleOfflineSessionsAndBatches(store: PatchesStoreBackend, sessionTimeoutMillis: number, docId: string, changes: Change[], baseRev: number, batchId?: string): Promise<Change[]>;