@dabble/patches 0.2.32 → 0.3.0

package/dist/algorithms/server/handleOfflineSessionsAndBatches.js

@@ -0,0 +1,80 @@
+import { createSortableId } from 'crypto-id';
+import { createVersionMetadata } from '../../data/version';
+import { applyChanges } from '../shared/applyChanges';
+import { getStateAtRevision } from './getStateAtRevision';
+/**
+ * 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 async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId) {
+    // Use batchId as groupId for multi-batch uploads; default offline sessions have no groupId
+    const groupId = batchId ?? createSortableId();
+    // Find the last version for this groupId (if any)
+    const [lastVersion] = await store.listVersions(docId, {
+        groupId,
+        reverse: true,
+        limit: 1,
+    });
+    let offlineBaseState;
+    let parentId;
+    if (lastVersion) {
+        // Continue from the last version's state
+        // loadVersionState returns a PatchState ({state, rev}); extract the .state
+        const vs = await store.loadVersionState(docId, lastVersion.id);
+        offlineBaseState = vs.state ?? vs;
+        parentId = lastVersion.id;
+    }
+    else {
+        // First batch for this batchId: start at baseRev
+        offlineBaseState = (await getStateAtRevision(store, docId, baseRev)).state;
+    }
+    let sessionStartIndex = 0;
+    for (let i = 1; i <= changes.length; i++) {
+        const isLastChange = i === changes.length;
+        const timeDiff = isLastChange ? Infinity : changes[i].created - changes[i - 1].created;
+        // Session ends if timeout exceeded OR it's the last change in the batch
+        if (timeDiff > sessionTimeoutMillis || isLastChange) {
+            const sessionChanges = changes.slice(sessionStartIndex, i);
+            if (sessionChanges.length > 0) {
+                // Check if this is a continuation of the previous session (merge/extend)
+                const isContinuation = !!lastVersion && sessionChanges[0].created - lastVersion.endDate <= sessionTimeoutMillis;
+                if (isContinuation) {
+                    // Merge/extend the existing version
+                    const mergedState = applyChanges(offlineBaseState, sessionChanges);
+                    await store.saveChanges(docId, sessionChanges);
+                    await store.updateVersion(docId, lastVersion.id, {}); // metadata already updated above
+                    offlineBaseState = mergedState;
+                    parentId = lastVersion.parentId;
+                }
+                else {
+                    // Create a new version for this session
+                    offlineBaseState = applyChanges(offlineBaseState, sessionChanges);
+                    const sessionMetadata = createVersionMetadata({
+                        parentId,
+                        groupId,
+                        origin: 'offline',
+                        startDate: sessionChanges[0].created,
+                        endDate: sessionChanges[sessionChanges.length - 1].created,
+                        rev: sessionChanges[sessionChanges.length - 1].rev,
+                        baseRev,
+                    });
+                    await store.createVersion(docId, sessionMetadata, offlineBaseState, sessionChanges);
+                    parentId = sessionMetadata.id;
+                }
+                sessionStartIndex = i;
+            }
+        }
+    }
+    // Collapse all changes into one for transformation
+    return [
+        changes.reduce((firstChange, nextChange) => {
+            firstChange.ops = [...firstChange.ops, ...nextChange.ops];
+            return firstChange;
+        }),
+    ];
+}

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

@@ -0,0 +1,11 @@
+import type { Change } from '../../types';
+/**
+ * Transforms incoming 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*.
+ * @param changes The incoming changes.
+ * @param stateAtBaseRev The server state *at the client's baseRev*.
+ * @param committedChanges The committed changes that happened *after* the client's baseRev.
+ * @param currentRev The current/latest revision number (these changes will have their `rev` set > `currentRev`).
+ * @returns The transformed changes.
+ */
+export declare function transformIncomingChanges(changes: Change[], stateAtBaseRev: any, committedChanges: Change[], currentRev: number): Change[];

package/dist/algorithms/server/transformIncomingChanges.js

@@ -0,0 +1,40 @@
+import { applyPatch } from '../../json-patch/applyPatch.js';
+import { transformPatch } from '../../json-patch/transformPatch.js';
+/**
+ * Transforms incoming 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*.
+ * @param changes The incoming changes.
+ * @param stateAtBaseRev The server state *at the client's baseRev*.
+ * @param committedChanges The committed changes that happened *after* the client's baseRev.
+ * @param currentRev The current/latest revision number (these changes will have their `rev` set > `currentRev`).
+ * @returns The transformed changes.
+ */
+export function transformIncomingChanges(changes, stateAtBaseRev, committedChanges, currentRev) {
+    const committedOps = committedChanges.flatMap(c => c.ops);
+    let state = stateAtBaseRev;
+    let rev = currentRev + 1;
+    // Apply transformation based on state at baseRev
+    return changes
+        .map(change => {
+        // Transform the incoming change's ops against the ops committed since baseRev
+        const transformedOps = transformPatch(stateAtBaseRev, committedOps, change.ops);
+        if (transformedOps.length === 0) {
+            return null; // Change is obsolete after transformation
+        }
+        try {
+            const previous = state;
+            state = applyPatch(state, transformedOps, { strict: true });
+            if (previous === state) {
+                // Changes were no-ops, we can skip this change
+                return null;
+            }
+        }
+        catch (error) {
+            console.error(`Error applying change ${change.id} to state:`, error);
+            return null;
+        }
+        // Return a new change object with transformed ops and original metadata
+        return { ...change, rev: rev++, ops: transformedOps };
+    })
+        .filter(Boolean);
+}

