@automerge/automerge-repo 2.0.0-alpha.20 → 2.0.0-alpha.23

package/src/helpers/abortable.ts

@@ -0,0 +1,61 @@
+/**
+ * Creates a promise that rejects when the signal is aborted.
+ *
+ * @remarks
+ * This utility creates a promise that rejects when the provided AbortSignal is aborted.
+ * It's designed to be used with Promise.race() to make operations abortable.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * try {
+ *   const result = await Promise.race([
+ *     fetch('https://api.example.com/data'),
+ *     abortable(controller.signal)
+ *   ]);
+ * } catch (err) {
+ *   if (err.name === 'AbortError') {
+ *     console.log('The operation was aborted');
+ *   }
+ * }
+ *
+ * // Later, to abort:
+ * controller.abort();
+ * ```
+ *
+ * @param signal - An AbortSignal that can be used to abort the operation
+ * @param cleanup - Optional cleanup function that will be called if aborted
+ * @returns A promise that rejects with AbortError when the signal is aborted
+ * @throws {DOMException} With name "AbortError" when aborted
+ */
+export function abortable(
+  signal?: AbortSignal,
+  cleanup?: () => void
+): Promise<never> {
+  if (signal?.aborted) {
+    throw new DOMException("Operation aborted", "AbortError")
+  }
+
+  if (!signal) {
+    return new Promise(() => {}) // Never resolves
+  }
+
+  return new Promise((_, reject) => {
+    signal.addEventListener(
+      "abort",
+      () => {
+        cleanup?.()
+        reject(new DOMException("Operation aborted", "AbortError"))
+      },
+      { once: true }
+    )
+  })
+}
+
+/**
+ * Include this type in an options object to pass an AbortSignal to a function.
+ */
+export interface AbortOptions {
+  signal?: AbortSignal
+}

package/src/helpers/tests/network-adapter-tests.ts

@@ -49,9 +49,10 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
         // Alice creates a document
         const aliceHandle = aliceRepo.create<TestDoc>()
 
