@automerge/automerge-repo 1.0.1 → 1.0.3

package/dist/DocHandle.d.ts

@@ -2,12 +2,29 @@ import * as A from "@automerge/automerge/next";
 import { EventEmitter } from "eventemitter3";
 import { StateValue } from "xstate";
 import type { DocumentId, PeerId, AutomergeUrl } from "./types.js";
-/** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
+/** DocHandle is a wrapper around a single Automerge document that lets us
+ * listen for changes and notify the network and storage of new changes.
+ *
+ * @remarks
+ * A `DocHandle` represents a document which is being managed by a {@link Repo}.
+ * To obtain `DocHandle` use {@link Repo.find} or {@link Repo.create}.
+ *
+ * To modify the underlying document use either {@link DocHandle.change} or
+ * {@link DocHandle.changeAt}. These methods will notify the `Repo` that some
+ * change has occured and the `Repo` will save any new changes to the
+ * attached {@link StorageAdapter} and send sync messages to connected peers.
+ * */
 export declare class DocHandle<T>//
  extends EventEmitter<DocHandleEvents<T>> {
     #private;
     documentId: DocumentId;
+    /** The URL of this document
+     *
+     * @remarks
+     * This can be used to request the document from an instance of {@link Repo}
+     */
     get url(): AutomergeUrl;
+    /** @hidden */
     constructor(documentId: DocumentId, { isNew, timeoutDelay }?: DocHandleOptions);
     /**
      * Checks if the document is ready for accessing or changes.
@@ -24,6 +41,7 @@ export declare class DocHandle<T>//
     isDeleted: () => boolean;
     isUnavailable: () => boolean;
     inState: (states: HandleState[]) => boolean;
+    /** @hidden */
     get state(): StateValue;
     /**
      * Use this to block until the document handle has finished loading.
@@ -51,7 +69,9 @@ export declare class DocHandle<T>//
      * @returns the current document, or undefined if the document is not ready
      */
     docSync(): A.Doc<T> | undefined;
-    /** `update` is called by the repo when we receive changes from the network */
+    /** `update` is called by the repo when we receive changes from the network
+     * @hidden
+     * */
     update(callback: (doc: A.Doc<T>) => A.Doc<T>): void;
     /** `change` is called by the repo when the document is changed locally  */
     change(callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): void;
@@ -61,9 +81,13 @@ export declare class DocHandle<T>//
      */
     changeAt(heads: A.Heads, callback: A.ChangeFn<T>, options?: A.ChangeOptions<T>): string[] | undefined;
     unavailable(): void;
-    /** `request` is called by the repo when the document is not found in storage */
+    /** `request` is called by the repo when the document is not found in storage
+     * @hidden
+     * */
     request(): void;
+    /** @hidden */
     awaitNetwork(): void;
+    /** @hidden */
     networkReady(): void;
     /** `delete` is called by the repo when the document is deleted */
     delete(): void;
@@ -75,7 +99,8 @@ export declare class DocHandle<T>//
      */
     broadcast(message: any): void;
 }
