@dabble/patches 0.2.11 → 0.2.13

package/dist/client/Patches.d.ts

@@ -1,12 +1,14 @@
 import { type Unsubscriber } from '../event-signal.js';
 import type { PatchesStore } from '../persist/PatchesStore.js';
 import type { Change } from '../types.js';
-import { PatchesDoc } from './PatchesDoc.js';
+import { PatchesDoc, type PatchesDocOptions } from './PatchesDoc.js';
 export interface PatchesOptions {
     /** Persistence layer instance (e.g., new IndexedDBStore('my-db') or new InMemoryStore()). */
     store: PatchesStore;
     /** Initial metadata to attach to changes from this client (merged with per-doc metadata). */
     metadata?: Record<string, any>;
+    /** Document-level options to pass to each PatchesDoc instance */
+    docOptions?: PatchesDocOptions;
 }
 interface ManagedDoc<T extends object> {
     doc: PatchesDoc<T>;
@@ -20,6 +22,7 @@ interface ManagedDoc<T extends object> {
 export declare class Patches {
     protected options: PatchesOptions;
     protected docs: Map<string, ManagedDoc<any>>;
+    readonly docOptions: PatchesDocOptions;
     readonly store: PatchesStore;
     readonly trackedDocs: Set<string>;
     readonly onError: import("../event-signal.js").Signal<(error: Error, context?: {
@@ -99,6 +102,11 @@ export declare class Patches {
      * Should be called when shutting down the client.
      */
     close(): void;
+    /**
+     * Updates document options that will be applied to all new documents
+     * @param options - Options to merge with current docOptions
+     */
+    updateDocOptions(options: Partial<PatchesDocOptions>): void;
     /**
      * Sets up a listener for local changes on a PatchesDoc, saving pending changes to the store.
      * @param docId - The document ID being managed.

package/dist/client/Patches.js

@@ -36,6 +36,7 @@ export class Patches {
         };
         this.options = opts;
         this.store = opts.store;
+        this.docOptions = opts.docOptions ?? {};
         this.store.listDocs().then(docs => {
             this.trackDocs(docs.map(({ docId }) => docId));
         });
@@ -90,7 +91,7 @@ export class Patches {
         const snapshot = await this.store.getDoc(docId);
         const initialState = (snapshot?.state ?? {});
         const mergedMetadata = { ...this.options.metadata, ...opts.metadata };
-        const doc = new PatchesDoc(initialState, mergedMetadata);
+        const doc = new PatchesDoc(initialState, mergedMetadata, this.docOptions);
         doc.setId(docId);
         if (snapshot) {
             doc.import(snapshot);
@@ -191,6 +192,13 @@ export class Patches {
         // Close store connection
         void this.store.close();
     }
+    /**
+     * Updates document options that will be applied to all new documents
+     * @param options - Options to merge with current docOptions
+     */
+    updateDocOptions(options) {
+        Object.assign(this.docOptions, options);
+    }
     // --- Internal Handlers ---
     /**
      * Sets up a listener for local changes on a PatchesDoc, saving pending changes to the store.

package/dist/client/PatchesDoc.d.ts

@@ -1,6 +1,16 @@
 import { type Unsubscriber } from '../event-signal.js';
 import type { JSONPatch } from '../json-patch/JSONPatch.js';
 import type { Change, PatchesSnapshot } from '../types.js';
+/**
+ * Options for creating a PatchesDoc instance
+ */
+export interface PatchesDocOptions {
+    /**
+     * Maximum size in bytes for a single payload (network message).
+     * Changes exceeding this will be split into multiple smaller changes.
+     */
+    maxPayloadBytes?: number;
+}
 /**
  * Represents a document synchronized using JSON patches.
  * Manages committed state, pending (local-only) changes, and
@@ -14,6 +24,7 @@ export declare class PatchesDoc<T extends object = object> {
     protected _pendingChanges: Change[];
     protected _sendingChanges: Change[];
     protected _changeMetadata: Record<string, any>;
+    protected readonly _maxPayloadBytes?: number;
     /** Subscribe to be notified before local state changes. */
     readonly onBeforeChange: import("../event-signal.js").Signal<(change: Change) => void>;
     /** Subscribe to be notified after local state changes are applied. */
@@ -24,8 +35,9 @@ export declare class PatchesDoc<T extends object = object> {
      * Creates an instance of PatchesDoc.
      * @param initialState Optional initial state.
      * @param initialMetadata Optional metadata to add to generated changes.
+     * @param options Additional options for the document.
      */
-    constructor(initialState?: T, initialMetadata?: Record<string, any>);
+    constructor(initialState?: T, initialMetadata?: Record<string, any>, options?: PatchesDocOptions);
     /** The unique identifier for this document, once assigned. */
     get id(): string | null;
     /** Current local state (committed + sending + pending). */

package/dist/client/PatchesDoc.js

@@ -2,6 +2,7 @@ import { createId } from 'crypto-id';
 import { signal } from '../event-signal.js';
 import { createJSONPatch } from '../json-patch/createJSONPatch.js';
 import { applyChanges, rebaseChanges } from '../utils.js';
+import { breakChange } from '../utils/breakChange.js';
 /**
  * Represents a document synchronized using JSON patches.
  * Manages committed state, pending (local-only) changes, and
@@ -12,8 +13,9 @@ export class PatchesDoc {
      * Creates an instance of PatchesDoc.
      * @param initialState Optional initial state.
      * @param initialMetadata Optional metadata to add to generated changes.
+     * @param options Additional options for the document.
      */
-    constructor(initialState = {}, initialMetadata = {}) {
+    constructor(initialState = {}, initialMetadata = {}, options = {}) {
         this._id = null;
         this._pendingChanges = [];
         this._sendingChanges = [];
@@ -28,6 +30,7 @@ export class PatchesDoc {
         this._state = structuredClone(initialState);
         this._committedRev = 0;
         this._changeMetadata = initialMetadata;
+        this._maxPayloadBytes = options.maxPayloadBytes;
     }
     /** The unique identifier for this document, once assigned. */
     get id() {
@@ -113,8 +116,19 @@ export class PatchesDoc {
         this.onBeforeChange.emit(change);
         // Apply to local state immediately
         this._state = patch.apply(this._state);
-        this._pendingChanges.push(change);
-        this.onChange.emit(change);
+        if (this._maxPayloadBytes) {
+            // Check if the change needs to be split due to size
+            const changes = breakChange(change, this._maxPayloadBytes);
+            // Emit events for each change piece
+            for (const piece of changes) {
+                this._pendingChanges.push(piece);
+                this.onChange.emit(piece);
+            }
+        }
+        else {
+            this._pendingChanges.push(change);
+            this.onChange.emit(change);
+        }
         this.onUpdate.emit(this._state);
         return change;
     }

package/dist/client/PatchesHistoryClient.js

@@ -31,25 +31,6 @@ class LRUCache {
         this.cache.clear();
     }
 }
-/**
- * Simple event signal for update notifications (like in PatchesDoc)
- */
-class Signal {
-    constructor() {
-        this.listeners = new Set();
-    }
-    subscribe(cb) {
-        this.listeners.add(cb);
-        return () => this.listeners.delete(cb);
-    }
-    emit() {
-        for (const cb of this.listeners)
-            cb();
-    }
-    clear() {
-        this.listeners.clear();
-    }
-}
 /**
  * Client-side history/scrubbing interface for a document.
  * Read-only: allows listing versions, loading states/changes, and scrubbing.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { Delta } from '@dabble/delta';
 export * from './client/Patches.js';
 export * from './client/PatchesDoc.js';
-export * from './event-signal';
+export * from './event-signal.js';
 export * from './json-patch/JSONPatch.js';
 export type { ApplyJSONPatchOptions } from './json-patch/types.js';
 export type * from './persist/PatchesStore.js';
-export type * from './types';
+export type * from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { Delta } from '@dabble/delta';
 export * from './client/Patches.js';
 export * from './client/PatchesDoc.js';
-export * from './event-signal';
+export * from './event-signal.js';
 export * from './json-patch/JSONPatch.js';

package/dist/json-patch/JSONPatch.js

@@ -139,7 +139,7 @@ export class JSONPatch {
     addObjectsInPath(obj, path) {
         path = checkPath(path);
         const parts = path.split('/');
-        for (var i = 1; i < parts.length - 1; i++) {
+        for (let i = 1; i < parts.length - 1; i++) {
             const prop = parts[i];
             if (!obj || !obj[prop]) {
                 this.add(parts.slice(0, i + 1).join('/'), {});

package/dist/json-patch/createJSONPatch.d.ts

@@ -1,4 +1,4 @@
-import { JSONPatch } from './JSONPatch';
+import { JSONPatch } from './JSONPatch.js';
 /**
  * Creates a `JSONPatch` instance by tracking changes made to a proxy object within an updater function.
  *

package/dist/json-patch/createJSONPatch.js

@@ -1,5 +1,5 @@
-import { JSONPatch } from './JSONPatch';
-import { createPatchProxy } from './patchProxy';
+import { JSONPatch } from './JSONPatch.js';
+import { createPatchProxy } from './patchProxy.js';
 /**
  * Creates a `JSONPatch` instance by tracking changes made to a proxy object within an updater function.
  *

package/dist/json-patch/index.d.ts

@@ -5,5 +5,4 @@ export { applyBitmask, bitmask, combineBitmasks } from './ops/bitmask.js';
 export * as defaultOps from './ops/index.js';
 export { transformPatch } from './transformPatch.js';
 export * from './ops/index.js';
-export * from './ops/index.js';
 export type { ApplyJSONPatchOptions, JSONPatchOpHandlerMap as JSONPatchCustomTypes, JSONPatchOp } from './types.js';

package/dist/json-patch/index.js

@@ -4,5 +4,4 @@ export { invertPatch } from './invertPatch.js';
 export { applyBitmask, bitmask, combineBitmasks } from './ops/bitmask.js';
 export * as defaultOps from './ops/index.js';
 export { transformPatch } from './transformPatch.js';
-export * from './ops/index.js'; // Exports all ops: add, remove, etc.
 export * from './ops/index.js';

package/dist/json-patch/ops/index.d.ts

@@ -7,7 +7,6 @@ import { move } from './move.js';
 import { remove } from './remove.js';
 import { replace } from './replace.js';
 import { test } from './test.js';
-export * from './bitmask.js';
 export { add, bit, copy, increment, move, remove, replace, test };
 export declare function getTypes(custom?: JSONPatchOpHandlerMap): {
     test: import("../types.js").JSONPatchOpHandler;

package/dist/json-patch/ops/index.js

@@ -7,7 +7,7 @@ import { remove } from './remove.js';
 import { replace } from './replace.js';
 import { test } from './test.js';
 import { text } from './text.js';
-export * from './bitmask.js';
+// Export all patch operations
 export { add, bit, copy, increment, move, remove, replace, test };
 export function getTypes(custom) {
     return {

package/dist/json-patch/ops/text.js

@@ -10,7 +10,7 @@ export const text = {
         if (!delta || !Array.isArray(delta.ops)) {
             return 'Invalid delta';
         }
-        let existingData = get(state, path);
+        const existingData = get(state, path);
         let doc;
         if (Array.isArray(existingData)) {
             if (existingData.length && existingData[0].insert) {

package/dist/json-patch/patchProxy.d.ts

@@ -1,4 +1,4 @@
-import { JSONPatch } from './JSONPatch';
+import { JSONPatch } from './JSONPatch.js';
 /**
  * Creates a proxy object that can be used in two ways:
  *

package/dist/json-patch/patchProxy.js

@@ -1,3 +1,4 @@
+import { JSONPatch } from './JSONPatch.js';
 // We use a function as the target so that `push` and other array methods can be called without error.
 const proxyFodder = {};
 export function createPatchProxy(target, patch) {

package/dist/json-patch/utils/get.js

@@ -1,6 +1,6 @@
 import { getOpData } from './getOpData.js';
 export function get(state, path) {
     // eslint-disable-next-line no-unused-vars
-    const [keys, lastKey, target] = getOpData(state, path);
+    const [, lastKey, target] = getOpData(state, path);
     return target ? target[lastKey] : undefined;
 }

package/dist/json-patch/utils/getType.d.ts

@@ -1,3 +1,3 @@
 import type { JSONPatchOp, State } from '../types.js';
 export declare function getType(state: State, patch: JSONPatchOp): import("../types.js").JSONPatchOpHandler;
-export declare function getTypeLike(state: State, patch: JSONPatchOp): "replace" | "add" | "remove" | "move" | "copy" | "test";
+export declare function getTypeLike(state: State, patch: JSONPatchOp): "replace" | "add" | "remove" | "copy" | "move" | "test";

package/dist/net/PatchesSync.d.ts

@@ -1,8 +1,13 @@
 import { Patches } from '../client/Patches.js';
 import type { WebSocketOptions } from './websocket/WebSocketTransport.js';
 export interface PatchesSyncOptions {
+    /** WebSocket connection options */
     wsOptions?: WebSocketOptions;
-    maxBatchSize?: number;
+    /**
+     * Maximum size in bytes for a single payload (network message).
+     * Changes exceeding this will be automatically split.
+     */
+    maxPayloadBytes?: number;
 }
 export interface PatchesSyncState {
     online: boolean;

package/dist/net/PatchesSync.js

@@ -1,3 +1,4 @@
+import { Patches } from '../client/Patches.js';
 import { signal } from '../event-signal.js';
 import { breakIntoBatches } from '../utils/batching.js';
 import { PatchesWebSocket } from './websocket/PatchesWebSocket.js';
@@ -76,6 +77,10 @@ export class PatchesSync {
         this.ws = new PatchesWebSocket(url, options.wsOptions);
         this._state.online = onlineState.isOnline;
         this.trackedDocs = new Set(patches.trackedDocs);
+        // Set maxPayloadBytes on Patches docOptions if provided
+        if (options.maxPayloadBytes) {
+            patches.updateDocOptions({ maxPayloadBytes: options.maxPayloadBytes });
+        }
         // --- Event Listeners ---
         onlineState.onOnlineChange(this._handleOnlineChange);
         this.ws.onStateChange(this._handleConnectionChange);
@@ -233,7 +238,7 @@ export class PatchesSync {
                     return; // Nothing to flush
                 }
             }
-            const batches = breakIntoBatches(pending, this.options.maxBatchSize);
+            const batches = breakIntoBatches(pending, this.options.maxPayloadBytes);
             for (const batch of batches) {
                 if (!this.state.connected) {
                     throw new Error('Disconnected during flush');

package/dist/net/websocket/onlineState.d.ts

@@ -1,6 +1,6 @@
 declare class OnlineState {
     onOnlineChange: import("../../event-signal").Signal<(isOnline: boolean) => void>;
-    _isOnline: any;
+    _isOnline: boolean;
     constructor();
     get isOnline(): boolean;
     get isOffline(): boolean;

package/dist/server/PatchesServer.js

@@ -94,7 +94,7 @@ export class PatchesServer {
             await this._createVersion(docId, currentState, currentChanges);
         }
         // 3. Load committed changes *after* the client's baseRev for transformation and idempotency checks
-        let committedChanges = await this.store.listChanges(docId, {
+        const committedChanges = await this.store.listChanges(docId, {
             startAfter: baseRev,
             withoutBatchId: batchId,
         });

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { JSONPatchOp } from './json-patch/types';
+import type { JSONPatchOp } from './json-patch/types.js';
 export interface Change {
     /** Unique identifier for the change, generated client-side. */
     id: string;
@@ -10,10 +10,10 @@ export interface Change {
     baseRev?: number;
     /** Client-side timestamp when the change was created. */
     created: number;
-    /** Optional arbitrary metadata associated with the change. */
-    metadata?: Record<string, any>;
     /** Optional batch identifier for grouping changes that belong to the same client batch (for multi-batch offline/large edits). */
     batchId?: string;
+    /** Optional arbitrary metadata associated with the change. */
+    [metadata: string]: any;
 }
 /**
  * Represents the state of a document in the OT protocol.
@@ -49,7 +49,7 @@ export interface Branch {
     /** Current status of the branch. */
     status: BranchStatus;
     /** Optional arbitrary metadata associated with the branch record. */
-    metadata?: Record<string, any>;
+    [metadata: string]: any;
 }
 /**
  * Metadata, state snapshot, and included changes for a specific version.
@@ -74,6 +74,8 @@ export interface VersionMetadata {
     rev: number;
     /** The revision number on the main timeline before the changes that created this version. If this is an offline/branch version, this is the revision number of the source document where the branch was created and not . */
     baseRev: number;
+    /** Optional arbitrary metadata associated with the version. */
+    [metadata: string]: any;
 }
 /**
  * Options for listing committed server changes. *Always* ordered by revision number.

package/dist/utils/batching.d.ts

@@ -1,5 +1,3 @@
 import type { Change } from '../types.js';
-/** Estimate JSON string byte size. */
-export declare function getJSONByteSize(data: any): number;
-/** Break changes into batches based on maxBatchSize. */
-export declare function breakIntoBatches(changes: Change[], maxSize?: number): Change[][];
+/** Break changes into batches based on maxPayloadBytes. */
+export declare function breakIntoBatches(changes: Change[], maxPayloadBytes?: number): Change[][];

package/dist/utils/batching.js

@@ -1,12 +1,9 @@
 import { createId } from 'crypto-id';
-/** Estimate JSON string byte size. */
-export function getJSONByteSize(data) {
-    // Basic estimation, might not be perfectly accurate due to encoding nuances
-    return new TextEncoder().encode(JSON.stringify(data)).length;
-}
-/** Break changes into batches based on maxBatchSize. */
-export function breakIntoBatches(changes, maxSize) {
-    if (!maxSize || getJSONByteSize(changes) < maxSize) {
+import { breakChange } from './breakChange.js'; // Import from new file
+import { getJSONByteSize } from './getJSONByteSize.js'; // Import from new file
+/** Break changes into batches based on maxPayloadBytes. */
+export function breakIntoBatches(changes, maxPayloadBytes) {
+    if (!maxPayloadBytes || getJSONByteSize(changes) < maxPayloadBytes) {
         return [changes];
     }
     const batchId = createId(12);
@@ -16,20 +13,26 @@ export function breakIntoBatches(changes, maxSize) {
     for (const change of changes) {
         // Add batchId if breaking up
         const changeWithBatchId = { ...change, batchId };
-        const changeSize = getJSONByteSize(changeWithBatchId) + (currentBatch.length > 0 ? 1 : 0); // Add 1 for comma
-        // If a single change is too big, we have an issue (should be rare)
-        if (changeSize > maxSize && currentBatch.length === 0) {
-            console.error(`Single change ${change.id} (size ${changeSize}) exceeds maxBatchSize (${maxSize}). Sending as its own batch.`);
-            batches.push([changeWithBatchId]); // Send it anyway
-            continue;
+        const individualActualSize = getJSONByteSize(changeWithBatchId);
+        let itemsToProcess;
+        if (individualActualSize > maxPayloadBytes) {
+            itemsToProcess = breakChange(changeWithBatchId, maxPayloadBytes);
+        }
+        else {
+            itemsToProcess = [changeWithBatchId];
         }
-        if (currentSize + changeSize > maxSize) {
-            batches.push(currentBatch);
-            currentBatch = [];
-            currentSize = 2;
+        for (const item of itemsToProcess) {
+            const itemActualSize = getJSONByteSize(item);
+            const itemSizeForBatching = itemActualSize + (currentBatch.length > 0 ? 1 : 0);
+            if (currentBatch.length > 0 && currentSize + itemSizeForBatching > maxPayloadBytes) {
+                batches.push(currentBatch);
+                currentBatch = [];
+                currentSize = 2;
+            }
+            const actualItemContribution = itemActualSize + (currentBatch.length > 0 ? 1 : 0);
+            currentBatch.push(item);
+            currentSize += actualItemContribution;
         }
-        currentBatch.push(changeWithBatchId);
-        currentSize += changeSize;
     }
     if (currentBatch.length > 0) {
         batches.push(currentBatch);

package/dist/utils/breakChange.d.ts

@@ -0,0 +1,10 @@
+import type { Change } from '../types.js';
+/**
+ * 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 declare function breakChange(orig: Change, maxBytes: number): Change[];

package/dist/utils/breakChange.js

@@ -0,0 +1,302 @@
+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.d.ts

@@ -0,0 +1,2 @@
+/** Estimate JSON string byte size. */
+export declare function getJSONByteSize(data: any): number;

package/dist/utils/getJSONByteSize.js

@@ -0,0 +1,13 @@
+import { TextEncoder } from 'util'; // Node.js TextEncoder
+/** 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
+    }
+}

package/dist/utils.d.ts

@@ -7,7 +7,7 @@ import type { Change, Deferred } from './types.js';
  * @param changes - Array of changes to split
  * @returns A tuple containing [changes before baseRev, changes with and after baseRev]
  */
-export declare function splitChanges<T>(changes: Change[]): [Change[], Change[]];
+export declare function splitChanges(changes: Change[]): [Change[], Change[]];
 /**
  * Applies a sequence of changes to a state object.
  * Each change is applied in sequence using the applyPatch function.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dabble/patches",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "Immutable JSON Patch implementation based on RFC 6902 supporting operational transformation and last-writer-wins",
   "author": "Jacob Wright <jacwright@gmail.com>",
   "bugs": {
@@ -66,13 +66,13 @@
     "@dabble/delta": "^1.2.4"
   },
   "devDependencies": {
-    "@sveltejs/package": "^2.3.10",
+    "@sveltejs/package": "^2.3.11",
     "@types/simple-peer": "^9.11.8",
     "fake-indexeddb": "^6.0.0",
     "prettier": "^3.5.3",
     "typescript": "^5.8.3",
-    "vite": "^6.2.6",
+    "vite": "^6.3.5",
     "vite-plugin-dts": "^4.5.3",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.3"
   }
 }