@automerge/automerge-repo 2.0.0-alpha.7 → 2.0.0-beta.1

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,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,9 +86,12 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
           this.emit("delete", { handle: this })
           return { doc: A.init() }
         }),
-        onUnavailable: () => {
-          this.emit("unavailable", { handle: this })
-        },
+        onUnavailable: assign(() => {
+          return { doc: A.init() }
+        }),
+        onUnload: assign(() => {
+          return { doc: A.init() }
+        }),
       },
     }).createMachine({
       /** @xstate-layout N4IgpgJg5mDOIC5QAoC2BDAxgCwJYDswBKAYgFUAFAEQEEAVAUQG0AGAXUVAAcB7WXAC64e+TiAAeiAOwAOAKwA6ACxSAzKqks1ATjlTdAGhABPRAFolAJksKN2y1KtKAbFLla5AX09G0WPISkVAwAMgyMrBxIILz8QiJikggAjCzOijKqLEqqybJyLizaRqYIFpbJtro5Uo7J2o5S3r4YOATECrgQADZgJADCAEoM9MzsYrGCwqLRSeoyCtra8pa5adquySXmDjY5ac7JljLJeepKzSB+bYGdPX0AYgCSAHJUkRN8UwmziM7HCgqyVcUnqcmScmcMm2ZV2yiyzkOx1OalUFx8V1aAQ63R46AgBCgJGGAEUyAwAMp0D7RSbxGagJKHFgKOSWJTJGRSCosCpKaEmRCqbQKU5yXINeTaer6LwY67YogKXH4wkkKgAeX6AH1hjQqABNGncL70xKIJQ5RY5BHOJag6wwpRyEWImQVeT1aWrVSXBXtJUqgn4Ik0ADqNCedG1L3CYY1gwA0saYqbpuaEG4pKLksKpFDgcsCjDhTnxTKpTLdH6sQGFOgAO7oKYhl5gAQNngAJwA1iRY3R40ndSNDSm6enfpm5BkWAVkvy7bpuTCKq7ndZnfVeSwuTX-HWu2AAI4AVzgQhD6q12rILxoADVIyEaAAhMLjtM-RmIE4LVSQi4nLLDIGzOCWwLKA0cgyLBoFWNy+43B0R5nheaqajqepjuMtJfgyEh-FoixqMCoKqOyhzgYKCDOq6UIeuCSxHOoSGKgop74OgABuzbdOgABGvTXlho5GrhJpxJOP4pLulT6KoMhpJY2hzsWNF0QobqMV6LG+pc+A8BAcBiP6gSfFJ36EQgKksksKxrHamwwmY7gLKB85QjBzoAWxdZdL0FnfARST8ooLC7qoTnWBU4pyC5ViVMKBQaHUDQuM4fm3EGhJBWaU7-CysEAUp3LpEpWw0WYRw2LmqzgqciIsCxWUdI2zaXlAbYdt2PZ5dJ1n5jY2iJY1ikOIcMJHCyUWHC62hRZkUVNPKta3Kh56wJ1-VWUyzhFc64JWJCtQNBBzhQW4cHwbsrVKpxPF8YJgV4ZZIWIKkiKiiNSkqZYWjzCWaQ5hFh0AcCuR3QoR74qUknBRmzholpv3OkpRQNNRpTzaKTWKbIWR5FDxm9AIkA7e9skUYCWayLILBZGoLkUSKbIyIdpxHPoyTeN4QA */
@@ -86,6 +103,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       context: { documentId, doc },
       on: {
         UPDATE: { actions: "onUpdate" },
+        UNLOAD: ".unloaded",
         DELETE: ".deleted",
       },
       states: {
@@ -113,6 +131,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 +155,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 +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 })
 
@@ -192,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,
+    })
   }
 
   /**
@@ -203,6 +233,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.
    *
@@ -241,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()
   }
 
   /**
@@ -284,17 +308,20 @@ 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() {
+    this.#machine.send({ type: BEGIN })
   }
 
   /**
-   * 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
@@ -303,49 +330,133 @@ 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.
-   * @returns
+   *
+   * @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: 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 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
+    }
+
+    // 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
   }
 
   /**
-   * 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 a set of Patch operations that will move a materialized document from one state to another
+   * 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().`
+      )
+    }
+
+    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)
+      )
     }
-    // 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
+
+    // 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))
+  }
+
+  /**
+   * `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
+    )
   }
 
   /**
@@ -368,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]
   }
 
@@ -402,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) },
@@ -413,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
         },
       },
@@ -453,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)
@@ -464,20 +591,31 @@ 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() {
     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 })
@@ -493,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)),
     })
   }
 
@@ -518,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
     }
@@ -529,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>
@@ -581,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
@@ -600,6 +740,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 */
@@ -607,8 +749,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
 
@@ -628,14 +777,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/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
 }