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

package/README.md

@@ -40,9 +40,9 @@ A `Repo` exposes these methods:
 
 - `create<T>(initialValue: T?)`
   Creates a new `Automerge.Doc` and returns a `DocHandle` for it. Accepts an optional initial value for the document. Produces an empty document (potentially violating the type!) otherwise.
-- `find<T>(docId: DocumentId)`  
+- `find<T>(docId: DocumentId): Promise<DocHandle<T>>`  
   Looks up a given document either on the local machine or (if necessary) over any configured
-  networks.
+  networks. Returns a promise that resolves when the document is loaded or throws if load fails.
 - `delete(docId: DocumentId)`  
   Deletes the local copy of a document from the local cache and local storage. _This does not currently delete the document from any other peers_.
 - `import(binary: Uint8Array)`  
@@ -57,10 +57,9 @@ 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.doc()`
+  Returns a `Doc<T>` that will contain the current value of the document.
+  Throws an error if the document is deleted.
 - `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
@@ -233,14 +232,14 @@ Now import it and add it to your list of network adapters:
 
 ```ts
 // main.tsx
-import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket" // <-- add this line
+import { WebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket" // <-- add this line
 
 // ...
 
 const repo = new Repo({
   network: [
     new BroadcastChannelNetworkAdapter(),
-    new BrowserWebSocketClientAdapter("ws://localhost:3030"), // <-- add this line
+    new WebSocketClientAdapter("ws://localhost:3030"), // <-- add this line
   ],
   storage: new IndexedDBStorageAdapter(),
 })
@@ -262,3 +261,4 @@ With gratitude for contributions by:
 - Jeremy Rose
 - Alex Currie-Clark
 - Dylan Mackenzie
+- Maciek Sakrejda

package/dist/AutomergeUrl.d.ts

@@ -1,17 +1,26 @@
-import type { LegacyDocumentId, AutomergeUrl, BinaryDocumentId, DocumentId, AnyDocumentId } from "./types.js";
+import type { LegacyDocumentId, AutomergeUrl, BinaryDocumentId, DocumentId, AnyDocumentId, UrlHeads } from "./types.js";
+import type { Heads as AutomergeHeads } from "@automerge/automerge/slim";
 export declare const urlPrefix = "automerge:";
-/** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
-export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
+interface ParsedAutomergeUrl {
     /** unencoded DocumentId */
     binaryDocumentId: BinaryDocumentId;
-    /** encoded DocumentId */
+    /** bs58 encoded DocumentId */
     documentId: DocumentId;
-};
+    /** Optional array of heads, if specified in URL */
+    heads?: UrlHeads;
+    /** Optional hex array of heads, in Automerge core format */
+    hexHeads?: string[];
+}
+/** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
+export declare const parseAutomergeUrl: (url: AutomergeUrl) => ParsedAutomergeUrl;
 /**
  * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
  * Throws on invalid input.
  */
 export declare const stringifyAutomergeUrl: (arg: UrlOptions | DocumentId | BinaryDocumentId) => AutomergeUrl;
+/** Helper to extract just the heads from a URL if they exist */
+export declare const getHeadsFromUrl: (url: AutomergeUrl) => string[] | undefined;
+export declare const anyDocumentIdToAutomergeUrl: (id: AnyDocumentId) => AutomergeUrl | undefined;
 /**
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
  * discriminator in Typescript.
@@ -25,6 +34,8 @@ export declare const isValidUuid: (str: unknown) => str is LegacyDocumentId;
 export declare const generateAutomergeUrl: () => AutomergeUrl;
 export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
 export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
+export declare const encodeHeads: (heads: AutomergeHeads) => UrlHeads;
+export declare const decodeHeads: (heads: UrlHeads) => AutomergeHeads;
 export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
 /**
  * Given any valid expression of a document ID, returns a DocumentId in base58check-encoded form.
@@ -40,6 +51,7 @@ export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
 export declare const interpretAsDocumentId: (id: AnyDocumentId) => DocumentId;
 type UrlOptions = {
     documentId: DocumentId | BinaryDocumentId;
+    heads?: UrlHeads;
 };
 export {};
 //# sourceMappingURL=AutomergeUrl.d.ts.map

package/dist/AutomergeUrl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AutomergeUrl.d.ts","sourceRoot":"","sources":["../src/AutomergeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACd,MAAM,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,QAAS,YAAY;IAQ/C,2BAA2B;;IAE3B,yBAAyB;;CAG5B,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAC3B,UAAU,GAAG,UAAU,GAAG,gBAAgB,KAmBL,YAC3C,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAS,OAAO,KAAG,GAAG,IAAI,YAUzD,CAAA;AAED,eAAO,MAAM,iBAAiB,QAAS,OAAO,KAAG,GAAG,IAAI,UASvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAS,OAAO,KAAG,GAAG,IAAI,gBACH,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGvC,CAAA;AAED,eAAO,MAAM,kBAAkB,UAAW,UAAU,KACjB,gBAAgB,GAAG,SAAS,CAAA;AAE/D,eAAO,MAAM,kBAAkB,UAAW,gBAAgB,KAC7B,UAAU,CAAA;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,6BAI1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,OAAQ,aAAa,eAqBtD,CAAA;AAID,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;CAC1C,CAAA"}
+{"version":3,"file":"AutomergeUrl.d.ts","sourceRoot":"","sources":["../src/AutomergeUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,EACb,QAAQ,EACT,MAAM,YAAY,CAAA;AASnB,OAAO,KAAK,EAAE,KAAK,IAAI,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAExE,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC,UAAU,kBAAkB;IAC1B,2BAA2B;IAC3B,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,8BAA8B;IAC9B,UAAU,EAAE,UAAU,CAAA;IACtB,mDAAmD;IACnD,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAED,sGAAsG;AACtG,eAAO,MAAM,iBAAiB,GAAI,KAAK,YAAY,KAAG,kBAsBrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,UAAU,GAAG,UAAU,GAAG,gBAAgB,KAC9C,YAgCF,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,eAAe,GAAI,KAAK,YAAY,KAAG,MAAM,EAAE,GAAG,SAG9D,CAAA;AAED,eAAO,MAAM,2BAA2B,GAAI,IAAI,aAAa,6BAO9C,CAAA;AAEf;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,YAsBzD,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,UASvD,CAAA;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,OAAO,KAAG,GAAG,IAAI,gBACH,CAAA;AAE/C;;GAEG;AACH,eAAO,MAAM,oBAAoB,QAAO,YAGvC,CAAA;AAED,eAAO,MAAM,kBAAkB,GAAI,OAAO,UAAU,KACjB,gBAAgB,GAAG,SAAS,CAAA;AAE/D,eAAO,MAAM,kBAAkB,GAAI,OAAO,gBAAgB,KAC7B,UAAU,CAAA;AAEvC,eAAO,MAAM,WAAW,GAAI,OAAO,cAAc,KAAG,QACsB,CAAA;AAE1E,eAAO,MAAM,WAAW,GAAI,OAAO,QAAQ,KAAG,cACgC,CAAA;AAE9E,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,6BAI1C,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,GAAI,IAAI,aAAa,eAqBtD,CAAA;AAID,KAAK,UAAU,GAAG;IAChB,UAAU,EAAE,UAAU,GAAG,gBAAgB,CAAA;IACzC,KAAK,CAAC,EAAE,QAAQ,CAAA;CACjB,CAAA"}

package/dist/AutomergeUrl.js

@@ -1,53 +1,98 @@
 import * as Uuid from "uuid";
 import bs58check from "bs58check";
+import { uint8ArrayFromHexString, uint8ArrayToHexString, } from "./helpers/bufferFromHex.js";
 export const urlPrefix = "automerge:";
 /** Given an Automerge URL, returns the DocumentId in both base58check-encoded form and binary form */
 export const parseAutomergeUrl = (url) => {
+    const [baseUrl, headsSection, ...rest] = url.split("#");
+    if (rest.length > 0) {
+        throw new Error("Invalid URL: contains multiple heads sections");
+    }
     const regex = new RegExp(`^${urlPrefix}(\\w+)$`);
-    const [, docMatch] = url.match(regex) || [];
+    const [, docMatch] = baseUrl.match(regex) || [];
     const documentId = docMatch;
     const binaryDocumentId = documentIdToBinary(documentId);
     if (!binaryDocumentId)
         throw new Error("Invalid document URL: " + url);
-    return {
-        /** unencoded DocumentId */
-        binaryDocumentId,
-        /** encoded DocumentId */
-        documentId,
-    };
+    if (headsSection === undefined)
+        return { binaryDocumentId, documentId };
+    const heads = (headsSection === "" ? [] : headsSection.split("|"));
+    const hexHeads = heads.map(head => {
+        try {
+            return uint8ArrayToHexString(bs58check.decode(head));
+        }
+        catch (e) {
+            throw new Error(`Invalid head in URL: ${head}`);
+        }
+    });
+    return { binaryDocumentId, hexHeads, documentId, heads };
 };
 /**
  * Given a documentId in either binary or base58check-encoded form, returns an Automerge URL.
  * Throws on invalid input.
  */
 export const stringifyAutomergeUrl = (arg) => {
-    const documentId = arg instanceof Uint8Array || typeof arg === "string"
-        ? arg
-        : "documentId" in arg
-            ? arg.documentId
-            : undefined;
+    if (arg instanceof Uint8Array || typeof arg === "string") {
+        return (urlPrefix +
+            (arg instanceof Uint8Array
+                ? binaryToDocumentId(arg)
+                : arg));
+    }
+    const { documentId, heads = undefined } = arg;
+    if (documentId === undefined)
+        throw new Error("Invalid documentId: " + documentId);
     const encodedDocumentId = documentId instanceof Uint8Array
         ? binaryToDocumentId(documentId)
-        : typeof documentId === "string"
-            ? documentId
-            : undefined;
-    if (encodedDocumentId === undefined)
-        throw new Error("Invalid documentId: " + documentId);
-    return (urlPrefix + encodedDocumentId);
+        : documentId;
+    let url = `${urlPrefix}${encodedDocumentId}`;
+    if (heads !== undefined) {
+        heads.forEach(head => {
+            try {
+                bs58check.decode(head);
+            }
+            catch (e) {
+                throw new Error(`Invalid head: ${head}`);
+            }
+        });
+        url += "#" + heads.join("|");
+    }
+    return url;
+};
+/** Helper to extract just the heads from a URL if they exist */
+export const getHeadsFromUrl = (url) => {
+    const { heads } = parseAutomergeUrl(url);
+    return heads;
 };
+export const anyDocumentIdToAutomergeUrl = (id) => isValidAutomergeUrl(id)
+    ? id
+    : isValidDocumentId(id)
+        ? stringifyAutomergeUrl({ documentId: id })
+        : isValidUuid(id)
+            ? parseLegacyUUID(id)
+            : undefined;
 /**
  * Given a string, returns true if it is a valid Automerge URL. This function also acts as a type
  * discriminator in Typescript.
  */
 export const isValidAutomergeUrl = (str) => {
-    if (typeof str !== "string")
-        return false;
-    if (!str || !str.startsWith(urlPrefix))
+    if (typeof str !== "string" || !str || !str.startsWith(urlPrefix))
         return false;
-    const automergeUrl = str;
     try {
-        const { documentId } = parseAutomergeUrl(automergeUrl);
-        return isValidDocumentId(documentId);
+        const { documentId, heads } = parseAutomergeUrl(str);
+        if (!isValidDocumentId(documentId))
+            return false;
+        if (heads &&
+            !heads.every(head => {
+                try {
+                    bs58check.decode(head);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            }))
+            return false;
+        return true;
     }
     catch {
         return false;
@@ -74,6 +119,8 @@ export const generateAutomergeUrl = () => {
 };
 export const documentIdToBinary = (docId) => bs58check.decodeUnsafe(docId);
 export const binaryToDocumentId = (docId) => bs58check.encode(docId);
+export const encodeHeads = (heads) => heads.map(h => bs58check.encode(uint8ArrayFromHexString(h)));
+export const decodeHeads = (heads) => heads.map(h => uint8ArrayToHexString(bs58check.decode(h)));
 export const parseLegacyUUID = (str) => {
     if (!Uuid.validate(str))
         return undefined;

package/dist/DocHandle.d.ts

@@ -1,6 +1,6 @@
 import * as A from "@automerge/automerge/slim/next";
 import { EventEmitter } from "eventemitter3";
-import type { AutomergeUrl, DocumentId, PeerId } from "./types.js";
+import type { AutomergeUrl, DocumentId, PeerId, UrlHeads } from "./types.js";
 import { StorageId } from "./storage/types.js";
 /**
  * A DocHandle is a wrapper around a single Automerge document that lets us listen for changes and
@@ -30,6 +30,13 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      * peers. We do not currently have an equivalent `whenSynced()`.
      */
     isReady: () => boolean;
+    /**
+     * @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: () => boolean;
     /**
      * @returns true if the document has been marked as deleted.
      *
@@ -48,7 +55,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     inState: (states: HandleState[]) => boolean;
     /** @hidden */
-    get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "deleted";
+    get state(): "idle" | "loading" | "requesting" | "ready" | "unavailable" | "unloaded" | "deleted";
     /**
      * @returns a promise that resolves when the document is in one of the given states (if no states
      * are passed, when the document is ready)
@@ -58,38 +65,26 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     whenReady(awaitStates?: HandleState[]): Promise<void>;
     /**
-     * @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.
      */
-    doc(
-    /** states to wait for, such as "LOADING". mostly for internal use. */
-    awaitStates?: HandleState[]): Promise<A.Doc<T> | undefined>;
+    doc(): A.Doc<T>;
     /**
-     * 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.
-     */
-    docSync(): A.Doc<T> | undefined;
+     * @deprecated */
+    docSync(): A.Doc<T>;
     /**
      * Returns the current "heads" of the document, akin to a git commit.
      * 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;
+    heads(): UrlHeads;
+    begin(): void;
     /**
-     * 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
@@ -98,28 +93,49 @@ export declare 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;
     /**
      * 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>;
     /**
-     * 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 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)
+     *
+     * @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: UrlHeads | DocHandle<T>, second?: UrlHeads): A.Patch[];
+    /**
+     * `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
-     * 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.
+     * I'm really not convinced this is the right way to surface this information so
+     * I'm leaving this API "hidden".
      *
