@automerge/automerge-repo 0.2.0 → 1.0.0-alpha.0

package/README.md

@@ -13,8 +13,6 @@ Other packages in this monorepo include:
   application.
 - [@automerge/automerge-repo-react-hooks](/packages/automerge-repo-react-hooks/): Example hooks for use with
   React.
-- [@automerge/automerge-repo-sync-server](/packages/automerge-repo-sync-server/): A small synchronization
-  server that facilitates asynchronous communication between peers
 
 #### Storage adapters
 
@@ -55,34 +53,19 @@ A `Repo` exposes these methods:
 A `DocHandle` is a wrapper around an `Automerge.Doc`. Its primary function is to dispatch changes to
 the document.
 
+- `handle.doc()` or `handle.docSync()`
+  Returns a `Promise<Doc<T>>` that will contain the current value of the document.
+  it waits until the document has finished loading and/or synchronizing over the network before
+  returning a value.
 - `handle.change((doc: T) => void)`  
   Calls the provided callback with an instrumented mutable object
   representing the document. Any changes made to the document will be recorded and distributed to
   other nodes.
-- `handle.value()`  
-  Returns a `Promise<Doc<T>>` that will contain the current value of the document.
-  it waits until the document has finished loading and/or synchronizing over the network before
-  returning a value.
-
-When required, you can also access the underlying document directly, but only after the handle is ready:
-
-```ts
-if (handle.ready()) {
-  doc = handle.doc
-} else {
-  handle.value().then(d => {
-    doc = d
-  })
-}
-```
 
 A `DocHandle` also emits these events:
 
-- `change({handle: DocHandle, doc: Doc<T>})`  
-  Called any time changes are created or received on the document. Request the `value()` from the
-  handle.
-- `patch({handle: DocHandle, patches: Patch[], patchInfo: PatchInfo})` 
-  Useful for manual increment maintenance of a video, most notably for text editors.
+- `change({handle: DocHandle, patches: Patch[], patchInfo: PatchInfo})` 
+  Called whenever the document changes, the handle's .doc
 - `delete`  
   Called when the document is deleted locally.
 
