@automerge/automerge-repo 1.1.0-alpha.7 → 1.1.1

package/dist/synchronizer/Synchronizer.d.ts

@@ -1,11 +1,19 @@
 import { EventEmitter } from "eventemitter3";
-import { MessageContents, OpenDocMessage, RepoMessage, SyncStateMessage } from "../network/messages.js";
+import { MessageContents, OpenDocMessage, RepoMessage } from "../network/messages.js";
+import { SyncState } from "@automerge/automerge";
+import { PeerId, DocumentId } from "../types.js";
 export declare abstract class Synchronizer extends EventEmitter<SynchronizerEvents> {
     abstract receiveMessage(message: RepoMessage): void;
 }
 export interface SynchronizerEvents {
-    message: (arg: MessageContents) => void;
-    "sync-state": (arg: SyncStateMessage) => void;
+    message: (payload: MessageContents) => void;
+    "sync-state": (payload: SyncStatePayload) => void;
     "open-doc": (arg: OpenDocMessage) => void;
 }
+/** Notify the repo that the sync state has changed  */
+export interface SyncStatePayload {
+    peerId: PeerId;
+    documentId: DocumentId;
+    syncState: SyncState;
+}
 //# sourceMappingURL=Synchronizer.d.ts.map

package/dist/synchronizer/Synchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACX,gBAAgB,EACjB,MAAM,wBAAwB,CAAA;AAE/B,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACvC,YAAY,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,CAAA;IAC7C,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CAC1C"}
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACjD,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CAC1C;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;CACrB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.1.0-alpha.7",
+  "version": "1.1.1",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -9,9 +9,8 @@
   "main": "dist/index.js",
   "scripts": {
     "build": "tsc",
-    "lint": "eslint --ext .ts src",
     "watch": "npm-watch build",
-    "test:coverage": "c8 --reporter=lcov --reporter=html --reporter=text yarn test",
+    "test:coverage": "c8 --reporter=lcov --reporter=html --reporter=text pnpm test",
     "test": "vitest",
     "test:watch": "npm-watch test",
     "fuzz": "ts-node --esm --experimentalSpecifierResolution=node fuzz/fuzz.ts"
@@ -56,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9a4711e39c93273d992c5686257246ddfaaafddd"
+  "gitHead": "7e0681014b8c5f672e2abc2a653a954ccb6d7aba"
 }

package/src/AutomergeUrl.ts

