@automerge/automerge-repo 2.0.0-alpha.20 → 2.0.0-alpha.22

package/dist/helpers/abortable.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Creates a promise that rejects when the signal is aborted.
+ *
+ * @remarks
+ * This utility creates a promise that rejects when the provided AbortSignal is aborted.
+ * It's designed to be used with Promise.race() to make operations abortable.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * try {
+ *   const result = await Promise.race([
+ *     fetch('https://api.example.com/data'),
+ *     abortable(controller.signal)
+ *   ]);
+ * } catch (err) {
+ *   if (err.name === 'AbortError') {
+ *     console.log('The operation was aborted');
+ *   }
+ * }
+ *
+ * // Later, to abort:
+ * controller.abort();
+ * ```
+ *
+ * @param signal - An AbortSignal that can be used to abort the operation
+ * @param cleanup - Optional cleanup function that will be called if aborted
+ * @returns A promise that rejects with AbortError when the signal is aborted
+ * @throws {DOMException} With name "AbortError" when aborted
+ */
+export declare function abortable(signal?: AbortSignal, cleanup?: () => void): Promise<never>;
+/**
+ * Include this type in an options object to pass an AbortSignal to a function.
+ */
+export interface AbortOptions {
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=abortable.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abortable.d.ts","sourceRoot":"","sources":["../../src/helpers/abortable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS,CACvB,MAAM,CAAC,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,MAAM,IAAI,GACnB,OAAO,CAAC,KAAK,CAAC,CAmBhB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB"}

package/dist/helpers/abortable.js

@@ -0,0 +1,45 @@
+/**
+ * Creates a promise that rejects when the signal is aborted.
+ *
+ * @remarks
+ * This utility creates a promise that rejects when the provided AbortSignal is aborted.
+ * It's designed to be used with Promise.race() to make operations abortable.
+ *
+ * @example
+ * ```typescript
+ * const controller = new AbortController();
+ *
+ * try {
+ *   const result = await Promise.race([
+ *     fetch('https://api.example.com/data'),
+ *     abortable(controller.signal)
+ *   ]);
+ * } catch (err) {
+ *   if (err.name === 'AbortError') {
+ *     console.log('The operation was aborted');
+ *   }
+ * }
+ *
+ * // Later, to abort:
+ * controller.abort();
+ * ```
+ *
+ * @param signal - An AbortSignal that can be used to abort the operation
+ * @param cleanup - Optional cleanup function that will be called if aborted
+ * @returns A promise that rejects with AbortError when the signal is aborted
+ * @throws {DOMException} With name "AbortError" when aborted
+ */
+export function abortable(signal, cleanup) {
+    if (signal?.aborted) {
+        throw new DOMException("Operation aborted", "AbortError");
+    }
+    if (!signal) {
+        return new Promise(() => { }); // Never resolves
+    }
+    return new Promise((_, reject) => {
+        signal.addEventListener("abort", () => {
+            cleanup?.();
+            reject(new DOMException("Operation aborted", "AbortError"));
+        }, { once: true });
+    });
+}

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":"AAUA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAIvF;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0Q5E;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"}
+{"version":3,"file":"network-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/network-adapter-tests.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAIvF;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA2Q5E;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

@@ -30,23 +30,23 @@ export function runNetworkAdapterTests(_setup, title) {
                 const bobRepo = new Repo({ network: b, peerId: bob });
                 // Alice creates a document
                 const aliceHandle = aliceRepo.create();
-                // Bob receives the document
-                await eventPromise(bobRepo, "document");
-                const bobHandle = bobRepo.find(aliceHandle.url);
+                // TODO: ... let connections complete. this shouldn't be necessary.
+                await pause(50);
+                const bobHandle = await bobRepo.find(aliceHandle.url);
                 // Alice changes the document
                 aliceHandle.change(d => {
                     d.foo = "bar";
                 });
                 // Bob receives the change
                 await eventPromise(bobHandle, "change");
-                assert.equal((await bobHandle.doc())?.foo, "bar");
+                assert.equal((await bobHandle).doc()?.foo, "bar");
                 // Bob changes the document
                 bobHandle.change(d => {
                     d.foo = "baz";
                 });
                 // Alice receives the change
                 await eventPromise(aliceHandle, "change");
-                assert.equal((await aliceHandle.doc())?.foo, "baz");
+                assert.equal(aliceHandle.doc().foo, "baz");
             };
             // Run the test in both directions, in case they're different types of adapters
             {
@@ -72,25 +72,25 @@ export function runNetworkAdapterTests(_setup, title) {
             const aliceHandle = aliceRepo.create();
             const docUrl = aliceHandle.url;
             // Bob and Charlie receive the document
-            await eventPromises([bobRepo, charlieRepo], "document");
-            const bobHandle = bobRepo.find(docUrl);
-            const charlieHandle = charlieRepo.find(docUrl);
+            await pause(50);
+            const bobHandle = await bobRepo.find(docUrl);
+            const charlieHandle = await charlieRepo.find(docUrl);
             // Alice changes the document
             aliceHandle.change(d => {
                 d.foo = "bar";
             });
             // Bob and Charlie receive the change
             await eventPromises([bobHandle, charlieHandle], "change");
-            assert.equal((await bobHandle.doc())?.foo, "bar");
-            assert.equal((await charlieHandle.doc())?.foo, "bar");
+            assert.equal(bobHandle.doc().foo, "bar");
+            assert.equal(charlieHandle.doc().foo, "bar");
             // Charlie changes the document
             charlieHandle.change(d => {
                 d.foo = "baz";
             });
             // Alice and Bob receive the change
             await eventPromises([aliceHandle, bobHandle], "change");
-            assert.equal((await bobHandle.doc())?.foo, "baz");
-            assert.equal((await charlieHandle.doc())?.foo, "baz");
+            assert.equal(bobHandle.doc().foo, "baz");
+            assert.equal(charlieHandle.doc().foo, "baz");
             teardown();
         });
         it("can broadcast a message", async () => {
@@ -101,7 +101,7 @@ export function runNetworkAdapterTests(_setup, title) {
             const charlieRepo = new Repo({ network: c, peerId: charlie });
             await eventPromises([aliceRepo, bobRepo, charlieRepo].map(r => r.networkSubsystem), "peer");
             const aliceHandle = aliceRepo.create();
-            const charlieHandle = charlieRepo.find(aliceHandle.url);
+            const charlieHandle = await charlieRepo.find(aliceHandle.url);
             // pause to give charlie a chance to let alice know it wants the doc
             await pause(100);
             const alicePresenceData = { presence: "alice" };

package/dist/synchronizer/CollectionSynchronizer.d.ts

@@ -1,3 +1,4 @@
+import { DocHandle } from "../DocHandle.js";
 import { Repo } from "../Repo.js";
 import { DocMessage } from "../network/messages.js";
 import { AutomergeUrl, DocumentId, PeerId } from "../types.js";
@@ -19,7 +20,7 @@ export declare class CollectionSynchronizer extends Synchronizer {
     /**
      * Starts synchronizing the given document with all peers that we share it generously with.
      */
-    addDocument(documentId: DocumentId): void;
+    addDocument(handle: DocHandle<unknown>): void;
     removeDocument(documentId: DocumentId): void;
     /** Adds a peer and maybe starts synchronizing with them */
     addPeer(peerId: PeerId): void;

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

@@ -1 +1 @@
-{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAa1C,OAAO,CAAC,IAAI;IATxB,kDAAkD;IAClD,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAK;gBAOtC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,YAAY,EAAO;IAuD7D;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAsCxC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAalC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,IAAI;QACT,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7C,CAAA;KACF;CASF"}
+{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAE3C,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAa1C,OAAO,CAAC,IAAI;IATxB,kDAAkD;IAClD,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAK;gBAOtC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,YAAY,EAAO;IAwD7D;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAyCxC;;OAEG;IACH,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC;IAatC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,IAAI;QACT,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7C,CAAA;KACF;CASF"}

package/dist/synchronizer/CollectionSynchronizer.js

@@ -1,5 +1,5 @@
 import debug from "debug";
-import { parseAutomergeUrl, stringifyAutomergeUrl } from "../AutomergeUrl.js";
+import { parseAutomergeUrl } from "../AutomergeUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 const log = debug("automerge-repo:collectionsync");
@@ -20,17 +20,18 @@ export class CollectionSynchronizer extends Synchronizer {
         this.#denylist = denylist.map(url => parseAutomergeUrl(url).documentId);
     }
     /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
-    #fetchDocSynchronizer(documentId) {
-        if (!this.docSynchronizers[documentId]) {
-            const handle = this.repo.find(stringifyAutomergeUrl({ documentId }));
-            this.docSynchronizers[documentId] = this.#initDocSynchronizer(handle);
+    #fetchDocSynchronizer(handle) {
+        if (!this.docSynchronizers[handle.documentId]) {
+            this.docSynchronizers[handle.documentId] =
+                this.#initDocSynchronizer(handle);
         }
-        return this.docSynchronizers[documentId];
+        return this.docSynchronizers[handle.documentId];
     }
     /** Creates a new docSynchronizer and sets it up to propagate messages */
     #initDocSynchronizer(handle) {
         const docSynchronizer = new DocSynchronizer({
             handle,
+            peerId: this.repo.networkSubsystem.peerId,
             onLoadSyncState: async (peerId) => {
                 if (!this.repo.storageSubsystem) {
                     return;
@@ -83,23 +84,26 @@ export class CollectionSynchronizer extends Synchronizer {
             return;
         }
         this.#docSetUp[documentId] = true;
-        const docSynchronizer = this.#fetchDocSynchronizer(documentId);
+        const handle = await this.repo.find(documentId, {
+            allowableStates: ["ready", "unavailable", "requesting"],
+        });
+        const docSynchronizer = this.#fetchDocSynchronizer(handle);
         docSynchronizer.receiveMessage(message);
         // Initiate sync with any new peers
         const peers = await this.#documentGenerousPeers(documentId);
-        docSynchronizer.beginSync(peers.filter(peerId => !docSynchronizer.hasPeer(peerId)));
+        void docSynchronizer.beginSync(peers.filter(peerId => !docSynchronizer.hasPeer(peerId)));
     }
     /**
      * Starts synchronizing the given document with all peers that we share it generously with.
      */
-    addDocument(documentId) {
+    addDocument(handle) {
         // HACK: this is a hack to prevent us from adding the same document twice
-        if (this.#docSetUp[documentId]) {
+        if (this.#docSetUp[handle.documentId]) {
             return;
         }
-        const docSynchronizer = this.#fetchDocSynchronizer(documentId);
-        void this.#documentGenerousPeers(documentId).then(peers => {
-            docSynchronizer.beginSync(peers);
+        const docSynchronizer = this.#fetchDocSynchronizer(handle);
+        void this.#documentGenerousPeers(handle.documentId).then(peers => {
+            void docSynchronizer.beginSync(peers);
         });
     }
     // TODO: implement this
@@ -118,7 +122,7 @@ export class CollectionSynchronizer extends Synchronizer {
             const { documentId } = docSynchronizer;
             void this.repo.sharePolicy(peerId, documentId).then(okToShare => {
                 if (okToShare)
-                    docSynchronizer.beginSync([peerId]);
+                    void docSynchronizer.beginSync([peerId]);
             });
         }
     }

package/dist/synchronizer/DocSynchronizer.d.ts

@@ -6,6 +6,7 @@ import { Synchronizer } from "./Synchronizer.js";
 type PeerDocumentStatus = "unknown" | "has" | "unavailable" | "wants";
 interface DocSynchronizerConfig {
     handle: DocHandle<unknown>;
+    peerId: PeerId;
     onLoadSyncState?: (peerId: PeerId) => Promise<A.SyncState | undefined>;
 }
 /**
@@ -15,11 +16,11 @@ interface DocSynchronizerConfig {
 export declare class DocSynchronizer extends Synchronizer {
     #private;
     syncDebounceRate: number;
-    constructor({ handle, onLoadSyncState }: DocSynchronizerConfig);
+    constructor({ handle, peerId, onLoadSyncState }: DocSynchronizerConfig);
     get peerStates(): Record<PeerId, PeerDocumentStatus>;
     get documentId(): import("../types.js").DocumentId;
     hasPeer(peerId: PeerId): boolean;
-    beginSync(peerIds: PeerId[]): void;
+    beginSync(peerIds: PeerId[]): Promise<void>;
     endSync(peerId: PeerId): void;
     receiveMessage(message: RepoMessage): void;
     receiveEphemeralMessage(message: EphemeralMessage): void;

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

@@ -1 +1 @@
-{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAsBV,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IAyB9D,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAkID,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAmD3B,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;IAuFxD,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM7E"}
+{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAyBV,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IA0BtE,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAiID,OAAO,CAAC,MAAM,EAAE,MAAM;IAIhB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAwDjC,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;IAwFxD,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM7E"}

package/dist/synchronizer/DocSynchronizer.js

@@ -19,11 +19,15 @@ export class DocSynchronizer extends Synchronizer {
     /** Sync state for each peer we've communicated with (including inactive peers) */
     #syncStates = {};
     #pendingSyncMessages = [];
+    // We keep this around at least in part for debugging.
+    // eslint-disable-next-line no-unused-private-class-members
+    #peerId;
     #syncStarted = false;
     #handle;
     #onLoadSyncState;
-    constructor({ handle, onLoadSyncState }) {
+    constructor({ handle, peerId, onLoadSyncState }) {
         super();
+        this.#peerId = peerId;
         this.#handle = handle;
         this.#onLoadSyncState =
             onLoadSyncState ?? (() => Promise.resolve(undefined));
@@ -33,7 +37,7 @@ export class DocSynchronizer extends Synchronizer {
         handle.on("ephemeral-message-outbound", payload => this.#broadcastToPeers(payload));
         // Process pending sync messages immediately after the handle becomes ready.
         void (async () => {
-            await handle.doc([READY, REQUESTING]);
+            await handle.whenReady([READY, REQUESTING]);
             this.#processAllPendingSyncMessages();
         })();
     }
@@ -45,8 +49,7 @@ export class DocSynchronizer extends Synchronizer {
     }
     /// PRIVATE
     async #syncWithPeers() {
-        this.#log(`syncWithPeers`);
-        const doc = await this.#handle.doc();
+        const doc = await this.#handle.legacyAsyncDoc(); // XXX THIS ONE IS WEIRD
         if (doc === undefined)
             return;
         this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
@@ -151,12 +154,12 @@ export class DocSynchronizer extends Synchronizer {
     hasPeer(peerId) {
         return this.#peers.includes(peerId);
     }
-    beginSync(peerIds) {
+    async beginSync(peerIds) {
         const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
         // At this point if we don't have anything in our storage, we need to use an empty doc to sync
         // with; but we don't want to surface that state to the front end
-        const docPromise = this.#handle
-            .doc([READY, REQUESTING, UNAVAILABLE])
+        const docPromise = this.#handle // TODO THIS IS ALSO WEIRD
+            .legacyAsyncDoc([READY, REQUESTING, UNAVAILABLE])
             .then(doc => {
             // we register out peers first, then say that sync has started
             this.#syncStarted = true;
@@ -169,7 +172,12 @@ export class DocSynchronizer extends Synchronizer {
             // the sync message from
             return doc ?? A.init();
         });
-        this.#log(`beginSync: ${peerIds.join(", ")}`);
+        const peersWithDocument = this.#peers.some(peerId => {
+            return this.#peerDocumentStatuses[peerId] == "has";
+        });
+        if (peersWithDocument) {
+            await this.#handle.whenReady();
+        }
         peerIds.forEach(peerId => {
             this.#withSyncState(peerId, syncState => {
                 // HACK: if we have a sync state already, we round-trip it through the encoding system to make

package/fuzz/fuzz.ts

@@ -107,9 +107,9 @@ for (let i = 0; i < 100000; i++) {
   })
 
   await pause(0)
-  const a = await aliceRepo.find(doc.url).doc()
-  const b = await bobRepo.find(doc.url).doc()
-  const c = await charlieRepo.find(doc.url).doc()
+  const a = (await aliceRepo.find(doc.url)).doc()
+  const b = (await bobRepo.find(doc.url)).doc()
+  const c = (await charlieRepo.find(doc.url)).doc()
   assert.deepStrictEqual(a, b, "A and B should be equal")
   assert.deepStrictEqual(b, c, "B and C should be equal")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.22",
   "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>",
@@ -60,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d53bc37be0fd923ff40f3cf7e2bd06a0496ddb73"
+  "gitHead": "b30af9827bed4615ba3c5e9ee93ca483915e4016"
 }

package/src/DocHandle.ts

@@ -83,12 +83,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
           this.emit("delete", { handle: this })
           return { doc: A.init() }
         }),
+        onUnavailable: assign(() => {
+          return { doc: A.init() }
+        }),
         onUnload: assign(() => {
           return { doc: A.init() }
         }),
-        onUnavailable: () => {
-          this.emit("unavailable", { handle: this })
-        },
       },
     }).createMachine({
       /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAYgFUAFAEQEEAVAUQG0AGAXUVAAcB7WXAC64e+TiAAeiAOwAOAKwA6ACxSAzKqks1ATjlTdAGhABPRAFolAJksKN2y1KtKAbFLla5AX09G0WPISkVAwAMgyMrBxIILz8QiJikggAjCzOijKqLEqqybJyLizaRqYIFpbJtro5Uo7J2o5S3r4YOATECrgQADZgJADCAEoM9MzsYrGCwqLRSeoyCtra8pa5adquySXmDjY5ac7JljLJeepKzSB+bYGdPX0AYgCSAHJUkRN8UwmziM7HCgqyVcUnqcmScmcMm2ZV2yiyzkOx1OalUFx8V1aAQ63R46AgBCgJGGAEUyAwAMp0D7RSbxGagJKHFgKOSWJTJGRSCosCpKaEmRCqbQKU5yXINeTaer6LwY67YogKXH4wkkKgAeX6AH1hjQqABNGncL70xKIJQ5RY5BHOJag6wwpRyEWImQVeT1aWrVSXBXtJUqgn4Ik0ADqNCedG1L3CYY1gwA0saYqbpuaEG4pKLksKpFDgcsCjDhTnxTKpTLdH6sQGFOgAO7oKYhl5gAQNngAJwA1iRY3R40ndSNDSm6enfpm5BkWAVkvy7bpuTCKq7ndZnfVeSwuTX-HWu2AAI4AVzgQhD6q12rILxoADVIyEaAAhMLjtM-RmIE4LVSQi4nLLDIGzOCWwLKA0cgyLBoFWNy+43B0R5nheaqajqepjuMtJfgyEh-FoixqMCoKqOyhzgYKCDOq6UIeuCSxHOoSGKgop74OgABuzbdOgABGvTXlho5GrhJpxJOP4pLulT6KoMhpJY2hzsWNF0QobqMV6LG+pc+A8BAcBiP6gSfFJ36EQgKksksKxrHamwwmY7gLKB85QjBzoAWxdZdL0FnfARST8ooLC7qoTnWBU4pyC5ViVMKBQaHUDQuM4fm3EGhJBWaU7-CysEAUp3LpEpWw0WYRw2LmqzgqciIsCxWUdI2zaXlAbYdt2PZ5dJ1n5jY2iJY1ikOIcMJHCyUWHC62hRZkUVNPKta3Kh56wJ1-VWUyzhFc64JWJCtQNBBzhQW4cHwbsrVKpxPF8YJgV4ZZIWIKkiKiiNSkqZYWjzCWaQ5hFh0AcCuR3QoR74qUknBRmzholpv3OkpRQNNRpTzaKTWKbIWR5FDxm9AIkA7e9skUYCWayLILBZGoLkUSKbIyIdpxHPoyTeN4QA */
@@ -281,7 +281,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * This is the recommended way to access a handle's document. Note that this waits for the handle
    * to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
    */
-  async doc(
+  async legacyAsyncDoc(
     /** states to wait for, such as "LOADING". mostly for internal use. */
     awaitStates: HandleState[] = ["ready", "unavailable"]
   ) {
@@ -292,45 +292,42 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       // if we timed out, return undefined
       return undefined
     }
-    // If we have fixed heads, return a view at those heads
-    if (this.#fixedHeads) {
-      const doc = this.#doc
-      if (!doc || this.isUnavailable()) return undefined
-      return A.view(doc, decodeHeads(this.#fixedHeads))
-    }
     // Return the document
     return !this.isUnavailable() ? this.#doc : undefined
   }
 
   /**
-   * Synchronously returns the current state of the Automerge document this handle manages, or
-   * undefined. Consider using `await handle.doc()` instead. Check `isReady()`, or use `whenReady()`
-   * if you want to make sure loading is complete first.
-   *
-   * Not to be confused with the SyncState of the document, which describes the state of the
-   * synchronization process.
+   * Returns the current state of the Automerge document this handle manages.
    *
-   * Note that `undefined` is not a valid Automerge document, so the return from this function is
-   * unambigous.
+   * @returns the current document
+   * @throws on deleted and unavailable documents
    *
-   * @returns the current document, or undefined if the document is not ready.
    */
-  docSync() {
-    if (!this.isReady()) return undefined
+  doc() {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
     if (this.#fixedHeads) {
-      const doc = this.#doc
-      return doc ? A.view(doc, decodeHeads(this.#fixedHeads)) : undefined
+      return A.view(this.#doc, decodeHeads(this.#fixedHeads))
     }
     return this.#doc
   }
 
+  /**
+   *
+   * @deprecated */
+  docSync() {
+    console.warn(
+      "docSync is deprecated. Use doc() instead. This function will be removed as part of the 2.0 release."
+    )
+    return this.doc()
+  }
+
   /**
    * Returns the current "heads" of the document, akin to a git commit.
    * This precisely defines the state of a document.
    * @returns the current document's heads, or undefined if the document is not ready
    */
-  heads(): UrlHeads | undefined {
-    if (!this.isReady()) return undefined
+  heads(): UrlHeads {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
     if (this.#fixedHeads) {
       return this.#fixedHeads
     }
@@ -365,8 +362,8 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Creates a new DocHandle with a fixed "view" at the given point in time represented
-   * by the `heads` passed in. The return value is the same type as docSync() and will return
+   * Creates a fixed "view" of an automerge document at the given point in time represented
+   * by the `heads` passed in. The return value is the same type as doc() and will return
    * undefined if the object hasn't finished loading.
    *
    * @remarks
@@ -426,7 +423,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       if (!otherHeads) throw new Error("Other document's heads not available")
 
       // Create a temporary merged doc to verify shared history and compute diff
-      const mergedDoc = A.merge(A.clone(doc), first.docSync()!)
+      const mergedDoc = A.merge(A.clone(doc), first.doc()!)
       // Use the merged doc to compute the diff
       return A.diff(
         mergedDoc,
@@ -591,10 +588,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
         `DocHandle#${this.documentId} is in view-only mode at specific heads. Use clone() to create a new document from this state.`
       )
     }