@@ -251,7 +234,7 @@ dev:demo`.
 ### Adding a sync server
 
 First, get a sync-server running locally, following the instructions for the
-[automerge-repo-sync-server](/packages/automerge-repo-sync-server/) package.
+[automerge-repo-sync-server](https://github.com/automerge/automerge-repo-sync-server) package.
 
 Next, update your application to synchronize with it:
 

package/dist/DocCollection.d.ts

@@ -1,6 +1,6 @@
 import EventEmitter from "eventemitter3";
 import { DocHandle } from "./DocHandle.js";
-import { type DocumentId } from "./types.js";
+import { DocumentId, AutomergeUrl } from "./types.js";
 import { type SharePolicy } from "./Repo.js";
 /**
  * A DocCollection is a collection of DocHandles. It supports creating new documents and finding
@@ -25,10 +25,10 @@ export declare class DocCollection extends EventEmitter<DocCollectionEvents> {
      */
     find<T>(
     /** The documentId of the handle to retrieve */
-    documentId: DocumentId): DocHandle<T>;
+    automergeUrl: AutomergeUrl): DocHandle<T>;
     delete(
     /** The documentId of the handle to delete */
-    documentId: DocumentId): void;
+    id: DocumentId | AutomergeUrl): void;
 }
 interface DocCollectionEvents {
     document: (arg: DocumentPayload) => void;
@@ -38,7 +38,7 @@ interface DocumentPayload {
     handle: DocHandle<any>;
 }
 interface DeleteDocumentPayload {
-    documentId: DocumentId;
+    encodedDocumentId: DocumentId;
 }
 export {};
 //# sourceMappingURL=DocCollection.d.ts.map

package/dist/DocCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocCollection.d.ts","sourceRoot":"","sources":["../src/DocCollection.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AAExC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE5C;;;KAGK;AACL,qBAAa,aAAc,SAAQ,YAAY,CAAC,mBAAmB,CAAC;;IAGlE,sDAAsD;IACtD,WAAW,EAAE,WAAW,CAAmB;;IAuB3C,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IAyBzB;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,+CAA+C;IAC/C,UAAU,EAAE,UAAU,GACrB,SAAS,CAAC,CAAC,CAAC;IAmBf,MAAM;IACJ,6CAA6C;IAC7C,UAAU,EAAE,UAAU;CAQzB;AAGD,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACxD;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;CACvB;AAED,UAAU,qBAAqB;IAC7B,UAAU,EAAE,UAAU,CAAA;CACvB"}
+{"version":3,"file":"DocCollection.d.ts","sourceRoot":"","sources":["../src/DocCollection.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAyB,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAS5C;;;KAGK;AACL,qBAAa,aAAc,SAAQ,YAAY,CAAC,mBAAmB,CAAC;;IAGlE,sDAAsD;IACtD,WAAW,EAAE,WAAW,CAAmB;;IAwB3C,8CAA8C;IAC9C,IAAI,OAAO,uCAEV;IAED;;;;OAIG;IACH,MAAM,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC;IA0BzB;;;OAGG;IACH,IAAI,CAAC,CAAC;IACJ,+CAA+C;IAC/C,YAAY,EAAE,YAAY,GACzB,SAAS,CAAC,CAAC,CAAC;IAef,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAchC;AAGD,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACxD;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;CACvB;AAED,UAAU,qBAAqB;IAC7B,iBAAiB,EAAE,UAAU,CAAA;CAC9B"}

package/dist/DocCollection.js

@@ -1,6 +1,6 @@
 import EventEmitter from "eventemitter3";
-import { v4 as uuid } from "uuid";
 import { DocHandle } from "./DocHandle.js";
+import { generateAutomergeUrl, isValidAutomergeUrl, parseAutomergeUrl, } from "./DocUrl.js";
 /**
  * A DocCollection is a collection of DocHandles. It supports creating new documents and finding
  * documents by ID.
@@ -22,6 +22,8 @@ export class DocCollection extends EventEmitter {
         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(documentId, { isNew });
         this.#handleCache[documentId] = handle;
         return handle;
@@ -50,8 +52,9 @@ export class DocCollection extends EventEmitter {
         // }
         // or
         // - pass a "reify" function that takes a `<any>` and returns `<T>`
-        const documentId = uuid();
-        const handle = this.#getHandle(documentId, true);
+        // Generate a new UUID and store it in the buffer
+        const { encodedDocumentId } = parseAutomergeUrl(generateAutomergeUrl());
+        const handle = this.#getHandle(encodedDocumentId, true);
         this.emit("document", { handle });
         return handle;
     }
@@ -61,25 +64,30 @@ export class DocCollection extends EventEmitter {
      */
     find(
     /** The documentId of the handle to retrieve */
-    documentId) {
-        // TODO: we want a way to make sure we don't yield intermediate document states during initial synchronization
-        // If we already have a handle, return it
-        if (this.#handleCache[documentId])
-            return this.#handleCache[documentId];
-        // Otherwise, create a new handle
-        const handle = this.#getHandle(documentId, false);
-        // 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
-        // emit a document event to advertise interest in this document
+    automergeUrl) {
+        if (!isValidAutomergeUrl(automergeUrl)) {
+            throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`);
+        }
+        const { encodedDocumentId } = parseAutomergeUrl(automergeUrl);
+        // If we have the handle cached, return it
+        if (this.#handleCache[encodedDocumentId])
+            return this.#handleCache[encodedDocumentId];
+        const handle = this.#getHandle(encodedDocumentId, false);
         this.emit("document", { handle });
         return handle;
     }
     delete(
     /** The documentId of the handle to delete */
-    documentId) {
-        const handle = this.#getHandle(documentId, false);
+    id) {
+        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,
+        });
     }
 }

package/dist/DocHandle.d.ts

@@ -1,21 +1,55 @@
 import * as A from "@automerge/automerge";
 import EventEmitter from "eventemitter3";
-import type { ChannelId, DocumentId, PeerId } from "./types.js";
+import { StateValue } from "xstate";
+import type { ChannelId, DocumentId, PeerId, AutomergeUrl } from "./types.js";
 /** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
 export declare class DocHandle<T>//
  extends EventEmitter<DocHandleEvents<T>> {
     #private;
     documentId: DocumentId;
+    get url(): AutomergeUrl;
     constructor(documentId: DocumentId, { isNew, timeoutDelay }?: DocHandleOptions);
-    get doc(): A.unstable.Doc<T>;
+    /**
+     * 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: () => boolean;
-    isReadyOrRequesting: () => boolean;
+    /**
+     * 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: () => boolean;
+    inState: (states: HandleState[]) => boolean;
+    get state(): StateValue;
+    /**
+     * Use this to block until the document handle has finished loading.
+     * The async equivalent to checking `inState()`.
+     * @param awaitStates = [READY]
+     * @returns
+     */
+    whenReady(awaitStates?: HandleState[]): Promise<void>;
     /**
-     * Returns the current document, waiting for the handle to be ready if necessary.
+     * 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.
      */
