@automerge/automerge-repo 2.0.0-collectionsync-alpha.1 → 2.0.0

package/test/Repo.test.ts

@@ -3,8 +3,11 @@ import { MessageChannelNetworkAdapter } from "../../automerge-repo-network-messa
 import assert from "assert"
 import * as Uuid from "uuid"
 import { describe, expect, it } from "vitest"
-import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import {
+  encodeHeads,
+  getHeadsFromUrl,
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
   generateAutomergeUrl,
   stringifyAutomergeUrl,
 } from "../src/AutomergeUrl.js"
@@ -13,6 +16,7 @@ import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import {
   AnyDocumentId,
+  UrlHeads,
   AutomergeUrl,
   DocHandle,
   DocumentId,
@@ -29,8 +33,7 @@ import {
 import { getRandomItem } from "./helpers/getRandomItem.js"
 import { TestDoc } from "./types.js"
 import { StorageId, StorageKey } from "../src/storage/types.js"
-
-const someDoc = A.init()
+import { chunkTypeFromKey } from "../src/storage/chunkTypeFromKey.js"
 
 describe("Repo", () => {
   describe("constructor", () => {
@@ -42,7 +45,6 @@ describe("Repo", () => {
 
   describe("local only", () => {
     const setup = ({ startReady = true } = {}) => {
-      const someDoc = A.init()
       const storageAdapter = new DummyStorageAdapter()
       const networkAdapter = new DummyNetworkAdapter({ startReady })
 
@@ -75,35 +77,34 @@ describe("Repo", () => {
     it("can create a document with an initial value", async () => {
       const { repo } = setup()
       const handle = repo.create({ foo: "bar" })
-      await handle.doc()
-      assert.equal(handle.docSync().foo, "bar")
+      assert.equal(handle.doc().foo, "bar")
     })
 
-    it("can find a document by url", () => {
+    it("can find a document by url", async () => {
       const { repo } = setup()
       const handle = repo.create<TestDoc>()
       handle.change((d: TestDoc) => {
         d.foo = "bar"
       })
 
-      const handle2 = repo.find(handle.url)
+      const handle2 = await repo.find(handle.url)
       assert.equal(handle, handle2)
-      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+      assert.deepEqual(handle2.doc(), { foo: "bar" })
     })
 
-    it("can find a document by its unprefixed document ID", () => {
+    it("can find a document by its unprefixed document ID", async () => {
       const { repo } = setup()
       const handle = repo.create<TestDoc>()
       handle.change((d: TestDoc) => {
         d.foo = "bar"
       })
 
-      const handle2 = repo.find(handle.documentId)
+      const handle2 = await repo.find(handle.documentId)
       assert.equal(handle, handle2)
-      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+      assert.deepEqual(handle2.doc(), { foo: "bar" })
     })
 
-    it("can find a document by legacy UUID (for now)", () => {
+    it("can find a document by legacy UUID (for now)", async () => {
       disableConsoleWarn()
 
       const { repo } = setup()
@@ -116,9 +117,9 @@ describe("Repo", () => {
       const { binaryDocumentId } = parseAutomergeUrl(url)
       const legacyDocId = Uuid.stringify(binaryDocumentId) as LegacyDocumentId
 
-      const handle2 = repo.find(legacyDocId)
+      const handle2 = await repo.find(legacyDocId)
       assert.equal(handle, handle2)
-      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+      assert.deepEqual(handle2.doc(), { foo: "bar" })
 
       reenableConsoleWarn()
     })
@@ -129,7 +130,7 @@ describe("Repo", () => {
       handle.change(d => {
         d.foo = "bar"
       })
-      const v = await handle.doc()
+      const v = handle.doc()
       assert.equal(handle.isReady(), true)
       assert.equal(v.foo, "bar")
     })
@@ -143,8 +144,8 @@ describe("Repo", () => {
       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" })
+      assert.deepStrictEqual(handle.doc(), handle2.doc())
+      assert.deepStrictEqual(handle2.doc(), { foo: "bar" })
     })
 
     it("the cloned documents are distinct", () => {
@@ -162,9 +163,9 @@ describe("Repo", () => {
         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" })
+      assert.notDeepStrictEqual(handle.doc(), handle2.doc())
+      assert.deepStrictEqual(handle.doc(), { foo: "bar", bar: "bif" })
+      assert.deepStrictEqual(handle2.doc(), { foo: "bar", baz: "baz" })
     })
 
     it("the cloned documents can merge", () => {
@@ -184,59 +185,47 @@ describe("Repo", () => {
 
       handle.merge(handle2)
 
-      assert.deepStrictEqual(handle.docSync(), {
+      assert.deepStrictEqual(handle.doc(), {
         foo: "bar",
         bar: "bif",
         baz: "baz",
       })
       // only the one handle should be changed
-      assert.deepStrictEqual(handle2.docSync(), { foo: "bar", baz: "baz" })
+      assert.deepStrictEqual(handle2.doc(), { foo: "bar", baz: "baz" })
     })
 
     it("throws an error if we try to find a handle with an invalid AutomergeUrl", async () => {
       const { repo } = setup()
-      try {
-        repo.find<TestDoc>("invalid-url" as unknown as AutomergeUrl)
-      } catch (e: any) {
-        assert.equal(e.message, "Invalid AutomergeUrl: 'invalid-url'")
-      }
+      await expect(async () => {
+        await repo.find<TestDoc>("invalid-url" as unknown as AutomergeUrl)
+      }).rejects.toThrow("Invalid AutomergeUrl: 'invalid-url'")
     })
 
     it("doesn't find a document that doesn't exist", async () => {
       const { repo } = setup()
-      const handle = repo.find<TestDoc>(generateAutomergeUrl())
-
-      await handle.whenReady(["ready", "unavailable"])
-
-      assert.equal(handle.isReady(), false)
-      assert.equal(handle.state, "unavailable")
-      const doc = await handle.doc()
-      assert.equal(doc, undefined)
-    })
-
-    it("emits an unavailable event when you don't have the document locally and are not connected to anyone", async () => {
-      const { repo } = setup()
-      const url = generateAutomergeUrl()
-      const handle = repo.find<TestDoc>(url)
-      assert.equal(handle.isReady(), false)
-      await eventPromise(handle, "unavailable")
+      await expect(async () => {
+        await repo.find<TestDoc>(generateAutomergeUrl())
+      }).rejects.toThrow(/Document (.*) is unavailable/)
     })
 
     it("doesn't mark a document as unavailable until network adapters are ready", async () => {
       const { repo, networkAdapter } = setup({ startReady: false })
       const url = generateAutomergeUrl()
-      const handle = repo.find<TestDoc>(url)
 
-      let wasUnavailable = false
-      handle.on("unavailable", () => {
-        wasUnavailable = true
-      })
+      const attemptedFind = repo.find<TestDoc>(url)
 
-      await pause(50)
-      assert.equal(wasUnavailable, false)
+      // First verify it stays pending for 50ms
+      await expect(
+        Promise.race([attemptedFind, pause(50)])
+      ).resolves.toBeUndefined()
 
+      // Trigger the rejection
       networkAdapter.forceReady()
-      await eventPromise(handle, "unavailable")
+
+      // Now verify it rejects
+      await expect(attemptedFind).rejects.toThrow(
+        /Document (.*) is unavailable/
+      )
     })
 
     it("can find a created document", async () => {
@@ -247,30 +236,27 @@ describe("Repo", () => {
       })
       assert.equal(handle.isReady(), true)
 
-      const bobHandle = repo.find<TestDoc>(handle.url)
+      const bobHandle = await repo.find<TestDoc>(handle.url)
 
       assert.equal(handle, bobHandle)
       assert.equal(handle.isReady(), true)
 
-      const v = await bobHandle.doc()
+      const v = bobHandle.doc()
       assert.equal(v?.foo, "bar")
     })
 
     it("saves the document when creating it", async () => {
       const { repo, storageAdapter } = setup()
-      const handle = repo.create<TestDoc>()
+      const handle = repo.create<TestDoc>({ foo: "saved" })
 
       const repo2 = new Repo({
         storage: storageAdapter,
       })
 
-      // TODO: remove this pause
-      await pause(100)
       await repo.flush()
 
-      const bobHandle = repo2.find<TestDoc>(handle.url)
-      await bobHandle.whenReady()
-      assert.equal(bobHandle.isReady(), true)
+      const bobHandle = await repo2.find<TestDoc>(handle.url)
+      assert.deepEqual(bobHandle.doc(), { foo: "saved" })
     })
 
     it("saves the document when changed and can find it again", async () => {
@@ -283,17 +269,15 @@ describe("Repo", () => {
 
       assert.equal(handle.isReady(), true)
 
-      // TODO: remove this pause
-      await pause(100)
       await repo.flush()
 
       const repo2 = new Repo({
         storage: storageAdapter,
       })
 
-      const bobHandle = repo2.find<TestDoc>(handle.url)
+      const bobHandle = await repo2.find<TestDoc>(handle.url)
 
-      const v = await bobHandle.doc()
+      const v = bobHandle.doc()
       assert.equal(v?.foo, "bar")
     })
 
@@ -305,7 +289,7 @@ describe("Repo", () => {
       })
       // we now have a snapshot and an incremental change in storage
       assert.equal(handle.isReady(), true)
-      const foo = await handle.doc()
+      const foo = handle.doc()
       assert.equal(foo?.foo, "bar")
 
       await pause()
@@ -322,7 +306,6 @@ describe("Repo", () => {
         d.foo = "bar"
       })
       assert.equal(handle.isReady(), true)
-      await handle.doc()
 
       await pause()
       repo.delete(handle.url)
@@ -359,7 +342,7 @@ describe("Repo", () => {
 
       const exported = await repo.export(handle.documentId)
       const loaded = A.load(exported)
-      const doc = await handle.doc()
+      const doc = handle.doc()
       assert.deepEqual(doc, loaded)
     })
 
@@ -387,17 +370,13 @@ describe("Repo", () => {
       })
 
       await repo.flush()
-      // TODO: remove this pause
-      await pause(100)
 
       const initialKeys = storage.keys()
 
       const repo2 = new Repo({
         storage,
       })
-      const handle2 = repo2.find(handle.url)
-      await handle2.doc()
-
+      const handle2 = await repo2.find(handle.url)
       assert.deepEqual(storage.keys(), initialKeys)
     })
 
@@ -423,14 +402,12 @@ describe("Repo", () => {
         const repo2 = new Repo({
           storage,
         })
-        const handle2 = repo2.find(handle.url)
-        await handle2.doc()
-
+        const handle2 = await repo2.find(handle.url)
         assert(storage.keys().length !== 0)
       }
     })
 
-    it.skip("doesn't create multiple snapshots in storage when a series of large changes are made in succession", async () => {
+    it("doesn't create multiple snapshots in storage when a series of large changes are made in succession", async () => {
       const { repo, storageAdapter } = setup()
       const handle = repo.create<{ objects: LargeObject[] }>()
 
@@ -454,6 +431,40 @@ describe("Repo", () => {
       )
     })
 
+    it("should not call loadDoc multiple times when find() is called in quick succession", async () => {
+      const { repo, storageAdapter } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change(d => {
+        d.foo = "bar"
+      })
+      await repo.flush()
+
+      // Create a new repo instance that will use the same storage
+      const repo2 = new Repo({
+        storage: storageAdapter,
+      })
+
+      // Track how many times loadDoc is called
+      let loadDocCallCount = 0
+      const originalLoadDoc = repo2.storageSubsystem!.loadDoc.bind(
+        repo2.storageSubsystem
+      )
+      repo2.storageSubsystem!.loadDoc = async documentId => {
+        loadDocCallCount++
+        return originalLoadDoc(documentId)
+      }
+
+      // Call find() twice in quick succession
+      const find1 = repo2.find(handle.url)
+      const find2 = repo2.find(handle.url)
+
+      // Wait for both calls to complete
+      await Promise.all([find1, find2])
+
+      // Verify loadDoc was only called once
+      assert.equal(loadDocCallCount, 1, "loadDoc should only be called once")
+    })
+
     it("can import an existing document", async () => {
       const { repo } = setup()
       const doc = A.init<TestDoc>()
@@ -465,7 +476,7 @@ describe("Repo", () => {
 
       const handle = repo.import<TestDoc>(saved)
       assert.equal(handle.isReady(), true)
-      const v = await handle.doc()
+      const v = handle.doc()
       assert.equal(v?.foo, "bar")
 
       expect(A.getHistory(v)).toEqual(A.getHistory(updatedDoc))
@@ -484,7 +495,7 @@ describe("Repo", () => {
       const { repo } = setup()
       // @ts-ignore - passing something other than UInt8Array
       const handle = repo.import<TestDoc>(A.from({ foo: 123 }))
-      const doc = await handle.doc()
+      const doc = handle.doc()
       expect(doc).toEqual({})
     })
 
@@ -492,7 +503,7 @@ describe("Repo", () => {
       const { repo } = setup()
       // @ts-ignore - passing something other than UInt8Array
       const handle = repo.import<TestDoc>({ foo: 123 })
-      const doc = await handle.doc()
+      const doc = handle.doc()
       expect(doc).toEqual({})
     })
 
@@ -500,14 +511,12 @@ describe("Repo", () => {
       it("contains doc handle", async () => {
         const { repo } = setup()
         const handle = repo.create({ foo: "bar" })
-        await handle.doc()
         assert(repo.handles[handle.documentId])
       })
 
       it("delete removes doc handle", async () => {
         const { repo } = setup()
         const handle = repo.create({ foo: "bar" })
-        await handle.doc()
         await repo.delete(handle.documentId)
         assert(repo.handles[handle.documentId] === undefined)
       })
@@ -515,7 +524,6 @@ describe("Repo", () => {
       it("removeFromCache removes doc handle", async () => {
         const { repo } = setup()
         const handle = repo.create({ foo: "bar" })
-        await handle.doc()
         await repo.removeFromCache(handle.documentId)
         assert(repo.handles[handle.documentId] === undefined)
       })
@@ -530,7 +538,7 @@ describe("Repo", () => {
     })
   })
 
-  describe.skip("flush behaviour", () => {
+  describe("flush behaviour", () => {
     const setup = () => {
       let blockedSaves = new Set<{ path: StorageKey; resolve: () => void }>()
       let resume = (documentIds?: DocumentId[]) => {
@@ -574,8 +582,8 @@ describe("Repo", () => {
 
     it("should not be in a new repo yet because the storage is slow", async () => {
       const { pausedStorage, repo, handle, handle2 } = setup()
-      expect((await handle.doc()).foo).toEqual("first")
-      expect((await handle2.doc()).foo).toEqual("second")
+      expect((await handle).doc().foo).toEqual("first")
+      expect((await handle2).doc().foo).toEqual("second")
 
       // Reload repo
       const repo2 = new Repo({
@@ -583,9 +591,10 @@ describe("Repo", () => {
       })
 
       // Could not find the document that is not yet saved because of slow storage.
-      const reloadedHandle = repo2.find<{ foo: string }>(handle.url)
+      await expect(async () => {
+        const reloadedHandle = await repo2.find<{ foo: string }>(handle.url)
+      }).rejects.toThrow(/Document (.*) is unavailable/)
       expect(pausedStorage.keys()).to.deep.equal([])
-      expect(await reloadedHandle.doc()).toEqual(undefined)
     })
 
     it("should be visible to a new repo after flush()", async () => {
@@ -605,10 +614,10 @@ describe("Repo", () => {
         })
 
         expect(
-          (await repo.find<{ foo: string }>(handle.documentId).doc()).foo
+          (await repo.find<{ foo: string }>(handle.documentId)).doc().foo
         ).toEqual("first")
         expect(
-          (await repo.find<{ foo: string }>(handle2.documentId).doc()).foo
+          (await repo.find<{ foo: string }>(handle2.documentId)).doc().foo
         ).toEqual("second")
       }
     })
@@ -630,13 +639,13 @@ describe("Repo", () => {
         })
 
         expect(
-          (await repo.find<{ foo: string }>(handle.documentId).doc()).foo
+          (await repo.find<{ foo: string }>(handle.documentId)).doc().foo
         ).toEqual("first")
         // Really, it's okay if the second one is also flushed but I'm forcing the issue
         // in the test storage engine above to make sure the behaviour is as documented
-        expect(
-          await repo.find<{ foo: string }>(handle2.documentId).doc()
-        ).toEqual(undefined)
+        await expect(async () => {
+          ;(await repo.find<{ foo: string }>(handle2.documentId)).doc()
+        }).rejects.toThrow(/Document (.*) is unavailable/)
       }
     })
 
@@ -659,40 +668,7 @@ describe("Repo", () => {
     })
   })
 
-  it("should sync correctly", async function () {
-    const pipe = DummyNetworkAdapter.createConnectedPair()
-    const repo1 = new Repo({
-      peerId: "peer1" as PeerId,
-      storage: new DummyStorageAdapter(),
-      sharePolicy: async () => false,
-      network: [pipe[0]],
-    })
-    const repo2 = new Repo({
-      peerId: "peer2" as PeerId,
-      storage: new DummyStorageAdapter(),
-      sharePolicy: async () => true,
-      network: [pipe[1]],
-    })
-
-    const handleOn1 = repo1.create()
-    await handleOn1.whenReady()
-    handleOn1.change((d: any) => {
-      d.foo = "bar"
-    })
-
-    pipe[0].peerCandidate("peer2" as PeerId)
-    pipe[1].peerCandidate("peer1" as PeerId)
-
-    await repo2.networkSubsystem.whenReady()
-    console.log("about to load handle on 2")
-    const handleOn2 = repo2.find(handleOn1.url)
-
-    await handleOn2.whenReady()
-    await pause(1)
-    assert.deepStrictEqual(handleOn2.docSync(), { foo: "bar" })
-  })
-
-  describe("with peers (linear network)", function () {
+  describe("with peers (linear network)", async () => {
     it("n-peers connected in a line", async () => {
       const createNConnectedRepos = async (
         numberOfPeers: number,
@@ -717,7 +693,7 @@ describe("Repo", () => {
 
           if (idx < numberOfPeers - 1) {
             network.push(pair[0])
-            pair[0].whenReady()
+            networkReady.push(pair[0].whenReady())
           }
 
           const repo = new Repo({
@@ -748,23 +724,25 @@ describe("Repo", () => {
         }
 
         await connectedPromise
-
         return { repos }
       }
 
-      // const numberOfPeers = 10
-      const numberOfPeers = 2
+      const numberOfPeers = 10
       const { repos } = await createNConnectedRepos(numberOfPeers, 10)
 
       const handle0 = repos[0].create()
       handle0.change((d: any) => {
         d.foo = "bar"
       })
-      const handleN = repos[numberOfPeers - 1].find<TestDoc>(handle0.url)
 
-      await handleN.whenReady()
-      await pause(1)
-      assert.deepStrictEqual(handleN.docSync(), { foo: "bar" })
+      const handleN = await repos[numberOfPeers - 1].find<TestDoc>(handle0.url)
+      assert.deepStrictEqual(handleN.doc(), { foo: "bar" })
+
+      const handleNBack = repos[numberOfPeers - 1].create({
+        foo: "reverse-trip",
+      })
+      const handle0Back = await repos[0].find<TestDoc>(handleNBack.url)
+      assert.deepStrictEqual(handle0Back.doc(), { foo: "reverse-trip" })
     })
 
     const setup = async ({
@@ -845,7 +823,6 @@ describe("Repo", () => {
       }
 
       const aliceHandle = aliceRepo.create<TestDoc>()
-      // await pause(10)
       aliceHandle.change(d => {
         d.foo = "bar"
       })
@@ -871,6 +848,7 @@ describe("Repo", () => {
         eventPromise(bobRepo.networkSubsystem, "peer"),
         eventPromise(charlieRepo.networkSubsystem, "peer"),
       ])
+
       return {
         alice,
         aliceRepo,
@@ -891,9 +869,8 @@ describe("Repo", () => {
     it("changes are replicated from aliceRepo to bobRepo", async () => {
       const { bobRepo, aliceHandle, teardown } = await setup()
 
-      const bobHandle = bobRepo.find<TestDoc>(aliceHandle.url)
-      await eventPromise(bobHandle, "change")
-      const bobDoc = await bobHandle.doc()
+      const bobHandle = await bobRepo.find<TestDoc>(aliceHandle.url)
+      const bobDoc = bobHandle.doc()
       assert.deepStrictEqual(bobDoc, { foo: "bar" })
       teardown()
     })
@@ -901,9 +878,8 @@ describe("Repo", () => {
     it("can load a document from aliceRepo on charlieRepo", async () => {
       const { charlieRepo, aliceHandle, teardown } = await setup()
 
-      const handle3 = charlieRepo.find<TestDoc>(aliceHandle.url)
-      await eventPromise(handle3, "change")
-      const doc3 = await handle3.doc()
+      const handle3 = await charlieRepo.find<TestDoc>(aliceHandle.url)
+      const doc3 = handle3.doc()
       assert.deepStrictEqual(doc3, { foo: "bar" })
       teardown()
     })
@@ -920,15 +896,13 @@ describe("Repo", () => {
         foo: "foundOnFakeDisk",
       })
       await bobRepo2.flush()
-      console.log("bob storage: ", bobStorage.keys())
 
       // Now, let's load it on the original bob repo (which shares a "disk")
-      const bobFoundIt = bobRepo.find<TestDoc>(inStorageHandle.url)
-      await bobFoundIt.whenReady()
+      const bobFoundIt = await bobRepo.find<TestDoc>(inStorageHandle.url)
 
       // Before checking if it syncs, make sure we have it!
       // (This behaviour is mostly test-validation, we are already testing load/save elsewhere.)
-      assert.deepStrictEqual(await bobFoundIt.doc(), { foo: "foundOnFakeDisk" })
+      assert.deepStrictEqual(bobFoundIt.doc(), { foo: "foundOnFakeDisk" })
 
       await pause(10)
 
@@ -949,7 +923,7 @@ describe("Repo", () => {
       teardown()
     })
 
-    it.skip("charlieRepo doesn't have a document it's not supposed to have", async () => {
+    it("charlieRepo doesn't have a document it's not supposed to have", async () => {
       const { aliceRepo, bobRepo, charlieRepo, notForCharlie, teardown } =
         await setup()
 
@@ -968,25 +942,22 @@ describe("Repo", () => {
     it("charlieRepo can request a document not initially shared with it", async () => {
       const { charlieRepo, notForCharlie, teardown } = await setup()
 
-      const handle = charlieRepo.find<TestDoc>(notForCharlie)
-
-      await pause(50)
-
-      const doc = await handle.doc()
+      const handle = await charlieRepo.find<TestDoc>(notForCharlie)
+      const doc = handle.doc()
 
       assert.deepStrictEqual(doc, { foo: "baz" })
 
       teardown()
     })
 
-    it.skip("charlieRepo can request a document across a network of multiple peers", async () => {
+    it("charlieRepo can request a document across a network of multiple peers", async () => {
       const { charlieRepo, notForBob, teardown } = await setup()
 
-      const handle = charlieRepo.find<TestDoc>(notForBob)
+      const handle = await charlieRepo.find<TestDoc>(notForBob)
 
       await pause(50)
 
-      const doc = await handle.doc()
+      const doc = handle.doc()
       assert.deepStrictEqual(doc, { foo: "bap" })
 
       teardown()
@@ -995,42 +966,10 @@ describe("Repo", () => {
     it("doesn't find a document which doesn't exist anywhere on the network", async () => {
       const { charlieRepo, teardown } = await setup()
       const url = generateAutomergeUrl()
-      const handle = charlieRepo.find<TestDoc>(url)
-      assert.equal(handle.isReady(), false)
-
-      const doc = await handle.doc()
-      assert.equal(doc, undefined)
-
-      teardown()
-    })
 
-    it("emits an unavailable event when it's not found on the network", async () => {
-      const { aliceRepo, teardown } = await setup()
-      const url = generateAutomergeUrl()
-      const handle = aliceRepo.find(url)
-      assert.equal(handle.isReady(), false)
-      await eventPromise(handle, "unavailable")
-      teardown()
-    })
-
-    it("emits an unavailable event every time an unavailable doc is requested", async () => {
-      const { charlieRepo, teardown } = await setup()
-      const url = generateAutomergeUrl()
-      const handle = charlieRepo.find<TestDoc>(url)
-      assert.equal(handle.isReady(), false)
-
-      await Promise.all([
-        eventPromise(handle, "unavailable"),
-        eventPromise(charlieRepo, "unavailable-document"),
-      ])
-
-      // make sure it emits a second time if the doc is still unavailable
-      const handle2 = charlieRepo.find<TestDoc>(url)
-      assert.equal(handle2.isReady(), false)
-      await Promise.all([
-        eventPromise(handle, "unavailable"),
-        eventPromise(charlieRepo, "unavailable-document"),
-      ])
+      await expect(charlieRepo.find<TestDoc>(url)).rejects.toThrow(
+        /Document (.*) is unavailable/
+      )
 
       teardown()
     })
@@ -1045,23 +984,23 @@ describe("Repo", () => {
       } = await setup({ connectAlice: false })
 
       const url = stringifyAutomergeUrl({ documentId: notForCharlie })
-      const handle = charlieRepo.find<TestDoc>(url)
-      assert.equal(handle.isReady(), false)
-
-      await eventPromise(handle, "unavailable")
+      await expect(charlieRepo.find<TestDoc>(url)).rejects.toThrow(
+        /Document (.*) is unavailable/
+      )
 
       connectAliceToBob()
 
       await eventPromise(aliceRepo.networkSubsystem, "peer")
-      // TODO: remove this pause
-      await pause(100)
 
-      const doc = await handle.doc(["ready"])
+      // Not sure why we need this pause here, but... we do.
+      await pause(150)
+      const handle = await charlieRepo.find<TestDoc>(url)
+      const doc = handle.doc()
       assert.deepStrictEqual(doc, { foo: "baz" })
 
       // an additional find should also return the correct resolved document
-      const handle2 = charlieRepo.find<TestDoc>(url)
-      const doc2 = await handle2.doc()
+      const handle2 = await charlieRepo.find<TestDoc>(url)
+      const doc2 = handle2.doc()
       assert.deepStrictEqual(doc2, { foo: "baz" })
 
       teardown()
@@ -1097,11 +1036,9 @@ describe("Repo", () => {
         sharePolicy: async () => true,
       })
 
-      const handle = a.find(url)
-
-      // We expect this to be unavailable as there is no connected peer and
-      // the repo has no storage.
-      await eventPromise(handle, "unavailable")
+      await expect(a.find<TestDoc>(url)).rejects.toThrow(
+        /Document (.*) is unavailable/
+      )
 
       // Now create a repo pointing at the storage containing the document and
       // connect it to the other end of the MessageChannel
@@ -1111,12 +1048,17 @@ describe("Repo", () => {
         network: [new MessageChannelNetworkAdapter(ba)],
       })
 
+      // We need a proper peer status API so we can tell when the
+      // peer is connected. For now we just wait a bit.
+      await pause(50)
+
       // The empty repo should be notified of the new peer, send it a request
       // and eventually resolve the handle to "READY"
-      await handle.whenReady()
+      const handle = await a.find<TestDoc>(url)
+      expect(handle.state).toBe("ready")
     })
 
-    it.skip("a deleted document from charlieRepo can be refetched", async () => {
+    it("a deleted document from charlieRepo can be refetched", async () => {
       const { charlieRepo, aliceHandle, teardown } = await setup()
 
       const deletePromise = eventPromise(charlieRepo, "delete-document")
@@ -1128,12 +1070,9 @@ describe("Repo", () => {
         d.foo = "baz"
       })
       await changePromise
-      // TODO: remove this pause
-      await pause(100)
 
-      const handle3 = charlieRepo.find<TestDoc>(aliceHandle.url)
-      await eventPromise(handle3, "change")
-      const doc3 = await handle3.doc()
+      const handle3 = await charlieRepo.find<TestDoc>(aliceHandle.url)
+      const doc3 = handle3.doc()
 
       assert.deepStrictEqual(doc3, { foo: "baz" })
 
@@ -1151,17 +1090,12 @@ describe("Repo", () => {
         const repo = getRandomItem([aliceRepo, bobRepo, charlieRepo])
         const docs = Object.values(repo.handles)
         const doc =
-          Math.random() < 0.5 || docs.length == 0
+          Math.random() < 0.5
             ? // heads, create a new doc
               repo.create<TestDoc>()
             : // tails, pick a random doc
               (getRandomItem(docs) as DocHandle<TestDoc>)
 
-        // make sure the doc is ready
-        if (!doc.isReady()) {
-          await doc.doc()
-        }
-
         // make a random change to it
         doc.change(d => {
           d.foo = Math.random().toString()
@@ -1177,10 +1111,10 @@ describe("Repo", () => {
 
       const data = { presence: "alice" }
 
-      const aliceHandle = aliceRepo.find<TestDoc>(
+      const aliceHandle = await aliceRepo.find<TestDoc>(
         stringifyAutomergeUrl({ documentId: notForCharlie })
       )
-      const bobHandle = bobRepo.find<TestDoc>(
+      const bobHandle = await bobRepo.find<TestDoc>(
         stringifyAutomergeUrl({ documentId: notForCharlie })
       )
 
@@ -1196,11 +1130,8 @@ describe("Repo", () => {
         setTimeout(resolve, 100)
       })
 
-      const messagePromise = eventPromise(bobHandle, "ephemeral-message")
       aliceHandle.broadcast(data)
-
-      // const { message } = await eventPromise(bobHandle, "ephemeral-message")
-      const { message } = await messagePromise
+      const { message } = await eventPromise(bobHandle, "ephemeral-message")
 
       assert.deepStrictEqual(message, data)
       assert.equal(charlieRepo.handles[notForCharlie], undefined, "charlie no")
@@ -1209,7 +1140,111 @@ describe("Repo", () => {
       teardown()
     })
 
-    it.skip("should report the remote heads when they change", async () => {
+    it("should save sync state of other peers", async () => {
+      const { bobRepo, teardown, charlieRepo } = await setup({
+        connectAlice: false,
+      })
+
+      const bobHandle = bobRepo.create<TestDoc>()
+      bobHandle.change(d => {
+        d.foo = "bar"
+      })
+
+      await pause(200)
+
+      // bob should store the sync state of charlie
+      const storedSyncState = await bobRepo.storageSubsystem.loadSyncState(
+        bobHandle.documentId,
+        await charlieRepo!.storageSubsystem.id()
+      )
+      assert.deepStrictEqual(
+        encodeHeads(storedSyncState.sharedHeads),
+        bobHandle.heads()
+      )
+
+      teardown()
+    })
+
+    it("should not save sync state of ephemeral peers", async () => {
+      const { bobRepo, teardown, charlieRepo } = await setup({
+        connectAlice: false,
+        isCharlieEphemeral: true,
+      })
+
+      const bobHandle = bobRepo.create<TestDoc>()
+      bobHandle.change(d => {
+        d.foo = "bar"
+      })
+
+      await pause(200)
+
+      // bob should not store the sync state for charlie because charly is an ephemeral peer
+      const storedSyncState = await bobRepo.storageSubsystem.loadSyncState(
+        bobHandle.documentId,
+        await charlieRepo!.storageSubsystem.id()
+      )
+      assert.deepStrictEqual(storedSyncState, undefined)
+
+      teardown()
+    })
+
+    it("should load sync state from storage", async () => {
+      const { bobRepo, teardown, charlie, charlieRepo, bobStorage, bob } =
+        await setup({
+          connectAlice: false,
+        })
+
+      // create a new doc and count sync messages
+      const bobHandle = bobRepo.create<TestDoc>()
+      bobHandle.change(d => {
+        d.foo = "bar"
+      })
+      let bobSyncMessages = 0
+      bobRepo.networkSubsystem.on("message", message => {
+        if (message.type === "sync") {
+          bobSyncMessages++
+        }
+      })
+      await pause(500)
+
+      // repo has no stored sync state for charlie so we should see 2 sync messages
+      assert.strictEqual(bobSyncMessages, 2)
+
+      await bobRepo.flush()
+
+      // setup new repo which uses bob's storage
+      const bob2Repo = new Repo({
+        storage: bobStorage,
+        peerId: "bob-2" as PeerId,
+      })
+
+      // connnect it with charlie
+      const channel = new MessageChannel()
+      bob2Repo.networkSubsystem.addNetworkAdapter(
+        new MessageChannelNetworkAdapter(channel.port2)
+      )
+      charlieRepo.networkSubsystem.addNetworkAdapter(
+        new MessageChannelNetworkAdapter(channel.port1)
+      )
+
+      // lookup doc we've previously created and count the messages
+      bob2Repo.find(bobHandle.documentId)
+      let bob2SyncMessages = 0
+      bob2Repo.networkSubsystem.on("message", message => {
+        if (message.type === "sync") {
+          bob2SyncMessages++
+        }
+      })
+      await pause(100)
+
+      // repo has stored sync state for charlie so we should see one sync messages
+      assert.strictEqual(bob2SyncMessages, 1)
+
+      channel.port1.close()
+      teardown()
+    })
+
+    it("should report the remote heads when they change", async () => {
       const { bobRepo, charlieRepo, teardown } = await setup({
         connectAlice: false,
       })
@@ -1225,15 +1260,14 @@ describe("Repo", () => {
 
       const nextRemoteHeadsPromise = new Promise<{
         storageId: StorageId
-        heads: A.Heads
+        heads: UrlHeads
       }>(resolve => {
         handle.on("remote-heads", ({ storageId, heads }) => {
           resolve({ storageId, heads })
         })
       })
 
-      const charlieHandle = charlieRepo.find<TestDoc>(handle.url)
-      await charlieHandle.whenReady()
+      const charlieHandle = await charlieRepo.find<TestDoc>(handle.url)
 
       // make a change on charlie
       charlieHandle.change(d => {
@@ -1270,35 +1304,7 @@ describe("Repo", () => {
     })
   })
 
-  it("peer receives a document when connection is recovered", async () => {
-    const alice = "alice" as PeerId
-    const bob = "bob" as PeerId
-    const [aliceAdapter, bobAdapter] = DummyNetworkAdapter.createConnectedPair()
-    const aliceRepo = new Repo({
-      network: [aliceAdapter],
-      peerId: alice,
-    })
-    const bobRepo = new Repo({
-      network: [bobAdapter],
-      peerId: bob,
-    })
-    const aliceDoc = aliceRepo.create()
-    aliceDoc.change((doc: any) => (doc.text = "Hello world"))
-
-    const bobDoc = bobRepo.find(aliceDoc.url)
-    await eventPromise(bobDoc, "unavailable")
-
-    aliceAdapter.peerCandidate(bob)
-    // Bob isn't yet connected to Alice and can't respond to her sync message
-    await pause(100)
-    bobAdapter.peerCandidate(alice)
-
-    await bobDoc.whenReady()
-
-    assert.equal(bobDoc.isReady(), true)
-  })
-
-  describe.skip("with peers (mesh network)", () => {
+  describe("with peers (mesh network)", () => {
     const setup = async () => {
       // Set up three repos; connect Alice to Bob, Bob to Charlie, and Alice to Charlie
 
@@ -1359,8 +1365,8 @@ describe("Repo", () => {
 
       const aliceHandle = aliceRepo.create<TestDoc>()
 
-      const bobHandle = bobRepo.find(aliceHandle.url)
-      const charlieHandle = charlieRepo.find(aliceHandle.url)
+      const bobHandle = await bobRepo.find(aliceHandle.url)
+      const charlieHandle = await charlieRepo.find(aliceHandle.url)
 
       // Alice should not receive her own ephemeral message
       aliceHandle.on("ephemeral-message", () => {
@@ -1398,9 +1404,8 @@ describe("Repo", () => {
       // pause to let the sync happen
       await pause(50)
 
-      const charlieHandle = charlieRepo.find(handle2.url)
-      await charlieHandle.doc()
-      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "bar" })
+      const charlieHandle = await charlieRepo.find(handle2.url)
+      assert.deepStrictEqual(charlieHandle.doc(), { foo: "bar" })
 
       teardown()
     })
@@ -1417,9 +1422,8 @@ describe("Repo", () => {
       // pause to let the sync happen
       await pause(50)
 
-      const charlieHandle = charlieRepo.find(handle2.url)
-      await charlieHandle.doc()
-      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "bar" })
+      const charlieHandle = await charlieRepo.find(handle2.url)
+      assert.deepStrictEqual(charlieHandle.doc(), { foo: "bar" })
 
       // now make a change to doc2 on bobs side and merge it into doc1
       handle2.change(d => {
@@ -1430,14 +1434,13 @@ describe("Repo", () => {
       // wait for the network to do it's thang
       await pause(350)
 
-      await charlieHandle.doc()
-      assert.deepStrictEqual(charlieHandle.docSync(), { foo: "baz" })
+      assert.deepStrictEqual(charlieHandle.doc(), { foo: "baz" })
 
       teardown()
     })
   })
 
-  describe.skip("the denylist", () => {
+  describe("the denylist", () => {
     it("should immediately return an unavailable message in response to a request for a denylisted document", async () => {
       const storage = new DummyStorageAdapter()
 
@@ -1466,100 +1469,162 @@ describe("Repo", () => {
         eventPromise(client.networkSubsystem, "peer"),
       ])
 
-      const clientDoc = client.find(doc.url)
-      await pause(100)
-      assert.strictEqual(clientDoc.docSync(), undefined)
+      await expect(async () => {
+        const clientDoc = await client.find(doc.url)
+      }).rejects.toThrow(/Document (.*) is unavailable/)
 
       const openDocs = Object.keys(server.metrics().documents).length
       assert.deepEqual(openDocs, 0)
     })
   })
-  describe("beelay bundle requests", () => {
-    function endsWithTwoZerosInDecimal(hexString: string) {
-      // Validate input is 32 bytes (64 characters) of hex
-      if (!/^[0-9a-fA-F]+$/.test(hexString)) {
-        throw new Error("Input must be a hexadecimal string, got " + hexString)
-      }
-      // Convert hex to decimal string
-      const decimal = BigInt("0x" + hexString).toString()
-      // Check if the last two digits are zeros
-      return decimal.endsWith("00")
-    }
+})
 
-    it("creates new bundles", () => {
-      const repo = new Repo({ network: [] })
-      const handle = repo.create<TestDoc>()
-      let heads = handle.heads()
-      let boundaryHashGenerated = false
-      let iteration = 0
-      while (!boundaryHashGenerated) {
-        handle.change(d => {
-          d.foo = `foo${iteration}`
-        })
-        const changeHash = A.decodeChange(
-          A.getLastLocalChange(handle.docSync()!)
-        ).hash
-        boundaryHashGenerated = endsWithTwoZerosInDecimal(changeHash)
-      }
-    })
+describe("Repo heads-in-URLs functionality", () => {
+  const setup = () => {
+    const repo = new Repo({})
+    const handle = repo.create()
+    handle.change((doc: any) => (doc.title = "Hello World"))
+    return { repo, handle }
+  }
+
+  it("finds a document view by URL with heads", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = await repo.find(url)
+    expect(view.doc()).toEqual({ title: "Hello World" })
   })
 
-  describe("when syncing collections", () => {
-    function setup() {
-      const abChannel = new MessageChannel()
+  it("returns a view, not the actual handle, when finding by URL with heads", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    await handle.change((doc: any) => (doc.title = "Changed"))
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = await repo.find(url)
+    expect(view.doc()).toEqual({ title: "Hello World" })
+    expect(handle.doc()).toEqual({ title: "Changed" })
+  })
 
-      const { port1: ab, port2: ba } = abChannel
+  it("changes to a document view do not affect the original", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = await repo.find(url)
+    expect(() =>
+      view.change((doc: any) => (doc.title = "Changed in View"))
+    ).toThrow()
+    expect(handle.doc()).toEqual({ title: "Hello World" })
+  })
 
-      const alice = new Repo({
-        network: [new MessageChannelNetworkAdapter(ab)],
-        peerId: "alice" as PeerId,
-        sharePolicy: async () => false,
-      })
-      const bob = new Repo({
-        network: [new MessageChannelNetworkAdapter(ba)],
-        peerId: "bob" as PeerId,
-      })
-      return { alice, bob }
-    }
+  it("document views are read-only", async () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    const view = await repo.find(url)
+    expect(() => view.change((doc: any) => (doc.title = "Changed"))).toThrow()
+  })
 
-    it("should sync linked documents", async () => {
-      let { alice, bob } = setup()
-      let doc1 = alice.create<{ linked: A.Link | null }>({ linked: null })
-      let doc2 = alice.create<{ foo: string }>({ foo: "bar" })
-      doc1.change(d => {
-        d.linked = new A.Link(doc2.url)
-      })
+  it("finds the latest document when given a URL without heads", async () => {
+    const { repo, handle } = setup()
+    await handle.change((doc: any) => (doc.title = "Changed"))
+    const found = await repo.find(handle.url)
+    expect(found.doc()).toEqual({ title: "Changed" })
+  })
 
-      let doc1OnBob = bob.find(doc1.url)
-      // TODO remove this pause
-      await pause(100)
+  it("getHeadsFromUrl returns heads array if present or undefined", () => {
+    const { repo, handle } = setup()
+    const heads = handle.heads()!
+    const url = stringifyAutomergeUrl({ documentId: handle.documentId, heads })
+    expect(getHeadsFromUrl(url)).toEqual(heads)
+
+    const urlWithoutHeads = generateAutomergeUrl()
+    expect(getHeadsFromUrl(urlWithoutHeads)).toBeUndefined()
+  })
 
-      await doc1OnBob.whenReady()
-      bob.networkSubsystem.disconnect()
+  it("isValidAutomergeUrl returns true for valid URLs", () => {
+    const { repo, handle } = setup()
+    const url = generateAutomergeUrl()
+    expect(isValidAutomergeUrl(url)).toBe(true)
 
-      let doc2OnBob = bob.find(doc2.url)
-      await doc2OnBob.whenReady()
-      assert.deepStrictEqual(doc2OnBob.docSync(), { foo: "bar" })
+    const urlWithHeads = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
     })
+    expect(isValidAutomergeUrl(urlWithHeads)).toBe(true)
+  })
 
-    it("should sync linked documents when a document is initialized contaiing links", async () => {
-      let { alice, bob } = setup()
-      let doc2 = alice.create<{ foo: string }>({ foo: "bar" })
-      let doc1 = alice.create<{ linked: A.Link | null }>({
-        linked: new A.Link(doc2.url),
-      })
+  it("isValidAutomergeUrl returns false for invalid URLs", () => {
+    const { repo, handle } = setup()
+    expect(isValidAutomergeUrl("not a url")).toBe(false)
+    expect(isValidAutomergeUrl("automerge:invalidid")).toBe(false)
+    expect(isValidAutomergeUrl("automerge:validid#invalidhead")).toBe(false)
+  })
 
-      let doc1OnBob = bob.find(doc1.url)
-      // TODO remove this pause
-      await pause(100)
+  it("parseAutomergeUrl extracts documentId and heads", () => {
+    const { repo, handle } = setup()
+    const url = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
+    })
+    const parsed = parseAutomergeUrl(url)
+    expect(parsed.documentId).toBe(handle.documentId)
+    expect(parsed.heads).toEqual(handle.heads())
+  })
 
-      await doc1OnBob.whenReady()
-      bob.networkSubsystem.disconnect()
+  it("stringifyAutomergeUrl creates valid URL", () => {
+    const { repo, handle } = setup()
+    const url = stringifyAutomergeUrl({
+      documentId: handle.documentId,
+      heads: handle.heads()!,
+    })
+    expect(isValidAutomergeUrl(url)).toBe(true)
+    const parsed = parseAutomergeUrl(url)
+    expect(parsed.documentId).toBe(handle.documentId)
+    expect(parsed.heads).toEqual(handle.heads())
+  })
+})
 
-      let doc2OnBob = bob.find(doc2.url)
-      await doc2OnBob.whenReady()
-      assert.deepStrictEqual(doc2OnBob.docSync(), { foo: "bar" })
+describe("Repo.find() abort behavior", () => {
+  it("aborts immediately if signal is already aborted", async () => {
+    const repo = new Repo()
+    const controller = new AbortController()
+    controller.abort()
+
+    await expect(
+      repo.find(generateAutomergeUrl(), { signal: controller.signal })
+    ).rejects.toThrow("Operation aborted")
+  })
+
+  it("can abort while waiting for ready state", async () => {
+    // Create a repo with no network adapters so document can't become ready
+    const repo = new Repo()
+    const url = generateAutomergeUrl()
+
+    const controller = new AbortController()
+
+    // Start find and abort after a moment
+    const findPromise = repo.find(url, { signal: controller.signal })
+    controller.abort()
+
+    await expect(findPromise).rejects.toThrow("Operation aborted")
+    await expect(findPromise).rejects.not.toThrow("unavailable")
+  })
+
+  it("returns handle immediately when allow unavailable is true, even with abort signal", async () => {
+    const repo = new Repo()
+    const controller = new AbortController()
+    const url = generateAutomergeUrl()
+
+    const handle = await repo.find(url, {
+      allowableStates: ["unavailable"],
+      signal: controller.signal,
     })
+
+    expect(handle).toBeDefined()
+
+    // Abort shouldn't affect the result since we skipped ready
+    controller.abort()
+    expect(handle.url).toBe(url)
   })
 })