@dabble/patches 0.1.1

package/dist/client/PatchDoc.d.ts

@@ -0,0 +1,85 @@
+import type { Change, PatchSnapshot } from '../types.js';
+/**
+ * Represents a document synchronized using JSON patches.
+ * Manages committed state, pending (local-only) changes, and
+ * changes currently being sent to the server.
+ */
+export declare class PatchDoc<T extends object> {
+    private _state;
+    private _committedState;
+    private _committedRev;
+    private _pendingChanges;
+    private _sendingChanges;
+    private _changeMetadata;
+    /** 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. */
+    readonly onChange: import("../event-signal.js").Signal<(change: Change) => void>;
+    /** Subscribe to be notified whenever state changes from any source. */
+    readonly onUpdate: import("../event-signal.js").Signal<(newState: T) => void>;
+    /**
+     * Creates an instance of PatchDoc.
+     * @param initialState Optional initial state.
+     * @param initialMetadata Optional metadata to add to generated changes.
+     */
+    constructor(initialState?: T, initialMetadata?: Record<string, any>);
+    /** Current local state (committed + sending + pending). */
+    get state(): T;
+    /** Last committed revision number from the server. */
+    get committedRev(): number;
+    /** Are there changes currently awaiting server confirmation? */
+    get isSending(): boolean;
+    /** Are there local changes that haven't been sent yet? */
+    get hasPending(): boolean;
+    /**
+     * Basic export for potential persistence (may lose sending state).
+     */
+    export(): PatchSnapshot<T>;
+    /**
+     * Basic import for potential persistence.
+     * Resets any `_sendingChanges` state and treats all imported changes as pending.
+     */
+    import(snapshot: PatchSnapshot<T>): void;
+    /**
+     * Sets metadata to be added to future changes.
+     * @param metadata Metadata to be added to future changes.
+     */
+    setChangeMetadata(metadata: Record<string, any>): void;
+    /**
+     * Applies an update to the local state, generating a patch and adding it to pending changes.
+     * @param mutator Function modifying a draft state.
+     * @returns The generated Change object or null if no changes occurred.
+     */
+    change(mutator: (draft: T) => void): Change | null;
+    /**
+     * Retrieves pending changes and marks them as sending.
+     * @returns Array of changes ready to be sent to the server.
+     * @throws Error if changes are already being sent.
+     */
+    getUpdatesForServer(): Change[];
+    /**
+     * Processes the server's response to a batch of changes sent via `getUpdatesForServer`.
+     * @param serverCommit The array of committed changes from the server.
+     *                     Expected to be empty (`[]`) if the sent batch was a no-op,
+     *                     or contain a single `Change` object representing the batch commit.
+     * @throws Error if the input format is unexpected or application fails.
+     */
+    applyServerConfirmation(serverCommit: Change[]): void;
+    /**
+     * Applies incoming changes from the server that were *not* initiated by this client.
+     * @param externalServerChanges An array of sequential changes from the server.
+     */
+    applyExternalServerUpdate(externalServerChanges: Change[]): void;
+    /**
+     * Handles the scenario where sending changes to the server failed.
+     * Moves the changes that were in the process of being sent back to the
+     * beginning of the pending queue to be retried later.
+     */
+    handleSendFailure(): void;
+    /** Recalculates _state from _committedState + _sendingChanges + _pendingChanges */
+    private _recalculateLocalState;
+    /**
+     * @deprecated Use export() - kept for backward compatibility if needed.
+     */
+    toJSON(): PatchSnapshot<T>;
+}

package/dist/client/PatchDoc.js

