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

package/dist/Repo.js

@@ -1,8 +1,8 @@
 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 { 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";
@@ -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;
@@ -39,31 +40,11 @@ export class Repo extends EventEmitter {
     peerMetadataByPeerId = {};
     #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions();
     #remoteHeadsGossipingEnabled = false;
-    constructor({ storage, network = [], peerId = randomPeerId(), sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, } = {}) {
+    constructor({ storage, network = [], peerId = randomPeerId(), sharePolicy, isEphemeral = storage === undefined, enableRemoteHeadsGossiping = false, denylist = [], } = {}) {
         super();
         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, denylist);
         // 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] || {};
@@ -133,11 +119,12 @@ export class Repo extends EventEmitter {
             }
             const heads = handle.getRemoteHeads(storageId);
             const haveHeadsChanged = message.syncState.theirHeads &&
-                (!heads || !headsAreSame(heads, message.syncState.theirHeads));
+                (!heads ||
+                    !headsAreSame(heads, encodeHeads(message.syncState.theirHeads)));
             if (haveHeadsChanged && message.syncState.theirHeads) {
-                handle.setRemoteHeads(storageId, message.syncState.theirHeads);
+                handle.setRemoteHeads(storageId, encodeHeads(message.syncState.theirHeads));
                 if (storageId && this.#remoteHeadsGossipingEnabled) {
-                    this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, message.syncState.theirHeads);
+                    this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(message.documentId, storageId, encodeHeads(message.syncState.theirHeads));
                 }
             }
         });
