@automerge/automerge-repo 2.0.0-collectionsync-alpha.1 → 2.0.1

package/dist/DocHandle.js

@@ -1,8 +1,8 @@
-import * as A from "@automerge/automerge/slim/next";
+import { next as A } from "@automerge/automerge/slim";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
 import { assertEvent, assign, createActor, setup, waitFor } from "xstate";
-import { stringifyAutomergeUrl } from "./AutomergeUrl.js";
+import { decodeHeads, encodeHeads, stringifyAutomergeUrl, } from "./AutomergeUrl.js";
 import { encode } from "./helpers/cbor.js";
 import { headsAreSame } from "./helpers/headsAreSame.js";
 import { withTimeout } from "./helpers/withTimeout.js";
@@ -24,6 +24,8 @@ export class DocHandle extends EventEmitter {
     #log;
     /** The XState actor running our state machine.  */
     #machine;
+    /** If set, this handle will only show the document at these heads */
+    #fixedHeads;
     /** The last known state of our document. */
     #prevDocState = A.init();
     /** How long to wait before giving up on a document. (Note that a document will be marked
@@ -31,6 +33,8 @@ export class DocHandle extends EventEmitter {
     #timeoutDelay = 60_000;
     /** A dictionary mapping each peer to the last heads we know they have. */
     #remoteHeads = {};
+    /** Cache for view handles, keyed by the stringified heads */
+    #viewCache = new Map();
     /** @hidden */
     constructor(documentId, options = {}) {
         super();
@@ -38,6 +42,9 @@ export class DocHandle extends EventEmitter {
         if ("timeoutDelay" in options && options.timeoutDelay) {
             this.#timeoutDelay = options.timeoutDelay;
         }
+        if ("heads" in options) {
+            this.#fixedHeads = options.heads;
+        }
         const doc = A.init();
         this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`);
         const delay = this.#timeoutDelay;
@@ -59,12 +66,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 */
@@ -150,7 +157,7 @@ export class DocHandle extends EventEmitter {
     #checkForChanges(before, after) {
         const beforeHeads = A.getHeads(before);
         const afterHeads = A.getHeads(after);
-        const docChanged = !headsAreSame(afterHeads, beforeHeads);
+        const docChanged = !headsAreSame(encodeHeads(afterHeads), encodeHeads(beforeHeads));
         if (docChanged) {
             this.emit("heads-changed", { handle: this, doc: after });
             const patches = A.diff(after, beforeHeads, afterHeads);
@@ -173,7 +180,10 @@ export class DocHandle extends EventEmitter {
     /** Our documentId in Automerge URL form.
      */
     get url() {
-        return stringifyAutomergeUrl({ documentId: this.documentId });
+        return stringifyAutomergeUrl({
+            documentId: this.documentId,
+            heads: this.#fixedHeads,
+        });
     }
     /**
      * @returns true if the document is ready for accessing or changes.
@@ -221,43 +231,26 @@ export class DocHandle extends EventEmitter {
         await withTimeout(this.#statePromise(awaitStates), this.#timeoutDelay);
     }
     /**
-     * @returns the current state of this handle's Automerge document.
+     * Returns the current state of the Automerge document this handle manages.
+     *
+     * @returns the current document
+     * @throws on deleted and unavailable documents
      *
-     * 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(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates = ["ready", "unavailable"]) {
-        try {
-            // wait for the document to enter one of the desired states
-            await this.#statePromise(awaitStates);
-        }
-        catch (error) {
-            // if we timed out, return undefined
-            return undefined;
+    doc() {
+        if (!this.isReady())
+            throw new Error("DocHandle is not ready");
+        if (this.#fixedHeads) {
+            return A.view(this.#doc, decodeHeads(this.#fixedHeads));
         }
-        // Return the document
-        return !this.isUnavailable() ? this.#doc : undefined;
+        return this.#doc;
     }
     /**
-     * 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.
-     *
-     * 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.
-     */
+     * @deprecated */
     docSync() {
-        if (!this.isReady())
-            return undefined;
-        else
-            return this.#doc;
+        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.
@@ -265,18 +258,18 @@ export class DocHandle extends EventEmitter {
      * @returns the current document's heads, or undefined if the document is not ready
      */
     heads() {
-        if (!this.isReady()) {
-            return undefined;
+        if (!this.isReady())
+            throw new Error("DocHandle is not ready");
+        if (this.#fixedHeads) {
+            return this.#fixedHeads;
         }
-        return A.getHeads(this.#doc);
+        return encodeHeads(A.getHeads(this.#doc));
     }
     begin() {
         this.#machine.send({ type: BEGIN });
     }
     /**
-     * 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 docSync() and will return
-     * undefined if the object hasn't finished loading.
+     * Returns an array of all past "heads" for the document in topological order.
      *
      * @remarks
      * A point-in-time in an automerge document is an *array* of heads since there may be
@@ -285,18 +278,18 @@ export class DocHandle extends EventEmitter {
      * history views would be quite large under concurrency (every thing in each branch against each other).
      * There might be a clever way to think about this, but we haven't found it yet, so for now at least
      * we present a single traversable view which excludes concurrency.
-     * @returns The individual heads for every change in the document.
+     * @returns UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].
      */
     history() {
         if (!this.isReady()) {
             return undefined;
         }
         // This just returns all the heads as individual strings.
-        return A.topoHistoryTraversal(this.#doc).map(h => [h]);
+        return A.topoHistoryTraversal(this.#doc).map(h => encodeHeads([h]));
     }
     /**
      * 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 docSync() and will return
+     * 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
@@ -304,32 +297,68 @@ export class DocHandle extends EventEmitter {
      * of Automerge doesn't check types at runtime, so if you go back to an old set of heads
      * that doesn't match the heads here, Typescript will not save you.
      *
-     * @returns An Automerge.Doc<T> at the point in time.
+     * @argument heads - The heads to view the document at. See history().
+     * @returns DocHandle<T> at the time of `heads`
      */
     view(heads) {
         if (!this.isReady()) {
-            return undefined;
+            throw new Error(`DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`);
+        }
+        // Create a cache key from the heads
+        const cacheKey = JSON.stringify(heads);
+        // Check if we have a cached handle for these heads
+        const cachedHandle = this.#viewCache.get(cacheKey);
+        if (cachedHandle) {
+            return cachedHandle;
         }
-        return A.view(this.#doc, heads);
+        // Create a new handle with the same documentId but fixed heads
+        const handle = new DocHandle(this.documentId, {
+            heads,
+            timeoutDelay: this.#timeoutDelay,
+        });
+        handle.update(() => A.clone(this.#doc));
+        handle.doneLoading();
+        // Store in cache
+        this.#viewCache.set(cacheKey, handle);
+        return handle;
     }
     /**
      * Returns a set of Patch operations that will move a materialized document from one state to another
      * if applied.
      *
      * @remarks
-     * We allow specifying both a from/to heads or just a single comparison point, in which case
-     * the base will be the current document heads.
+     * We allow specifying either:
+     * - Two sets of heads to compare directly
+     * - A single set of heads to compare against our current heads
+     * - Another DocHandle to compare against (which must share history with this document)
      *
-     * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
+     * @throws Error if the documents don't share history or if either document is not ready
+     * @returns Automerge patches that go from one document state to the other
      */
     diff(first, second) {
         if (!this.isReady()) {
-            return undefined;
+            throw new Error(`DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling diff().`);
+        }
+        const doc = this.#doc;
+        if (!doc)
+            throw new Error("Document not available");
+        // If first argument is a DocHandle
+        if (first instanceof DocHandle) {
+            if (!first.isReady()) {
+                throw new Error("Cannot diff against a handle that isn't ready");
+            }
+            const otherHeads = first.heads();
+            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.doc());
+            // Use the merged doc to compute the diff
+            return A.diff(mergedDoc, decodeHeads(this.heads()), decodeHeads(otherHeads));
         }
-        // We allow only one set of heads to be specified, in which case we use the doc's heads
-        const from = second ? first : this.heads() || []; // because we guard above this should always have useful data
+        // Otherwise treat as heads
+        const from = second ? first : (this.heads() || []);
         const to = second ? second : first;
-        return A.diff(this.#doc, from, to);
+        return A.diff(doc, decodeHeads(from), decodeHeads(to));
     }
     /**
      * `metadata(head?)` allows you to look at the metadata for a change
@@ -350,7 +379,8 @@ export class DocHandle extends EventEmitter {
             change = this.heads()[0];
         }
         // we return undefined instead of null by convention in this API
-        return A.inspectChange(this.#doc, change) || undefined;
+        return (A.inspectChange(this.#doc, decodeHeads([change])[0]) ||
+            undefined);
     }
     /**
      * `update` is called any time we have a new document state; could be
@@ -370,7 +400,7 @@ export class DocHandle extends EventEmitter {
         this.#machine.send({ type: DOC_READY });
     }
     /**
-     * Called by the repo either when a doc handle changes or we receive new remote heads.
+     * Called by the repo when a doc handle changes or we receive new remote heads.
      * @hidden
      */
     setRemoteHeads(storageId, heads) {
@@ -400,6 +430,9 @@ export class DocHandle extends EventEmitter {
         if (!this.isReady()) {
             throw new Error(`DocHandle#${this.documentId} is in ${this.state} and not ready. Check \`handle.isReady()\` before accessing the document.`);
         }
+        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.`);
+        }
         this.#machine.send({
             type: UPDATE,
             payload: { callback: doc => A.change(doc, options, callback) },
@@ -414,13 +447,18 @@ export class DocHandle extends EventEmitter {
         if (!this.isReady()) {
             throw new Error(`DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before accessing the document.`);
         }
+        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.`);
+        }
         let resultHeads = undefined;
         this.#machine.send({
             type: UPDATE,
             payload: {
                 callback: doc => {
-                    const result = A.changeAt(doc, heads, options, callback);
-                    resultHeads = result.newHeads || undefined;
+                    const result = A.changeAt(doc, decodeHeads(heads), options, callback);
+                    resultHeads = result.newHeads
+                        ? encodeHeads(result.newHeads)
+                        : undefined;
                     return result.newDoc;
                 },
             },