@@ -13,7 +13,7 @@ export const urlPrefix = "automerge:"
 /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
 export const parseAutomergeUrl = (url: AutomergeUrl) => {
   const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [_, docMatch] = url.match(regex) || []
+  const [, docMatch] = url.match(regex) || []
   const documentId = docMatch as DocumentId
   const binaryDocumentId = documentIdToBinary(documentId)
 

package/src/DocHandle.ts

@@ -39,7 +39,7 @@ export class DocHandle<T> //
   #log: debug.Debugger
 
   #machine: DocHandleXstateMachine<T>
-  #timeoutDelay: number
+  #timeoutDelay = 60_000
   #remoteHeads: Record<StorageId, A.Heads> = {}
 
   /** The URL of this document
@@ -54,20 +54,30 @@ export class DocHandle<T> //
   /** @hidden */
   constructor(
     public documentId: DocumentId,
-    { isNew = false, timeoutDelay = 60_000 }: DocHandleOptions = {}
+    options: DocHandleOptions<T> = {}
   ) {
     super()
-    this.#timeoutDelay = timeoutDelay
-    this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
 
-    // initial doc
-    let doc = A.init<T>()
+    this.documentId = documentId
+
+    if ("timeoutDelay" in options && options.timeoutDelay) {
+      this.#timeoutDelay = options.timeoutDelay
+    }
 
-    // Make an empty change so that we have something to save to disk
+    let doc: T
+    const isNew = "isNew" in options && options.isNew
     if (isNew) {
-      doc = A.emptyChange(doc, {})
+      // T should really be constrained to extend `Record<string, unknown>` (an automerge doc can't be
+      // e.g. a primitive, an array, etc. - it must be an object). But adding that constraint creates
+      // a bunch of other problems elsewhere so for now we'll just cast it here to make Automerge happy.
+      doc = A.from(options.initialValue as Record<string, unknown>) as T
+      doc = A.emptyChange<T>(doc)
+    } else {
+      doc = A.init<T>()
     }
 
+    this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
+
     /**
      * Internally we use a state machine to orchestrate document loading and/or syncing, in order to
      * avoid requesting data we already have, or surfacing intermediate values to the consumer.
@@ -234,13 +244,12 @@ export class DocHandle<T> //
 
   /** Returns a promise that resolves when the docHandle is in one of the given states */
   #statePromise(awaitStates: HandleState | HandleState[]) {
-    if (!Array.isArray(awaitStates)) awaitStates = [awaitStates]
-    return Promise.any(
-      awaitStates.map(state =>
-        waitFor(this.#machine, s => s.matches(state), {
-          timeout: this.#timeoutDelay * 2, // use a longer delay here so as not to race with other delays
-        })
-      )
+    const awaitStatesArray = Array.isArray(awaitStates) ? awaitStates : [awaitStates]
+    return waitFor(
+      this.#machine,
+      s => awaitStatesArray.some((state) => s.matches(state)),
+      // use a longer delay here so as not to race with other delays
+      {timeout: this.#timeoutDelay * 2}
     )
   }
 
@@ -451,10 +460,22 @@ export class DocHandle<T> //
 // WRAPPER CLASS TYPES
 
 /** @hidden */
-export interface DocHandleOptions {
-  isNew?: boolean
-  timeoutDelay?: number
-}
+export type DocHandleOptions<T> =
+  // NEW DOCUMENTS
+  | {
+      /** If we know this is a new document (because we're creating it) this should be set to true. */
+      isNew: true
+
+      /** The initial value of the document. */
+      initialValue?: T
+    }
+  // EXISTING DOCUMENTS
+  | {
+      isNew?: false
+
+      /** The number of milliseconds before we mark this document as unavailable if we don't have it and nobody shares it with us. */
+      timeoutDelay?: number
+    }
 
 export interface DocHandleMessagePayload {
   destinationId: PeerId

package/src/Repo.ts

@@ -2,22 +2,23 @@ import { next as Automerge } from "@automerge/automerge"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import {
-  generateAutomergeUrl,
-  interpretAsDocumentId,
-  parseAutomergeUrl,
+    generateAutomergeUrl,
+    interpretAsDocumentId,
+    parseAutomergeUrl,
 } from "./AutomergeUrl.js"
 import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
+import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js"
+import { headsAreSame } from "./helpers/headsAreSame.js"
 import { throttle } from "./helpers/throttle.js"
-import { NetworkAdapter, type PeerMetadata } from "./network/NetworkAdapter.js"
+import { NetworkAdapterInterface, type PeerMetadata } from "./network/NetworkAdapterInterface.js"
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
-import { StorageAdapter } from "./storage/StorageAdapter.js"
+import { RepoMessage } from "./network/messages.js"
+import { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js"
 import { StorageSubsystem } from "./storage/StorageSubsystem.js"
+import { StorageId } from "./storage/types.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
+import { SyncStatePayload } from "./synchronizer/Synchronizer.js"
 import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
-import { RepoMessage, SyncStateMessage } from "./network/messages.js"
-import { StorageId } from "./storage/types.js"
-import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js"
-import { headsAreSame } from "./helpers/headsAreSame.js"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -52,6 +53,7 @@ export class Repo extends EventEmitter<RepoEvents> {
   peerMetadataByPeerId: Record<PeerId, PeerMetadata> = {}
 
   #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
+  #remoteHeadsGossipingEnabled = false
 
   constructor({
     storage,
@@ -59,8 +61,10 @@ export class Repo extends EventEmitter<RepoEvents> {
     peerId,
     sharePolicy,
     isEphemeral = storage === undefined,
+    enableRemoteHeadsGossiping = false,
   }: RepoConfig) {
     super()
+    this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping
     this.#log = debug(`automerge-repo:repo`)
     this.sharePolicy = sharePolicy ?? this.sharePolicy
 
@@ -77,10 +81,7 @@ export class Repo extends EventEmitter<RepoEvents> {
         }: DocHandleEncodedChangePayload<any>) => {
           void storageSubsystem.saveDoc(handle.documentId, doc)
         }
-        handle.on(
-          "heads-changed",
-          throttle(saveFn, this.saveDebounceRate)
-        )
+        handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate))
 
         if (isNew) {
           // this is a new document, immediately save it
@@ -140,9 +141,11 @@ export class Repo extends EventEmitter<RepoEvents> {
       networkSubsystem.send(message)
     })
 
-    this.#synchronizer.on("open-doc", ({ peerId, documentId }) => {
-      this.#remoteHeadsSubscriptions.subscribePeerToDoc(peerId, documentId)
-    })
+    if (this.#remoteHeadsGossipingEnabled) {
+      this.#synchronizer.on("open-doc", ({ peerId, documentId }) => {
+        this.#remoteHeadsSubscriptions.subscribePeerToDoc(peerId, documentId)
+      })
+    }
 
     // STORAGE
     // The storage subsystem has access to some form of persistence, and deals with save and loading documents.
