@automerge/automerge-repo 0.0.1

package/src/test-utilities/adapter-tests.ts

@@ -0,0 +1,163 @@
+import { PeerId, Repo, type NetworkAdapter, ChannelId } from "../index.js"
+import {
+  eventPromise,
+  eventPromises,
+} from "../helpers/eventPromise.js"
+import { assert } from "chai"
+import { describe, it } from "mocha"
+
+/**
+ * Runs a series of tests against a set of three peers, each represented by one or more instantiated
+ * network adapters.
+ *
+ * The adapter `setup` function should return an object with the following properties:
+ *
+ * - `adapters`: A tuple representing three peers' network configuration. Each element can be either
+ *   a single adapter or an array of adapters. Each will be used to instantiate a Repo for that
+ *   peer.
+ * - `teardown`: An optional function that will be called after the tests have run. This can be used
+ *   to clean up any resources that were created during the test.
+ */
+export function runAdapterTests(_setup: SetupFn, title?: string): void {
+  // Wrap the provided setup function
+  const setup = async () => {
+    const { adapters, teardown = NO_OP } = await _setup()
+
+    // these might be individual adapters or arrays of adapters; normalize them to arrays
+    const [a, b, c] = adapters.map(toArray)
+
+    return { adapters: [a, b, c], teardown }
+  }
+
+  describe(`Adapter acceptance tests ${title ? `(${title})` : ""}`, () => {
+    it("can sync 2 repos", async () => {
+      const doTest = async (a: NetworkAdapter[], b: NetworkAdapter[]) => {
+        const aliceRepo = new Repo({ network: a, peerId: alice })
+        const bobRepo = new Repo({ network: b, peerId: bob })
+
+        // Alice creates a document
+        const aliceHandle = aliceRepo.create<TestDoc>()
+
+        // Bob receives the document
+        await eventPromise(bobRepo, "document")
+        const bobHandle = bobRepo.find<TestDoc>(aliceHandle.documentId)
+
+        // Alice changes the document
+        aliceHandle.change(d => {
+          d.foo = "bar"
+        })
+
+        // Bob receives the change
+        await eventPromise(bobHandle, "change")
+        assert.equal((await bobHandle.value()).foo, "bar")
+
+        // Bob changes the document
+        bobHandle.change(d => {
+          d.foo = "baz"
+        })
+
+        // Alice receives the change
+        await eventPromise(aliceHandle, "change")
+        assert.equal((await aliceHandle.value()).foo, "baz")
+      }
+
+      // Run the test in both directions, in case they're different types of adapters
+      {
+        const { adapters, teardown } = await setup()
+        const [x, y] = adapters
+        await doTest(x, y) // x is Alice
+        teardown()
+      }
+      {
+        const { adapters, teardown } = await setup()
+        const [x, y] = adapters
+        await doTest(y, x) // y is Alice
+        teardown()
+      }
+    })
+
+    it("can sync 3 repos", async () => {
+      const { adapters, teardown } = await setup()
+      const [a, b, c] = adapters
+
+      const aliceRepo = new Repo({ network: a, peerId: alice })
+      const bobRepo = new Repo({ network: b, peerId: bob })
+      const charlieRepo = new Repo({ network: c, peerId: charlie })
+
+      // Alice creates a document
+      const aliceHandle = aliceRepo.create<TestDoc>()
+      const documentId = aliceHandle.documentId
+
+      // Bob and Charlie receive the document
+      await eventPromises([bobRepo, charlieRepo], "document")
+      const bobHandle = bobRepo.find<TestDoc>(documentId)
+      const charlieHandle = charlieRepo.find<TestDoc>(documentId)
+
+      // Alice changes the document
+      aliceHandle.change(d => {
+        d.foo = "bar"
+      })
+
+      // Bob and Charlie receive the change
+      await eventPromises([bobHandle, charlieHandle], "change")
+      assert.equal((await bobHandle.value()).foo, "bar")
+      assert.equal((await charlieHandle.value()).foo, "bar")
+
+      // Charlie changes the document
+      charlieHandle.change(d => {
+        d.foo = "baz"
+      })
+
+      // Alice and Bob receive the change
+      await eventPromises([aliceHandle, bobHandle], "change")
+      assert.equal((await bobHandle.value()).foo, "baz")
+      assert.equal((await charlieHandle.value()).foo, "baz")
+
+      teardown()
+    })
+
+    // TODO: with BroadcastChannel, this test never ends, because it goes into an infinite loop,
+    // because the network has cycles (see #92)
+    it.skip("can broadcast a message", async () => {
+      const { adapters, teardown } = await setup()
+      const [a, b, c] = adapters
+
+      const aliceRepo = new Repo({ network: a, peerId: alice })
+      const bobRepo = new Repo({ network: b, peerId: bob })
+      const charlieRepo = new Repo({ network: c, peerId: charlie })
+
+      await eventPromises(
+        [aliceRepo, bobRepo, charlieRepo].map(r => r.networkSubsystem),
+        "peer"
+      )
+
+      const channelId = "broadcast" as ChannelId
+      const alicePresenceData = { presence: "alice" }
+
+      aliceRepo.ephemeralData.broadcast(channelId, alicePresenceData)
+      const { data } = await eventPromise(charlieRepo.ephemeralData, "data")
+
+      assert.deepStrictEqual(data, alicePresenceData)
+      teardown()
+    })
+  })
+}
+
+const NO_OP = () => { }
+
+type Network = NetworkAdapter | NetworkAdapter[]
+
+export type SetupFn = () => Promise<{
+  adapters: [Network, Network, Network]
+  teardown?: () => void
+}>
+
+type TestDoc = {
+  foo: string
+}
+
+const toArray = <T>(x: T | T[]) => (Array.isArray(x) ? x : [x])
+
+const alice = "alice" as PeerId
+const bob = "bob" as PeerId
+const charlie = "charlie" as PeerId

