@automerge/automerge-repo 2.0.0-alpha.1 → 2.0.0-alpha.12

package/dist/DocHandle.d.ts

@@ -30,6 +30,13 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * peers. We do not currently have an equivalent `whenSynced()`.
      */
     isReady: () => boolean;
+    /**
+     * @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: () => boolean;
     /**
      * @returns true if the document has been marked as deleted.
      *
@@ -48,7 +55,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     inState: (states: HandleState[]) => boolean;
     /** @hidden */
-    get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "deleted";
+    get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "unloaded" | "deleted";
     /**
      * @returns a promise that resolves when the document is in one of the given states (if no states
      * are passed, when the document is ready)
@@ -86,6 +93,58 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * @returns the current document's heads, or undefined if the document is not ready
      */
     heads(): A.Heads | undefined;
+    begin(): void;
+    /**
+     * 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.
+     *
+     * @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 The individual heads for every change in the document.
+     */
+    history(): A.Heads[] | undefined;
+    /**
+     * 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.
+     *
+     * @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.
+     *
+     * @returns An Automerge.Doc<T> at the point in time.
+     */
+    view(heads: A.Heads): A.Doc<T> | undefined;
+    /**
+     * 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.
+     *
+     * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
+     */
+    diff(first: A.Heads, second?: A.Heads): A.Patch[] | undefined;
+    /**
+     * `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?: string): A.DecodedChange | undefined;
     /**
      * `update` is called any time we have a new document state; could be
      * from a local change, a remote change, or a new document from storage.
@@ -148,6 +207,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * @hidden
      * */
     request(): void;
+    /** Called by the repo to free memory used by the document. */
+    unload(): void;
+    /** Called by the repo to reuse an unloaded handle. */
+    reload(): void;
     /** Called by the repo when the document is deleted. */
     delete(): void;
     /**
@@ -158,6 +221,10 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * must have a unique PeerId.
      */
     broadcast(message: unknown): void;
+    metrics(): {
+        numOps: number;
+        numChanges: number;
+    };
 }
 /** @hidden */
 export type DocHandleOptions<T> = {
@@ -232,11 +299,13 @@ export declare const HandleState: {
     readonly REQUESTING: "requesting";
     /** The document is available */
     readonly READY: "ready";
+    /** The document has been unloaded from the handle, to free memory usage */
+    readonly UNLOADED: "unloaded";
     /** The document has been deleted from the repo */
     readonly DELETED: "deleted";
     /** The document was not available in storage or from any connected peers */
     readonly UNAVAILABLE: "unavailable";
 };
 export type HandleState = (typeof HandleState)[keyof typeof HandleState];
-export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", DELETED: "deleted", UNAVAILABLE: "unavailable";
+export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", UNLOADED: "unloaded", DELETED: "deleted", UNAVAILABLE: "unavailable";
 //# sourceMappingURL=DocHandle.d.ts.map

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -59,6 +59,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 +74,7 @@ export class DocHandle extends EventEmitter {
             context: { documentId, doc },
             on: {
                 UPDATE: { actions: "onUpdate" },
+                UNLOAD: ".unloaded",
                 DELETE: ".deleted",
             },
             states: {
@@ -98,6 +102,12 @@ export class DocHandle extends EventEmitter {
                     on: { DOC_READY: "ready" },
                 },
                 ready: {},
+                unloaded: {
+                    entry: "onUnload",
+                    on: {
+                        RELOAD: "loading",
+                    },
+                },
                 deleted: { entry: "onDelete", type: "final" },
             },
         });
@@ -113,7 +123,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 */
@@ -172,6 +182,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.
      *
@@ -253,6 +270,88 @@ export class DocHandle extends EventEmitter {
         }
         return 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.
