feat: create a document with a provided identifier

packages/automerge-repo/src/Repo.ts

@@ -352,10 +352,10 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   /**
    * Creates a new document and returns a handle to it. The initial value of the document is
-   * an empty object `{}`. Its documentId is generated by the system. we emit a `document` event
-   * to advertise interest in the document.
+   * an empty object `{}`. Its documentId is generated by the system if not procided.
+   * We emit a `document` event to advertise interest in the document.
    */
-  create<T>(): DocHandle<T> {
+  create<T>(opts?: { documentId?: AnyDocumentId }): DocHandle<T> {
     // TODO:
     // either
     // - pass an initial value and do something like this to ensure that you get a valid initial value
@@ -374,8 +374,15 @@ export class Repo extends EventEmitter<RepoEvents> {
     // or
     // - pass a "reify" function that takes a `<any>` and returns `<T>`
 
-    // Generate a new UUID and store it in the buffer
-    const { documentId } = parseAutomergeUrl(generateAutomergeUrl())
+    let documentId: DocumentId | undefined = opts?.documentId
+      ? interpretAsDocumentId(opts.documentId)
+      : undefined;
+
+    if (!documentId) {
+      // If no identifier is provided, generate a new UUID and store it in the buffer
+      ({ documentId } = parseAutomergeUrl(generateAutomergeUrl()))
+    }
+
     const handle = this.#getHandle<T>(documentId, true) as DocHandle<T>
     this.emit("document", { handle, isNew: true })
     return handle

packages/automerge-repo/src/index.ts

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

packages/automerge-repo/test/Repo.test.ts

@@ -4,7 +4,7 @@ import assert from "assert"
 import * as Uuid from "uuid"
 import { describe, expect, it } from "vitest"
 import { READY } from "../src/DocHandle.js"
-import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
+import { binaryToDocumentId, interpretAsDocumentId, parseAutomergeUrl } from "../src/AutomergeUrl.js"
 import {
   generateAutomergeUrl,
   stringifyAutomergeUrl,
@@ -14,7 +14,7 @@ import { eventPromise } from "../src/helpers/eventPromise.js"
 import { pause } from "../src/helpers/pause.js"
 import {
   AnyDocumentId,
-  AutomergeUrl,
+  AutomergeUrl, BinaryDocumentId,
   DocHandle,
   DocumentId,
   LegacyDocumentId,
@@ -67,6 +67,21 @@ describe("Repo", () => {
       assert.equal(handle.isReady(), true)
     })
 
+    it("can create a document with a custom documentId", () => {
+      const predictableId = interpretAsDocumentId(Uuid.v5(
+        "MyIdentifier1234",
+        "2bbbfa6a-a640-11ee-8228-62cbdfde7c1d",
+        new Uint8Array(16)
+      ) as BinaryDocumentId);
+
+      const { repo } = setup()
+      const handle = repo.create({
+        documentId: predictableId,
+      });
+
+      assert.equal(handle.documentId, predictableId)
+    });
+
     it("can find a document by url", () => {
       const { repo } = setup()
       const handle = repo.create<TestDoc>()