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

package/src/Repo.ts

@@ -23,6 +23,10 @@ import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js
 import { SyncStatePayload } from "./synchronizer/Synchronizer.js"
 import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
 
+function randomPeerId() {
+  return ("peer-" + Math.random().toString(36).slice(4)) as PeerId
+}
+
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -61,7 +65,7 @@ export class Repo extends EventEmitter<RepoEvents> {
   constructor({
     storage,
     network = [],
-    peerId,
+    peerId = randomPeerId(),
     sharePolicy,
     isEphemeral = storage === undefined,
     enableRemoteHeadsGossiping = false,
@@ -75,7 +79,7 @@ export class Repo extends EventEmitter<RepoEvents> {
 
     // The `document` event is fired by the DocCollection any time we create a new document or look
     // up a document by ID. We listen for it in order to wire up storage and network synchronization.
-    this.on("document", async ({ handle, isNew }) => {
+    this.on("document", async ({ handle }) => {
       if (storageSubsystem) {
         // Save when the document changes, but no more often than saveDebounceRate.
         const saveFn = ({
@@ -85,17 +89,6 @@ export class Repo extends EventEmitter<RepoEvents> {
           void storageSubsystem.saveDoc(handle.documentId, doc)
         }
         handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate))
-
-        if (isNew) {
-          // this is a new document, immediately save it
-          await storageSubsystem.saveDoc(handle.documentId, handle.docSync()!)
-        } else {
-          // Try to load from disk
-          const loadedDoc = await storageSubsystem.loadDoc(handle.documentId)
-          if (loadedDoc) {
-            handle.update(() => loadedDoc)
-          }
-        }
       }
 
       handle.on("unavailable", () => {
@@ -105,20 +98,6 @@ export class Repo extends EventEmitter<RepoEvents> {
         })
       })
 
-      if (this.networkSubsystem.isReady()) {
-        handle.request()
-      } else {
-        handle.awaitNetwork()
-        this.networkSubsystem
-          .whenReady()
-          .then(() => {
-            handle.networkReady()
-          })
-          .catch(err => {
-            this.#log("error waiting for network", { err })
-          })
-      }
-
       // Register the document with the synchronizer. This advertises our interest in the document.
       this.#synchronizer.addDocument(handle.documentId)
     })
@@ -324,20 +303,16 @@ export class Repo extends EventEmitter<RepoEvents> {
   /** Returns an existing handle if we have it; creates one otherwise. */
   #getHandle<T>({
     documentId,
-    isNew,
-    initialValue,
   }: {
     /** The documentId of the handle to look up or create */
     documentId: DocumentId /** If we know we're creating a new document, specify this so we can have access to it immediately */
-    isNew: boolean
-    initialValue?: T
   }) {
     // If we have the handle cached, return it
     if (this.#handleCache[documentId]) return this.#handleCache[documentId]
 
     // If not, create a new handle, cache it, and return it
     if (!documentId) throw new Error(`Invalid documentId ${documentId}`)
-    const handle = new DocHandle<T>(documentId, { isNew, initialValue })
+    const handle = new DocHandle<T>(documentId)
     this.#handleCache[documentId] = handle
     return handle
   }
@@ -366,10 +341,21 @@ export class Repo extends EventEmitter<RepoEvents> {
     const { documentId } = parseAutomergeUrl(generateAutomergeUrl())
     const handle = this.#getHandle<T>({
       documentId,
-      isNew: true,
-      initialValue,
     }) as DocHandle<T>
-    this.emit("document", { handle, isNew: true })
+
+    this.emit("document", { handle })
+
+    handle.update(() => {
+      let nextDoc: Automerge.Doc<T>
+      if (initialValue) {
+        nextDoc = Automerge.from(initialValue)
+      } else {
+        nextDoc = Automerge.emptyChange(Automerge.init())
+      }
+      return nextDoc
+    })
+
+    handle.doneLoading()
     return handle
   }
 
@@ -434,11 +420,34 @@ export class Repo extends EventEmitter<RepoEvents> {
       return this.#handleCache[documentId]
     }
 
+    // If we don't already have the handle, make an empty one and try loading it
     const handle = this.#getHandle<T>({
       documentId,
-      isNew: false,
     }) as DocHandle<T>
-    this.emit("document", { handle, isNew: false })
+
+    // Try to load from disk before telling anyone else about it
+    if (this.storageSubsystem) {
+      void this.storageSubsystem.loadDoc(handle.documentId).then(loadedDoc => {
+        if (loadedDoc) {
+          // uhhhh, sorry if you're reading this because we were lying to the type system
+          handle.update(() => loadedDoc as Automerge.Doc<T>)
+          handle.doneLoading()
+        } else {
+          this.networkSubsystem
+            .whenReady()
+            .then(() => {
+              handle.request()
+            })
+            .catch(err => {
+              this.#log("error waiting for network", { err })
+            })
+          this.emit("document", { handle })
+        }
+      })
+    } else {
+      handle.request()
+      this.emit("document", { handle })
+    }
     return handle
   }
 