-    const mergingDoc = otherHandle.docSync()
-    if (!mergingDoc) {
-      throw new Error("The document to be merged in is falsy, aborting.")
-    }
+    const mergingDoc = otherHandle.doc()
 
     this.update(doc => {
       return A.merge(doc, mergingDoc)
@@ -680,7 +674,6 @@ export interface DocHandleEvents<T> {
   "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
-  unavailable: (payload: DocHandleUnavailablePayload<T>) => void
   "ephemeral-message": (payload: DocHandleEphemeralMessagePayload<T>) => void
   "ephemeral-message-outbound": (
     payload: DocHandleOutboundEphemeralMessagePayload<T>

package/src/FindProgress.ts

@@ -0,0 +1,48 @@
+import { DocHandle } from "./DocHandle.js"
+
+export type FindProgressState =
+  | "loading"
+  | "ready"
+  | "failed"
+  | "aborted"
+  | "unavailable"
+
+interface FindProgressBase<T> {
+  state: FindProgressState
+  handle: DocHandle<T>
+}
+
+interface FindProgressLoading<T> extends FindProgressBase<T> {
+  state: "loading"
+  progress: number
+}
+
+interface FindProgressReady<T> extends FindProgressBase<T> {
+  state: "ready"
+}
+
+interface FindProgressFailed<T> extends FindProgressBase<T> {
+  state: "failed"
+  error: Error
+}
+
+interface FindProgressUnavailable<T> extends FindProgressBase<T> {
+  state: "unavailable"
+}
+
+interface FindProgressAborted<T> extends FindProgressBase<T> {
+  state: "aborted"
+}
+
+export type FindProgress<T> =
+  | FindProgressLoading<T>
+  | FindProgressReady<T>
+  | FindProgressFailed<T>
+  | FindProgressUnavailable<T>
+  | FindProgressAborted<T>
+
+export type FindProgressWithMethods<T> = FindProgress<T> & {
+  next: () => Promise<FindProgressWithMethods<T>>
+  // TODO: i don't like this allowableStates
+  untilReady: (allowableStates: string[]) => Promise<DocHandle<T>>
+}