@automerge/automerge-repo 1.0.12 → 1.0.13

package/dist/AutomergeUrl.d.ts

@@ -0,0 +1,45 @@
+import type { LegacyDocumentId, AutomergeUrl, BinaryDocumentId, DocumentId, AnyDocumentId } from "./types.js";
+export declare const urlPrefix = "automerge:";
+/** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
+export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
+    /** unencoded DocumentId */
+    binaryDocumentId: BinaryDocumentId;
+    /** encoded DocumentId */
+    documentId: DocumentId;
+};
+/**
+ * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
+ * Throws on invalid input.
+ */
+export declare const stringifyAutomergeUrl: (arg: UrlOptions | DocumentId | BinaryDocumentId) => AutomergeUrl;
+/**
+ * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
+ * discriminator in Typescript.
+ */
+export declare const isValidAutomergeUrl: (str: string | undefined | null) => str is AutomergeUrl;
+export declare const isValidDocumentId: (str: string) => str is DocumentId;
+export declare const isValidUuid: (str: string) => str is LegacyDocumentId;
+/**
+ * Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.
+ */
+export declare const generateAutomergeUrl: () => AutomergeUrl;
+export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
+export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
+export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
+/**
+ * Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
+ *
+ * Currently supports:
+ * - base58check-encoded DocumentId
+ * - Automerge URL
+ * - legacy UUID
+ * - binary DocumentId
+ *
+ * Throws on invalid input.
+ */
+export declare const interpretAsDocumentId: (id: AnyDocumentId) => DocumentId;
+type UrlOptions = {
+    documentId: DocumentId | BinaryDocumentId;
+};
+export {};
+//# sourceMappingURL=AutomergeUrl.d.ts.map

package/dist/AutomergeUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AutomergeUrl.d.ts","sourceRoot":"","sources":["../src/AutomergeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,QAAS,YAAY;IAQ/C,2BAA2B;;IAE3B,yBAAyB;;CAG5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAC3B,UAAU,GAAG,UAAU,GAAG,gBAAgB,iBAoBhD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACzB,MAAM,GAAG,SAAS,GAAG,IAAI,wBAU/B,CAAA;AAED,eAAO,MAAM,iBAAiB,QAAS,MAAM,sBAQ5C,CAAA;AAED,eAAO,MAAM,WAAW,QAAS,MAAM,4BACnB,CAAA;AAEpB;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGvC,CAAA;AAED,eAAO,MAAM,kBAAkB,UAAW,UAAU,iCACW,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,eACnB,CAAA;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,6BAI1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,OAAQ,aAAa,eAqBtD,CAAA;AAID,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;CAC1C,CAAA"}

package/dist/AutomergeUrl.js

@@ -0,0 +1,108 @@
+import * as Uuid from "uuid";
+import bs58check from "bs58check";
+export const urlPrefix = "automerge:";
+/** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
+export const parseAutomergeUrl = (url) => {
+    const regex = new RegExp(`^${urlPrefix}(\\w+)$`);
+    const [_, docMatch] = url.match(regex) || [];
+    const documentId = docMatch;
+    const binaryDocumentId = documentIdToBinary(documentId);
+    if (!binaryDocumentId)
+        throw new Error("Invalid document URL: " + url);
+    return {
+        /** unencoded DocumentId */
+        binaryDocumentId,
+        /** encoded DocumentId */
+        documentId,
+    };
+};
+/**
+ * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
+ * Throws on invalid input.
+ */
+export const stringifyAutomergeUrl = (arg) => {
+    let documentId = arg instanceof Uint8Array || typeof arg === "string"
+        ? arg
+        : "documentId" in arg
+            ? arg.documentId
+            : undefined;
+    const encodedDocumentId = documentId instanceof Uint8Array
+        ? binaryToDocumentId(documentId)
+        : typeof documentId === "string"
+            ? documentId
+            : undefined;
+    if (encodedDocumentId === undefined)
+        throw new Error("Invalid documentId: " + documentId);
+    return (urlPrefix + encodedDocumentId);
+};
+/**
+ * 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) => {
+    if (!str || !str.startsWith(urlPrefix))
+        return false;
+    const automergeUrl = str;
+    try {
+        const { documentId } = parseAutomergeUrl(automergeUrl);
+        return isValidDocumentId(documentId);
+    }
+    catch {
+        return false;
+    }
+};
+export const isValidDocumentId = (str) => {
+    // try to decode from base58
+    const binaryDocumentID = documentIdToBinary(str);
+    if (binaryDocumentID === undefined)
+        return false; // invalid base58check encoding
+    // confirm that the document ID is a valid UUID
+    const documentId = Uuid.stringify(binaryDocumentID);
+    return Uuid.validate(documentId);
+};
+export const isValidUuid = (str) => Uuid.validate(str);
+/**
+ * Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.
+ */
+export const generateAutomergeUrl = () => {
+    const documentId = Uuid.v4(null, new Uint8Array(16));
+    return stringifyAutomergeUrl({ documentId });
+};
+export const documentIdToBinary = (docId) => bs58check.decodeUnsafe(docId);
+export const binaryToDocumentId = (docId) => bs58check.encode(docId);
+export const parseLegacyUUID = (str) => {
+    if (!Uuid.validate(str))
+        return undefined;
+    const documentId = Uuid.parse(str);
+    return stringifyAutomergeUrl({ documentId });
+};
+/**
+ * Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
+ *
+ * Currently supports:
+ * - base58check-encoded DocumentId
+ * - Automerge URL
+ * - legacy UUID
+ * - binary DocumentId
+ *
+ * Throws on invalid input.
+ */
+export const interpretAsDocumentId = (id) => {
+    // binary
+    if (id instanceof Uint8Array)
+        return binaryToDocumentId(id);
+    // url
+    if (isValidAutomergeUrl(id))
+        return parseAutomergeUrl(id).documentId;
+    // base58check
+    if (isValidDocumentId(id))
+        return id;
+    // legacy UUID
+    if (isValidUuid(id)) {
+        console.warn("Future versions will not support UUIDs as document IDs; use Automerge URLs instead.");
+        const binaryDocumentID = Uuid.parse(id);
+        return binaryToDocumentId(binaryDocumentID);
+    }
+    // none of the above
+    throw new Error(`Invalid AutomergeUrl: '${id}'`);
+};

