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

package/dist/DocHandle.js

@@ -2,7 +2,7 @@ import * as A from "@automerge/automerge/slim/next";
 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
@@ -38,6 +40,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,9 +64,12 @@ export class DocHandle extends EventEmitter {
                     this.emit("delete", { handle: this });
                     return { doc: A.init() };
                 }),
-                onUnavailable: () => {
-                    this.emit("unavailable", { handle: this });
-                },
+                onUnavailable: assign(() => {
+                    return { doc: A.init() };
+                }),
+                onUnload: assign(() => {
+                    return { doc: A.init() };
+                }),
             },
         }).createMachine({
             /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAYgFUAFAEQEEAVAUQG0AGAXUVAAcB7WXAC64e+TiAAeiAOwAOAKwA6ACxSAzKqks1ATjlTdAGhABPRAFolAJksKN2y1KtKAbFLla5AX09G0WPISkVAwAMgyMrBxIILz8QiJikggAjCzOijKqLEqqybJyLizaRqYIFpbJtro5Uo7J2o5S3r4YOATECrgQADZgJADCAEoM9MzsYrGCwqLRSeoyCtra8pa5adquySXmDjY5ac7JljLJeepKzSB+bYGdPX0AYgCSAHJUkRN8UwmziM7HCgqyVcUnqcmScmcMm2ZV2yiyzkOx1OalUFx8V1aAQ63R46AgBCgJGGAEUyAwAMp0D7RSbxGagJKHFgKOSWJTJGRSCosCpKaEmRCqbQKU5yXINeTaer6LwY67YogKXH4wkkKgAeX6AH1hjQqABNGncL70xKIJQ5RY5BHOJag6wwpRyEWImQVeT1aWrVSXBXtJUqgn4Ik0ADqNCedG1L3CYY1gwA0saYqbpuaEG4pKLksKpFDgcsCjDhTnxTKpTLdH6sQGFOgAO7oKYhl5gAQNngAJwA1iRY3R40ndSNDSm6enfpm5BkWAVkvy7bpuTCKq7ndZnfVeSwuTX-HWu2AAI4AVzgQhD6q12rILxoADVIyEaAAhMLjtM-RmIE4LVSQi4nLLDIGzOCWwLKA0cgyLBoFWNy+43B0R5nheaqajqepjuMtJfgyEh-FoixqMCoKqOyhzgYKCDOq6UIeuCSxHOoSGKgop74OgABuzbdOgABGvTXlho5GrhJpxJOP4pLulT6KoMhpJY2hzsWNF0QobqMV6LG+pc+A8BAcBiP6gSfFJ36EQgKksksKxrHamwwmY7gLKB85QjBzoAWxdZdL0FnfARST8ooLC7qoTnWBU4pyC5ViVMKBQaHUDQuM4fm3EGhJBWaU7-CysEAUp3LpEpWw0WYRw2LmqzgqciIsCxWUdI2zaXlAbYdt2PZ5dJ1n5jY2iJY1ikOIcMJHCyUWHC62hRZkUVNPKta3Kh56wJ1-VWUyzhFc64JWJCtQNBBzhQW4cHwbsrVKpxPF8YJgV4ZZIWIKkiKiiNSkqZYWjzCWaQ5hFh0AcCuR3QoR74qUknBRmzholpv3OkpRQNNRpTzaKTWKbIWR5FDxm9AIkA7e9skUYCWayLILBZGoLkUSKbIyIdpxHPoyTeN4QA */
@@ -71,6 +79,7 @@ export class DocHandle extends EventEmitter {
             context: { documentId, doc },
             on: {
                 UPDATE: { actions: "onUpdate" },
+                UNLOAD: ".unloaded",
                 DELETE: ".deleted",
             },
             states: {
@@ -98,6 +107,12 @@ export class DocHandle extends EventEmitter {
                     on: { DOC_READY: "ready" },
                 },
                 ready: {},
+                unloaded: {
+                    entry: "onUnload",
+                    on: {
+                        RELOAD: "loading",
+                    },
+                },
                 deleted: { entry: "onDelete", type: "final" },
             },
         });
@@ -113,7 +128,7 @@ export class DocHandle extends EventEmitter {
         });
         // Start the machine, and send a create or find event to get things going
         this.#machine.start();
-        this.#machine.send({ type: BEGIN });
+        this.begin();
     }
     // PRIVATE
     /** Returns the current document, regardless of state */
