@automerge/automerge-repo 2.0.0-collectionsync-alpha.1 → 2.0.0

package/src/DocHandle.ts

@@ -1,12 +1,16 @@
-import * as A from "@automerge/automerge/slim/next"
+import { next as A } from "@automerge/automerge/slim"
 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,10 @@ 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> = {}
+
+  /** Cache for view handles, keyed by the stringified heads */
+  #viewCache: Map<string, DocHandle<T>> = new Map()
 
   /** @hidden */
   constructor(
@@ -49,6 +59,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,12 +86,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
           this.emit("delete", { handle: this })
           return { doc: A.init() }
         }),
+        onUnavailable: assign(() => {
+          return { doc: A.init() }
+        }),
         onUnload: assign(() => {
           return { doc: A.init() }
         }),
-        onUnavailable: () => {
-          this.emit("unavailable", { handle: this })
-        },
       },
     }).createMachine({
       /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAYgFUAFAEQEEAVAUQG0AGAXUVAAcB7WXAC64e+TiAAeiAOwAOAKwA6ACxSAzKqks1ATjlTdAGhABPRAFolAJksKN2y1KtKAbFLla5AX09G0WPISkVAwAMgyMrBxIILz8QiJikggAjCzOijKqLEqqybJyLizaRqYIFpbJtro5Uo7J2o5S3r4YOATECrgQADZgJADCAEoM9MzsYrGCwqLRSeoyCtra8pa5adquySXmDjY5ac7JljLJeepKzSB+bYGdPX0AYgCSAHJUkRN8UwmziM7HCgqyVcUnqcmScmcMm2ZV2yiyzkOx1OalUFx8V1aAQ63R46AgBCgJGGAEUyAwAMp0D7RSbxGagJKHFgKOSWJTJGRSCosCpKaEmRCqbQKU5yXINeTaer6LwY67YogKXH4wkkKgAeX6AH1hjQqABNGncL70xKIJQ5RY5BHOJag6wwpRyEWImQVeT1aWrVSXBXtJUqgn4Ik0ADqNCedG1L3CYY1gwA0saYqbpuaEG4pKLksKpFDgcsCjDhTnxTKpTLdH6sQGFOgAO7oKYhl5gAQNngAJwA1iRY3R40ndSNDSm6enfpm5BkWAVkvy7bpuTCKq7ndZnfVeSwuTX-HWu2AAI4AVzgQhD6q12rILxoADVIyEaAAhMLjtM-RmIE4LVSQi4nLLDIGzOCWwLKA0cgyLBoFWNy+43B0R5nheaqajqepjuMtJfgyEh-FoixqMCoKqOyhzgYKCDOq6UIeuCSxHOoSGKgop74OgABuzbdOgABGvTXlho5GrhJpxJOP4pLulT6KoMhpJY2hzsWNF0QobqMV6LG+pc+A8BAcBiP6gSfFJ36EQgKksksKxrHamwwmY7gLKB85QjBzoAWxdZdL0FnfARST8ooLC7qoTnWBU4pyC5ViVMKBQaHUDQuM4fm3EGhJBWaU7-CysEAUp3LpEpWw0WYRw2LmqzgqciIsCxWUdI2zaXlAbYdt2PZ5dJ1n5jY2iJY1ikOIcMJHCyUWHC62hRZkUVNPKta3Kh56wJ1-VWUyzhFc64JWJCtQNBBzhQW4cHwbsrVKpxPF8YJgV4ZZIWIKkiKiiNSkqZYWjzCWaQ5hFh0AcCuR3QoR74qUknBRmzholpv3OkpRQNNRpTzaKTWKbIWR5FDxm9AIkA7e9skUYCWayLILBZGoLkUSKbIyIdpxHPoyTeN4QA */
@@ -176,7 +190,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 +219,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,
+    })
   }
 
   /**
@@ -259,42 +279,28 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * @returns the current state of this handle's Automerge document.
+   * Returns the current state of the Automerge document this handle manages.
+   *
+   * @returns the current document
+   * @throws on deleted and unavailable documents
    *
-   * This is the recommended way to access a handle's document. Note that this waits for the handle
-   * to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
    */