-        // Bob receives the document
-        await eventPromise(bobRepo, "document")
-        const bobHandle = bobRepo.find<TestDoc>(aliceHandle.url)
+        // TODO: ... let connections complete. this shouldn't be necessary.
+        await pause(50)
+
+        const bobHandle = await bobRepo.find<TestDoc>(aliceHandle.url)
 
         // Alice changes the document
         aliceHandle.change(d => {
@@ -60,7 +61,7 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
         // Bob receives the change
         await eventPromise(bobHandle, "change")
-        assert.equal((await bobHandle.doc())?.foo, "bar")
+        assert.equal((await bobHandle).doc()?.foo, "bar")
 
         // Bob changes the document
         bobHandle.change(d => {
@@ -69,7 +70,7 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
         // Alice receives the change
         await eventPromise(aliceHandle, "change")
-        assert.equal((await aliceHandle.doc())?.foo, "baz")
+        assert.equal(aliceHandle.doc().foo, "baz")
       }
 
       // Run the test in both directions, in case they're different types of adapters
@@ -100,9 +101,9 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
       const docUrl = aliceHandle.url
 
       // Bob and Charlie receive the document
-      await eventPromises([bobRepo, charlieRepo], "document")
-      const bobHandle = bobRepo.find<TestDoc>(docUrl)
-      const charlieHandle = charlieRepo.find<TestDoc>(docUrl)
+      await pause(50)
+      const bobHandle = await bobRepo.find<TestDoc>(docUrl)
+      const charlieHandle = await charlieRepo.find<TestDoc>(docUrl)
 
       // Alice changes the document
       aliceHandle.change(d => {
@@ -111,8 +112,8 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
       // Bob and Charlie receive the change
       await eventPromises([bobHandle, charlieHandle], "change")
-      assert.equal((await bobHandle.doc())?.foo, "bar")
-      assert.equal((await charlieHandle.doc())?.foo, "bar")
+      assert.equal(bobHandle.doc().foo, "bar")
+      assert.equal(charlieHandle.doc().foo, "bar")
 
       // Charlie changes the document
       charlieHandle.change(d => {
@@ -121,8 +122,8 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
       // Alice and Bob receive the change
       await eventPromises([aliceHandle, bobHandle], "change")
-      assert.equal((await bobHandle.doc())?.foo, "baz")
-      assert.equal((await charlieHandle.doc())?.foo, "baz")
+      assert.equal(bobHandle.doc().foo, "baz")
+      assert.equal(charlieHandle.doc().foo, "baz")
 
       teardown()
     })
@@ -141,7 +142,7 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
       )
 
       const aliceHandle = aliceRepo.create<TestDoc>()
-      const charlieHandle = charlieRepo.find(aliceHandle.url)
+      const charlieHandle = await charlieRepo.find(aliceHandle.url)
 
       // pause to give charlie a chance to let alice know it wants the doc
       await pause(100)

package/src/synchronizer/CollectionSynchronizer.ts

@@ -1,6 +1,6 @@
 import debug from "debug"
 import { DocHandle } from "../DocHandle.js"
-import { parseAutomergeUrl, stringifyAutomergeUrl } from "../AutomergeUrl.js"
+import { parseAutomergeUrl } from "../AutomergeUrl.js"
 import { Repo } from "../Repo.js"
 import { DocMessage } from "../network/messages.js"
 import { AutomergeUrl, DocumentId, PeerId } from "../types.js"
@@ -29,18 +29,19 @@ export class CollectionSynchronizer extends Synchronizer {
   }
 
   /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
-  #fetchDocSynchronizer(documentId: DocumentId) {
-    if (!this.docSynchronizers[documentId]) {
-      const handle = this.repo.find(stringifyAutomergeUrl({ documentId }))
-      this.docSynchronizers[documentId] = this.#initDocSynchronizer(handle)
+  #fetchDocSynchronizer(handle: DocHandle<unknown>) {
+    if (!this.docSynchronizers[handle.documentId]) {
+      this.docSynchronizers[handle.documentId] =
+        this.#initDocSynchronizer(handle)
     }
-    return this.docSynchronizers[documentId]
+    return this.docSynchronizers[handle.documentId]
   }
 
   /** Creates a new docSynchronizer and sets it up to propagate messages */
   #initDocSynchronizer(handle: DocHandle<unknown>): DocSynchronizer {
     const docSynchronizer = new DocSynchronizer({
       handle,
+      peerId: this.repo.networkSubsystem.peerId,
       onLoadSyncState: async peerId => {
         if (!this.repo.storageSubsystem) {
           return
@@ -109,13 +110,16 @@ export class CollectionSynchronizer extends Synchronizer {
 
     this.#docSetUp[documentId] = true
 
-    const docSynchronizer = this.#fetchDocSynchronizer(documentId)
+    const handle = await this.repo.find(documentId, {
+      allowableStates: ["ready", "unavailable", "requesting"],
+    })
+    const docSynchronizer = this.#fetchDocSynchronizer(handle)
 
     docSynchronizer.receiveMessage(message)
 
     // Initiate sync with any new peers
     const peers = await this.#documentGenerousPeers(documentId)
-    docSynchronizer.beginSync(
+    void docSynchronizer.beginSync(
       peers.filter(peerId => !docSynchronizer.hasPeer(peerId))
     )
   }
@@ -123,14 +127,14 @@ export class CollectionSynchronizer extends Synchronizer {
   /**
    * Starts synchronizing the given document with all peers that we share it generously with.
    */
-  addDocument(documentId: DocumentId) {
+  addDocument(handle: DocHandle<unknown>) {
     // HACK: this is a hack to prevent us from adding the same document twice
-    if (this.#docSetUp[documentId]) {
+    if (this.#docSetUp[handle.documentId]) {
       return
     }
-    const docSynchronizer = this.#fetchDocSynchronizer(documentId)
-    void this.#documentGenerousPeers(documentId).then(peers => {
-      docSynchronizer.beginSync(peers)
+    const docSynchronizer = this.#fetchDocSynchronizer(handle)
+    void this.#documentGenerousPeers(handle.documentId).then(peers => {
+      void docSynchronizer.beginSync(peers)
     })
   }
 
@@ -152,7 +156,7 @@ export class CollectionSynchronizer extends Synchronizer {
     for (const docSynchronizer of Object.values(this.docSynchronizers)) {
       const { documentId } = docSynchronizer
       void this.repo.sharePolicy(peerId, documentId).then(okToShare => {
-        if (okToShare) docSynchronizer.beginSync([peerId])
+        if (okToShare) void docSynchronizer.beginSync([peerId])
       })
     }
   }

package/src/synchronizer/DocSynchronizer.ts

@@ -30,6 +30,7 @@ type PendingMessage = {
 
 interface DocSynchronizerConfig {
   handle: DocHandle<unknown>
+  peerId: PeerId
   onLoadSyncState?: (peerId: PeerId) => Promise<A.SyncState | undefined>
 }
 
@@ -56,13 +57,17 @@ export class DocSynchronizer extends Synchronizer {
 
   #pendingSyncMessages: Array<PendingMessage> = []
 
+  // We keep this around at least in part for debugging.
+  // eslint-disable-next-line no-unused-private-class-members
+  #peerId: PeerId
   #syncStarted = false
 
   #handle: DocHandle<unknown>
   #onLoadSyncState: (peerId: PeerId) => Promise<A.SyncState | undefined>
 
-  constructor({ handle, onLoadSyncState }: DocSynchronizerConfig) {
+  constructor({ handle, peerId, onLoadSyncState }: DocSynchronizerConfig) {
     super()
+    this.#peerId = peerId
     this.#handle = handle
     this.#onLoadSyncState =
       onLoadSyncState ?? (() => Promise.resolve(undefined))
@@ -81,7 +86,6 @@ export class DocSynchronizer extends Synchronizer {
 
     // Process pending sync messages immediately after the handle becomes ready.
     void (async () => {
-      await handle.doc([READY, REQUESTING])
       this.#processAllPendingSyncMessages()
     })()
   }
@@ -97,10 +101,13 @@ export class DocSynchronizer extends Synchronizer {
   /// PRIVATE
 
   async #syncWithPeers() {
-    this.#log(`syncWithPeers`)
-    const doc = await this.#handle.doc()
-    if (doc === undefined) return
-    this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    try {
+      await this.#handle.whenReady()
+      const doc = this.#handle.doc() // XXX THIS ONE IS WEIRD
+      this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc))
+    } catch (e) {
+      console.log("sync with peers threw an exception")
+    }
   }
 
   async #broadcastToPeers({
@@ -226,32 +233,26 @@ export class DocSynchronizer extends Synchronizer {
     return this.#peers.includes(peerId)
   }
 
-  beginSync(peerIds: PeerId[]) {
-    const noPeersWithDocument = peerIds.every(
-      peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
-    )
-
-    // At this point if we don't have anything in our storage, we need to use an empty doc to sync
-    // with; but we don't want to surface that state to the front end
-
-    const docPromise = this.#handle
-      .doc([READY, REQUESTING, UNAVAILABLE])
-      .then(doc => {
-        // we register out peers first, then say that sync has started
+  async beginSync(peerIds: PeerId[]) {
+    void this.#handle
+      .whenReady([READY, REQUESTING, UNAVAILABLE])
+      .then(() => {
+        this.#syncStarted = true
+        this.#checkDocUnavailable()
+      })
+      .catch(e => {
+        console.log("caught whenready", e)
         this.#syncStarted = true
         this.#checkDocUnavailable()
-
-        const wasUnavailable = doc === undefined
-        if (wasUnavailable && noPeersWithDocument) {
-          return
-        }
-
-        // If the doc is unavailable we still need a blank document to generate
-        // the sync message from
-        return doc ?? A.init<unknown>()
       })
 
-    this.#log(`beginSync: ${peerIds.join(", ")}`)
+    const peersWithDocument = this.#peers.some(peerId => {
+      return this.#peerDocumentStatuses[peerId] == "has"
+    })
+
+    if (peersWithDocument) {
+      await this.#handle.whenReady()
+    }
 
     peerIds.forEach(peerId => {
       this.#withSyncState(peerId, syncState => {
@@ -264,11 +265,28 @@ export class DocSynchronizer extends Synchronizer {
         )
         this.#setSyncState(peerId, reparsedSyncState)
 
-        docPromise
-          .then(doc => {
-            if (doc) {
-              this.#sendSyncMessage(peerId, doc)
+        // At this point if we don't have anything in our storage, we need to use an empty doc to sync
+        // with; but we don't want to surface that state to the front end
+        this.#handle
+          .whenReady([READY, REQUESTING, UNAVAILABLE])
+          .then(() => {
+            const doc = this.#handle.isReady()
+              ? this.#handle.doc()
+              : A.init<unknown>()
+
+            const noPeersWithDocument = peerIds.every(
+              peerId =>
+                this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]
+            )
+
+            const wasUnavailable = doc === undefined
+            if (wasUnavailable && noPeersWithDocument) {
+              return
             }
+
+            // If the doc is unavailable we still need a blank document to generate
+            // the sync message from
+            this.#sendSyncMessage(peerId, doc ?? A.init<unknown>())
           })
           .catch(err => {
             this.#log(`Error loading doc for ${peerId}: ${err}`)
@@ -352,6 +370,7 @@ export class DocSynchronizer extends Synchronizer {
     this.#withSyncState(message.senderId, syncState => {
       this.#handle.update(doc => {
         const start = performance.now()
+
         const [newDoc, newSyncState] = A.receiveSyncMessage(
           doc,
           syncState,

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,7 +1,7 @@
 import * as A from "@automerge/automerge/next"
 import assert from "assert"
 import { decode } from "cbor-x"
-import { describe, it, vi } from "vitest"
+import { describe, expect, it, vi } from "vitest"
 import {
   encodeHeads,
   generateAutomergeUrl,
@@ -11,7 +11,6 @@ import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import { DocHandle, DocHandleChangePayload } from "../src/index.js"
 import { TestDoc } from "./types.js"
-import { UNLOADED } from "../src/DocHandle.js"
 
 describe("DocHandle", () => {
   const TEST_ID = parseAutomergeUrl(generateAutomergeUrl()).documentId
@@ -39,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")
   })
 
@@ -51,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 () => {
@@ -67,7 +66,7 @@ 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")
@@ -87,15 +86,15 @@ describe("DocHandle", () => {
     handle.change(d => (d.foo = "bar"))
     assert.equal(handle.isReady(), true)
 
-    const heads = encodeHeads(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 () => {
@@ -128,7 +127,7 @@ describe("DocHandle", () => {
 
     const history = handle.history()
     const viewHandle = new DocHandle<TestDoc>(TEST_ID, { heads: history[0] })
-    viewHandle.update(() => A.clone(handle.docSync()!))
+    viewHandle.update(() => A.clone(handle.doc()!))
     viewHandle.doneLoading()
 
     assert.deepEqual(await viewHandle.doc(), { foo: "zero" })
@@ -260,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
@@ -286,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")
   })
 
@@ -296,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(_ => {}))
   })
@@ -312,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")
   })
@@ -328,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
@@ -353,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()
       })
@@ -390,7 +389,7 @@ describe("DocHandle", () => {
       doc.foo = "baz"
     })
 
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "baz")
 
     return p
@@ -405,7 +404,7 @@ describe("DocHandle", () => {
     })
 
     await p
-    const doc = await handle.doc()
+    const doc = handle.doc()
     assert.equal(doc?.foo, "bar")
   })
 
@@ -425,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 () => {
@@ -440,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 })
 
@@ -454,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 () => {
@@ -473,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")
   })
 
@@ -489,49 +483,6 @@ describe("DocHandle", () => {
     assert.equal(handle.isDeleted(), true)
   })
 
-  it("should clear document reference when unloaded", async () => {
-    const handle = setup()
-
-    handle.change(doc => {
-      doc.foo = "bar"
-    })
-    const doc = await handle.doc()
-    assert.equal(doc?.foo, "bar")
-
-    handle.unload()
-    assert.equal(handle.isUnloaded(), true)
-
-    const clearedDoc = await handle.doc([UNLOADED])
-    assert.notEqual(clearedDoc?.foo, "bar")
-  })
-
-  it("should allow reloading after unloading", async () => {
-    const handle = setup()
-
-    handle.change(doc => {
-      doc.foo = "bar"
-    })
-    const doc = await handle.doc()
-    assert.equal(doc?.foo, "bar")
-
-    handle.unload()
-
-    // reload to transition from unloaded to loading
-    handle.reload()
-
-    // simulate requesting from the network
-    handle.request()
-
-    // simulate updating from the network
-    handle.update(doc => {
-      return A.change(doc, d => (d.foo = "bar"))
-    })
-
-    const reloadedDoc = await handle.doc()
-    assert.equal(handle.isReady(), true)
-    assert.equal(reloadedDoc?.foo, "bar")
-  })
-
   it("should allow changing at old heads", async () => {
     const handle = setup()