-interface DocHandleOptions {
+/** @hidden */
+export interface DocHandleOptions {
     isNew?: boolean;
     timeoutDelay?: number;
 }
@@ -91,10 +116,15 @@ export interface DocHandleEncodedChangePayload<T> {
 export interface DocHandleDeletePayload<T> {
     handle: DocHandle<T>;
 }
+/** Emitted when a document has changed */
 export interface DocHandleChangePayload<T> {
+    /** The hande which changed */
     handle: DocHandle<T>;
+    /** The value of the document after the change */
     doc: A.Doc<T>;
+    /** The patches representing the change that occurred */
     patches: A.Patch[];
+    /** Information about the change */
     patchInfo: A.PatchInfo<T>;
 }
 export interface DocHandleEphemeralMessagePayload {
@@ -114,14 +144,27 @@ export interface DocHandleEvents<T> {
     "ephemeral-message": (payload: DocHandleEphemeralMessagePayload) => void;
     "ephemeral-message-outbound": (payload: DocHandleOutboundEphemeralMessagePayload) => void;
 }
+/**
+ * The state of a document handle
+ * @enum
+ *
+ */
 export declare const HandleState: {
+    /** The handle has been created but not yet loaded or requested */
     readonly IDLE: "idle";
+    /** We are waiting for storage to finish loading */
     readonly LOADING: "loading";
+    /** We are waiting for the network to be come ready */
     readonly AWAITING_NETWORK: "awaitingNetwork";
+    /** We are waiting for someone in the network to respond to a sync request */
     readonly REQUESTING: "requesting";
+    /** The document is available */
     readonly READY: "ready";
+    /** We were unable to load or request the document for some reason */
     readonly FAILED: "failed";
+    /** 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];
@@ -138,5 +181,4 @@ export declare const Event: {
     readonly MARK_UNAVAILABLE: "MARK_UNAVAILABLE";
 };
 export declare const IDLE: "idle", LOADING: "loading", AWAITING_NETWORK: "awaitingNetwork", REQUESTING: "requesting", READY: "ready", FAILED: "failed", DELETED: "deleted", UNAVAILABLE: "unavailable";
-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":"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"}
+{"version":3,"file":"DocHandle.d.ts","sourceRoot":"","sources":["../src/DocHandle.ts"],"names":[],"mappings":"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"}

package/dist/DocHandle.js

@@ -8,16 +8,33 @@ import { pause } from "./helpers/pause.js";
 import { TimeoutError, withTimeout } from "./helpers/withTimeout.js";
 import { stringifyAutomergeUrl } from "./DocUrl.js";
 import { encode } from "./helpers/cbor.js";
-/** DocHandle is a wrapper around a single Automerge document that lets us listen for changes. */
+/** DocHandle is a wrapper around a single Automerge document that lets us
+ * listen for changes and notify the network and storage of new changes.
+ *
+ * @remarks
+ * A `DocHandle` represents a document which is being managed by a {@link Repo}.
+ * To obtain `DocHandle` use {@link Repo.find} or {@link Repo.create}.
+ *
+ * To modify the underlying document use either {@link DocHandle.change} or
+ * {@link DocHandle.changeAt}. These methods will notify the `Repo` that some
+ * change has occured and the `Repo` will save any new changes to the
+ * attached {@link StorageAdapter} and send sync messages to connected peers.
+ * */
 export class DocHandle//
  extends EventEmitter {
     documentId;
     #log;
     #machine;
     #timeoutDelay;
+    /** The URL of this document
+     *
+     * @remarks
+     * This can be used to request the document from an instance of {@link Repo}
+     */
     get url() {
         return stringifyAutomergeUrl({ documentId: this.documentId });
     }
+    /** @hidden */
     constructor(documentId, { isNew = false, timeoutDelay = 60_000 } = {}) {
         super();
         this.documentId = documentId;
@@ -200,6 +217,7 @@ export class DocHandle//
     isDeleted = () => this.inState([HandleState.DELETED]);
     isUnavailable = () => this.inState([HandleState.UNAVAILABLE]);
     inState = (states) => states.some(this.#machine?.getSnapshot().matches);
+    /** @hidden */
     get state() {
         return this.#machine?.getSnapshot().value;
     }
@@ -250,7 +268,9 @@ export class DocHandle//
         }
         return this.#doc;
     }
-    /** `update` is called by the repo when we receive changes from the network */
+    /** `update` is called by the repo when we receive changes from the network
+     * @hidden
+     * */
     update(callback) {
         this.#machine.send(UPDATE, {
             payload: { callback },
@@ -292,15 +312,19 @@ export class DocHandle//
     unavailable() {
         this.#machine.send(MARK_UNAVAILABLE);
     }
-    /** `request` is called by the repo when the document is not found in storage */
+    /** `request` is called by the repo when the document is not found in storage
+     * @hidden
+     * */
     request() {
         if (this.#state === LOADING)
             this.#machine.send(REQUEST);
     }
+    /** @hidden */
     awaitNetwork() {
         if (this.#state === LOADING)
             this.#machine.send(AWAIT_NETWORK);
     }
+    /** @hidden */
     networkReady() {
         if (this.#state === AWAITING_NETWORK)
             this.#machine.send(NETWORK_READY);
@@ -324,14 +348,27 @@ export class DocHandle//
 }
 // STATE MACHINE TYPES
 // state
+/**
+ * The state of a document handle
+ * @enum
+ *
+ */
 export const HandleState = {
+    /** The handle has been created but not yet loaded or requested */
     IDLE: "idle",
+    /** We are waiting for storage to finish loading */
     LOADING: "loading",
+    /** We are waiting for the network to be come ready */
     AWAITING_NETWORK: "awaitingNetwork",
+    /** We are waiting for someone in the network to respond to a sync request */
     REQUESTING: "requesting",
+    /** The document is available */
     READY: "ready",
+    /** We were unable to load or request the document for some reason */
     FAILED: "failed",
+    /** The document has been deleted from the repo */
     DELETED: "deleted",
+    /** The document was not available in storage or from any connected peers */
     UNAVAILABLE: "unavailable",
 };
 // events

package/dist/DocUrl.d.ts

@@ -10,9 +10,6 @@ export declare const parseAutomergeUrl: (url: AutomergeUrl) => {
     binaryDocumentId: BinaryDocumentId;
     documentId: DocumentId;
 };
-interface StringifyAutomergeUrlOptions {
-    documentId: DocumentId | BinaryDocumentId;
-}
 /**
  * Given a documentId in either canonical form, return an Automerge URL
  * Throws on invalid input.
@@ -20,7 +17,9 @@ interface StringifyAutomergeUrlOptions {
  * @param { documentId: BinaryDocumentId | DocumentId }
  * @returns AutomergeUrl
  */
-export declare const stringifyAutomergeUrl: ({ documentId, }: StringifyAutomergeUrlOptions) => AutomergeUrl;
+export declare const stringifyAutomergeUrl: ({ documentId, }: {
+    documentId: DocumentId | BinaryDocumentId;
+}) => AutomergeUrl;
 /**
  * Given a string, return true if it is a valid Automerge URL
  * also acts as a type discriminator in Typescript.
@@ -36,5 +35,5 @@ export declare const isValidAutomergeUrl: (str: string) => str is AutomergeUrl;
 export declare const generateAutomergeUrl: () => AutomergeUrl;
 export declare const documentIdToBinary: (docId: DocumentId) => BinaryDocumentId | undefined;
 export declare const binaryToDocumentId: (docId: BinaryDocumentId) => DocumentId;
-export {};
+export declare const parseLegacyUUID: (str: string) => AutomergeUrl | undefined;
 //# 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":"AAAA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAA;AAInB,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"}
+{"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,YAAY,CAAA;AAInB,eAAO,MAAM,SAAS,eAAe,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAS,YAAY;;;CAIlD,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;gBAElB,UAAU,GAAG,gBAAgB;MAAI,YAQhD,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;AAEvC,eAAO,MAAM,eAAe,QAAS,MAAM,KAAG,YAAY,GAAG,SAM5D,CAAA"}

package/dist/DocUrl.js

@@ -1,4 +1,4 @@
-import { v4 as uuid } from "uuid";
+import * as Uuid from "uuid";
 import bs58check from "bs58check";
 export const urlPrefix = "automerge:";
 /**
@@ -47,10 +47,17 @@ export const isValidAutomergeUrl = (str) => {
  * @returns a new Automerge URL with a random UUID documentId
  */
 export const generateAutomergeUrl = () => stringifyAutomergeUrl({
-    documentId: uuid(null, new Uint8Array(16)),
+    documentId: Uuid.v4(null, new Uint8Array(16)),
 });
 export const documentIdToBinary = (docId) => bs58check.decodeUnsafe(docId);
 export const binaryToDocumentId = (docId) => bs58check.encode(docId);
+export const parseLegacyUUID = (str) => {
+    if (Uuid.validate(str)) {
+        const uuid = Uuid.parse(str);
+        return stringifyAutomergeUrl({ documentId: uuid });
+    }
+    return undefined;
+};
 /**
  * parts breaks up the URL into constituent pieces,
  * eventually this could include things like heads, so we use this structure

package/dist/EphemeralData.d.ts

@@ -1,5 +1,6 @@
 import { DocumentId, PeerId } from "./index.js";
 import { EphemeralMessageContents } from "./network/messages.js";
+/** A randomly generated string created when the {@link Repo} starts up */
 export type SessionId = string & {
     __SessionId: false;
 };

package/dist/EphemeralData.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EphemeralData.d.ts","sourceRoot":"","sources":["../src/EphemeralData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAGhE,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAChE;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IAClD,IAAI,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;CAC5C,CAAA"}
+{"version":3,"file":"EphemeralData.d.ts","sourceRoot":"","sources":["../src/EphemeralData.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAC/C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAA;AAGhE,0EAA0E;AAC1E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,WAAW,EAAE,KAAK,CAAA;CAAE,CAAA;AAEvD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAA;CAChE;AAED,MAAM,MAAM,0BAA0B,GAAG;IACvC,OAAO,EAAE,CAAC,KAAK,EAAE,wBAAwB,KAAK,IAAI,CAAA;IAClD,IAAI,EAAE,CAAC,KAAK,EAAE,oBAAoB,KAAK,IAAI,CAAA;CAC5C,CAAA"}

package/dist/Repo.d.ts

@@ -6,11 +6,21 @@ import { type AutomergeUrl, DocumentId, PeerId } from "./types.js";
 import { DocHandle } from "./DocHandle.js";
 import { EventEmitter } from "eventemitter3";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
-export declare class Repo extends EventEmitter<DocCollectionEvents> {
+/** The `Repo` is the main entry point of this library
+ *
+ * @remarks
+ * To construct a `Repo` you will need an {@link StorageAdapter} and one or
+ * more {@link NetworkAdapter}s. Once you have a `Repo` you can use it to
+ * obtain {@link DocHandle}s.
+ */
+export declare class Repo extends EventEmitter<RepoEvents> {
     #private;
+    /** @hidden */
     networkSubsystem: NetworkSubsystem;
+    /** @hidden */
     storageSubsystem?: StorageSubsystem;
     /** By default, we share generously with all peers. */
+    /** @hidden */
     sharePolicy: SharePolicy;
     constructor({ storage, network, peerId, sharePolicy }: RepoConfig);
     /** Returns all the handles we have cached. */
@@ -45,18 +55,28 @@ export interface RepoConfig {
      */
     sharePolicy?: SharePolicy;
 }
+/** A function that determines whether we should share a document with a peer
+ *
+ * @remarks
+ * This function is called by the {@link Repo} every time a new document is created
+ * or discovered (such as when another peer starts syncing with us). If this
+ * function returns `true` then the {@link Repo} will begin sharing the new
+ * document with the peer given by `peerId`.
+ * */
 export type SharePolicy = (peerId: PeerId, documentId?: DocumentId) => Promise<boolean>;
-interface DocCollectionEvents {
+export interface RepoEvents {
+    /** A new document was created or discovered */
     document: (arg: DocumentPayload) => void;
+    /** A document was deleted */
     "delete-document": (arg: DeleteDocumentPayload) => void;
+    /** A document was marked as unavailable (we don't have it and none of our peers have it) */
     "unavailable-document": (arg: DeleteDocumentPayload) => void;
 }
-interface DocumentPayload {
+export interface DocumentPayload {
     handle: DocHandle<any>;
     isNew: boolean;
 }
-interface DeleteDocumentPayload {
+export interface DeleteDocumentPayload {
     documentId: DocumentId;
 }
-export {};
 //# sourceMappingURL=Repo.d.ts.map

package/dist/Repo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAIlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,8FAA8F;AAC9F,qBAAa,IAAK,SAAQ,YAAY,CAAC,mBAAmB,CAAC;;IAGzD,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAGnC,sDAAsD;IACtD,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IAoHjE,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;IAwBf,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAchC;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,UAAU,mBAAmB;IAC3B,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,UAAU,eAAe;IACvB,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,UAAU,qBAAqB;IAC7B,UAAU,EAAE,UAAU,CAAA;CACvB"}
+{"version":3,"file":"Repo.d.ts","sourceRoot":"","sources":["../src/Repo.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAEhE,OAAO,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AASlE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,8FAA8F;AAC9F;;;;;;GAMG;AACH,qBAAa,IAAK,SAAQ,YAAY,CAAC,UAAU,CAAC;;IAGhD,cAAc;IACd,gBAAgB,EAAE,gBAAgB,CAAA;IAClC,cAAc;IACd,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAGnC,sDAAsD;IACtD,cAAc;IACd,WAAW,EAAE,WAAW,CAAmB;gBAE/B,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,UAAU;IAuHjE,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;IAgCf,MAAM;IACJ,6CAA6C;IAC7C,EAAE,EAAE,UAAU,GAAG,YAAY;CAchC;AAED,MAAM,WAAW,UAAU;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,gDAAgD;IAChD,OAAO,CAAC,EAAE,cAAc,CAAA;IAExB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAA;IAEzB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAA;CAC1B;AAED;;;;;;;KAOK;AACL,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,UAAU,KACpB,OAAO,CAAC,OAAO,CAAC,CAAA;AAGrB,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,QAAQ,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACxC,6BAA6B;IAC7B,iBAAiB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACvD,4FAA4F;IAC5F,sBAAsB,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,CAAA;CAC7D;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,CAAA;IACtB,KAAK,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,UAAU,CAAA;CACvB"}

package/dist/Repo.js

@@ -2,16 +2,26 @@ import debug from "debug";
 import { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 import { StorageSubsystem } from "./storage/StorageSubsystem.js";
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
-import { parseAutomergeUrl, generateAutomergeUrl, isValidAutomergeUrl } from "./DocUrl.js";
+import { parseAutomergeUrl, generateAutomergeUrl, isValidAutomergeUrl, parseLegacyUUID, } from "./DocUrl.js";
 import { DocHandle } from "./DocHandle.js";
 import { EventEmitter } from "eventemitter3";
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
+/** The `Repo` is the main entry point of this library
+ *
+ * @remarks
+ * To construct a `Repo` you will need an {@link StorageAdapter} and one or
+ * more {@link NetworkAdapter}s. Once you have a `Repo` you can use it to
+ * obtain {@link DocHandle}s.
+ */
 export class Repo extends EventEmitter {
     #log;
+    /** @hidden */
     networkSubsystem;
+    /** @hidden */
     storageSubsystem;
     #handleCache = {};
     /** By default, we share generously with all peers. */
+    /** @hidden */
     sharePolicy = async () => true;
     constructor({ storage, network, peerId, sharePolicy }) {
         super();
@@ -49,9 +59,12 @@ export class Repo extends EventEmitter {
             }
             else {
                 handle.awaitNetwork();
-                this.networkSubsystem.whenReady().then(() => {
+                this.networkSubsystem
+                    .whenReady()
+                    .then(() => {
                     handle.networkReady();
-                }).catch(err => {
+                })
+                    .catch(err => {
                     this.#log("error waiting for network", { err });
                 });
             }
@@ -151,7 +164,14 @@ export class Repo extends EventEmitter {
     /** The documentId of the handle to retrieve */
     automergeUrl) {
         if (!isValidAutomergeUrl(automergeUrl)) {
-            throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`);
+            let maybeAutomergeUrl = parseLegacyUUID(automergeUrl);
+            if (maybeAutomergeUrl) {
+                console.warn("Legacy UUID document ID detected, converting to AutomergeUrl. This will be removed in a future version.");
+                automergeUrl = maybeAutomergeUrl;
+            }
+            else {
+                throw new Error(`Invalid AutomergeUrl: '${automergeUrl}'`);
+            }
         }
         const { documentId } = parseAutomergeUrl(automergeUrl);
         // If we have the handle cached, return it

package/dist/index.d.ts

@@ -1,15 +1,40 @@
-export { DocHandle, HandleState } from "./DocHandle.js";
-export type { DocHandleChangePayload } from "./DocHandle.js";
+/**
+ * @packageDocumentation
+ *
+ * The [`automerge`](https://www.npmjs.com/package/@automerge/automerge) CRDT
+ * provides a core CRDT data structure and an implementation of a storage
+ * format and sync protocol but doesn't provide the plumbing to use these tools
+ * in a JS application. `automerge-repo` provides the plumbing.
+ *
+ * The main entry point is the {@link Repo} class, which you instantiate with
+ * a {@link StorageAdapter} and zero or more {@link NetworkAdapter}s. Once you
+ * have a repo you can use it to create {@link DocHandle}s. {@link DocHandle}s
+ * are a reference to a document, identified by a {@link AutomergeUrl}, a place to
+ * listen for changes to the document, and to make new changes.
+ *
+ * A typical example of how to use this library then might look like this:
+ *
+ * ```typescript
+ * import { Repo } from "@automerge/automerge-repo";
+ *
+ * const repo = new Repo({
+ *   storage: <storage adapter>,
+ *   network: [<network adapter>, <network adapter>]
+ * })
+ *
+ * const handle = repo.create
+ * ```
+ */
+export { DocHandle, type HandleState, type DocHandleOptions, type DocHandleEvents } from "./DocHandle.js";
+export type { DocHandleChangePayload, DocHandleDeletePayload, DocHandleEphemeralMessagePayload, DocHandleOutboundEphemeralMessagePayload, DocHandleEncodedChangePayload, } from "./DocHandle.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
-export type { OpenPayload, PeerCandidatePayload, PeerDisconnectedPayload, } from "./network/NetworkAdapter.js";
-export type { Message, NetworkAdapterMessage, EphemeralMessage, SyncMessage, } from "./network/messages.js";
+export type { OpenPayload, PeerCandidatePayload, PeerDisconnectedPayload, NetworkAdapterEvents, } from "./network/NetworkAdapter.js";
+export type { Message, ArriveMessage, WelcomeMessage, NetworkAdapterMessage, EphemeralMessage, RequestMessage, DocumentUnavailableMessage, SyncMessage, SessionId, } from "./network/messages.js";
 export { isValidMessage } from "./network/messages.js";
-export { NetworkSubsystem } from "./network/NetworkSubsystem.js";
-export { Repo, type SharePolicy } from "./Repo.js";
+export { Repo, type SharePolicy, type RepoConfig, type RepoEvents, type DeleteDocumentPayload, type DocumentPayload } from "./Repo.js";
 export { StorageAdapter, type StorageKey } from "./storage/StorageAdapter.js";
-export { StorageSubsystem } from "./storage/StorageSubsystem.js";
-export { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
 export { parseAutomergeUrl, isValidAutomergeUrl, stringifyAutomergeUrl as generateAutomergeUrl, } from "./DocUrl.js";
 export * from "./types.js";
+/** @hidden **/
 export * as cbor from "./helpers/cbor.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,6BAA6B,CAAA;AAMpC,YAAY,EACV,OAAO,EACP,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,GACZ,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAA;AACjF,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,IAAI,oBAAoB,GAC9C,MAAM,aAAa,CAAA;AACpB,cAAc,YAAY,CAAA;AAE1B,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACzG,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,gCAAgC,EAChC,wCAAwC,EACxC,6BAA6B,GAC9B,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,6BAA6B,CAAA;AAMpC,YAAY,EACV,OAAO,EACP,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,cAAc,EACd,0BAA0B,EAC1B,WAAW,EACX,SAAS,GACV,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEtD,OAAO,EAAE,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AACtI,OAAO,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAC7E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,IAAI,oBAAoB,GAC9C,MAAM,aAAa,CAAA;AACpB,cAAc,YAAY,CAAA;AAE1B,eAAe;AACf,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -1,11 +1,36 @@
-export { DocHandle, HandleState } from "./DocHandle.js";
+/**
+ * @packageDocumentation
+ *
+ * The [`automerge`](https://www.npmjs.com/package/@automerge/automerge) CRDT
+ * provides a core CRDT data structure and an implementation of a storage
+ * format and sync protocol but doesn't provide the plumbing to use these tools
+ * in a JS application. `automerge-repo` provides the plumbing.
+ *
+ * The main entry point is the {@link Repo} class, which you instantiate with
+ * a {@link StorageAdapter} and zero or more {@link NetworkAdapter}s. Once you
+ * have a repo you can use it to create {@link DocHandle}s. {@link DocHandle}s
+ * are a reference to a document, identified by a {@link AutomergeUrl}, a place to
+ * listen for changes to the document, and to make new changes.
+ *
+ * A typical example of how to use this library then might look like this:
+ *
+ * ```typescript
+ * import { Repo } from "@automerge/automerge-repo";
+ *
+ * const repo = new Repo({
+ *   storage: <storage adapter>,
+ *   network: [<network adapter>, <network adapter>]
+ * })
+ *
+ * const handle = repo.create
+ * ```
+ */
+export { DocHandle } from "./DocHandle.js";
 export { NetworkAdapter } from "./network/NetworkAdapter.js";
 export { isValidMessage } from "./network/messages.js";
-export { NetworkSubsystem } from "./network/NetworkSubsystem.js";
 export { Repo } from "./Repo.js";
 export { StorageAdapter } from "./storage/StorageAdapter.js";
-export { StorageSubsystem } from "./storage/StorageSubsystem.js";
-export { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js";
 export { parseAutomergeUrl, isValidAutomergeUrl, stringifyAutomergeUrl as generateAutomergeUrl, } from "./DocUrl.js";
 export * from "./types.js";
+/** @hidden **/
 export * as cbor from "./helpers/cbor.js";

package/dist/network/NetworkAdapter.d.ts

@@ -1,17 +1,38 @@
 import { EventEmitter } from "eventemitter3";
 import { PeerId } from "../types.js";
 import { Message } from "./messages.js";
+/** An interface representing some way to connect to other peers
+ *
+ * @remarks
+ * The {@link Repo} uses one or more `NetworkAdapter`s to connect to other peers.
+ * Because the network may take some time to be ready the {@link Repo} will wait
+ * until the adapter emits a `ready` event before it starts trying to use it
+ */
 export declare abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents> {
     peerId?: PeerId;
+    /** Called by the {@link Repo} to start the connection process
+     *
+     * @argument peerId - the peerId of this repo
+     */
     abstract connect(peerId: PeerId): void;
+    /** Called by the {@link Repo} to send a message to a peer
+     *
+     * @argument message - the message to send
+     */
     abstract send(message: Message): void;
+    /** Called by the {@link Repo} to disconnect from the network */
     abstract disconnect(): void;
 }
 export interface NetworkAdapterEvents {
+    /** Emitted when the network is ready to be used */
     ready: (payload: OpenPayload) => void;
+    /** Emitted when the network is closed */
     close: () => void;
+    /** Emitted when the network adapter learns about a new peer */
     "peer-candidate": (payload: PeerCandidatePayload) => void;
+    /** Emitted when the network adapter learns that a peer has disconnected */
     "peer-disconnected": (payload: PeerDisconnectedPayload) => void;
+    /** Emitted when the network adapter receives a message from a peer */
     message: (payload: Message) => void;
 }
 export interface OpenPayload {

package/dist/network/NetworkAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkAdapter.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC,8BAAsB,cAAe,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAEtC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAErC,QAAQ,CAAC,UAAU,IAAI,IAAI;CAC5B;AAID,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACrC,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IACzD,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC/D,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;CACf"}
+{"version":3,"file":"NetworkAdapter.d.ts","sourceRoot":"","sources":["../../src/network/NetworkAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAEvC;;;;;;GAMG;AACH,8BAAsB,cAAe,SAAQ,YAAY,CAAC,oBAAoB,CAAC;IAC7E,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAEtC;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAErC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,IAAI,IAAI;CAC5B;AAID,MAAM,WAAW,oBAAoB;IACnC,mDAAmD;IACnD,KAAK,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAA;IACrC,yCAAyC;IACzC,KAAK,EAAE,MAAM,IAAI,CAAA;IACjB,+DAA+D;IAC/D,gBAAgB,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,CAAA;IACzD,2EAA2E;IAC3E,mBAAmB,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,IAAI,CAAA;IAC/D,sEAAsE;IACtE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAA;CACpC;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,cAAc,CAAA;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAA;CACf"}

package/dist/network/NetworkAdapter.js

@@ -1,4 +1,11 @@
 import { EventEmitter } from "eventemitter3";
+/** An interface representing some way to connect to other peers
+ *
+ * @remarks
+ * The {@link Repo} uses one or more `NetworkAdapter`s to connect to other peers.
+ * Because the network may take some time to be ready the {@link Repo} will wait
+ * until the adapter emits a `ready` event before it starts trying to use it
+ */
 export class NetworkAdapter extends EventEmitter {
     peerId; // hmmm, maybe not
 }