-    value(awaitStates?: HandleState[]): Promise<A.unstable.Doc<T>>;
-    loadAttemptedValue(): Promise<A.unstable.Doc<T>>;
+    doc(awaitStates?: HandleState[]): Promise<A.Doc<T>>;
+    /**
+     * 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;
     /** `load` is called by the repo when the document is found in storage */
     load(binary: Uint8Array): void;
     /** `update` is called by the repo when we receive changes from the network */
@@ -37,21 +71,22 @@ export interface DocHandleMessagePayload {
     channelId: ChannelId;
     data: Uint8Array;
 }
-export interface DocHandleChangePayload<T> {
+export interface DocHandleEncodedChangePayload<T> {
     handle: DocHandle<T>;
     doc: A.Doc<T>;
 }
 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;
 }
 export declare const HandleState: {
@@ -59,7 +94,7 @@ export declare const HandleState: {
     readonly LOADING: "loading";
     readonly REQUESTING: "requesting";
     readonly READY: "ready";
-    readonly ERROR: "error";
+    readonly FAILED: "failed";
     readonly DELETED: "deleted";
 };
 export type HandleState = (typeof HandleState)[keyof typeof HandleState];
@@ -73,5 +108,6 @@ export declare const Event: {
     readonly TIMEOUT: "TIMEOUT";
     readonly DELETE: "DELETE";
 };
+export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", FAILED: "failed", DELETED: "deleted";
 export {};
 //# sourceMappingURL=DocHandle.d.ts.map

package/dist/DocHandle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,sBAAsB,CAAA;AAEzC,OAAO,YAAY,MAAM,eAAe,CAAA;AAiBxC,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAE/D,iGAAiG;AACjG,qBAAa,SAAS,CAAC,CAAC,CAAE,EAAE;AAC1B,SAAQ,YAAY,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;;IAQ/B,UAAU,EAAE,UAAU;gBAAtB,UAAU,EAAE,UAAU,EAC7B,EAAE,KAAa,EAAE,YAAqB,EAAE,GAAE,gBAAqB;IAqHjE,IAAI,GAAG,sBAQN;IA4BD,OAAO,gBAA8B;IACrC,mBAAmB,gBACkC;IACrD,SAAS,gBAAgC;IAEzC;;OAEG;IACG,KAAK,CAAC,WAAW,GAAE,WAAW,EAAY;IAc1C,kBAAkB;IAIxB,yEAAyE;IACzE,IAAI,CAAC,MAAM,EAAE,UAAU;IAMvB,8EAA8E;IAC9E,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAI5C,2EAA2E;IAC3E,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM;IAehE,QAAQ,CACN,KAAK,EAAE,CAAC,CAAC,KAAK,EACd,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAM;IAgBlC,gFAAgF;IAChF,OAAO;IAIP,kEAAkE;IAClE,MAAM;CAGP;AAID,UAAU,gBAAgB;IACxB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,EAAE,MAAM,CAAA;IACrB,SAAS,EAAE,SAAS,CAAA;IACpB,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;CACd;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC;IACvC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;CACrB;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAA;IACpB,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,CAAA;IAClB,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IACpD,KAAK,EAAE,CAAC,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;IAClD,MAAM,EAAE,CAAC,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAA;CACrD;AAMD,eAAO,MAAM,WAAW;;;;;;;CAOd,CAAA;AACV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAA;AAkBxE,eAAO,MAAM,KAAK;;;;;;;;;CASR,CAAA"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -6,6 +6,7 @@ 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 { stringifyAutomergeUrl } from "./DocUrl.js";
 /** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
 export class DocHandle//
  extends EventEmitter {
@@ -13,31 +14,33 @@ export class DocHandle//
     #log;
     #machine;
     #timeoutDelay;
-    constructor(documentId, { isNew = false, timeoutDelay = 700000 } = {}) {
+    get url() {
+        return stringifyAutomergeUrl({ documentId: this.documentId });
+    }
+    constructor(documentId, { isNew = false, timeoutDelay = 60_000 } = {}) {
         super();
         this.documentId = documentId;
         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({
-            patchCallback: (patches, patchInfo) => this.emit("patch", { handle: this, patches, patchInfo }),
-        });
+        const doc = A.init();
         /**
          * 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({
             predictableActionArguments: true,
             id: "docHandle",
             initial: IDLE,
-            context: { documentId, doc },
+            context: { documentId: this.documentId, doc },
             states: {
                 idle: {
                     on: {
@@ -57,6 +60,12 @@ export class DocHandle//
                         REQUEST: { target: REQUESTING },
                         DELETE: { actions: "onDelete", target: DELETED },
                     },
+                    after: [
+                        {
+                            delay: this.#timeoutDelay,
+                            target: FAILED,
+                        },
+                    ],
                 },
                 requesting: {
                     on: {
@@ -66,6 +75,12 @@ export class DocHandle//
                         REQUEST_COMPLETE: { target: READY },
                         DELETE: { actions: "onDelete", target: DELETED },
                     },
+                    after: [
+                        {
+                            delay: this.#timeoutDelay,
+                            target: FAILED,
+                        },
+                    ],
                 },
                 ready: {
                     on: {
@@ -74,8 +89,12 @@ export class DocHandle//
                         DELETE: { actions: "onDelete", target: DELETED },
                     },
                 },
-                error: {},
-                deleted: {},
+                failed: {
+                    type: "final",
+                },
+                deleted: {
+                    type: "final",
+                },
             },
         }, {
             actions: {
@@ -102,26 +121,30 @@ export class DocHandle//
             .onTransition(({ value: state, history, context }, event) => {
             const oldDoc = history?.context?.doc;
             const newDoc = context.doc;
+            this.#log(`${event} → ${state}`, newDoc);
             const docChanged = newDoc && oldDoc && !headsAreSame(newDoc, 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;
     }
@@ -134,21 +157,48 @@ export class DocHandle//
         if (!Array.isArray(awaitStates))
             awaitStates = [awaitStates];
         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
         })));
     }
     // PUBLIC
-    isReady = () => this.#state === READY;
-    isReadyOrRequesting = () => this.#state === READY || this.#state === REQUESTING;
-    isDeleted = () => this.#state === DELETED;
     /**
-     * Returns the current document, waiting for the handle to be ready if necessary.
+     * 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) => states.some(this.#machine?.getSnapshot().matches);
+    get state() {
+        return this.#machine?.getSnapshot().value;
+    }
+    /**
+     * Use this to block until the document handle has finished loading.
+     * The async equivalent to checking `inState()`.
+     * @param awaitStates = [READY]
+     * @returns
      */
-    async value(awaitStates = [READY]) {
+    async whenReady(awaitStates = [READY]) {
+        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 = [READY]) {
         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)
@@ -159,18 +209,33 @@ export class DocHandle//
         // Return the document
         return this.#doc;
     }
-    async loadAttemptedValue() {
-        return this.value([READY, REQUESTING]);
+    /**
+     * 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() {
+        if (!this.isReady()) {
+            return undefined;
+        }
+        return this.#doc;
     }
     /** `load` is called by the repo when the document is found in storage */
     load(binary) {
-        if (binary.length) {
+        if (binary.length && binary.length > 0) {
             this.#machine.send(LOAD, { payload: { binary } });
         }
     }
     /** `update` is called by the repo when we receive changes from the network */
     update(callback) {
-        this.#machine.send(UPDATE, { payload: { callback } });
+        this.#machine.send(UPDATE, {
+            payload: { callback },
+        });
     }
     /** `change` is called by the repo when the document is changed locally  */
     change(callback, options = {}) {
@@ -192,7 +257,7 @@ export class DocHandle//
         this.#machine.send(UPDATE, {
             payload: {
                 callback: (doc) => {
-                    return A.changeAt(doc, heads, options, callback);
+                    return A.changeAt(doc, heads, options, callback).newDoc;
                 },
             },
         });