@@ -442,22 +480,23 @@ export class DocHandle extends EventEmitter {
         if (!this.isReady() || !otherHandle.isReady()) {
             throw new Error("Both handles must be ready to merge");
         }
-        const mergingDoc = otherHandle.docSync();
-        if (!mergingDoc) {
-            throw new Error("The document to be merged in is falsy, aborting.");
+        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.doc();
         this.update(doc => {
             return A.merge(doc, mergingDoc);
         });
     }
     /**
-     * Used in testing to mark this document as unavailable.
+     * Updates the internal state machine to mark the document unavailable.
      * @hidden
      */
     unavailable() {
         this.#machine.send({ type: DOC_UNAVAILABLE });
     }
-    /** Called by the repo when the document is not found in storage.
+    /**
+     * Called by the repo either when the document is not found in storage.
      * @hidden
      * */
     request() {
@@ -486,7 +525,7 @@ export class DocHandle extends EventEmitter {
     broadcast(message) {
         this.emit("ephemeral-message-outbound", {
             handle: this,
-            data: encode(message),
+            data: new Uint8Array(encode(message)),
         });
     }
     metrics() {

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/RemoteHeadsSubscriptions.d.ts

@@ -1,19 +1,18 @@
-import { next as A } from "@automerge/automerge/slim";
 import { EventEmitter } from "eventemitter3";
-import { DocumentId, PeerId } from "./types.js";
+import { DocumentId, PeerId, UrlHeads } from "./types.js";
 import { RemoteHeadsChanged, RemoteSubscriptionControlMessage } from "./network/messages.js";
 import { StorageId } from "./index.js";
 export type RemoteHeadsSubscriptionEventPayload = {
     documentId: DocumentId;
     storageId: StorageId;
-    remoteHeads: A.Heads;
+    remoteHeads: UrlHeads;
     timestamp: number;
 };
 export type NotifyRemoteHeadsPayload = {
     targetId: PeerId;
     documentId: DocumentId;
     storageId: StorageId;
-    heads: A.Heads;
+    heads: UrlHeads;
     timestamp: number;
 };
 type RemoteHeadsSubscriptionEvents = {
@@ -33,7 +32,7 @@ export declare class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSu
     /** A peer we are not directly connected to has changed their heads */
     handleRemoteHeads(msg: RemoteHeadsChanged): void;
     /** A peer we are directly connected to has updated their heads */
-    handleImmediateRemoteHeadsChanged(documentId: DocumentId, storageId: StorageId, heads: A.Heads): void;
+    handleImmediateRemoteHeadsChanged(documentId: DocumentId, storageId: StorageId, heads: UrlHeads): void;
     addGenerousPeer(peerId: PeerId): void;
     removePeer(peerId: PeerId): void;
     subscribePeerToDoc(peerId: PeerId, documentId: DocumentId): void;

package/dist/RemoteHeadsSubscriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RemoteHeadsSubscriptions.d.ts","sourceRoot":"","sources":["../src/RemoteHeadsSubscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EACjC,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAItC,MAAM,MAAM,mCAAmC,GAAG;IAChD,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,CAAC,CAAC,KAAK,CAAA;IACpB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAGD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,6BAA6B,GAAG;IACnC,sBAAsB,EAAE,CAAC,OAAO,EAAE,mCAAmC,KAAK,IAAI,CAAA;IAC9E,oBAAoB,EAAE,CAAC,OAAO,EAAE;QAC9B,KAAK,EAAE,MAAM,EAAE,CAAA;QACf,GAAG,CAAC,EAAE,SAAS,EAAE,CAAA;QACjB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;KACrB,KAAK,IAAI,CAAA;IACV,qBAAqB,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAA;CACnE,CAAA;AAED,qBAAa,wBAAyB,SAAQ,YAAY,CAAC,6BAA6B,CAAC;;IAcvF,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE;IAkBvC,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE;IAsB3C,oBAAoB,CAAC,OAAO,EAAE,gCAAgC;IA0E9D,sEAAsE;IACtE,iBAAiB,CAAC,GAAG,EAAE,kBAAkB;IAgDzC,kEAAkE;IAClE,iCAAiC,CAC/B,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,CAAC,CAAC,KAAK;IAgChB,eAAe,CAAC,MAAM,EAAE,MAAM;IAwB9B,UAAU,CAAC,MAAM,EAAE,MAAM;IA2BzB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CAoE1D"}
+{"version":3,"file":"RemoteHeadsSubscriptions.d.ts","sourceRoot":"","sources":["../src/RemoteHeadsSubscriptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AACzD,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EACjC,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAItC,MAAM,MAAM,mCAAmC,GAAG;IAChD,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,WAAW,EAAE,QAAQ,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAGD,MAAM,MAAM,wBAAwB,GAAG;IACrC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;IACpB,KAAK,EAAE,QAAQ,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,KAAK,6BAA6B,GAAG;IACnC,sBAAsB,EAAE,CAAC,OAAO,EAAE,mCAAmC,KAAK,IAAI,CAAA;IAC9E,oBAAoB,EAAE,CAAC,OAAO,EAAE;QAC9B,KAAK,EAAE,MAAM,EAAE,CAAA;QACf,GAAG,CAAC,EAAE,SAAS,EAAE,CAAA;QACjB,MAAM,CAAC,EAAE,SAAS,EAAE,CAAA;KACrB,KAAK,IAAI,CAAA;IACV,qBAAqB,EAAE,CAAC,OAAO,EAAE,wBAAwB,KAAK,IAAI,CAAA;CACnE,CAAA;AAED,qBAAa,wBAAyB,SAAQ,YAAY,CAAC,6BAA6B,CAAC;;IAcvF,kBAAkB,CAAC,OAAO,EAAE,SAAS,EAAE;IAkBvC,sBAAsB,CAAC,OAAO,EAAE,SAAS,EAAE;IAsB3C,oBAAoB,CAAC,OAAO,EAAE,gCAAgC;IA0E9D,sEAAsE;IACtE,iBAAiB,CAAC,GAAG,EAAE,kBAAkB;IAgDzC,kEAAkE;IAClE,iCAAiC,CAC/B,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,QAAQ;IAgCjB,eAAe,CAAC,MAAM,EAAE,MAAM;IAwB9B,UAAU,CAAC,MAAM,EAAE,MAAM;IA2BzB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU;CAuE1D"}

package/dist/RemoteHeadsSubscriptions.js

@@ -270,7 +270,10 @@ export class RemoteHeadsSubscriptions extends EventEmitter {
                 continue;
             }
             else {
-                remote.set(storageId, { timestamp, heads });
+                remote.set(storageId, {
+                    timestamp,
+                    heads: heads,
+                });
                 changedHeads.push({
                     documentId,
                     storageId: storageId,

package/dist/Repo.d.ts

@@ -8,6 +8,18 @@ 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 } from "./FindProgress.js";
+export type FindProgressWithMethods<T> = FindProgress<T> & {
+    untilReady: (allowableStates: string[]) => Promise<DocHandle<T>>;
+    peek: () => FindProgress<T>;
+    subscribe: (callback: (progress: FindProgress<T>) => void) => () => void;
+};
+export type ProgressSignal<T> = {
+    peek: () => FindProgress<T>;
+    subscribe: (callback: (progress: FindProgress<T>) => void) => () => void;
+    untilReady: (allowableStates: string[]) => Promise<DocHandle<T>>;
+};
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -20,7 +32,11 @@ export declare class Repo extends EventEmitter<RepoEvents> {
     #private;
     /** @hidden */
     networkSubsystem: NetworkSubsystem;
-    storageSubsystem: StorageSubsystem;
+    /** @hidden */
+    storageSubsystem?: StorageSubsystem;
+    /** The debounce rate is adjustable on the repo. */
+    /** @hidden */
+    saveDebounceRate: number;
     /** @hidden */
     synchronizer: CollectionSynchronizer;
     /** By default, we share generously with all peers. */
@@ -53,17 +69,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;
@@ -147,6 +163,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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"}