@@ -172,6 +159,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 +197,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 +238,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 +254,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 +286,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) {
@@ -297,49 +306,51 @@ export class Repo extends EventEmitter {
     find(
     /** The url or documentId of the handle to retrieve */
     id) {
-        const documentId = interpretAsDocumentId(id);
-        // If we have the handle cached, return it
-        if (this.#handleCache[documentId]) {
-            if (this.#handleCache[documentId].isUnavailable()) {
+        const { documentId, heads } = isValidAutomergeUrl(id)
+            ? parseAutomergeUrl(id)
+            : { documentId: interpretAsDocumentId(id), heads: undefined };
+        const cachedHandle = this.#handleCache[documentId];
+        if (cachedHandle) {
+            if (cachedHandle.isUnavailable()) {
                 // this ensures that the event fires after the handle has been returned
                 setTimeout(() => {
-                    this.#handleCache[documentId].emit("unavailable", {
-                        handle: this.#handleCache[documentId],
+                    cachedHandle.emit("unavailable", {
+                        handle: cachedHandle,
                     });
                 });
             }
-            return this.#handleCache[documentId];
+            // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+            return heads ? cachedHandle.view(heads) : cachedHandle;
         }
         // If we don't already have the handle, make an empty one and try loading it
         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 });
-        }
-        return 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 });
+        });
+        // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+        return heads ? handle.view(heads) : handle;
     }
     delete(
     /** The url or documentId of the handle to delete */
@@ -415,10 +426,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"}

package/dist/entrypoints/fullfat.js

@@ -6,5 +6,4 @@ export * from "../index.js";
 // disable
 //
 // eslint-disable-next-line automerge-slimport/enforce-automerge-slim-import
-import { next as Am } from "@automerge/automerge";
-Am.init();
+import "@automerge/automerge";

package/dist/helpers/bufferFromHex.d.ts

@@ -0,0 +1,3 @@
+export declare const uint8ArrayFromHexString: (hexString: string) => Uint8Array;
+export declare const uint8ArrayToHexString: (data: Uint8Array) => string;
+//# sourceMappingURL=bufferFromHex.d.ts.map

package/dist/helpers/bufferFromHex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bufferFromHex.d.ts","sourceRoot":"","sources":["../../src/helpers/bufferFromHex.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,uBAAuB,cAAe,MAAM,KAAG,UAS3D,CAAA;AAED,eAAO,MAAM,qBAAqB,SAAU,UAAU,KAAG,MAExD,CAAA"}

package/dist/helpers/bufferFromHex.js

@@ -0,0 +1,13 @@
+export const uint8ArrayFromHexString = (hexString) => {
+    if (hexString.length % 2 !== 0) {
+        throw new Error("Hex string must have an even length");
+    }
+    const bytes = new Uint8Array(hexString.length / 2);
+    for (let i = 0; i < hexString.length; i += 2) {
+        bytes[i >> 1] = parseInt(hexString.slice(i, i + 2), 16);
+    }
+    return bytes;
+};
+export const uint8ArrayToHexString = (data) => {
+    return Array.from(data, byte => byte.toString(16).padStart(2, "0")).join("");
+};

package/dist/helpers/headsAreSame.d.ts

@@ -1,3 +1,3 @@
-import { Heads } from "@automerge/automerge/slim/next";
-export declare const headsAreSame: (a: Heads, b: Heads) => boolean;
+import type { UrlHeads } from "../types.js";
+export declare const headsAreSame: (a: UrlHeads, b: UrlHeads) => boolean;
 //# sourceMappingURL=headsAreSame.d.ts.map

package/dist/helpers/headsAreSame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"headsAreSame.d.ts","sourceRoot":"","sources":["../../src/helpers/headsAreSame.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gCAAgC,CAAA;AAGtD,eAAO,MAAM,YAAY,MAAO,KAAK,KAAK,KAAK,YAE9C,CAAA"}
+{"version":3,"file":"headsAreSame.d.ts","sourceRoot":"","sources":["../../src/helpers/headsAreSame.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,eAAO,MAAM,YAAY,MAAO,QAAQ,KAAK,QAAQ,YAEpD,CAAA"}

package/dist/helpers/mergeArrays.d.ts

@@ -1,2 +1,2 @@
-export declare function mergeArrays(myArrays: Uint8Array[]): Uint8Array;
+export declare function mergeArrays(myArrays: Uint8Array[]): Uint8Array<ArrayBuffer>;
 //# sourceMappingURL=mergeArrays.d.ts.map

package/dist/helpers/mergeArrays.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mergeArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeArrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,cAgBjD"}
+{"version":3,"file":"mergeArrays.d.ts","sourceRoot":"","sources":["../../src/helpers/mergeArrays.ts"],"names":[],"mappings":"AAAA,wBAAgB,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE,2BAgBjD"}

package/dist/helpers/tests/storage-adapter-tests.d.ts

@@ -1,7 +1,7 @@
 import type { StorageAdapterInterface } from "../../storage/StorageAdapterInterface.js";
-export declare function runStorageAdapterTests(_setup: SetupFn, title?: string): void;
+export declare function runStorageAdapterTests(setup: SetupFn, title?: string): void;
 export type SetupFn = () => Promise<{
     adapter: StorageAdapterInterface;
-    teardown?: () => void;
+    teardown?: () => void | Promise<void>;
 }>;
 //# sourceMappingURL=storage-adapter-tests.d.ts.map

package/dist/helpers/tests/storage-adapter-tests.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/storage-adapter-tests.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAQvF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA+K5E;AAID,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,OAAO,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;CACtB,CAAC,CAAA"}
+{"version":3,"file":"storage-adapter-tests.d.ts","sourceRoot":"","sources":["../../../src/helpers/tests/storage-adapter-tests.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0CAA0C,CAAA;AAcvF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA+H3E;AAID,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC;IAClC,OAAO,EAAE,uBAAuB,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACtC,CAAC,CAAA"}

package/dist/helpers/tests/storage-adapter-tests.js

@@ -1,107 +1,87 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, beforeEach, it as _it } from "vitest";
 const PAYLOAD_A = () => new Uint8Array([0, 1, 127, 99, 154, 235]);
 const PAYLOAD_B = () => new Uint8Array([1, 76, 160, 53, 57, 10, 230]);
 const PAYLOAD_C = () => new Uint8Array([2, 111, 74, 131, 236, 96, 142, 193]);
 const LARGE_PAYLOAD = new Uint8Array(100000).map(() => Math.random() * 256);
-export function runStorageAdapterTests(_setup, title) {
-    const setup = async () => {
-        const { adapter, teardown = NO_OP } = await _setup();
-        return { adapter, teardown };
-    };
+const it = (_it);
+export function runStorageAdapterTests(setup, title) {
+    beforeEach(async (ctx) => {
+        const { adapter, teardown = NO_OP } = await setup();
+        ctx.adapter = adapter;
+        return teardown;
+    });
     describe(`Storage adapter acceptance tests ${title ? `(${title})` : ""}`, () => {
         describe("load", () => {
-            it("should return undefined if there is no data", async () => {
-                const { adapter, teardown } = await setup();
+            it("should return undefined if there is no data", async ({ adapter }) => {
                 const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"]);
                 expect(actual).toBeUndefined();
-                teardown();
             });
         });
         describe("save and load", () => {
-            it("should return data that was saved", async () => {
-                const { adapter, teardown } = await setup();
+            it("should return data that was saved", async ({ adapter }) => {
                 await adapter.save(["storage-adapter-id"], PAYLOAD_A());
                 const actual = await adapter.load(["storage-adapter-id"]);
                 expect(actual).toStrictEqual(PAYLOAD_A());
-                teardown();
             });
-            it("should work with composite keys", async () => {
-                const { adapter, teardown } = await setup();
+            it("should work with composite keys", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"]);
                 expect(actual).toStrictEqual(PAYLOAD_A());
-                teardown();
             });
-            it("should work with a large payload", async () => {
-                const { adapter, teardown } = await setup();
+            it("should work with a large payload", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], LARGE_PAYLOAD);
                 const actual = await adapter.load(["AAAAA", "sync-state", "xxxxx"]);
                 expect(actual).toStrictEqual(LARGE_PAYLOAD);
-                teardown();
             });
         });
         describe("loadRange", () => {
-            it("should return an empty array if there is no data", async () => {
-                const { adapter, teardown } = await setup();
+            it("should return an empty array if there is no data", async ({ adapter, }) => {
                 expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([]);
-                teardown();
             });
         });
         describe("save and loadRange", () => {
-            it("should return all the data that matches the key", async () => {
-                const { adapter, teardown } = await setup();
+            it("should return all the data that matches the key", async ({ adapter, }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B());
                 await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C());
-                expect(await adapter.loadRange(["AAAAA"])).toStrictEqual(expect.arrayContaining([
+                expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
                     { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
                     { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
-                expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual(expect.arrayContaining([
+                ]);
+                expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
                     { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
-                teardown();
+                ]);
             });
-            it("should only load values that match they key", async () => {
-                const { adapter, teardown } = await setup();
+            it("should only load values that match they key", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_C());
                 const actual = await adapter.loadRange(["AAAAA"]);
-                expect(actual).toStrictEqual(expect.arrayContaining([
+                expect(actual).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-                ]));
-                expect(actual).toStrictEqual(expect.not.arrayContaining([
-                    { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-                ]));
-                teardown();
+                ]);
             });
         });
         describe("save and remove", () => {
-            it("after removing, should be empty", async () => {
-                const { adapter, teardown } = await setup();
+            it("after removing, should be empty", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "snapshot", "xxxxx"], PAYLOAD_A());
                 await adapter.remove(["AAAAA", "snapshot", "xxxxx"]);
                 expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([]);
                 expect(await adapter.load(["AAAAA", "snapshot", "xxxxx"])).toBeUndefined();
-                teardown();
             });
         });
         describe("save and save", () => {
-            it("should overwrite data saved with the same key", async () => {
-                const { adapter, teardown } = await setup();
+            it("should overwrite data saved with the same key", async ({ adapter, }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_B());
                 expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
                     { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_B() },
                 ]);
-                teardown();
             });
         });
         describe("removeRange", () => {
-            it("should remove a range of records", async () => {
-                const { adapter, teardown } = await setup();
+            it("should remove a range of records", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B());
                 await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C());
@@ -109,10 +89,8 @@ export function runStorageAdapterTests(_setup, title) {
                 expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
                     { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
                 ]);
-                teardown();
             });
-            it("should not remove records that don't match", async () => {
-                const { adapter, teardown } = await setup();
+            it("should not remove records that don't match", async ({ adapter }) => {
                 await adapter.save(["AAAAA", "sync-state", "xxxxx"], PAYLOAD_A());
                 await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_B());
                 await adapter.removeRange(["AAAAA"]);
@@ -120,7 +98,6 @@ export function runStorageAdapterTests(_setup, title) {
                 expect(actual).toStrictEqual([
                     { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_B() },
                 ]);
-                teardown();
             });
         });
     });

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * ```
  */
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, isValidDocumentId, parseAutomergeUrl, stringifyAutomergeUrl, interpretAsDocumentId, generateAutomergeUrl, } from "./AutomergeUrl.js";
+export { isValidAutomergeUrl, isValidDocumentId, parseAutomergeUrl, stringifyAutomergeUrl, interpretAsDocumentId, generateAutomergeUrl, encodeHeads, decodeHeads, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
 export type { NetworkAdapterInterface } from "./network/NetworkAdapterInterface.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAEnF,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,GACb,MAAM,sCAAsC,CAAA;AAE7C,YAAY,EACV,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,oBAAoB,CAAA;AAE3B,cAAc,YAAY,CAAA;AAG1B,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAA;AAGnE,YAAY,EACV,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAa,EACb,IAAI,EACJ,OAAO,EACP,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,SAAS,EACT,SAAS,EACT,MAAM,GACP,MAAM,gCAAgC,CAAA;AAIvC,OAAO,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,IAAI,EACJ,YAAY,GACb,MAAM,gCAAgC,CAAA;AAKvC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,MAAM,GACP,MAAM,gCAAgC,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,oBAAoB,EACpB,WAAW,EACX,WAAW,GACZ,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAA;AAEnF,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,2BAA2B,EAC3B,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AAEvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAElB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,YAAY,GACb,MAAM,sCAAsC,CAAA;AAE7C,YAAY,EACV,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,GACZ,MAAM,uBAAuB,CAAA;AAE9B,YAAY,EACV,KAAK,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,oBAAoB,CAAA;AAE3B,cAAc,YAAY,CAAA;AAG1B,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAA;AAGnE,YAAY,EACV,GAAG,EACH,KAAK,EACL,KAAK,EACL,aAAa,EACb,IAAI,EACJ,OAAO,EACP,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,OAAO,EACP,SAAS,EACT,SAAS,EACT,MAAM,GACP,MAAM,gCAAgC,CAAA;AAIvC,OAAO,EACL,UAAU,EACV,aAAa,EACb,YAAY,EACZ,IAAI,EACJ,YAAY,GACb,MAAM,gCAAgC,CAAA;AAKvC,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,MAAM,EACN,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,MAAM,GACP,MAAM,gCAAgC,CAAA"}

package/dist/index.js

@@ -26,7 +26,7 @@
  * ```
  */
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, isValidDocumentId, parseAutomergeUrl, stringifyAutomergeUrl, interpretAsDocumentId, generateAutomergeUrl, } from "./AutomergeUrl.js";
+export { isValidAutomergeUrl, isValidDocumentId, parseAutomergeUrl, stringifyAutomergeUrl, interpretAsDocumentId, generateAutomergeUrl, encodeHeads, decodeHeads, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
 export { isRepoMessage } from "./network/messages.js";

package/dist/storage/StorageSubsystem.d.ts

@@ -2,11 +2,20 @@ import * as A from "@automerge/automerge/slim/next";
 import { type DocumentId } from "../types.js";
 import { StorageAdapterInterface } from "./StorageAdapterInterface.js";
 import { StorageId } from "./types.js";
+import { EventEmitter } from "eventemitter3";
+type StorageSubsystemEvents = {
+    "document-loaded": (arg: {
+        documentId: DocumentId;
+        durationMillis: number;
+        numOps: number;
+        numChanges: number;
+    }) => void;
+};
 /**
  * The storage subsystem is responsible for saving and loading Automerge documents to and from
  * storage adapter. It also provides a generic key/value storage interface for other uses.
  */
-export declare class StorageSubsystem {
+export declare class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     #private;
     constructor(storageAdapter: StorageAdapterInterface);
     id(): Promise<StorageId>;
@@ -49,4 +58,5 @@ export declare class StorageSubsystem {
     loadSyncState(documentId: DocumentId, storageId: StorageId): Promise<A.SyncState | undefined>;
     saveSyncState(documentId: DocumentId, storageId: StorageId, syncState: A.SyncState): Promise<void>;
 }
+export {};
 //# sourceMappingURL=StorageSubsystem.d.ts.map

package/dist/storage/StorageSubsystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAK7D;;;GAGG;AACH,qBAAa,gBAAgB;;gBAef,cAAc,EAAE,uBAAuB;IAI7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAmClE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAazE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAM7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}
+{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAInD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IA0ClE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAczE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAkEhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}