@automerge/automerge-repo 1.0.5 → 1.0.6

package/dist/DocHandle.d.ts

@@ -80,6 +80,19 @@ export declare class DocHandle<T>//
      * @returns A set of heads representing the concurrent change that was made.
      */
     changeAt(heads: A.Heads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): string[] | undefined;
+    /** Merge another document into this document
+     *
+     * @param otherHandle - the handle of the document to merge into this one
+     *
+     * @remarks
+     * This is a convenience method for
+     * `handle.change(doc => A.merge(doc, otherHandle.docSync()))`. Any peers
+     * whom we are sharing changes with will be notified of the changes resulting
+     * from the merge.
+     *
+     * @throws if either document is not ready or if `otherHandle` is unavailable (`otherHandle.docSync() === undefined`)
+     */
+    merge(otherHandle: DocHandle<T>): void;
     unavailable(): void;
     /** `request` is called by the repo when the document is not found in storage
      * @hidden

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -309,6 +309,30 @@ export class DocHandle//
         });
         return resultHeads;
     }
+    /** Merge another document into this document
+     *
+     * @param otherHandle - the handle of the document to merge into this one
+     *
+     * @remarks
+     * This is a convenience method for
+     * `handle.change(doc => A.merge(doc, otherHandle.docSync()))`. Any peers
+     * whom we are sharing changes with will be notified of the changes resulting
+     * from the merge.
+     *
+     * @throws if either document is not ready or if `otherHandle` is unavailable (`otherHandle.docSync() === undefined`)
+     */
+    merge(otherHandle) {
+        if (!this.isReady() || !otherHandle.isReady()) {
+            throw new Error("Both handles must be ready to merge");
+        }
+        const mergingDoc = otherHandle.docSync();
+        if (!mergingDoc) {
+            throw new Error("The document to be merged in is null, aborting.");
+        }
+        this.update(doc => {
+            return A.merge(doc, mergingDoc);
+        });
+    }
     unavailable() {
         this.#machine.send(MARK_UNAVAILABLE);
     }

package/dist/Repo.d.ts

