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

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,6 +64,9 @@ export class DocHandle extends EventEmitter {
                     this.emit("delete", { handle: this });
                     return { doc: A.init() };
                 }),
+                onUnload: assign(() => {
+                    return { doc: A.init() };
+                }),
                 onUnavailable: () => {
                     this.emit("unavailable", { handle: this });
                 },
@@ -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.
      *
@@ -220,6 +245,13 @@ 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;
     }
@@ -239,8 +271,11 @@ export class DocHandle extends EventEmitter {
     docSync() {
         if (!this.isReady())
             return undefined;
-        else
-            return this.#doc;
+        if (this.#fixedHeads) {
+            const doc = this.#doc;
+            return doc ? A.view(doc, decodeHeads(this.#fixedHeads)) : undefined;
+        }
+        return this.#doc;
     }
     /**
      * Returns the current "heads" of the document, akin to a git commit.
@@ -248,10 +283,120 @@ 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.#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;
         }
-        return A.getHeads(this.#doc);
+        // This just returns all the heads as individual strings.
+        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
+     * 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.docSync());
+            // 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;
+        }
+        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 +446,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 +463,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,6 +496,9 @@ export class DocHandle extends EventEmitter {
         if (!this.isReady() || !otherHandle.isReady()) {
             throw new Error("Both handles must be ready to merge");
         }
+        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.");
@@ -365,6 +521,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 +546,9 @@ export class DocHandle extends EventEmitter {
             data: encode(message),
         });
     }
+    metrics() {
+        return A.stats(this.#doc);
+    }
 }
 // STATE MACHINE TYPES & CONSTANTS
 // state
@@ -397,16 +564,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/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,9 @@ 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";
 /** 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 +25,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 */
@@ -89,7 +93,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 +126,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 +149,7 @@ 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 DocumentPayload {
     handle: DocHandle<any>;
@@ -134,4 +157,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":"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"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"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"}