@@ -152,14 +155,10 @@ export class Repo extends EventEmitter<RepoEvents> {
     // NETWORK
     // The network subsystem deals with sending and receiving messages to and from peers.
 
-    const myPeerMetadata: Promise<PeerMetadata> = new Promise(
-      // eslint-disable-next-line no-async-promise-executor -- TODO: fix
-      async (resolve) =>
-        resolve({
-          storageId: await storageSubsystem?.id(),
-          isEphemeral,
-        } as PeerMetadata)
-    )
+    const myPeerMetadata: Promise<PeerMetadata> = (async () => ({
+      storageId: await storageSubsystem?.id(),
+      isEphemeral,
+    }))()
 
     const networkSubsystem = new NetworkSubsystem(
       network,
@@ -178,7 +177,7 @@ export class Repo extends EventEmitter<RepoEvents> {
 
       this.sharePolicy(peerId)
         .then(shouldShare => {
-          if (shouldShare) {
+          if (shouldShare && this.#remoteHeadsGossipingEnabled) {
             this.#remoteHeadsSubscriptions.addGenerousPeer(peerId)
           }
         })
@@ -218,7 +217,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       if (haveHeadsChanged) {
         handle.setRemoteHeads(storageId, message.syncState.theirHeads)
 
-        if (storageId) {
+        if (storageId && this.#remoteHeadsGossipingEnabled) {
           this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(
             message.documentId,
             storageId,
@@ -228,45 +227,51 @@ export class Repo extends EventEmitter<RepoEvents> {
       }
     })
 
-    this.#remoteHeadsSubscriptions.on("notify-remote-heads", message => {
-      this.networkSubsystem.send({
-        type: "remote-heads-changed",
-        targetId: message.targetId,
-        documentId: message.documentId,
-        newHeads: {
-          [message.storageId]: {
-            heads: message.heads,
-            timestamp: message.timestamp,
+    if (this.#remoteHeadsGossipingEnabled) {
+      this.#remoteHeadsSubscriptions.on("notify-remote-heads", message => {
+        this.networkSubsystem.send({
+          type: "remote-heads-changed",
+          targetId: message.targetId,
+          documentId: message.documentId,
+          newHeads: {
+            [message.storageId]: {
+              heads: message.heads,
+              timestamp: message.timestamp,
+            },
           },
-        },
+        })
       })
-    })
 
-    this.#remoteHeadsSubscriptions.on("change-remote-subs", message => {
-      this.#log("change-remote-subs", message)
-      for (const peer of message.peers) {
-        this.networkSubsystem.send({
-          type: "remote-subscription-change",
-          targetId: peer,
-          add: message.add,
-          remove: message.remove,
-        })
-      }
-    })
+      this.#remoteHeadsSubscriptions.on("change-remote-subs", message => {
+        this.#log("change-remote-subs", message)
+        for (const peer of message.peers) {
+          this.networkSubsystem.send({
+            type: "remote-subscription-change",
+            targetId: peer,
+            add: message.add,
+            remove: message.remove,
+          })
+        }
+      })
 
-    this.#remoteHeadsSubscriptions.on("remote-heads-changed", message => {
-      const handle = this.#handleCache[message.documentId]
-      handle.setRemoteHeads(message.storageId, message.remoteHeads)
-    })
+      this.#remoteHeadsSubscriptions.on("remote-heads-changed", message => {
+        const handle = this.#handleCache[message.documentId]
+        handle.setRemoteHeads(message.storageId, message.remoteHeads)
+      })
+    }
   }
 
   #receiveMessage(message: RepoMessage) {
     switch (message.type) {
       case "remote-subscription-change":
-        this.#remoteHeadsSubscriptions.handleControlMessage(message)
+        if (this.#remoteHeadsGossipingEnabled) {
+          this.#remoteHeadsSubscriptions.handleControlMessage(message)
+        }
         break
       case "remote-heads-changed":
-        this.#remoteHeadsSubscriptions.handleRemoteHeads(message)
+        if (this.#remoteHeadsGossipingEnabled) {
+          this.#remoteHeadsSubscriptions.handleRemoteHeads(message)
+        }
         break
       case "sync":
       case "request":
@@ -280,17 +285,17 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   #throttledSaveSyncStateHandlers: Record<
     StorageId,
-    (message: SyncStateMessage) => void
+    (payload: SyncStatePayload) => void
   > = {}
 
   /** saves sync state throttled per storage id, if a peer doesn't have a storage id it's sync state is not persisted */
-  #saveSyncState(message: SyncStateMessage) {
+  #saveSyncState(payload: SyncStatePayload) {
     if (!this.storageSubsystem) {
       return
     }
 
     const { storageId, isEphemeral } =
-      this.peerMetadataByPeerId[message.peerId] || {}
+      this.peerMetadataByPeerId[payload.peerId] || {}
 
     if (!storageId || isEphemeral) {
       return
@@ -299,33 +304,37 @@ export class Repo extends EventEmitter<RepoEvents> {
     let handler = this.#throttledSaveSyncStateHandlers[storageId]
     if (!handler) {
       handler = this.#throttledSaveSyncStateHandlers[storageId] = throttle(
-        ({ documentId, syncState }: SyncStateMessage) => {
-          this.storageSubsystem!.saveSyncState(documentId, storageId, syncState)
-            .catch(err => {
-              this.#log("error saving sync state", { err })
-            })
+        ({ documentId, syncState }: SyncStatePayload) => {
+          void this.storageSubsystem!.saveSyncState(
+            documentId,
+            storageId,
+            syncState
+          )
         },
         this.saveDebounceRate
       )
     }
 
-    handler(message)
+    handler(payload)
   }
 
   /** Returns an existing handle if we have it; creates one otherwise. */
-  #getHandle<T>(
+  #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 */
+    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 })
+    const handle = new DocHandle<T>(documentId, { isNew, initialValue })
     this.#handleCache[documentId] = handle
     return handle
   }