+     *
+     * @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 The individual heads for every change in the document.
+     */
+    history() {
+        if (!this.isReady()) {
+            return undefined;
+        }
+        // This just returns all the heads as individual strings.
+        return A.topoHistoryTraversal(this.#doc).map(h => [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
+     * 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.
+     *
+     * @returns An Automerge.Doc<T> at the point in time.
+     */
+    view(heads) {
+        if (!this.isReady()) {
+            return undefined;
+        }
+        return A.view(this.#doc, heads);
+    }
+    /**
+     * 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.
+     *
+     * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
+     */
+    diff(first, second) {
+        if (!this.isReady()) {
+            return undefined;
+        }
+        // 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
+        const to = second ? second : first;
+        return A.diff(this.#doc, from, 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, change) || undefined;
+    }
     /**
      * `update` is called any time we have a new document state; could be
      * from a local change, a remote change, or a new document from storage.
@@ -365,6 +464,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 +489,9 @@ export class DocHandle extends EventEmitter {
             data: encode(message),
         });
     }
+    metrics() {
+        return A.stats(this.#doc);
+    }
 }
 // STATE MACHINE TYPES & CONSTANTS
 // state
@@ -397,16 +507,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/Repo.d.ts

@@ -5,6 +5,8 @@ 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 { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
+import { DocSyncMetrics } from "./synchronizer/Synchronizer.js";
 import type { AnyDocumentId, 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,6 +25,8 @@ 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;
@@ -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 */
@@ -127,6 +143,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 +151,11 @@ export interface DocumentPayload {
 export interface DeleteDocumentPayload {
     documentId: DocumentId;
 }
+export type DocMetrics = DocSyncMetrics | {
+    type: "doc-loaded";
+    documentId: DocumentId;
+    durationMillis: number;
+    numOps: number;
+    numChanges: number;
+};
 //# 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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"}

package/dist/Repo.js

@@ -2,7 +2,7 @@ import { next as Automerge } from "@automerge/automerge/slim";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
 import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
-import { DocHandle } from "./DocHandle.js";
+import { DELETED, DocHandle, READY, UNAVAILABLE, UNLOADED, } from "./DocHandle.js";
 import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js";
 import { headsAreSame } from "./helpers/headsAreSame.js";
 import { throttle } from "./helpers/throttle.js";
@@ -30,7 +30,8 @@ export class Repo extends EventEmitter {
     /** @hidden */
     saveDebounceRate = 100;
     #handleCache = {};
-    #synchronizer;
+    /** @hidden */
+    synchronizer;
     /** By default, we share generously with all peers. */
     /** @hidden */
     sharePolicy = async () => true;
@@ -44,26 +45,6 @@ export class Repo extends EventEmitter {
         this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping;
         this.#log = debug(`automerge-repo:repo`);
         this.sharePolicy = sharePolicy ?? this.sharePolicy;
-        // DOC COLLECTION
-        // The `document` event is fired by the DocCollection any time we create a new document or look
-        // up a document by ID. We listen for it in order to wire up storage and network synchronization.
-        this.on("document", async ({ handle }) => {
-            if (storageSubsystem) {
-                // Save when the document changes, but no more often than saveDebounceRate.
-                const saveFn = ({ handle, doc, }) => {
-                    void storageSubsystem.saveDoc(handle.documentId, doc);
-                };
-                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);
-        });
         this.on("delete-document", ({ documentId }) => {
             // TODO Pass the delete on to the network
             // synchronizer.removeDocument(documentId)
@@ -75,20 +56,25 @@ export class Repo extends EventEmitter {
         });
         // SYNCHRONIZER
         // The synchronizer uses the network subsystem to keep documents in sync with peers.
-        this.#synchronizer = new CollectionSynchronizer(this);
+        this.synchronizer = new CollectionSynchronizer(this);
         // When the synchronizer emits messages, send them to peers
-        this.#synchronizer.on("message", message => {
+        this.synchronizer.on("message", message => {
             this.#log(`sending ${message.type} message to ${message.targetId}`);
             networkSubsystem.send(message);
         });
+        // Forward metrics from doc synchronizers
+        this.synchronizer.on("metrics", event => this.emit("doc-metrics", event));
         if (this.#remoteHeadsGossipingEnabled) {
-            this.#synchronizer.on("open-doc", ({ peerId, documentId }) => {
+            this.synchronizer.on("open-doc", ({ peerId, documentId }) => {
                 this.#remoteHeadsSubscriptions.subscribePeerToDoc(peerId, documentId);
             });
         }
         // STORAGE
         // The storage subsystem has access to some form of persistence, and deals with save and loading documents.
         const storageSubsystem = storage ? new StorageSubsystem(storage) : undefined;
+        if (storageSubsystem) {
+            storageSubsystem.on("document-loaded", event => this.emit("doc-metrics", { type: "doc-loaded", ...event }));
+        }
         this.storageSubsystem = storageSubsystem;
         // NETWORK
         // The network subsystem deals with sending and receiving messages to and from peers.
@@ -113,18 +99,18 @@ export class Repo extends EventEmitter {
                 .catch(err => {
                 console.log("error in share policy", { err });
             });
-            this.#synchronizer.addPeer(peerId);
+            this.synchronizer.addPeer(peerId);
         });
         // When a peer disconnects, remove it from the synchronizer
         networkSubsystem.on("peer-disconnected", ({ peerId }) => {
-            this.#synchronizer.removePeer(peerId);
+            this.synchronizer.removePeer(peerId);
             this.#remoteHeadsSubscriptions.removePeer(peerId);
         });
         // Handle incoming messages
         networkSubsystem.on("message", async (msg) => {
             this.#receiveMessage(msg);
         });
-        this.#synchronizer.on("sync-state", message => {
+        this.synchronizer.on("sync-state", message => {
             this.#saveSyncState(message);
             const handle = this.#handleCache[message.documentId];
             const { storageId } = this.peerMetadataByPeerId[message.peerId] || {};
@@ -172,6 +158,28 @@ export class Repo extends EventEmitter {
             });
         }
     }
+    // The `document` event is fired by the DocCollection any time we create a new document or look
+    // up a document by ID. We listen for it in order to wire up storage and network synchronization.
+    #registerHandleWithSubsystems(handle) {
+        const { storageSubsystem } = this;
+        if (storageSubsystem) {
+            // Save when the document changes, but no more often than saveDebounceRate.
+            const saveFn = ({ handle, doc }) => {
+                void storageSubsystem.saveDoc(handle.documentId, doc);
+            };
+            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 });
+    }
     #receiveMessage(message) {
         switch (message.type) {
             case "remote-subscription-change":
@@ -188,7 +196,7 @@ export class Repo extends EventEmitter {
             case "request":
             case "ephemeral":
             case "doc-unavailable":
-                this.#synchronizer.receiveMessage(message).catch(err => {
+                this.synchronizer.receiveMessage(message).catch(err => {
                     console.log("error receiving message", { err });
                 });
         }
@@ -229,7 +237,7 @@ export class Repo extends EventEmitter {
     }
     /** Returns a list of all connected peer ids */
     get peers() {
-        return this.#synchronizer.peers;
+        return this.synchronizer.peers;
     }
     getStorageIdOfPeer(peerId) {
         return this.peerMetadataByPeerId[peerId]?.storageId;
@@ -245,7 +253,7 @@ export class Repo extends EventEmitter {
         const handle = this.#getHandle({
             documentId,
         });
-        this.emit("document", { handle });
+        this.#registerHandleWithSubsystems(handle);
         handle.update(() => {
             let nextDoc;
             if (initialValue) {
@@ -277,7 +285,7 @@ export class Repo extends EventEmitter {
     clone(clonedHandle) {
         if (!clonedHandle.isReady()) {
             throw new Error(`Cloned handle is not yet in ready state.
-        (Try await handle.waitForReady() first.)`);
+        (Try await handle.whenReady() first.)`);
         }
         const sourceDoc = clonedHandle.docSync();
         if (!sourceDoc) {
@@ -314,31 +322,29 @@ export class Repo extends EventEmitter {
         const handle = this.#getHandle({
             documentId,
         });
-        // Try to load from disk before telling anyone else about it
-        if (this.storageSubsystem) {
-            void this.storageSubsystem.loadDoc(handle.documentId).then(loadedDoc => {
-                if (loadedDoc) {
-                    // uhhhh, sorry if you're reading this because we were lying to the type system
-                    handle.update(() => loadedDoc);
-                    handle.doneLoading();
-                }
-                else {
-                    this.networkSubsystem
-                        .whenReady()
-                        .then(() => {
-                        handle.request();
-                    })
-                        .catch(err => {
-                        this.#log("error waiting for network", { err });
-                    });
-                    this.emit("document", { handle });
-                }
-            });
-        }
-        else {
-            handle.request();
-            this.emit("document", { handle });
-        }
+        // 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();
+            }
+            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();
+            }
+            this.#registerHandleWithSubsystems(handle);
+        })
+            .catch(err => {
+            this.#log("error waiting for network", { err });
+        });
         return handle;
     }
     delete(
@@ -415,10 +421,41 @@ export class Repo extends EventEmitter {
             return this.storageSubsystem.saveDoc(handle.documentId, doc);
         }));
     }
+    /**
+     * 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>
+     */
+    async removeFromCache(documentId) {
+        if (!this.#handleCache[documentId]) {
+            this.#log(`WARN: removeFromCache called but handle not found in handleCache for documentId: ${documentId}`);
+            return;
+        }
+        const handle = this.#getHandle({ documentId });
+        const doc = await handle.doc([READY, UNLOADED, DELETED, UNAVAILABLE]);
+        if (doc) {
+            if (handle.isReady()) {
+                handle.unload();
+            }
+            else {
+                this.#log(`WARN: removeFromCache called but handle for documentId: ${documentId} in unexpected state: ${handle.state}`);
+            }
+            delete this.#handleCache[documentId];
+            // TODO: remove document from synchronizer when removeDocument is implemented
+            // this.synchronizer.removeDocument(documentId)
+        }
+        else {
+            this.#log(`WARN: removeFromCache called but doc undefined for documentId: ${documentId}`);
+        }
+    }
     shutdown() {
         this.networkSubsystem.adapters.forEach(adapter => {
             adapter.disconnect();
         });
         return this.flush();
     }
+    metrics() {
+        return { documents: this.synchronizer.metrics() };
+    }
 }

package/dist/entrypoints/fullfat.d.ts

@@ -1,2 +1,3 @@
 export * from "../index.js";
+import "@automerge/automerge";
 //# sourceMappingURL=fullfat.d.ts.map

package/dist/entrypoints/fullfat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fullfat.d.ts","sourceRoot":"","sources":["../../src/entrypoints/fullfat.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"fullfat.d.ts","sourceRoot":"","sources":["../../src/entrypoints/fullfat.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAS3B,OAAO,sBAAsB,CAAA"}