Add metadata api

packages/automerge-repo/src/DocHandle.ts

@@ -42,6 +42,9 @@ export class DocHandle<T> //
   #timeoutDelay: number
   #remoteHeads: Record<StorageId, A.Heads> = {}
 
+  // Reference to global meta data that is set on the repo to be attached to each change
+  #globalMetadataRef?: ChangeMetadataRef
+
   /** The URL of this document
    *
    * @remarks
@@ -54,10 +57,15 @@ export class DocHandle<T> //
   /** @hidden */
   constructor(
     public documentId: DocumentId,
-    { isNew = false, timeoutDelay = 60_000 }: DocHandleOptions = {}
+    {
+      isNew = false,
+      timeoutDelay = 60_000,
+      globalMetadataRef,
+    }: DocHandleOptions = {}
   ) {
     super()
     this.#timeoutDelay = timeoutDelay
+    this.#globalMetadataRef = globalMetadataRef
     this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
 
     // initial doc
@@ -340,7 +348,7 @@ export class DocHandle<T> //
   }
 
   /** `change` is called by the repo when the document is changed locally  */
-  change(callback: A.ChangeFn<T>, options: A.ChangeOptions<T> = {}) {
+  change(callback: A.ChangeFn<T>, options: DocHandleChangeOptions<T> = {}) {
     if (!this.isReady()) {
       throw new Error(
         `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before accessing the document.`
@@ -349,7 +357,14 @@ export class DocHandle<T> //
     this.#machine.send(UPDATE, {
       payload: {
         callback: (doc: A.Doc<T>) => {
-          return A.change(doc, options, callback)
+          return A.change(
+            doc,
+            optionsWithGlobalMetadata(
+              options,
+              this.#globalMetadataRef?.current ?? {}
+            ),
+            callback
+          )
         },
       },
     })
@@ -362,7 +377,7 @@ export class DocHandle<T> //
   changeAt(
     heads: A.Heads,
     callback: A.ChangeFn<T>,
-    options: A.ChangeOptions<T> = {}
+    options: DocHandleChangeOptions<T> = {}
   ): string[] | undefined {
     if (!this.isReady()) {
       throw new Error(
@@ -373,7 +388,15 @@ export class DocHandle<T> //
     this.#machine.send(UPDATE, {
       payload: {
         callback: (doc: A.Doc<T>) => {
-          const result = A.changeAt(doc, heads, options, callback)
+          const result = A.changeAt(
+            doc,
+            heads,
+            optionsWithGlobalMetadata(
+              options,
+              this.#globalMetadataRef?.current ?? {}
+            ),
+            callback
+          )
           resultHeads = result.newHeads
           return result.newDoc
         },
@@ -448,12 +471,48 @@ export class DocHandle<T> //
   }
 }
 
+function optionsWithGlobalMetadata<T>(
+  options: DocHandleChangeOptions<T>,
+  globalMetadata: ChangeMetadata
+): A.ChangeOptions<T> {
+  let metadata = { ...globalMetadata }
+
+  if (options.metadata) {
+    if (!metadata) {
+      metadata = {}
+    }
+
+    Object.assign(metadata, options.metadata)
+  }
+
+  return {
+    time: options.time,
+    message:
+      Object.values(metadata).length > 0 ? JSON.stringify(metadata) : undefined,
+    patchCallback: options.patchCallback,
+  }
+}
+
 // WRAPPER CLASS TYPES
 
 /** @hidden */
 export interface DocHandleOptions {
   isNew?: boolean
   timeoutDelay?: number
+  globalMetadataRef?: ChangeMetadataRef
+}
+
+// todo: remove this type once we have real metadata on changes in automerge
+// as an interim solution we use the message attribute to store the metadata as a JSON string
+export interface DocHandleChangeOptions<T> {
+  metadata?: ChangeMetadata
+  time?: number
+  patchCallback?: A.PatchCallback<T>
+}
+
+export type ChangeMetadata = Record<string, number | string | boolean>
+export interface ChangeMetadataRef {
+  current: ChangeMetadata
 }
 
 export interface DocHandleMessagePayload {

packages/automerge-repo/src/Repo.ts

@@ -6,7 +6,12 @@ import {
   interpretAsDocumentId,
   parseAutomergeUrl,
 } from "./AutomergeUrl.js"
-import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
+import {
+  DocHandle,
+  DocHandleEncodedChangePayload,
+  ChangeMetadata,
+  ChangeMetadataRef,
+} from "./DocHandle.js"
 import { RemoteHeadsSubscriptions } from "./RemoteHeadsSubscriptions.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { throttle } from "./helpers/throttle.js"
@@ -55,6 +60,8 @@ export class Repo extends EventEmitter<RepoEvents> {
   #remoteHeadsSubscriptions = new RemoteHeadsSubscriptions()
   #remoteHeadsGossipingEnabled = false
 
+  #globalMetadataRef: ChangeMetadataRef = { current: {} }
+
   constructor({
     storage,
     network,
@@ -331,7 +338,10 @@ export class Repo extends EventEmitter<RepoEvents> {
 
     // If not, create a new handle, cache it, and return it
     if (!documentId) throw new Error(`Invalid documentId ${documentId}`)
-    const handle = new DocHandle<T>(documentId, { isNew })
+    const handle = new DocHandle<T>(documentId, {
+      isNew,
+      globalMetadataRef: this.#globalMetadataRef,
+    })
     this.#handleCache[documentId] = handle
     return handle
   }
@@ -346,6 +356,11 @@ export class Repo extends EventEmitter<RepoEvents> {
     return this.#synchronizer.peers
   }
 
+  /** Set meta data that will be attached to each change that is created through a handle from this repo */
+  setGlobalMetadata(metadata: ChangeMetadata) {
+    this.#globalMetadataRef.current = metadata
+  }
+
   getStorageIdOfPeer(peerId: PeerId): StorageId | undefined {
     return this.peerMetadataByPeerId[peerId]?.storageId
   }

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

@@ -303,6 +303,106 @@ describe("DocHandle", () => {
     assert(wasBar, "foo should have been bar as we changed at the old heads")
   })
 
+  describe("metadata on changes", () => {
+    it("should allow to pass in a reference to global metadata", () => {
+      const handle = new DocHandle<TestDoc>(TEST_ID, {
+        isNew: true,
+        globalMetadataRef: { current: { author: "bob" } },
+      })
+
+      const doc1 = handle.docSync()
+
+      // ... with change
+      handle.change(doc => {
+        doc.foo = "bar"
+      })
+
+      // ... with change at
+      handle.changeAt(A.getHeads(doc1), doc => {
+        doc.foo = "baz"
+      })
+
+      const doc2 = handle.docSync()
+
+      const changes = A.getChanges(doc1, doc2).map(A.decodeChange)
+      assert.equal(changes.length, 2)
+      assert.equal(changes[0].message, JSON.stringify({ author: "bob" }))
+      assert.equal(changes[1].message, JSON.stringify({ author: "bob" }))
+    })
+
+    it("should allow to add additional local metadata with", () => {
+      const handle = new DocHandle<TestDoc>(TEST_ID, {
+        isNew: true,
+        globalMetadataRef: { current: { author: "bob" } },
+      })
+
+      const doc1 = handle.docSync()
+
+      // ... with change
+      handle.change(
+        doc => {
+          doc.foo = "bar"
+        },
+        { metadata: { message: "with change" } }
+      )
+
+      // ... with change at
+      handle.changeAt(
+        A.getHeads(doc1),
+        doc => {
+          doc.foo = "baz"
+        },
+        { metadata: { message: "with changeAt" } }
+      )
+
+      const doc2 = handle.docSync()
+
+      const changes = A.getChanges(doc1, doc2).map(A.decodeChange)
+      assert.equal(changes.length, 2)
+      assert.equal(
+        changes[0].message,
+        JSON.stringify({ author: "bob", message: "with change" })
+      )
+      assert.equal(
+        changes[1].message,
+        JSON.stringify({ author: "bob", message: "with changeAt" })
+      )
+    })
+
+    it("should allow to override global data with change", () => {
+      const handle = new DocHandle<TestDoc>(TEST_ID, {
+        isNew: true,
+        globalMetadataRef: { current: { author: "bob" } },
+      })
+
+      const doc1 = handle.docSync()
+
+      // ... with change
+      handle.change(
+        doc => {
+          doc.foo = "bar"
+        },
+        { metadata: { author: "sandra" } }
+      )
+
+      // ... with change at
+      handle.changeAt(
+        A.getHeads(doc1),
+        doc => {
+          doc.foo = "baz"
+        },
+        { metadata: { author: "frank" } }
+      )
+
+      const doc2 = handle.docSync()
+
+      const changes = A.getChanges(doc1, doc2).map(A.decodeChange)
+      assert.equal(changes.length, 2)
+      assert.equal(changes[0].message, JSON.stringify({ author: "sandra" }))
+      assert.equal(changes[1].message, JSON.stringify({ author: "frank" }))
+    })
+  })
+
   describe("ephemeral messaging", () => {
     it("can broadcast a message for the network to send out", async () => {
       const handle = new DocHandle<TestDoc>(TEST_ID, { isNew: true })

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

@@ -5,6 +5,7 @@ import * as Uuid from "uuid"
 import { describe, expect, it } from "vitest"
 import { READY } from "../src/DocHandle.js"
 import { parseAutomergeUrl } from "../src/AutomergeUrl.js"
+
 import {
   generateAutomergeUrl,
   stringifyAutomergeUrl,
@@ -451,6 +452,26 @@ describe("Repo", () => {
         repo.import<TestDoc>(A.init<TestDoc> as unknown as Uint8Array)
       }).toThrow()
     })
+
+    it("can set global change metadata", () => {
+      const { repo } = setup()
+
+      const handle = repo.create<TestDoc>()
+
+      const doc1 = handle.docSync()
+
+      repo.setGlobalMetadata({ author: "bob" })
+      handle.change(doc => {
+        doc.foo = "bar"
+      })
+
+      const doc2 = handle.docSync()
+
+      const changes = A.getChanges(doc1, doc2).map(A.decodeChange)
+
+      expect(changes.length).toEqual(1)
+      expect(changes[0].message).toEqual(JSON.stringify({ author: "bob" }))
+    })
   })
 
   describe("with peers (linear network)", async () => {