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

package/README.md

@@ -38,15 +38,17 @@ This library provides two main components: the `Repo` itself, and the `DocHandle
 
 A `Repo` exposes these methods:
 
-- `create<T>()`  
-  Creates a new, empty `Automerge.Doc` and returns a `DocHandle` for it.
+- `create<T>(initialValue: T?)`
+  Creates a new `Automerge.Doc` and returns a `DocHandle` for it. Accepts an optional initial value for the document. Produces an empty document (potentially violating the type!) otherwise.
 - `find<T>(docId: DocumentId)`  
   Looks up a given document either on the local machine or (if necessary) over any configured
   networks.
 - `delete(docId: DocumentId)`  
   Deletes the local copy of a document from the local cache and local storage. _This does not currently delete the document from any other peers_.
 - `import(binary: Uint8Array)`  
-  Imports a document binary (from `Automerge.save(doc)`) into the repo, returning a new handle
+  Imports a document binary (from `export()` or `Automerge.save(doc)`) into the repo, returning a new handle
+- `export(docId: DocumentId)`  
+  Exports the document. Returns a Promise containing either the Uint8Array of the document or undefined if the document is currently unavailable. See the [Automerge binary format spec](https://automerge.org/automerge-binary-format-spec/) for more details on the shape of the Uint8Array.
 - `.on("document", ({handle: DocHandle}) => void)`  
   Registers a callback to be fired each time a new document is loaded or created.
 - `.on("delete-document", ({handle: DocHandle}) => void)`  

package/dist/AutomergeUrl.js

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

package/dist/DocHandle.d.ts

@@ -26,7 +26,7 @@ export declare class DocHandle<T>//
      */
     get url(): AutomergeUrl;
     /** @hidden */
-    constructor(documentId: DocumentId, { isNew, timeoutDelay }?: DocHandleOptions);
+    constructor(documentId: DocumentId, options?: DocHandleOptions<T>);
     /**
      * Checks if the document is ready for accessing or changes.
      * Note that for documents already stored locally this occurs before synchronization
@@ -120,10 +120,16 @@ export declare class DocHandle<T>//
     broadcast(message: unknown): void;
 }
 /** @hidden */
-export interface DocHandleOptions {
-    isNew?: boolean;
+export type DocHandleOptions<T> = {
+    /** 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;
+} | {
+    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;
     documentId: DocumentId;

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -24,7 +24,7 @@ export class DocHandle//
     documentId;
     #log;
     #machine;
-    #timeoutDelay;
+    #timeoutDelay = 60_000;
     #remoteHeads = {};
     /** The URL of this document
      *
@@ -35,17 +35,26 @@ export class DocHandle//
         return stringifyAutomergeUrl({ documentId: this.documentId });
     }
     /** @hidden */
-    constructor(documentId, { isNew = false, timeoutDelay = 60_000 } = {}) {
+    constructor(documentId, options = {}) {
         super();
         this.documentId = documentId;
-        this.#timeoutDelay = timeoutDelay;
-        this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`);
-        // initial doc
-        let doc = A.init();
-        // Make an empty change so that we have something to save to disk
+        this.documentId = documentId;
+        if ("timeoutDelay" in options && options.timeoutDelay) {
+            this.#timeoutDelay = options.timeoutDelay;
+        }
+        let doc;
+        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);
+            doc = A.emptyChange(doc);
         }
+        else {
+            doc = A.init();
+        }
+        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.
@@ -192,11 +201,10 @@ export class DocHandle//
     }
     /** Returns a promise that resolves when the docHandle is in one of the given states */
     #statePromise(awaitStates) {
-        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 });
     }
     // PUBLIC
     /**

package/dist/Repo.d.ts

@@ -1,11 +1,11 @@
 import { EventEmitter } from "eventemitter3";
 import { DocHandle } from "./DocHandle.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 { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
-import type { AnyDocumentId, DocumentId, PeerId } from "./types.js";
 import { StorageId } from "./storage/types.js";
+import type { AnyDocumentId, DocumentId, PeerId } from "./types.js";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -29,18 +29,18 @@ export declare class Repo extends EventEmitter<RepoEvents> {
     /** maps peer id to to persistence information (storageId, isEphemeral), access by collection synchronizer  */
     /** @hidden */
     peerMetadataByPeerId: Record<PeerId, PeerMetadata>;
