@dabble/patches 0.2.10 → 0.2.12

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/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/patchProxy.d.ts

@@ -0,0 +1,41 @@
+import { JSONPatch } from './JSONPatch.js';
+/**
+ * Creates a proxy object that can be used in two ways:
+ *
+ * 1.  **Path Generation:** When used without a `JSONPatch` instance, accessing properties
+ *     on the proxy generates a JSON Pointer path string via `toString()`. This allows
+ *     for type-safe path creation when using `JSONPatch` methods directly.
+ *     ```ts
+ *     const patch = new JSONPatch();
+ *     const proxy = createPatchProxy<MyType>();
+ *     patch.text(proxy.content, new Delta().insert('text')); // Path is '/content'
+ *     patch.increment(proxy.counter, 5);                     // Path is '/counter'
+ *     ```
+ *
+ * 2.  **Automatic Patch Generation:** When created with a target object and a `JSONPatch`
+ *     instance, modifying the proxy (setting properties, calling array methods like
+ *     `push`, `splice`, etc.) automatically generates the corresponding JSON Patch
+ *     operations and adds them to the provided `patch` instance.
+ *     ```ts
+ *     const patch = new JSONPatch();
+ *     const myObj = { name: { first: 'Alice' }, tags: ['a'] };
+ *     const proxy = createPatchProxy(myObj, patch);
+ *     proxy.name.first = 'Bob';  // Generates replace op
+ *     proxy.tags.push('b');      // Generates add op
+ *     ```
+ *
+ * The proxy behaves like the original value in most contexts due to the `valueOf` trap.
+ * For optional properties, use the non-null assertion operator (!) when setting values:
+ * ```ts
+ * interface User { middleName?: string }
+ * const proxy = createPatchProxy<User>(user, patch);
+ * proxy.middleName! = 'John';  // Assert middleName exists before setting
+ * ```
+ *
+ * @template T The type of the object to proxy.
+ * @param target The target object (required for automatic patch generation mode).
+ * @param patch The `JSONPatch` instance to add generated operations to (required for automatic patch generation mode).
+ * @returns A proxy object of type T.
+ */
+export declare function createPatchProxy<T>(): T;
+export declare function createPatchProxy<T>(target: T, patch: JSONPatch): T;

package/dist/json-patch/patchProxy.js