package/dist/algorithms/shared/applyChanges.d.ts

@@ -0,0 +1,10 @@
+import type { Change } from '../../types.js';
+/**
+ * Applies a sequence of changes to a state object.
+ * Each change is applied in sequence using the applyPatch function.
+ *
+ * @param state - The initial state to apply changes to
+ * @param changes - Array of changes to apply
+ * @returns The state after all changes have been applied
+ */
+export declare function applyChanges<T>(state: T, changes: Change[]): T;

package/dist/algorithms/shared/applyChanges.js

@@ -0,0 +1,17 @@
+import { applyPatch } from '../../json-patch/applyPatch.js';
+/**
+ * Applies a sequence of changes to a state object.
+ * Each change is applied in sequence using the applyPatch function.
+ *
+ * @param state - The initial state to apply changes to
+ * @param changes - Array of changes to apply
+ * @returns The state after all changes have been applied
+ */
+export function applyChanges(state, changes) {
+    if (!changes.length)
+        return state;
+    for (const change of changes) {
+        state = applyPatch(state, change.ops, { strict: true });
+    }
+    return state;
+}

package/dist/{utils.d.ts → algorithms/shared/rebaseChanges.d.ts}

@@ -1,13 +1,4 @@
-import type { Change, Deferred } from './types.js';
-/**
- * Applies a sequence of changes to a state object.
- * Each change is applied in sequence using the applyPatch function.
- *
- * @param state - The initial state to apply changes to
- * @param changes - Array of changes to apply
- * @returns The state after all changes have been applied
- */
-export declare function applyChanges<T>(state: T, changes: Change[]): T;
+import type { Change } from '../../types.js';
 /**
  * Rebases local changes against server changes using operational transformation.
  * This function handles the transformation of local changes to be compatible with server changes
@@ -24,4 +15,3 @@ export declare function applyChanges<T>(state: T, changes: Change[]): T;
  * @returns Array of rebased local changes with updated revision numbers
  */
 export declare function rebaseChanges(serverChanges: Change[], localChanges: Change[]): Change[];
-export declare function deferred<T = void>(): Deferred<T>;

package/dist/{utils.js → algorithms/shared/rebaseChanges.js}

