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

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

@@ -1,6 +1,6 @@
 import assert from "assert";
 import { describe, expect, it } from "vitest";
-import { Repo } from "../../index.js";
+import { generateAutomergeUrl, parseAutomergeUrl, Repo, } from "../../index.js";
 import { eventPromise, eventPromises } from "../eventPromise.js";
 import { pause } from "../pause.js";
 /**
@@ -125,6 +125,93 @@ export function runNetworkAdapterTests(_setup, title) {
             });
             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";
+            const rightPeerId = "right";
+            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";
+            const rightPeerId = "right";
+            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";
+            const rightPeerId = "right";
+            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();
+        });
     });
 }
 const NO_OP = () => { };

package/dist/helpers/throttle.d.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/dist/helpers/throttle.js

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

package/dist/network/NetworkAdapter.d.ts

@@ -16,6 +16,8 @@ import { NetworkAdapterInterface } from "./NetworkAdapterInterface.js";
 export declare abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents> implements NetworkAdapterInterface {
     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/dist/network/NetworkAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkAdapter.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAEtE;;;;;;;;;GASG;AACH,8BAAsB,cACpB,SAAQ,YAAY,CAAC,oBAAoB,CACzC,YAAW,uBAAuB;IAElC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAEnE;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAErC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,IAAI,IAAI;CAC5B"}
+{"version":3,"file":"NetworkAdapter.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAEtE;;;;;;;;;GASG;AACH,8BAAsB,cACpB,SAAQ,YAAY,CAAC,oBAAoB,CACzC,YAAW,uBAAuB;IAElC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,QAAQ,CAAC,OAAO,IAAI,OAAO;IAC3B,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI;IAEnE;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAErC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,IAAI,IAAI;CAC5B"}

package/dist/network/NetworkAdapterInterface.d.ts

@@ -26,6 +26,8 @@ export interface PeerMetadata {
 export interface NetworkAdapterInterface extends EventEmitter<NetworkAdapterEvents> {
     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
@@ -41,8 +43,6 @@ export interface NetworkAdapterInterface extends EventEmitter<NetworkAdapterEven
     disconnect(): void;
 }
 export interface NetworkAdapterEvents {
-    /** Emitted when the network is ready to be used */
-    ready: (payload: OpenPayload) => void;
     /** Emitted when the network is closed */
     close: () => void;
     /** Emitted when the network adapter learns about a new peer */

package/dist/network/NetworkAdapterInterface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkAdapterInterface.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapterInterface.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBACf,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAE1D;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAE5B,gEAAgE;IAChE,UAAU,IAAI,IAAI,CAAA;CACnB;AAID,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IAErC,yCAAyC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAA;IAEjB,+DAA+D;IAC/D,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAEzD,2EAA2E;IAC3E,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAE/D,sEAAsE;IACtE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,uBAAuB,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"NetworkAdapterInterface.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapterInterface.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,uBACf,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,YAAY,CAAA;IAE3B,OAAO,IAAI,OAAO,CAAA;IAClB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IAE1B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAG1D;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAE5B,gEAAgE;IAChE,UAAU,IAAI,IAAI,CAAA;CACnB;AAID,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAA;IAEjB,+DAA+D;IAC/D,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IAEzD,2EAA2E;IAC3E,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAE/D,sEAAsE;IACtE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,uBAAuB,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;CACf"}

package/dist/network/NetworkSubsystem.d.ts

@@ -6,17 +6,20 @@ export declare class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvent
     #private;
     peerId: PeerId;
     private peerMetadata;
+    adapters: NetworkAdapterInterface[];
     constructor(adapters: NetworkAdapterInterface[], peerId: PeerId, peerMetadata: Promise<PeerMetadata>);
+    disconnect(): void;
+    reconnect(): void;
     addNetworkAdapter(networkAdapter: NetworkAdapterInterface): void;
+    removeNetworkAdapter(networkAdapter: NetworkAdapterInterface): void;
     send(message: MessageContents): void;
     isReady: () => boolean;