package/src/types.ts

@@ -0,0 +1,3 @@
+export type DocumentId = string & { __documentId: true }
+export type PeerId = string & { __peerId: false }
+export type ChannelId = string & { __channelId: false }

package/test/CollectionSynchronizer.test.ts

@@ -0,0 +1,73 @@
+import { CollectionSynchronizer } from "../src/synchronizer/CollectionSynchronizer.js"
+import { ChannelId, DocCollection, DocumentId, PeerId } from "../src"
+import assert from "assert"
+import { beforeEach } from "mocha"
+import { MessagePayload } from "../src/network/NetworkAdapter.js"
+
+describe("CollectionSynchronizer", () => {
+  let collection: DocCollection
+  let synchronizer: CollectionSynchronizer
+
+  beforeEach(() => {
+    collection = new DocCollection()
+    synchronizer = new CollectionSynchronizer(collection)
+  })
+
+  it("is not null", async () => {
+    assert(synchronizer !== null)
+  })
+
+  it("starts synchronizing a document to peers when added", done => {
+    const handle = collection.create()
+    synchronizer.addPeer("peer1" as PeerId)
+
+    synchronizer.once("message", (event: MessagePayload) => {
+      assert(event.targetId === "peer1")
+      assert(event.channelId === (handle.documentId as unknown as ChannelId))
+      done()
+    })
+
+    synchronizer.addDocument(handle.documentId)
+  })
+
+  it("starts synchronizing existing documents when a peer is added", done => {
+    const handle = collection.create()
+    synchronizer.addDocument(handle.documentId)
+    synchronizer.once("message", (event: MessagePayload) => {
+      assert(event.targetId === "peer1")
+      assert(event.channelId === (handle.documentId as unknown as ChannelId))
+      done()
+    })
+    synchronizer.addPeer("peer1" as PeerId)
+  })
+
+  it("should not synchronize to a peer which is excluded from the share policy", done => {
+    const handle = collection.create()
+
+    collection.sharePolicy = async (peerId: PeerId) => peerId !== "peer1"
+
+    synchronizer.addDocument(handle.documentId)
+    synchronizer.once("message", () => {
+      done(new Error("Should not have sent a message"))
+    })
+    synchronizer.addPeer("peer1" as PeerId)
+
+    setTimeout(done)
+  })
+
+  it("should not synchronize a document which is excluded from the share policy", done => {
+    const handle = collection.create()
+    collection.sharePolicy = async (_, documentId) =>
+      documentId !== handle.documentId
+
+    synchronizer.addPeer("peer2" as PeerId)
+
+    synchronizer.once("message", () => {
+      done(new Error("Should not have sent a message"))
+    })
+
+    synchronizer.addDocument(handle.documentId)
+
+    setTimeout(done)
+  })
+})