@@ -345,32 +354,18 @@ export class Repo extends EventEmitter<RepoEvents> {
   }
 
   /**
-   * Creates a new document and returns a handle to it. The initial value of the document is
-   * an empty object `{}`. Its documentId is generated by the system. we emit a `document` event
-   * to advertise interest in the document.
+   * Creates a new document and returns a handle to it. The initial value of the document is an
+   * empty object `{}` unless an initial value is provided. Its documentId is generated by the
+   * system. we emit a `document` event to advertise interest in the document.
    */
-  create<T>(): DocHandle<T> {
-    // TODO:
-    // either
-    // - pass an initial value and do something like this to ensure that you get a valid initial value
-
-    // const myInitialValue = {
-    //   tasks: [],
-    //   filter: "all",
-    //
-    // const guaranteeInitialValue = (doc: any) => {
-    // if (!doc.tasks) doc.tasks = []
-    // if (!doc.filter) doc.filter = "all"
-
-    //   return { ...myInitialValue, ...doc }
-    // }
-
-    // or
-    // - pass a "reify" function that takes a `<any>` and returns `<T>`
-
+  create<T>(initialValue?: T): DocHandle<T> {
     // Generate a new UUID and store it in the buffer
     const { documentId } = parseAutomergeUrl(generateAutomergeUrl())
-    const handle = this.#getHandle<T>(documentId, true) as DocHandle<T>
+    const handle = this.#getHandle<T>({
+      documentId,
+      isNew: true,
+      initialValue,
+    }) as DocHandle<T>
     this.emit("document", { handle, isNew: true })
     return handle
   }