@@ -448,7 +457,7 @@ export class Repo extends EventEmitter<RepoEvents> {
   ) {
     const documentId = interpretAsDocumentId(id)
 
-    const handle = this.#getHandle({ documentId, isNew: false })
+    const handle = this.#getHandle({ documentId })
     handle.delete()
 
     delete this.#handleCache[documentId]
@@ -465,7 +474,7 @@ export class Repo extends EventEmitter<RepoEvents> {
   async export(id: AnyDocumentId): Promise<Uint8Array | undefined> {
     const documentId = interpretAsDocumentId(id)
 
-    const handle = this.#getHandle({ documentId, isNew: false })
+    const handle = this.#getHandle({ documentId })
     const doc = await handle.doc()
     if (!doc) return undefined
     return Automerge.save(doc)
@@ -529,6 +538,13 @@ export class Repo extends EventEmitter<RepoEvents> {
       })
     )
   }
+
+  shutdown(): Promise<void> {
+    this.networkSubsystem.adapters.forEach(adapter => {
+      adapter.disconnect()
+    })
+    return this.flush()
+  }
 }
 
 export interface RepoConfig {
@@ -582,7 +598,6 @@ export interface RepoEvents {
 
 export interface DocumentPayload {
   handle: DocHandle<any>
-  isNew: boolean
 }
 
 export interface DeleteDocumentPayload {

package/src/entrypoints/slim.ts

@@ -1 +1,2 @@
 export * from "../index.js"
+export { initializeBase64Wasm, initializeWasm } from "@automerge/automerge/slim"

package/src/helpers/DummyNetworkAdapter.ts

@@ -2,20 +2,44 @@ import { pause } from "../../src/helpers/pause.js"
 import { Message, NetworkAdapter, PeerId } from "../../src/index.js"
 
 export class DummyNetworkAdapter extends NetworkAdapter {
-  #startReady: boolean
   #sendMessage?: SendMessageFn
 
+  #ready = false
+  #readyResolver?: () => void
+  #readyPromise: Promise<void> = new Promise<void>(resolve => {
+    this.#readyResolver = resolve
+  })
+
+  isReady() {
+    return this.#ready
+  }
+
+  whenReady() {
+    return this.#readyPromise
+  }
+
+  #forceReady() {
+    if (!this.#ready) {
+      this.#ready = true
+      this.#readyResolver?.()
+    }
+  }
+
+  // A public wrapper for use in tests!
+  forceReady() {
+    this.#forceReady()
+  }
+
   constructor(opts: Options = { startReady: true }) {
     super()
-    this.#startReady = opts.startReady || false
+    if (opts.startReady) {
+      this.#forceReady()
+    }
     this.#sendMessage = opts.sendMessage
   }
 
   connect(peerId: PeerId) {
     this.peerId = peerId
-    if (this.#startReady) {
-      this.emit("ready", { network: this })
-    }
   }
 
   disconnect() {}

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

@@ -1,6 +1,13 @@
 import assert from "assert"
 import { describe, expect, it } from "vitest"
-import { PeerId, PeerMetadata, Repo, StorageId } from "../../index.js"
+import {
+  generateAutomergeUrl,
+  parseAutomergeUrl,
+  PeerId,
+  PeerMetadata,
+  Repo,
+  StorageId,
+} from "../../index.js"
 import type { NetworkAdapterInterface } from "../../network/NetworkAdapterInterface.js"
 import { eventPromise, eventPromises } from "../eventPromise.js"
 import { pause } from "../pause.js"
@@ -169,6 +176,119 @@ export function runNetworkAdapterTests(_setup: SetupFn, title?: string): void {
 
       teardown()
     })