package/test/DocCollection.test.ts

@@ -0,0 +1,19 @@
+import assert from "assert"
+import { DocCollection, DocumentId } from "../src"
+import { TestDoc } from "./types.js"
+
+const MISSING_DOCID = "non-existent-docID" as DocumentId
+
+describe("DocCollection", () => {
+  it("can create documents which are ready to go", async () => {
+    const collection = new DocCollection()
+    const handle = collection.create<TestDoc>()
+    assert(handle.isReady() === true)
+  })
+
+  it("can start finding documents and they shouldn't be ready", () => {
+    const collection = new DocCollection()
+    const handle = collection.find<TestDoc>(MISSING_DOCID)
+    assert(handle.isReady() === false)
+  })
+})

package/test/DocHandle.test.ts

@@ -0,0 +1,281 @@
+import * as A from "@automerge/automerge"
+import assert from "assert"
+import { it } from "mocha"
+import { DocHandle, DocHandleChangePayload, DocumentId } from "../src"
+import { pause } from "../src/helpers/pause"
+import { TestDoc } from "./types.js"
+
+describe("DocHandle", () => {
+  const TEST_ID = "test-document-id" as DocumentId
+
+  const binaryFromMockStorage = () => {
+    const doc = A.change<{ foo: string }>(A.init(), d => (d.foo = "bar"))
+    const binary = A.save(doc)
+    return binary
+  }
+
+  it("should take the UUID passed into it", () => {
+    const handle = new DocHandle(TEST_ID)
+    assert.equal(handle.documentId, TEST_ID)
+  })
+
+  it("should become ready when a document is loaded", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+    assert.equal(handle.isReady(), false)
+
+    // simulate loading from storage
+    handle.load(binaryFromMockStorage())
+
+    assert.equal(handle.isReady(), true)
+    const doc = await handle.value()
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should allow sync access to the doc", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+    assert.equal(handle.isReady(), false)
+
+    // simulate loading from storage
+    handle.load(binaryFromMockStorage())
+
+    assert.equal(handle.isReady(), true)
+    const doc = await handle.value()
+    assert.deepEqual(doc, handle.doc)
+  })
+
+  it("should throws an error if we accessing the doc before ready", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+
+    assert.throws(() => handle.doc)
+  })
+
+  it("should not return a value until ready", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+    assert.equal(handle.isReady(), false)
+
+    // simulate loading from storage
+    handle.load(binaryFromMockStorage())
+
+    const doc = await handle.value()
+
+    assert.equal(handle.isReady(), true)
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should block changes until ready()", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+
+    // can't make changes in LOADING state
+    assert.equal(handle.isReady(), false)
+    assert.throws(() => handle.change(d => (d.foo = "baz")))
+
+    // simulate loading from storage
+    handle.load(binaryFromMockStorage())
+
+    // now we're in READY state so we can make changes
+    assert.equal(handle.isReady(), true)
+    handle.change(d => (d.foo = "pizza"))
+
+    const doc = await handle.value()
+    assert.equal(doc.foo, "pizza")
+  })
+
+  it("should not be ready while requesting from the network", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+
+    // we don't have it in storage, so we request it from the network
+    handle.request()
+
+    assert.throws(() => handle.doc)
+    assert.equal(handle.isReady(), false)
+    assert.throws(() => handle.change(h => {}))
+  })
+
+  it("should become ready if the document is updated by the network", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID)
+
+    // we don't have it in storage, so we request it from the network
+    handle.request()
+
+    // simulate updating from the network
+    handle.update(doc => {
+      return A.change(doc, d => (d.foo = "bar"))
+    })
+
+    const doc = await handle.value()
+    assert.equal(handle.isReady(), true)
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should emit a change message when changes happen", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+
+    const p = new Promise<DocHandleChangePayload<TestDoc>>(resolve =>
+      handle.once("change", d => resolve(d))
+    )
+
+    handle.change(doc => {
+      doc.foo = "bar"
+    })
+
+    const doc = await handle.value()
+    assert.equal(doc.foo, "bar")
+
+    const changePayload = await p
+    assert.deepStrictEqual(changePayload.doc, doc)
+    assert.deepStrictEqual(changePayload.handle, handle)
+  })
+
+  it("should not emit a change message if no change happens via update", done => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    handle.once("change", () => {
+      done(new Error("shouldn't have changed"))
+    })
+    handle.update(d => {
+      setTimeout(done, 0)
+      return d
+    })
+  })
+
+  it("should emit distinct change messages when consecutive changes happen", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+
+    let calls = 0
+    const p = new Promise(resolve =>
+      handle.on("change", async ({ doc: d }) => {
+        if (calls === 0) {
+          assert.equal(d.foo, "bar")
+          calls++
+          return
+        }
+        assert.equal(d.foo, "baz")
+        resolve(d)
+      })
+    )
+
+    handle.change(doc => {
+      doc.foo = "bar"
+    })
+
+    handle.change(doc => {
+      doc.foo = "baz"
+    })
+
+    const doc = await handle.value()
+    assert.equal(doc.foo, "baz")
+
+    return p
+  })
+
+  it("should emit a patch message when changes happen", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const p = new Promise(resolve => handle.once("patch", d => resolve(d)))
+
+    handle.change(doc => {
+      doc.foo = "bar"
+    })
+
+    await p
+    const doc = await handle.value()
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should not emit a patch message if no change happens", done => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    handle.on("patch", () => {
+      done(new Error("shouldn't have patched"))
+    })
+    handle.change(_doc => {
+      // do nothing
+      setTimeout(done, 0)
+    })
+  })
+
+  it("should time out if the document is not loaded", async () => {
+    // set docHandle time out after 5 ms
+    const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
+
+    // we're not going to load
+    await pause(10)
+
+    // so it should time out
+    return assert.rejects(handle.value, "DocHandle timed out")
+  })
+
+  it("should not time out if the document is loaded in time", async () => {
+    // set docHandle time out after 5 ms
+    const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
+
+    // simulate loading from storage before the timeout expires
+    handle.load(binaryFromMockStorage())
+
+    // now it should not time out
+    const doc = await handle.value()
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should time out if the document is not updated from the network", async () => {
+    // set docHandle time out after 5 ms
+    const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
+
+    // simulate requesting from the network
+    handle.request()
+
+    // there's no update
+    await pause(10)
+
+    // so it should time out
+    return assert.rejects(handle.value, "DocHandle timed out")
+  })
+
+  it("should not time out if the document is updated in time", async () => {
+    // set docHandle time out after 5 ms
+    const handle = new DocHandle<TestDoc>(TEST_ID, { timeoutDelay: 5 })
+
+    // simulate requesting from the network
+    handle.request()
+
+    // simulate updating from the network before the timeout expires
+    handle.update(doc => {
+      return A.change(doc, d => (d.foo = "bar"))
+    })
+
+    // now it should not time out
+    const doc = await handle.value()
+    assert.equal(doc.foo, "bar")
+  })
+
+  it("should emit a delete event when deleted", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+
+    const p = new Promise<void>(resolve =>
+      handle.once("delete", () => resolve())
+    )
+    handle.delete()
+    await p
+
+    assert.equal(handle.isDeleted(), true)
+  })
+
+  it("should allow changing at old heads", async () => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+
+    handle.change(doc => {
+      doc.foo = "bar"
+    })
+
+    const headsBefore = A.getHeads(handle.doc)
+
+    handle.change(doc => {
+      doc.foo = "rab"
+    })
+
+    let wasBar = false
+    handle.changeAt(headsBefore, doc => {
+      wasBar = doc.foo === "bar"
+      doc.foo = "baz"
+    })
+
+    assert(wasBar, "foo should have been bar as we changed at the old heads")
+  })
+})

