@automerge/automerge-repo 2.0.0-alpha.14 → 2.0.0-alpha.17

package/src/DocHandle.ts

@@ -2,7 +2,12 @@ import * as A from "@automerge/automerge/slim/next"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import { assertEvent, assign, createActor, setup, waitFor } from "xstate"
-import { stringifyAutomergeUrl } from "./AutomergeUrl.js"
+import {
+  decodeHeads,
+  encodeHeads,
+  stringifyAutomergeUrl,
+  UrlHeads,
+} from "./AutomergeUrl.js"
 import { encode } from "./helpers/cbor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { withTimeout } from "./helpers/withTimeout.js"
@@ -28,6 +33,9 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   /** The XState actor running our state machine.  */
   #machine
 
+  /** If set, this handle will only show the document at these heads */
+  #fixedHeads?: UrlHeads
+
   /** The last known state of our document. */
   #prevDocState: T = A.init<T>()
 
@@ -36,7 +44,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   #timeoutDelay = 60_000
 
   /** A dictionary mapping each peer to the last heads we know they have. */
-  #remoteHeads: Record<StorageId, A.Heads> = {}
+  #remoteHeads: Record<StorageId, UrlHeads> = {}
 
   /** @hidden */
   constructor(
@@ -49,6 +57,10 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       this.#timeoutDelay = options.timeoutDelay
     }
 
+    if ("heads" in options) {
+      this.#fixedHeads = options.heads
+    }
+
     const doc = A.init<T>()
 
     this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
@@ -176,7 +188,10 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   #checkForChanges(before: A.Doc<T>, after: A.Doc<T>) {
     const beforeHeads = A.getHeads(before)
     const afterHeads = A.getHeads(after)