@@ -214,7 +279,7 @@ export const HandleState = {
     LOADING: "loading",
     REQUESTING: "requesting",
     READY: "ready",
-    ERROR: "error",
+    FAILED: "failed",
     DELETED: "deleted",
 };
 // events
@@ -229,5 +294,5 @@ export const Event = {
     DELETE: "DELETE",
 };
 // CONSTANTS
-const { IDLE, LOADING, REQUESTING, READY, ERROR, DELETED } = HandleState;
+export const { IDLE, LOADING, REQUESTING, READY, FAILED, DELETED } = HandleState;
 const { CREATE, LOAD, FIND, REQUEST, UPDATE, TIMEOUT, DELETE, REQUEST_COMPLETE, } = Event;

package/dist/DocUrl.d.ts

@@ -1,20 +1,40 @@
-/// <reference types="node" />
-export declare const linkForDocumentId: (id: any) => string;
-export declare const documentIdFromShareLink: (link: any) => any;
-export declare const isValidShareLink: (str: any) => boolean;
-export declare const parts: (str: any) => {
-    key: any;
-    nonCrc: any;
-    crc: any;
+import { type AutomergeUrl, type BinaryDocumentId, type DocumentId } from "./types";
+export declare const urlPrefix = "automerge:";
+/**
+ * given an Automerge URL, return a decoded DocumentId (and the encoded DocumentId)
+ *
+ * @param url
+ * @returns { documentId: Uint8Array(16), encodedDocumentId: bs58check.encode(documentId) }
+ */
+export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
+    binaryDocumentId: BinaryDocumentId;
+    encodedDocumentId: DocumentId;
 };