@@ -0,0 +1,299 @@
+import { createId } from 'crypto-id';
+import { signal } from '../event-signal.js';
+import { createJSONPatch } from '../json-patch/createJSONPatch.js';
+import { applyChanges, rebaseChanges } from '../utils.js';
+/**
+ * Represents a document synchronized using JSON patches.
+ * Manages committed state, pending (local-only) changes, and
+ * changes currently being sent to the server.
+ */
+export class PatchDoc {
+    /**
+     * Creates an instance of PatchDoc.
+     * @param initialState Optional initial state.
+     * @param initialMetadata Optional metadata to add to generated changes.
+     */
+    constructor(initialState = {}, initialMetadata = {}) {
+        this._pendingChanges = []; // Changes made locally, not yet sent
+        this._sendingChanges = []; // Changes sent to server, awaiting confirmation
+        this._changeMetadata = {};
+        /** Subscribe to be notified before local state changes. */
+        this.onBeforeChange = signal();
+        /** Subscribe to be notified after local state changes are applied. */
+        this.onChange = signal();
+        /** Subscribe to be notified whenever state changes from any source. */
+        this.onUpdate = signal();
+        // Use structuredClone for robust deep cloning
+        this._committedState = structuredClone(initialState);
+        this._state = structuredClone(initialState);
+        this._committedRev = 0;
+        this._changeMetadata = initialMetadata;
+    }
+    /** Current local state (committed + sending + pending). */
+    get state() {
+        return this._state;
+    }
+    /** Last committed revision number from the server. */
+    get committedRev() {
+        return this._committedRev;
+    }
+    /** Are there changes currently awaiting server confirmation? */
+    get isSending() {
+        return this._sendingChanges.length > 0;
+    }
+    /** Are there local changes that haven't been sent yet? */
+    get hasPending() {
+        return this._pendingChanges.length > 0;
+    }
+    /**
+     * Basic export for potential persistence (may lose sending state).
+     */
+    export() {
+        return {
+            state: this._committedState,
+            rev: this._committedRev,
+            // Includes sending and pending changes. On import, all become pending.
+            changes: [...this._sendingChanges, ...this._pendingChanges],
+        };
+    }
+    /**
+     * Basic import for potential persistence.
+     * Resets any `_sendingChanges` state and treats all imported changes as pending.
+     */
+    import(snapshot) {
+        this._committedState = structuredClone(snapshot.state); // Use structuredClone
+        this._committedRev = snapshot.rev;
+        this._pendingChanges = snapshot.changes ?? []; // All imported changes become pending
+        this._sendingChanges = []; // Reset sending state on import
+        this._recalculateLocalState();
+        this.onUpdate.emit(this._state);
+    }
+    /**
+     * Sets metadata to be added to future changes.
+     * @param metadata Metadata to be added to future changes.
+     */
+    setChangeMetadata(metadata) {
+        this._changeMetadata = metadata;
+    }
+    /**
+     * Applies an update to the local state, generating a patch and adding it to pending changes.
+     * @param mutator Function modifying a draft state.
+     * @returns The generated Change object or null if no changes occurred.
+     */
+    change(mutator) {
+        const patch = createJSONPatch(this._state, mutator);
+        if (patch.ops.length === 0) {
+            return null;
+        }
+        const rev = this._pendingChanges[this._pendingChanges.length - 1]?.rev ??
+            this._sendingChanges[this._sendingChanges.length - 1]?.rev ??
+            this._committedRev;
+        // Note: Client-side 'rev' is just for local ordering and might be removed.
+        // It's the baseRev that matters for sending.
+        const change = {
+            id: createId(),
+            ops: patch.ops,
+            rev,
+            baseRev: this._committedRev, // Based on the last known committed state
+            created: Date.now(),
+            ...(Object.keys(this._changeMetadata).length > 0 && { metadata: { ...this._changeMetadata } }),
+        };
+        this.onBeforeChange.emit(change);
+        // Apply to local state immediately
+        this._state = patch.apply(this._state);
+        this._pendingChanges.push(change);
+        this.onChange.emit(change);
+        this.onUpdate.emit(this._state);
+        return change;
+    }
+    /**
+     * Retrieves pending changes and marks them as sending.
+     * @returns Array of changes ready to be sent to the server.
+     * @throws Error if changes are already being sent.
+     */
+    getUpdatesForServer() {
+        if (this.isSending) {
+            // It's generally simpler if the client waits for confirmation before sending more.
+            // If overlapping requests are needed, state management becomes much more complex.
+            throw new Error('Cannot get updates while previous batch is awaiting confirmation.');
+        }
+        if (!this.hasPending) {
+            return [];
+        }
+        this._sendingChanges = this._pendingChanges;
+        this._pendingChanges = [];
+        // Ensure the baseRev is set correctly based on the committedRev *at the time of sending*
+        // (The update method already does this, but double-check if logic changes)
+        this._sendingChanges.forEach(change => {
+            change.baseRev = this._committedRev;
+        });
+        return this._sendingChanges;
+    }
+    /**
+     * Processes the server's response to a batch of changes sent via `getUpdatesForServer`.
+     * @param serverCommit The array of committed changes from the server.
+     *                     Expected to be empty (`[]`) if the sent batch was a no-op,
+     *                     or contain a single `Change` object representing the batch commit.
+     * @throws Error if the input format is unexpected or application fails.
+     */
+    applyServerConfirmation(serverCommit) {
+        if (!Array.isArray(serverCommit)) {
+            throw new Error('Invalid server confirmation format: Expected an array.');
+        }
+        if (!this.isSending) {
+            console.warn('Received server confirmation but no changes were marked as sending.');
+            // Decide how to handle this - ignore? Apply if possible?
+            // For now, let's ignore if the server sent something unexpected.
+            if (serverCommit.length === 0)
+                return; // Ignore empty confirmations if not sending
+            // If server sent a commit unexpectedly, it implies a state mismatch. Hard to recover.
+            // Maybe apply cautiously if rev matches?
+            const commit = serverCommit[0];
+            if (commit && commit.rev === this._committedRev + 1) {
+                console.warn('Applying unexpected server commit cautiously.');
+                // Proceed as if confirmation was expected
+            }
+            else {
+                throw new Error('Received unexpected server commit with mismatching revision.');
+            }
+        }
+        if (serverCommit.length === 0) {
+            // Server confirmed the batch was a no-op (transformed away).
+            // The client's `_sendingChanges` are effectively discarded.
+            console.log('Server confirmed batch as no-op.');
+            this._sendingChanges = [];
+            // No change to _committedState or _committedRev
+            // Rebase any *new* pending changes against the *old* committed state (no server change occurred)
+            // Since baseRev didn't change, no rebase needed. Just recalculate state.
+        }
+        else if (serverCommit.length === 1) {
+            // Server confirmed the batch and returned the single resulting commit.
+            const committedChange = serverCommit[0];
+            if (!committedChange.rev || committedChange.rev <= this._committedRev) {
+                throw new Error(`Server commit invalid revision: ${committedChange.rev}, expected > ${this._committedRev}`);
+            }
+            // if (committedChange.rev !== this._committedRev + 1) {
+            //   // This indicates a potential issue, maybe missed updates?
+            //   // Or server batches multiple client requests?
+            //   // For now, strictly expect +1 unless server protocol changes.
+            //   console.warn(`Server commit revision ${committedChange.rev} !== expected ${this._committedRev + 1}`);
+            //   // Decide recovery strategy: request resync? Accept gap?
+            // }
+            // 1. Apply the server's committed change to our committed state
+            try {
+                this._committedState = applyChanges(this._committedState, [committedChange]);
+            }
+            catch (error) {
+                console.error('Failed to apply server commit to committed state:', error);
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                throw new Error(`Critical sync error applying server commit: ${errorMessage}`);
+            }
+            // 2. Update committed revision
+            this._committedRev = committedChange.rev;
+            // 3. Discard the confirmed _sendingChanges
+            const confirmedSentChanges = this._sendingChanges;
+            this._sendingChanges = [];
+            // 4. Rebase any *new* pending changes (added after getUpdatesForServer was called)
+            //    against the change that the server *actually* applied.
+            if (this.hasPending) {
+                this._pendingChanges = rebaseChanges([committedChange], this._pendingChanges);
+            }
+        }
+        else {
+            throw new Error(`Unexpected server confirmation format: Expected 0 or 1 change, received ${serverCommit.length}`);
+        }
+        // 5. Recalculate the local state from the new committed state + rebased pending changes
+        this._recalculateLocalState();
+        // 6. Notify listeners
+        this.onUpdate.emit(this._state);
+    }
+    /**
+     * Applies incoming changes from the server that were *not* initiated by this client.
+     * @param externalServerChanges An array of sequential changes from the server.
+     */
+    applyExternalServerUpdate(externalServerChanges) {
+        if (externalServerChanges.length === 0) {
+            return;
+        }
+        const firstChange = externalServerChanges[0];
+        // Allow for gaps if server sends updates out of order, but warn.
+        if (firstChange.rev && firstChange.rev <= this._committedRev) {
+            console.warn(`Ignoring external server update starting at revision ${firstChange.rev} which is <= current committed ${this._committedRev}`);
+            return; // Ignore already processed or irrelevant changes
+        }
+        // if (firstChange.rev && firstChange.rev !== this._committedRev + 1) {
+        //   console.warn(`External server update starting at ${firstChange.rev} does not directly follow committed ${this._committedRev}`);
+        //   // Handle potential gaps - request resync? Apply cautiously?
+        // }
+        const lastChange = externalServerChanges[externalServerChanges.length - 1];
+        // 1. Apply to committed state
+        try {
+            this._committedState = applyChanges(this._committedState, externalServerChanges);
+        }
+        catch (error) {
+            console.error('Failed to apply external server update to committed state:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new Error(`Critical sync error applying external server update: ${errorMessage}`);
+        }
+        // 2. Update committed revision
+        if (lastChange.rev) {
+            this._committedRev = lastChange.rev;
+        }
+        else {
+            console.error('External server update missing revision on last change.');
+            // Cannot reliably update revision - potential state divergence
+        }
+        // 3. Rebase *both* sending and pending changes against the external changes
+        if (this.isSending) {
+            this._sendingChanges = rebaseChanges(externalServerChanges, this._sendingChanges);
+        }
+        if (this.hasPending) {
+            this._pendingChanges = rebaseChanges(externalServerChanges, this._pendingChanges);
+        }
+        // 4. Recalculate local state
+        this._recalculateLocalState();
+        // 5. Notify listeners
+        this.onUpdate.emit(this._state);
+    }
+    /**
+     * Handles the scenario where sending changes to the server failed.
+     * Moves the changes that were in the process of being sent back to the
+     * beginning of the pending queue to be retried later.
+     */
+    handleSendFailure() {
+        if (this.isSending) {
+            console.warn(`Handling send failure: Moving ${this._sendingChanges.length} changes back to pending queue.`);
+            // Prepend sending changes back to pending queue to maintain order and prioritize retry
+            this._pendingChanges.unshift(...this._sendingChanges);
+            this._sendingChanges = [];
+            // Do NOT recalculate state here, as the state didn't actually advance
+            // due to the failed send. The state should still reflect the last known
+            // good state + pending changes (which now includes the failed ones).
+        }
+        else {
+            console.warn('handleSendFailure called but no changes were marked as sending.');
+        }
+    }
+    /** Recalculates _state from _committedState + _sendingChanges + _pendingChanges */
+    _recalculateLocalState() {
+        try {
+            // Apply sending changes first, then pending changes over that result
+            // Note: The previous implementation combined them, which might be okay if applyChanges handles arrays,
+            // but separating them is clearer conceptually if applyChanges expects one state and one array of changes.
+            // Assuming applyChanges handles an array of changes correctly:
+            this._state = applyChanges(this._committedState, [...this._sendingChanges, ...this._pendingChanges]);
+        }
+        catch (error) {
+            console.error('CRITICAL: Error recalculating local state after update:', error);
+            // This indicates a potentially serious issue with patch application or rebasing logic.
+            // Re-throw the error to allow higher-level handling (e.g., trigger resync)
+            throw error;
+        }
+    }
+    /**
+     * @deprecated Use export() - kept for backward compatibility if needed.
+     */
+    toJSON() {
+        return this.export();
+    }
+}

package/dist/client/index.d.ts

@@ -0,0 +1,2 @@
+export { PatchDoc } from './PatchDoc';
+export type { Change, PatchSnapshot, VersionMetadata } from '../types';

package/dist/client/index.js

@@ -0,0 +1 @@
+export { PatchDoc } from './PatchDoc';

package/dist/event-signal.d.ts

@@ -0,0 +1,31 @@
+export type SignalSubscriber = (...args: any[]) => any;
+export type ErrorSubscriber = (error: Error) => any;
+export type Unsubscriber = () => void;
+type Args<T> = T extends (...args: infer A) => any ? A : never;
+export type Signal<T extends SignalSubscriber = SignalSubscriber> = {
+    (subscriber: T): Unsubscriber;
+    error: (errorListener: ErrorSubscriber) => Unsubscriber;
+    emit: (...args: Args<T>) => Promise<void>;
+    clear: () => void;
+};
+/**
+ * Creates a signal, a function that can be used to subscribe to events. The signal can be called with a subscriber
+ * function to register event listeners. It has methods for emitting events, handling errors, and managing subscriptions.
+ *
+ * @example
+ * const onLoad = signal<(data: MyData) => void>();
+ *
+ * // Subscribe to data
+ * onLoad((data) => console.log('loaded', data));
+ *
+ * // Subscribe to errors
+ * onLoad.error((error) => console.error('error', error));
+ *
+ * // Emit data to subscribers
+ * await onLoad.emit('data'); // logs 'loaded data'
+ *
+ * // Clear all subscribers
+ * onLoad.clear();
+ */
+export declare function signal<T extends SignalSubscriber = SignalSubscriber>(): Signal<T>;
+export {};

package/dist/event-signal.js

@@ -0,0 +1,40 @@
+/**
+ * Creates a signal, a function that can be used to subscribe to events. The signal can be called with a subscriber
+ * function to register event listeners. It has methods for emitting events, handling errors, and managing subscriptions.
+ *
+ * @example
+ * const onLoad = signal<(data: MyData) => void>();
+ *
+ * // Subscribe to data
+ * onLoad((data) => console.log('loaded', data));
+ *
+ * // Subscribe to errors
+ * onLoad.error((error) => console.error('error', error));
+ *
+ * // Emit data to subscribers
+ * await onLoad.emit('data'); // logs 'loaded data'
+ *
+ * // Clear all subscribers
+ * onLoad.clear();
+ */
+export function signal() {
+    const subscribers = new Set();
+    const errorListeners = new Set();
+    function signal(subscriber) {
+        subscribers.add(subscriber);
+        return () => subscribers.delete(subscriber);
+    }
+    signal.emit = async (...args) => {
+        const listeners = args[0] instanceof Error ? errorListeners : subscribers;
+        Array.from(listeners).map(listener => listener(...args));
+    };
+    signal.error = (errorListener) => {
+        errorListeners.add(errorListener);
+        return () => errorListeners.delete(errorListener);
+    };
+    signal.clear = () => {
+        subscribers.clear();
+        errorListeners.clear();
+    };
+    return signal;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { PatchDoc } from './client/PatchDoc.js';
+export type { Change, PatchSnapshot, PatchState, VersionMetadata } from './types';

package/dist/index.js

@@ -0,0 +1 @@
+export { PatchDoc } from './client/PatchDoc.js';

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

@@ -0,0 +1,126 @@
+/*!
+ * Based on work from
+ * https://github.com/mohayonao/json-touch-patch
+ * (c) 2018 mohayonao
+ *
+ * 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 { Delta } from '@dabble/delta';
+import type { ApplyJSONPatchOptions, JSONPatchOp, JSONPatchOpHandlerMap } from './types.js';
+export type PathLike = string | {
+    toString(): string;
+};
+export interface WriteOptions {
+    soft?: boolean;
+}
+/**
+ * A JSONPatch helps with creating and applying one or more "JSON patches". It can track one or more changes
+ * together which may form a single operation or transaction.
+ */
+export declare class JSONPatch {
+    ops: JSONPatchOp[];
+    custom: JSONPatchOpHandlerMap;
+    /**
+     * Create a new JSONPatch, optionally with an existing array of operations.
+     */
+    constructor(ops?: JSONPatchOp[], custom?: JSONPatchOpHandlerMap);
+    op(op: string, path: PathLike, value?: any, from?: PathLike, soft?: boolean): this;
+    /**
+     * Tests a value exists. If it doesn't, the patch is not applied.
+     */
+    test(path: PathLike, value: any): this;
+    /**
+     * Adds the value to an object or array, inserted before the given index.
+     */
+    add(path: PathLike, value: any, options?: WriteOptions): this;
+    /**
+     * Deletes the value at the given path or removes it from an array.
+     */
+    remove(path: PathLike): this;
+    /**
+     * Replaces a value (same as remove+add).
+     */
+    replace(path: PathLike, value: any, options?: WriteOptions): this;
+    /**
+     * Copies the value at `from` to `path`.
+     */
+    copy(from: PathLike, to: PathLike, options?: WriteOptions): this;
+    /**
+     * Moves the value at `from` to `path`.
+     */
+    move(from: PathLike, to: PathLike): this;
+    /**
+     * Increments a numeric value by 1 or the given amount.
+     */
+    increment(path: PathLike, value?: number): this;
+    /**
+     * Decrements a numeric value by 1 or the given amount.
+     */
+    decrement(path: PathLike, value?: number): this;
+    /**
+     * Flips a bit at the given index in a bitmask to the given value.
+     */
+    bit(path: PathLike, index: number, on: boolean): this;
+    /**
+     * Applies a delta to a text document.
+     */
+    text(path: PathLike, value: Delta | Delta['ops']): this;
+    /**
+     * Creates a patch from an object partial, updating each field. Set a field to undefined to delete it.
+     */
+    addUpdates(updates: {
+        [key: string]: any;
+    }, path?: string): this;
+    /**
+     * This will ensure an "add empty object" operation is created for each property along the path that does not exist.
+     */
+    addObjectsInPath(obj: any, path: PathLike): this;
+    /**
+     * Apply this patch to an object, returning a new object with the applied changes (or the same object if nothing
+     * changed in the patch). Optionally apply the page at the given path prefix.
+     */
+    apply<T>(obj: T, options?: ApplyJSONPatchOptions): T;
+    /**
+     * Transform the given patch against this one. This patch is considered to have happened first. Optionally provide
+     * the object these operations are being applied to if available to know for sure if a numerical path is an array
+     * index or object key. Otherwise, all numerical paths are treated as array indexes.
+     */
+    transform(patch: JSONPatch | JSONPatchOp[], obj?: any): this;
+    /**
+     * Create a patch which can reverse what this patch does. Because JSON Patches do not store previous values, you
+     * must provide the previous object to create a reverse patch.
+     */
+    invert(obj: any): this;
+    /**
+     * Compose/collapse patches into fewer operations.
+     */
+    compose(patch?: JSONPatch | JSONPatchOp[]): this;
+    /**
+     * Add two patches together.
+     */
+    concat(patch: JSONPatch | JSONPatchOp[]): this;
+    /**
+     * Returns an array of patch operations.
+     */
+    toJSON(): JSONPatchOp[];
+    /**
+     * Create a new JSONPatch with the provided JSON patch operations.
+     */
+    static fromJSON<T>(this: {
+        new (ops?: JSONPatchOp[], types?: JSONPatchOpHandlerMap): T;
+    }, ops?: JSONPatchOp[], types?: JSONPatchOpHandlerMap): T;
+}
+export type JSONPath<T> = T extends object ? T extends Array<infer U> ? {
+    readonly [K in keyof T & number]-?: JSONPathValue<U>;
+} : {
+    readonly [K in keyof T as T[K] extends Function ? never : K]-?: JSONPathValue<NonNullable<T[K]>>;
+} : never;
+export type JSONPathValue<T> = {
+    toString(): string;
+} & (T extends object ? JSONPath<T> : {});
+export declare function createJSONPath<T = unknown>(): JSONPath<T>;