@dabble/patches 0.2.32 → 0.3.0

package/dist/types.d.ts

@@ -33,6 +33,14 @@ export interface PatchesState<T = any> {
 export interface PatchesSnapshot<T = any> extends PatchesState<T> {
     changes: Change[];
 }
+/**
+ * Represents the syncing state of a document.
+ * @property initial - The document is not syncing.
+ * @property updating - The document is syncing.
+ * @property null - The document is not syncing.
+ * @property Error - The document is syncing with an error.
+ */
+export type SyncingState = 'initial' | 'updating' | null | Error;
 /** Status options for a branch */
 export type BranchStatus = 'open' | 'closed' | 'merged' | 'archived' | 'abandoned';
 export interface Branch {
@@ -116,10 +124,4 @@ export interface ListVersionsOptions {
     /** Filter by the group ID (branch ID or offline batch ID). */
     groupId?: string;
 }
-export interface Deferred<T = void> {
-    promise: Promise<T>;
-    resolve: (value: T) => void;
-    reject: (reason?: any) => void;
-    status: 'pending' | 'fulfilled' | 'rejected';
-}
 export {};

package/dist/utils/concurrency.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Wrap a function which is blockable for a document.
+ * Also, a Typescript decorator for functions which are blockable.
+ */
+export declare function blockable<T extends (docId: string, ...args: any[]) => Promise<any>>(target: T): T;
+/**
+ * Wrap a function which blocks on a document.
+ * Also, a Typescript decorator for functions which block.
+ */
+export declare function blocking<T extends (docId: string, ...args: any[]) => Promise<any>>(target: T): T;
+/**
+ * Wrap a function which returns a response which is blockable for a document (e.g. fetch).
+ * Also, a Typescript decorator for functions whose response should be blocked when needed.
+ */
+export declare function blockableResponse<T extends (docId: string, ...args: any[]) => Promise<any>>(target: T): T;
+/**
+ * Wrap a function to only return the result of the first call.
+ *
+ * ### Examples:
+ * ```ts
+ * const getFromStorage = oneResult(async (key: string) => {
+ *   ...
+ * });
+ */
+export declare function singleInvocation<T extends (...args: any[]) => Promise<any>>(target: T): T;
+export declare function singleInvocation<T extends (...args: any[]) => Promise<any>>(matchOnFirstArg: boolean): (target: T) => T;

package/dist/utils/concurrency.js

@@ -0,0 +1,60 @@
+import { simplifiedConcurrency } from 'simplified-concurrency';
+const docIds = new Map();
+/**
+ * Make the concurrency be per-path to allow multiple records to be loaded and updated at the same time, keeping only
+ * the record's operations sequential with respect to other operations on the same record.
+ */
+function concurrency(docId) {
+    let concurrency = docIds.get(docId);
+    if (!concurrency) {
+        concurrency = simplifiedConcurrency();
+        docIds.set(docId, concurrency);
+    }
+    return concurrency;
+}
+/**
+ * Wrap a function which is blockable for a document.
+ * Also, a Typescript decorator for functions which are blockable.
+ */
+export function blockable(target) {
+    return function (...args) {
+        return concurrency(args[0]).blockFunction(target, args, this);
+    };
+}
+/**
+ * Wrap a function which blocks on a document.
+ * Also, a Typescript decorator for functions which block.
+ */
+export function blocking(target) {
+    return function (...args) {
+        return concurrency(args[0]).blockWhile(target.apply(this, args));
+    };
+}
+/**
+ * Wrap a function which returns a response which is blockable for a document (e.g. fetch).
+ * Also, a Typescript decorator for functions whose response should be blocked when needed.
+ */
+export function blockableResponse(target) {
+    return function (...args) {
+        return concurrency(args[0]).blockResponse(target.apply(this, args));
+    };
+}
+export function singleInvocation(matchOnFirstArgOrTarget) {
+    if (typeof matchOnFirstArgOrTarget === 'function') {
+        return singleInvocation(false)(matchOnFirstArgOrTarget);
+    }
+    return function (target) {
+        const promises = new Map();
+        return function (...args) {
+            const key = matchOnFirstArgOrTarget ? args[0] : 1;
+            if (promises.has(key))
+                return promises.get(key);
+            const promise = target.apply(this, args);
+            promises.set(key, promise);
+            promise.finally(() => {
+                promises.delete(key);
+            });
+            return promise;
+        };
+    };
+}

package/dist/utils/deferred.d.ts

@@ -0,0 +1,7 @@
+export interface Deferred<T = void> {
+    promise: Promise<T>;
+    resolve: (value: T) => void;
+    reject: (reason?: any) => void;
+    status: 'pending' | 'fulfilled' | 'rejected';
+}
+export declare function deferred<T = void>(): Deferred<T>;

package/dist/utils/deferred.js

@@ -0,0 +1,23 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.32",
+  "version": "0.3.0",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {
@@ -55,17 +55,23 @@
     "build": "svelte-package -i src",
     "prepare": "npm run build",
     "test": "vitest run",
-    "tdd": "vitest"
+    "tdd": "vitest",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix"
   },
   "dependencies": {
     "@dabble/delta": "^1.2.4",
-    "alphacounter": "^2.x",
-    "crypto-id": "^0.2.3",
-    "simple-peer": "^9.11.1"
+    "alphacounter": "^2.1.1",
+    "crypto-id": "^0.3.0",
+    "simple-peer": "^9.11.1",
+    "simplified-concurrency": "^0.2.0"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.3.11",
     "@types/simple-peer": "^9.11.8",
+    "@typescript-eslint/eslint-plugin": "^8.33.1",
+    "@typescript-eslint/parser": "^8.33.1",
+    "eslint": "^9.28.0",
     "fake-indexeddb": "^6.0.0",
     "prettier": "^3.5.3",
     "typescript": "^5.8.3",

package/dist/utils/breakChange.js

@@ -1,302 +0,0 @@
-import { Op } from '@dabble/delta';
-import { createId } from 'crypto-id';
-import { getJSONByteSize } from './getJSONByteSize.js'; // Import from new location
-/**
- * Break a single Change into multiple Changes so that
- * JSON.stringify(change).length 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({
-            ...orig,
-            id: createId(),
-            rev: rev++,
-            ops: group,
-            created: Date.now(),
-        });
-        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;
-    // Calculate the budget for the delta content itself
-    const baseSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: '' }] });
-    const budget = maxBytes - baseSize;
-    // Ensure maxLength for splitLargeInsert is at least 1, apply a smaller buffer
-    const buffer = 20; // Reduced buffer
-    const maxLength = Math.max(1, budget - buffer);
-    // Ensure deltaOps is always an array, handle both Delta objects and raw arrays
-    let deltaOps = [];
-    if (textOp.value) {
-        if (Array.isArray(textOp.value)) {
-            // Direct array of ops
-            deltaOps = textOp.value;
-        }
-        else if (textOp.value.ops && Array.isArray(textOp.value.ops)) {
-            // Delta object with ops property
-            deltaOps = textOp.value.ops;
-        }
-        else if (typeof textOp.value === 'object') {
-            // Convert object to array with single op
-            deltaOps = [textOp.value];
-        }
-    }
-    let currentOps = [];
-    let retain = 0;
-    // Helper to create a Change with current accumulated delta ops
-    const flushDelta = () => {
-        if (!currentOps.length)
-            return;
-        const newOp = {
-            ...textOp,
-            value: currentOps,
-        };
-        results.push({
-            ...origChange,
-            id: createId(),
-            rev: rev++,
-            ops: [newOp],
-            created: Date.now(),
-        });
-        currentOps = [];
-    };
-    for (const op of deltaOps) {
-        // Check if adding this op would exceed the size limit
-        const tentativeOps = [...currentOps, op];
-        const tentativeChange = {
-            ...origChange,
-            ops: [{ ...textOp, value: tentativeOps }],
-        };
-        // Add an initial retain op if we're starting a new group of ops and there were prior ops
-        if (currentOps.length === 0 && retain) {
-            currentOps.push({ retain });
-        }
-        if (getJSONByteSize(tentativeChange) > maxBytes) {
-            flushDelta();
-            // Handle the case where a single delta op is too large (e.g., very large text insert)
-            if (currentOps.length === 0 && getJSONByteSize({ ...origChange, ops: [op] }) > maxBytes) {
-                // Split large insert into chunks
-                const retainBeforeChunks = retain; // Capture retain position BEFORE these chunks
-                const [newRetain, chunks] = splitLargeInsert(op, retain, maxLength);
-                retain = newRetain; // Update overall retain state for ops *after* these chunks
-                for (let i = 0; i < chunks.length; i++) {
-                    const chunk = chunks[i];
-                    // Only add retain before the *first* chunk from splitLargeInsert
-                    if (i === 0 && retainBeforeChunks > 0) {
-                        currentOps = [{ retain: retainBeforeChunks }, chunk];
-                    }
-                    else {
-                        currentOps = [chunk];
-                    }
-                    flushDelta(); // Flushes the chunk (potentially with retain on first)
-                }
-                continue;
-            }
-        }
-        currentOps.push(op);
-        if (!op.delete) {
-            retain += Op.length(op);
-        }
-    }
-    // Flush any remaining ops
-    flushDelta();
-    return results;
-}
-/**
- * Split a large insert operation into multiple smaller ones
- */
-function splitLargeInsert(insertOp, retain, maxChunkSize) {
-    const results = [];
-    if (!insertOp.insert || typeof insertOp.insert !== 'string') {
-        throw new Error(`Single @txt operation exceeds maxBytes. Cannot split further.`);
-    }
-    const text = insertOp.insert;
-    // const attrs = insertOp.attributes || {}; // attrs not used currently
-    // Ensure maxChunkSize is positive
-    if (maxChunkSize <= 0) {
-        throw new Error(`Calculated maxChunkSize is <= 0, cannot split insert.`);
-    }
-    // Ensure chunkSize is at least 1 to prevent infinite loops
-    const targetChunkSize = Math.max(1, maxChunkSize);
-    const numChunks = Math.ceil(text.length / targetChunkSize);
-    const chunkSize = Math.ceil(text.length / numChunks);
-    for (let i = 0; i < text.length; i += chunkSize) {
-        const chunkText = text.slice(i, i + chunkSize);
-        const op = { ...insertOp, insert: chunkText }; // Keep original attrs
-        // For the first chunk, no retain is needed
-        // Retain calculation seems complex, let breakTextOp handle retains between chunks
-        // if (i !== 0) {
-        //   results.push({ retain });
-        // }
-        results.push(op);
-        // Retain is now managed by the caller (breakTextOp)
-        // retain += Op.length(op);
-    }
-    // Return just the ops, retain calculation happens in breakTextOp
-    return [retain, results]; // This return signature might need review based on usage
-}
-/**
- * Attempt to break a large value in a replace/add operation
- */
-function breakLargeValueOp(origChange, op, maxBytes, startRev) {
-    const results = [];
-    let rev = startRev;
-    // Calculate base size without the value to estimate budget for value chunks
-    const baseOpSize = getJSONByteSize({ ...op, value: '' });
-    const baseChangeSize = getJSONByteSize({ ...origChange, ops: [{ ...op, value: '' }] }) - baseOpSize;
-    const valueBudget = maxBytes - baseChangeSize - 50; // 50 bytes buffer for overhead
-    // Special case: if value is a string, we can split it into chunks
-    if (typeof op.value === 'string' && op.value.length > 100) {
-        // Only split reasonably large strings
-        const text = op.value;
-        // Ensure chunkSize is at least 1
-        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' }; // Default to add?
-            if (i === 0) {
-                // First chunk: use original op type (add/replace) and path
-                newOp.op = op.op;
-                newOp.path = op.path;
-                newOp.value = chunk;
-            }
-            else {
-                // Subsequent chunks: use 'add' to append to the string (assuming target is container)
-                // This assumes the path points to an array or object where subsequent adds make sense.
-                // A more robust solution might need context or use a specific 'patch' op.
-                // If path was `/foo/bar`, appending needs `/foo/bar/-` or similar if array?
-                // For now, let's assume path allows adding / maybe this needs a custom 'append' op?
-                // Reverting to a placeholder 'patch' op type needing server interpretation.
-                newOp.op = 'patch';
-                newOp.path = op.path; // Operate on the original path
-                newOp.appendString = chunk;
-            }
-            results.push({
-                ...origChange,
-                id: createId(),
-                rev: rev++,
-                ops: [newOp],
-                created: Date.now(),
-            });
-        }
-        return results;
-    }
-    else if (Array.isArray(op.value) && op.value.length > 1) {
-        // Special case: if value is an array, we can split it into smaller arrays
-        // This requires careful size checking per chunk
-        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) {
-                // Flush current chunk
-                const chunkOp = {};
-                if (chunkStartIndex === 0) {
-                    chunkOp.op = op.op;
-                    chunkOp.path = op.path;
-                    chunkOp.value = currentChunk;
-                }
-                else {
-                    // Append subsequent chunks - needs server support for 'appendArray'
-                    chunkOp.op = 'patch';
-                    chunkOp.path = op.path;
-                    chunkOp.appendArray = currentChunk;
-                }
-                results.push({
-                    ...origChange,
-                    id: createId(),
-                    rev: rev++,
-                    ops: [chunkOp],
-                    created: Date.now(),
-                });
-                currentChunk = [item]; // Start new chunk with current item
-                chunkStartIndex = i;
-            }
-            else {
-                currentChunk.push(item);
-            }
-        }
-        // Flush the last chunk
-        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({
-                ...origChange,
-                id: createId(),
-                rev: rev++,
-                ops: [chunkOp],
-                created: Date.now(),
-            });
-        }
-        return results;
-    }
-    // If we can't split it, throw an error
-    throw new Error(`Single operation of type ${op.op} (path: ${op.path}) exceeds maxBytes and can't be split further.`);
-}

package/dist/utils/getJSONByteSize.js

@@ -1,12 +0,0 @@
-/** Estimate JSON string byte size. */
-export function getJSONByteSize(data) {
-    // Basic estimation, might not be perfectly accurate due to encoding nuances
-    try {
-        return new TextEncoder().encode(JSON.stringify(data)).length;
-    }
-    catch (e) {
-        // Handle circular structures or other stringify errors
-        console.error('Error calculating JSON size:', e);
-        return Infinity; // Treat errors as infinitely large
-    }
-}