package/test/DocSynchronizer.test.ts

@@ -0,0 +1,68 @@
+import assert from "assert"
+import { DocumentId, PeerId } from "../src/types.js"
+import { DocHandle } from "../src/DocHandle.js"
+import { DocSynchronizer } from "../src/synchronizer/DocSynchronizer.js"
+import { eventPromise } from "../src/helpers/eventPromise.js"
+import { TestDoc } from "./types.js"
+
+const alice = "alice" as PeerId
+const bob = "bob" as PeerId
+
+describe("DocSynchronizer", () => {
+  let handle: DocHandle<TestDoc>
+  let docSynchronizer: DocSynchronizer
+
+  const setup = () => {
+    const docId = "synced-doc" as DocumentId
+    handle = new DocHandle<TestDoc>(docId, { isNew: true })
+    docSynchronizer = new DocSynchronizer(handle)
+    return { handle, docSynchronizer }
+  }
+
+  it("takes the handle passed into it", () => {
+    const { handle, docSynchronizer } = setup()
+    assert(docSynchronizer.documentId === handle.documentId)
+  })
+
+  it("emits a syncMessage when beginSync is called", async () => {
+    const { docSynchronizer } = setup()
+    docSynchronizer.beginSync(alice)
+    const { targetId } = await eventPromise(docSynchronizer, "message")
+    assert.equal(targetId, "alice")
+  })
+
+  it("emits a syncMessage to peers when the handle is updated", async () => {
+    const { handle, docSynchronizer } = setup()
+    docSynchronizer.beginSync(alice)
+    handle.change(doc => {
+      doc.foo = "bar"
+    })
+    const { targetId } = await eventPromise(docSynchronizer, "message")
+    assert.equal(targetId, "alice")
+  })
+
+  it("still syncs with a peer after it disconnects and reconnects", async () => {
+    const { handle, docSynchronizer } = setup()
+
+    // first connection
+    {
+      await docSynchronizer.beginSync(bob)
+      handle.change(doc => {
+        doc.foo = "a change"
+      })
+      const { targetId } = await eventPromise(docSynchronizer, "message")
+      assert.equal(targetId, "bob")
+      docSynchronizer.endSync(bob)
+    }
+
+    // second connection
+    {
+      await docSynchronizer.beginSync(bob)
+      handle.change(doc => {
+        doc.foo = "another change"
+      })
+      const { targetId } = await eventPromise(docSynchronizer, "message")
+      assert.equal(targetId, "bob")
+    }
+  })
+})

