@automerge/automerge-repo 2.0.0-alpha.2 → 2.0.0-alpha.20

package/src/DocHandle.ts

@@ -2,11 +2,15 @@ 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,
+} from "./AutomergeUrl.js"
 import { encode } from "./helpers/cbor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { withTimeout } from "./helpers/withTimeout.js"
-import type { AutomergeUrl, DocumentId, PeerId } from "./types.js"
+import type { AutomergeUrl, DocumentId, PeerId, UrlHeads } from "./types.js"
 import { StorageId } from "./storage/types.js"
 
 /**
@@ -28,6 +32,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 +43,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 +56,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)}`)
@@ -72,6 +83,9 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
           this.emit("delete", { handle: this })
           return { doc: A.init() }
         }),
+        onUnload: assign(() => {
+          return { doc: A.init() }
+        }),
         onUnavailable: () => {
           this.emit("unavailable", { handle: this })
         },
@@ -86,6 +100,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       context: { documentId, doc },
       on: {
         UPDATE: { actions: "onUpdate" },
+        UNLOAD: ".unloaded",
         DELETE: ".deleted",
       },
       states: {
@@ -113,6 +128,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
           on: { DOC_READY: "ready" },
         },
         ready: {},
+        unloaded: {
+          entry: "onUnload",
+          on: {
+            RELOAD: "loading",
+          },
+        },
         deleted: { entry: "onDelete", type: "final" },
       },
     })
@@ -131,7 +152,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
 
     // Start the machine, and send a create or find event to get things going
     this.#machine.start()
-    this.#machine.send({ type: BEGIN })
+    this.begin()
   }
 
   // PRIVATE
@@ -166,7 +187,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 })
 
@@ -192,7 +216,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,
+    })
   }
 
   /**
@@ -203,6 +230,14 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
    */
   isReady = () => this.inState(["ready"])
 
+  /**
+   * @returns true if the document has been unloaded.
+   *
+   * Unloaded documents are freed from memory but not removed from local storage. It's not currently
+   * possible at runtime to reload an unloaded document.
+   */
+  isUnloaded = () => this.inState(["unloaded"])
+
   /**
    * @returns true if the document has been marked as deleted.
    *
@@ -257,6 +292,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
   }
@@ -276,7 +317,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
   }
 
   /**
@@ -284,11 +329,142 @@ 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 {
+  heads(): UrlHeads | undefined {
+    if (!this.isReady()) return undefined
+    if (this.#fixedHeads) {
+      return this.#fixedHeads
+    }
+    return encodeHeads(A.getHeads(this.#doc))
+  }
+
+  begin() {
+    this.#machine.send({ type: BEGIN })
+  }
+
+  /**
+   * 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
+   * concurrent edits. This API just returns a topologically sorted history of all edits
+   * so every previous entry will be (in some sense) before later ones, but the set of all possible
+   * 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 UrlHeads[] - The individual heads for every change in the document. Each item is a tagged string[1].
+   */
+  history(): UrlHeads[] | undefined {
     if (!this.isReady()) {
       return undefined
     }
-    return A.getHeads(this.#doc)
+    // This just returns all the heads as individual strings.
+
+    return A.topoHistoryTraversal(this.#doc).map(h =>
+      encodeHeads([h])
+    ) as UrlHeads[]
+  }
+
+  /**
+   * 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.
+   *
+   * @remarks
+   * Note that our Typescript types do not consider change over time and the current version
+   * 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.
+   *
+   * @argument heads - The heads to view the document at. See history().
+   * @returns DocHandle<T> at the time of `heads`
+   */
+  view(heads: UrlHeads): DocHandle<T> {
+    if (!this.isReady()) {
+      throw new Error(
+        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling view().`
+      )
+    }
+    // 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
+  }
+
+  /**
+   * Returns a set of Patch operations that will move a materialized document from one state to another
+   * if applied.
+   *
+   * @remarks
+   * 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)
+   *
+   * @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: UrlHeads | DocHandle<T>, second?: UrlHeads): A.Patch[] {
+    if (!this.isReady()) {
+      throw new Error(
+        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before calling diff().`
+      )
+    }
+
+    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(doc, decodeHeads(from), decodeHeads(to))
+  }
+
+  /**
+   * `metadata(head?)` allows you to look at the metadata for a change
+   * this can be used to build history graphs to find commit messages and edit times.
+   * this interface.
+   *
+   * @remarks
+   * I'm really not convinced this is the right way to surface this information so
+   * I'm leaving this API "hidden".
+   *
+   * @hidden
+   */
+  metadata(change?: string): A.DecodedChange | undefined {
+    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, decodeHeads([change] as UrlHeads)[0]) ||
+      undefined
+    )
   }
 
   /**
@@ -314,13 +490,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]
   }
 
@@ -345,6 +521,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) },
@@ -356,22 +539,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
         },
       },
@@ -396,6 +586,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.")
@@ -421,6 +616,16 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     if (this.#state === "loading") this.#machine.send({ type: REQUEST })
   }
 
+  /** Called by the repo to free memory used by the document. */
+  unload() {
+    this.#machine.send({ type: UNLOAD })
+  }
+
+  /** Called by the repo to reuse an unloaded handle. */
+  reload() {
+    this.#machine.send({ type: RELOAD })
+  }
+
   /** Called by the repo when the document is deleted. */
   delete() {
     this.#machine.send({ type: DELETE })
@@ -439,6 +644,10 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       data: encode(message),
     })
   }