+
+    it("should emit disconnect events on disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await Promise.all([
+        eventPromise(leftRepo.networkSubsystem, "peer"),
+        eventPromise(rightRepo.networkSubsystem, "peer"),
+      ])
+
+      const disconnectionPromises = Promise.all([
+        eventPromise(leftRepo.networkSubsystem, "peer-disconnected"),
+        eventPromise(rightRepo.networkSubsystem, "peer-disconnected"),
+      ])
+      left.disconnect()
+
+      await disconnectionPromises
+      teardown()
+    })
+
+    it("should not send messages after disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await Promise.all([
+        eventPromise(rightRepo.networkSubsystem, "peer"),
+        eventPromise(leftRepo.networkSubsystem, "peer"),
+      ])
+
+      const disconnected = eventPromise(right, "peer-disconnected")
+
+      left.disconnect()
+      await disconnected
+
+      const rightReceivedFromLeft = new Promise(resolve => {
+        right.on("message", msg => {
+          if (msg.senderId === leftPeerId) {
+            resolve(null)
+          }
+        })
+      })
+
+      const rightReceived = Promise.race([rightReceivedFromLeft, pause(10)])
+
+      const documentId = parseAutomergeUrl(generateAutomergeUrl()).documentId
+      left.send({
+        type: "foo",
+        data: new Uint8Array([1, 2, 3]),
+        documentId,
+        senderId: leftPeerId,
+        targetId: rightPeerId,
+      })
+
+      assert.equal(await rightReceived, null)
+      teardown()
+    })
+
+    it("should support reconnecting after disconnect", async () => {
+      const { adapters, teardown } = await setup()
+      const left = adapters[0][0]
+      const right = adapters[1][0]
+
+      const leftPeerId = "left" as PeerId
+      const rightPeerId = "right" as PeerId
+
+      const _leftRepo = new Repo({
+        network: [left],
+        peerId: leftPeerId,
+      })
+
+      const rightRepo = new Repo({
+        network: [right],
+        peerId: rightPeerId,
+      })
+
+      await eventPromise(rightRepo.networkSubsystem, "peer")
+
+      left.disconnect()
+
+      await pause(10)
+
+      left.connect(leftPeerId)
+      await eventPromise(left, "peer-candidate")
+      teardown()
+    })
   })
 }
 

package/src/helpers/throttle.ts

@@ -20,7 +20,7 @@
  *
  *
  * Example usage:
- * const callback = debounce((ev) => { doSomethingExpensiveOrOccasional() }, 100)
+ * const callback = throttle((ev) => { doSomethingExpensiveOrOccasional() }, 100)
  * target.addEventListener('frequent-event', callback);
  *
  */

package/src/network/NetworkAdapter.ts

@@ -23,6 +23,9 @@ export abstract class NetworkAdapter
   peerId?: PeerId
   peerMetadata?: PeerMetadata
 
+  abstract isReady(): boolean
+  abstract whenReady(): Promise<void>
+
   /** Called by the {@link Repo} to start the connection process
    *
    * @argument peerId - the peerId of this repo

package/src/network/NetworkAdapterInterface.ts

@@ -32,12 +32,16 @@ export interface NetworkAdapterInterface
   peerId?: PeerId
   peerMetadata?: PeerMetadata
 
+  isReady(): boolean
+  whenReady(): Promise<void>
+
   /** Called by the {@link Repo} to start the connection process
    *
    * @argument peerId - the peerId of this repo
    * @argument peerMetadata - how this adapter should present itself to other peers
    */
   connect(peerId: PeerId, peerMetadata?: PeerMetadata): void
+  // TODO: should this just return a ready promise?
 
   /** Called by the {@link Repo} to send a message to a peer
    *
@@ -52,9 +56,6 @@ export interface NetworkAdapterInterface
 // events & payloads
 
 export interface NetworkAdapterEvents {
-  /** Emitted when the network is ready to be used */
-  ready: (payload: OpenPayload) => void
-
   /** Emitted when the network is closed */
   close: () => void
 

