@automerge/automerge-repo 2.0.0-alpha.2 → 2.0.0-alpha.22

package/src/synchronizer/Synchronizer.ts

@@ -15,6 +15,7 @@ export interface SynchronizerEvents {
   message: (payload: MessageContents) => void
   "sync-state": (payload: SyncStatePayload) => void
   "open-doc": (arg: OpenDocMessage) => void
+  metrics: (arg: DocSyncMetrics) => void
 }
 
 /** Notify the repo that the sync state has changed  */
@@ -23,3 +24,16 @@ export interface SyncStatePayload {
   documentId: DocumentId
   syncState: SyncState
 }
+
+export type DocSyncMetrics =
+  | {
+      type: "receive-sync-message"
+      documentId: DocumentId
+      durationMillis: number
+      numOps: number
+      numChanges: number
+    }
+  | {
+      type: "doc-denied"
+      documentId: DocumentId
+    }

package/src/types.ts

@@ -27,8 +27,11 @@ export type AnyDocumentId =
   | BinaryDocumentId
   | LegacyDocumentId
 
+// We need to define our own version of heads because the AutomergeHeads type is not bs58check encoded
+export type UrlHeads = string[] & { __automergeUrlHeads: unknown }
+
 /** A branded type for peer IDs */
 export type PeerId = string & { __peerId: true }
 
 /** A randomly generated string created when the {@link Repo} starts up */
-export type SessionId = string & { __SessionId: true }
+export type SessionId = string & { __sessionId: true }

package/test/AutomergeUrl.test.ts

@@ -3,9 +3,11 @@ import bs58check from "bs58check"
 import { describe, it } from "vitest"
 import {
   generateAutomergeUrl,
+  getHeadsFromUrl,
   isValidAutomergeUrl,
   parseAutomergeUrl,
   stringifyAutomergeUrl,
+  UrlHeads,
 } from "../src/AutomergeUrl.js"
 import type {
   AutomergeUrl,
@@ -102,3 +104,131 @@ describe("AutomergeUrl", () => {
     })
   })
 })