-    const docChanged = !headsAreSame(afterHeads, beforeHeads)
+    const docChanged = !headsAreSame(
+      encodeHeads(afterHeads),
+      encodeHeads(beforeHeads)
+    )
     if (docChanged) {
       this.emit("heads-changed", { handle: this, doc: after })
 
@@ -202,7 +217,10 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   /** Our documentId in Automerge URL form.
    */
   get url(): AutomergeUrl {
-    return stringifyAutomergeUrl({ documentId: this.documentId })
+    return stringifyAutomergeUrl({
+      documentId: this.documentId,
+      heads: this.#fixedHeads,
+    })
   }
 
   /**
@@ -275,6 +293,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       // if we timed out, return undefined
       return undefined
     }
+    // If we have fixed heads, return a view at those heads
+    if (this.#fixedHeads) {
+      const doc = this.#doc
+      if (!doc || this.isUnavailable()) return undefined
+      return A.view(doc, decodeHeads(this.#fixedHeads))
+    }
     // Return the document
     return !this.isUnavailable() ? this.#doc : undefined
   }
@@ -294,7 +318,11 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    */
   docSync() {
     if (!this.isReady()) return undefined
-    else return this.#doc
+    if (this.#fixedHeads) {
+      const doc = this.#doc
+      return doc ? A.view(doc, decodeHeads(this.#fixedHeads)) : undefined
+    }
+    return this.#doc
   }
 
   /**
@@ -302,11 +330,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * This precisely defines the state of a document.
    * @returns the current document's heads, or undefined if the document is not ready
    */
-  heads(): A.Heads | undefined {
-    if (!this.isReady()) {
-      return undefined
+  heads(): UrlHeads | undefined {
+    if (!this.isReady()) return undefined
+    if (this.#fixedHeads) {
+      return this.#fixedHeads
     }
-    return A.getHeads(this.#doc)
+    return encodeHeads(A.getHeads(this.#doc))
   }
 
   begin() {
@@ -314,9 +343,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Creates a fixed "view" of an automerge document at the given point in time represented
-   * by the `heads` passed in. The return value is the same type as docSync() and will return
-   * undefined if the object hasn't finished loading.
+   * Returns an array of all past "heads" for the document in topological order.
    *
    * @remarks
    * A point-in-time in an automerge document is an *array* of heads since there may be
@@ -325,19 +352,21 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * history views would be quite large under concurrency (every thing in each branch against each other).
    * There might be a clever way to think about this, but we haven't found it yet, so for now at least
    * we present a single traversable view which excludes concurrency.
-   * @returns The individual heads for every change in the document.
+   * @returns UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].
    */
-  history(): A.Heads[] | undefined {
+  history(): UrlHeads[] | undefined {
     if (!this.isReady()) {
       return undefined
     }
     // This just returns all the heads as individual strings.
 
-    return A.topoHistoryTraversal(this.#doc).map(h => [h]) as A.Heads[]
+    return A.topoHistoryTraversal(this.#doc).map(h =>
+      encodeHeads([h])
+    ) as UrlHeads[]
   }
 
   /**
-   * Creates a fixed "view" of an automerge document at the given point in time represented
+   * Creates a new DocHandle with a fixed "view" at the given point in time represented
    * by the `heads` passed in. The return value is the same type as docSync() and will return
    * undefined if the object hasn't finished loading.
    *
@@ -346,13 +375,24 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * of Automerge doesn't check types at runtime, so if you go back to an old set of heads
    * that doesn't match the heads here, Typescript will not save you.
    *
-   * @returns An Automerge.Doc<T> at the point in time.
+   * @argument heads - The heads to view the document at. See history().
+   * @returns DocHandle<T> at the time of `heads`
    */
-  view(heads: A.Heads): A.Doc<T> | undefined {
+  view(heads: UrlHeads): DocHandle<T> {
     if (!this.isReady()) {
-      return undefined
+      throw new Error(
+        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`
+      )
     }
-    return A.view(this.#doc, heads)
+    // Create a new handle with the same documentId but fixed heads
+    const handle = new DocHandle<T>(this.documentId, {
+      heads,
+      timeoutDelay: this.#timeoutDelay,
+    })
+    handle.update(() => A.clone(this.#doc))
+    handle.doneLoading()
+
+    return handle
   }
 
   /**
@@ -360,19 +400,46 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * if applied.
    *
    * @remarks
-   * We allow specifying both a from/to heads or just a single comparison point, in which case
-   * the base will be the current document heads.
+   * We allow specifying either:
+   * - Two sets of heads to compare directly
+   * - A single set of heads to compare against our current heads
+   * - Another DocHandle to compare against (which must share history with this document)
    *
-   * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
+   * @throws Error if the documents don't share history or if either document is not ready
+   * @returns Automerge patches that go from one document state to the other
    */
-  diff(first: A.Heads, second?: A.Heads): A.Patch[] | undefined {
+  diff(first: UrlHeads | DocHandle<T>, second?: UrlHeads): A.Patch[] {
     if (!this.isReady()) {
-      return undefined
+      throw new Error(
+        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling diff().`
+      )
     }
-    // We allow only one set of heads to be specified, in which case we use the doc's heads
-    const from = second ? first : this.heads() || [] // because we guard above this should always have useful data
+
+    const doc = this.#doc
+    if (!doc) throw new Error("Document not available")
+
+    // If first argument is a DocHandle
+    if (first instanceof DocHandle) {
+      if (!first.isReady()) {
+        throw new Error("Cannot diff against a handle that isn't ready")
+      }
+      const otherHeads = first.heads()
+      if (!otherHeads) throw new Error("Other document's heads not available")
+
+      // Create a temporary merged doc to verify shared history and compute diff
+      const mergedDoc = A.merge(A.clone(doc), first.docSync()!)
+      // Use the merged doc to compute the diff
+      return A.diff(
+        mergedDoc,
+        decodeHeads(this.heads()!),
+        decodeHeads(otherHeads)
+      )
+    }
+
+    // Otherwise treat as heads
+    const from = second ? first : ((this.heads() || []) as UrlHeads)
     const to = second ? second : first
-    return A.diff(this.#doc, from, to)
+    return A.diff(doc, decodeHeads(from), decodeHeads(to))
   }
 
   /**
@@ -390,11 +457,15 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     if (!this.isReady()) {
       return undefined
     }
+
     if (!change) {
       change = this.heads()![0]
     }
     // we return undefined instead of null by convention in this API
-    return A.inspectChange(this.#doc, change) || undefined
+    return (
+      A.inspectChange(this.#doc, decodeHeads([change] as UrlHeads)[0]) ||
+      undefined
+    )
   }
 
   /**
@@ -420,13 +491,13 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * Called by the repo either when a doc handle changes or we receive new remote heads.
    * @hidden
    */
-  setRemoteHeads(storageId: StorageId, heads: A.Heads) {
+  setRemoteHeads(storageId: StorageId, heads: UrlHeads) {
     this.#remoteHeads[storageId] = heads
     this.emit("remote-heads", { storageId, heads })
   }
 
   /** Returns the heads of the storageId. */
-  getRemoteHeads(storageId: StorageId): A.Heads | undefined {
+  getRemoteHeads(storageId: StorageId): UrlHeads | undefined {
     return this.#remoteHeads[storageId]
   }
 
@@ -451,6 +522,13 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
         `DocHandle#${this.documentId} is in ${this.state} and not ready. Check \`handle.isReady()\` before accessing the document.`
       )
     }
+
+    if (this.#fixedHeads) {
+      throw new Error(
+        `DocHandle#${this.documentId} is in view-only mode at specific heads. Use clone() to create a new document from this state.`
+      )
+    }
+
     this.#machine.send({
       type: UPDATE,
       payload: { callback: doc => A.change(doc, options, callback) },
@@ -462,22 +540,29 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    * @returns A set of heads representing the concurrent change that was made.
    */
   changeAt(
-    heads: A.Heads,
+    heads: UrlHeads,
     callback: A.ChangeFn<T>,
     options: A.ChangeOptions<T> = {}
-  ): string[] | undefined {
+  ): UrlHeads[] | undefined {
     if (!this.isReady()) {
       throw new Error(
         `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before accessing the document.`
       )
     }
-    let resultHeads: string[] | undefined = undefined
+    if (this.#fixedHeads) {
+      throw new Error(
+        `DocHandle#${this.documentId} is in view-only mode at specific heads. Use clone() to create a new document from this state.`
+      )
+    }
+    let resultHeads: UrlHeads | undefined = undefined
     this.#machine.send({
       type: UPDATE,
       payload: {
         callback: doc => {
-          const result = A.changeAt(doc, heads, options, callback)
-          resultHeads = result.newHeads || undefined
+          const result = A.changeAt(doc, decodeHeads(heads), options, callback)
+          resultHeads = result.newHeads
+            ? encodeHeads(result.newHeads)
+            : undefined
           return result.newDoc
         },
       },
@@ -502,6 +587,11 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     if (!this.isReady() || !otherHandle.isReady()) {
       throw new Error("Both handles must be ready to merge")
     }
+    if (this.#fixedHeads) {
+      throw new Error(
+        `DocHandle#${this.documentId} is in view-only mode at specific heads. Use clone() to create a new document from this state.`
+      )
+    }
     const mergingDoc = otherHandle.docSync()
     if (!mergingDoc) {
       throw new Error("The document to be merged in is falsy, aborting.")
@@ -577,6 +667,9 @@ export type DocHandleOptions<T> =
   | {
       isNew?: false
 
+      // An optional point in time to lock the document to.
+      heads?: UrlHeads
+
       /** The number of milliseconds before we mark this document as unavailable if we don't have it and nobody shares it with us. */
       timeoutDelay?: number
     }
@@ -640,7 +733,7 @@ export interface DocHandleOutboundEphemeralMessagePayload<T> {
 /** Emitted when we have new remote heads for this document */
 export interface DocHandleRemoteHeadsPayload {
   storageId: StorageId
-  heads: A.Heads
+  heads: UrlHeads
 }
 
 // STATE MACHINE TYPES & CONSTANTS

package/src/RemoteHeadsSubscriptions.ts

@@ -1,4 +1,3 @@
-import { next as A } from "@automerge/automerge/slim"
 import { EventEmitter } from "eventemitter3"
 import { DocumentId, PeerId } from "./types.js"
 import {
@@ -7,12 +6,13 @@ import {
 } from "./network/messages.js"
 import { StorageId } from "./index.js"
 import debug from "debug"
+import { UrlHeads } from "./AutomergeUrl.js"
 
 // Notify a DocHandle that remote heads have changed
 export type RemoteHeadsSubscriptionEventPayload = {
   documentId: DocumentId
   storageId: StorageId
-  remoteHeads: A.Heads
+  remoteHeads: UrlHeads
   timestamp: number
 }
 
@@ -21,7 +21,7 @@ export type NotifyRemoteHeadsPayload = {
   targetId: PeerId
   documentId: DocumentId
   storageId: StorageId
-  heads: A.Heads
+  heads: UrlHeads
   timestamp: number
 }
 
@@ -216,7 +216,7 @@ export class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSubscripti
   handleImmediateRemoteHeadsChanged(
     documentId: DocumentId,
     storageId: StorageId,
-    heads: A.Heads
+    heads: UrlHeads
   ) {
     this.#log("handleLocalHeadsChanged", documentId, storageId, heads)
     const remote = this.#knownHeads.get(documentId)
@@ -334,7 +334,7 @@ export class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSubscripti
   #changedHeads(msg: RemoteHeadsChanged): {
     documentId: DocumentId
     storageId: StorageId
-    remoteHeads: A.Heads
+    remoteHeads: UrlHeads
     timestamp: number
   }[] {
     const changedHeads = []
@@ -356,11 +356,14 @@ export class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSubscripti
       if (docRemote && docRemote.timestamp >= timestamp) {
         continue
       } else {
-        remote.set(storageId as StorageId, { timestamp, heads })
+        remote.set(storageId as StorageId, {
+          timestamp,
+          heads: heads as UrlHeads,
+        })
         changedHeads.push({
           documentId,
           storageId: storageId as StorageId,
-          remoteHeads: heads,
+          remoteHeads: heads as UrlHeads,
           timestamp,
         })
       }
@@ -371,5 +374,5 @@ export class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSubscripti
 
 type LastHeads = {
   timestamp: number
-  heads: A.Heads
+  heads: UrlHeads
 }

package/src/Repo.ts

@@ -2,8 +2,10 @@ import { next as Automerge } from "@automerge/automerge/slim"
 import debug from "debug"
 import { EventEmitter } from "eventemitter3"
 import {
+  encodeHeads,
   generateAutomergeUrl,
   interpretAsDocumentId,
+  isValidAutomergeUrl,
   parseAutomergeUrl,
 } from "./AutomergeUrl.js"
 import {
@@ -193,16 +195,20 @@ export class Repo extends EventEmitter<RepoEvents> {
       const heads = handle.getRemoteHeads(storageId)
       const haveHeadsChanged =
         message.syncState.theirHeads &&
-        (!heads || !headsAreSame(heads, message.syncState.theirHeads))
+        (!heads ||
+          !headsAreSame(heads, encodeHeads(message.syncState.theirHeads)))
 
       if (haveHeadsChanged && message.syncState.theirHeads) {
-        handle.setRemoteHeads(storageId, message.syncState.theirHeads)
+        handle.setRemoteHeads(
+          storageId,
+          encodeHeads(message.syncState.theirHeads)
+        )
 
         if (storageId && this.#remoteHeadsGossipingEnabled) {
           this.#remoteHeadsSubscriptions.handleImmediateRemoteHeadsChanged(
             message.documentId,
             storageId,
-            message.syncState.theirHeads
+            encodeHeads(message.syncState.theirHeads)
           )
         }
       }
@@ -430,19 +436,22 @@ export class Repo extends EventEmitter<RepoEvents> {
     /** The url or documentId of the handle to retrieve */
     id: AnyDocumentId
   ): DocHandle<T> {
-    const documentId = interpretAsDocumentId(id)
+    const { documentId, heads } = isValidAutomergeUrl(id)
+      ? parseAutomergeUrl(id)
+      : { documentId: interpretAsDocumentId(id), heads: undefined }
 
-    // If we have the handle cached, return it
-    if (this.#handleCache[documentId]) {
-      if (this.#handleCache[documentId].isUnavailable()) {
+    const cachedHandle = this.#handleCache[documentId]
+    if (cachedHandle) {
+      if (cachedHandle.isUnavailable()) {
         // this ensures that the event fires after the handle has been returned
         setTimeout(() => {
-          this.#handleCache[documentId].emit("unavailable", {
-            handle: this.#handleCache[documentId],
+          cachedHandle.emit("unavailable", {
+            handle: cachedHandle,
           })
         })
       }
-      return this.#handleCache[documentId]
+      // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+      return heads ? cachedHandle.view(heads) : cachedHandle
     }
 
     // If we don't already have the handle, make an empty one and try loading it
@@ -473,7 +482,9 @@ export class Repo extends EventEmitter<RepoEvents> {
       .catch(err => {
         this.#log("error waiting for network", { err })
       })
-    return handle
+
+    // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+    return heads ? handle.view(heads) : handle
   }
 
   delete(

package/src/helpers/bufferFromHex.ts

@@ -0,0 +1,14 @@
+export const uint8ArrayFromHexString = (hexString: string): Uint8Array => {
+  if (hexString.length % 2 !== 0) {
+    throw new Error("Hex string must have an even length")
+  }
+  const bytes = new Uint8Array(hexString.length / 2)
+  for (let i = 0; i < hexString.length; i += 2) {
+    bytes[i >> 1] = parseInt(hexString.slice(i, i + 2), 16)
+  }
+  return bytes
+}
+
+export const uint8ArrayToHexString = (data: Uint8Array): string => {
+  return Array.from(data, byte => byte.toString(16).padStart(2, "0")).join("")
+}

package/src/helpers/headsAreSame.ts

@@ -1,6 +1,6 @@
-import { Heads } from "@automerge/automerge/slim/next"
 import { arraysAreEqual } from "./arraysAreEqual.js"
+import { UrlHeads } from "../AutomergeUrl.js"
 
-export const headsAreSame = (a: Heads, b: Heads) => {
+export const headsAreSame = (a: UrlHeads, b: UrlHeads) => {
   return arraysAreEqual(a, b)
 }

package/src/helpers/tests/storage-adapter-tests.ts

@@ -67,20 +67,16 @@ export function runStorageAdapterTests(setup: SetupFn, title?: string): void {
         await adapter.save(["AAAAA", "snapshot", "yyyyy"], PAYLOAD_B())
         await adapter.save(["AAAAA", "sync-state", "zzzzz"], PAYLOAD_C())
 
-        expect(await adapter.loadRange(["AAAAA"])).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-            { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
-            { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
-
-        expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-            { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
+        expect(await adapter.loadRange(["AAAAA"])).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+          { key: ["AAAAA", "snapshot", "yyyyy"], data: PAYLOAD_B() },
+          { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
+        ])
+
+        expect(await adapter.loadRange(["AAAAA", "sync-state"])).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+          { key: ["AAAAA", "sync-state", "zzzzz"], data: PAYLOAD_C() },
+        ])
       })
 
       it("should only load values that match they key", async ({ adapter }) => {
@@ -88,16 +84,9 @@ export function runStorageAdapterTests(setup: SetupFn, title?: string): void {
         await adapter.save(["BBBBB", "sync-state", "zzzzz"], PAYLOAD_C())
 
         const actual = await adapter.loadRange(["AAAAA"])
-        expect(actual).toStrictEqual(
-          expect.arrayContaining([
-            { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
-          ])
-        )
-        expect(actual).toStrictEqual(
-          expect.not.arrayContaining([
-            { key: ["BBBBB", "sync-state", "zzzzz"], data: PAYLOAD_C() },
-          ])
-        )
+        expect(actual).toStrictEqual([
+          { key: ["AAAAA", "sync-state", "xxxxx"], data: PAYLOAD_A() },
+        ])
       })
     })
 

package/src/storage/StorageSubsystem.ts

@@ -9,6 +9,7 @@ import { keyHash, headsHash } from "./keyHash.js"
 import { chunkTypeFromKey } from "./chunkTypeFromKey.js"
 import * as Uuid from "uuid"
 import { EventEmitter } from "eventemitter3"
+import { encodeHeads } from "../AutomergeUrl.js"
 
 type StorageSubsystemEvents = {
   "document-loaded": (arg: {
@@ -173,6 +174,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     } else {
       await this.#saveIncremental(documentId, doc)
     }
+
     this.#storedHeads.set(documentId, A.getHeads(doc))
   }
 
@@ -279,7 +281,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     }
 
     const newHeads = A.getHeads(doc)
-    if (headsAreSame(newHeads, oldHeads)) {
+    if (headsAreSame(encodeHeads(newHeads), encodeHeads(oldHeads))) {
       // the document hasn't changed
       return false
     }

package/src/types.ts

@@ -27,8 +27,11 @@ export type AnyDocumentId =
   | BinaryDocumentId
   | LegacyDocumentId
 
+// We need to define our own version of heads because the AutomergeHeads type is not bs58check encoded
+export type UrlHeads = string[] & { __automergeUrlHeads: unknown }
+
 /** A branded type for peer IDs */
 export type PeerId = string & { __peerId: true }
 
 /** A randomly generated string created when the {@link Repo} starts up */
-export type SessionId = string & { __SessionId: true }
+export type SessionId = string & { __sessionId: true }