package/src/network/NetworkSubsystem.ts

@@ -26,12 +26,11 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
   #count = 0
   #sessionId: SessionId = Math.random().toString(36).slice(2) as SessionId
   #ephemeralSessionCounts: Record<EphemeralMessageSource, number> = {}
-  #readyAdapterCount = 0
-  #adapters: NetworkAdapterInterface[] = []
+  adapters: NetworkAdapterInterface[] = []
 
   constructor(
     adapters: NetworkAdapterInterface[],
-    public peerId = randomPeerId(),
+    public peerId: PeerId,
     private peerMetadata: Promise<PeerMetadata>
   ) {
     super()
@@ -39,25 +38,25 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     adapters.forEach(a => this.addNetworkAdapter(a))
   }
 
+  disconnect() {
+    this.adapters.forEach(a => a.disconnect())
+  }
+
+  reconnect() {
+    this.adapters.forEach(a => a.connect(this.peerId))
+  }
+
   addNetworkAdapter(networkAdapter: NetworkAdapterInterface) {
-    this.#adapters.push(networkAdapter)
-    networkAdapter.once("ready", () => {
-      this.#readyAdapterCount++
-      this.#log(
-        "Adapters ready: ",
-        this.#readyAdapterCount,
-        "/",
-        this.#adapters.length
-      )
-      if (this.#readyAdapterCount === this.#adapters.length) {
-        this.emit("ready")
-      }
-    })
+    this.adapters.push(networkAdapter)
 
     networkAdapter.on("peer-candidate", ({ peerId, peerMetadata }) => {
       this.#log(`peer candidate: ${peerId} `)
       // TODO: This is where authentication would happen
 
+      // TODO: on reconnection, this would create problems!
+      // the server would see a reconnection as a late-arriving channel
+      // for an existing peer and decide to ignore it until the connection
+      // times out: turns out my ICE/SIP emulation laziness did not pay off here
       if (!this.#adaptersByPeer[peerId]) {
         // TODO: handle losing a server here
         this.#adaptersByPeer[peerId] = networkAdapter
@@ -114,6 +113,13 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
       })
   }
 
+  // TODO: this probably introduces a race condition for the ready event
+  // but I plan to refactor that as part of this branch in another patch
+  removeNetworkAdapter(networkAdapter: NetworkAdapterInterface) {
+    this.adapters = this.adapters.filter(a => a !== networkAdapter)
+    networkAdapter.disconnect()
+  }
+
   send(message: MessageContents) {
     const peer = this.#adaptersByPeer[message.targetId]
     if (!peer) {
@@ -153,33 +159,20 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
   }
 
   isReady = () => {
-    return this.#readyAdapterCount === this.#adapters.length
+    return this.adapters.every(a => a.isReady())
   }
 
   whenReady = async () => {
-    if (this.isReady()) {
-      return
-    } else {
-      return new Promise<void>(resolve => {
-        this.once("ready", () => {
-          resolve()
-        })
-      })
-    }
+    return Promise.all(this.adapters.map(a => a.whenReady()))
   }
 }
 
-function randomPeerId() {
-  return `user-${Math.round(Math.random() * 100000)}` as PeerId
-}
-
 // events & payloads
 
 export interface NetworkSubsystemEvents {
   peer: (payload: PeerPayload) => void
   "peer-disconnected": (payload: PeerDisconnectedPayload) => void
   message: (payload: RepoMessage) => void
-  ready: () => void
 }
 
 export interface PeerPayload {

package/test/AutomergeUrl.test.ts

@@ -96,5 +96,9 @@ describe("AutomergeUrl", () => {
       const url = stringifyAutomergeUrl({ documentId: badUuidDocumentId })
       assert(isValidAutomergeUrl(url) === false)
     })
+
+    it("should return false for a documentId that is just some random type", () => {
+      assert(isValidAutomergeUrl({ foo: "bar" } as unknown) === false)
+    })
   })
 })

package/test/DocHandle.test.ts

