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

package/dist/Repo.js

@@ -1,13 +1,15 @@
 import { next as Automerge } from "@automerge/automerge/slim";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
-import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
+import { encodeHeads, generateAutomergeUrl, interpretAsDocumentId, isValidAutomergeUrl, parseAutomergeUrl, } from "./AutomergeUrl.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";
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
-import { next as A } from "@automerge/automerge/slim";
-import { InMemoryStorageAdapter } from "./storage/StorageAdapter.js";
+import { abortable } from "./helpers/abortable.js";
 function randomPeerId() {
     return ("peer-" + Math.random().toString(36).slice(4));
 }
@@ -23,7 +25,11 @@ export class Repo extends EventEmitter {
     #log;
     /** @hidden */
     networkSubsystem;
+    /** @hidden */
     storageSubsystem;
+    /** The debounce rate is adjustable on the repo. */
+    /** @hidden */
+    saveDebounceRate = 100;
     #handleCache = {};
     /** @hidden */
     synchronizer;
@@ -33,73 +39,49 @@ export class Repo extends EventEmitter {
     /** maps peer id to to persistence information (storageId, isEphemeral), access by collection synchronizer  */
     /** @hidden */
     peerMetadataByPeerId = {};
-    #beelay;
+    #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions();
+    #remoteHeadsGossipingEnabled = false;
+    #progressCache = {};
     constructor({ storage, network = [], peerId = randomPeerId(), sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, denylist = [], } = {}) {
         super();
-        if (storage == null) {
-            // beelayStorage = new InMemoryStorageAdapter()
-            storage = new InMemoryStorageAdapter();
-        }
-        this.#beelay = new A.beelay.Beelay({
-            storage,
-            peerId,
-            requestPolicy: async ({ docId }) => {
-                const peers = Array.from(this.networkSubsystem.peers);
-                const generousPeers = [];
-                for (const peerId of peers) {
-                    const okToShare = await this.sharePolicy(peerId);
-                    if (okToShare)
-                        generousPeers.push(peerId);
-                }
-                return generousPeers;
-            },
-        });
-        this.storageSubsystem = new StorageSubsystem(this.#beelay, storage);
+        this.#remoteHeadsGossipingEnabled = enableRemoteHeadsGossiping;
         this.#log = debug(`automerge-repo:repo`);
         this.sharePolicy = sharePolicy ?? this.sharePolicy;
-        this.#beelay.on("message", ({ message }) => {
-            this.#log(`sending ${message} message to ${message.recipient}`);
-            networkSubsystem.send({
-                targetId: message.recipient,
-                type: "beelay",
-                ...message,
-            });
-        });
-        this.#beelay.on("docEvent", event => {
-            this.#log(`received ${event.data.type} event for ${event.docId}`);
-            const handle = this.#handleCache[event.docId];
-            if (handle != null) {
-                handle.update(d => Automerge.loadIncremental(d, event.data.contents));
-            }
-        });
-        this.#beelay.on("bundleRequired", ({ start, end, checkpoints, docId }) => {
-            ;
-            (async () => {
-                const doc = await this.storageSubsystem.loadDoc(docId);
-                if (doc == null) {
-                    console.warn("document not found when creating bundle");
-                    return;
-                }
-                const bundle = A.saveBundle(doc, start, end);
-                this.#beelay.addBundle({
-                    docId,
-                    checkpoints,
-                    start,
-                    end,
-                    data: bundle,
+        this.on("delete-document", ({ documentId }) => {
+            // TODO Pass the delete on to the network
+            // synchronizer.removeDocument(documentId)
+            if (storageSubsystem) {
+                storageSubsystem.removeDoc(documentId).catch(err => {
+                    this.#log("error deleting document", { documentId, err });
                 });
-            })();
+            }
         });
         // SYNCHRONIZER
