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

package/README.md

@@ -40,9 +40,9 @@ A `Repo` exposes these methods:
 
 - `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)`  
+- `find<T>(docId: DocumentId): Promise<DocHandle<T>>`  
   Looks up a given document either on the local machine or (if necessary) over any configured
-  networks.
+  networks. Returns a promise that resolves when the document is loaded or throws if load fails.
 - `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)`  
@@ -57,10 +57,9 @@ A `Repo` exposes these methods:
 A `DocHandle` is a wrapper around an `Automerge.Doc`. Its primary function is to dispatch changes to
 the document.
 
-- `handle.doc()` or `handle.docSync()`
-  Returns a `Promise<Doc<T>>` that will contain the current value of the document.
-  it waits until the document has finished loading and/or synchronizing over the network before
-  returning a value.
+- `handle.doc()`
+  Returns a `Doc<T>` that will contain the current value of the document.
+  Throws an error if the document is deleted.
 - `handle.change((doc: T) => void)`  
   Calls the provided callback with an instrumented mutable object
   representing the document. Any changes made to the document will be recorded and distributed to

package/dist/DocHandle.d.ts

@@ -70,29 +70,27 @@ export declare 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.
      */
-    doc(
+    legacyAsyncDoc(
     /** states to wait for, such as "LOADING". mostly for internal use. */
     awaitStates?: HandleState[]): Promise<A.Doc<T> | 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.
+     * Returns the current state of the Automerge document this handle manages.
      *
-     * Not to be confused with the SyncState of the document, which describes the state of the
-     * synchronization process.
+     * @returns the current document
+     * @throws on deleted and unavailable documents
      *
-     * Note that `undefined` is not a valid Automerge document, so the return from this function is
-     * unambigous.
-     *
-     * @returns the current document, or undefined if the document is not ready.
      */
-    docSync(): A.Doc<T> | undefined;
+    doc(): A.Doc<T>;
+    /**
+     *
+     * @deprecated */
+    docSync(): A.Doc<T>;
     /**
      * 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;
+    heads(): UrlHeads;
     begin(): void;
     /**
      * Returns an array of all past "heads" for the document in topological order.
@@ -108,8 +106,8 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     history(): UrlHeads[] | undefined;
     /**
-     * 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
@@ -245,7 +243,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>) => void;
     "remote-heads": (payload: DocHandleRemoteHeadsPayload) => void;

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAEnD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAU5C,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAE9C;;;;;;;;;;;;GAYG;AACH,qBAAa,SAAS,CAAC,CAAC,CAAE,SAAQ,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;;IAqBvD,UAAU,EAAE,UAAU;IAF/B,cAAc;gBAEL,UAAU,EAAE,UAAU,EAC7B,OAAO,GAAE,gBAAgB,CAAC,CAAC,CAAM;IAqKnC;OACG;IACH,IAAI,GAAG,IAAI,YAAY,CAKtB;IAED;;;;;OAKG;IACH,OAAO,gBAAgC;IAEvC;;;;;OAKG;IACH,UAAU,gBAAmC;IAE7C;;;;;OAKG;IACH,SAAS,gBAAkC;IAE3C;;;;OAIG;IACH,aAAa,gBAAsC;IAEnD;;OAEG;IACH,OAAO,WAAY,WAAW,EAAE,aAC0B;IAE1D,cAAc;IACd,IAAI,KAAK,yFAER;IAED;;;;;;OAMG;IACG,SAAS,CAAC,WAAW,GAAE,WAAW,EAAc;IAItD;;;;;OAKG;IACG,GAAG;IACP,sEAAsE;IACtE,WAAW,GAAE,WAAW,EAA6B;IAmBvD;;;;;;;;;;;;OAYG;IACH,OAAO;IASP;;;;OAIG;IACH,KAAK,IAAI,QAAQ,GAAG,SAAS;IAQ7B,KAAK;IAIL;;;;;;;;;;;OAWG;IACH,OAAO,IAAI,QAAQ,EAAE,GAAG,SAAS;IAWjC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC;IAiBnC;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE;IAkClE;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,aAAa,GAAG,SAAS;IAetD;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAI5C;;;;OAIG;IACH,WAAW;IAIX;;;OAGG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ;IAKpD,0CAA0C;IAC1C,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS;IAI1D;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM;IAkBhE;;;;OAIG;IACH,QAAQ,CACN,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM,GAC/B,QAAQ,EAAE,GAAG,SAAS;IA6BzB;;;;;;;OAOG;IACH,KAAK;IACH,wDAAwD;IACxD,WAAW,EAAE,SAAS,CAAC,CAAC,CAAC;IAoB3B;;;OAGG;IACH,WAAW;IAIX;;SAEK;IACL,OAAO;IAIP,8DAA8D;IAC9D,MAAM;IAIN,sDAAsD;IACtD,MAAM;IAIN,uDAAuD;IACvD,MAAM;IAIN;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO;IAO1B,OAAO,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;CAGlD;AAID,cAAc;AACd,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAE1B;IACE,gGAAgG;IAChG,KAAK,EAAE,IAAI,CAAA;IAEX,yCAAyC;IACzC,YAAY,CAAC,EAAE,CAAC,CAAA;CACjB,GAED;IACE,KAAK,CAAC,EAAE,KAAK,CAAA;IAGb,KAAK,CAAC,EAAE,QAAQ,CAAA;IAEhB,+HAA+H;IAC/H,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAIL,2EAA2E;AAC3E,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,eAAe,EAAE,CAAC,OAAO,EAAE,6BAA6B,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpE,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpD,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpD,WAAW,EAAE,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC9D,mBAAmB,EAAE,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAC3E,4BAA4B,EAAE,CAC5B,OAAO,EAAE,wCAAwC,CAAC,CAAC,CAAC,KACjD,IAAI,CAAA;IACT,cAAc,EAAE,CAAC,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAA;CAC/D;AAED,sDAAsD;AACtD,MAAM,WAAW,6BAA6B,CAAC,CAAC;IAC9C,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;CACd;AAED,6CAA6C;AAC7C,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,8BAA8B;IAC9B,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,iDAAiD;IACjD,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACb,wDAAwD;IACxD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAA;IAClB,mCAAmC;IACnC,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED,4CAA4C;AAC5C,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,6DAA6D;AAC7D,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,gCAAgC,CAAC,CAAC;IACjD,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,kEAAkE;AAClE,MAAM,WAAW,wCAAwC,CAAC,CAAC;IACzD,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,8DAA8D;AAC9D,MAAM,WAAW,2BAA2B;IAC1C,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,QAAQ,CAAA;CAChB;AAMD;;GAEG;AACH,eAAO,MAAM,WAAW;IACtB,kEAAkE;;IAElE,mDAAmD;;IAEnD,6EAA6E;;IAE7E,gCAAgC;;IAEhC,2EAA2E;;IAE3E,kDAAkD;;IAElD,4EAA4E;;CAEpE,CAAA;AACV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAExE,eAAO,MACL,IAAI,UACJ,OAAO,aACP,UAAU,gBACV,KAAK,WACL,QAAQ,cACR,OAAO,aACP,WAAW,eACE,CAAA"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -64,12 +64,12 @@ export class DocHandle extends EventEmitter {
                     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 */
@@ -234,7 +234,7 @@ export class DocHandle extends EventEmitter {
      * 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 = ["ready", "unavailable"]) {
         try {
@@ -245,38 +245,31 @@ export class DocHandle extends EventEmitter {
             // 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() {
+    doc() {
         if (!this.isReady())
-            return undefined;
+            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.
@@ -284,7 +277,7 @@ export class DocHandle extends EventEmitter {
      */
     heads() {
         if (!this.isReady())
-            return undefined;
+            throw new Error("DocHandle is not ready");
         if (this.#fixedHeads) {
             return this.#fixedHeads;
         }
@@ -313,8 +306,8 @@ export class DocHandle extends EventEmitter {
         return A.topoHistoryTraversal(this.#doc).map(h => encodeHeads([h]));
     }
     /**
-     * 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
@@ -367,7 +360,7 @@ export class DocHandle extends EventEmitter {
             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, decodeHeads(this.heads()), decodeHeads(otherHeads));
         }
@@ -499,10 +492,7 @@ export class DocHandle extends EventEmitter {
         if (this.#fixedHeads) {
             throw new Error(`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);
         });

package/dist/FindProgress.d.ts

@@ -0,0 +1,30 @@
+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>>;
+    untilReady: (allowableStates: string[]) => Promise<DocHandle<T>>;
+};
+export {};
+//# sourceMappingURL=FindProgress.d.ts.map

package/dist/FindProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FindProgress.d.ts","sourceRoot":"","sources":["../src/FindProgress.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAE1C,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,OAAO,GACP,QAAQ,GACR,SAAS,GACT,aAAa,CAAA;AAEjB,UAAU,gBAAgB,CAAC,CAAC;IAC1B,KAAK,EAAE,iBAAiB,CAAA;IACxB,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,UAAU,mBAAmB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IAC1D,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,UAAU,iBAAiB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IACxD,KAAK,EAAE,OAAO,CAAA;CACf;AAED,UAAU,kBAAkB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IACzD,KAAK,EAAE,QAAQ,CAAA;IACf,KAAK,EAAE,KAAK,CAAA;CACb;AAED,UAAU,uBAAuB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IAC9D,KAAK,EAAE,aAAa,CAAA;CACrB;AAED,UAAU,mBAAmB,CAAC,CAAC,CAAE,SAAQ,gBAAgB,CAAC,CAAC,CAAC;IAC1D,KAAK,EAAE,SAAS,CAAA;CACjB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IACtB,mBAAmB,CAAC,CAAC,CAAC,GACtB,iBAAiB,CAAC,CAAC,CAAC,GACpB,kBAAkB,CAAC,CAAC,CAAC,GACrB,uBAAuB,CAAC,CAAC,CAAC,GAC1B,mBAAmB,CAAC,CAAC,CAAC,CAAA;AAE1B,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG;IACzD,IAAI,EAAE,MAAM,OAAO,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,CAAA;IAE/C,UAAU,EAAE,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA;CACjE,CAAA"}

package/dist/FindProgress.js

@@ -0,0 +1 @@
+export {};

package/dist/Repo.d.ts

@@ -8,6 +8,8 @@ import { StorageId } from "./storage/types.js";
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
 import { DocSyncMetrics } from "./synchronizer/Synchronizer.js";
 import type { AnyDocumentId, AutomergeUrl, DocumentId, PeerId } from "./types.js";
+import { AbortOptions } from "./helpers/abortable.js";
+import { FindProgress, FindProgressWithMethods } from "./FindProgress.js";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -57,17 +59,17 @@ export declare class Repo extends EventEmitter<RepoEvents> {
      * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
      * be notified of the newly created DocHandle.
      *
-     * @throws if the cloned handle is not yet ready or if
-     * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
      */
     clone<T>(clonedHandle: DocHandle<T>): DocHandle<T>;
+    findWithProgress<T>(id: AnyDocumentId, options?: AbortOptions): FindProgressWithMethods<T> | FindProgress<T>;
+    find<T>(id: AnyDocumentId, options?: RepoFindOptions & AbortOptions): Promise<DocHandle<T>>;
     /**
      * Retrieves a document by id. It gets data from the local system, but also emits a `document`
      * event to advertise interest in the document.
      */
-    find<T>(
+    findClassic<T>(
     /** The url or documentId of the handle to retrieve */
-    id: AnyDocumentId): DocHandle<T>;
+    id: AnyDocumentId, options?: RepoFindOptions & AbortOptions): Promise<DocHandle<T>>;
     delete(
     /** The url or documentId of the handle to delete */
     id: AnyDocumentId): void;
@@ -151,6 +153,9 @@ export interface RepoEvents {
     "unavailable-document": (arg: DeleteDocumentPayload) => void;
     "doc-metrics": (arg: DocMetrics) => void;
 }
+export interface RepoFindOptions {
+    allowableStates?: string[];
+}
 export interface DocumentPayload {
     handle: DocHandle<any>;
 }

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

@@ -9,6 +9,7 @@ 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 { abortable } from "./helpers/abortable.js";
 function randomPeerId() {
     return ("peer-" + Math.random().toString(36).slice(4));
 }
@@ -170,16 +171,8 @@ export class Repo extends EventEmitter {
             };
             handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate));
         }
-        handle.on("unavailable", () => {
-            this.#log("document unavailable", { documentId: handle.documentId });
-            this.emit("unavailable-document", {
-                documentId: handle.documentId,
-            });
-        });
         // Register the document with the synchronizer. This advertises our interest in the document.
-        this.synchronizer.addDocument(handle.documentId);
-        // Preserve the old event in case anyone was using it.
-        this.emit("document", { handle });
+        this.synchronizer.addDocument(handle);
     }
     #receiveMessage(message) {
         switch (message.type) {
@@ -280,18 +273,13 @@ export class Repo extends EventEmitter {
      * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
      * be notified of the newly created DocHandle.
      *
-     * @throws if the cloned handle is not yet ready or if
-     * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
      */
     clone(clonedHandle) {
         if (!clonedHandle.isReady()) {
             throw new Error(`Cloned handle is not yet in ready state.
         (Try await handle.whenReady() first.)`);
         }
-        const sourceDoc = clonedHandle.docSync();
-        if (!sourceDoc) {
-            throw new Error("Cloned handle doesn't have a document.");
-        }
+        const sourceDoc = clonedHandle.doc();
         const handle = this.create();
         handle.update(() => {
             // we replace the document with the new cloned one
@@ -299,58 +287,171 @@ export class Repo extends EventEmitter {
         });
         return handle;
     }
-    /**
-     * Retrieves a document by id. It gets data from the local system, but also emits a `document`
-     * event to advertise interest in the document.
-     */
-    find(
-    /** The url or documentId of the handle to retrieve */
-    id) {
+    findWithProgress(id, options = {}) {
+        const { signal } = options;
+        const abortPromise = abortable(signal);
         const { documentId, heads } = isValidAutomergeUrl(id)
             ? parseAutomergeUrl(id)
             : { documentId: interpretAsDocumentId(id), heads: undefined };
-        const cachedHandle = this.#handleCache[documentId];
-        if (cachedHandle) {
-            if (cachedHandle.isUnavailable()) {
-                // this ensures that the event fires after the handle has been returned
-                setTimeout(() => {
-                    cachedHandle.emit("unavailable", {
-                        handle: cachedHandle,
-                    });
-                });
+        // Check cache first - return plain FindStep for terminal states
+        if (this.#handleCache[documentId]) {
+            const handle = this.#handleCache[documentId];
+            if (handle.state === UNAVAILABLE) {
+                const result = {
+                    state: "unavailable",
+                    error: new Error(`Document ${id} is unavailable`),
+                    handle,
+                };
+                return result;
+            }
+            if (handle.state === DELETED) {
+                return {
+                    state: "failed",
+                    error: new Error(`Document ${id} was deleted`),
+                    handle,
+                };
+            }
+            if (handle.state === READY) {
+                // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+                return {
+                    state: "ready",
+                    // TODO: this handle needs to be cached (or at least avoid running clone)
+                    handle: heads ? handle.view(heads) : handle,
+                };
             }
-            // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
-            return heads ? cachedHandle.view(heads) : cachedHandle;
         }
-        // If we don't already have the handle, make an empty one and try loading it
-        const handle = this.#getHandle({
-            documentId,
-        });
-        // Loading & network is going to be asynchronous no matter what,
-        // but we want to return the handle immediately.
-        const attemptLoad = this.storageSubsystem
-            ? this.storageSubsystem.loadDoc(handle.documentId)
-            : Promise.resolve(null);
-        attemptLoad
-            .then(async (loadedDoc) => {
-            if (loadedDoc) {
-                // uhhhh, sorry if you're reading this because we were lying to the type system
-                handle.update(() => loadedDoc);
-                handle.doneLoading();
+        // the generator takes over `this`, so we need an alias to the repo this
+        // eslint-disable-next-line @typescript-eslint/no-this-alias
+        const that = this;
+        async function* progressGenerator() {
+            try {
+                const handle = that.#getHandle({ documentId });
+                yield { state: "loading", progress: 25, handle };
+                const loadingPromise = await (that.storageSubsystem
+                    ? that.storageSubsystem.loadDoc(handle.documentId)
+                    : Promise.resolve(null));
+                const loadedDoc = await Promise.race([loadingPromise, abortPromise]);
+                if (loadedDoc) {
+                    handle.update(() => loadedDoc);
+                    handle.doneLoading();
+                    yield { state: "loading", progress: 50, handle };
+                }
+                else {
+                    await Promise.race([that.networkSubsystem.whenReady(), abortPromise]);
+                    handle.request();
+                    yield { state: "loading", progress: 75, handle };
+                }
+                that.#registerHandleWithSubsystems(handle);
+                await Promise.race([
+                    handle.whenReady([READY, UNAVAILABLE]),
+                    abortPromise,
+                ]);
+                if (handle.state === UNAVAILABLE) {
+                    yield { state: "unavailable", handle };
+                }
+                if (handle.state === DELETED) {
+                    throw new Error(`Document ${id} was deleted`);
+                }
+                yield { state: "ready", handle };
             }
-            else {
-                // we want to wait for the network subsystem to be ready before
-                // we request the document. this prevents entering unavailable during initialization.
-                await this.networkSubsystem.whenReady();
-                handle.request();
+            catch (error) {
+                yield {
+                    state: "failed",
+                    error: error instanceof Error ? error : new Error(String(error)),
+                    handle,
+                };
             }
-            this.#registerHandleWithSubsystems(handle);
-        })
-            .catch(err => {
-            this.#log("error waiting for network", { err });
-        });
-        // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
-        return heads ? handle.view(heads) : handle;
+        }
+        const iterator = progressGenerator();
+        const next = async () => {
+            const result = await iterator.next();
+            return { ...result.value, next };
+        };
+        const untilReady = async (allowableStates) => {
+            for await (const state of iterator) {
+                if (allowableStates.includes(state.handle.state)) {
+                    return state.handle;
+                }
+                if (state.state === "unavailable") {
+                    throw new Error(`Document ${id} is unavailable`);
+                }
+                if (state.state === "ready")
+                    return state.handle;
+                if (state.state === "failed")
+                    throw state.error;
+            }
+            throw new Error("Iterator completed without reaching ready state");
+        };
+        const handle = this.#getHandle({ documentId });
+        const initial = { state: "loading", progress: 0, handle };
+        return { ...initial, next, untilReady };
+    }
+    async find(id, options = {}) {
+        const { allowableStates = ["ready"], signal } = options;
+        const progress = this.findWithProgress(id, { signal });
+        /*if (allowableStates.includes(progress.state)) {
+          console.log("returning early")
+          return progress.handle
+        }*/
+        if ("untilReady" in progress) {
+            this.#registerHandleWithSubsystems(progress.handle);
+            return progress.untilReady(allowableStates);
+        }
+        else {
+            return progress.handle;
+        }
+    }
+    /**
+     * Loads a document without waiting for ready state
+     */
+    async #loadDocument(documentId) {
+        // If we have the handle cached, return it
+        if (this.#handleCache[documentId]) {
+            return this.#handleCache[documentId];
+        }
+        // If we don't already have the handle, make an empty one and try loading it
+        const handle = this.#getHandle({ documentId });
+        const loadedDoc = await (this.storageSubsystem
+            ? this.storageSubsystem.loadDoc(handle.documentId)
+            : Promise.resolve(null));
+        if (loadedDoc) {
+            // We need to cast this to <T> because loadDoc operates in <unknowns>.
+            // This is really where we ought to be validating the input matches <T>.
+            handle.update(() => loadedDoc);
+            handle.doneLoading();
+        }
+        else {
+            // Because the network subsystem might still be booting up, we wait
+            // here so that we don't immediately give up loading because we're still
+            // making our initial connection to a sync server.
+            await this.networkSubsystem.whenReady();
+            handle.request();
+        }
+        this.#registerHandleWithSubsystems(handle);
+        return handle;
+    }
+    /**
+     * Retrieves a document by id. It gets data from the local system, but also emits a `document`
+     * event to advertise interest in the document.
+     */
+    async findClassic(
+    /** The url or documentId of the handle to retrieve */
+    id, options = {}) {
+        const documentId = interpretAsDocumentId(id);
+        const { allowableStates, signal } = options;
+        return Promise.race([
+            (async () => {
+                const handle = await this.#loadDocument(documentId);
+                if (!allowableStates) {
+                    await handle.whenReady([READY, UNAVAILABLE]);
+                    if (handle.state === UNAVAILABLE && !signal?.aborted) {
+                        throw new Error(`Document ${id} is unavailable`);
+                    }
+                }
+                return handle;
+            })(),
+            abortable(signal),
+        ]);
     }
     delete(
     /** The url or documentId of the handle to delete */
@@ -371,9 +472,7 @@ export class Repo extends EventEmitter {
     async export(id) {
         const documentId = interpretAsDocumentId(id);
         const handle = this.#getHandle({ documentId });
-        const doc = await handle.doc();
-        if (!doc)
-            return undefined;
+        const doc = handle.doc();
         return Automerge.save(doc);
     }
     /**
@@ -419,11 +518,7 @@ export class Repo extends EventEmitter {
             ? documents.map(id => this.#handleCache[id])
             : Object.values(this.#handleCache);
         await Promise.all(handles.map(async (handle) => {
-            const doc = handle.docSync();
-            if (!doc) {
-                return;
-            }
-            return this.storageSubsystem.saveDoc(handle.documentId, doc);
+            return this.storageSubsystem.saveDoc(handle.documentId, handle.doc());
         }));
     }
     /**
@@ -438,7 +533,9 @@ export class Repo extends EventEmitter {
             return;
         }
         const handle = this.#getHandle({ documentId });
-        const doc = await handle.doc([READY, UNLOADED, DELETED, UNAVAILABLE]);
+        await handle.whenReady([READY, UNLOADED, DELETED, UNAVAILABLE]);
+        const doc = handle.doc();
+        // because this is an internal-ish function, we'll be extra careful about undefined docs here
         if (doc) {
             if (handle.isReady()) {
                 handle.unload();