@@ -436,7 +431,10 @@ export class Repo extends EventEmitter<RepoEvents> {
       return this.#handleCache[documentId]
     }
 
-    const handle = this.#getHandle<T>(documentId, false) as DocHandle<T>
+    const handle = this.#getHandle<T>({
+      documentId,
+      isNew: false,
+    }) as DocHandle<T>
     this.emit("document", { handle, isNew: false })
     return handle
   }
@@ -447,13 +445,29 @@ export class Repo extends EventEmitter<RepoEvents> {
   ) {
     const documentId = interpretAsDocumentId(id)
 
-    const handle = this.#getHandle(documentId, false)
+    const handle = this.#getHandle({ documentId, isNew: false })
     handle.delete()
 
     delete this.#handleCache[documentId]
     this.emit("delete-document", { documentId })
   }
 
+  /**
+   * Exports a document to a binary format.
+   * @param id - The url or documentId of the handle to export
+   *
+   * @returns Promise<Uint8Array | undefined> - A Promise containing the binary document,
+   * or undefined if the document is unavailable.
+   */
+  async export(id: AnyDocumentId): Promise<Uint8Array | undefined> {
+    const documentId = interpretAsDocumentId(id)
+
+    const handle = this.#getHandle({ documentId, isNew: false })
+    const doc = await handle.doc()
+    if (!doc) return undefined
+    return Automerge.save(doc)
+  }
+
   /**
    * Imports document binary into the repo.
    * @param binary - The binary to import
@@ -471,8 +485,14 @@ export class Repo extends EventEmitter<RepoEvents> {
   }
 
   subscribeToRemotes = (remotes: StorageId[]) => {
-    this.#log("subscribeToRemotes", { remotes })
-    this.#remoteHeadsSubscriptions.subscribeToRemotes(remotes)
+    if (this.#remoteHeadsGossipingEnabled) {
+      this.#log("subscribeToRemotes", { remotes })
+      this.#remoteHeadsSubscriptions.subscribeToRemotes(remotes)
+    } else {
+      this.#log(
+        "WARN: subscribeToRemotes called but remote heads gossiping is not enabled"
+      )
+    }
   }
 
   storageId = async (): Promise<StorageId | undefined> => {
@@ -493,16 +513,21 @@ export interface RepoConfig {
   isEphemeral?: boolean
 
   /** A storage adapter can be provided, or not */
-  storage?: StorageAdapter
+  storage?: StorageAdapterInterface
 
   /** One or more network adapters must be provided */
-  network: NetworkAdapter[]
+  network: NetworkAdapterInterface[]
 
   /**
    * Normal peers typically share generously with everyone (meaning we sync all our documents with
    * all peers). A server only syncs documents that a peer explicitly requests by ID.
    */
   sharePolicy?: SharePolicy