-        this.synchronizer = new CollectionSynchronizer(this.#beelay, this, []);
+        // The synchronizer uses the network subsystem to keep documents in sync with peers.
+        this.synchronizer = new CollectionSynchronizer(this, denylist);
+        // When the synchronizer emits messages, send them to peers
         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.#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.
         const myPeerMetadata = (async () => ({
-            // storageId: await this.storageSubsystem.id(),
+            storageId: await storageSubsystem?.id(),
             isEphemeral,
         }))();
         const networkSubsystem = new NetworkSubsystem(network, peerId, myPeerMetadata);
@@ -110,69 +92,128 @@ export class Repo extends EventEmitter {
             if (peerMetadata) {
                 this.peerMetadataByPeerId[peerId] = { ...peerMetadata };
             }
+            this.sharePolicy(peerId)
+                .then(shouldShare => {
+                if (shouldShare && this.#remoteHeadsGossipingEnabled) {
+                    this.#remoteHeadsSubscriptions.addGenerousPeer(peerId);
+                }
+            })
+                .catch(err => {
+                console.log("error in share policy", { err });
+            });
             this.synchronizer.addPeer(peerId);
         });
+        // When a peer disconnects, remove it from the synchronizer
+        networkSubsystem.on("peer-disconnected", ({ peerId }) => {
+            this.synchronizer.removePeer(peerId);
+            this.#remoteHeadsSubscriptions.removePeer(peerId);
+        });
         // Handle incoming messages
         networkSubsystem.on("message", async (msg) => {
-            //@ts-ignore
-            // const inspected = A.beelay.inspectMessage(msg.message)
-            // this.#log(`received msg: ${JSON.stringify(inspected)}`)
-            //@ts-ignore
-            if (msg.type === "beelay") {
-                if (!(msg.message instanceof Uint8Array)) {
-                    // The Uint8Array instance in the vitest VM is _different_ from the
-                    // Uint8Array instance which is available in this file for some reason.
-                    // So, even though `msg.message` _is_ a `Uint8Array`, we have to do this
-                    // absurd thing to get the tests to pass
-                    msg.message = Uint8Array.from(msg.message);
-                }
-                this.#beelay.receiveMessage({
-                    message: {
-                        sender: msg.senderId,
-                        recipient: msg.targetId,
-                        message: msg.message,
-                    },
-                });
+            this.#receiveMessage(msg);
+        });
+        this.synchronizer.on("sync-state", message => {
+            this.#saveSyncState(message);
+            const handle = this.#handleCache[message.documentId];
+            const { storageId } = this.peerMetadataByPeerId[message.peerId] || {};
+            if (!storageId) {
+                return;
             }
-            else {
-                this.#receiveMessage(msg);
+            const heads = handle.getRemoteHeads(storageId);
+            const haveHeadsChanged = message.syncState.theirHeads &&
+                (!heads ||
+                    !headsAreSame(heads, encodeHeads(message.syncState.theirHeads)));
+            if (haveHeadsChanged && message.syncState.theirHeads) {
+                handle.setRemoteHeads(storageId, encodeHeads(message.syncState.theirHeads));
+                if (storageId && this.#remoteHeadsGossipingEnabled) {
+                    this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, encodeHeads(message.syncState.theirHeads));
+                }
             }
         });
+        if (this.#remoteHeadsGossipingEnabled) {
+            this.#remoteHeadsSubscriptions.on("notify-remote-heads", message => {
+                this.networkSubsystem.send({
+                    type: "remote-heads-changed",
+                    targetId: message.targetId,
+                    documentId: message.documentId,
+                    newHeads: {
+                        [message.storageId]: {
+                            heads: message.heads,
+                            timestamp: message.timestamp,
+                        },
+                    },
+                });
+            });
+            this.#remoteHeadsSubscriptions.on("change-remote-subs", message => {
+                this.#log("change-remote-subs", message);
+                for (const peer of message.peers) {
+                    this.networkSubsystem.send({
+                        type: "remote-subscription-change",
+                        targetId: peer,
+                        add: message.add,
+                        remove: message.remove,
+                    });
+                }
+            });
+            this.#remoteHeadsSubscriptions.on("remote-heads-changed", message => {
+                const handle = this.#handleCache[message.documentId];
+                handle.setRemoteHeads(message.storageId, message.remoteHeads);
+            });
+        }
     }
     // 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) {