-    constructor({ storage, network, peerId, sharePolicy, isEphemeral, }: RepoConfig);
+    constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, }: RepoConfig);
     /** Returns all the handles we have cached. */
     get handles(): Record<DocumentId, DocHandle<any>>;
     /** Returns a list of all connected peer ids */
     get peers(): PeerId[];
     getStorageIdOfPeer(peerId: PeerId): StorageId | undefined;
     /**
-     * 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>;
+    create<T>(initialValue?: T): DocHandle<T>;
     /** Create a new DocHandle by cloning the history of an existing DocHandle.
      *
      * @param clonedHandle - The handle to clone
@@ -67,6 +67,14 @@ export declare class Repo extends EventEmitter<RepoEvents> {
     delete(
     /** The url or documentId of the handle to delete */
     id: AnyDocumentId): void;
+    /**
+     * 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.
+     */
+    export(id: AnyDocumentId): Promise<Uint8Array | undefined>;
     /**
      * Imports document binary into the repo.
      * @param binary - The binary to import
@@ -82,14 +90,18 @@ export interface RepoConfig {
      * Sync state is only persisted for non-ephemeral peers */
     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/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}

package/dist/Repo.js

@@ -3,12 +3,12 @@ import debug from "debug";
 import { EventEmitter } from "eventemitter3";
 import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
 import { DocHandle } from "./DocHandle.js";
+import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js";
+import { headsAreSame } from "./helpers/headsAreSame.js";
 import { throttle } from "./helpers/throttle.js";
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.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
  *
@@ -35,8 +35,10 @@ export class Repo extends EventEmitter {
     /** @hidden */
     peerMetadataByPeerId = {};
     #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions();
-    constructor({ storage, network, peerId, sharePolicy, isEphemeral = storage === undefined, }) {
+    #remoteHeadsGossipingEnabled = false;
+    constructor({ storage, network, peerId, sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, }) {
         super();
+        this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping;
         this.#log = debug(`automerge-repo:repo`);
         this.sharePolicy = sharePolicy ?? this.sharePolicy;
         // DOC COLLECTION
@@ -101,21 +103,21 @@ export class Repo extends EventEmitter {
             this.#log(`sending ${message.type} message to ${message.targetId}`);
             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.
         const storageSubsystem = storage ? new StorageSubsystem(storage) : undefined;
         this.storageSubsystem = storageSubsystem;
         // NETWORK
         // The network subsystem deals with sending and receiving messages to and from peers.
-        const myPeerMetadata = new Promise(
-        // eslint-disable-next-line no-async-promise-executor -- TODO: fix
-        async (resolve) => resolve({
+        const myPeerMetadata = (async () => ({
             storageId: await storageSubsystem?.id(),
             isEphemeral,
-        }));
+        }))();
         const networkSubsystem = new NetworkSubsystem(network, peerId, myPeerMetadata);
         this.networkSubsystem = networkSubsystem;
         // When we get a new peer, register it with the synchronizer
@@ -126,7 +128,7 @@ export class Repo extends EventEmitter {
             }
             this.sharePolicy(peerId)
                 .then(shouldShare => {
-                if (shouldShare) {
+                if (shouldShare && this.#remoteHeadsGossipingEnabled) {
                     this.#remoteHeadsSubscriptions.addGenerousPeer(peerId);
                 }
             })
@@ -156,47 +158,53 @@ export class Repo extends EventEmitter {
                 (!heads || !headsAreSame(heads, message.syncState.theirHeads));
             if (haveHeadsChanged) {
                 handle.setRemoteHeads(storageId, message.syncState.theirHeads);
-                if (storageId) {
+                if (storageId && this.#remoteHeadsGossipingEnabled) {
                     this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, message.syncState.theirHeads);
                 }
             }
         });
-        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) {
+        if (this.#remoteHeadsGossipingEnabled) {
+            this.#remoteHeadsSubscriptions.on("notify-remote-heads", message => {
                 this.networkSubsystem.send({
-                    type: "remote-subscription-change",
-                    targetId: peer,
-                    add: message.add,
-                    remove: message.remove,
+                    type: "remote-heads-changed",
+                    targetId: message.targetId,
+                    documentId: message.documentId,
+                    newHeads: {
+                        [message.storageId]: {
+                            heads: message.heads,
+                            timestamp: message.timestamp,
+                        },
+                    },
                 });
-            }
-        });
-        this.#remoteHeadsSubscriptions.on("remote-heads-changed", message => {
-            const handle = this.#handleCache[message.documentId];
-            handle.setRemoteHeads(message.storageId, message.remoteHeads);
-        });
+            });
+            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);
+            });
+        }
     }
     #receiveMessage(message) {
         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":
