@automerge/automerge-repo 1.0.12 → 1.0.14

package/dist/storage/StorageSubsystem.js

@@ -1,28 +1,127 @@
 import * as A from "@automerge/automerge/next";
 import debug from "debug";
-import * as sha256 from "fast-sha256";
 import { headsAreSame } from "../helpers/headsAreSame.js";
 import { mergeArrays } from "../helpers/mergeArrays.js";
-function keyHash(binary) {
-    const hash = sha256.hash(binary);
-    const hashArray = Array.from(new Uint8Array(hash)); // convert buffer to byte array
-    const hashHex = hashArray.map(b => ("00" + b.toString(16)).slice(-2)).join(""); // convert bytes to hex string
-    return hashHex;
-}
-function headsHash(heads) {
-    const encoder = new TextEncoder();
-    const headsbinary = mergeArrays(heads.map((h) => encoder.encode(h)));
-    return keyHash(headsbinary);
-}
+import { keyHash, headsHash } from "./keyHash.js";
+import { chunkTypeFromKey } from "./chunkTypeFromKey.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 {
+    /** The storage adapter to use for saving and loading documents */
     #storageAdapter;
-    #chunkInfos = new Map();
+    /** Record of the latest heads we've loaded or saved for each document  */
     #storedHeads = new Map();
+    /** Metadata on the chunks we've already loaded for each document */
+    #chunkInfos = new Map();
+    /** Flag to avoid compacting when a compaction is already underway */
+    #compacting = false;
     #log = debug(`automerge-repo:storage-subsystem`);
-    #snapshotting = false;
     constructor(storageAdapter) {
         this.#storageAdapter = storageAdapter;
     }