-        handle.on("heads-changed", () => {
-            const doc = handle.docSync();
-            if (doc != null) {
-                this.storageSubsystem.saveDoc(handle.documentId, doc);
-            }
-        });
-        handle.on("unavailable", () => {
-            this.#log("document unavailable", { documentId: handle.documentId });
-            this.emit("unavailable-document", {
-                documentId: handle.documentId,
-            });
-        });
-        this.synchronizer.addDocument(handle.documentId);
-        // Preserve the old event in case anyone was using it.
-        this.emit("document", { 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));
+        }
+        // Register the document with the synchronizer. This advertises our interest in the document.
+        this.synchronizer.addDocument(handle);
     }
     #receiveMessage(message) {
         switch (message.type) {
             case "remote-subscription-change":
+                if (this.#remoteHeadsGossipingEnabled) {
+                    this.#remoteHeadsSubscriptions.handleControlMessage(message);
+                }
+                break;
             case "remote-heads-changed":
+                if (this.#remoteHeadsGossipingEnabled) {
+                    this.#remoteHeadsSubscriptions.handleRemoteHeads(message);
+                }
                 break;
             case "sync":
             case "request":
             case "ephemeral":
             case "doc-unavailable":
                 this.synchronizer.receiveMessage(message).catch(err => {
-                    console.error("error receiving message", { err });
+                    console.log("error receiving message", { err });
                 });
-                break;
         }
     }
+    #throttledSaveSyncStateHandlers = {};
+    /** saves sync state throttled per storage id, if a peer doesn't have a storage id it's sync state is not persisted */
+    #saveSyncState(payload) {
+        if (!this.storageSubsystem) {
+            return;
+        }
+        const { storageId, isEphemeral } = this.peerMetadataByPeerId[payload.peerId] || {};
+        if (!storageId || isEphemeral) {
+            return;
+        }
+        let handler = this.#throttledSaveSyncStateHandlers[storageId];
+        if (!handler) {
+            handler = this.#throttledSaveSyncStateHandlers[storageId] = throttle(({ documentId, syncState }) => {
+                void this.storageSubsystem.saveSyncState(documentId, storageId, syncState);
+            }, this.saveDebounceRate);
+        }
+        handler(payload);
+    }
     /** Returns an existing handle if we have it; creates one otherwise. */
     #getHandle({ documentId, }) {
         // If we have the handle cached, return it
@@ -191,7 +232,7 @@ export class Repo extends EventEmitter {
     }
     /** Returns a list of all connected peer ids */
     get peers() {
-        return this.networkSubsystem.peers;
+        return this.synchronizer.peers;
     }
     getStorageIdOfPeer(peerId) {
         return this.peerMetadataByPeerId[peerId]?.storageId;
@@ -207,7 +248,7 @@ export class Repo extends EventEmitter {
         const handle = this.#getHandle({
             documentId,
         });