package/dist/DocHandle.js

@@ -3,7 +3,7 @@ import debug from "debug";
 import { EventEmitter } from "eventemitter3";
 import { assign, createMachine, interpret, } from "xstate";
 import { waitFor } from "xstate/lib/waitFor.js";
-import { stringifyAutomergeUrl } from "./DocUrl.js";
+import { stringifyAutomergeUrl } from "./AutomergeUrl.js";
 import { encode } from "./helpers/cbor.js";
 import { headsAreSame } from "./helpers/headsAreSame.js";
 import { withTimeout } from "./helpers/withTimeout.js";

package/dist/Repo.d.ts

@@ -4,7 +4,7 @@ import { NetworkAdapter } from "./network/NetworkAdapter.js";
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageAdapter } from "./storage/StorageAdapter.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
-import { DocumentId, PeerId, type AutomergeUrl } from "./types.js";
+import type { AnyDocumentId, DocumentId, PeerId } from "./types.js";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
  *
@@ -55,11 +55,11 @@ export declare class Repo extends EventEmitter<RepoEvents> {
      * event to advertise interest in the document.
      */
     find<T>(
-    /** The documentId of the handle to retrieve */
-    automergeUrl: AutomergeUrl): DocHandle<T>;
+    /** The url or documentId of the handle to retrieve */
+    id: AnyDocumentId): DocHandle<T>;
     delete(
-    /** The documentId of the handle to delete */
-    id: DocumentId | AutomergeUrl): void;
+    /** The url or documentId of the handle to delete */
+    id: AnyDocumentId): void;
 }
 export interface RepoConfig {
     /** Our unique identifier */

package/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAiC,MAAM,gBAAgB,CAAA;AAQzE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAElE,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC,mDAAmD;IACnD,cAAc;IACd,gBAAgB,SAAM;IAItB,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IA8HjE,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IA0BzB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAuBnC;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,+CAA+C;IAC/C,YAAY,EAAE,YAAY,GACzB,SAAS,CAAC,CAAC,CAAC;IAgCf,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAUhC;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAM5C,OAAO,EAAE,SAAS,EAAiC,MAAM,gBAAgB,CAAA;AAEzE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEnE,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC,mDAAmD;IACnD,cAAc;IACd,gBAAgB,SAAM;IAItB,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IA8HjE,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IA0BzB;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAuBnC;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,sDAAsD;IACtD,EAAE,EAAE,aAAa,GAChB,SAAS,CAAC,CAAC,CAAC;IAqBf,MAAM;IACJ,oDAAoD;IACpD,EAAE,EAAE,aAAa;CAUpB;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}

package/dist/Repo.js

@@ -1,8 +1,8 @@
 import { next as Automerge } from "@automerge/automerge";
 import debug from "debug";
 import { EventEmitter } from "eventemitter3";
+import { generateAutomergeUrl, interpretAsDocumentId, parseAutomergeUrl, } from "./AutomergeUrl.js";
 import { DocHandle } from "./DocHandle.js";
