@dabble/patches 0.5.3 → 0.5.4

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

@@ -1,8 +1,9 @@
 import { PatchesSnapshot, ChangeMutator, Change } from '../../types.js';
+import { SizeCalculator } from '../shared/changeBatching.js';
 import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../../json-patch/types.js';
 
-declare function makeChange<T = any>(snapshot: PatchesSnapshot<T>, mutator: ChangeMutator<T>, changeMetadata?: Record<string, any>, maxPayloadBytes?: number): Change[];
+declare function makeChange<T = any>(snapshot: PatchesSnapshot<T>, mutator: ChangeMutator<T>, changeMetadata?: Record<string, any>, maxStorageBytes?: number, sizeCalculator?: SizeCalculator): Change[];
 
 export { makeChange };

package/dist/algorithms/client/makeChange.js

@@ -3,7 +3,7 @@ import { createChange } from "../../data/change.js";
 import { createJSONPatch } from "../../json-patch/createJSONPatch.js";
 import { breakChanges } from "../shared/changeBatching.js";
 import { createStateFromSnapshot } from "./createStateFromSnapshot.js";
-function makeChange(snapshot, mutator, changeMetadata, maxPayloadBytes) {
+function makeChange(snapshot, mutator, changeMetadata, maxStorageBytes, sizeCalculator) {
   const pendingChanges = snapshot.changes;
   const pendingRev = pendingChanges[pendingChanges.length - 1]?.rev ?? snapshot.rev;
   const state = createStateFromSnapshot(snapshot);
@@ -19,8 +19,8 @@ function makeChange(snapshot, mutator, changeMetadata, maxPayloadBytes) {
     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) {
-    newChangesArray = breakChanges(newChangesArray, maxPayloadBytes);
+  if (maxStorageBytes) {
+    newChangesArray = breakChanges(newChangesArray, maxStorageBytes, sizeCalculator);
   }
   return newChangesArray;
 }

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

@@ -14,6 +14,6 @@ import '../../json-patch/types.js';
  *   - 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
  */
-declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxPayloadBytes?: number): Promise<[Change[], Change[]]>;
+declare function commitChanges(store: PatchesStoreBackend, docId: string, changes: ChangeInput[], sessionTimeoutMillis: number, options?: CommitChangesOptions, maxStorageBytes?: number): Promise<[Change[], Change[]]>;
 
 export { CommitChangesOptions, commitChanges };

package/dist/algorithms/server/commitChanges.js

@@ -6,7 +6,7 @@ import { getSnapshotAtRevision } from "./getSnapshotAtRevision.js";
 import { getStateAtRevision } from "./getStateAtRevision.js";
 import { handleOfflineSessionsAndBatches } from "./handleOfflineSessionsAndBatches.js";
 import { transformIncomingChanges } from "./transformIncomingChanges.js";
-async function commitChanges(store, docId, changes, sessionTimeoutMillis, options, maxPayloadBytes) {
+async function commitChanges(store, docId, changes, sessionTimeoutMillis, options, maxStorageBytes) {
   if (changes.length === 0) {
     return [[], []];
   }
@@ -68,7 +68,7 @@ async function commitChanges(store, docId, changes, sessionTimeoutMillis, option
       origin,
       true,
       // isOffline
-      maxPayloadBytes
+      maxStorageBytes
     );
     if (canFastForward) {
       await store.saveChanges(docId, incomingChanges);

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

@@ -13,9 +13,9 @@ import '../../json-patch/types.js';
  * @param batchId The batch identifier
  * @param origin The origin to use for created versions (default: 'offline-branch')
  * @param isOffline Whether these changes were created offline (metadata flag)
- * @param maxPayloadBytes If set, break collapsed changes that exceed this size
+ * @param maxStorageBytes If set, break collapsed changes that exceed this size
  * @returns The changes (collapsed into one if divergent, unchanged if fast-forward)
  */
-declare function handleOfflineSessionsAndBatches(store: PatchesStoreBackend, sessionTimeoutMillis: number, docId: string, changes: Change[], baseRev: number, batchId?: string, origin?: 'main' | 'offline-branch', isOffline?: boolean, maxPayloadBytes?: number): Promise<Change[]>;
+declare function handleOfflineSessionsAndBatches(store: PatchesStoreBackend, sessionTimeoutMillis: number, docId: string, changes: Change[], baseRev: number, batchId?: string, origin?: 'main' | 'offline-branch', isOffline?: boolean, maxStorageBytes?: number): Promise<Change[]>;
 
 export { handleOfflineSessionsAndBatches };

package/dist/algorithms/server/handleOfflineSessionsAndBatches.js

@@ -5,7 +5,7 @@ import { getISO, timestampDiff } from "../../utils/dates.js";
 import { applyChanges } from "../shared/applyChanges.js";
 import { breakChanges } from "../shared/changeBatching.js";
 import { getStateAtRevision } from "./getStateAtRevision.js";
-async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId, origin = "offline-branch", isOffline = true, maxPayloadBytes) {
+async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docId, changes, baseRev, batchId, origin = "offline-branch", isOffline = true, maxStorageBytes) {
   const groupId = batchId ?? createSortableId();
   const [lastVersion] = await store.listVersions(docId, {
     groupId,
@@ -61,8 +61,8 @@ async function handleOfflineSessionsAndBatches(store, sessionTimeoutMillis, docI
       firstChange.ops = [...firstChange.ops, ...nextChange.ops];
       return firstChange;
     });
-    if (maxPayloadBytes) {
-      return breakChanges([collapsed], maxPayloadBytes);
+    if (maxStorageBytes) {
+      return breakChanges([collapsed], maxStorageBytes);
     }
     return [collapsed];
   }

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

@@ -3,17 +3,55 @@ import '../../json-patch/JSONPatch.js';
 import '@dabble/delta';
 import '../../json-patch/types.js';
 
+/**
+ * Function that calculates the storage size of data.
+ * Used by change batching to determine if changes need to be split.
+ *
+ * Import pre-built calculators from '@dabble/patches/compression':
+ * - `compressedSizeBase64` - Uses actual LZ compression + base64
+ * - `compressedSizeUint8` - Uses actual LZ compression to binary
+ *
+ * Or provide your own (e.g., ratio estimate):
+ * ```typescript
+ * const ratioEstimate = (data) => getJSONByteSize(data) * 0.5;
+ * ```
+ */
+type SizeCalculator = (data: unknown) => number;
 /** Estimate JSON string byte size. */
 declare function getJSONByteSize(data: unknown): number;
 /**
- * Break changes into smaller changes so that each change's JSON string size never exceeds `maxBytes`.
+ * Break changes into smaller changes so that each change's storage 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
+ *
+ * @param changes - The changes to break apart
+ * @param maxBytes - Maximum storage size in bytes per change
+ * @param sizeCalculator - Custom size calculator (e.g., for compressed size)
+ */
+declare function breakChanges(changes: Change[], maxBytes: number, sizeCalculator?: SizeCalculator): Change[];
+/**
+ * Options for breaking changes into batches.
+ */
+interface BreakChangesIntoBatchesOptions {
+    /** Batch limit for wire (uncompressed JSON). Defaults to 1MB. */
+    maxPayloadBytes?: number;
+    /** Per-change storage limit. If exceeded, individual changes are split. */
+    maxStorageBytes?: number;
+    /** Custom size calculator for storage limit (e.g., compressed size). */
+    sizeCalculator?: SizeCalculator;
+}
+/**
+ * Break changes into batches for network transmission.
+ *
+ * Two distinct limits:
+ * - `maxPayloadBytes`: Controls batch size for wire transmission (uses uncompressed JSON size)
+ * - `maxStorageBytes`: Controls per-change splitting for backend storage (uses sizeCalculator if provided)
+ *
+ * @param changes - The changes to batch
+ * @param options - Batching options (or just maxPayloadBytes for backward compatibility)
  */
-declare function breakChanges(changes: Change[], maxBytes: number): Change[];
-/** Break changes into batches based on maxPayloadBytes. */
-declare function breakChangesIntoBatches(changes: Change[], maxPayloadBytes?: number): Change[][];
+declare function breakChangesIntoBatches(changes: Change[], options?: BreakChangesIntoBatchesOptions | number): Change[][];
 
-export { breakChanges, breakChangesIntoBatches, getJSONByteSize };
+export { type BreakChangesIntoBatchesOptions, type SizeCalculator, breakChanges, breakChangesIntoBatches, getJSONByteSize };

package/dist/algorithms/shared/changeBatching.js

@@ -10,22 +10,30 @@ function getJSONByteSize(data) {
     throw new Error("Error calculating JSON size: " + e);
   }
 }
-function breakChanges(changes, maxBytes) {
+function breakChanges(changes, maxBytes, sizeCalculator) {
   const results = [];
   for (const change of changes) {
-    results.push(...breakSingleChange(change, maxBytes));
+    results.push(...breakSingleChange(change, maxBytes, sizeCalculator));
   }
   return results;
 }
-function breakChangesIntoBatches(changes, maxPayloadBytes) {
-  if (!maxPayloadBytes || getJSONByteSize(changes) < maxPayloadBytes) {
-    return [changes];
+const DEFAULT_MAX_PAYLOAD_BYTES = 1e6;
+function breakChangesIntoBatches(changes, options) {
+  const opts = typeof options === "number" ? { maxPayloadBytes: options } : options ?? {};
+  const maxPayloadBytes = opts.maxPayloadBytes ?? DEFAULT_MAX_PAYLOAD_BYTES;
+  const { maxStorageBytes, sizeCalculator } = opts;
+  let processedChanges = changes;
+  if (maxStorageBytes) {
+    processedChanges = breakChanges(changes, maxStorageBytes, sizeCalculator);
+  }
+  if (getJSONByteSize(processedChanges) < maxPayloadBytes) {
+    return [processedChanges];
   }
   const batchId = createId(12);
   const batches = [];
   let currentBatch = [];
   let currentSize = 2;
-  for (const change of changes) {
+  for (const change of processedChanges) {
     const changeWithBatchId = { ...change, batchId };
     const individualActualSize = getJSONByteSize(changeWithBatchId);
     let itemsToProcess;
@@ -52,8 +60,14 @@ function breakChangesIntoBatches(changes, maxPayloadBytes) {
   }
   return batches;
 }
-function breakSingleChange(orig, maxBytes) {
-  if (getJSONByteSize(orig) <= maxBytes) return [orig];
+function getSizeForStorage(data, sizeCalculator) {
+  if (sizeCalculator) {
+    return sizeCalculator(data);
+  }
+  return getJSONByteSize(data);
+}
+function breakSingleChange(orig, maxBytes, sizeCalculator) {
+  if (getSizeForStorage(orig, sizeCalculator) <= maxBytes) return [orig];
   const byOps = [];
   let group = [];
   let rev = orig.rev;
@@ -64,17 +78,17 @@ function breakSingleChange(orig, maxBytes) {
   };
   for (const op of orig.ops) {
     const tentative = group.concat(op);
-    if (getJSONByteSize({ ...orig, ops: tentative }) > maxBytes) flush();
-    if (group.length === 0 && getJSONByteSize({ ...orig, ops: [op] }) > maxBytes) {
+    if (getSizeForStorage({ ...orig, ops: tentative }, sizeCalculator) > maxBytes) flush();
+    if (group.length === 0 && getSizeForStorage({ ...orig, ops: [op] }, sizeCalculator) > maxBytes) {
       if (op.op === "@txt" && op.value) {
-        const pieces = breakTextOp(orig, op, maxBytes, rev);
+        const pieces = breakTextOp(orig, op, maxBytes, rev, sizeCalculator);
         byOps.push(...pieces);
         if (pieces.length > 0) {
           rev = pieces[pieces.length - 1].rev + 1;
         }
         continue;
       } else if (op.op === "replace" || op.op === "add") {
-        const pieces = breakLargeValueOp(orig, op, maxBytes, rev);
+        const pieces = breakLargeValueOp(orig, op, maxBytes, rev, sizeCalculator);
         byOps.push(...pieces);
         if (pieces.length > 0) {
           rev = pieces[pieces.length - 1].rev + 1;
@@ -91,10 +105,10 @@ function breakSingleChange(orig, maxBytes) {
   flush();
   return byOps;
 }
-function breakTextOp(origChange, textOp, maxBytes, startRev) {
+function breakTextOp(origChange, textOp, maxBytes, startRev, sizeCalculator) {
   const results = [];
   let rev = startRev;
-  const baseSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: "" }] });
+  const baseSize = getSizeForStorage({ ...origChange, ops: [{ ...textOp, value: "" }] }, sizeCalculator);
   const budget = maxBytes - baseSize;
   const buffer = 20;
   const maxLength = Math.max(1, budget - buffer);
@@ -128,12 +142,15 @@ function breakTextOp(origChange, textOp, maxBytes, startRev) {
       testBatchOps.push({ retain: retainToPrefixCurrentPiece });
     }
     testBatchOps.push(op);
-    const testBatchSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: testBatchOps }] });
+    const testBatchSize = getSizeForStorage({ ...origChange, ops: [{ ...textOp, value: testBatchOps }] }, sizeCalculator);
     if (currentOpsForNextChangePiece.length > 0 && testBatchSize > maxBytes) {
       flushCurrentChangePiece();
     }
     const opStandaloneOps = retainToPrefixCurrentPiece > 0 ? [{ retain: retainToPrefixCurrentPiece }, op] : [op];
-    const opStandaloneSize = getJSONByteSize({ ...origChange, ops: [{ ...textOp, value: opStandaloneOps }] });
+    const opStandaloneSize = getSizeForStorage(
+      { ...origChange, ops: [{ ...textOp, value: opStandaloneOps }] },
+      sizeCalculator
+    );
     if (currentOpsForNextChangePiece.length === 0 && opStandaloneSize > maxBytes) {
       if (op.insert && typeof op.insert === "string") {
         const insertChunks = splitLargeInsertText(op.insert, maxLength, op.attributes);
@@ -178,11 +195,11 @@ function splitLargeInsertText(text, maxChunkLength, attributes) {
   }
   return results;
 }
-function breakLargeValueOp(origChange, op, maxBytes, startRev) {
+function breakLargeValueOp(origChange, op, maxBytes, startRev, sizeCalculator) {
   const results = [];
   let rev = startRev;
-  const baseOpSize = getJSONByteSize({ ...op, value: "" });
-  const baseChangeSize = getJSONByteSize({ ...origChange, ops: [{ ...op, value: "" }] }) - baseOpSize;
+  const baseOpSize = getSizeForStorage({ ...op, value: "" }, sizeCalculator);
+  const baseChangeSize = getSizeForStorage({ ...origChange, ops: [{ ...op, value: "" }] }, sizeCalculator) - baseOpSize;
   const valueBudget = maxBytes - baseChangeSize - 50;
   if (typeof op.value === "string" && op.value.length > 100) {
     const text = op.value;
@@ -212,7 +229,7 @@ function breakLargeValueOp(origChange, op, maxBytes, startRev) {
       const item = originalArray[i];
       const tentativeChunk = [...currentChunk, item];
       const tentativeOp = { ...op, value: tentativeChunk };
-      const tentativeChangeSize = getJSONByteSize({ ...origChange, ops: [tentativeOp] });
+      const tentativeChangeSize = getSizeForStorage({ ...origChange, ops: [tentativeOp] }, sizeCalculator);
       if (currentChunk.length > 0 && tentativeChangeSize > maxBytes) {
         const chunkOp = {};
         if (chunkStartIndex === 0) {

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

@@ -0,0 +1,12 @@
+declare function compress(uncompressed: string | null): string;
+declare function decompress(compressed: string | null): string | null;
+declare function compressToBase64(input: string | null): string;
+declare function decompressFromBase64(input: string | null): string | null;
+declare function compressToUTF16(input: string | null): string;
+declare function decompressFromUTF16(compressed: string | null): string | null;
+declare function compressToUint8Array(uncompressed: string | null): Uint8Array;
+declare function decompressFromUint8Array(compressed: Uint8Array | null): string | null;
+declare function compressToEncodedURIComponent(input: string | null): string;
+declare function decompressFromEncodedURIComponent(input: string | null): string | null;
+
+export { compress, compressToBase64, compressToEncodedURIComponent, compressToUTF16, compressToUint8Array, decompress, decompressFromBase64, decompressFromEncodedURIComponent, decompressFromUTF16, decompressFromUint8Array };