-        let initialLinks = [];
+        this.#registerHandleWithSubsystems(handle);
         handle.update(() => {
             let nextDoc;
             if (initialValue) {
@@ -216,27 +257,8 @@ export class Repo extends EventEmitter {
             else {
                 nextDoc = Automerge.emptyChange(Automerge.init());
             }
-            const patches = A.diff(nextDoc, [], A.getHeads(nextDoc));
-            for (const patch of patches) {
-                initialLinks = patches
-                    .map(patch => {
-                    if (patch.action === "put") {
-                        if (patch.value instanceof A.Link) {
-                            return patch.value;
-                        }
-                    }
-                    return null;
-                })
-                    .filter(v => v != null);
-            }
             return nextDoc;
         });
-        for (const link of initialLinks) {
-            const { documentId: target } = parseAutomergeUrl(link.target);
-            this.#beelay.addLink({ from: documentId, to: target });
-        }
-        this.storageSubsystem.saveDoc(handle.documentId, handle.docSync());
-        this.#registerHandleWithSubsystems(handle);
         handle.doneLoading();
         return handle;
     }
@@ -252,18 +274,13 @@ export class Repo extends EventEmitter {
      * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
      * be notified of the newly created DocHandle.
      *
-     * @throws if the cloned handle is not yet ready or if
-     * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
      */
     clone(clonedHandle) {
         if (!clonedHandle.isReady()) {
             throw new Error(`Cloned handle is not yet in ready state.
         (Try await handle.whenReady() first.)`);
         }
-        const sourceDoc = clonedHandle.docSync();
-        if (!sourceDoc) {
-            throw new Error("Cloned handle doesn't have a document.");
-        }
+        const sourceDoc = clonedHandle.doc();
         const handle = this.create();
         handle.update(() => {
             // we replace the document with the new cloned one
@@ -271,55 +288,220 @@ export class Repo extends EventEmitter {
         });
         return handle;
     }
-    /**
-     * Retrieves a document by id. It gets data from the local system, but also emits a `document`
-     * event to advertise interest in the document.
-     */
-    find(
-    /** The url or documentId of the handle to retrieve */
-    id) {
-        this.#log("find", { id });
-        const documentId = interpretAsDocumentId(id);
-        // If we have the handle cached, return it
+    findWithProgress(id, options = {}) {
+        const { signal } = options;
+        const { documentId, heads } = isValidAutomergeUrl(id)
+            ? parseAutomergeUrl(id)
+            : { documentId: interpretAsDocumentId(id), heads: undefined };
+        // Check handle cache first - return plain FindStep for terminal states
         if (this.#handleCache[documentId]) {
-            if (this.#handleCache[documentId].isUnavailable()) {
-                // this ensures that the event fires after the handle has been returned
-                setTimeout(() => {
-                    this.#handleCache[documentId].emit("unavailable", {
-                        handle: this.#handleCache[documentId],
-                    });
-                });
+            const handle = this.#handleCache[documentId];
+            if (handle.state === UNAVAILABLE) {
+                const result = {
+                    state: "unavailable",
+                    error: new Error(`Document ${id} is unavailable`),
+                    handle,
+                };
+                return result;
+            }
+            if (handle.state === DELETED) {
+                const result = {
+                    state: "failed",
+                    error: new Error(`Document ${id} was deleted`),
+                    handle,
+                };
+                return result;
+            }
+            if (handle.state === READY) {
+                const result = {
+                    state: "ready",
+                    handle: heads ? handle.view(heads) : handle,
+                };
+                return result;
             }
-            return this.#handleCache[documentId];
         }
-        // If we don't already have the handle, make an empty one and try loading it
-        const handle = this.#getHandle({
-            documentId,
-        });
-        // Loading & network is going to be asynchronous no matter what,
-        // but we want to return the handle immediately.
-        const attemptLoad = this.storageSubsystem.loadDoc(handle.documentId);
-        attemptLoad
-            .then(async (loadedDoc) => {
+        // Check progress cache for any existing signal
+        const cachedProgress = this.#progressCache[documentId];
+        if (cachedProgress) {
+            const handle = this.#handleCache[documentId];
+            // Return cached progress if we have a handle and it's either in a terminal state or loading
+            if (handle &&
+                (handle.state === READY ||
+                    handle.state === UNAVAILABLE ||
+                    handle.state === DELETED ||
+                    handle.state === "loading")) {
+                return cachedProgress;
+            }
+        }
+        const handle = this.#getHandle({ documentId });
+        const initial = {
+            state: "loading",
+            progress: 0,
+            handle,
+        };
+        // Create a new progress signal
+        const progressSignal = {
+            subscribers: new Set(),
+            currentProgress: undefined,
+            notify: (progress) => {
+                progressSignal.currentProgress = progress;
+                progressSignal.subscribers.forEach(callback => callback(progress));
+                // Cache all states, not just terminal ones
+                this.#progressCache[documentId] = progress;
+            },
+            peek: () => progressSignal.currentProgress || initial,
+            subscribe: (callback) => {
+                progressSignal.subscribers.add(callback);
+                return () => progressSignal.subscribers.delete(callback);
+            },
+        };
+        progressSignal.notify(initial);
+        // Start the loading process
+        void this.#loadDocumentWithProgress(id, documentId, handle, progressSignal, signal ? abortable(new Promise(() => { }), signal) : new Promise(() => { }));
+        const result = {
+            ...initial,
+            peek: progressSignal.peek,
+            subscribe: progressSignal.subscribe,
+        };
+        this.#progressCache[documentId] = result;
+        return result;
+    }
+    async #loadDocumentWithProgress(id, documentId, handle, progressSignal, abortPromise) {
+        try {
+            progressSignal.notify({
+                state: "loading",
+                progress: 25,
+                handle,
+            });
+            const loadingPromise = await (this.storageSubsystem
+                ? this.storageSubsystem.loadDoc(handle.documentId)
+                : Promise.resolve(null));
+            const loadedDoc = await Promise.race([loadingPromise, abortPromise]);
             if (loadedDoc) {
-                // uhhhh, sorry if you're reading this because we were lying to the type system
                 handle.update(() => loadedDoc);
                 handle.doneLoading();
+                progressSignal.notify({
+                    state: "loading",
+                    progress: 50,
+                    handle,
+                });
             }
             else {
-                // we want to wait for the network subsystem to be ready before
-                // we request the document. this prevents entering unavailable during initialization.
-                await this.networkSubsystem.whenReady();
-                console.log("we didn't find it so we're requesting");
+                await Promise.race([this.networkSubsystem.whenReady(), abortPromise]);
                 handle.request();
+                progressSignal.notify({
+                    state: "loading",
+                    progress: 75,
+                    handle,
+                });
             }
             this.#registerHandleWithSubsystems(handle);
-        })
-            .catch(err => {
-            this.#log("error waiting for network", { err });
-        });
+            await Promise.race([handle.whenReady([READY, UNAVAILABLE]), abortPromise]);
+            if (handle.state === UNAVAILABLE) {
+                const unavailableProgress = {
+                    state: "unavailable",
+                    handle,
+                };
+                progressSignal.notify(unavailableProgress);
+                return;
+            }
+            if (handle.state === DELETED) {
+                throw new Error(`Document ${id} was deleted`);
+            }
+            progressSignal.notify({ state: "ready", handle });
+        }
+        catch (error) {
+            progressSignal.notify({
+                state: "failed",
+                error: error instanceof Error ? error : new Error(String(error)),
+                handle: this.#getHandle({ documentId }),
+            });
+        }
+    }
+    async find(id, options = {}) {
+        const { allowableStates = ["ready"], signal } = options;
+        // Check if already aborted
+        if (signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        const progress = this.findWithProgress(id, { signal });
+        if ("subscribe" in progress) {
+            this.#registerHandleWithSubsystems(progress.handle);
+            return new Promise((resolve, reject) => {
+                const unsubscribe = progress.subscribe(state => {
+                    if (allowableStates.includes(state.handle.state)) {
+                        unsubscribe();
+                        resolve(state.handle);
+                    }
+                    else if (state.state === "unavailable") {
+                        unsubscribe();
+                        reject(new Error(`Document ${id} is unavailable`));
+                    }
+                    else if (state.state === "failed") {
+                        unsubscribe();
+                        reject(state.error);
+                    }
+                });
+            });
+        }
+        else {
+            if (progress.handle.state === READY) {
+                return progress.handle;
+            }
+            // If the handle isn't ready, wait for it and then return it
+            await progress.handle.whenReady([READY, UNAVAILABLE]);
+            return progress.handle;
+        }
+    }
+    /**
+     * Loads a document without waiting for ready state
+     */
+    async #loadDocument(documentId) {
+        // If we have the handle cached, return it
+        if (this.#handleCache[documentId]) {
+            return this.#handleCache[documentId];
+        }
+        // If we don't already have the handle, make an empty one and try loading it
+        const handle = this.#getHandle({ documentId });
+        const loadedDoc = await (this.storageSubsystem
+            ? this.storageSubsystem.loadDoc(handle.documentId)
+            : Promise.resolve(null));
+        if (loadedDoc) {
+            // We need to cast this to <T> because loadDoc operates in <unknowns>.
+            // This is really where we ought to be validating the input matches <T>.
+            handle.update(() => loadedDoc);
+            handle.doneLoading();
+        }
+        else {
+            // Because the network subsystem might still be booting up, we wait
+            // here so that we don't immediately give up loading because we're still
+            // making our initial connection to a sync server.
+            await this.networkSubsystem.whenReady();
+            handle.request();
+        }
+        this.#registerHandleWithSubsystems(handle);
         return handle;
     }