@@ -0,0 +1,125 @@
+// 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) {
+    // Call the internal implementation
+    return createPatchProxyInternal(target, patch);
+}
+// Internal implementation with the path parameter
+function createPatchProxyInternal(target, patch, path = '') {
+    // Always use an empty function as the proxy target
+    // This allows us to proxy any type of value, including primitives and undefined,
+    // and enables calling array methods like push/splice directly on array proxies.
+    return new Proxy(proxyFodder, {
+        get(_, prop) {
+            // Return the value directly for symbol properties (not relevant for JSON paths)
+            if (typeof prop === 'symbol') {
+                return target?.[prop];
+            }
+            // Handle toString specially to make properties work as PathLike
+            if (prop === 'toString') {
+                return function () {
+                    return path;
+                };
+            }
+            // Handle valueOf to make the proxy behave like the original value in most contexts
+            if (prop === 'valueOf') {
+                return function () {
+                    return target;
+                };
+            }
+            // --- Array Method Interception ---
+            if (Array.isArray(target)) {
+                switch (prop) {
+                    case 'push':
+                        return (...items) => {
+                            const index = target.length;
+                            for (let i = 0; i < items.length; i++) {
+                                patch?.add(`${path}/${index + i}`, items[i]);
+                            }
+                        };
+                    case 'pop':
+                        return () => {
+                            const index = target.length - 1;
+                            if (index >= 0) {
+                                patch?.remove(`${path}/${index}`);
+                            }
+                        };
+                    case 'shift':
+                        return () => {
+                            if (target.length > 0) {
+                                patch?.remove(`${path}/0`);
+                            }
+                        };
+                    case 'unshift':
+                        return (...items) => {
+                            for (let i = 0; i < items.length; i++) {
+                                patch?.add(`${path}/${i}`, items[i]);
+                            }
+                        };
+                    case 'splice':
+                        return (start, deleteCount, ...items) => {
+                            const actualStart = start < 0 ? Math.max(target.length + start, 0) : Math.min(start, target.length);
+                            const actualDeleteCount = Math.min(Math.max(deleteCount === undefined ? target.length - actualStart : deleteCount, 0), target.length - actualStart);
+                            // Remove deleted elements
+                            for (let i = 0; i < actualDeleteCount; i++) {
+                                patch?.remove(`${path}/${actualStart}`); // Path automatically adjusts for subsequent removes
+                            }
+                            // Add new elements
+                            for (let i = 0; i < items.length; i++) {
+                                patch?.add(`${path}/${actualStart + i}`, items[i]);
+                            }
+                        };
+                }
+            }
+            // --- End Array Method Interception ---
+            // Create a proxy for the property value if it's not an intercepted array method
+            // This handles objects, primitives, and undefined values uniformly
+            // Call the internal implementation recursively
+            return createPatchProxyInternal(target?.[prop], patch, `${path}/${String(prop)}`);
+        },
+        set(_, prop, value) {
+            // Ignore setting the 'length' property on arrays directly
+            if (Array.isArray(target) && prop === 'length') {
+                return true;
+            }
+            if (target?.[prop] === value)
+                return true;
+            const patchPath = `${path}/${String(prop)}`;
+            if (value === undefined) {
+                patch?.remove(patchPath);
+            }
+            else {
+                patch?.replace(patchPath, value);
+            }
+            return true;
+        },
+        deleteProperty(_, prop) {
+            if (target == null || prop in target) {
+                patch?.remove(`${path}/${String(prop)}`);
+            }
+            return true;
+        },
+        // Make the proxy appear to be the same type as the target
+        getPrototypeOf() {
+            return Object.getPrototypeOf(target);
+        },
+        // Support instanceof checks
+        isExtensible() {
+            return target != null && Object.isExtensible(target);
+        },
+        // Support Object.keys and other enumeration methods
+        ownKeys() {
+            return target != null && typeof target === 'object' ? Reflect.ownKeys(target) : [];
+        },
+        // Support property descriptor access
+        getOwnPropertyDescriptor(_, prop) {
+            if (target == null || typeof target !== 'object')
+                return undefined;
+            return Object.getOwnPropertyDescriptor(target, prop);
+        },
+        // Support Object.hasOwnProperty
+        has(_, prop) {
+            return target != null && typeof target === 'object' && prop in target;
+        },
+    });
+}

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

@@ -0,0 +1,2 @@
+import type { JSONPatchOpHandlerMap, Runner } from './types.js';
+export declare function runWithObject(object: any, allTypes: JSONPatchOpHandlerMap, shouldCache: boolean, callback: Runner): any;

package/dist/json-patch/state.js

@@ -0,0 +1,8 @@
+export function runWithObject(object, allTypes, shouldCache, callback) {
+    const state = {
+        root: { '': object },
+        types: allTypes,
+        cache: shouldCache ? new Set() : null,
+    };
+    return callback(state) || state.root[''];
+}

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

@@ -0,0 +1,19 @@
+/*!
+ * Based on work from
+ * https://github.com/Palindrom/JSONPatchOT
+ * (c) 2017 Tomek Wytrebowicz
+ *
+ * MIT license
+ * (c) 2022 Jacob Wright
+ *
+ *
+ * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
+ * all situaions. Please avoid using this syntax when using Operational Transformations.
+ */
+import type { JSONPatchOp, JSONPatchOpHandlerMap } from './types.js';
+/**
+ * Transform an array of JSON Patch operations against another array of JSON Patch operations. Returns a new array with
+ * transformed operations. Operations that change are cloned, making the results of this function immutable.
+ * `otherOps` are transformed over `thisOps` with thisOps considered to have happened first.
+ */
+export declare function transformPatch(obj: any, thisOps: JSONPatchOp[], otherOps: JSONPatchOp[], custom?: JSONPatchOpHandlerMap): JSONPatchOp[];

