@dabble/patches 0.3.2 → 0.4.1

package/dist/client/Patches.js

@@ -41,170 +41,170 @@ import { PatchesDoc } from './PatchesDoc.js';
  * Can be used standalone or with PatchesSync for network synchronization.
  */
 let Patches = (() => {
-    var _a;
     let _instanceExtraInitializers = [];
     let _openDoc_decorators;
-    return _a = class Patches {
-            constructor(opts) {
-                this.options = __runInitializers(this, _instanceExtraInitializers);
-                this.docs = new Map();
-                this.trackedDocs = new Set();
-                // Public signals
-                this.onError = signal();
-                this.onServerCommit = signal();
-                this.onTrackDocs = signal();
-                this.onUntrackDocs = signal();
-                this.onDeleteDoc = signal();
-                this.onChange = signal();
-                this.options = opts;
-                this.store = opts.store;
-                this.docOptions = opts.docOptions ?? {};
-                this.store.listDocs().then(docs => {
-                    this.trackDocs(docs.map(({ docId }) => docId));
-                });
-            }
-            // --- Public API Methods ---
-            /**
-             * Tracks the given document IDs, adding them to the set of tracked documents and notifying listeners.
-             * Tracked docs are kept in sync with the server, even when not open locally.
-             * This allows for background syncing and updates of unopened documents.
-             * @param docIds - Array of document IDs to track.
-             */
-            async trackDocs(docIds) {
-                docIds = docIds.filter(id => !this.trackedDocs.has(id));
-                if (!docIds.length)
-                    return;
-                docIds.forEach(this.trackedDocs.add, this.trackedDocs);
-                this.onTrackDocs.emit(docIds);
-                await this.store.trackDocs(docIds);
-            }
-            /**
-             * Untracks the given document IDs, removing them from the set of tracked documents and notifying listeners.
-             * Untracked docs will no longer be kept in sync with the server, even if not open locally.
-             * Closes any open docs and removes them from the store.
-             * @param docIds - Array of document IDs to untrack.
-             */
-            async untrackDocs(docIds) {
-                docIds = docIds.filter(id => this.trackedDocs.has(id));
-                if (!docIds.length)
-                    return;
-                docIds.forEach(this.trackedDocs.delete, this.trackedDocs);
-                this.onUntrackDocs.emit(docIds);
-                // Close any open PatchesDoc instances first
-                const closedPromises = docIds.filter(id => this.docs.has(id)).map(id => this.closeDoc(id)); // closeDoc removes from this.docs map
-                await Promise.all(closedPromises);
-                // Remove from store
-                await this.store.untrackDocs(docIds);
-            }
-            /**
-             * Opens a document by ID, loading its state from the store and setting up change listeners.
-             * If the doc is already open, returns the existing instance.
-             * @param docId - The document ID to open.
-             * @param opts - Optional metadata to merge with the doc's metadata.
-             * @returns The opened PatchesDoc instance.
-             */
-            async openDoc(docId, opts = {}) {
-                const existing = this.docs.get(docId);
-                if (existing)
-                    return existing.doc;
-                // Ensure the doc is tracked before proceeding
-                await this.trackDocs([docId]);
-                // Load initial state from store
-                const snapshot = await this.store.getDoc(docId);
-                const initialState = (snapshot?.state ?? {});
-                const mergedMetadata = { ...this.options.metadata, ...opts.metadata };
-                const doc = new PatchesDoc(initialState, mergedMetadata, this.docOptions);
-                doc.setId(docId);
-                if (snapshot) {
-                    doc.import(snapshot);
-                }
-                // Set up local listener -> store
-                const unsubscribe = doc.onChange(changes => this._savePendingChanges(docId, changes));
-                this.docs.set(docId, { doc, unsubscribe });
-                return doc;
-            }
-            /**
-             * Closes an open document by ID, removing listeners and optionally untracking it.
-             * @param docId - The document ID to close.
-             * @param options - Optional: set untrack to true to also untrack the doc.
-             */
-            async closeDoc(docId, { untrack = false } = {}) {
-                const managed = this.docs.get(docId);
-                if (managed) {
-                    managed.unsubscribe();
-                    this.docs.delete(docId);
-                    if (untrack) {
-                        await this.untrackDocs([docId]);
-                    }
-                }
+    return class Patches {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+            _openDoc_decorators = [singleInvocation(true)];
+            __esDecorate(this, null, _openDoc_decorators, { kind: "method", name: "openDoc", static: false, private: false, access: { has: obj => "openDoc" in obj, get: obj => obj.openDoc }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        options = __runInitializers(this, _instanceExtraInitializers);
+        docs = new Map();
+        docOptions;
+        store;
+        trackedDocs = new Set();
+        // Public signals
+        onError = signal();
+        onServerCommit = signal();
+        onTrackDocs = signal();
+        onUntrackDocs = signal();
+        onDeleteDoc = signal();
+        onChange = signal();
+        constructor(opts) {
+            this.options = opts;
+            this.store = opts.store;
+            this.docOptions = opts.docOptions ?? {};
+            this.store.listDocs().then(docs => {
+                this.trackDocs(docs.map(({ docId }) => docId));
+            });
+        }
+        // --- Public API Methods ---
+        /**
+         * Tracks the given document IDs, adding them to the set of tracked documents and notifying listeners.
+         * Tracked docs are kept in sync with the server, even when not open locally.
+         * This allows for background syncing and updates of unopened documents.
+         * @param docIds - Array of document IDs to track.
+         */
+        async trackDocs(docIds) {
+            docIds = docIds.filter(id => !this.trackedDocs.has(id));
+            if (!docIds.length)
+                return;
+            docIds.forEach(this.trackedDocs.add, this.trackedDocs);
+            this.onTrackDocs.emit(docIds);
+            await this.store.trackDocs(docIds);
+        }
+        /**
+         * Untracks the given document IDs, removing them from the set of tracked documents and notifying listeners.
+         * Untracked docs will no longer be kept in sync with the server, even if not open locally.
+         * Closes any open docs and removes them from the store.
+         * @param docIds - Array of document IDs to untrack.
+         */
+        async untrackDocs(docIds) {
+            docIds = docIds.filter(id => this.trackedDocs.has(id));
+            if (!docIds.length)
+                return;
+            docIds.forEach(this.trackedDocs.delete, this.trackedDocs);
+            this.onUntrackDocs.emit(docIds);
+            // Close any open PatchesDoc instances first
+            const closedPromises = docIds.filter(id => this.docs.has(id)).map(id => this.closeDoc(id)); // closeDoc removes from this.docs map
+            await Promise.all(closedPromises);
+            // Remove from store
+            await this.store.untrackDocs(docIds);
+        }
+        /**
+         * Opens a document by ID, loading its state from the store and setting up change listeners.
+         * If the doc is already open, returns the existing instance.
+         * @param docId - The document ID to open.
+         * @param opts - Optional metadata to merge with the doc's metadata.
+         * @returns The opened PatchesDoc instance.
+         */
+        async openDoc(docId, opts = {}) {
+            const existing = this.docs.get(docId);
+            if (existing)
+                return existing.doc;
+            // Ensure the doc is tracked before proceeding
+            await this.trackDocs([docId]);
+            // Load initial state from store
+            const snapshot = await this.store.getDoc(docId);
+            const initialState = (snapshot?.state ?? {});
+            const mergedMetadata = { ...this.options.metadata, ...opts.metadata };
+            const doc = new PatchesDoc(initialState, mergedMetadata, this.docOptions);
+            doc.setId(docId);
+            if (snapshot) {
+                doc.import(snapshot);
             }
-            /**
-             * Deletes a document by ID, closing it if open, untracking it, and removing it from the store.
-             * Emits the onDeleteDoc signal.
-             * @param docId - The document ID to delete.
-             */
-            async deleteDoc(docId) {
-                // Close if open locally
-                if (this.docs.has(docId)) {
-                    await this.closeDoc(docId);
-                }
-                // Unsubscribe from server if tracked (deletes the doc from the store before the next step adds a tombstone)
-                if (this.trackedDocs.has(docId)) {
+            // Set up local listener -> store
+            const unsubscribe = doc.onChange(changes => this._savePendingChanges(docId, changes));
+            this.docs.set(docId, { doc, unsubscribe });
+            return doc;
+        }
+        /**
+         * Closes an open document by ID, removing listeners and optionally untracking it.
+         * @param docId - The document ID to close.
+         * @param options - Optional: set untrack to true to also untrack the doc.
+         */
+        async closeDoc(docId, { untrack = false } = {}) {
+            const managed = this.docs.get(docId);
+            if (managed) {
+                managed.unsubscribe();
+                this.docs.delete(docId);
+                if (untrack) {
                     await this.untrackDocs([docId]);
                 }
-                // Mark document as deleted in store (adds a tombstone until sync commits it)
-                await this.store.deleteDoc(docId);
-                this.onDeleteDoc.emit(docId);
             }
-            /**
-             * Gets an open document instance by ID, if it exists.
-             * Used by PatchesSync for applying server changes to open docs.
-             * @param docId - The document ID to get.
-             * @returns The PatchesDoc instance or undefined if not open.
-             */
-            getOpenDoc(docId) {
-                return this.docs.get(docId)?.doc;
+        }
+        /**
+         * Deletes a document by ID, closing it if open, untracking it, and removing it from the store.
+         * Emits the onDeleteDoc signal.
+         * @param docId - The document ID to delete.
+         */
+        async deleteDoc(docId) {
+            // Close if open locally
+            if (this.docs.has(docId)) {
+                await this.closeDoc(docId);
             }
-            /**
-             * Closes all open documents and cleans up listeners and store connections.
-             * Should be called when shutting down the client.
-             */
-            close() {
-                // Clean up local PatchesDoc listeners
-                this.docs.forEach(managed => managed.unsubscribe());
-                this.docs.clear();
-                // Close store connection
-                this.store.close();
-                this.onChange.clear();
-                this.onDeleteDoc.clear();
-                this.onUntrackDocs.clear();
-                this.onTrackDocs.clear();
-                this.onServerCommit.clear();
-                this.onError.clear();
+            // Unsubscribe from server if tracked (deletes the doc from the store before the next step adds a tombstone)
+            if (this.trackedDocs.has(docId)) {
+                await this.untrackDocs([docId]);
             }
-            /**
-             * Internal handler for saving pending changes to the store.
-             * @param docId - The document ID to save the changes for.
-             * @param changes - The changes to save.
-             */
-            async _savePendingChanges(docId, changes) {
-                try {
-                    await this.store.savePendingChanges(docId, changes);
-                    // Only after it is persisted, emit the change (for PatchesSync to flush)
-                    this.onChange.emit(docId, changes);
-                }
-                catch (err) {
-                    console.error(`Error saving pending changes for doc ${docId}:`, err);
-                    this.onError.emit(err, { docId });
-                }
+            // Mark document as deleted in store (adds a tombstone until sync commits it)
+            await this.store.deleteDoc(docId);
+            this.onDeleteDoc.emit(docId);
+        }
+        /**
+         * Gets an open document instance by ID, if it exists.
+         * Used by PatchesSync for applying server changes to open docs.
+         * @param docId - The document ID to get.
+         * @returns The PatchesDoc instance or undefined if not open.
+         */
+        getOpenDoc(docId) {
+            return this.docs.get(docId)?.doc;
+        }
+        /**
+         * Closes all open documents and cleans up listeners and store connections.
+         * Should be called when shutting down the client.
+         */
+        close() {
+            // Clean up local PatchesDoc listeners
+            this.docs.forEach(managed => managed.unsubscribe());
+            this.docs.clear();
+            // Close store connection
+            this.store.close();
+            this.onChange.clear();
+            this.onDeleteDoc.clear();
+            this.onUntrackDocs.clear();
+            this.onTrackDocs.clear();
+            this.onServerCommit.clear();
+            this.onError.clear();
+        }
+        /**
+         * Internal handler for saving pending changes to the store.
+         * @param docId - The document ID to save the changes for.
+         * @param changes - The changes to save.
+         */
+        async _savePendingChanges(docId, changes) {
+            try {
+                await this.store.savePendingChanges(docId, changes);
+                // Only after it is persisted, emit the change (for PatchesSync to flush)
+                this.onChange.emit(docId, changes);
             }
-        },
-        (() => {
-            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
-            _openDoc_decorators = [singleInvocation(true)];
-            __esDecorate(_a, null, _openDoc_decorators, { kind: "method", name: "openDoc", static: false, private: false, access: { has: obj => "openDoc" in obj, get: obj => obj.openDoc }, metadata: _metadata }, null, _instanceExtraInitializers);
-            if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
-        })(),
-        _a;
+            catch (err) {
+                console.error(`Error saving pending changes for doc ${docId}:`, err);
+                this.onError.emit(err, { docId });
+            }
+        }
+    };
 })();
 export { Patches };

package/dist/client/PatchesDoc.d.ts

@@ -1,6 +1,5 @@
 import { type Unsubscriber } from '../event-signal.js';
-import type { JSONPatch } from '../json-patch/JSONPatch.js';
-import type { Change, DeepRequired, PatchesSnapshot, SyncingState } from '../types.js';
+import type { Change, ChangeMutator, PatchesSnapshot, SyncingState } from '../types.js';
 /**
  * Options for creating a PatchesDoc instance
  */
@@ -68,10 +67,10 @@ export declare class PatchesDoc<T extends object = object> {
     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.
+     * @param mutator Function that uses JSONPatch methods with type-safe paths.
+     * @returns The generated Change objects.
      */
-    change(mutator: (draft: DeepRequired<T>, patch: JSONPatch) => void): Change[];
+    change(mutator: ChangeMutator<T>): Change[];
     /**
      * Returns the pending changes for this document.
      * @returns The pending changes.

package/dist/client/PatchesDoc.js

@@ -8,6 +8,20 @@ import { signal } from '../event-signal.js';
  * changes currently being sent to the server.
  */
 export class PatchesDoc {
+    _id = null;
+    _state;
+    _snapshot;
+    _changeMetadata = {};
+    _syncing = null;
+    _maxPayloadBytes;
+    /** Subscribe to be notified before local state changes. */
+    onBeforeChange = signal();
+    /** Subscribe to be notified after local state changes are applied. */
+    onChange = signal();
+    /** Subscribe to be notified whenever state changes from any source. */
+    onUpdate = signal();
+    /** Subscribe to be notified when syncing state changes. */
+    onSyncing = signal();
     /**
      * Creates an instance of PatchesDoc.
      * @param initialState Optional initial state.
@@ -15,17 +29,6 @@ export class PatchesDoc {
      * @param options Additional options for the document.
      */
     constructor(initialState = {}, initialMetadata = {}, options = {}) {
-        this._id = null;
-        this._changeMetadata = {};
-        this._syncing = null;
-        /** 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();
-        /** Subscribe to be notified when syncing state changes. */
-        this.onSyncing = signal();
         this._state = structuredClone(initialState);
         this._snapshot = { state: this._state, rev: 0, changes: [] };
         this._changeMetadata = initialMetadata;
@@ -83,8 +86,8 @@ export class PatchesDoc {
     }
     /**
      * 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.
+     * @param mutator Function that uses JSONPatch methods with type-safe paths.
+     * @returns The generated Change objects.
      */
     change(mutator) {
         const changes = makeChange(this._snapshot, mutator, this._changeMetadata, this._maxPayloadBytes);

package/dist/client/PatchesHistoryClient.js

@@ -1,9 +1,10 @@
 import { applyChanges } from '../algorithms/shared/applyChanges.js';
 import { signal } from '../event-signal.js';
 class LRUCache {
+    maxSize;
+    cache = new Map();
     constructor(maxSize) {
         this.maxSize = maxSize;
-        this.cache = new Map();
     }
     get(key) {
         const value = this.cache.get(key);
@@ -36,15 +37,18 @@ class LRUCache {
  * Read-only: allows listing versions, loading states/changes, and scrubbing.
  */
 export class PatchesHistoryClient {
+    api;
+    /** Document ID */
+    id;
+    /** Event signal for versions changes */
+    onVersionsChange = signal();
+    /** Event signal for state changes */
+    onStateChange = signal();
+    _versions = [];
+    _state = null;
+    cache = new LRUCache(6);
     constructor(id, api) {
         this.api = api;
-        /** Event signal for versions changes */
-        this.onVersionsChange = signal();
-        /** Event signal for state changes */
-        this.onStateChange = signal();
-        this._versions = [];
-        this._state = null;
-        this.cache = new LRUCache(6);
         this.id = id;
     }
     /** List of loaded versions */

package/dist/json-patch/JSONPatch.js

@@ -21,6 +21,8 @@ import { transformPatch } from './transformPatch.js';
  * together which may form a single operation or transaction.
  */
 export class JSONPatch {
+    ops;
+    custom;
     /**
      * Create a new JSONPatch, optionally with an existing array of operations.
      */

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

@@ -1,36 +1,33 @@
-import type { DeepRequired } from '../types.js';
+import type { ChangeMutator } from '../types.js';
 import { JSONPatch } from './JSONPatch.js';
 /**
- * Creates a `JSONPatch` instance by tracking changes made to a proxy object within an updater function.
+ * Creates a `JSONPatch` instance using a path-only proxy for type-safe operation generation.
  *
- * This provides a convenient way to generate patches based on direct object manipulation.
- * The `updater` function receives a proxy of the `target` object and the `JSONPatch` instance.
- * Modifications made to the proxy object (setting properties, calling array methods)
- * are automatically converted into JSON Patch operations and added to the patch instance.
- * You can also directly call methods on the `patch` instance within the updater.
+ * The mutator function receives a JSONPatch instance and a PathProxy for creating
+ * type-safe JSON Pointer paths. All modifications must be done through explicit
+ * JSONPatch methods - the path proxy will throw errors if mutation is attempted.
  *
  * @template T The type of the target object.
- * @param target The initial state of the object.
- * @param updater A function that receives a proxy of the target and a `JSONPatch` instance.
- *                Modify the proxy or call patch methods within this function to generate operations.
- * @returns A `JSONPatch` instance containing the operations generated within the updater.
+ * @param target The initial state of the object (used for type inference only).
+ * @param mutator A function that receives a JSONPatch instance and a PathProxy.
+ * @returns A `JSONPatch` instance containing the operations generated within the mutator.
  *
  * @example
  * ```ts
  * const myObj = { name: { first: 'Alice' }, age: 30, tags: ['a'] };
  *
- * const patch = createJSONPatch(myObj, (proxy, p) => {
- *   proxy.name.first = 'Bob'; // Generates a 'replace' op via the proxy
- *   proxy.tags.push('b');     // Generates an 'add' op via the proxy
- *   p.increment(proxy.age, 1); // Directly adds an 'increment' op
+ * const patch = createJSONPatch(myObj, (patch, path) => {
+ *   patch.replace(path.name.first, 'Bob');  // Type-safe path creation
+ *   patch.increment(path.age, 1);           // Explicit operations only
+ *   patch.add(path.tags[1], 'b');           // Array path handling
  * });
  *
  * console.log(patch.ops);
  * // [
  * //   { op: 'replace', path: '/name/first', value: 'Bob' },
- * //   { op: 'add', path: '/tags/1', value: 'b' },
- * //   { op: 'increment', path: '/age', value: 1 }
+ * //   { op: 'increment', path: '/age', value: 1 },
+ * //   { op: 'add', path: '/tags/1', value: 'b' }
  * // ]
  * ```
  */
-export declare function createJSONPatch<T>(target: T, updater: (proxy: DeepRequired<T>, patch: JSONPatch) => void): JSONPatch;
+export declare function createJSONPatch<T>(mutator: ChangeMutator<T>): JSONPatch;

package/dist/json-patch/createJSONPatch.js

@@ -1,41 +1,39 @@
 import { JSONPatch } from './JSONPatch.js';
-import { createPatchProxy } from './patchProxy.js';
+import { createPathProxy } from './pathProxy.js';
 /**
- * Creates a `JSONPatch` instance by tracking changes made to a proxy object within an updater function.
+ * Creates a `JSONPatch` instance using a path-only proxy for type-safe operation generation.
  *
- * This provides a convenient way to generate patches based on direct object manipulation.
- * The `updater` function receives a proxy of the `target` object and the `JSONPatch` instance.
- * Modifications made to the proxy object (setting properties, calling array methods)
- * are automatically converted into JSON Patch operations and added to the patch instance.
- * You can also directly call methods on the `patch` instance within the updater.
+ * The mutator function receives a JSONPatch instance and a PathProxy for creating
+ * type-safe JSON Pointer paths. All modifications must be done through explicit
+ * JSONPatch methods - the path proxy will throw errors if mutation is attempted.
  *
  * @template T The type of the target object.
- * @param target The initial state of the object.
- * @param updater A function that receives a proxy of the target and a `JSONPatch` instance.
- *                Modify the proxy or call patch methods within this function to generate operations.
- * @returns A `JSONPatch` instance containing the operations generated within the updater.
+ * @param target The initial state of the object (used for type inference only).
+ * @param mutator A function that receives a JSONPatch instance and a PathProxy.
+ * @returns A `JSONPatch` instance containing the operations generated within the mutator.
  *
  * @example
  * ```ts
  * const myObj = { name: { first: 'Alice' }, age: 30, tags: ['a'] };
  *
- * const patch = createJSONPatch(myObj, (proxy, p) => {
- *   proxy.name.first = 'Bob'; // Generates a 'replace' op via the proxy
- *   proxy.tags.push('b');     // Generates an 'add' op via the proxy
- *   p.increment(proxy.age, 1); // Directly adds an 'increment' op
+ * const patch = createJSONPatch(myObj, (patch, path) => {
+ *   patch.replace(path.name.first, 'Bob');  // Type-safe path creation
+ *   patch.increment(path.age, 1);           // Explicit operations only
+ *   patch.add(path.tags[1], 'b');           // Array path handling
  * });
  *
  * console.log(patch.ops);
  * // [
  * //   { op: 'replace', path: '/name/first', value: 'Bob' },
- * //   { op: 'add', path: '/tags/1', value: 'b' },
- * //   { op: 'increment', path: '/age', value: 1 }
+ * //   { op: 'increment', path: '/age', value: 1 },
+ * //   { op: 'add', path: '/tags/1', value: 'b' }
  * // ]
  * ```
  */
-export function createJSONPatch(target, updater) {
+export function createJSONPatch(mutator) {
     const patch = new JSONPatch();
-    // Use the specific overload of createPatchProxy that takes target and patch
-    updater(createPatchProxy(target, patch), patch);
+    // Create path-only proxy for type-safe path generation
+    const pathProxy = createPathProxy();
+    mutator(patch, pathProxy);
     return patch;
 }

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

@@ -0,0 +1,22 @@
+import type { PathProxy } from '../types.js';
+/**
+ * Creates a path proxy for generating JSON Pointer paths in a type-safe way.
+ * This proxy should ONLY be used for path creation with JSONPatch methods.
+ *
+ * Usage:
+ * ```ts
+ * const patch = new JSONPatch();
+ * const path = createPathProxy<MyType>();
+ * patch.replace(path.content, 'new text');      // Path is '/content'
+ * patch.increment(path.counter, 5);             // Path is '/counter'
+ * patch.add(path.items[0], newItem);            // Path is '/items/0'
+ * ```
+ *
+ * The proxy will throw errors if you attempt to set properties or delete properties.
+ * This prevents accidental mutation and ensures explicit patch operations are used.
+ *
+ * @template T The type of the object to create paths for.
+ * @returns A path proxy object.
+ */
+export declare const createPathProxy: <T>() => PathProxy<T>;
+export declare function pathProxy<T>(path?: string): PathProxy<T>;