package/test/EphemeralData.test.ts

@@ -0,0 +1,44 @@
+import assert from "assert"
+import * as CBOR from "cbor-x"
+import { EphemeralData } from "../src/EphemeralData.js"
+import { ChannelId, PeerId } from "../src/types.js"
+
+describe("EphemeralData", () => {
+  const ephemeral = new EphemeralData()
+  const otherPeerId = "other_peer" as PeerId
+  const destinationChannelId = "channel_id" as ChannelId
+  const messageData = { foo: "bar" }
+
+  it("should emit a network message on broadcast()", done => {
+    ephemeral.on("message", event => {
+      try {
+        const { targetId, channelId, message, broadcast } = event
+        assert.deepStrictEqual(CBOR.decode(message), messageData)
+        assert.strictEqual(broadcast, true)
+        assert.strictEqual(channelId, channelId)
+        done()
+      } catch (e) {
+        done(e)
+      }
+    })
+    ephemeral.broadcast(destinationChannelId, messageData)
+  })
+
+  it("should emit a data event on receive()", done => {
+    ephemeral.on("data", ({ peerId, channelId, data }) => {
+      try {
+        assert.deepStrictEqual(peerId, otherPeerId)
+        assert.deepStrictEqual(channelId, destinationChannelId)
+        assert.deepStrictEqual(data, messageData)
+        done()
+      } catch (e) {
+        done(e)
+      }
+    })
+    ephemeral.receive(
+      otherPeerId,
+      ("m/" + destinationChannelId) as ChannelId, // TODO: this is nonsense
+      CBOR.encode(messageData)
+    )
+  })
+})

package/test/Network.test.ts

@@ -0,0 +1,13 @@
+import assert from "assert"
+import { NetworkSubsystem } from "../src/network/NetworkSubsystem.js"
+
+// Note: The sync tests in `Repo.test.ts` exercise the network subsystem, and the suite in
+// `automerge-repo` provides test utilities that individual adapters can
+// use to ensure that they work correctly.
+
+describe("Network subsystem", () => {
+  it("Can be instantiated", () => {
+    const network = new NetworkSubsystem([])
+    assert(network !== null)
+  })
+})