-export declare const encodedParts: (str: any) => {
-    nonCrc: any;
-    key: any;
-    crc: any;
-};
-export declare const withCrc: (str: any) => string;
-export declare const encode: (str: any) => any;
-export declare const decode: (str: any) => any;
-export declare const hexToBuffer: (key: any) => Buffer;
-export declare const bufferToHex: (key: any) => any;
+interface StringifyAutomergeUrlOptions {
+    documentId: DocumentId | BinaryDocumentId;
+}
+/**
+ * Given a documentId in either canonical form, return an Automerge URL
+ * Throws on invalid input.
+ * Note: this is an object because we anticipate adding fields in the future.
+ * @param { documentId: EncodedDocumentId | DocumentId }
+ * @returns AutomergeUrl
+ */
+export declare const stringifyAutomergeUrl: ({ documentId, }: StringifyAutomergeUrlOptions) => AutomergeUrl;
+/**
+ * Given a string, return true if it is a valid Automerge URL
+ * also acts as a type discriminator in Typescript.
+ * @param str: URL candidate
+ * @returns boolean
+ */
+export declare const isValidAutomergeUrl: (str: string) => str is AutomergeUrl;
+/**
+ * generateAutomergeUrl produces a new AutomergeUrl.
+ * generally only called by create(), but used in tests as well.
+ * @returns a new Automerge URL with a random UUID documentId
+ */
+export declare const generateAutomergeUrl: () => AutomergeUrl;
+export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
+export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
+export {};
 //# sourceMappingURL=DocUrl.d.ts.map

package/dist/DocUrl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocUrl.d.ts","sourceRoot":"","sources":["../src/DocUrl.ts"],"names":[],"mappings":";AAIA,eAAO,MAAM,iBAAiB,qBAA6C,CAAA;AAE3E,eAAO,MAAM,uBAAuB,oBAInC,CAAA;AAED,eAAO,MAAM,gBAAgB,uBAG5B,CAAA;AAED,eAAO,MAAM,KAAK;;;;CAQjB,CAAA;AAED,eAAO,MAAM,YAAY;;;;CAIxB,CAAA;AAED,eAAO,MAAM,OAAO,sBAAwC,CAAA;AAE5D,eAAO,MAAM,MAAM,mBAAyC,CAAA;AAE5D,eAAO,MAAM,MAAM,mBAAyC,CAAA;AAE5D,eAAO,MAAM,WAAW,sBAC8B,CAAA;AAEtD,eAAO,MAAM,WAAW,mBAC0B,CAAA"}
+{"version":3,"file":"DocUrl.d.ts","sourceRoot":"","sources":["../src/DocUrl.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,SAAS,CAAA;AAIhB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAS,YAAY;;;CAIlD,CAAA;AAED,UAAU,4BAA4B;IACpC,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;CAC1C;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,oBAE/B,4BAA4B,KAAG,YAQjC,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAS,MAAM,wBAK9C,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGpC,CAAA;AAEJ,eAAO,MAAM,kBAAkB,UACtB,UAAU,KAChB,gBAAgB,GAAG,SACyC,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAAG,UACtB,CAAA"}