@@ -209,38 +217,31 @@ export class Repo extends EventEmitter {
     }
     #throttledSaveSyncStateHandlers = {};
     /** 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) {
+    #saveSyncState(payload) {
         if (!this.storageSubsystem) {
             return;
         }
-        const { storageId, isEphemeral } = this.peerMetadataByPeerId[message.peerId] || {};
+        const { storageId, isEphemeral } = this.peerMetadataByPeerId[payload.peerId] || {};
         if (!storageId || isEphemeral) {
             return;
         }
         let handler = this.#throttledSaveSyncStateHandlers[storageId];
         if (!handler) {
             handler = this.#throttledSaveSyncStateHandlers[storageId] = throttle(({ documentId, syncState }) => {
-                this.storageSubsystem.saveSyncState(documentId, storageId, syncState)
-                    .catch(err => {
-                    this.#log("error saving sync state", { err });
-                });
+                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(
-    /** The documentId of the handle to look up or create */
-    documentId, 
-    /** If we know we're creating a new document, specify this so we can have access to it immediately */
-    isNew) {
+    #getHandle({ documentId, isNew, initialValue, }) {
         // 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(documentId, { isNew });
+        const handle = new DocHandle(documentId, { isNew, initialValue });
         this.#handleCache[documentId] = handle;
         return handle;
     }