package/dist/json-patch/transformPatch.js

@@ -0,0 +1,37 @@
+/*!
+ * Based on work from
+ * https://github.com/Palindrom/JSONPatchOT
+ * (c) 2017 Tomek Wytrebowicz
+ *
+ * MIT license
+ * (c) 2022 Jacob Wright
+ *
+ *
+ * WARNING: using /array/- syntax to indicate the end of the array makes it impossible to transform arrays correctly in
+ * all situaions. Please avoid using this syntax when using Operational Transformations.
+ */
+import { getTypes } from './ops/index.js';
+import { runWithObject } from './state.js';
+import { getType } from './utils/getType.js';
+import { log } from './utils/log.js';
+/**
+ * Transform an array of JSON Patch operations against another array of JSON Patch operations. Returns a new array with
+ * transformed operations. Operations that change are cloned, making the results of this function immutable.
+ * `otherOps` are transformed over `thisOps` with thisOps considered to have happened first.
+ */
+export function transformPatch(obj, thisOps, otherOps, custom) {
+    const types = getTypes(custom);
+    return runWithObject(obj, types, false, state => {
+        return thisOps.reduce((otherOps, thisOp) => {
+            // transform ops with patch operation
+            const handler = getType(state, thisOp)?.transform;
+            if (typeof handler === 'function') {
+                otherOps = handler(state, thisOp, otherOps);
+            }
+            else {
+                log('No function to transform against for', thisOp.op);
+            }
+            return otherOps;
+        }, otherOps);
+    });
+}

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

@@ -0,0 +1,52 @@
+export interface JSONPatchOpHandler {
+    like: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
+    apply(state: State, path: string, valueOrFrom: any): string | void;
+    transform(state: State, other: JSONPatchOp, ops: JSONPatchOp[]): JSONPatchOp[];
+    invert(state: State, op: JSONPatchOp, value: any, changedObj: any, isIndex: boolean): JSONPatchOp;
+    compose?(state: State, value1: any, value2: any): any;
+}
+export interface JSONPatchOpHandlerMap {
+    [key: string]: JSONPatchOpHandler;
+}
+export interface ApplyJSONPatchOptions {
+    /**
+     * Do not reject patches if error occurs (partial patching)
+     */
+    partial?: boolean;
+    /**
+     * Throw an exception if an error occurs when patching
+     */
+    strict?: boolean;
+    /**
+     * Stop on error and return the original object (without throwing an exception)
+     */
+    rigid?: boolean;
+    /**
+     * Don't log errors when they occurs during patching, if strict is not true, errors will be logged if this is false
+     */
+    silent?: boolean;
+    /**
+     * Saves the patch that caused the error to this property of the options object
+     */
+    error?: JSONPatchOp;
+    /**
+     * Apply changes at a given path prefix
+     */
+    atPath?: string;
+}
+export interface JSONPatchOp {
+    op: string;
+    path: string;
+    from?: string;
+    value?: any;
+    soft?: boolean;
+}
+export interface Root {
+    '': any;
+}
+export type State = {
+    root: Root;
+    types: JSONPatchOpHandlerMap;
+    cache: Set<any> | null;
+};
+export type Runner = (state: State) => any;

package/dist/json-patch/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1 @@
+export declare function deepEqual(a: any, b: any): boolean;

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