-    whenReady: () => Promise<void>;
+    whenReady: () => Promise<void[]>;
 }
 export interface NetworkSubsystemEvents {
     peer: (payload: PeerPayload) => void;
     "peer-disconnected": (payload: PeerDisconnectedPayload) => void;
     message: (payload: RepoMessage) => void;
-    ready: () => void;
 }
 export interface PeerPayload {
     peerId: PeerId;

package/dist/network/NetworkSubsystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkSubsystem.d.ts","sourceRoot":"","sources":["../../src/network/NetworkSubsystem.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAa,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACb,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAEL,eAAe,EACf,WAAW,EAGZ,MAAM,eAAe,CAAA;AAOtB,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;IAY/D,MAAM;IACb,OAAO,CAAC,YAAY;gBAFpB,QAAQ,EAAE,uBAAuB,EAAE,EAC5B,MAAM,QAAiB,EACtB,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC;IAO7C,iBAAiB,CAAC,cAAc,EAAE,uBAAuB;IA2EzD,IAAI,CAAC,OAAO,EAAE,eAAe;IAsC7B,OAAO,gBAEN;IAED,SAAS,sBAUR;CACF;AAQD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACpC,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC/D,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACvC,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,YAAY,CAAA;CAC3B"}
+{"version":3,"file":"NetworkSubsystem.d.ts","sourceRoot":"","sources":["../../src/network/NetworkSubsystem.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAa,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EACV,uBAAuB,EACvB,uBAAuB,EACvB,YAAY,EACb,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAEL,eAAe,EACf,WAAW,EAGZ,MAAM,eAAe,CAAA;AAOtB,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;IAW/D,MAAM,EAAE,MAAM;IACrB,OAAO,CAAC,YAAY;IALtB,QAAQ,EAAE,uBAAuB,EAAE,CAAK;gBAGtC,QAAQ,EAAE,uBAAuB,EAAE,EAC5B,MAAM,EAAE,MAAM,EACb,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC;IAO7C,UAAU;IAIV,SAAS;IAIT,iBAAiB,CAAC,cAAc,EAAE,uBAAuB;IAqEzD,oBAAoB,CAAC,cAAc,EAAE,uBAAuB;IAK5D,IAAI,CAAC,OAAO,EAAE,eAAe;IAsC7B,OAAO,gBAEN;IAED,SAAS,wBAER;CACF;AAID,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACpC,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC/D,OAAO,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,YAAY,CAAA;CAC3B"}

package/dist/network/NetworkSubsystem.js

@@ -10,27 +10,29 @@ export class NetworkSubsystem extends EventEmitter {
     #count = 0;
     #sessionId = Math.random().toString(36).slice(2);
     #ephemeralSessionCounts = {};
-    #readyAdapterCount = 0;
-    #adapters = [];
-    constructor(adapters, peerId = randomPeerId(), peerMetadata) {
+    adapters = [];
+    constructor(adapters, peerId, peerMetadata) {
         super();
         this.peerId = peerId;
         this.peerMetadata = peerMetadata;
         this.#log = debug(`automerge-repo:network:${this.peerId}`);
         adapters.forEach(a => this.addNetworkAdapter(a));
     }
+    disconnect() {
+        this.adapters.forEach(a => a.disconnect());
+    }
+    reconnect() {
+        this.adapters.forEach(a => a.connect(this.peerId));
+    }
     addNetworkAdapter(networkAdapter) {
-        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;
@@ -75,6 +77,12 @@ export class NetworkSubsystem extends EventEmitter {
             this.#log("error connecting to network", err);
         });
     }
+    // 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) {
+        this.adapters = this.adapters.filter(a => a !== networkAdapter);
+        networkAdapter.disconnect();
+    }
     send(message) {
         const peer = this.#adaptersByPeer[message.targetId];
         if (!peer) {
@@ -113,21 +121,9 @@ export class NetworkSubsystem extends EventEmitter {
         peer.send(outbound);
     }
     isReady = () => {
-        return this.#readyAdapterCount === this.#adapters.length;
+        return this.adapters.every(a => a.isReady());
     };
     whenReady = async () => {
-        if (this.isReady()) {
-            return;
-        }
-        else {
-            return new Promise(resolve => {
-                this.once("ready", () => {
-                    resolve();
-                });
-            });
-        }
+        return Promise.all(this.adapters.map(a => a.whenReady()));
     };
 }
-function randomPeerId() {
-    return `user-${Math.round(Math.random() * 100000)}`;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.2.1",
+  "version": "2.0.0-alpha.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>",
@@ -23,7 +23,7 @@
     "vite": "^5.0.8"
   },
   "dependencies": {
-    "@automerge/automerge": "^2.2.5",
+    "@automerge/automerge": "^2.2.7",
     "bs58check": "^3.0.1",
     "cbor-x": "^1.3.0",
     "debug": "^4.3.4",
@@ -60,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "2108823d685e855977defb75a938838a3734818b"
+  "gitHead": "86421aba21c8037b916ee93f962df1c121fef52b"
 }

package/src/AutomergeUrl.ts

@@ -57,9 +57,8 @@ export const stringifyAutomergeUrl = (
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
  * discriminator in Typescript.
  */
-export const isValidAutomergeUrl = (
-  str: string | undefined | null
-): str is AutomergeUrl => {
+export const isValidAutomergeUrl = (str: unknown): str is AutomergeUrl => {
+  if (typeof str !== "string") return false
   if (!str || !str.startsWith(urlPrefix)) return false
   const automergeUrl = str as AutomergeUrl
   try {
@@ -70,7 +69,8 @@ export const isValidAutomergeUrl = (
   }
 }
 
-export const isValidDocumentId = (str: string): str is DocumentId => {
+export const isValidDocumentId = (str: unknown): str is DocumentId => {
+  if (typeof str !== "string") return false
   // try to decode from base58
   const binaryDocumentID = documentIdToBinary(str as DocumentId)
   if (binaryDocumentID === undefined) return false // invalid base58check encoding
@@ -80,8 +80,8 @@ export const isValidDocumentId = (str: string): str is DocumentId => {
   return Uuid.validate(documentId)
 }
 
-export const isValidUuid = (str: string): str is LegacyDocumentId =>
-  Uuid.validate(str)
+export const isValidUuid = (str: unknown): str is LegacyDocumentId =>
+  typeof str === "string" && Uuid.validate(str)
 
 /**
  * Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.

package/src/DocHandle.ts

@@ -29,7 +29,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   #machine
 
   /** The last known state of our document. */
-  #prevDocState: T | undefined
+  #prevDocState: T = A.init<T>()
 
   /** How long to wait before giving up on a document. (Note that a document will be marked
    * unavailable much sooner if all known peers respond that they don't have it.) */
@@ -49,17 +49,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       this.#timeoutDelay = options.timeoutDelay
     }
 
-    let doc: T
-    const isNew = "isNew" in options && options.isNew
-    if (isNew) {
-      // 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>()
-    }
+    const doc = A.init<T>()
 
     this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
 
@@ -80,7 +70,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
         }),
         onDelete: assign(() => {
           this.emit("delete", { handle: this })
-          return { doc: undefined }
+          return { doc: A.init() }
         }),
         onUnavailable: () => {
           this.emit("unavailable", { handle: this })
@@ -101,21 +91,16 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       states: {
         idle: {
           on: {
-            CREATE: "ready",
-            FIND: "loading",
+            BEGIN: "loading",
           },
         },
         loading: {
           on: {
             REQUEST: "requesting",
             DOC_READY: "ready",
-            AWAIT_NETWORK: "awaitingNetwork",
           },
           after: { [delay]: "unavailable" },
         },
-        awaitingNetwork: {
-          on: { NETWORK_READY: "requesting" },
-        },
         requesting: {
           on: {
             DOC_UNAVAILABLE: "unavailable",
@@ -146,7 +131,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
 
     // Start the machine, and send a create or find event to get things going
     this.#machine.start()
-    this.#machine.send(isNew ? { type: CREATE } : { type: FIND })
+    this.#machine.send({ type: BEGIN })
   }
 
   // PRIVATE
@@ -178,13 +163,14 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * Called after state transitions. If the document has changed, emits a change event. If we just
    * received the document for the first time, signal that our request has been completed.
    */
-  #checkForChanges(before: T | undefined, after: T) {
-    const docChanged =
-      after && before && !headsAreSame(A.getHeads(after), A.getHeads(before))
+  #checkForChanges(before: A.Doc<T>, after: A.Doc<T>) {
+    const beforeHeads = A.getHeads(before)
+    const afterHeads = A.getHeads(after)
+    const docChanged = !headsAreSame(afterHeads, beforeHeads)
     if (docChanged) {
       this.emit("heads-changed", { handle: this, doc: after })
 
-      const patches = A.diff(after, A.getHeads(before), A.getHeads(after))
+      const patches = A.diff(after, beforeHeads, afterHeads)
       if (patches.length > 0) {
         this.emit("change", {
           handle: this,
@@ -306,14 +292,24 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * `update` is called by the repo when we receive changes from the network
-   * Called by the repo when we receive changes from the network.
+   * `update` is called any time we have a new document state; could be
+   * from a local change, a remote change, or a new document from storage.
+   * Does not cause state changes.
    * @hidden
    */
   update(callback: (doc: A.Doc<T>) => A.Doc<T>) {
     this.#machine.send({ type: UPDATE, payload: { callback } })
   }
 
+  /**
+   * `doneLoading` is called by the repo after it decides it has all the changes
+   * it's going to get during setup. This might mean it was created locally,
+   * or that it was loaded from storage, or that it was received from a peer.
+   */
+  doneLoading() {
+    this.#machine.send({ type: DOC_READY })
+  }
+
   /**
    * Called by the repo either when a doc handle changes or we receive new remote heads.
    * @hidden
@@ -346,7 +342,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   change(callback: A.ChangeFn<T>, options: A.ChangeOptions<T> = {}) {
     if (!this.isReady()) {
       throw new Error(
-        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before accessing the document.`
+        `DocHandle#${this.documentId} is in ${this.state} and not ready. Check \`handle.isReady()\` before accessing the document.`
       )
     }
     this.#machine.send({
@@ -425,17 +421,6 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     if (this.#state === "loading") this.#machine.send({ type: REQUEST })
   }
 
-  /** @hidden */
-  awaitNetwork() {
-    if (this.#state === "loading") this.#machine.send({ type: AWAIT_NETWORK })
-  }
-
-  /** @hidden */
-  networkReady() {
-    if (this.#state === "awaitingNetwork")
-      this.#machine.send({ type: NETWORK_READY })
-  }
-
   /** Called by the repo when the document is deleted. */
   delete() {
     this.#machine.send({ type: DELETE })
@@ -550,8 +535,6 @@ export const HandleState = {
   IDLE: "idle",
   /** We are waiting for storage to finish loading */
   LOADING: "loading",
-  /** We are waiting for the network to be come ready */
-  AWAITING_NETWORK: "awaitingNetwork",
   /** We are waiting for someone in the network to respond to a sync request */
   REQUESTING: "requesting",
   /** The document is available */
@@ -563,15 +546,8 @@ export const HandleState = {
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]
 
-export const {
-  IDLE,
-  LOADING,
-  AWAITING_NETWORK,
-  REQUESTING,
-  READY,
-  DELETED,
-  UNAVAILABLE,
-} = HandleState
+export const { IDLE, LOADING, REQUESTING, READY, DELETED, UNAVAILABLE } =
+  HandleState
 
 // context
 
@@ -584,8 +560,7 @@ interface DocHandleContext<T> {
 
 /** These are the (internal) events that can be sent to the state machine */
 type DocHandleEvent<T> =
-  | { type: typeof CREATE }
-  | { type: typeof FIND }
+  | { type: typeof BEGIN }
   | { type: typeof REQUEST }
   | { type: typeof DOC_READY }
   | {
@@ -595,15 +570,10 @@ type DocHandleEvent<T> =
   | { type: typeof TIMEOUT }
   | { type: typeof DELETE }
   | { type: typeof DOC_UNAVAILABLE }
-  | { type: typeof AWAIT_NETWORK }
-  | { type: typeof NETWORK_READY }
 
-const CREATE = "CREATE"
-const FIND = "FIND"
+const BEGIN = "BEGIN"
 const REQUEST = "REQUEST"
 const DOC_READY = "DOC_READY"
-const AWAIT_NETWORK = "AWAIT_NETWORK"
-const NETWORK_READY = "NETWORK_READY"
 const UPDATE = "UPDATE"
 const DELETE = "DELETE"
 const TIMEOUT = "TIMEOUT"