@automerge/automerge-repo 0.2.1 → 1.0.0-alpha.2

package/dist/synchronizer/CollectionSynchronizer.js

@@ -1,3 +1,4 @@
+import { stringifyAutomergeUrl, } from "../DocUrl.js";
 import { DocSynchronizer } from "./DocSynchronizer.js";
 import { Synchronizer } from "./Synchronizer.js";
 import debug from "debug";
@@ -16,7 +17,7 @@ export class CollectionSynchronizer extends Synchronizer {
     /** Returns a synchronizer for the given document, creating one if it doesn't already exist.  */
     #fetchDocSynchronizer(documentId) {
         if (!this.#docSynchronizers[documentId]) {
-            const handle = this.repo.find(documentId);
+            const handle = this.repo.find(stringifyAutomergeUrl({ documentId }));
             this.#docSynchronizers[documentId] = this.#initDocSynchronizer(handle);
         }
         return this.#docSynchronizers[documentId];
@@ -46,6 +47,9 @@ export class CollectionSynchronizer extends Synchronizer {
     async receiveSyncMessage(peerId, channelId, message) {
         log(`onSyncMessage: ${peerId}, ${channelId}, ${message.byteLength}bytes`);
         const documentId = channelId;
+        if (!documentId) {
+            throw new Error("received a message with an invalid documentId");
+        }
         const docSynchronizer = await this.#fetchDocSynchronizer(documentId);
         await docSynchronizer.receiveSyncMessage(peerId, channelId, message);
         // Initiate sync with any new peers

package/dist/synchronizer/DocSynchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAanC,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC;IAgB1C,IAAI,UAAU,qCAEb;IAuED,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,MAAM,EAAE,MAAM;IAkBxB,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU;CAsCtB"}
+{"version":3,"file":"DocSynchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/DocSynchronizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAqB,MAAM,iBAAiB,CAAA;AAC9D,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIhD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,YAAY;;IAanC,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC;IAgB1C,IAAI,UAAU,qCAEb;IAwED,OAAO,CAAC,MAAM,EAAE,MAAM;IAItB,SAAS,CAAC,MAAM,EAAE,MAAM;IAkBxB,OAAO,CAAC,MAAM,EAAE,MAAM;IAKtB,kBAAkB,CAChB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,UAAU;CAsCtB"}

package/dist/synchronizer/DocSynchronizer.js

@@ -1,4 +1,5 @@
 import * as A from "@automerge/automerge";
+import { READY, REQUESTING } from "../DocHandle.js";
 import { Synchronizer } from "./Synchronizer.js";
 import debug from "debug";
 /**
@@ -25,7 +26,7 @@ export class DocSynchronizer extends Synchronizer {
         handle.on("change", () => this.#syncWithPeers());
         // Process pending sync messages immediately after the handle becomes ready.
         void (async () => {
-            await handle.loadAttemptedValue();
+            await handle.doc([READY, REQUESTING]);
             this.#processAllPendingSyncMessages();
         })();
     }
@@ -35,7 +36,7 @@ export class DocSynchronizer extends Synchronizer {
     /// PRIVATE
     async #syncWithPeers() {
         this.#log(`syncWithPeers`);
-        const doc = await this.handle.value();
+        const doc = await this.handle.doc();
         this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
     }
     #getSyncState(peerId) {
@@ -92,7 +93,7 @@ export class DocSynchronizer extends Synchronizer {
         this.#log(`beginSync: ${peerId}`);
         // 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
-        void this.handle.loadAttemptedValue().then(doc => {
+        void this.handle.doc([READY, REQUESTING]).then(doc => {
             // HACK: if we have a sync state already, we round-trip it through the encoding system to make
             // sure state is preserved. This prevents an infinite loop caused by failed attempts to send
             // messages during disconnection.
@@ -108,10 +109,10 @@ export class DocSynchronizer extends Synchronizer {
         this.#peers = this.#peers.filter(p => p !== peerId);
     }
     receiveSyncMessage(peerId, channelId, message) {
-        if (channelId !== this.documentId)
+        if (channelId !== this.handle.documentId)
             throw new Error(`channelId doesn't match documentId`);
         // We need to block receiving the syncMessages until we've checked local storage
-        if (!this.handle.isReadyOrRequesting()) {
+        if (!this.handle.inState([READY, REQUESTING])) {
             this.#pendingSyncMessages.push({ peerId, message });
             return;
         }

package/dist/types.d.ts

@@ -1,6 +1,12 @@
 export type DocumentId = string & {
     __documentId: true;
 };
+export type AutomergeUrl = string & {
+    __documentUrl: true;
+};
+export type BinaryDocumentId = Uint8Array & {
+    __binaryDocumentId: true;
+};
 export type PeerId = string & {
     __peerId: false;
 };

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAC3D,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA;AACjD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "0.2.1",
+  "version": "1.0.0-alpha.2",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -22,19 +22,22 @@
   },
   "devDependencies": {
     "@types/debug": "^4.1.7",
+    "@types/node": "^20.4.8",
     "@types/uuid": "^8.3.4",
     "@types/ws": "^8.5.3",
     "@typescript-eslint/eslint-plugin": "^5.33.0",
     "@typescript-eslint/parser": "^5.33.0",
-    "http-server": "^14.1.0"
+    "http-server": "^14.1.0",
+    "typescript": "^5.1.6"
   },
   "peerDependencies": {
-    "@automerge/automerge": "^2.1.0-alpha.8"
+    "@automerge/automerge": "^2.1.0-alpha.10"
   },
   "dependencies": {
+    "bs58check": "^3.0.1",
     "cbor-x": "^1.3.0",
     "debug": "^4.3.4",
-    "eventemitter3": "^4.0.7",
+    "eventemitter3": "^5.0.1",
     "fast-sha256": "^1.3.0",
     "tiny-typed-emitter": "^2.1.0",
     "ts-node": "^10.9.1",
@@ -62,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7f048ecaa62eb1246f54773c6b10bada0767497b"
+  "gitHead": "b5830dde8f135b694809698aaad2a9fdc79a9898"
 }

package/src/DocCollection.ts

@@ -1,8 +1,14 @@
 import EventEmitter from "eventemitter3"
-import { v4 as uuid } from "uuid"
 import { DocHandle } from "./DocHandle.js"
-import { type DocumentId } from "./types.js"
+import { DocumentId, type BinaryDocumentId, AutomergeUrl } from "./types.js"
 import { type SharePolicy } from "./Repo.js"
+import {
+  documentIdToBinary,
+  binaryToDocumentId,
+  generateAutomergeUrl,
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
+} from "./DocUrl.js"
 
 /**
  * A DocCollection is a collection of DocHandles. It supports creating new documents and finding
@@ -30,6 +36,7 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
     if (this.#handleCache[documentId]) return this.#handleCache[documentId]
 
     // If not, create a new handle, cache it, and return it
+    if (!documentId) throw new Error(`Invalid documentId ${documentId}`)
     const handle = new DocHandle<T>(documentId, { isNew })
     this.#handleCache[documentId] = handle
     return handle
@@ -64,8 +71,9 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
     // or
     // - pass a "reify" function that takes a `<any>` and returns `<T>`
 
-    const documentId = uuid() as DocumentId
-    const handle = this.#getHandle<T>(documentId, true) as DocHandle<T>
+    // Generate a new UUID and store it in the buffer
+    const { encodedDocumentId } = parseAutomergeUrl(generateAutomergeUrl())
+    const handle = this.#getHandle<T>(encodedDocumentId, true) as DocHandle<T>
     this.emit("document", { handle })
     return handle
   }
@@ -76,35 +84,37 @@ export class DocCollection extends EventEmitter<DocCollectionEvents> {
    */
   find<T>(
     /** The documentId of the handle to retrieve */
-    documentId: DocumentId
+    automergeUrl: AutomergeUrl
   ): DocHandle<T> {
-    // TODO: we want a way to make sure we don't yield intermediate document states during initial synchronization
+    if (!isValidAutomergeUrl(automergeUrl)) {
+      throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`)
+    }
 
-    // If we already have a handle, return it
-    if (this.#handleCache[documentId])
-      return this.#handleCache[documentId] as DocHandle<T>
-
-    // Otherwise, create a new handle
-    const handle = this.#getHandle<T>(documentId, false) as DocHandle<T>
-
-    // we don't directly initialize a value here because the StorageSubsystem and Synchronizers go
-    // and get the data asynchronously and block on read instead of on create
+    const { encodedDocumentId } = parseAutomergeUrl(automergeUrl)
+    // If we have the handle cached, return it
+    if (this.#handleCache[encodedDocumentId])
+      return this.#handleCache[encodedDocumentId]
 
-    // emit a document event to advertise interest in this document
+    const handle = this.#getHandle<T>(encodedDocumentId, false) as DocHandle<T>
     this.emit("document", { handle })
-
     return handle
   }
 
   delete(
     /** The documentId of the handle to delete */
-    documentId: DocumentId
+    id: DocumentId | AutomergeUrl
   ) {
-    const handle = this.#getHandle(documentId, false)
+    if (isValidAutomergeUrl(id)) {
+      ;({ encodedDocumentId: id } = parseAutomergeUrl(id))
+    }
+
+    const handle = this.#getHandle(id, false)
     handle.delete()
 
-    delete this.#handleCache[documentId]
-    this.emit("delete-document", { documentId })
+    delete this.#handleCache[id]
+    this.emit("delete-document", {
+      encodedDocumentId: id,
+    })
   }
 }
 
@@ -119,5 +129,5 @@ interface DocumentPayload {
 }
 
 interface DeleteDocumentPayload {
-  documentId: DocumentId
+  encodedDocumentId: DocumentId
 }

package/src/DocHandle.ts

@@ -17,7 +17,8 @@ import { waitFor } from "xstate/lib/waitFor.js"
 import { headsAreSame } from "./helpers/headsAreSame.js"
 import { pause } from "./helpers/pause.js"
 import { TimeoutError, withTimeout } from "./helpers/withTimeout.js"
-import type { ChannelId, DocumentId, PeerId } from "./types.js"
+import type { ChannelId, DocumentId, PeerId, AutomergeUrl } from "./types.js"
+import { stringifyAutomergeUrl } from "./DocUrl.js"
 
 /** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
 export class DocHandle<T> //
@@ -28,30 +29,32 @@ export class DocHandle<T> //
   #machine: DocHandleXstateMachine<T>
   #timeoutDelay: number
 
+  get url(): AutomergeUrl {
+    return stringifyAutomergeUrl({ documentId: this.documentId })
+  }
+
   constructor(
     public documentId: DocumentId,
-    { isNew = false, timeoutDelay = 700000 }: DocHandleOptions = {}
+    { isNew = false, timeoutDelay = 60_000 }: DocHandleOptions = {}
   ) {
     super()
     this.#timeoutDelay = timeoutDelay
-    this.#log = debug(`automerge-repo:dochandle:${documentId.slice(0, 5)}`)
+    this.#log = debug(`automerge-repo:dochandle:${this.documentId.slice(0, 5)}`)
 
     // initial doc
-    const doc = A.init<T>({
-      patchCallback: (patches, patchInfo) =>
-        this.emit("patch", { handle: this, patches, patchInfo }),
-    })
+    const doc = A.init<T>()
 
     /**
      * Internally we use a state machine to orchestrate document loading and/or syncing, in order to
      * avoid requesting data we already have, or surfacing intermediate values to the consumer.
      *
-     *                      ┌─────────┐           ┌────────────┐
-     *  ┌───────┐  ┌──FIND──┤ loading ├─REQUEST──►│ requesting ├─UPDATE──┐
+     *                          ┌─────────────────────┬─────────TIMEOUT────►┌────────┐
+     *                      ┌───┴─────┐           ┌───┴────────┐            │ failed │
+     *  ┌───────┐  ┌──FIND──┤ loading ├─REQUEST──►│ requesting ├─UPDATE──┐  └────────┘
      *  │ idle  ├──┤        └───┬─────┘           └────────────┘         │
-     *  └───────┘  │            │                                        └─►┌─────────┐
-     *             │            └───────LOAD───────────────────────────────►│  ready  │
-     *             └──CREATE───────────────────────────────────────────────►└─────────┘
+     *  └───────┘  │            │                                        └─►┌────────┐
+     *             │            └───────LOAD───────────────────────────────►│ ready  │
+     *             └──CREATE───────────────────────────────────────────────►└────────┘
      */
     this.#machine = interpret(
       createMachine<DocHandleContext<T>, DocHandleEvent<T>>(
@@ -60,7 +63,7 @@ export class DocHandle<T> //
 
           id: "docHandle",
           initial: IDLE,
-          context: { documentId, doc },
+          context: { documentId: this.documentId, doc },
           states: {
             idle: {
               on: {
@@ -74,12 +77,18 @@ export class DocHandle<T> //
             },
             loading: {
               on: {
-                // LOAD is called by the Repo if the document is found in storage
-                LOAD: { actions: "onLoad", target: READY },
+                // UPDATE is called by the Repo if the document is found in storage
+                UPDATE: { actions: "onUpdate", target: READY },
                 // REQUEST is called by the Repo if the document is not found in storage
                 REQUEST: { target: REQUESTING },
                 DELETE: { actions: "onDelete", target: DELETED },
               },
+              after: [
+                {
+                  delay: this.#timeoutDelay,
+                  target: FAILED,
+                },
+              ],
             },
             requesting: {
               on: {
@@ -89,6 +98,12 @@ export class DocHandle<T> //
                 REQUEST_COMPLETE: { target: READY },
                 DELETE: { actions: "onDelete", target: DELETED },
               },
+              after: [
+                {
+                  delay: this.#timeoutDelay,
+                  target: FAILED,
+                },
+              ],
             },
             ready: {
               on: {
@@ -97,22 +112,18 @@ export class DocHandle<T> //
                 DELETE: { actions: "onDelete", target: DELETED },
               },
             },
-            error: {},
-            deleted: {},
+            failed: {
+              type: "final",
+            },
+            deleted: {
+              type: "final",
+            },
           },
         },
 
         {
           actions: {
-            /** Apply the binary changes from storage and put the updated doc on context */
-            onLoad: assign((context, { payload }: LoadEvent) => {
-              const { binary } = payload
-              const { doc } = context
-              const newDoc = A.loadIncremental(doc, binary)
-              return { doc: newDoc }
-            }),
-
-            /** Put the updated doc on context; if it's different, emit a `change` event */
+            /** Put the updated doc on context */
             onUpdate: assign((context, { payload }: UpdateEvent<T>) => {
               const { doc: oldDoc } = context
 
@@ -133,33 +144,36 @@ export class DocHandle<T> //
         const oldDoc = history?.context?.doc
         const newDoc = context.doc
 
-        const docChanged = newDoc && oldDoc && !headsAreSame(newDoc, oldDoc)
+        console.log(`${event} → ${state}`, newDoc)
+
+        const docChanged = newDoc && oldDoc && !headsAreSame(A.getHeads(newDoc), A.getHeads(oldDoc))
         if (docChanged) {
-          this.emit("change", { handle: this, doc: newDoc })
+          this.emit("heads-changed", { handle: this, doc: newDoc })
+
+          const patches = A.diff(newDoc, A.getHeads(oldDoc), A.getHeads(newDoc))
+          if (patches.length > 0) {
+            const source = "change" // TODO: pass along the source (load/change/network)
+            this.emit("change", {
+              handle: this,
+              doc: newDoc,
+              patches,
+              patchInfo: { before: oldDoc, after: newDoc, source },
+            })
+          }
+
           if (!this.isReady()) {
             this.#machine.send(REQUEST_COMPLETE)
           }
         }
-        this.#log(`${event} → ${state}`, this.#doc)
       })
       .start()
 
     this.#machine.send(isNew ? CREATE : FIND)
   }
 
-  get doc() {
-    if (!this.isReady()) {
-      throw new Error(
-        `DocHandle#${this.documentId} is not ready. Check \`handle.isReady()\` before accessing the document.`
-      )
-    }
-
-    return this.#doc
-  }
-
   // PRIVATE
 
-  /** Returns the current document */
+  /** Returns the current document, regardless of state */
   get #doc() {
     return this.#machine?.getSnapshot().context.doc
   }
@@ -175,7 +189,7 @@ export class DocHandle<T> //
     return Promise.any(
       awaitStates.map(state =>
         waitFor(this.#machine, s => s.matches(state), {
-          timeout: this.#timeoutDelay, // match the delay above
+          timeout: this.#timeoutDelay * 2000, // longer than the delay above for testing
         })
       )
     )