@@ -140,7 +155,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);
@@ -163,7 +178,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.
@@ -172,6 +190,13 @@ export class DocHandle extends EventEmitter {
      * peers. We do not currently have an equivalent `whenSynced()`.
      */
     isReady = () => this.inState(["ready"]);
+    /**
+     * @returns true if the document has been unloaded.
+     *
+     * Unloaded documents are freed from memory but not removed from local storage. It's not currently
+     * possible at runtime to reload an unloaded document.
+     */
+    isUnloaded = () => this.inState(["unloaded"]);
     /**
      * @returns true if the document has been marked as deleted.
      *
@@ -209,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 {
@@ -224,23 +249,26 @@ export class DocHandle extends EventEmitter {
         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.
+     * 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() {
+    doc() {
         if (!this.isReady())
-            return undefined;
-        else
-            return this.#doc;
+            throw new Error("DocHandle is not ready");
+        if (this.#fixedHeads) {
+            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.
@@ -248,10 +276,120 @@ export class DocHandle extends EventEmitter {
      * @returns the current document's heads, or undefined if the document is not ready
      */
     heads() {
+        if (!this.isReady())
+            throw new Error("DocHandle is not ready");
+        if (this.#fixedHeads) {
+            return this.#fixedHeads;
+        }
+        return encodeHeads(A.getHeads(this.#doc));
+    }
+    begin() {
+        this.#machine.send({ type: BEGIN });
+    }
+    /**
+     * 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
+     * concurrent edits. This API just returns a topologically sorted history of all edits
+     * so every previous entry will be (in some sense) before later ones, but the set of all possible
+     * 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 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 => 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 doc() and will return
+     * undefined if the object hasn't finished loading.
+     *
+     * @remarks
+     * Note that our Typescript types do not consider change over time and the current version
+     * 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.
+     *
+     * @argument heads - The heads to view the document at. See history().
+     * @returns DocHandle<T> at the time of `heads`
+     */
+    view(heads) {
+        if (!this.isReady()) {
+            throw new Error(`DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`);
+        }
+        // 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();
+        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 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)
+     *
+     * @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()) {
+            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));
+        }
+        // Otherwise treat as heads
+        const from = second ? first : (this.heads() || []);
+        const to = second ? second : first;
+        return A.diff(doc, decodeHeads(from), decodeHeads(to));
+    }
+    /**
+     * `metadata(head?)` allows you to look at the metadata for a change
+     * this can be used to build history graphs to find commit messages and edit times.
+     * this interface.
+     *
+     * @remarks
+     * I'm really not convinced this is the right way to surface this information so
+     * I'm leaving this API "hidden".
+     *
+     * @hidden
+     */
+    metadata(change) {
         if (!this.isReady()) {
             return undefined;
         }
-        return A.getHeads(this.#doc);
+        if (!change) {
+            change = this.heads()[0];
+        }
+        // we return undefined instead of null by convention in this API
+        return (A.inspectChange(this.#doc, decodeHeads([change])[0]) ||
+            undefined);
     }
     /**
      * `update` is called any time we have a new document state; could be
@@ -301,6 +439,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) },
@@ -315,13 +456,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;
                 },
             },
@@ -343,10 +489,10 @@ 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);
         });
@@ -365,6 +511,14 @@ export class DocHandle extends EventEmitter {
         if (this.#state === "loading")
             this.#machine.send({ type: REQUEST });
     }
+    /** Called by the repo to free memory used by the document. */
+    unload() {
+        this.#machine.send({ type: UNLOAD });
+    }
+    /** Called by the repo to reuse an unloaded handle. */
+    reload() {
+        this.#machine.send({ type: RELOAD });
+    }
     /** Called by the repo when the document is deleted. */
     delete() {
         this.#machine.send({ type: DELETE });
@@ -382,6 +536,9 @@ export class DocHandle extends EventEmitter {
             data: encode(message),
         });
     }
+    metrics() {
+        return A.stats(this.#doc);
+    }
 }
 // STATE MACHINE TYPES & CONSTANTS
 // state
@@ -397,16 +554,20 @@ export const HandleState = {
     REQUESTING: "requesting",
     /** The document is available */
     READY: "ready",
+    /** The document has been unloaded from the handle, to free memory usage */
+    UNLOADED: "unloaded",
     /** The document has been deleted from the repo */
     DELETED: "deleted",
     /** The document was not available in storage or from any connected peers */
     UNAVAILABLE: "unavailable",
 };
-export const { IDLE, LOADING, REQUESTING, READY, DELETED, UNAVAILABLE } = HandleState;
+export const { IDLE, LOADING, REQUESTING, READY, UNLOADED, DELETED, UNAVAILABLE, } = HandleState;
 const BEGIN = "BEGIN";
 const REQUEST = "REQUEST";
 const DOC_READY = "DOC_READY";
 const UPDATE = "UPDATE";
+const UNLOAD = "UNLOAD";
+const RELOAD = "RELOAD";
 const DELETE = "DELETE";
 const TIMEOUT = "TIMEOUT";
 const DOC_UNAVAILABLE = "DOC_UNAVAILABLE";

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

@@ -5,7 +5,11 @@ import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageAdapterInterface } from "./storage/StorageAdapterInterface.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
 import { StorageId } from "./storage/types.js";
-import type { AnyDocumentId, DocumentId, PeerId } from "./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
  *