-  async doc(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates: HandleState[] = ["ready", "unavailable"]
-  ) {
-    try {
-      // wait for the document to enter one of the desired states
-      await this.#statePromise(awaitStates)
-    } catch (error) {
-      // if we timed out, return undefined
-      return undefined
+  doc() {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
+    if (this.#fixedHeads) {
+      return A.view(this.#doc, decodeHeads(this.#fixedHeads))
     }
-    // Return the document
-    return !this.isUnavailable() ? this.#doc : undefined
+    return this.#doc
   }
 
   /**
-   * Synchronously returns the current state of the Automerge document this handle manages, or
-   * undefined. Consider using `await handle.doc()` instead. Check `isReady()`, or use `whenReady()`
-   * if you want to make sure loading is complete first.
-   *
-   * Not to be confused with the SyncState of the document, which describes the state of the
-   * synchronization process.
-   *
-   * Note that `undefined` is not a valid Automerge document, so the return from this function is
-   * unambigous.
    *
-   * @returns the current document, or undefined if the document is not ready.
-   */
+   * @deprecated */
   docSync() {
-    if (!this.isReady()) return undefined
-    else return this.#doc
+    console.warn(
+      "docSync is deprecated. Use doc() instead. This function will be removed as part of the 2.0 release."
+    )
+    return this.doc()
   }
 
   /**
@@ -302,11 +308,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 {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
+    if (this.#fixedHeads) {
+      return this.#fixedHeads
     }
-    return A.getHeads(this.#doc)
+    return encodeHeads(A.getHeads(this.#doc))
   }
 
   begin() {
@@ -314,9 +321,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,20 +330,22 @@ 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
-   * by the `heads` passed in. The return value is the same type as docSync() and will return
+   * by the `heads` passed in. The return value is the same type as doc() and will return
    * undefined if the object hasn't finished loading.
    *
    * @remarks
@@ -346,13 +353,37 @@ 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().`
+      )
+    }
+
+    // Create a cache key from the heads
+    const cacheKey = JSON.stringify(heads)
+
+    // Check if we have a cached handle for these heads
+    const cachedHandle = this.#viewCache.get(cacheKey)
+    if (cachedHandle) {
+      return cachedHandle
     }
-    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()
+
+    // Store in cache
+    this.#viewCache.set(cacheKey, handle)
+
+    return handle
   }
 
   /**
@@ -360,19 +391,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.doc()!)
+      // 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 +448,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
+    )
   }
 
   /**
@@ -417,16 +479,16 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Called by the repo either when a doc handle changes or we receive new remote heads.
+   * Called by the repo 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 +513,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 +531,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,10 +578,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     if (!this.isReady() || !otherHandle.isReady()) {
       throw new Error("Both handles must be ready to merge")
     }
-    const mergingDoc = otherHandle.docSync()
-    if (!mergingDoc) {
-      throw new Error("The document to be merged in is falsy, aborting.")
+    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.doc()
 
     this.update(doc => {
       return A.merge(doc, mergingDoc)
@@ -513,14 +591,15 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * Used in testing to mark this document as unavailable.
+   * Updates the internal state machine to mark the document unavailable.
    * @hidden
    */
   unavailable() {
     this.#machine.send({ type: DOC_UNAVAILABLE })
   }
 
-  /** Called by the repo when the document is not found in storage.
+  /**
+   * Called by the repo either when the document is not found in storage.
    * @hidden
    * */
   request() {
@@ -552,7 +631,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   broadcast(message: unknown) {
     this.emit("ephemeral-message-outbound", {
       handle: this,
-      data: encode(message),
+      data: new Uint8Array(encode(message)),
     })
   }
 
@@ -577,6 +656,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
     }
@@ -588,7 +670,6 @@ export interface DocHandleEvents<T> {
   "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
-  unavailable: (payload: DocHandleUnavailablePayload<T>) => void
   "ephemeral-message": (payload: DocHandleEphemeralMessagePayload<T>) => void
   "ephemeral-message-outbound": (
     payload: DocHandleOutboundEphemeralMessagePayload<T>
@@ -640,7 +721,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/FindProgress.ts

@@ -0,0 +1,48 @@
+import { DocHandle } from "./DocHandle.js"
+
+export type FindProgressState =
+  | "loading"
+  | "ready"
+  | "failed"
+  | "aborted"
+  | "unavailable"
+
+interface FindProgressBase<T> {
+  state: FindProgressState
+  handle: DocHandle<T>
+}
+
+interface FindProgressLoading<T> extends FindProgressBase<T> {
+  state: "loading"
+  progress: number
+}
+
+interface FindProgressReady<T> extends FindProgressBase<T> {
+  state: "ready"
+}
+
+interface FindProgressFailed<T> extends FindProgressBase<T> {
+  state: "failed"
+  error: Error
+}
+
+interface FindProgressUnavailable<T> extends FindProgressBase<T> {
+  state: "unavailable"
+}
+
+interface FindProgressAborted<T> extends FindProgressBase<T> {
+  state: "aborted"
+}
+
+export type FindProgress<T> =
+  | FindProgressLoading<T>
+  | FindProgressReady<T>
+  | FindProgressFailed<T>
+  | FindProgressUnavailable<T>
+  | FindProgressAborted<T>
+
+export type FindProgressWithMethods<T> = FindProgress<T> & {
+  next: () => Promise<FindProgressWithMethods<T>>
+  // TODO: i don't like this allowableStates
+  untilReady: (allowableStates: string[]) => Promise<DocHandle<T>>
+}

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
 }