+    // ARBITRARY KEY/VALUE STORAGE
+    // The `load`, `save`, and `remove` methods are for generic key/value storage, as opposed to
+    // Automerge documents. For example, they're used by the LocalFirstAuthProvider to persist the
+    // encrypted team graph that encodes group membership and permissions.
+    //
+    // The namespace parameter is to prevent collisions with other users of the storage subsystem.
+    // Typically this will be the name of the plug-in, adapter, or other system that is using it. For
+    // example, the LocalFirstAuthProvider uses the namespace `LocalFirstAuthProvider`.
+    /** Loads a value from storage. */
+    async load(
+    /** Namespace to prevent collisions with other users of the storage subsystem. */
+    namespace, 
+    /** Key to load. Typically a UUID or other unique identifier, but could be any string. */
+    key) {
+        const storageKey = [namespace, key];
+        return await this.#storageAdapter.load(storageKey);
+    }
+    /** Saves a value in storage. */
+    async save(
+    /** Namespace to prevent collisions with other users of the storage subsystem. */
+    namespace, 
+    /** Key to load. Typically a UUID or other unique identifier, but could be any string. */
+    key, 
+    /** Data to save, as a binary blob. */
+    data) {
+        const storageKey = [namespace, key];
+        await this.#storageAdapter.save(storageKey, data);
+    }
+    /** Removes a value from storage. */
+    async remove(
+    /** Namespace to prevent collisions with other users of the storage subsystem. */
+    namespace, 
+    /** Key to remove. Typically a UUID or other unique identifier, but could be any string. */
+    key) {
+        const storageKey = [namespace, key];
+        await this.#storageAdapter.remove(storageKey);
+    }
+    // AUTOMERGE DOCUMENT STORAGE
+    /**
+     * Loads the Automerge document with the given ID from storage.
+     */
+    async loadDoc(documentId) {
+        // Load all the chunks for this document
+        const chunks = await this.#storageAdapter.loadRange([documentId]);
+        const binaries = [];
+        const chunkInfos = [];
+        for (const chunk of chunks) {
+            // chunks might have been deleted in the interim
+            if (chunk.data === undefined)
+                continue;
+            const chunkType = chunkTypeFromKey(chunk.key);
+            if (chunkType == null)
+                continue;
+            chunkInfos.push({
+                key: chunk.key,
+                type: chunkType,
+                size: chunk.data.length,
+            });
+            binaries.push(chunk.data);
+        }
+        this.#chunkInfos.set(documentId, chunkInfos);
+        // Merge the chunks into a single binary
+        const binary = mergeArrays(binaries);
+        if (binary.length === 0)
+            return null;
+        // Load into an Automerge document
+        const newDoc = A.loadIncremental(A.init(), binary);
+        // Record the latest heads for the document
+        this.#storedHeads.set(documentId, A.getHeads(newDoc));
+        return newDoc;
+    }
+    /**
+     * Saves the provided Automerge document to storage.
+     *
+     * @remarks
+     * Under the hood this makes incremental saves until the incremental size is greater than the
+     * snapshot size, at which point the document is compacted into a single snapshot.
+     */
+    async saveDoc(documentId, doc) {
+        // Don't bother saving if the document hasn't changed
+        if (!this.#shouldSave(documentId, doc))
+            return;
+        const sourceChunks = this.#chunkInfos.get(documentId) ?? [];
+        if (this.#shouldCompact(sourceChunks)) {
+            await this.#saveTotal(documentId, doc, sourceChunks);
+        }
+        else {
+            await this.#saveIncremental(documentId, doc);
+        }
+        this.#storedHeads.set(documentId, A.getHeads(doc));
+    }
+    /**
+     * Removes the Automerge document with the given ID from storage
+     */
+    async removeDoc(documentId) {
+        await this.#storageAdapter.removeRange([documentId, "snapshot"]);
+        await this.#storageAdapter.removeRange([documentId, "incremental"]);
+    }
+    /**
+     * Saves just the incremental changes since the last save.
+     */
     async #saveIncremental(documentId, doc) {
         const binary = A.saveSince(doc, this.#storedHeads.get(documentId) ?? []);
         if (binary && binary.length > 0) {
@@ -43,8 +142,11 @@ export class StorageSubsystem {
             return Promise.resolve();
         }
     }
+    /**
+     * Compacts the document storage into a single shapshot.
+     */
     async #saveTotal(documentId, doc, sourceChunks) {
-        this.#snapshotting = true;
+        this.#compacting = true;
         const binary = A.save(doc);
         const snapshotHash = headsHash(A.getHeads(doc));
         const key = [documentId, "snapshot", snapshotHash];
@@ -58,66 +160,30 @@ export class StorageSubsystem {
         const newChunkInfos = this.#chunkInfos.get(documentId)?.filter(c => !oldKeys.has(c.key)) ?? [];
         newChunkInfos.push({ key, type: "snapshot", size: binary.length });
         this.#chunkInfos.set(documentId, newChunkInfos);
-        this.#snapshotting = false;
-    }
-    async loadDoc(documentId) {
-        const loaded = await this.#storageAdapter.loadRange([documentId]);
-        const binaries = [];
-        const chunkInfos = [];
-        for (const chunk of loaded) {
-            const chunkType = chunkTypeFromKey(chunk.key);
-            if (chunkType == null) {
-                continue;
-            }
-            chunkInfos.push({
-                key: chunk.key,
-                type: chunkType,
-                size: chunk.data.length,
-            });
-            binaries.push(chunk.data);
-        }
-        this.#chunkInfos.set(documentId, chunkInfos);
-        const binary = mergeArrays(binaries);
-        if (binary.length === 0) {
-            return null;
-        }
-        const newDoc = A.loadIncremental(A.init(), binary);
-        this.#storedHeads.set(documentId, A.getHeads(newDoc));
-        return newDoc;
-    }
-    async saveDoc(documentId, doc) {
-        if (!this.#shouldSave(documentId, doc)) {
-            return;
-        }
-        const sourceChunks = this.#chunkInfos.get(documentId) ?? [];
-        if (this.#shouldCompact(sourceChunks)) {
-            void this.#saveTotal(documentId, doc, sourceChunks);
-        }
-        else {
-            void this.#saveIncremental(documentId, doc);
-        }
-        this.#storedHeads.set(documentId, A.getHeads(doc));
-    }
-    async remove(documentId) {
-        void this.#storageAdapter.removeRange([documentId, "snapshot"]);
-        void this.#storageAdapter.removeRange([documentId, "incremental"]);
+        this.#compacting = false;
     }
+    /**
+     * Returns true if the document has changed since the last time it was saved.
+     */
     #shouldSave(documentId, doc) {
         const oldHeads = this.#storedHeads.get(documentId);
         if (!oldHeads) {
+            // we haven't saved this document before
             return true;
         }
         const newHeads = A.getHeads(doc);
         if (headsAreSame(newHeads, oldHeads)) {
+            // the document hasn't changed
             return false;
         }
-        return true;
+        return true; // the document has changed
     }
+    /**
+     * We only compact if the incremental size is greater than the snapshot size.
+     */
     #shouldCompact(sourceChunks) {
-        if (this.#snapshotting) {
+        if (this.#compacting)
             return false;
-        }
-        // compact if the incremental size is greater than the snapshot size
         let snapshotSize = 0;
         let incrementalSize = 0;
         for (const chunk of sourceChunks) {
@@ -131,16 +197,3 @@ export class StorageSubsystem {
         return incrementalSize >= snapshotSize;
     }
 }
-function chunkTypeFromKey(key) {
-    if (key.length < 2) {
-        return null;
-    }
-    const chunkTypeStr = key[key.length - 2];
-    if (chunkTypeStr === "snapshot" || chunkTypeStr === "incremental") {
-        const chunkType = chunkTypeStr;
-        return chunkType;
-    }
-    else {
-        return null;
-    }
-}

package/dist/storage/chunkTypeFromKey.d.ts

@@ -0,0 +1,13 @@
+import { StorageKey } from "./types.js";
+import { ChunkType } from "./types.js";
+/**
+ * Keys for storing Automerge documents are of the form:
+ * ```ts
+ * [documentId, "snapshot", hash]  // OR
+ * [documentId, "incremental", hash]
+ * ```
+ * This function returns the chunk type ("snapshot" or "incremental") if the key is in one of these
+ * forms.
+ */
+export declare function chunkTypeFromKey(key: StorageKey): ChunkType | null;
+//# sourceMappingURL=chunkTypeFromKey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunkTypeFromKey.d.ts","sourceRoot":"","sources":["../../src/storage/chunkTypeFromKey.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CASlE"}

package/dist/storage/chunkTypeFromKey.js

@@ -0,0 +1,18 @@
+/**
+ * Keys for storing Automerge documents are of the form:
+ * ```ts
+ * [documentId, "snapshot", hash]  // OR
+ * [documentId, "incremental", hash]
+ * ```
+ * This function returns the chunk type ("snapshot" or "incremental") if the key is in one of these
+ * forms.
+ */
+export function chunkTypeFromKey(key) {
+    if (key.length < 2)
+        return null;
+    const chunkTypeStr = key[key.length - 2]; // next-to-last element in key
+    if (chunkTypeStr === "snapshot" || chunkTypeStr === "incremental") {
+        return chunkTypeStr;
+    }
+    return null;
+}

package/dist/storage/keyHash.d.ts

@@ -0,0 +1,4 @@
+import * as A from "@automerge/automerge/next";
+export declare function keyHash(binary: Uint8Array): string;
+export declare function headsHash(heads: A.Heads): string;
+//# sourceMappingURL=keyHash.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keyHash.d.ts","sourceRoot":"","sources":["../../src/storage/keyHash.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,2BAA2B,CAAA;AAI9C,wBAAgB,OAAO,CAAC,MAAM,EAAE,UAAU,UAIzC;AACD,wBAAgB,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC,KAAK,GAAG,MAAM,CAIhD"}

package/dist/storage/keyHash.js

@@ -0,0 +1,15 @@
+import * as sha256 from "fast-sha256";
+import { mergeArrays } from "../helpers/mergeArrays.js";
+export function keyHash(binary) {
+    // calculate hash
+    const hash = sha256.hash(binary);
+    return bufferToHexString(hash);
+}
+export function headsHash(heads) {
+    const encoder = new TextEncoder();
+    const headsbinary = mergeArrays(heads.map((h) => encoder.encode(h)));
+    return keyHash(headsbinary);
+}
+function bufferToHexString(data) {
+    return Array.from(data, byte => byte.toString(16).padStart(2, "0")).join("");
+}

package/dist/storage/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A chunk is a snapshot or incremental change that is stored in a {@link StorageAdapter}.
+ */
+export type Chunk = {
+    key: StorageKey;
+    data: Uint8Array | undefined;
+};
+/**
+ * Metadata about a chunk of data loaded from storage. This is stored on the StorageSubsystem so
+ * when we are compacting we know what chunks we can safely delete.
+ */
+export type ChunkInfo = {
+    key: StorageKey;
+    type: ChunkType;
+    size: number;
+};
+export type ChunkType = "snapshot" | "incremental";
+/**
+ * A storage key is an array of strings that represents a path to a value in a
+ * {@link StorageAdapter}.
+ *
+ * @remarks
+ * Storage keys are arrays because they are hierarchical and they allow the storage subsystem to do
+ * range queries for all keys that have a particular prefix. For example, incremental changes for a
+ * given document might be stored under `[<documentId>, "incremental", <SHA256>]`.
+ *
+ * automerge-repo mostly uses keys in the following form:
+ * ```ts
+ * [documentId, "snapshot", hash]  // OR
+ * [documentId, "incremental", hash]
+ * ```
+ *
+ * However, the storage adapter implementation should be agnostic to the meaning of the key and
+ * should not assume any particular structure.
+ **/
+export type StorageKey = string[];
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,GAAG,EAAE,UAAU,CAAA;IACf,IAAI,EAAE,UAAU,GAAG,SAAS,CAAA;CAC7B,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,GAAG,EAAE,UAAU,CAAA;IACf,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,aAAa,CAAA;AAElD;;;;;;;;;;;;;;;;;IAiBI;AACJ,MAAM,MAAM,UAAU,GAAG,MAAM,EAAE,CAAA"}

package/dist/storage/types.js

@@ -0,0 +1 @@
+export {};

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.14",
   "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": "c4a155e56613bbd396d3b764f3a2ec5807ac02db"
 }

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
@@ -107,7 +106,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       // synchronizer.removeDocument(documentId)
 
       if (storageSubsystem) {
-        storageSubsystem.remove(documentId).catch(err => {
+        storageSubsystem.removeDoc(documentId).catch(err => {
           this.#log("error deleting document", { documentId, err })
         })
       }
@@ -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 })
   }
 }