@@ -23,13 +27,15 @@ export declare class Repo extends EventEmitter<RepoEvents> {
     /** The debounce rate is adjustable on the repo. */
     /** @hidden */
     saveDebounceRate: number;
+    /** @hidden */
+    synchronizer: CollectionSynchronizer;
     /** By default, we share generously with all peers. */
     /** @hidden */
     sharePolicy: SharePolicy;
     /** maps peer id to to persistence information (storageId, isEphemeral), access by collection synchronizer  */
     /** @hidden */
     peerMetadataByPeerId: Record<PeerId, PeerMetadata>;
-    constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, }?: RepoConfig);
+    constructor({ storage, network, peerId, sharePolicy, isEphemeral, enableRemoteHeadsGossiping, denylist, }?: RepoConfig);
     /** Returns all the handles we have cached. */
     get handles(): Record<DocumentId, DocHandle<any>>;
     /** Returns a list of all connected peer ids */
@@ -53,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;
@@ -89,7 +95,19 @@ export declare class Repo extends EventEmitter<RepoEvents> {
      * @returns Promise<void>
      */
     flush(documents?: DocumentId[]): Promise<void>;
+    /**
+     * Removes a DocHandle from the handleCache.
+     * @hidden this API is experimental and may change.
+     * @param documentId - documentId of the DocHandle to remove from handleCache, if present in cache.
+     * @returns Promise<void>
+     */
+    removeFromCache(documentId: DocumentId): Promise<void>;
     shutdown(): Promise<void>;
+    metrics(): {
+        documents: {
+            [key: string]: any;
+        };
+    };
 }
 export interface RepoConfig {
     /** Our unique identifier */
@@ -110,6 +128,12 @@ export interface RepoConfig {
      * Whether to enable the experimental remote heads gossiping feature
      */
     enableRemoteHeadsGossiping?: boolean;
+    /**
+     * A list of automerge URLs which should never be loaded regardless of what
+     * messages are received or what the share policy is. This is useful to avoid
+     * loading documents that are known to be too resource intensive.
+     */
+    denylist?: AutomergeUrl[];
 }
 /** A function that determines whether we should share a document with a peer
  *
@@ -127,6 +151,10 @@ export interface RepoEvents {
     "delete-document": (arg: DeleteDocumentPayload) => void;
     /** A document was marked as unavailable (we don't have it and none of our peers have it) */
     "unavailable-document": (arg: DeleteDocumentPayload) => void;
+    "doc-metrics": (arg: DocMetrics) => void;
+}
+export interface RepoFindOptions {
+    allowableStates?: string[];
 }
 export interface DocumentPayload {
     handle: DocHandle<any>;
@@ -134,4 +162,14 @@ export interface DocumentPayload {
 export interface DeleteDocumentPayload {
     documentId: DocumentId;
 }
+export type DocMetrics = DocSyncMetrics | {
+    type: "doc-loaded";
+    documentId: DocumentId;
+    durationMillis: number;
+    numOps: number;
+    numChanges: number;
+} | {
+    type: "doc-denied";
+    documentId: DocumentId;
+};
 //# sourceMappingURL=Repo.d.ts.map

package/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAM5C,OAAO,EAAE,SAAS,EAAiC,MAAM,gBAAgB,CAAA;AAIzE,OAAO,EACL,uBAAuB,EACvB,KAAK,YAAY,EAClB,MAAM,sCAAsC,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAG9C,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAMnE,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC,mDAAmD;IACnD,cAAc;IACd,gBAAgB,SAAM;IAMtB,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;IAE3C,8GAA8G;IAC9G,cAAc;IACd,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAK;gBAK3C,EACV,OAAO,EACP,OAAY,EACZ,MAAuB,EACvB,WAAW,EACX,WAAmC,EACnC,0BAAkC,GACnC,GAAE,UAAe;IAwPlB,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAIzD;;;;OAIG;IACH,MAAM,CAAC,CAAC,EAAE,YAAY,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC;IAuBzC;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAuBnC;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,sDAAsD;IACtD,EAAE,EAAE,aAAa,GAChB,SAAS,CAAC,CAAC,CAAC;IA+Cf,MAAM;IACJ,oDAAoD;IACpD,EAAE,EAAE,aAAa;IAWnB;;;;;;OAMG;IACG,MAAM,CAAC,EAAE,EAAE,aAAa,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAShE;;;OAGG;IACH,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU;IAY5B,kBAAkB,YAAa,SAAS,EAAE,UASzC;IAED,SAAS,QAAa,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC,CAMnD;IAED;;;;;OAKG;IACG,KAAK,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpD,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAM1B;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;8DAC0D;IAC1D,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB,gDAAgD;IAChD,OAAO,CAAC,EAAE,uBAAuB,CAAA;IAEjC,iEAAiE;IACjE,OAAO,CAAC,EAAE,uBAAuB,EAAE,CAAA;IAEnC;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;IAEzB;;OAEG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAA;CACrC;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}