@automerge/automerge-repo 1.2.0 → 2.0.0-alpha.0

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.0",
+  "version": "2.0.0-alpha.0",
   "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.3",
+    "@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": "06126099322474bb8c6251b58b1ee5e63c174f06"
+  "gitHead": "16356392fb2ed9245565ae04f6e6b49e61195e65"
 }

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"

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/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() {}