@@ -183,19 +197,48 @@ export class DocHandle<T> //
 
   // PUBLIC
 
-  isReady = () => this.#state === READY
-  isReadyOrRequesting = () =>
-    this.#state === READY || this.#state === REQUESTING
-  isDeleted = () => this.#state === DELETED
+  /**
+   * Checks if the document is ready for accessing or changes.
+   * Note that for documents already stored locally this occurs before synchronization
+   * with any peers. We do not currently have an equivalent `whenSynced()`.
+   */
+  isReady = () => this.inState([HandleState.READY])
+  /**
+   * Checks if this document has been marked as deleted.
+   * Deleted documents are removed from local storage and the sync process.
+   * It's not currently possible at runtime to undelete a document.
+   * @returns true if the document has been marked as deleted
+   */
+  isDeleted = () => this.inState([HandleState.DELETED])
+  inState = (states: HandleState[]) =>
+    states.some(this.#machine?.getSnapshot().matches)
+
+  get state() {
+    return this.#machine?.getSnapshot().value
+  }
 
   /**
-   * Returns the current document, waiting for the handle to be ready if necessary.
+   * Use this to block until the document handle has finished loading.
+   * The async equivalent to checking `inState()`.
+   * @param awaitStates = [READY]
+   * @returns
    */
-  async value(awaitStates: HandleState[] = [READY]) {
+  async whenReady(awaitStates: HandleState[] = [READY]): Promise<void> {
+    await withTimeout(this.#statePromise(awaitStates), this.#timeoutDelay)
+  }
+
+  /**
+   * Returns the current state of the Automerge document this handle manages.
+   * Note that this waits for the handle to be ready if necessary, and currently, if
+   * loading (or synchronization) fails, will never resolve.
+   *
+   * @param {awaitStates=[READY]} optional states to wait for, such as "LOADING". mostly for internal use.
+   */
+  async doc(awaitStates: HandleState[] = [READY]): Promise<A.Doc<T>> {
     await pause() // yield one tick because reasons
     try {
       // wait for the document to enter one of the desired states
-      await withTimeout(this.#statePromise(awaitStates), this.#timeoutDelay)
+      await this.#statePromise(awaitStates)
     } catch (error) {
       if (error instanceof TimeoutError)
         throw new Error(`DocHandle: timed out loading ${this.documentId}`)
@@ -205,20 +248,29 @@ export class DocHandle<T> //
     return this.#doc
   }
 
-  async loadAttemptedValue() {
-    return this.value([READY, REQUESTING])
-  }
-
-  /** `load` is called by the repo when the document is found in storage */
-  load(binary: Uint8Array) {
-    if (binary.length) {
-      this.#machine.send(LOAD, { payload: { binary } })
+  /**
+   * Returns the current state of the Automerge document this handle manages, or undefined.
+   * Useful in a synchronous context. Consider using `await handle.doc()` instead, check `isReady()`,
+   * or use `whenReady()` if you want to make sure loading is complete first.
+   *
+   * Do not confuse this 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
+   */
+  docSync(): A.Doc<T> | undefined {
+    if (!this.isReady()) {
+      return undefined
     }
+
+    return this.#doc
   }
 
   /** `update` is called by the repo when we receive changes from the network */
   update(callback: (doc: A.Doc<T>) => A.Doc<T>) {
-    this.#machine.send(UPDATE, { payload: { callback } })
+    this.#machine.send(UPDATE, {
+      payload: { callback },
+    })
   }
 
   /** `change` is called by the repo when the document is changed locally  */
@@ -250,7 +302,7 @@ export class DocHandle<T> //
     this.#machine.send(UPDATE, {
       payload: {
         callback: (doc: A.Doc<T>) => {
-          return A.changeAt(doc, heads, options, callback)
+          return A.changeAt(doc, heads, options, callback).newDoc
         },
       },
     })
@@ -280,7 +332,7 @@ export interface DocHandleMessagePayload {
   data: Uint8Array
 }
 
-export interface DocHandleChangePayload<T> {
+export interface DocHandleEncodedChangePayload<T> {
   handle: DocHandle<T>
   doc: A.Doc<T>
 }
@@ -289,15 +341,16 @@ export interface DocHandleDeletePayload<T> {
   handle: DocHandle<T>
 }
 
-export interface DocHandlePatchPayload<T> {
+export interface DocHandleChangePayload<T> {
   handle: DocHandle<T>
+  doc: A.Doc<T>
   patches: A.Patch[]
   patchInfo: A.PatchInfo<T>
 }
 
 export interface DocHandleEvents<T> {
+  "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
-  patch: (payload: DocHandlePatchPayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
 }
 
@@ -310,7 +363,7 @@ export const HandleState = {
   LOADING: "loading",
   REQUESTING: "requesting",
   READY: "ready",
-  ERROR: "error",
+  FAILED: "failed",
   DELETED: "deleted",
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]
@@ -325,7 +378,7 @@ type DocHandleMachineState = {
 // context
 
 interface DocHandleContext<T> {
-  documentId: string
+  documentId: DocumentId
   doc: A.Doc<T>
 }
 
@@ -333,7 +386,6 @@ interface DocHandleContext<T> {
 
 export const Event = {
   CREATE: "CREATE",
-  LOAD: "LOAD",
   FIND: "FIND",
   REQUEST: "REQUEST",
   REQUEST_COMPLETE: "REQUEST_COMPLETE",
@@ -344,7 +396,6 @@ export const Event = {
 type Event = (typeof Event)[keyof typeof Event]
 
 type CreateEvent = { type: typeof CREATE; payload: { documentId: string } }
-type LoadEvent = { type: typeof LOAD; payload: { binary: Uint8Array } }
 type FindEvent = { type: typeof FIND; payload: { documentId: string } }
 type RequestEvent = { type: typeof REQUEST }
 type RequestCompleteEvent = { type: typeof REQUEST_COMPLETE }
@@ -357,7 +408,6 @@ type TimeoutEvent = { type: typeof TIMEOUT }
 
 type DocHandleEvent<T> =
   | CreateEvent
-  | LoadEvent
   | FindEvent
   | RequestEvent
   | RequestCompleteEvent
@@ -383,14 +433,6 @@ type DocHandleXstateMachine<T> = Interpreter<
 
 // CONSTANTS
 
-const { IDLE, LOADING, REQUESTING, READY, ERROR, DELETED } = HandleState
-const {
-  CREATE,
-  LOAD,
-  FIND,
-  REQUEST,
-  UPDATE,
-  TIMEOUT,
-  DELETE,
-  REQUEST_COMPLETE,
-} = Event
+export const { IDLE, LOADING, REQUESTING, READY, FAILED, DELETED } = HandleState
+const { CREATE, FIND, REQUEST, UPDATE, TIMEOUT, DELETE, REQUEST_COMPLETE } =
+  Event