@@ -0,0 +1,33 @@
+export function deepEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (!(a && b) || typeof a !== 'object' || typeof b !== 'object') {
+        return false;
+    }
+    if (a.length !== b.length) {
+        return false;
+    }
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b)) {
+            return false;
+        }
+        for (let i = 0, imax = a.length; i < imax; i++) {
+            if (!deepEqual(a[i], b[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    const aKeys = Object.keys(a);
+    if (aKeys.length !== Object.keys(b).length) {
+        return false;
+    }
+    for (let j = 0, jmax = aKeys.length; j < jmax; j++) {
+        const key = aKeys[j];
+        if (!deepEqual(a[key], b[key])) {
+            return false;
+        }
+    }
+    return true;
+}

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

@@ -0,0 +1,2 @@
+import type { ApplyJSONPatchOptions, JSONPatchOp, State } from '../types.js';
+export declare function exit(state: State, object: any, patch: JSONPatchOp, opts: ApplyJSONPatchOptions): any;

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

@@ -0,0 +1,4 @@
+export function exit(state, object, patch, opts) {
+    opts.error = patch;
+    return opts.partial && state.root ? state.root[''] : object;
+}

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

@@ -0,0 +1,2 @@
+import type { State } from '../types.js';
+export declare function get(state: State, path: string): any;

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

@@ -0,0 +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);
+    return target ? target[lastKey] : undefined;
+}

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

@@ -0,0 +1,2 @@
+import type { State } from '../types.js';
+export declare function getOpData(state: State, path: string, createMissingObjects?: boolean): any[];

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

@@ -0,0 +1,10 @@
+import { EMPTY, pluck } from './pluck.js';
+import { toKeys } from './toKeys.js';
+export function getOpData(state, path, createMissingObjects) {
+    const keys = toKeys(path);
+    const lastKey = keys[keys.length - 1];
+    let target = pluck(state, keys);
+    if (createMissingObjects)
+        target = target || EMPTY;
+    return [keys, lastKey, target];
+}

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

@@ -0,0 +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" | "copy" | "move" | "test";

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

@@ -0,0 +1,6 @@
+export function getType(state, patch) {
+    return state.types?.[patch.op];
+}
+export function getTypeLike(state, patch) {
+    return state.types?.[patch.op]?.like;
+}

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

@@ -0,0 +1,14 @@
+export * from './deepEqual.js';
+export * from './get.js';
+export * from './getOpData.js';
+export * from './getType.js';
+export * from './log.js';
+export * from './ops.js';
+export * from './paths.js';
+export * from './pluck.js';
+export * from './shallowCopy.js';
+export * from './softWrites.js';
+export * from './toArrayIndex.js';
+export * from './toKeys.js';
+export * from './updateArrayIndexes.js';
+export * from './updateArrayPath.js';

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

@@ -0,0 +1,14 @@
+export * from './deepEqual.js';
+export * from './get.js';
+export * from './getOpData.js';
+export * from './getType.js';
+export * from './log.js';
+export * from './ops.js';
+export * from './paths.js';
+export * from './pluck.js';
+export * from './shallowCopy.js';
+export * from './softWrites.js';
+export * from './toArrayIndex.js';
+export * from './toKeys.js';
+export * from './updateArrayIndexes.js';
+export * from './updateArrayPath.js';

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

@@ -0,0 +1,2 @@
+export declare function verbose(value: boolean): void;
+export declare function log(...rest: any[]): void;

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

@@ -0,0 +1,7 @@
+let displayLogs = false;
+export function verbose(value) {
+    displayLogs = value;
+}
+export function log(...rest) {
+    displayLogs && console.log(...rest);
+}

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

@@ -0,0 +1,14 @@
+import type { JSONPatchOp, State } from '../types.js';
+/**
+ * Check whether this operation is an add operation of some sort (add, copy, move).
+ */
+export declare function isAdd(state: State, op: JSONPatchOp, pathName: 'from' | 'path'): boolean;
+/**
+ * Transforms an array of ops, returning the original if there is no change, filtering out ops that are dropped.
+ */
+export declare function mapAndFilterOps(ops: JSONPatchOp[], iterator: (op: JSONPatchOp, index: number, breakAfter: (keepRest?: boolean) => {}) => JSONPatchOp | JSONPatchOp[] | null): JSONPatchOp[];
+/**
+ * Remove operations that apply to a value which was removed.
+ */
+export declare function updateRemovedOps(state: State, thisPath: string, otherOps: JSONPatchOp[], isRemove?: boolean, updatableObject?: boolean, opOp?: string, customHandler?: (op: JSONPatchOp) => any): JSONPatchOp[];
+export declare function transformRemove(state: State, thisPath: string, otherOps: JSONPatchOp[], isRemove?: boolean): JSONPatchOp[];