@automerge/automerge-repo 2.0.0-alpha.6 → 2.0.0-beta.1

package/test/DocHandle.test.ts

@@ -1,8 +1,12 @@
 import * as A from "@automerge/automerge/next"
 import assert from "assert"
 import { decode } from "cbor-x"
-import { describe, it, vi } from "vitest"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import { describe, expect, it, vi } from "vitest"
+import {
+  encodeHeads,
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+} from "../src/AutomergeUrl.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import { DocHandle, DocHandleChangePayload } from "../src/index.js"
@@ -34,7 +38,7 @@ describe("DocHandle", () => {
     handle.update(doc => docFromMockStorage(doc))
 
     assert.equal(handle.isReady(), true)
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
@@ -46,13 +50,13 @@ describe("DocHandle", () => {
     handle.update(doc => docFromMockStorage(doc))
 
     assert.equal(handle.isReady(), true)
-    const doc = await handle.doc()
-    assert.deepEqual(doc, handle.docSync())
+    const doc = handle.doc()
+    assert.deepEqual(doc, handle.doc())
   })
 
-  it("should return undefined if we access the doc before ready", async () => {
+  it("should throw an exception if we access the doc before ready", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
-    assert.equal(handle.docSync(), undefined)
+    assert.throws(() => handle.doc())
   })
 
   it("should not return a doc until ready", async () => {
@@ -62,26 +66,185 @@ describe("DocHandle", () => {
     // simulate loading from storage
     handle.update(doc => docFromMockStorage(doc))
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
 
     assert.equal(handle.isReady(), true)
     assert.equal(doc?.foo, "bar")
   })
 
+  /** HISTORY TRAVERSAL
+   * This API is relatively alpha-ish but we're already
+   * doing things in our own apps that are fairly ambitious
+   * by routing around to a lower-level API.
+   * This is an attempt to wrap up the existing practice
+   * in a slightly more supportable set of APIs but should be
+   * considered provisional: expect further improvements.
+   */
+
   it("should return the heads when requested", async () => {
     const handle = setup()
     handle.change(d => (d.foo = "bar"))
     assert.equal(handle.isReady(), true)
 
-    const heads = A.getHeads(handle.docSync())
+    const heads = encodeHeads(A.getHeads(handle.doc()))
     assert.notDeepEqual(handle.heads(), [])
     assert.deepEqual(heads, handle.heads())
   })
 
-  it("should return undefined if the heads aren't loaded", async () => {
+  it("should throw an if the heads aren't loaded", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
-    assert.deepEqual(handle.heads(), undefined)
+    expect(() => handle.heads()).toThrow("DocHandle is not ready")
+  })
+
+  it("should return the history when requested", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "bar"))
+    handle.change(d => (d.foo = "baz"))
+    assert.equal(handle.isReady(), true)
+
+    const history = handle.history()
+    assert.deepEqual(handle.history().length, 2)
+  })
+
+  it("should return a commit from the history", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    handle.change(d => (d.foo = "one"))
+    handle.change(d => (d.foo = "two"))
+    handle.change(d => (d.foo = "three"))
+    assert.equal(handle.isReady(), true)
+
+    const history = handle.history()
+    const viewHandle = handle.view(history[1])
+    assert.deepEqual(await viewHandle.doc(), { foo: "one" })
+  })
+
+  it("should support fixed heads from construction", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    handle.change(d => (d.foo = "one"))
+
+    const history = handle.history()
+    const viewHandle = new DocHandle<TestDoc>(TEST_ID, { heads: history[0] })
+    viewHandle.update(() => A.clone(handle.doc()!))
+    viewHandle.doneLoading()
+
+    assert.deepEqual(await viewHandle.doc(), { foo: "zero" })
+  })
+
+  it("should prevent changes on fixed-heads handles", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const viewHandle = handle.view(handle.heads()!)
+
+    assert.throws(() => viewHandle.change(d => (d.foo = "one")))
+    assert.throws(() =>
+      viewHandle.changeAt(handle.heads()!, d => (d.foo = "one"))
+    )
+    assert.throws(() => viewHandle.merge(handle))
+  })
+
+  it("should return fixed heads from heads()", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const originalHeads = handle.heads()!
+
+    handle.change(d => (d.foo = "one"))
+    const viewHandle = handle.view(originalHeads)
+
+    assert.deepEqual(viewHandle.heads(), originalHeads)
+    assert.notDeepEqual(viewHandle.heads(), handle.heads())
+  })
+
+  it("should return diffs", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    handle.change(d => (d.foo = "one"))
+    handle.change(d => (d.foo = "two"))
+    handle.change(d => (d.foo = "three"))
+    assert.equal(handle.isReady(), true)
+
+    const history = handle.history()
+    const patches = handle.diff(history[1])
+    assert.deepEqual(patches, [
+      { action: "put", path: ["foo"], value: "" },
+      { action: "splice", path: ["foo", 0], value: "one" },
+    ])
+  })
+
+  it("should support arbitrary diffs too", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    handle.change(d => (d.foo = "one"))
+    handle.change(d => (d.foo = "two"))
+    handle.change(d => (d.foo = "three"))
+    assert.equal(handle.isReady(), true)
+
+    const history = handle.history()
+    const patches = handle.diff(history[1], history[3])
+    assert.deepEqual(patches, [
+      { action: "put", path: ["foo"], value: "" },
+      { action: "splice", path: ["foo", 0], value: "three" },
+    ])
+    const backPatches = handle.diff(history[3], history[1])
+    assert.deepEqual(backPatches, [
+      { action: "put", path: ["foo"], value: "" },
+      { action: "splice", path: ["foo", 0], value: "one" },
+    ])
+  })
+
+  it("should support diffing against another handle", async () => {
+    const handle = setup()
+    handle.change(d => (d.foo = "zero"))
+    const viewHandle = handle.view(handle.heads()!)
+
+    handle.change(d => (d.foo = "one"))
+
+    const patches = viewHandle.diff(handle)
+    assert.deepEqual(patches, [
+      { action: "put", path: ["foo"], value: "" },
+      { action: "splice", path: ["foo", 0], value: "one" },
+    ])
+  })
+
+  // TODO: alexg -- should i remove this test? should this fail or no?
+  it.skip("should fail diffing against unrelated handles", async () => {
+    const handle1 = setup()
+    const handle2 = setup()
+
+    handle1.change(d => (d.foo = "zero"))
+    handle2.change(d => (d.foo = "one"))
+
+    assert.throws(() => handle1.diff(handle2))
+  })
+
+  it("should allow direct access to decoded changes", async () => {
+    const handle = setup()
+    const time = Date.now()
+    handle.change(d => (d.foo = "foo"), { message: "commitMessage" })
+    assert.equal(handle.isReady(), true)
+
+    const metadata = handle.metadata()
+    assert.deepEqual(metadata.message, "commitMessage")
+    // NOTE: I'm not testing time because of https://github.com/automerge/automerge/issues/965
+    // but it does round-trip successfully!
+  })
+
+  it("should allow direct access to a specific decoded change", async () => {
+    const handle = setup()
+    const time = Date.now()
+    handle.change(d => (d.foo = "foo"), { message: "commitMessage" })
+    handle.change(d => (d.foo = "foo"), { message: "commitMessage2" })
+    handle.change(d => (d.foo = "foo"), { message: "commitMessage3" })
+    handle.change(d => (d.foo = "foo"), { message: "commitMessage4" })
+    assert.equal(handle.isReady(), true)
+
+    const history = handle.history()
+    const metadata = handle.metadata(history[0][0])
+    assert.deepEqual(metadata.message, "commitMessage")
+    // NOTE: I'm not testing time because of https://github.com/automerge/automerge/issues/965
+    // but it does round-trip successfully!
   })
 
   /**
@@ -96,8 +259,6 @@ describe("DocHandle", () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
 
-    handle.doc()
-
     assert(vi.getTimerCount() > timerCount)
 
     // simulate loading from storage
@@ -122,7 +283,7 @@ describe("DocHandle", () => {
     assert.equal(handle.isReady(), true)
     handle.change(d => (d.foo = "pizza"))
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "pizza")
   })
 
@@ -132,7 +293,9 @@ describe("DocHandle", () => {
     // we don't have it in storage, so we request it from the network
     handle.request()
 
-    assert.equal(handle.docSync(), undefined)
+    await expect(() => {
+      handle.doc()
+    }).toThrowError("DocHandle is not ready")
     assert.equal(handle.isReady(), false)
     assert.throws(() => handle.change(_ => {}))
   })
@@ -148,7 +311,7 @@ describe("DocHandle", () => {
       return A.change(doc, d => (d.foo = "bar"))
     })
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(handle.isReady(), true)
     assert.equal(doc?.foo, "bar")
   })
@@ -164,7 +327,7 @@ describe("DocHandle", () => {
       doc.foo = "bar"
     })
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
 
     const changePayload = await p
@@ -189,7 +352,7 @@ describe("DocHandle", () => {
 
     const p = new Promise<void>(resolve =>
       handle.once("change", ({ handle, doc }) => {
-        assert.equal(handle.docSync()?.foo, doc.foo)
+        assert.equal(handle.doc()?.foo, doc.foo)
 
         resolve()
       })
@@ -226,7 +389,7 @@ describe("DocHandle", () => {
       doc.foo = "baz"
     })
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "baz")
 
     return p
@@ -241,7 +404,7 @@ describe("DocHandle", () => {
     })
 
     await p
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
@@ -261,11 +424,7 @@ describe("DocHandle", () => {
     // set docHandle time out after 5 ms
     const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
 
-    const doc = await handle.doc()
-
-    assert.equal(doc, undefined)
-
-    assert.equal(handle.state, "unavailable")
+    expect(() => handle.doc()).toThrowError("DocHandle is not ready")
   })
 
   it("should not time out if the document is loaded in time", async () => {
@@ -276,11 +435,11 @@ describe("DocHandle", () => {
     handle.update(doc => docFromMockStorage(doc))
 
     // now it should not time out
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
-  it("should be undefined if loading from the network times out", async () => {
+  it("should throw an exception if loading from the network times out", async () => {
     // set docHandle time out after 5 ms
     const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
 
@@ -290,8 +449,7 @@ describe("DocHandle", () => {
     // there's no update
     await pause(10)
 
-    const doc = await handle.doc()
-    assert.equal(doc, undefined)
+    expect(() => handle.doc()).toThrowError("DocHandle is not ready")
   })
 
   it("should not time out if the document is updated in time", async () => {
@@ -309,7 +467,7 @@ describe("DocHandle", () => {
     // now it should not time out
     await pause(5)
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
@@ -362,4 +520,71 @@ describe("DocHandle", () => {
       assert.deepStrictEqual(decode(data), message)
     })
   })
+
+  it("should cache view handles based on heads", async () => {
+    // Create and setup a document with some data
+    const handle = setup()
+    handle.change(doc => {
+      doc.foo = "Hello"
+    })
+    const heads1 = handle.heads()
+
+    // Make another change to get a different set of heads
+    handle.change(doc => {
+      doc.foo = "Hello, World!"
+    })
+
+    // Create a view at the first set of heads
+    const view1 = handle.view(heads1)
+
+    // Request the same view again
+    const view2 = handle.view(heads1)
+
+    // Verify we got the same handle instance back (cached version)
+    expect(view1).toBe(view2)
+
+    // Verify the contents are correct
+    expect(view1.doc().foo).toBe("Hello")
+
+    // Test with a different set of heads
+    const view3 = handle.view(handle.heads())
+    expect(view3).not.toBe(view1)
+    expect(view3.doc().foo).toBe("Hello, World!")
+  })
+
+  it("should improve performance when requesting the same view multiple times", () => {
+    // Create and setup a document with some data
+    const handle = setup()
+    handle.change(doc => {
+      doc.foo = "Hello"
+    })
+    const heads = handle.heads()
+
+    // First, measure time without cache (first access)
+    const startTimeNoCached = performance.now()
+    const firstView = handle.view(heads)
+    const endTimeNoCached = performance.now()
+
+    // Now measure with cache (subsequent accesses)
+    const startTimeCached = performance.now()
+    for (let i = 0; i < 100; i++) {
+      handle.view(heads)
+    }
+    const endTimeCached = performance.now()
+
+    // Assert that all views are the same instance
+    for (let i = 0; i < 10; i++) {
+      expect(handle.view(heads)).toBe(firstView)
+    }
+
+    // Calculate average times
+    const timeForFirstAccess = endTimeNoCached - startTimeNoCached
+    const timeForCachedAccesses = (endTimeCached - startTimeCached) / 100
+
+    console.log(`Time for first view (no cache): ${timeForFirstAccess}ms`)
+    console.log(`Average time per cached view: ${timeForCachedAccesses}ms`)
+
+    // Cached access should be significantly faster
+    expect(timeForCachedAccesses).toBeLessThan(timeForFirstAccess / 10)
+  })
 })

package/test/DocSynchronizer.test.ts

@@ -1,7 +1,11 @@
 import assert from "assert"
 import { describe, it } from "vitest"
 import { next as Automerge } from "@automerge/automerge"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import {
+  encodeHeads,
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+} from "../src/AutomergeUrl.js"
 import { DocHandle } from "../src/DocHandle.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import {
@@ -67,11 +71,14 @@ describe("DocSynchronizer", () => {
 
     assert.equal(message1.peerId, "alice")
     assert.equal(message1.documentId, handle.documentId)
-    assert.deepEqual(message1.syncState.lastSentHeads, [])
+    assert.deepStrictEqual(message1.syncState.lastSentHeads, [])
 
     assert.equal(message2.peerId, "alice")
     assert.equal(message2.documentId, handle.documentId)
-    assert.deepEqual(message2.syncState.lastSentHeads, handle.heads())
+    assert.deepStrictEqual(
+      encodeHeads(message2.syncState.lastSentHeads),
+      handle.heads()
+    )
   })
 
   it("still syncs with a peer after it disconnects and reconnects", async () => {