-import { generateAutomergeUrl, isValidAutomergeUrl, parseAutomergeUrl, parseLegacyUUID, } from "./DocUrl.js";
 import { throttle } from "./helpers/throttle.js";
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
@@ -198,19 +198,9 @@ export class Repo extends EventEmitter {
      * event to advertise interest in the document.
      */
     find(
-    /** The documentId of the handle to retrieve */
-    automergeUrl) {
-        if (!isValidAutomergeUrl(automergeUrl)) {
-            const maybeAutomergeUrl = parseLegacyUUID(automergeUrl);
-            if (maybeAutomergeUrl) {
-                console.warn("Legacy UUID document ID detected, converting to AutomergeUrl. This will be removed in a future version.");
-                automergeUrl = maybeAutomergeUrl;
-            }
-            else {
-                throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`);
-            }
-        }
-        const { documentId } = parseAutomergeUrl(automergeUrl);
+    /** 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()) {
@@ -228,13 +218,12 @@ export class Repo extends EventEmitter {
         return handle;
     }
     delete(
-    /** The documentId of the handle to delete */
+    /** The url or documentId of the handle to delete */
     id) {
-        if (isValidAutomergeUrl(id))
-            id = parseAutomergeUrl(id).documentId;
-        const handle = this.#getHandle(id, false);
+        const documentId = interpretAsDocumentId(id);
+        const handle = this.#getHandle(documentId, false);
         handle.delete();
-        delete this.#handleCache[id];
-        this.emit("delete-document", { documentId: id });
+        delete this.#handleCache[documentId];
+        this.emit("delete-document", { documentId });
     }
 }

package/dist/index.d.ts

@@ -26,7 +26,7 @@
  * ```
  */
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./DocUrl.js";
+export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
 export { isValidRepoMessage } from "./network/messages.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,qBAAqB,GACtB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAE5D,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAClB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAC7D,cAAc,YAAY,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,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAE5D,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AAIzC,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,6BAA6B,EAC7B,gCAAgC,EAChC,eAAe,EACf,gBAAgB,EAChB,wCAAwC,EACxC,WAAW,GACZ,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,qBAAqB,EACrB,eAAe,EACf,UAAU,EACV,UAAU,EACV,WAAW,GACZ,MAAM,WAAW,CAAA;AAClB,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AACpC,YAAY,EACV,aAAa,EACb,0BAA0B,EAC1B,gBAAgB,EAChB,OAAO,EACP,WAAW,EACX,cAAc,EACd,WAAW,EACX,cAAc,GACf,MAAM,uBAAuB,CAAA;AAC9B,YAAY,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAC7D,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -26,7 +26,7 @@
  * ```
  */
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./DocUrl.js";
+export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
 export { isValidRepoMessage } from "./network/messages.js";

package/dist/synchronizer/CollectionSynchronizer.js

@@ -1,5 +1,5 @@
 import debug from "debug";
-import { stringifyAutomergeUrl } from "../DocUrl.js";
+import { stringifyAutomergeUrl } from "../AutomergeUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 const log = debug("automerge-repo:collectionsync");

package/dist/types.d.ts

@@ -1,23 +1,31 @@
-/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
- */
-export type DocumentId = string & {
-    __documentId: true;
-};
-/** A branded string representing a URL for a document
- *
- * @remarks
- * An automerge URL has the form `automerge:<base58 encoded string>`. This
- * type is returned from various routines which validate a url.
- *
+/**
+ * A branded string representing a URL for a document, in the form `automerge:<base58check encoded
+ * string>`; for example, `automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu`.
  */
 export type AutomergeUrl = string & {
     __documentUrl: true;
 };
-/** A document ID as a Uint8Array instead of a bas58 encoded string. Typically you should use a {@link AutomergeUrl} instead.
+/**
+ * The base58check-encoded UUID of a document. This is the string following the `automerge:`
+ * protocol prefix in an AutomergeUrl; for example, `4NMNnkMhL8jXrdJ9jamS58PAVdXu`. When recording
+ * links to an Automerge document in another Automerge document, you should store a
+ * {@link AutomergeUrl} instead.
  */
+export type DocumentId = string & {
+    __documentId: true;
+};
+/** The unencoded UUID of a document. Typically you should use a {@link AutomergeUrl} instead. */
 export type BinaryDocumentId = Uint8Array & {
     __binaryDocumentId: true;
 };
+/**
+ * A UUID encoded as a hex string. As of v1.0, a {@link DocumentID} is stored as a base58-encoded string with a checksum.
+ * Support for this format will be removed in a future version.
+ */
+export type LegacyDocumentId = string & {
+    __legacyDocumentId: true;
+};
+export type AnyDocumentId = AutomergeUrl | DocumentId | BinaryDocumentId | LegacyDocumentId;
 /** A branded type for peer IDs */
 export type PeerId = string & {
     __peerId: true;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;GACG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAE3D;GACG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE,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;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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "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>",
@@ -57,5 +57,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "254bad1c774fa2a881265aaad5283af231bf72eb"
+  "gitHead": "48ca7b968758d7fd95f13fa03dc69d452cdd15f5"
 }

package/src/AutomergeUrl.ts

@@ -0,0 +1,144 @@
+import type {
+  LegacyDocumentId,
+  AutomergeUrl,
+  BinaryDocumentId,
+  DocumentId,
+  AnyDocumentId,
+} from "./types.js"
+import * as Uuid from "uuid"
+import bs58check from "bs58check"
+
+export const urlPrefix = "automerge:"
+
+/** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
+export const parseAutomergeUrl = (url: AutomergeUrl) => {
+  const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
+  const [_, docMatch] = url.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,
+  }
+}
+
+/**
+ * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
+ * Throws on invalid input.
+ */
+export const stringifyAutomergeUrl = (
+  arg: UrlOptions | DocumentId | BinaryDocumentId
+) => {
+  let documentId =
+    arg instanceof Uint8Array || typeof arg === "string"
+      ? arg
+      : "documentId" in arg
+      ? arg.documentId
+      : undefined
+
+  const encodedDocumentId =
+    documentId instanceof Uint8Array
+      ? binaryToDocumentId(documentId)
+      : typeof documentId === "string"
+      ? documentId
+      : undefined
+
+  if (encodedDocumentId === undefined)
+    throw new Error("Invalid documentId: " + documentId)
+
+  return (urlPrefix + encodedDocumentId) as AutomergeUrl
+}
+
+/**
+ * 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: string | undefined | null
+): str is AutomergeUrl => {
+  if (!str || !str.startsWith(urlPrefix)) return false
+  const automergeUrl = str as AutomergeUrl
+  try {
+    const { documentId } = parseAutomergeUrl(automergeUrl)
+    return isValidDocumentId(documentId)
+  } catch {
+    return false
+  }
+}
+
+export const isValidDocumentId = (str: string): str is DocumentId => {
+  // try to decode from base58
+  const binaryDocumentID = documentIdToBinary(str as DocumentId)
+  if (binaryDocumentID === undefined) return false // invalid base58check encoding
+
+  // confirm that the document ID is a valid UUID
+  const documentId = Uuid.stringify(binaryDocumentID)
+  return Uuid.validate(documentId)
+}
+
+export const isValidUuid = (str: string): str is LegacyDocumentId =>
+  Uuid.validate(str)
+
+/**
+ * Returns a new Automerge URL with a random UUID documentId. Called by Repo.create(), and also used by tests.
+ */
+export const generateAutomergeUrl = (): AutomergeUrl => {
+  const documentId = Uuid.v4(null, new Uint8Array(16)) as BinaryDocumentId
+  return stringifyAutomergeUrl({ documentId })
+}
+
+export const documentIdToBinary = (docId: DocumentId) =>
+  bs58check.decodeUnsafe(docId) as BinaryDocumentId | undefined
+
+export const binaryToDocumentId = (docId: BinaryDocumentId) =>
+  bs58check.encode(docId) as DocumentId
+
+export const parseLegacyUUID = (str: string) => {
+  if (!Uuid.validate(str)) return undefined
+  const documentId = Uuid.parse(str) as BinaryDocumentId
+  return stringifyAutomergeUrl({ documentId })
+}
+
+/**
+ * Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
+ *
+ * Currently supports:
+ * - base58check-encoded DocumentId
+ * - Automerge URL
+ * - legacy UUID
+ * - binary DocumentId
+ *
+ * Throws on invalid input.
+ */
+export const interpretAsDocumentId = (id: AnyDocumentId) => {
+  // binary
+  if (id instanceof Uint8Array) return binaryToDocumentId(id)
+
+  // url
+  if (isValidAutomergeUrl(id)) return parseAutomergeUrl(id).documentId
+
+  // base58check
+  if (isValidDocumentId(id)) return id
+
+  // legacy UUID
+  if (isValidUuid(id)) {
+    console.warn(
+      "Future versions will not support UUIDs as document IDs; use Automerge URLs instead."
+    )
+    const binaryDocumentID = Uuid.parse(id) as BinaryDocumentId
+    return binaryToDocumentId(binaryDocumentID)
+  }
+
+  // none of the above
+  throw new Error(`Invalid AutomergeUrl: '${id}'`)
+}
+
+// TYPES
+
+type UrlOptions = {
+  documentId: DocumentId | BinaryDocumentId
+}

package/src/DocHandle.ts

@@ -14,7 +14,7 @@ import {
   TypegenDisabled,
 } from "xstate"
 import { waitFor } from "xstate/lib/waitFor.js"
-import { stringifyAutomergeUrl } from "./DocUrl.js"
+import { stringifyAutomergeUrl } from "./AutomergeUrl.js"
 import { encode } from "./helpers/cbor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { withTimeout } from "./helpers/withTimeout.js"

package/src/Repo.ts

@@ -1,20 +1,19 @@
 import { next as Automerge } from "@automerge/automerge"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
-import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
 import {
   generateAutomergeUrl,
-  isValidAutomergeUrl,
+  interpretAsDocumentId,
   parseAutomergeUrl,
-  parseLegacyUUID,
-} from "./DocUrl.js"
+} from "./AutomergeUrl.js"
+import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
 import { throttle } from "./helpers/throttle.js"
 import { NetworkAdapter } from "./network/NetworkAdapter.js"
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
 import { StorageAdapter } from "./storage/StorageAdapter.js"
 import { StorageSubsystem } from "./storage/StorageSubsystem.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
-import { DocumentId, PeerId, type AutomergeUrl } from "./types.js"
+import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -247,22 +246,11 @@ export class Repo extends EventEmitter<RepoEvents> {
    * event to advertise interest in the document.
    */
   find<T>(
-    /** The documentId of the handle to retrieve */
-    automergeUrl: AutomergeUrl
+    /** The url or documentId of the handle to retrieve */
+    id: AnyDocumentId
   ): DocHandle<T> {
-    if (!isValidAutomergeUrl(automergeUrl)) {
-      const maybeAutomergeUrl = parseLegacyUUID(automergeUrl)
-      if (maybeAutomergeUrl) {
-        console.warn(
-          "Legacy UUID document ID detected, converting to AutomergeUrl. This will be removed in a future version."
-        )
-        automergeUrl = maybeAutomergeUrl
-      } else {
-        throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`)
-      }
-    }
+    const documentId = interpretAsDocumentId(id)
 
-    const { documentId } = parseAutomergeUrl(automergeUrl)
     // If we have the handle cached, return it
     if (this.#handleCache[documentId]) {
       if (this.#handleCache[documentId].isUnavailable()) {
@@ -282,16 +270,16 @@ export class Repo extends EventEmitter<RepoEvents> {
   }
 
   delete(
-    /** The documentId of the handle to delete */
-    id: DocumentId | AutomergeUrl
+    /** The url or documentId of the handle to delete */
+    id: AnyDocumentId
   ) {
-    if (isValidAutomergeUrl(id)) id = parseAutomergeUrl(id).documentId
+    const documentId = interpretAsDocumentId(id)
 
-    const handle = this.#getHandle(id, false)
+    const handle = this.#getHandle(documentId, false)
     handle.delete()
 
-    delete this.#handleCache[id]
-    this.emit("delete-document", { documentId: id })
+    delete this.#handleCache[documentId]
+    this.emit("delete-document", { documentId })
   }
 }
 

package/src/index.ts

@@ -31,7 +31,7 @@ export {
   isValidAutomergeUrl,
   parseAutomergeUrl,
   stringifyAutomergeUrl,
-} from "./DocUrl.js"
+} from "./AutomergeUrl.js"
 export { Repo } from "./Repo.js"
 export { NetworkAdapter } from "./network/NetworkAdapter.js"
 export { isValidRepoMessage } from "./network/messages.js"

package/src/synchronizer/CollectionSynchronizer.ts

@@ -1,6 +1,6 @@
 import debug from "debug"
 import { DocHandle } from "../DocHandle.js"
-import { stringifyAutomergeUrl } from "../DocUrl.js"
+import { stringifyAutomergeUrl } from "../AutomergeUrl.js"
 import { Repo } from "../Repo.js"
 import { RepoMessage } from "../network/messages.js"
 import { DocumentId, PeerId } from "../types.js"

package/src/types.ts

@@ -1,20 +1,32 @@
-/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
- */
-export type DocumentId = string & { __documentId: true } // for logging
-
-/** A branded string representing a URL for a document
- *
- * @remarks
- * An automerge URL has the form `automerge:<base58 encoded string>`. This
- * type is returned from various routines which validate a url.
- *
+/**
+ * A branded string representing a URL for a document, in the form `automerge:<base58check encoded
+ * string>`; for example, `automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu`.
  */
 export type AutomergeUrl = string & { __documentUrl: true } // for opening / linking
 
-/** A document ID as a Uint8Array instead of a bas58 encoded string. Typically you should use a {@link AutomergeUrl} instead.
+/**
+ * The base58check-encoded UUID of a document. This is the string following the `automerge:`
+ * protocol prefix in an AutomergeUrl; for example, `4NMNnkMhL8jXrdJ9jamS58PAVdXu`. When recording
+ * links to an Automerge document in another Automerge document, you should store a
+ * {@link AutomergeUrl} instead.
  */
+export type DocumentId = string & { __documentId: true } // for logging
+
+/** The unencoded UUID of a document. Typically you should use a {@link AutomergeUrl} instead. */
 export type BinaryDocumentId = Uint8Array & { __binaryDocumentId: true } // for storing / syncing
 
+/**
+ * A UUID encoded as a hex string. As of v1.0, a {@link DocumentID} is stored as a base58-encoded string with a checksum.
+ * Support for this format will be removed in a future version.
+ */
+export type LegacyDocumentId = string & { __legacyDocumentId: true }
+
+export type AnyDocumentId =
+  | AutomergeUrl
+  | DocumentId
+  | BinaryDocumentId
+  | LegacyDocumentId
+
 /** A branded type for peer IDs */
 export type PeerId = string & { __peerId: true }
 

package/test/AutomergeUrl.test.ts

@@ -0,0 +1,100 @@
+import assert from "assert"
+import bs58check from "bs58check"
+import { describe, it } from "vitest"
+import {
+  generateAutomergeUrl,
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
+  stringifyAutomergeUrl,
+} from "../src/AutomergeUrl.js"
+import type {
+  AutomergeUrl,
+  BinaryDocumentId,
+  DocumentId,
+} from "../src/types.js"
+
+const goodUrl = "automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu" as AutomergeUrl
+const badChecksumUrl = "automerge:badbadbad" as AutomergeUrl
+const badPrefixUrl = "yjs😉:4NMNnkMhL8jXrdJ9jamS58PAVdXu" as AutomergeUrl
+
+const goodDocumentId = "4NMNnkMhL8jXrdJ9jamS58PAVdXu" as DocumentId
+const badChecksumDocumentId = "badbadbad" as DocumentId
+const badUuidDocumentId = bs58check.encode(
+  new Uint8Array([1, 2, 3, 4, 42, -1, 69, 777])
+) as DocumentId
+
+const goodBinaryDocumentId = Uint8Array.from([
+  241, 194, 156, 132, 116, 200, 74, 222, 184, 0, 190, 71, 98, 125, 51, 191,
+]) as BinaryDocumentId
+
+describe("AutomergeUrl", () => {
+  describe("generateAutomergeUrl", () => {
+    it("should generate a valid Automerge URL", () => {
+      const url = generateAutomergeUrl()
+      assert(url.startsWith("automerge:"))
+      assert(parseAutomergeUrl(url).binaryDocumentId)
+    })
+  })
+
+  describe("stringifyAutomergeUrl", () => {
+    it("should stringify a binary document ID", () => {
+      const url = stringifyAutomergeUrl({ documentId: goodBinaryDocumentId })
+      assert.strictEqual(url, goodUrl)
+    })
+
+    it("should stringify a string document ID", () => {
+      const url = stringifyAutomergeUrl({ documentId: goodDocumentId })
+      assert.strictEqual(url, goodUrl)
+    })
+
+    it("supports passing a document ID without wrapping it in an object", () => {
+      const url1 = stringifyAutomergeUrl(goodDocumentId)
+      const url2 = stringifyAutomergeUrl({ documentId: goodDocumentId })
+      assert.equal(url1, url2)
+    })
+  })
+
+  describe("parseAutomergeUrl", () => {
+    it("should parse a valid url", () => {
+      const { binaryDocumentId, documentId } = parseAutomergeUrl(goodUrl)
+      assert.deepEqual(binaryDocumentId, goodBinaryDocumentId)
+      assert.equal(documentId, goodDocumentId)
+    })
+
+    it("should throw on url with invalid checksum", () => {
+      assert.throws(() => parseAutomergeUrl(badChecksumUrl))
+    })
+
+    it("should throw on url with invalid prefix", () => {
+      assert.throws(() => parseAutomergeUrl(badPrefixUrl))
+    })
+  })
+
+  describe("isValidAutomergeUrl", () => {
+    it("should return true for a valid url", () => {
+      assert(isValidAutomergeUrl(goodUrl) === true)
+    })
+
+    it("should return false for null url", () => {
+      assert(isValidAutomergeUrl(null) === false)
+    })
+
+    it("should return false for a url with invalid checksum", () => {
+      assert(isValidAutomergeUrl(badChecksumUrl) === false)
+    })
+
+    it("should return false for a url with invalid prefix", () => {
+      assert(isValidAutomergeUrl(badPrefixUrl) === false)
+    })
+
+    it("should return false for a documentId with an invalid checksum", () => {
+      const url = stringifyAutomergeUrl({ documentId: badChecksumDocumentId })
+      assert(isValidAutomergeUrl(url) === false)
+    })
+
+    it("should return false for a documentId that is not a valid UUID ", () => {
+      const url = stringifyAutomergeUrl({ documentId: badUuidDocumentId })
+      assert(isValidAutomergeUrl(url) === false)
+    })
+  })
+})

package/test/DocHandle.test.ts

@@ -2,7 +2,7 @@ import * as A from "@automerge/automerge/next"
 import assert from "assert"
 import { decode } from "cbor-x"
 import { describe, it } from "vitest"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/DocUrl.js"
+import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import { DocHandle, DocHandleChangePayload } from "../src/index.js"

package/test/DocSynchronizer.test.ts

@@ -1,7 +1,7 @@
 import assert from "assert"
 import { describe, it } from "vitest"
 import { DocHandle } from "../src/DocHandle.js"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/DocUrl.js"
+import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import {
   DocumentUnavailableMessage,

package/test/Repo.test.ts

@@ -2,9 +2,12 @@ import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-
 import assert from "assert"
 import * as Uuid from "uuid"
 import { describe, it } from "vitest"
-import { parseAutomergeUrl } from "../dist/DocUrl.js"
+import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { READY } from "../src/DocHandle.js"
-import { generateAutomergeUrl, stringifyAutomergeUrl } from "../src/DocUrl.js"
+import {
+  generateAutomergeUrl,
+  stringifyAutomergeUrl,
+} from "../src/AutomergeUrl.js"
 import { Repo } from "../src/Repo.js"
 import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
@@ -12,6 +15,7 @@ import {
   AutomergeUrl,
   DocHandle,
   DocumentId,
+  LegacyDocumentId,
   PeerId,
   SharePolicy,
 } from "../src/index.js"
@@ -51,7 +55,7 @@ describe("Repo", () => {
       assert.equal(handle.isReady(), true)
     })
 
-    it("can find a document once it's created", () => {
+    it("can find a document by url", () => {
       const { repo } = setup()
       const handle = repo.create<TestDoc>()
       handle.change((d: TestDoc) => {
@@ -63,7 +67,19 @@ describe("Repo", () => {
       assert.deepEqual(handle2.docSync(), { foo: "bar" })
     })
 
-    it("can find a document using a legacy UUID (for now)", () => {
+    it("can find a document by its unprefixed document ID", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change((d: TestDoc) => {
+        d.foo = "bar"
+      })
+
+      const handle2 = repo.find(handle.documentId)
+      assert.equal(handle, handle2)
+      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+    })
+
+    it("can find a document by legacy UUID (for now)", () => {
       disableConsoleWarn()
 
       const { repo } = setup()
@@ -74,9 +90,9 @@ describe("Repo", () => {
 
       const url = handle.url
       const { binaryDocumentId } = parseAutomergeUrl(url)
-      const legacyDocumentId = Uuid.stringify(binaryDocumentId) as AutomergeUrl // a white lie
+      const legacyDocId = Uuid.stringify(binaryDocumentId) as LegacyDocumentId
 
-      const handle2 = repo.find(legacyDocumentId)
+      const handle2 = repo.find(legacyDocId)
       assert.equal(handle, handle2)
       assert.deepEqual(handle2.docSync(), { foo: "bar" })
 

package/test/StorageSubsystem.test.ts

@@ -5,7 +5,7 @@ import fs from "fs"
 import os from "os"
 import path from "path"
 import { describe, it } from "vitest"
-import { generateAutomergeUrl, parseAutomergeUrl } from "../src/DocUrl.js"
+import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import { StorageSubsystem } from "../src/storage/StorageSubsystem.js"
 import { DummyStorageAdapter } from "./helpers/DummyStorageAdapter.js"
 

package/dist/DocUrl.d.ts

@@ -1,39 +0,0 @@
-import { type AutomergeUrl, type BinaryDocumentId, type DocumentId } from "./types.js";
-export declare const urlPrefix = "automerge:";
-/**
- * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
- *
- * @param url
- * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
- */
-export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
-    binaryDocumentId: BinaryDocumentId;
-    documentId: DocumentId;
-};
-/**
- * Given a documentId in either canonical form, return an Automerge URL
- * Throws on invalid input.
- * Note: this is an object because we anticipate adding fields in the future.
- * @param { documentId: BinaryDocumentId | DocumentId }
- * @returns AutomergeUrl
- */
-export declare const stringifyAutomergeUrl: ({ documentId, }: {
-    documentId: DocumentId | BinaryDocumentId;
-}) => AutomergeUrl;
-/**
- * Given a string, return true if it is a valid Automerge URL
- * also acts as a type discriminator in Typescript.
- * @param str: URL candidate
- * @returns boolean
- */
-export declare const isValidAutomergeUrl: (str: string) => str is AutomergeUrl;
-/**
- * generateAutomergeUrl produces a new AutomergeUrl.
- * generally only called by create(), but used in tests as well.
- * @returns a new Automerge URL with a random UUID documentId
- */
-export declare const generateAutomergeUrl: () => AutomergeUrl;
-export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
-export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
-export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
-//# sourceMappingURL=DocUrl.d.ts.map

package/dist/DocUrl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"DocUrl.d.ts","sourceRoot":"","sources":["../src/DocUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAS,YAAY;;;CAIlD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;gBAGpB,UAAU,GAAG,gBAAgB;MACvC,YAQH,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAS,MAAM,wBAK9C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGpC,CAAA;AAEJ,eAAO,MAAM,kBAAkB,UACtB,UAAU,KAChB,gBAAgB,GAAG,SACyC,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAAG,UACtB,CAAA;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,KAAG,YAAY,GAAG,SAM5D,CAAA"}

package/dist/DocUrl.js

@@ -1,74 +0,0 @@
-import * as Uuid from "uuid";
-import bs58check from "bs58check";
-export const urlPrefix = "automerge:";
-/**
- * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
- *
- * @param url
- * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
- */
-export const parseAutomergeUrl = (url) => {
-    const { binaryDocumentId, documentId } = parts(url);
-    if (!binaryDocumentId)
-        throw new Error("Invalid document URL: " + url);
-    return { binaryDocumentId, documentId };
-};
-/**
- * Given a documentId in either canonical form, return an Automerge URL
- * Throws on invalid input.
- * Note: this is an object because we anticipate adding fields in the future.
- * @param { documentId: BinaryDocumentId | DocumentId }
- * @returns AutomergeUrl
- */
-export const stringifyAutomergeUrl = ({ documentId, }) => {
-    if (documentId instanceof Uint8Array)
-        return (urlPrefix +
-            binaryToDocumentId(documentId));
-    else if (typeof documentId === "string") {
-        return (urlPrefix + documentId);
-    }
-    throw new Error("Invalid documentId: " + documentId);
-};
-/**
- * Given a string, return true if it is a valid Automerge URL
- * also acts as a type discriminator in Typescript.
- * @param str: URL candidate
- * @returns boolean
- */
-export const isValidAutomergeUrl = (str) => {
-    if (!str.startsWith(urlPrefix))
-        return false;
-    const { binaryDocumentId: documentId } = parts(str);
-    return documentId ? true : false;
-};
-/**
- * generateAutomergeUrl produces a new AutomergeUrl.
- * generally only called by create(), but used in tests as well.
- * @returns a new Automerge URL with a random UUID documentId
- */
-export const generateAutomergeUrl = () => stringifyAutomergeUrl({
-    documentId: Uuid.v4(null, new Uint8Array(16)),
-});
-export const documentIdToBinary = (docId) => bs58check.decodeUnsafe(docId);
-export const binaryToDocumentId = (docId) => bs58check.encode(docId);
-export const parseLegacyUUID = (str) => {
-    if (Uuid.validate(str)) {
-        const uuid = Uuid.parse(str);
-        return stringifyAutomergeUrl({ documentId: uuid });
-    }
-    return undefined;
-};
-/**
- * parts breaks up the URL into constituent pieces,
- * eventually this could include things like heads, so we use this structure
- * we return both a binary & string-encoded version of the document ID
- * @param str
- * @returns { binaryDocumentId, documentId }
- */
-const parts = (str) => {
-    const regex = new RegExp(`^${urlPrefix}(\\w+)$`);
-    const [_, docMatch] = str.match(regex) || [];
-    const documentId = docMatch;
-    const binaryDocumentId = documentIdToBinary(documentId);
-    return { binaryDocumentId, documentId };
-};

package/src/DocUrl.ts

@@ -1,96 +0,0 @@
-import {
-  type AutomergeUrl,
-  type BinaryDocumentId,
-  type DocumentId,
-} from "./types.js"
-import * as Uuid from "uuid"
-import bs58check from "bs58check"
-
-export const urlPrefix = "automerge:"
-
-/**
- * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
- *
- * @param url
- * @returns { binaryDocumentId: BinaryDocumentId, documentId: DocumentId }
- */
-export const parseAutomergeUrl = (url: AutomergeUrl) => {
-  const { binaryDocumentId, documentId } = parts(url)
-  if (!binaryDocumentId) throw new Error("Invalid document URL: " + url)
-  return { binaryDocumentId, documentId }
-}
-
-/**
- * Given a documentId in either canonical form, return an Automerge URL
- * Throws on invalid input.
- * Note: this is an object because we anticipate adding fields in the future.
- * @param { documentId: BinaryDocumentId | DocumentId }
- * @returns AutomergeUrl
- */
-export const stringifyAutomergeUrl = ({
-  documentId,
-}: {
-  documentId: DocumentId | BinaryDocumentId
-}): AutomergeUrl => {
-  if (documentId instanceof Uint8Array)
-    return (urlPrefix +
-      binaryToDocumentId(documentId as BinaryDocumentId)) as AutomergeUrl
-  else if (typeof documentId === "string") {
-    return (urlPrefix + documentId) as AutomergeUrl
-  }
-  throw new Error("Invalid documentId: " + documentId)
-}
-
-/**
- * Given a string, return true if it is a valid Automerge URL
- * also acts as a type discriminator in Typescript.
- * @param str: URL candidate
- * @returns boolean
- */
-export const isValidAutomergeUrl = (str: string): str is AutomergeUrl => {
-  if (!str.startsWith(urlPrefix)) return false
-
-  const { binaryDocumentId: documentId } = parts(str)
-  return documentId ? true : false
-}
-
-/**
- * generateAutomergeUrl produces a new AutomergeUrl.
- * generally only called by create(), but used in tests as well.
- * @returns a new Automerge URL with a random UUID documentId
- */
-export const generateAutomergeUrl = (): AutomergeUrl =>
-  stringifyAutomergeUrl({
-    documentId: Uuid.v4(null, new Uint8Array(16)) as BinaryDocumentId,
-  })
-
-export const documentIdToBinary = (
-  docId: DocumentId
-): BinaryDocumentId | undefined =>
-  bs58check.decodeUnsafe(docId) as BinaryDocumentId | undefined
-
-export const binaryToDocumentId = (docId: BinaryDocumentId): DocumentId =>
-  bs58check.encode(docId) as DocumentId
-
-export const parseLegacyUUID = (str: string): AutomergeUrl | undefined => {
-  if (Uuid.validate(str)) {
-    const uuid = Uuid.parse(str) as BinaryDocumentId
-    return stringifyAutomergeUrl({ documentId: uuid })
-  }
-  return undefined
-}
-
-/**
- * parts breaks up the URL into constituent pieces,
- * eventually this could include things like heads, so we use this structure
- * we return both a binary & string-encoded version of the document ID
- * @param str
- * @returns { binaryDocumentId, documentId }
- */
-const parts = (str: string) => {
-  const regex = new RegExp(`^${urlPrefix}(\\w+)$`)
-  const [_, docMatch] = str.match(regex) || []
-  const documentId = docMatch as DocumentId
-  const binaryDocumentId = documentIdToBinary(documentId)
-  return { binaryDocumentId, documentId }
-}