@automerge/automerge-repo - npm Package Compare versions

Comparing version 1.0.12 to 1.0.13

dist/DocHandle.js

@@ -6,3 +6,3 @@ import * as A from "@automerge/automerge/next";
 import { waitFor } from "xstate/lib/waitFor.js";
-import { stringifyAutomergeUrl } from "./DocUrl.js";
+import { stringifyAutomergeUrl } from "./AutomergeUrl.js";
 import { encode } from "./helpers/cbor.js";
@@ -9,0 +9,0 @@ import { headsAreSame } from "./helpers/headsAreSame.js";

dist/index.d.ts

@@ -29,3 +29,3 @@ /**
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./DocUrl.js";
+export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
@@ -32,0 +32,0 @@ export { NetworkAdapter } from "./network/NetworkAdapter.js";

dist/index.js

@@ -29,3 +29,3 @@ /**
 export { DocHandle } from "./DocHandle.js";
-export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./DocUrl.js";
+export { isValidAutomergeUrl, parseAutomergeUrl, stringifyAutomergeUrl, } from "./AutomergeUrl.js";
 export { Repo } from "./Repo.js";
@@ -32,0 +32,0 @@ export { NetworkAdapter } from "./network/NetworkAdapter.js";

dist/Repo.d.ts

@@ -7,3 +7,3 @@ import { EventEmitter } from "eventemitter3";
 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. */
@@ -59,7 +59,7 @@ /** The `Repo` is the main entry point of this library
     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;
 }
@@ -66,0 +66,0 @@ export interface RepoConfig {

dist/Repo.js

 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";
@@ -201,15 +201,5 @@ import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
     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
@@ -232,11 +222,10 @@ if (this.#handleCache[documentId]) {
     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 });
     }
 }

dist/synchronizer/CollectionSynchronizer.js

 import debug from "debug";
-import { stringifyAutomergeUrl } from "../DocUrl.js";
+import { stringifyAutomergeUrl } from "../AutomergeUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
@@ -4,0 +4,0 @@ import { Synchronizer } from "./Synchronizer.js";

dist/types.d.ts

@@ -1,21 +0,29 @@
-/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
+/**
+ * A branded string representing a URL for a document, in the form `automerge:<base58check encoded
+ * string>`; for example, `automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu`.
  */
-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.
- *
- */
 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 */
@@ -22,0 +30,0 @@ export type PeerId = string & {

package.json

 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "A repository object to manage a collection of automerge documents",
@@ -60,3 +60,3 @@ "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   },
-  "gitHead": "254bad1c774fa2a881265aaad5283af231bf72eb"
+  "gitHead": "48ca7b968758d7fd95f13fa03dc69d452cdd15f5"
 }

src/DocHandle.ts

@@ -17,3 +17,3 @@ import * as A from "@automerge/automerge/next"
 import { waitFor } from "xstate/lib/waitFor.js"
-import { stringifyAutomergeUrl } from "./DocUrl.js"
+import { stringifyAutomergeUrl } from "./AutomergeUrl.js"
 import { encode } from "./helpers/cbor.js"
@@ -20,0 +20,0 @@ import { headsAreSame } from "./helpers/headsAreSame.js"

src/index.ts

@@ -34,3 +34,3 @@ /**
   stringifyAutomergeUrl,
-} from "./DocUrl.js"
+} from "./AutomergeUrl.js"
 export { Repo } from "./Repo.js"
@@ -37,0 +37,0 @@ export { NetworkAdapter } from "./network/NetworkAdapter.js"

src/Repo.ts

 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"
@@ -17,3 +16,3 @@ import { NetworkAdapter } from "./network/NetworkAdapter.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
-import { DocumentId, PeerId, type AutomergeUrl } from "./types.js"
+import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
 
@@ -251,18 +250,7 @@ /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
   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
@@ -287,12 +275,12 @@ if (this.#handleCache[documentId]) {
   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 })
   }
@@ -299,0 +287,0 @@ }

src/synchronizer/CollectionSynchronizer.ts

 import debug from "debug"
 import { DocHandle } from "../DocHandle.js"
-import { stringifyAutomergeUrl } from "../DocUrl.js"
+import { stringifyAutomergeUrl } from "../AutomergeUrl.js"
 import { Repo } from "../Repo.js"
@@ -5,0 +5,0 @@ import { RepoMessage } from "../network/messages.js"

src/types.ts

@@ -1,18 +0,30 @@
-/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
+/**
+ * A branded string representing a URL for a document, in the form `automerge:<base58check encoded
+ * string>`; for example, `automerge:4NMNnkMhL8jXrdJ9jamS58PAVdXu`.
  */
-export type DocumentId = string & { __documentId: true } // for logging
+export type AutomergeUrl = string & { __documentUrl: true } // for opening / linking
 
-/** 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.
- *
+/**
+ * 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 AutomergeUrl = string & { __documentUrl: true } // for opening / linking
+export type DocumentId = string & { __documentId: true } // for logging
 
-/** A document ID as a Uint8Array instead of a bas58 encoded string. Typically you should use a {@link AutomergeUrl} instead.
- */
+/** 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 */
@@ -19,0 +31,0 @@ export type PeerId = string & { __peerId: true }

test/DocHandle.test.ts

@@ -5,3 +5,3 @@ import * as A from "@automerge/automerge/next"
 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"
@@ -8,0 +8,0 @@ import { pause } from "../src/helpers/pause.js"

test/DocSynchronizer.test.ts

 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"
@@ -6,0 +6,0 @@ import {

test/Repo.test.ts

@@ -5,5 +5,8 @@ import { MessageChannelNetworkAdapter } from "@automerge/automerge-repo-network-messagechannel"
 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"
@@ -16,2 +19,3 @@ import { eventPromise } from "../src/helpers/eventPromise.js"
   DocumentId,
+  LegacyDocumentId,
   PeerId,
@@ -56,3 +60,3 @@ SharePolicy,
 
-    it("can find a document once it's created", () => {
+    it("can find a document by url", () => {
       const { repo } = setup()
@@ -69,3 +73,15 @@ const handle = repo.create<TestDoc>()
 
-    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()
@@ -81,5 +97,5 @@
       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)
@@ -86,0 +102,0 @@ assert.deepEqual(handle2.docSync(), { foo: "bar" })

test/StorageSubsystem.test.ts

@@ -8,3 +8,3 @@ import { NodeFSStorageAdapter } from "@automerge/automerge-repo-storage-nodefs"
 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"
@@ -11,0 +11,0 @@ import { DummyStorageAdapter } from "./helpers/DummyStorageAdapter.js"

No alert changes

Improved metrics

Total package byte prevSize

273190

increased by2.52%

Number of package files

114

increased by0.88%

Lines of code

6221

increased by2.79%

No dependency changes