-     * @returns Automerge patches that go from one document state to the other. Use view() to get the full state.
+     * @hidden
      */
-    diff(first: A.Heads, second?: A.Heads): A.Patch[] | undefined;
+    metadata(change?: string): A.DecodedChange | undefined;
     /**
      * `update` is called any time we have a new document state; could be
      * from a local change, a remote change, or a new document from storage.
@@ -134,12 +150,12 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      */
     doneLoading(): void;
     /**
-     * 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): void;
+    setRemoteHeads(storageId: StorageId, heads: UrlHeads): void;
     /** Returns the heads of the storageId. */
-    getRemoteHeads(storageId: StorageId): A.Heads | undefined;
+    getRemoteHeads(storageId: StorageId): UrlHeads | undefined;
     /**
      * All changes to an Automerge document should be made through this method.
      * Inside the callback, the document should be treated as mutable: all edits will be recorded
@@ -161,7 +177,7 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
      *
      * @returns A set of heads representing the concurrent change that was made.
      */
-    changeAt(heads: A.Heads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): string[] | undefined;
+    changeAt(heads: UrlHeads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): UrlHeads[] | undefined;
     /**
      * Merges another document into this document. Any peers we are sharing changes with will be
      * notified of the changes resulting from the merge.
@@ -174,14 +190,19 @@ export declare class DocHandle<T> extends EventEmitter<DocHandleEvents<T>> {
     /** the handle of the document to merge into this one */
     otherHandle: DocHandle<T>): void;
     /**
-     * Used in testing to mark this document as unavailable.
+     * Updates the internal state machine to mark the document unavailable.
      * @hidden
      */
     unavailable(): void;