@@ -31,6 +31,22 @@ export declare class Repo extends EventEmitter<RepoEvents> {
      * to advertise interest in the document.
      */
     create<T>(): DocHandle<T>;
+    /** Create a new DocHandle by cloning the history of an existing DocHandle.
+     *
+     * @param clonedHandle - The handle to clone
+     *
+     * @remarks This is a wrapper around the `clone` function in the Automerge library.
+     * The new `DocHandle` will have a new URL but will share history with the original,
+     * which means that changes made to the cloned handle can be sensibly merged back
+     * into the original.
+     *
+     * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
+     * be notified of the newly created DocHandle.
+     *
+     * @throws if the cloned handle is not yet ready or if
+     * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
+     */
+    clone<T>(clonedHandle: DocHandle<T>): DocHandle<T>;
     /**
      * Retrieves a document by id. It gets data from the local system, but also emits a `document`
      * event to advertise interest in the document.

package/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AASlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAGnC,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IAuHjE,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IA0BzB;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,+CAA+C;IAC/C,YAAY,EAAE,YAAY,GACzB,SAAS,CAAC,CAAC,CAAC;IAgCf,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAchC;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AASlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAGnC,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IAuHjE,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IA0BzB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAuBnC;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,+CAA+C;IAC/C,YAAY,EAAE,YAAY,GACzB,SAAS,CAAC,CAAC,CAAC;IAgCf,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAchC;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}

package/dist/Repo.js

@@ -5,6 +5,7 @@ import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js
 import { parseAutomergeUrl, generateAutomergeUrl, isValidAutomergeUrl, parseLegacyUUID, } from "./DocUrl.js";
 import { DocHandle } from "./DocHandle.js";
 import { EventEmitter } from "eventemitter3";
+import { next as Automerge } from "@automerge/automerge";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -156,6 +157,37 @@ export class Repo extends EventEmitter {
         this.emit("document", { handle, isNew: true });
         return handle;
     }
+    /** Create a new DocHandle by cloning the history of an existing DocHandle.
+     *
+     * @param clonedHandle - The handle to clone
+     *
+     * @remarks This is a wrapper around the `clone` function in the Automerge library.
+     * The new `DocHandle` will have a new URL but will share history with the original,
+     * which means that changes made to the cloned handle can be sensibly merged back
+     * into the original.
+     *
+     * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
+     * be notified of the newly created DocHandle.
+     *
+     * @throws if the cloned handle is not yet ready or if
+     * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
+     */
+    clone(clonedHandle) {
+        if (!clonedHandle.isReady()) {
+            throw new Error(`Cloned handle is not yet in ready state.
+        (Try await handle.waitForReady() first.)`);
+        }
+        const sourceDoc = clonedHandle.docSync();
+        if (!sourceDoc) {
+            throw new Error("Cloned handle doesn't have a document.");
+        }
+        const handle = this.create();
+        handle.update((doc) => {
+            // we replace the document with the new cloned one
+            return Automerge.clone(sourceDoc);
+        });
+        return handle;
+    }
     /**
      * Retrieves a document by id. It gets data from the local system, but also emits a `document`
      * event to advertise interest in the document.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -65,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "09256d61e0e4e0afd5d8deb1e187b57cb2413e1e"
+  "gitHead": "088696831fed48c7a8a88109acd0465222dc8522"
 }

package/src/DocHandle.ts

@@ -28,7 +28,7 @@ import { encode } from "./helpers/cbor.js"
  * A `DocHandle` represents a document which is being managed by a {@link Repo}.
  * To obtain `DocHandle` use {@link Repo.find} or {@link Repo.create}.
  *
- * To modify the underlying document use either {@link DocHandle.change} or 
+ * To modify the underlying document use either {@link DocHandle.change} or
  * {@link DocHandle.changeAt}. These methods will notify the `Repo` that some
  * change has occured and the `Repo` will save any new changes to the
  * attached {@link StorageAdapter} and send sync messages to connected peers.
@@ -321,7 +321,7 @@ export class DocHandle<T> //
     return this.#doc
   }
 
-  /** `update` is called by the repo when we receive changes from the network 
+  /** `update` is called by the repo when we receive changes from the network
    * @hidden
    * */
   update(callback: (doc: A.Doc<T>) => A.Doc<T>) {
@@ -373,11 +373,37 @@ export class DocHandle<T> //
     return resultHeads
   }
 
+  /** Merge another document into this document
+   *
+   * @param otherHandle - the handle of the document to merge into this one
+   *
+   * @remarks
+   * This is a convenience method for
+   * `handle.change(doc => A.merge(doc, otherHandle.docSync()))`. Any peers
+   * whom we are sharing changes with will be notified of the changes resulting
+   * from the merge.
+   *
+   * @throws if either document is not ready or if `otherHandle` is unavailable (`otherHandle.docSync() === undefined`)
+   */
+  merge(otherHandle: DocHandle<T>) {
+    if (!this.isReady() || !otherHandle.isReady()) {
+      throw new Error("Both handles must be ready to merge")
+    }
+    const mergingDoc = otherHandle.docSync()
+    if (!mergingDoc) {
+      throw new Error("The document to be merged in is null, aborting.")
+    }
+
+    this.update(doc => {
+      return A.merge(doc, mergingDoc)
+    })
+  }
+
   unavailable() {
     this.#machine.send(MARK_UNAVAILABLE)
   }
 
-  /** `request` is called by the repo when the document is not found in storage 
+  /** `request` is called by the repo when the document is not found in storage
    * @hidden
    * */
   request() {

package/src/Repo.ts

@@ -15,7 +15,7 @@ import {
 
 import { DocHandle } from "./DocHandle.js"
 import { EventEmitter } from "eventemitter3"
-import bs58check from "bs58check"
+import { next as Automerge } from "@automerge/automerge"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -193,6 +193,44 @@ export class Repo extends EventEmitter<RepoEvents> {
     return handle
   }
 
+  /** Create a new DocHandle by cloning the history of an existing DocHandle.
+   *
+   * @param clonedHandle - The handle to clone
+   *
+   * @remarks This is a wrapper around the `clone` function in the Automerge library.
+   * The new `DocHandle` will have a new URL but will share history with the original, 
+   * which means that changes made to the cloned handle can be sensibly merged back 
+   * into the original. 
+   *
+   * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
+   * be notified of the newly created DocHandle.
+   *
+   * @throws if the cloned handle is not yet ready or if
+   * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
+   */
+  clone<T>(clonedHandle: DocHandle<T>) {
+    if (!clonedHandle.isReady()) {
+      throw new Error(
+        `Cloned handle is not yet in ready state.
+        (Try await handle.waitForReady() first.)`
+      )
+    }
+
+    const sourceDoc = clonedHandle.docSync()
+    if (!sourceDoc) {
+      throw new Error("Cloned handle doesn't have a document.")
+    }
+
+    const handle = this.create<T>()
+
+    handle.update((doc: Automerge.Doc<T>) => {
+      // we replace the document with the new cloned one
+      return Automerge.clone(sourceDoc)
+    })
+
+    return handle
+  }
+
   /**
    * Retrieves a document by id. It gets data from the local system, but also emits a `document`
    * event to advertise interest in the document.
@@ -267,7 +305,7 @@ export interface RepoConfig {
   sharePolicy?: SharePolicy
 }
 
-/** A function that determines whether we should share a document with a peer 
+/** A function that determines whether we should share a document with a peer
  *
  * @remarks
  * This function is called by the {@link Repo} every time a new document is created

package/test/Repo.test.ts

@@ -93,6 +93,65 @@ describe("Repo", () => {
       assert.equal(v?.foo, "bar")
     })
 
+    it("can clone a document", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change(d => {
+        d.foo = "bar"
+      })
+      const handle2 = repo.clone(handle)
+      assert.equal(handle2.isReady(), true)
+      assert.notEqual(handle.documentId, handle2.documentId)
+      assert.deepStrictEqual(handle.docSync(), handle2.docSync())
+      assert.deepStrictEqual(handle2.docSync(), { foo: "bar" })
+    })
+
+    it("the cloned documents are distinct", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change(d => {
+        d.foo = "bar"
+      })
+      const handle2 = repo.clone(handle)
+
+      handle.change(d => {
+        d.bar = "bif"
+      })
+      handle2.change(d => {
+        d.baz = "baz"
+      })
+
+      assert.notDeepStrictEqual(handle.docSync(), handle2.docSync())
+      assert.deepStrictEqual(handle.docSync(), { foo: "bar", bar: "bif" })
+      assert.deepStrictEqual(handle2.docSync(), { foo: "bar", baz: "baz" })
+    })
+
+    it("the cloned documents can merge", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change(d => {
+        d.foo = "bar"
+      })
+      const handle2 = repo.clone(handle)
+
+      handle.change(d => {
+        d.bar = "bif"
+      })
+      handle2.change(d => {
+        d.baz = "baz"
+      })
+
+      handle.merge(handle2)
+
+      assert.deepStrictEqual(handle.docSync(), {
+        foo: "bar",
+        bar: "bif",
+        baz: "baz",
+      })
+      // only the one handle should be changed
+      assert.deepStrictEqual(handle2.docSync(), { foo: "bar", baz: "baz" })
+    })
+
     it("throws an error if we try to find a handle with an invalid AutomergeUrl", async () => {
       const { repo } = setup()
       try {
@@ -726,5 +785,51 @@ describe("Repo", () => {
       assert.deepStrictEqual(bob.message, message)
       assert.deepStrictEqual(charlie.message, message)
     })
+
+    it("notifies peers when a document is cloned", async () => {
+      const { bobRepo, charlieRepo } = await setupMeshNetwork()
+
+      // pause to let the network set up
+      await pause(50)
+
+      const handle = bobRepo.create<TestDoc>()
+      handle.change(d => { d.foo = "bar" })
+      const handle2 = bobRepo.clone(handle) 
+
+      // pause to let the sync happen
+      await pause(50)
+
+      const charlieHandle = charlieRepo.find(handle2.url)
+      await charlieHandle.doc()
+      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "bar" })
+    })
+
+    it("notifies peers when a document is merged", async () => {
+      const { bobRepo, charlieRepo } = await setupMeshNetwork()
+
+      // pause to let the network set up
+      await pause(50)
+
+      const handle = bobRepo.create<TestDoc>()
+      handle.change(d => { d.foo = "bar" })
+      const handle2 = bobRepo.clone(handle) 
+
+      // pause to let the sync happen
+      await pause(50)
+
+      const charlieHandle = charlieRepo.find(handle2.url)
+      await charlieHandle.doc()
+      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "bar" })
+
+      // now make a change to doc2 on bobs side and merge it into doc1
+      handle2.change(d => { d.foo = "baz" })
+      handle.merge(handle2)
+      
+      // wait for the network to do it's thang
+      await pause(50)
+
+      await charlieHandle.doc() 
+      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "baz" })
+    })
   })
 })

package/test/types.ts

@@ -1,3 +1,5 @@
 export interface TestDoc {
   foo: string
+  bar?: string
+  baz?: string
 }