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

package/dist/storage/StorageSubsystem.js

@@ -5,11 +5,13 @@ import { mergeArrays } from "../helpers/mergeArrays.js";
 import { keyHash, headsHash } from "./keyHash.js";
 import { chunkTypeFromKey } from "./chunkTypeFromKey.js";
 import * as Uuid from "uuid";
+import { EventEmitter } from "eventemitter3";
+import { encodeHeads } from "../AutomergeUrl.js";
 /**
  * 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 class StorageSubsystem {
+export class StorageSubsystem extends EventEmitter {
     /** The storage adapter to use for saving and loading documents */
     #storageAdapter;
     /** Record of the latest heads we've loaded or saved for each document  */
@@ -20,6 +22,7 @@ export class StorageSubsystem {
     #compacting = false;
     #log = debug(`automerge-repo:storage-subsystem`);
     constructor(storageAdapter) {
+        super();
         this.#storageAdapter = storageAdapter;
     }
     async id() {
@@ -100,7 +103,14 @@ export class StorageSubsystem {
         if (binary.length === 0)
             return null;
         // Load into an Automerge document
+        const start = performance.now();
         const newDoc = A.loadIncremental(A.init(), binary);
+        const end = performance.now();
+        this.emit("document-loaded", {
+            documentId,
+            durationMillis: end - start,
+            ...A.stats(newDoc),
+        });
         // Record the latest heads for the document
         this.#storedHeads.set(documentId, A.getHeads(newDoc));
         return newDoc;
@@ -178,8 +188,14 @@ export class StorageSubsystem {
     }
     async loadSyncState(documentId, storageId) {
         const key = [documentId, "sync-state", storageId];
-        const loaded = await this.#storageAdapter.load(key);
-        return loaded ? A.decodeSyncState(loaded) : undefined;
+        try {
+            const loaded = await this.#storageAdapter.load(key);
+            return loaded ? A.decodeSyncState(loaded) : undefined;
+        }
+        catch (e) {
+            this.#log(`Error loading sync state for ${documentId} from ${storageId}`);
+            return undefined;
+        }
     }
     async saveSyncState(documentId, storageId, syncState) {
         const key = [documentId, "sync-state", storageId];
@@ -195,7 +211,7 @@ export class StorageSubsystem {
             return true;
         }
         const newHeads = A.getHeads(doc);
-        if (headsAreSame(newHeads, oldHeads)) {
+        if (headsAreSame(encodeHeads(newHeads), encodeHeads(oldHeads))) {
             // the document hasn't changed
             return false;
         }

package/dist/synchronizer/CollectionSynchronizer.d.ts

@@ -1,12 +1,16 @@
 import { Repo } from "../Repo.js";
 import { DocMessage } from "../network/messages.js";
-import { DocumentId, PeerId } from "../types.js";
+import { AutomergeUrl, DocumentId, PeerId } from "../types.js";
+import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 /** A CollectionSynchronizer is responsible for synchronizing a DocCollection with peers. */
 export declare class CollectionSynchronizer extends Synchronizer {
     #private;
     private repo;
-    constructor(repo: Repo);
+    /** A map of documentIds to their synchronizers */
+    /** @hidden */
+    docSynchronizers: Record<DocumentId, DocSynchronizer>;
+    constructor(repo: Repo, denylist?: AutomergeUrl[]);
     /**
      * When we receive a sync message for a document we haven't got in memory, we
      * register it with the repo and start synchronizing
@@ -23,5 +27,14 @@ export declare class CollectionSynchronizer extends Synchronizer {
     removePeer(peerId: PeerId): void;
     /** Returns a list of all connected peer ids */
     get peers(): PeerId[];
+    metrics(): {
+        [key: string]: {
+            peers: PeerId[];
+            size: {
+                numOps: number;
+                numChanges: number;
+            };
+        };
+    };
 }
 //# sourceMappingURL=CollectionSynchronizer.d.ts.map

package/dist/synchronizer/CollectionSynchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAU1C,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE,IAAI;IAqD9B;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAyBxC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAalC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;CACF"}
+{"version":3,"file":"CollectionSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/CollectionSynchronizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD,4FAA4F;AAC5F,qBAAa,sBAAuB,SAAQ,YAAY;;IAa1C,OAAO,CAAC,IAAI;IATxB,kDAAkD;IAClD,cAAc;IACd,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAK;gBAOtC,IAAI,EAAE,IAAI,EAAE,QAAQ,GAAE,YAAY,EAAO;IAuD7D;;;OAGG;IACG,cAAc,CAAC,OAAO,EAAE,UAAU;IAsCxC;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,UAAU;IAalC,cAAc,CAAC,UAAU,EAAE,UAAU;IAIrC,2DAA2D;IAC3D,OAAO,CAAC,MAAM,EAAE,MAAM;IAgBtB,uDAAuD;IACvD,UAAU,CAAC,MAAM,EAAE,MAAM;IASzB,+CAA+C;IAC/C,IAAI,KAAK,IAAI,MAAM,EAAE,CAEpB;IAED,OAAO,IAAI;QACT,CAAC,GAAG,EAAE,MAAM,GAAG;YACb,KAAK,EAAE,MAAM,EAAE,CAAA;YACf,IAAI,EAAE;gBAAE,MAAM,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAA;SAC7C,CAAA;KACF;CASF"}

package/dist/synchronizer/CollectionSynchronizer.js

@@ -1,5 +1,5 @@
 import debug from "debug";
-import { stringifyAutomergeUrl } from "../AutomergeUrl.js";
+import { parseAutomergeUrl, stringifyAutomergeUrl } from "../AutomergeUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 const log = debug("automerge-repo:collectionsync");
@@ -9,20 +9,23 @@ export class CollectionSynchronizer extends Synchronizer {
     /** The set of peers we are connected with */
     #peers = new Set();
     /** A map of documentIds to their synchronizers */
-    #docSynchronizers = {};
+    /** @hidden */
+    docSynchronizers = {};
     /** Used to determine if the document is know to the Collection and a synchronizer exists or is being set up */
     #docSetUp = {};
-    constructor(repo) {
+    #denylist;
+    constructor(repo, denylist = []) {
         super();
         this.repo = repo;
+        this.#denylist = denylist.map(url => parseAutomergeUrl(url).documentId);
     }
     /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
     #fetchDocSynchronizer(documentId) {
-        if (!this.#docSynchronizers[documentId]) {
+        if (!this.docSynchronizers[documentId]) {
             const handle = this.repo.find(stringifyAutomergeUrl({ documentId }));
-            this.#docSynchronizers[documentId] = this.#initDocSynchronizer(handle);
+            this.docSynchronizers[documentId] = this.#initDocSynchronizer(handle);
         }
-        return this.#docSynchronizers[documentId];
+        return this.docSynchronizers[documentId];
     }
     /** Creates a new docSynchronizer and sets it up to propagate messages */
     #initDocSynchronizer(handle) {
@@ -42,6 +45,7 @@ export class CollectionSynchronizer extends Synchronizer {
         docSynchronizer.on("message", event => this.emit("message", event));
         docSynchronizer.on("open-doc", event => this.emit("open-doc", event));
         docSynchronizer.on("sync-state", event => this.emit("sync-state", event));
+        docSynchronizer.on("metrics", event => this.emit("metrics", event));
         return docSynchronizer;
     }
     /** returns an array of peerIds that we share this document generously with */
@@ -66,6 +70,18 @@ export class CollectionSynchronizer extends Synchronizer {
         if (!documentId) {
             throw new Error("received a message with an invalid documentId");
         }
+        if (this.#denylist.includes(documentId)) {
+            this.emit("metrics", {
+                type: "doc-denied",
+                documentId,
+            });
+            this.emit("message", {
+                type: "doc-unavailable",
+                documentId,
+                targetId: message.senderId,
+            });
+            return;
+        }
         this.#docSetUp[documentId] = true;
         const docSynchronizer = this.#fetchDocSynchronizer(documentId);
         docSynchronizer.receiveMessage(message);
@@ -98,7 +114,7 @@ export class CollectionSynchronizer extends Synchronizer {
             return;
         }
         this.#peers.add(peerId);
-        for (const docSynchronizer of Object.values(this.#docSynchronizers)) {
+        for (const docSynchronizer of Object.values(this.docSynchronizers)) {
             const { documentId } = docSynchronizer;
             void this.repo.sharePolicy(peerId, documentId).then(okToShare => {
                 if (okToShare)
@@ -110,7 +126,7 @@ export class CollectionSynchronizer extends Synchronizer {
     removePeer(peerId) {
         log(`removing peer ${peerId}`);
         this.#peers.delete(peerId);
-        for (const docSynchronizer of Object.values(this.#docSynchronizers)) {
+        for (const docSynchronizer of Object.values(this.docSynchronizers)) {
             docSynchronizer.endSync(peerId);
         }
     }
@@ -118,4 +134,9 @@ export class CollectionSynchronizer extends Synchronizer {
     get peers() {
         return Array.from(this.#peers);
     }
+    metrics() {
+        return Object.fromEntries(Object.entries(this.docSynchronizers).map(([documentId, synchronizer]) => {
+            return [documentId, synchronizer.metrics()];
+        }));
+    }
 }

package/dist/synchronizer/DocSynchronizer.d.ts

@@ -24,6 +24,13 @@ export declare class DocSynchronizer extends Synchronizer {
     receiveMessage(message: RepoMessage): void;
     receiveEphemeralMessage(message: EphemeralMessage): void;
     receiveSyncMessage(message: SyncMessage | RequestMessage): void;
+    metrics(): {
+        peers: PeerId[];
+        size: {
+            numOps: number;
+            numChanges: number;
+        };
+    };
 }
 export {};
 //# sourceMappingURL=DocSynchronizer.d.ts.map

package/dist/synchronizer/DocSynchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAsBV,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IAyB9D,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAkID,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAmD3B,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;CA8EzD"}
+{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,gCAAgC,CAAA;AAGnD,OAAO,EACL,SAAS,EAKV,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAEL,gBAAgB,EAEhB,WAAW,EACX,cAAc,EACd,WAAW,EAEZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGhD,KAAK,kBAAkB,GAAG,SAAS,GAAG,KAAK,GAAG,aAAa,GAAG,OAAO,CAAA;AAOrE,UAAU,qBAAqB;IAC7B,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAC1B,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAA;CACvE;AAED;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAE/C,gBAAgB,SAAM;gBAsBV,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,qBAAqB;IAyB9D,IAAI,UAAU,uCAEb;IAED,IAAI,UAAU,qCAEb;IAkID,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE;IAmD3B,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,cAAc,CAAC,OAAO,EAAE,WAAW;IAkBnC,uBAAuB,CAAC,OAAO,EAAE,gBAAgB;IAuBjD,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc;IAuFxD,OAAO,IAAI;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAM7E"}

package/dist/synchronizer/DocSynchronizer.js

@@ -252,7 +252,15 @@ export class DocSynchronizer extends Synchronizer {
         }
         this.#withSyncState(message.senderId, syncState => {
             this.#handle.update(doc => {
+                const start = performance.now();
                 const [newDoc, newSyncState] = A.receiveSyncMessage(doc, syncState, message.data);
+                const end = performance.now();
+                this.emit("metrics", {
+                    type: "receive-sync-message",
+                    documentId: this.#handle.documentId,
+                    durationMillis: end - start,
+                    ...A.stats(doc),
+                });
                 this.#setSyncState(message.senderId, newSyncState);
                 // respond to just this peer (as required)
                 this.#sendSyncMessage(message.senderId, doc);
@@ -286,4 +294,10 @@ export class DocSynchronizer extends Synchronizer {
         }
         this.#pendingSyncMessages = [];
     }
+    metrics() {
+        return {
+            peers: this.#peers,
+            size: this.#handle.metrics(),
+        };
+    }
 }

package/dist/synchronizer/Synchronizer.d.ts

@@ -9,6 +9,7 @@ export interface SynchronizerEvents {
     message: (payload: MessageContents) => void;
     "sync-state": (payload: SyncStatePayload) => void;
     "open-doc": (arg: OpenDocMessage) => void;
+    metrics: (arg: DocSyncMetrics) => void;
 }
 /** Notify the repo that the sync state has changed  */
 export interface SyncStatePayload {
@@ -16,4 +17,14 @@ export interface SyncStatePayload {
     documentId: DocumentId;
     syncState: SyncState;
 }
+export type DocSyncMetrics = {
+    type: "receive-sync-message";
+    documentId: DocumentId;
+    durationMillis: number;
+    numOps: number;
+    numChanges: number;
+} | {
+    type: "doc-denied";
+    documentId: DocumentId;
+};
 //# sourceMappingURL=Synchronizer.d.ts.map

package/dist/synchronizer/Synchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACjD,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CAC1C;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;CACrB"}
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,WAAW,EACZ,MAAM,wBAAwB,CAAA;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEhD,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAA;IAC3C,YAAY,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAA;IACjD,UAAU,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;IACzC,OAAO,EAAE,CAAC,GAAG,EAAE,cAAc,KAAK,IAAI,CAAA;CACvC;AAED,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,sBAAsB,CAAA;IAC5B,UAAU,EAAE,UAAU,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB,GACD;IACE,IAAI,EAAE,YAAY,CAAA;IAClB,UAAU,EAAE,UAAU,CAAA;CACvB,CAAA"}

package/dist/types.d.ts

@@ -26,12 +26,15 @@ export type LegacyDocumentId = string & {
     __legacyDocumentId: true;
 };
 export type AnyDocumentId = AutomergeUrl | DocumentId | BinaryDocumentId | LegacyDocumentId;
+export type UrlHeads = string[] & {
+    __automergeUrlHeads: unknown;
+};
 /** A branded type for peer IDs */
 export type PeerId = string & {
     __peerId: true;
 };
 /** A randomly generated string created when the {@link Repo} starts up */
 export type SessionId = string & {
-    __SessionId: true;
+    __sessionId: true;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAExD,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,gBAAgB,CAAA;AAEpB,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhD,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAExD,iGAAiG;AACjG,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAEpE,MAAM,MAAM,aAAa,GACrB,YAAY,GACZ,UAAU,GACV,gBAAgB,GAChB,gBAAgB,CAAA;AAGpB,MAAM,MAAM,QAAQ,GAAG,MAAM,EAAE,GAAG;IAAE,mBAAmB,EAAE,OAAO,CAAA;CAAE,CAAA;AAElE,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAA;AAEhD,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.20",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -23,7 +23,7 @@
     "vite": "^5.0.8"
   },
   "dependencies": {
-    "@automerge/automerge": "^2.2.7",
+    "@automerge/automerge": "^2.2.8",
     "bs58check": "^3.0.1",
     "cbor-x": "^1.3.0",
     "debug": "^4.3.4",
@@ -60,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "373ce97a1c3153b476926290942e8a55cde7874b"
+  "gitHead": "d53bc37be0fd923ff40f3cf7e2bd06a0496ddb73"
 }

package/src/AutomergeUrl.ts

@@ -4,26 +4,54 @@ import type {
   BinaryDocumentId,
   DocumentId,
   AnyDocumentId,
+  UrlHeads,
 } from "./types.js"
+
 import * as Uuid from "uuid"
 import bs58check from "bs58check"
+import {
+  uint8ArrayFromHexString,
+  uint8ArrayToHexString,
+} from "./helpers/bufferFromHex.js"
+
+import type { Heads as AutomergeHeads } from "@automerge/automerge/slim"
 
 export const urlPrefix = "automerge:"
 
+interface ParsedAutomergeUrl {
+  /** unencoded DocumentId */
+  binaryDocumentId: BinaryDocumentId
+  /** bs58 encoded DocumentId */
+  documentId: DocumentId
+  /** Optional array of heads, if specified in URL */
+  heads?: UrlHeads
+  /** Optional hex array of heads, in Automerge core format */
+  hexHeads?: string[] // AKA: heads
+}
+
 /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
-export const parseAutomergeUrl = (url: AutomergeUrl) => {
+export const parseAutomergeUrl = (url: AutomergeUrl): ParsedAutomergeUrl => {
+  const [baseUrl, headsSection, ...rest] = url.split("#")
+  if (rest.length > 0) {
+    throw new Error("Invalid URL: contains multiple heads sections")
+  }
   const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [, docMatch] = url.match(regex) || []
+  const [, docMatch] = baseUrl.match(regex) || []
   const documentId = docMatch as DocumentId
   const binaryDocumentId = documentIdToBinary(documentId)
 
   if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
-  return {
-    /** unencoded DocumentId */
-    binaryDocumentId,
-    /** encoded DocumentId */
-    documentId,
-  }
+  if (headsSection === undefined) return { binaryDocumentId, documentId }
+
+  const heads = (headsSection === "" ? [] : headsSection.split("|")) as UrlHeads
+  const hexHeads = heads.map(head => {
+    try {
+      return uint8ArrayToHexString(bs58check.decode(head))
+    } catch (e) {
+      throw new Error(`Invalid head in URL: ${head}`)
+    }
+  })
+  return { binaryDocumentId, hexHeads, documentId, heads }
 }
 
 /**
@@ -32,38 +60,78 @@ export const parseAutomergeUrl = (url: AutomergeUrl) => {
  */
 export const stringifyAutomergeUrl = (
   arg: UrlOptions | DocumentId | BinaryDocumentId
-) => {
-  const documentId =
-    arg instanceof Uint8Array || typeof arg === "string"
-      ? arg
-      : "documentId" in arg
-      ? arg.documentId
-      : undefined
+): AutomergeUrl => {
+  if (arg instanceof Uint8Array || typeof arg === "string") {
+    return (urlPrefix +
+      (arg instanceof Uint8Array
+        ? binaryToDocumentId(arg)
+        : arg)) as AutomergeUrl
+  }
+
+  const { documentId, heads = undefined } = arg
+
+  if (documentId === undefined)
+    throw new Error("Invalid documentId: " + documentId)
 
   const encodedDocumentId =
     documentId instanceof Uint8Array
       ? binaryToDocumentId(documentId)
-      : typeof documentId === "string"
-      ? documentId
-      : undefined
+      : documentId
+
+  let url = `${urlPrefix}${encodedDocumentId}`
+
+  if (heads !== undefined) {
+    heads.forEach(head => {
+      try {
+        bs58check.decode(head)
+      } catch (e) {
+        throw new Error(`Invalid head: ${head}`)
+      }
+    })
+    url += "#" + heads.join("|")
+  }
 
-  if (encodedDocumentId === undefined)
-    throw new Error("Invalid documentId: " + documentId)
+  return url as AutomergeUrl
+}
 
-  return (urlPrefix + encodedDocumentId) as AutomergeUrl
+/** Helper to extract just the heads from a URL if they exist */
+export const getHeadsFromUrl = (url: AutomergeUrl): string[] | undefined => {
+  const { heads } = parseAutomergeUrl(url)
+  return heads
 }
 
+export const anyDocumentIdToAutomergeUrl = (id: AnyDocumentId) =>
+  isValidAutomergeUrl(id)
+    ? id
+    : isValidDocumentId(id)
+    ? stringifyAutomergeUrl({ documentId: id })
+    : isValidUuid(id)
+    ? parseLegacyUUID(id)
+    : undefined
+
 /**
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
  * discriminator in Typescript.
  */
 export const isValidAutomergeUrl = (str: unknown): str is AutomergeUrl => {
-  if (typeof str !== "string") return false
-  if (!str || !str.startsWith(urlPrefix)) return false
-  const automergeUrl = str as AutomergeUrl
+  if (typeof str !== "string" || !str || !str.startsWith(urlPrefix))
+    return false
   try {
-    const { documentId } = parseAutomergeUrl(automergeUrl)
-    return isValidDocumentId(documentId)
+    const { documentId, heads } = parseAutomergeUrl(str as AutomergeUrl)
+    if (!isValidDocumentId(documentId)) return false
+    if (
+      heads &&
+      !heads.every(head => {
+        try {
+          bs58check.decode(head)
+          return true
+        } catch {
+          return false
+        }
+      })
+    )
+      return false
+    return true
   } catch {
     return false
   }
@@ -97,6 +165,12 @@ export const documentIdToBinary = (docId: DocumentId) =>
 export const binaryToDocumentId = (docId: BinaryDocumentId) =>
   bs58check.encode(docId) as DocumentId
 
+export const encodeHeads = (heads: AutomergeHeads): UrlHeads =>
+  heads.map(h => bs58check.encode(uint8ArrayFromHexString(h))) as UrlHeads
+
+export const decodeHeads = (heads: UrlHeads): AutomergeHeads =>
+  heads.map(h => uint8ArrayToHexString(bs58check.decode(h))) as AutomergeHeads
+
 export const parseLegacyUUID = (str: string) => {
   if (!Uuid.validate(str)) return undefined
   const documentId = Uuid.parse(str) as BinaryDocumentId
@@ -141,4 +215,5 @@ export const interpretAsDocumentId = (id: AnyDocumentId) => {
 
 type UrlOptions = {
   documentId: DocumentId | BinaryDocumentId
+  heads?: UrlHeads
 }