@automerge/automerge-repo 2.0.0-alpha.14 → 2.0.0-alpha.16

package/dist/Repo.js

@@ -1,7 +1,7 @@
 import { next as Automerge } from "@automerge/automerge/slim";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
-import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
+import { 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";
@@ -119,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));
                 }
             }
         });
@@ -305,18 +306,21 @@ 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({
@@ -345,7 +349,8 @@ export class Repo extends EventEmitter {
             .catch(err => {
             this.#log("error waiting for network", { err });
         });
-        return handle;
+        // 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 */

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 { UrlHeads } from "../AutomergeUrl.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,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAE7C,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.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;AAcvF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CA0I3E;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"}
+{"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

@@ -44,26 +44,23 @@ export function runStorageAdapterTests(setup, title) {
                 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() },
-                ]));
+                ]);
             });
             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() },
-                ]));
+                ]);
             });
         });
         describe("save and remove", () => {

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;AAI7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,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;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;IAW7B,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"}

package/dist/storage/StorageSubsystem.js

@@ -6,6 +6,7 @@ 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.
@@ -210,7 +211,7 @@ export class StorageSubsystem extends EventEmitter {
             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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.14",
+  "version": "2.0.0-alpha.16",
   "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>",
@@ -60,5 +60,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "3048251989fc0cdbf605f534e48750f0c681004a"
+  "gitHead": "04e79be28aca7dc566ced3b2c32e05ca5d37ce69"
 }

package/src/AutomergeUrl.ts

@@ -5,25 +5,55 @@ import type {
   DocumentId,
   AnyDocumentId,
 } 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:"
 
+// We need to define our own version of heads because the AutomergeHeads type is not bs58check encoded
+export type UrlHeads = string[] & { __automergeUrlHeadsBrand: unknown }
+
+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 +62,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 +167,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 +217,5 @@ export const interpretAsDocumentId = (id: AnyDocumentId) => {
 
 type UrlOptions = {
   documentId: DocumentId | BinaryDocumentId
+  heads?: UrlHeads
 }