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

package/dist/synchronizer/DocSynchronizer.js

@@ -19,11 +19,15 @@ export class DocSynchronizer extends Synchronizer {
     /** Sync state for each peer we've communicated with (including inactive peers) */
     #syncStates = {};
     #pendingSyncMessages = [];
+    // We keep this around at least in part for debugging.
+    // eslint-disable-next-line no-unused-private-class-members
+    #peerId;
     #syncStarted = false;
     #handle;
     #onLoadSyncState;
-    constructor({ handle, onLoadSyncState }) {
+    constructor({ handle, peerId, onLoadSyncState }) {
         super();
+        this.#peerId = peerId;
         this.#handle = handle;
         this.#onLoadSyncState =
             onLoadSyncState ?? (() => Promise.resolve(undefined));
@@ -33,7 +37,6 @@ export class DocSynchronizer extends Synchronizer {
         handle.on("ephemeral-message-outbound", payload => this.#broadcastToPeers(payload));
         // Process pending sync messages immediately after the handle becomes ready.
         void (async () => {
-            await handle.doc([READY, REQUESTING]);
             this.#processAllPendingSyncMessages();
         })();
     }
@@ -45,11 +48,14 @@ export class DocSynchronizer extends Synchronizer {
     }
     /// PRIVATE
     async #syncWithPeers() {
-        this.#log(`syncWithPeers`);
-        const doc = await this.#handle.doc();
-        if (doc === undefined)
-            return;
-        this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
+        try {
+            await this.#handle.whenReady();
+            const doc = this.#handle.doc(); // XXX THIS ONE IS WEIRD
+            this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
+        }
+        catch (e) {
+            console.log("sync with peers threw an exception");
+        }
     }
     async #broadcastToPeers({ data, }) {
         this.#log(`broadcastToPeers`, this.#peers);
@@ -151,25 +157,24 @@ export class DocSynchronizer extends Synchronizer {
     hasPeer(peerId) {
         return this.#peers.includes(peerId);
     }
-    beginSync(peerIds) {
-        const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
-        // At this point if we don't have anything in our storage, we need to use an empty doc to sync
-        // with; but we don't want to surface that state to the front end
-        const docPromise = this.#handle
-            .doc([READY, REQUESTING, UNAVAILABLE])
-            .then(doc => {
-            // we register out peers first, then say that sync has started
+    async beginSync(peerIds) {
+        void this.#handle
+            .whenReady([READY, REQUESTING, UNAVAILABLE])
+            .then(() => {
+            this.#syncStarted = true;
+            this.#checkDocUnavailable();
+        })
+            .catch(e => {
+            console.log("caught whenready", e);
             this.#syncStarted = true;
             this.#checkDocUnavailable();
-            const wasUnavailable = doc === undefined;
-            if (wasUnavailable && noPeersWithDocument) {
-                return;
-            }
-            // If the doc is unavailable we still need a blank document to generate
-            // the sync message from
-            return doc ?? A.init();
         });
-        this.#log(`beginSync: ${peerIds.join(", ")}`);
+        const peersWithDocument = this.#peers.some(peerId => {
+            return this.#peerDocumentStatuses[peerId] == "has";
+        });
+        if (peersWithDocument) {
+            await this.#handle.whenReady();
+        }
         peerIds.forEach(peerId => {
             this.#withSyncState(peerId, syncState => {
                 // HACK: if we have a sync state already, we round-trip it through the encoding system to make
@@ -178,11 +183,22 @@ export class DocSynchronizer extends Synchronizer {
                 // TODO: cover that case with a test and remove this hack
                 const reparsedSyncState = A.decodeSyncState(A.encodeSyncState(syncState));
                 this.#setSyncState(peerId, reparsedSyncState);
-                docPromise
-                    .then(doc => {
-                    if (doc) {
-                        this.#sendSyncMessage(peerId, doc);
+                // At this point if we don't have anything in our storage, we need to use an empty doc to sync
+                // with; but we don't want to surface that state to the front end
+                this.#handle
+                    .whenReady([READY, REQUESTING, UNAVAILABLE])
+                    .then(() => {
+                    const doc = this.#handle.isReady()
+                        ? this.#handle.doc()
+                        : A.init();
+                    const noPeersWithDocument = peerIds.every(peerId => this.#peerDocumentStatuses[peerId] in ["unavailable", "wants"]);
+                    const wasUnavailable = doc === undefined;
+                    if (wasUnavailable && noPeersWithDocument) {
+                        return;
                     }
+                    // If the doc is unavailable we still need a blank document to generate
+                    // the sync message from
+                    this.#sendSyncMessage(peerId, doc ?? A.init());
                 })
                     .catch(err => {
                     this.#log(`Error loading doc for ${peerId}: ${err}`);

package/fuzz/fuzz.ts

@@ -107,9 +107,9 @@ for (let i = 0; i < 100000; i++) {
   })
 
   await pause(0)
-  const a = await aliceRepo.find(doc.url).doc()
-  const b = await bobRepo.find(doc.url).doc()
-  const c = await charlieRepo.find(doc.url).doc()
+  const a = (await aliceRepo.find(doc.url)).doc()
+  const b = (await bobRepo.find(doc.url)).doc()
+  const c = (await charlieRepo.find(doc.url)).doc()
   assert.deepStrictEqual(a, b, "A and B should be equal")
   assert.deepStrictEqual(b, c, "B and C should be equal")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.0.0-alpha.20",
+  "version": "2.0.0-alpha.23",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -20,6 +20,7 @@
   },
   "devDependencies": {
     "http-server": "^14.1.0",
+    "ts-node": "^10.9.2",
     "vite": "^5.0.8"
   },
   "dependencies": {
@@ -29,8 +30,6 @@
     "debug": "^4.3.4",
     "eventemitter3": "^5.0.1",
     "fast-sha256": "^1.3.0",
-    "tiny-typed-emitter": "^2.1.0",
-    "ts-node": "^10.9.1",
     "uuid": "^9.0.0",
     "xstate": "^5.9.1"
   },
@@ -60,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d53bc37be0fd923ff40f3cf7e2bd06a0496ddb73"
+  "gitHead": "82a9bed7cc6a92940f3aa68167f6990123dda58e"
 }

package/src/DocHandle.ts

@@ -83,12 +83,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 */
@@ -276,52 +276,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
-    }
-    // If we have fixed heads, return a view at those heads
+  doc() {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
     if (this.#fixedHeads) {
-      const doc = this.#doc
-      if (!doc || this.isUnavailable()) return undefined
-      return A.view(doc, decodeHeads(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
-    if (this.#fixedHeads) {
-      const doc = this.#doc
-      return doc ? A.view(doc, decodeHeads(this.#fixedHeads)) : undefined
-    }
-    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()
   }
 
   /**
@@ -329,8 +305,8 @@ 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(): UrlHeads | undefined {
-    if (!this.isReady()) return undefined
+  heads(): UrlHeads {
+    if (!this.isReady()) throw new Error("DocHandle is not ready")
     if (this.#fixedHeads) {
       return this.#fixedHeads
     }
@@ -365,8 +341,8 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
   }
 
   /**
-   * 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
+   * 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 doc() and will return
    * undefined if the object hasn't finished loading.
    *
    * @remarks
@@ -426,7 +402,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
       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()!)
+      const mergedDoc = A.merge(A.clone(doc), first.doc()!)
       // Use the merged doc to compute the diff
       return A.diff(
         mergedDoc,
@@ -591,10 +567,7 @@ export class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
         `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.")
-    }
+    const mergingDoc = otherHandle.doc()
 
     this.update(doc => {
       return A.merge(doc, mergingDoc)
@@ -641,7 +614,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)),
     })
   }
 
@@ -680,7 +653,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>

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/Repo.ts

@@ -39,6 +39,8 @@ import type {
   DocumentId,
   PeerId,
 } from "./types.js"
+import { abortable, AbortOptions } from "./helpers/abortable.js"
+import { FindProgress, FindProgressWithMethods } from "./FindProgress.js"
 
 function randomPeerId() {
   return ("peer-" + Math.random().toString(36).slice(4)) as PeerId
@@ -260,18 +262,8 @@ export class Repo extends EventEmitter<RepoEvents> {
       handle.on("heads-changed", throttle(saveFn, this.saveDebounceRate))
     }
 
-    handle.on("unavailable", () => {
-      this.#log("document unavailable", { documentId: handle.documentId })
-      this.emit("unavailable-document", {
-        documentId: handle.documentId,
-      })
-    })
-
     // Register the document with the synchronizer. This advertises our interest in the document.
-    this.synchronizer.addDocument(handle.documentId)
-
-    // Preserve the old event in case anyone was using it.
-    this.emit("document", { handle })
+    this.synchronizer.addDocument(handle)
   }
 
   #receiveMessage(message: RepoMessage) {
@@ -402,8 +394,6 @@ export class Repo extends EventEmitter<RepoEvents> {
    * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
    * be notified of the newly created DocHandle.
    *
-   * @throws if the cloned handle is not yet ready or if
-   * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
    */
   clone<T>(clonedHandle: DocHandle<T>) {
     if (!clonedHandle.isReady()) {
@@ -413,11 +403,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       )
     }
 
-    const sourceDoc = clonedHandle.docSync()
-    if (!sourceDoc) {
-      throw new Error("Cloned handle doesn't have a document.")
-    }
-
+    const sourceDoc = clonedHandle.doc()
     const handle = this.create<T>()
 
     handle.update(() => {
@@ -428,63 +414,196 @@ export class Repo extends EventEmitter<RepoEvents> {
     return handle
   }
 
-  /**
-   * Retrieves a document by id. It gets data from the local system, but also emits a `document`
-   * event to advertise interest in the document.
-   */
-  find<T>(
-    /** The url or documentId of the handle to retrieve */
-    id: AnyDocumentId
-  ): DocHandle<T> {
+  findWithProgress<T>(
+    id: AnyDocumentId,
+    options: AbortOptions = {}
+  ): FindProgressWithMethods<T> | FindProgress<T> {
+    const { signal } = options
+    const abortPromise = abortable(signal)
+
     const { documentId, heads } = isValidAutomergeUrl(id)
       ? parseAutomergeUrl(id)
       : { documentId: interpretAsDocumentId(id), heads: undefined }
 
-    const cachedHandle = this.#handleCache[documentId]
-    if (cachedHandle) {
-      if (cachedHandle.isUnavailable()) {
-        // this ensures that the event fires after the handle has been returned
-        setTimeout(() => {
-          cachedHandle.emit("unavailable", {
-            handle: cachedHandle,
-          })
-        })
+    // Check cache first - return plain FindStep for terminal states
+    if (this.#handleCache[documentId]) {
+      const handle = this.#handleCache[documentId]
+      if (handle.state === UNAVAILABLE) {
+        const result = {
+          state: "unavailable" as const,
+          error: new Error(`Document ${id} is unavailable`),
+          handle,
+        }
+        return result
+      }
+      if (handle.state === DELETED) {
+        return {
+          state: "failed",
+          error: new Error(`Document ${id} was deleted`),
+          handle,
+        }
+      }
+      if (handle.state === READY) {
+        // If we already have the handle, return it immediately (or a view of the handle if heads are specified)
+        return {
+          state: "ready",
+          // TODO: this handle needs to be cached (or at least avoid running clone)
+          handle: heads ? handle.view(heads) : handle,
+        }
       }
-      // 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
-    const handle = this.#getHandle<T>({
-      documentId,
-    }) as DocHandle<T>
+    // the generator takes over `this`, so we need an alias to the repo this
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const that = this
+    async function* progressGenerator(): AsyncGenerator<FindProgress<T>> {
+      try {
+        const handle = that.#getHandle<T>({ documentId })
+        yield { state: "loading", progress: 25, handle }
 
-    // Loading & network is going to be asynchronous no matter what,
-    // but we want to return the handle immediately.
-    const attemptLoad = this.storageSubsystem
-      ? this.storageSubsystem.loadDoc(handle.documentId)
-      : Promise.resolve(null)
+        const loadingPromise = await (that.storageSubsystem
+          ? that.storageSubsystem.loadDoc(handle.documentId)
+          : Promise.resolve(null))
+
+        const loadedDoc = await Promise.race([loadingPromise, abortPromise])
 
-    attemptLoad
-      .then(async loadedDoc => {
         if (loadedDoc) {
-          // uhhhh, sorry if you're reading this because we were lying to the type system
           handle.update(() => loadedDoc as Automerge.Doc<T>)
           handle.doneLoading()
+          yield { state: "loading", progress: 50, handle }
         } else {
-          // we want to wait for the network subsystem to be ready before
-          // we request the document. this prevents entering unavailable during initialization.
-          await this.networkSubsystem.whenReady()
+          await Promise.race([that.networkSubsystem.whenReady(), abortPromise])
           handle.request()
+          yield { state: "loading", progress: 75, handle }
         }
-        this.#registerHandleWithSubsystems(handle)
-      })
-      .catch(err => {
-        this.#log("error waiting for network", { err })
-      })
 
-    // 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
+        that.#registerHandleWithSubsystems(handle)
+
+        await Promise.race([
+          handle.whenReady([READY, UNAVAILABLE]),
+          abortPromise,
+        ])
+
+        if (handle.state === UNAVAILABLE) {
+          yield { state: "unavailable", handle }
+        }
+        if (handle.state === DELETED) {
+          throw new Error(`Document ${id} was deleted`)
+        }
+
+        yield { state: "ready", handle }
+      } catch (error) {
+        yield {
+          state: "failed",
+          error: error instanceof Error ? error : new Error(String(error)),
+          handle,
+        }
+      }
+    }
+
+    const iterator = progressGenerator()
+
+    const next = async () => {
+      const result = await iterator.next()
+      return { ...result.value, next }
+    }
+
+    const untilReady = async (allowableStates: string[]) => {
+      for await (const state of iterator) {
+        if (allowableStates.includes(state.handle.state)) {
+          return state.handle
+        }
+        if (state.state === "unavailable") {
+          throw new Error(`Document ${id} is unavailable`)
+        }
+        if (state.state === "ready") return state.handle
+        if (state.state === "failed") throw state.error
+      }
+      throw new Error("Iterator completed without reaching ready state")
+    }
+
+    const handle = this.#getHandle<T>({ documentId })
+    const initial = { state: "loading" as const, progress: 0, handle }
+    return { ...initial, next, untilReady }
+  }
+
+  async find<T>(
+    id: AnyDocumentId,
+    options: RepoFindOptions & AbortOptions = {}
+  ): Promise<DocHandle<T>> {
+    const { allowableStates = ["ready"], signal } = options
+    const progress = this.findWithProgress<T>(id, { signal })
+
+    /*if (allowableStates.includes(progress.state)) {
+      console.log("returning early")
+      return progress.handle
+    }*/
+
+    if ("untilReady" in progress) {
+      this.#registerHandleWithSubsystems(progress.handle)
+      return progress.untilReady(allowableStates)
+    } else {
+      return progress.handle
+    }
+  }
+
+  /**
+   * Loads a document without waiting for ready state
+   */
+  async #loadDocument<T>(documentId: DocumentId): Promise<DocHandle<T>> {
+    // If we have the handle cached, return it
+    if (this.#handleCache[documentId]) {
+      return this.#handleCache[documentId]
+    }
+
+    // If we don't already have the handle, make an empty one and try loading it
+    const handle = this.#getHandle<T>({ documentId })
+    const loadedDoc = await (this.storageSubsystem
+      ? this.storageSubsystem.loadDoc(handle.documentId)
+      : Promise.resolve(null))
+
+    if (loadedDoc) {
+      // We need to cast this to <T> because loadDoc operates in <unknowns>.
+      // This is really where we ought to be validating the input matches <T>.
+      handle.update(() => loadedDoc as Automerge.Doc<T>)
+      handle.doneLoading()
+    } else {
+      // Because the network subsystem might still be booting up, we wait
+      // here so that we don't immediately give up loading because we're still
+      // making our initial connection to a sync server.
+      await this.networkSubsystem.whenReady()
+      handle.request()
+    }
+
+    this.#registerHandleWithSubsystems(handle)
+    return handle
+  }
+
+  /**
+   * Retrieves a document by id. It gets data from the local system, but also emits a `document`
+   * event to advertise interest in the document.
+   */
+  async findClassic<T>(
+    /** The url or documentId of the handle to retrieve */
+    id: AnyDocumentId,
+    options: RepoFindOptions & AbortOptions = {}
+  ): Promise<DocHandle<T>> {
+    const documentId = interpretAsDocumentId(id)
+    const { allowableStates, signal } = options
+
+    return Promise.race([
+      (async () => {
+        const handle = await this.#loadDocument<T>(documentId)
+        if (!allowableStates) {
+          await handle.whenReady([READY, UNAVAILABLE])
+          if (handle.state === UNAVAILABLE && !signal?.aborted) {
+            throw new Error(`Document ${id} is unavailable`)
+          }
+        }
+        return handle
+      })(),
+      abortable(signal),
+    ])
   }
 
   delete(
@@ -511,8 +630,7 @@ export class Repo extends EventEmitter<RepoEvents> {
     const documentId = interpretAsDocumentId(id)
 
     const handle = this.#getHandle({ documentId })
-    const doc = await handle.doc()
-    if (!doc) return undefined
+    const doc = handle.doc()
     return Automerge.save(doc)
   }
 
@@ -566,11 +684,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       : Object.values(this.#handleCache)
     await Promise.all(
       handles.map(async handle => {
-        const doc = handle.docSync()
-        if (!doc) {
-          return
-        }
-        return this.storageSubsystem!.saveDoc(handle.documentId, doc)
+        return this.storageSubsystem!.saveDoc(handle.documentId, handle.doc())
       })
     )
   }
@@ -589,7 +703,9 @@ export class Repo extends EventEmitter<RepoEvents> {
       return
     }
     const handle = this.#getHandle({ documentId })
-    const doc = await handle.doc([READY, UNLOADED, DELETED, UNAVAILABLE])
+    await handle.whenReady([READY, UNLOADED, DELETED, UNAVAILABLE])
+    const doc = handle.doc()
+    // because this is an internal-ish function, we'll be extra careful about undefined docs here
     if (doc) {
       if (handle.isReady()) {
         handle.unload()
@@ -677,6 +793,10 @@ export interface RepoEvents {
   "doc-metrics": (arg: DocMetrics) => void
 }
 
+export interface RepoFindOptions {
+  allowableStates?: string[]
+}
+
 export interface DocumentPayload {
   handle: DocHandle<any>
 }