+
+  /**
+   * Whether to enable the experimental remote heads gossiping feature
+   */
+  enableRemoteHeadsGossiping?: boolean
 }
 
 /** A function that determines whether we should share a document with a peer

package/src/helpers/pause.ts

@@ -1,14 +1,6 @@
+/* c8 ignore start */
+
 export const pause = (t = 0) =>
   new Promise<void>(resolve => setTimeout(() => resolve(), t))
 
-export function rejectOnTimeout<T>(
-  promise: Promise<T>,
-  millis: number
-): Promise<T> {
-  return Promise.race([
-    promise,
-    pause(millis).then(() => {
-      throw new Error("timeout exceeded")
-    }),
-  ])
-}
+/* c8 ignore end */

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

@@ -1,6 +1,7 @@
 import assert from "assert"
-import { describe, it } from "vitest"
-import { PeerId, Repo, type NetworkAdapter } from "../../index.js"
+import { describe, expect, it } from "vitest"
+import { 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"
 
@@ -29,7 +30,10 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
 
   describe(`Adapter acceptance tests ${title ? `(${title})` : ""}`, () => {
     it("can sync 2 repos", async () => {
-      const doTest = async (a: NetworkAdapter[], b: NetworkAdapter[]) => {
+      const doTest = async (
+        a: NetworkAdapterInterface[],
+        b: NetworkAdapterInterface[]
+      ) => {
         const aliceRepo = new Repo({ network: a, peerId: alice })
         const bobRepo = new Repo({ network: b, peerId: bob })
 
@@ -141,12 +145,34 @@ export function runAdapterTests(_setup: SetupFn, title?: string): void {
       assert.deepStrictEqual(message, alicePresenceData)
       teardown()
     })
+
+    it("emits a peer-candidate event with proper peer metadata when a peer connects", async () => {
+      const { adapters, teardown } = await setup()
+      const a = adapters[0][0]
+      const b = adapters[1][0]
+
+      const bPromise = eventPromise(b, "peer-candidate")
+
+      const aPeerMetadata: PeerMetadata = { storageId: "a" as StorageId }
+
+      b.connect("b" as PeerId, { storageId: "b" as StorageId })
+      a.connect("a" as PeerId, aPeerMetadata)
+
+      const peerCandidate = await bPromise
+
+      expect(peerCandidate).toMatchObject({
+        peerId: "a",
+        peerMetadata: aPeerMetadata,
+      })
+
+      teardown()
+    })
   })
 }
 
 const NO_OP = () => {}
 
-type Network = NetworkAdapter | NetworkAdapter[]
+type Network = NetworkAdapterInterface | NetworkAdapterInterface[]
 
 export type SetupFn = () => Promise<{
   adapters: [Network, Network, Network]

package/src/helpers/withTimeout.ts

@@ -1,3 +1,4 @@
+/* c8 ignore start */
 /**
  * If `promise` is resolved before `t` ms elapse, the timeout is cleared and the result of the
  * promise is returned. If the timeout ends first, a `TimeoutError` is thrown.
@@ -26,3 +27,4 @@ export class TimeoutError extends Error {
     this.name = "TimeoutError"
   }
 }
+/* c8 ignore end */

package/src/index.ts

@@ -34,8 +34,10 @@ export {
 } from "./AutomergeUrl.js"
 export { Repo } from "./Repo.js"
 export { NetworkAdapter } from "./network/NetworkAdapter.js"
-export { isValidRepoMessage } from "./network/messages.js"
+export type { NetworkAdapterInterface } from "./network/NetworkAdapterInterface.js"
+export { isRepoMessage } from "./network/messages.js"
 export { StorageAdapter } from "./storage/StorageAdapter.js"
+export type { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js"
 
 /** @hidden **/
 export * as cbor from "./helpers/cbor.js"
@@ -68,7 +70,7 @@ export type {
   PeerCandidatePayload,
   PeerDisconnectedPayload,
   PeerMetadata,
-} from "./network/NetworkAdapter.js"
+} from "./network/NetworkAdapterInterface.js"
 
 export type {
   DocumentUnavailableMessage,