+
+describe("AutomergeUrl with heads", () => {
+  // Create some sample encoded heads for testing
+  const head1 = bs58check.encode(new Uint8Array([1, 2, 3, 4])) as string
+  const head2 = bs58check.encode(new Uint8Array([5, 6, 7, 8])) as string
+  const goodHeads = [head1, head2] as UrlHeads
+  const urlWithHeads = `${goodUrl}#${head1}|${head2}` as AutomergeUrl
+  const invalidHead = "not-base58-encoded"
+  const invalidHeads = [invalidHead] as UrlHeads
+
+  describe("stringifyAutomergeUrl", () => {
+    it("should stringify a url with heads", () => {
+      const url = stringifyAutomergeUrl({
+        documentId: goodDocumentId,
+        heads: goodHeads,
+      })
+      assert.strictEqual(url, urlWithHeads)
+    })
+
+    it("should throw if heads are not valid base58check", () => {
+      assert.throws(() =>
+        stringifyAutomergeUrl({
+          documentId: goodDocumentId,
+          heads: invalidHeads,
+        })
+      )
+    })
+  })
+
+  describe("parseAutomergeUrl", () => {
+    it("should parse a url with heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(urlWithHeads)
+      assert.equal(documentId, goodDocumentId)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should parse a url without heads", () => {
+      const { documentId, heads } = parseAutomergeUrl(goodUrl)
+      assert.equal(documentId, goodDocumentId)
+      assert.equal(heads, undefined)
+    })
+
+    it("should throw on url with invalid heads encoding", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert.throws(() => parseAutomergeUrl(badUrl))
+    })
+  })
+
+  describe("isValidAutomergeUrl", () => {
+    it("should return true for a valid url with heads", () => {
+      assert(isValidAutomergeUrl(urlWithHeads) === true)
+    })
+
+    it("should return false for a url with invalid heads", () => {
+      const badUrl = `${goodUrl}#${invalidHead}` as AutomergeUrl
+      assert(isValidAutomergeUrl(badUrl) === false)
+    })
+  })
+
+  describe("getHeadsFromUrl", () => {
+    it("should return heads from a valid url", () => {
+      const heads = getHeadsFromUrl(urlWithHeads)
+      assert.deepEqual(heads, [head1, head2])
+    })
+
+    it("should return undefined for url without heads", () => {
+      const heads = getHeadsFromUrl(goodUrl)
+      assert.equal(heads, undefined)
+    })
+  })
+  it("should handle a single head correctly", () => {
+    const urlWithOneHead = `${goodUrl}#${head1}` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithOneHead)
+    assert.deepEqual(heads, [head1])
+  })
+
+  it("should round-trip urls with heads", () => {
+    const originalUrl = urlWithHeads
+    const parsed = parseAutomergeUrl(originalUrl)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, originalUrl)
+  })
+
+  describe("should reject malformed urls", () => {
+    it("should reject urls with trailing delimiter", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#${head1}:` as AutomergeUrl))
+    })
+
+    it("should reject urls with empty head", () => {
+      assert(!isValidAutomergeUrl(`${goodUrl}#|${head1}` as AutomergeUrl))
+    })
+
+    it("should reject urls with multiple hash characters", () => {
+      assert(
+        !isValidAutomergeUrl(`${goodUrl}#${head1}#${head2}` as AutomergeUrl)
+      )
+    })
+  })
+})
+
+describe("empty heads section", () => {
+  it("should treat bare # as empty heads array", () => {
+    const urlWithEmptyHeads = `${goodUrl}#` as AutomergeUrl
+    const { heads } = parseAutomergeUrl(urlWithEmptyHeads)
+    assert.deepEqual(heads, [])
+  })
+
+  it("should round-trip empty heads array", () => {
+    const original = `${goodUrl}#` as AutomergeUrl
+    const parsed = parseAutomergeUrl(original)
+    const roundTripped = stringifyAutomergeUrl({
+      documentId: parsed.documentId,
+      heads: parsed.heads,
+    })
+    assert.equal(roundTripped, original)
+  })
+
+  it("should distinguish between no heads and empty heads", () => {
+    const noHeads = parseAutomergeUrl(goodUrl)
+    const emptyHeads = parseAutomergeUrl(`${goodUrl}#` as AutomergeUrl)
+
+    assert.equal(noHeads.heads, undefined)
+    assert.deepEqual(emptyHeads.heads, [])
+  })
+})

package/test/CollectionSynchronizer.test.ts

@@ -28,13 +28,13 @@ describe("CollectionSynchronizer", () => {
         done()
       })
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
     }))
 
   it("starts synchronizing existing documents when a peer is added", () =>
     new Promise<void>(done => {
       const handle = repo.create()
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
       synchronizer.once("message", event => {
         const { targetId, documentId } = event as SyncMessage
         assert(targetId === "peer1")
@@ -50,7 +50,7 @@ describe("CollectionSynchronizer", () => {
 
       repo.sharePolicy = async (peerId: PeerId) => peerId !== "peer1"
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
       synchronizer.once("message", () => {
         reject(new Error("Should not have sent a message"))
       })
@@ -71,7 +71,7 @@ describe("CollectionSynchronizer", () => {
         reject(new Error("Should not have sent a message"))
       })
 
-      synchronizer.addDocument(handle.documentId)
+      synchronizer.addDocument(handle)
 
       setTimeout(done)
     }))

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,7 +259,7 @@ describe("DocHandle", () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
 
-    handle.doc()
+    handle.legacyAsyncDoc()
 
     assert(vi.getTimerCount() > timerCount)
 
@@ -122,7 +285,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 +295,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 +313,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 +329,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 +354,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 +391,7 @@ describe("DocHandle", () => {
       doc.foo = "baz"
     })
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "baz")
 
     return p
@@ -241,7 +406,7 @@ describe("DocHandle", () => {
     })
 
     await p
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
@@ -261,11 +426,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 +437,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 +451,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 +469,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")
   })
 

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 () => {