@@ -10,6 +10,12 @@ import { TestDoc } from "./types.js"
 
 describe("DocHandle", () => {
   const TEST_ID = parseAutomergeUrl(generateAutomergeUrl()).documentId
+  const setup = (options?) => {
+    const handle = new DocHandle<TestDoc>(TEST_ID, options)
+    handle.update(() => A.init())
+    handle.doneLoading()
+    return handle
+  }
 
   const docFromMockStorage = (doc: A.Doc<{ foo: string }>) => {
     return A.change<{ foo: string }>(doc, d => (d.foo = "bar"))
@@ -20,15 +26,6 @@ describe("DocHandle", () => {
     assert.equal(handle.documentId, TEST_ID)
   })
 
-  it("should take an initial value", async () => {
-    const handle = new DocHandle(TEST_ID, {
-      isNew: true,
-      initialValue: { foo: "bar" },
-    })
-    const doc = await handle.doc()
-    assert.equal(doc.foo, "bar")
-  })
-
   it("should become ready when a document is loaded", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
     assert.equal(handle.isReady(), false)
@@ -55,7 +52,6 @@ describe("DocHandle", () => {
 
   it("should return undefined if we access the doc before ready", async () => {
     const handle = new DocHandle<TestDoc>(TEST_ID)
-
     assert.equal(handle.docSync(), undefined)
   })
 
@@ -73,10 +69,8 @@ describe("DocHandle", () => {
   })
 
   it("should return the heads when requested", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, {
-      isNew: true,
-      initialValue: { foo: "bar" },
-    })
+    const handle = setup()
+    handle.change(d => (d.foo = "bar"))
     assert.equal(handle.isReady(), true)
 
     const heads = A.getHeads(handle.docSync())
@@ -94,6 +88,7 @@ describe("DocHandle", () => {
    * Once there's a Repo#stop API this case should be covered in accompanying
    * tests and the following test removed.
    */
+  // TODO as part of future cleanup: move this to Repo
   it("no pending timers after a document is loaded", async () => {
     vi.useFakeTimers()
     const timerCount = vi.getTimerCount()
@@ -159,7 +154,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a change message when changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<DocHandleChangePayload<TestDoc>>(resolve =>
       handle.once("change", d => resolve(d))
@@ -179,7 +174,7 @@ describe("DocHandle", () => {
 
   it("should not emit a change message if no change happens via update", () =>
     new Promise<void>((done, reject) => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
       handle.once("change", () => {
         reject(new Error("shouldn't have changed"))
       })
@@ -190,7 +185,7 @@ describe("DocHandle", () => {
     }))
 
   it("should update the internal doc prior to emitting the change message", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<void>(resolve =>
       handle.once("change", ({ handle, doc }) => {
@@ -208,7 +203,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit distinct change messages when consecutive changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     let calls = 0
     const p = new Promise(resolve =>
@@ -238,7 +233,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a change message when changes happen", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
     const p = new Promise(resolve => handle.once("change", d => resolve(d)))
 
     handle.change(doc => {
@@ -252,7 +247,7 @@ describe("DocHandle", () => {
 
   it("should not emit a patch message if no change happens", () =>
     new Promise<void>((done, reject) => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
       handle.on("change", () => {
         reject(new Error("shouldn't have changed"))
       })
@@ -301,7 +296,7 @@ describe("DocHandle", () => {
 
   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: 1 })
+    const handle = setup({ timeoutDelay: 1 })
 
     // simulate requesting from the network
     handle.request()
@@ -319,7 +314,7 @@ describe("DocHandle", () => {
   })
 
   it("should emit a delete event when deleted", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     const p = new Promise<void>(resolve =>
       handle.once("delete", () => resolve())
@@ -331,7 +326,7 @@ describe("DocHandle", () => {
   })
 
   it("should allow changing at old heads", async () => {
-    const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+    const handle = setup()
 
     handle.change(doc => {
       doc.foo = "bar"
@@ -355,7 +350,8 @@ describe("DocHandle", () => {
 
   describe("ephemeral messaging", () => {
     it("can broadcast a message for the network to send out", async () => {
-      const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })
+      const handle = setup()
+
       const message = { foo: "bar" }
 
       const promise = eventPromise(handle, "ephemeral-message-outbound")