+
+  metrics(): { numOps: number; numChanges: number } {
+    return A.stats(this.#doc)
+  }
 }
 
 //  TYPES
@@ -457,6 +666,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
     }
@@ -520,7 +732,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
@@ -539,6 +751,8 @@ export const HandleState = {
   REQUESTING: "requesting",
   /** The document is available */
   READY: "ready",
+  /** The document has been unloaded from the handle, to free memory usage */
+  UNLOADED: "unloaded",
   /** The document has been deleted from the repo */
   DELETED: "deleted",
   /** The document was not available in storage or from any connected peers */
@@ -546,8 +760,15 @@ export const HandleState = {
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]
 
-export const { IDLE, LOADING, REQUESTING, READY, DELETED, UNAVAILABLE } =
-  HandleState
+export const {
+  IDLE,
+  LOADING,
+  REQUESTING,
+  READY,
+  UNLOADED,
+  DELETED,
+  UNAVAILABLE,
+} = HandleState
 
 // context
 
@@ -567,14 +788,18 @@ type DocHandleEvent<T> =
       type: typeof UPDATE
       payload: { callback: (doc: A.Doc<T>) => A.Doc<T> }
     }
-  | { type: typeof TIMEOUT }
+  | { type: typeof UNLOAD }
+  | { type: typeof RELOAD }
   | { type: typeof DELETE }
+  | { type: typeof TIMEOUT }
   | { type: typeof DOC_UNAVAILABLE }
 
 const BEGIN = "BEGIN"
 const REQUEST = "REQUEST"
 const DOC_READY = "DOC_READY"
 const UPDATE = "UPDATE"
+const UNLOAD = "UNLOAD"
+const RELOAD = "RELOAD"
 const DELETE = "DELETE"
 const TIMEOUT = "TIMEOUT"
 const DOC_UNAVAILABLE = "DOC_UNAVAILABLE"

package/src/RemoteHeadsSubscriptions.ts

@@ -1,6 +1,5 @@
-import { next as A } from "@automerge/automerge/slim"
 import { EventEmitter } from "eventemitter3"
-import { DocumentId, PeerId } from "./types.js"
+import { DocumentId, PeerId, UrlHeads } from "./types.js"
 import {
   RemoteHeadsChanged,
   RemoteSubscriptionControlMessage,
@@ -12,7 +11,7 @@ import debug from "debug"
 export type RemoteHeadsSubscriptionEventPayload = {
   documentId: DocumentId
   storageId: StorageId
-  remoteHeads: A.Heads
+  remoteHeads: UrlHeads
   timestamp: number
 }
 
@@ -21,7 +20,7 @@ export type NotifyRemoteHeadsPayload = {
   targetId: PeerId
   documentId: DocumentId
   storageId: StorageId
-  heads: A.Heads
+  heads: UrlHeads
   timestamp: number
 }
 
@@ -216,7 +215,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 +333,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 +355,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 +373,5 @@ export class RemoteHeadsSubscriptions extends EventEmitter<RemoteHeadsSubscripti
 
 type LastHeads = {
   timestamp: number
-  heads: A.Heads
+  heads: UrlHeads
 }