@@ -1,21 +1,4 @@
-import { applyPatch } from './json-patch/applyPatch.js';
-import { JSONPatch } from './json-patch/JSONPatch.js';
-/**
- * Applies a sequence of changes to a state object.
- * Each change is applied in sequence using the applyPatch function.
- *
- * @param state - The initial state to apply changes to
- * @param changes - Array of changes to apply
- * @returns The state after all changes have been applied
- */
-export function applyChanges(state, changes) {
-    if (!changes.length)
-        return state;
-    for (const change of changes) {
-        state = applyPatch(state, change.ops, { strict: true });
-    }
-    return state;
-}
+import { JSONPatch } from '../../json-patch/JSONPatch.js';
 /**
  * Rebases local changes against server changes using operational transformation.
  * This function handles the transformation of local changes to be compatible with server changes
@@ -54,7 +37,7 @@ export function rebaseChanges(serverChanges, localChanges) {
         .map(change => change.ops)
         .flat());
     // Rebase local changes against server changes
-    const base = lastChange.rev;
+    const baseRev = lastChange.rev;
     let rev = lastChange.rev;
     return filteredLocalChanges
         .map(change => {
@@ -62,30 +45,7 @@ export function rebaseChanges(serverChanges, localChanges) {
         const ops = transformPatch.transform(change.ops).ops;
         if (!ops.length)
             return null;
-        return { ...change, base, rev, ops };
+        return { ...change, baseRev, rev, ops };
     })
         .filter(Boolean);
 }
-export function deferred() {
-    let resolve;
-    let reject;
-    let _status = 'pending';
-    const promise = new Promise((_resolve, _reject) => {
-        resolve = (value) => {
-            _resolve(value);
-            _status = 'fulfilled';
-        };
-        reject = (reason) => {
-            _reject(reason);
-            _status = 'rejected';
-        };
-    });
-    return {
-        promise,
-        resolve,
-        reject,
-        get status() {
-            return _status;
-        },
-    };
-}

package/dist/client/InMemoryStore.d.ts

@@ -12,8 +12,9 @@ export declare class InMemoryStore implements PatchesStore {
     getLastRevs(docId: string): Promise<[number, number]>;
     listDocs(includeDeleted?: boolean): Promise<TrackedDoc[]>;
     saveDoc(docId: string, snapshot: PatchesState): Promise<void>;
-    savePendingChange(docId: string, change: Change): Promise<void>;
+    savePendingChanges(docId: string, changes: Change[]): Promise<void>;
     saveCommittedChanges(docId: string, changes: Change[], sentPendingRange?: [number, number]): Promise<void>;
+    replacePendingChanges(docId: string, changes: Change[]): Promise<void>;
     trackDocs(docIds: string[]): Promise<void>;
     untrackDocs(docIds: string[]): Promise<void>;
     deleteDoc(docId: string): Promise<void>;

package/dist/client/InMemoryStore.js

@@ -1,5 +1,5 @@
+import { applyChanges } from '../algorithms/shared/applyChanges.js';
 import { transformPatch } from '../json-patch/transformPatch.js';
-import { applyChanges } from '../utils.js';
 /**
  * A trivial in‑memory implementation of OfflineStore (soon PatchesStore).
  * All data lives in JS objects – nothing survives a page reload.
@@ -55,11 +55,11 @@ export class InMemoryStore {
     async saveDoc(docId, snapshot) {
         this.docs.set(docId, { snapshot, committed: [], pending: [] });
     }
-    async savePendingChange(docId, change) {
+    async savePendingChanges(docId, changes) {
         const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
         if (!this.docs.has(docId))
             this.docs.set(docId, buf);
-        buf.pending.push(change);
+        buf.pending.push(...changes);
     }
     async saveCommittedChanges(docId, changes, sentPendingRange) {
         const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
@@ -71,6 +71,12 @@ export class InMemoryStore {
             buf.pending = buf.pending.filter(p => p.rev < min || p.rev > max);
         }
     }
+    async replacePendingChanges(docId, changes) {
+        const buf = this.docs.get(docId) ?? { committed: [], pending: [] };
+        if (!this.docs.has(docId))
+            this.docs.set(docId, buf);
+        buf.pending = [...changes];
+    }
     // ─── Metadata / Tracking ───────────────────────────────────────────
     async trackDocs(docIds) {
         for (const docId of docIds) {

package/dist/client/IndexedDBStore.d.ts

@@ -47,15 +47,34 @@ export declare class IndexedDBStore implements PatchesStore {
      * Completely remove all data for this docId and mark it as deleted (tombstone).
      */
     deleteDoc(docId: string): Promise<void>;
+    /**
+     * Confirm the deletion of a document.
+     * @param docId - The ID of the document to delete.
+     */
     confirmDeleteDoc(docId: string): Promise<void>;
+    /**
+     * Save a document's state to the store.
+     * @param docId - The ID of the document to save.
+     * @param docState - The state of the document to save.
+     */
     saveDoc(docId: string, docState: PatchesState): Promise<void>;
     /**
      * Append an array of local changes to the pending queue.
      * Called *before* you attempt to send them to the server.
      */
-    savePendingChange(docId: string, change: Change): Promise<void>;
-    /** Read back all pending changes for this docId (in order). */
+    savePendingChanges(docId: string, changes: Change[]): Promise<void>;
+    /**
+     * Read back all pending changes for this docId (in order).
+     * @param docId - The ID of the document to get the pending changes for.
+     * @returns The pending changes.
+     */
     getPendingChanges(docId: string): Promise<Change[]>;
+    /**
+     * Replace all pending changes for a document (used after rebasing).
+     * @param docId - The ID of the document to replace the pending changes for.
+     * @param changes - The changes to replace the pending changes with.
+     */
+    replacePendingChanges(docId: string, changes: Change[]): Promise<void>;
     /**
      * Store server‐confirmed changes.  Will:
      * - persist them in the committedChanges store
@@ -67,8 +86,21 @@ export declare class IndexedDBStore implements PatchesStore {
      * from the server in response to a patchesDoc request.
      */
     saveCommittedChanges(docId: string, changes: Change[], sentPendingRange?: [number, number]): Promise<void>;
+    /**
+     * List all documents in the store.
+     * @param includeDeleted - Whether to include deleted documents.
+     * @returns The list of documents.
+     */
     listDocs(includeDeleted?: boolean): Promise<TrackedDoc[]>;
+    /**
+     * Track a document.
+     * @param docIds - The IDs of the documents to track.
+     */
     trackDocs(docIds: string[]): Promise<void>;
+    /**
+     * Untrack a document.
+     * @param docIds - The IDs of the documents to untrack.
+     */
     untrackDocs(docIds: string[]): Promise<void>;
     /**
      * Tell me the last committed revision you have *and* the highest