+    /**
+     * Retrieves a document by id. It gets data from the local system, but also emits a `document`
+     * event to advertise interest in the document.
+     */
+    async findClassic(
+    /** The url or documentId of the handle to retrieve */
+    id, options = {}) {
+        const documentId = interpretAsDocumentId(id);
+        const { allowableStates, signal } = options;
+        return abortable((async () => {
+            const handle = await this.#loadDocument(documentId);
+            if (!allowableStates) {
+                await handle.whenReady([READY, UNAVAILABLE]);
+                if (handle.state === UNAVAILABLE && !signal?.aborted) {
+                    throw new Error(`Document ${id} is unavailable`);
+                }
+            }
+            return handle;
+        })(), signal);
+    }
     delete(
     /** The url or documentId of the handle to delete */
     id) {
@@ -327,6 +509,7 @@ export class Repo extends EventEmitter {
         const handle = this.#getHandle({ documentId });
         handle.delete();
         delete this.#handleCache[documentId];
+        delete this.#progressCache[documentId];
         this.emit("delete-document", { documentId });
     }
     /**
@@ -339,9 +522,7 @@ export class Repo extends EventEmitter {
     async export(id) {
         const documentId = interpretAsDocumentId(id);
         const handle = this.#getHandle({ documentId });
-        const doc = await handle.doc();
-        if (!doc)
-            return undefined;
+        const doc = handle.doc();
         return Automerge.save(doc);
     }
     /**
@@ -356,7 +537,15 @@ export class Repo extends EventEmitter {
         });
         return handle;
     }
-    subscribeToRemotes = (remotes) => { };
+    subscribeToRemotes = (remotes) => {
+        if (this.#remoteHeadsGossipingEnabled) {
+            this.#log("subscribeToRemotes", { remotes });
+            this.#remoteHeadsSubscriptions.subscribeToRemotes(remotes);
+        }
+        else {
+            this.#log("WARN: subscribeToRemotes called but remote heads gossiping is not enabled");
+        }
+    };
     storageId = async () => {
         if (!this.storageSubsystem) {
             return undefined;
@@ -379,11 +568,7 @@ export class Repo extends EventEmitter {
             ? documents.map(id => this.#handleCache[id])
             : Object.values(this.#handleCache);
         await Promise.all(handles.map(async (handle) => {
-            const doc = handle.docSync();
-            if (!doc) {
-                return;
-            }
-            return this.storageSubsystem.saveDoc(handle.documentId, doc);
+            return this.storageSubsystem.saveDoc(handle.documentId, handle.doc());
         }));
     }
     /**
@@ -398,7 +583,9 @@ export class Repo extends EventEmitter {
             return;
         }
         const handle = this.#getHandle({ documentId });
-        const doc = await handle.doc([READY, UNLOADED, DELETED, UNAVAILABLE]);
+        await handle.whenReady([READY, UNLOADED, DELETED, UNAVAILABLE]);
+        const doc = handle.doc();
+        // because this is an internal-ish function, we'll be extra careful about undefined docs here
         if (doc) {
             if (handle.isReady()) {
                 handle.unload();
@@ -421,7 +608,6 @@ export class Repo extends EventEmitter {
         return this.flush();
     }
     metrics() {
-        //return { documents: this.synchronizer.metrics() }
-        return { documents: {} };
+        return { documents: this.synchronizer.metrics() };
     }
 }