@@ -256,28 +257,18 @@ export class Repo extends EventEmitter {
         return this.peerMetadataByPeerId[peerId]?.storageId;
     }
     /**
-     * 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() {
-        // 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(initialValue) {
         // Generate a new UUID and store it in the buffer
         const { documentId } = parseAutomergeUrl(generateAutomergeUrl());
-        const handle = this.#getHandle(documentId, true);
+        const handle = this.#getHandle({
+            documentId,
+            isNew: true,
+            initialValue,
+        });
         this.emit("document", { handle, isNew: true });
         return handle;
     }
@@ -332,7 +323,10 @@ export class Repo extends EventEmitter {
             }
             return this.#handleCache[documentId];
         }
-        const handle = this.#getHandle(documentId, false);
+        const handle = this.#getHandle({
+            documentId,
+            isNew: false,
+        });
         this.emit("document", { handle, isNew: false });
         return handle;
     }
@@ -340,11 +334,26 @@ export class Repo extends EventEmitter {
     /** The url or documentId of the handle to delete */
     id) {
         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) {
+        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
@@ -358,8 +367,13 @@ export class Repo extends EventEmitter {
         return handle;
     }
     subscribeToRemotes = (remotes) => {
-        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 () => {
         if (!this.storageSubsystem) {

package/dist/helpers/pause.d.ts

@@ -1,3 +1,2 @@
 export declare const pause: (t?: number) => Promise<void>;
-export declare function rejectOnTimeout<T>(promise: Promise<T>, millis: number): Promise<T>;
 //# sourceMappingURL=pause.d.ts.map

package/dist/helpers/pause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pause.d.ts","sourceRoot":"","sources":["../../src/helpers/pause.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,+BAC4C,CAAA;AAE9D,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,CAAC,CAAC,CAOZ"}
+{"version":3,"file":"pause.d.ts","sourceRoot":"","sources":["../../src/helpers/pause.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,KAAK,+BAC4C,CAAA"}

package/dist/helpers/pause.js

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

package/dist/helpers/tests/network-adapter-tests.d.ts

@@ -1,4 +1,4 @@
-import { type NetworkAdapter } from "../../index.js";
+import type { NetworkAdapterInterface } from "../../network/NetworkAdapterInterface.js";
 /**
  * Runs a series of tests against a set of three peers, each represented by one or more instantiated
  * network adapters.
@@ -12,7 +12,7 @@ import { type NetworkAdapter } from "../../index.js";
  *   to clean up any resources that were created during the test.
  */
 export declare function runAdapterTests(_setup: SetupFn, title?: string): void;
-type Network = NetworkAdapter | NetworkAdapter[];
+type Network = NetworkAdapterInterface | NetworkAdapterInterface[];
 export type SetupFn = () => Promise<{
     adapters: [Network, Network, Network];
     teardown?: () => void;

package/dist/helpers/tests/network-adapter-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/network-adapter-tests.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAIlE;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA8HrE;AAID,KAAK,OAAO,GAAG,cAAc,GAAG,cAAc,EAAE,CAAA;AAEhD,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAC,CAAA"}
+{"version":3,"file":"network-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/network-adapter-tests.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAIvF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAuJrE;AAID,KAAK,OAAO,GAAG,uBAAuB,GAAG,uBAAuB,EAAE,CAAA;AAElE,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;IACrC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAC,CAAA"}

package/dist/helpers/tests/network-adapter-tests.js

@@ -1,5 +1,5 @@
 import assert from "assert";
-import { describe, it } from "vitest";
+import { describe, expect, it } from "vitest";
 import { Repo } from "../../index.js";
 import { eventPromise, eventPromises } from "../eventPromise.js";
 import { pause } from "../pause.js";
@@ -110,6 +110,21 @@ export function runAdapterTests(_setup, title) {
             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 = { storageId: "a" };
+            b.connect("b", { storageId: "b" });
+            a.connect("a", aPeerMetadata);
+            const peerCandidate = await bPromise;
+            expect(peerCandidate).toMatchObject({
+                peerId: "a",
+                peerMetadata: aPeerMetadata,
+            });
+            teardown();
+        });
     });
 }
 const NO_OP = () => { };

package/dist/helpers/withTimeout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withTimeout.d.ts","sourceRoot":"","sources":["../../src/helpers/withTimeout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW,8BAEnB,MAAM,eAcV,CAAA;AAED,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B"}
+{"version":3,"file":"withTimeout.d.ts","sourceRoot":"","sources":["../../src/helpers/withTimeout.ts"],"names":[],"mappings":"AACA;;;GAGG;AACH,eAAO,MAAM,WAAW,8BAEnB,MAAM,eAcV,CAAA;AAED,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B"}

package/dist/helpers/withTimeout.js

@@ -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.
@@ -20,3 +21,4 @@ export class TimeoutError extends Error {
         this.name = "TimeoutError";
     }
 }
+/* c8 ignore end */

package/dist/index.d.ts

@@ -29,13 +29,15 @@ export { DocHandle } from "./DocHandle.js";
 export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } 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";
 export type { DocHandleChangePayload, DocHandleDeletePayload, DocHandleEncodedChangePayload, DocHandleEphemeralMessagePayload, DocHandleRemoteHeadsPayload, DocHandleEvents, DocHandleOptions, DocHandleOutboundEphemeralMessagePayload, HandleState, } from "./DocHandle.js";
 export type { DeleteDocumentPayload, DocumentPayload, RepoConfig, RepoEvents, SharePolicy, } from "./Repo.js";
-export type { NetworkAdapterEvents, OpenPayload, PeerCandidatePayload, PeerDisconnectedPayload, PeerMetadata, } from "./network/NetworkAdapter.js";
+export type { NetworkAdapterEvents, OpenPayload, PeerCandidatePayload, PeerDisconnectedPayload, PeerMetadata, } from "./network/NetworkAdapterInterface.js";
 export type { DocumentUnavailableMessage, EphemeralMessage, Message, RepoMessage, RequestMessage, SyncMessage, } from "./network/messages.js";
 export type { Chunk, ChunkInfo, ChunkType, StorageKey, StorageId, } from "./storage/types.js";
 export * from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAE5D,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,GACb,MAAM,6BAA6B,CAAA;AAEpC,YAAY,EACV,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,oBAAoB,CAAA;AAE3B,cAAc,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAEnF,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,GACb,MAAM,sCAAsC,CAAA;AAE7C,YAAY,EACV,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,oBAAoB,CAAA;AAE3B,cAAc,YAAY,CAAA"}