-    /** 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(): void;
+    /** Called by the repo to free memory used by the document. */
+    unload(): void;
+    /** Called by the repo to reuse an unloaded handle. */
+    reload(): void;
     /** Called by the repo when the document is deleted. */
     delete(): void;
     /**
@@ -205,6 +226,7 @@ export type DocHandleOptions<T> = {
     initialValue?: T;
 } | {
     isNew?: false;
+    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;
 };
@@ -213,7 +235,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>) => void;
     "remote-heads": (payload: DocHandleRemoteHeadsPayload) => void;
@@ -256,7 +277,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;
 }
 /**
  * Possible internal states for a DocHandle
@@ -270,11 +291,13 @@ export declare const HandleState: {
     readonly REQUESTING: "requesting";
     /** The document is available */
     readonly READY: "ready";
+    /** The document has been unloaded from the handle, to free memory usage */
+    readonly UNLOADED: "unloaded";
     /** The document has been deleted from the repo */
     readonly DELETED: "deleted";
     /** The document was not available in storage or from any connected peers */
     readonly UNAVAILABLE: "unavailable";
 };
 export type HandleState = (typeof HandleState)[keyof typeof HandleState];
-export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", DELETED: "deleted", UNAVAILABLE: "unavailable";
+export declare const IDLE: "idle", LOADING: "loading", REQUESTING: "requesting", READY: "ready", UNLOADED: "unloaded", DELETED: "deleted", UNAVAILABLE: "unavailable";
 //# 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":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}