@automerge/automerge-repo 1.0.1 → 1.0.3

package/dist/network/messages.d.ts

@@ -1,4 +1,5 @@
 import { SessionId } from "../EphemeralData.js";
+export { type SessionId } from "../EphemeralData.js";
 import { DocumentId, PeerId } from "../types.js";
 export declare function isValidMessage(message: NetworkAdapterMessage): message is SyncMessage | EphemeralMessage | RequestMessage | DocumentUnavailableMessage;
 export declare function isDocumentUnavailableMessage(message: NetworkAdapterMessage): message is DocumentUnavailableMessage;
@@ -14,7 +15,20 @@ export interface SyncMessageContents {
     targetId: PeerId;
     documentId: DocumentId;
 }
-export type SyncMessage = SyncMessageEnvelope & SyncMessageContents;
+/**
+ * A sync message for a particular document
+ */
+export type SyncMessage = {
+    /** The peer ID of the sender of this message */
+    senderId: PeerId;
+    type: "sync";
+    /** The automerge sync message */
+    data: Uint8Array;
+    /** The peer ID of the recipient of this message */
+    targetId: PeerId;
+    /** The document ID of the document this message is for */
+    documentId: DocumentId;
+};
 export interface EphemeralMessageEnvelope {
     senderId: PeerId;
     count: number;
@@ -26,32 +40,93 @@ export interface EphemeralMessageContents {
     documentId: DocumentId;
     data: Uint8Array;
 }
-export type EphemeralMessage = EphemeralMessageEnvelope & EphemeralMessageContents;
+/** An ephemeral message
+ *
+ * @remarks
+ * Ephemeral messages are not persisted anywhere and have no particular
+ * structure. `automerge-repo` will gossip them around, in order to avoid
+ * eternal loops of ephemeral messages every message has a session ID, which
+ * is a random number generated by the sender at startup time, and a sequence
+ * number. The combination of these two things allows us to discard messages
+ * we have already seen.
+ * */
+export type EphemeralMessage = {
+    /** The ID of the peer who sent this message */
+    senderId: PeerId;
+    /** A sequence number which must be incremented for each message sent by this peer */
+    count: number;
+    /** The ID of the session this message is part of. The sequence number for a given session always increases */
+    sessionId: SessionId;
+    type: "ephemeral";
+    /** The peer this message is for */
+    targetId: PeerId;
+    /** The document ID this message pertains to */
+    documentId: DocumentId;
+    /** The actual data of the message */
+    data: Uint8Array;
+};
 export interface DocumentUnavailableMessageContents {
     type: "doc-unavailable";
     documentId: DocumentId;
     targetId: PeerId;
 }
-export type DocumentUnavailableMessage = SyncMessageEnvelope & DocumentUnavailableMessageContents;
+/** Sent by a {@link Repo} to indicate that it does not have the document and none of it's connected peers do either */
+export type DocumentUnavailableMessage = {
+    /** The peer who sent this message */
+    senderId: PeerId;
+    type: "doc-unavailable";
+    /** The document which the peer claims it doesn't have */
+    documentId: DocumentId;
+    /** The peer this message is for */
+    targetId: PeerId;
+};
 export interface RequestMessageContents {
     type: "request";
     data: Uint8Array;
     targetId: PeerId;
     documentId: DocumentId;
 }
-export type RequestMessage = SyncMessageEnvelope & RequestMessageContents;
+/** Sent by a {@link Repo} to request a document from a peer
+ *
+ * @remarks
+ * This is identical to a {@link SyncMessage} except that it is sent by a {@link Repo}
+ * as the initial sync message when asking the other peer if it has the document.
+ * */
+export type RequestMessage = {
+    /** The peer who sent this message */
+    senderId: PeerId;
+    type: "request";
+    /** The initial automerge sync message */
+    data: Uint8Array;
+    /** The peer this message is for */
+    targetId: PeerId;
+    /** The document ID this message requests */
+    documentId: DocumentId;
+};
 export type MessageContents = SyncMessageContents | EphemeralMessageContents | RequestMessageContents | DocumentUnavailableMessageContents;
+/** The type of messages that {@link Repo} sends and receive to {@link NetworkAdapter}s */
 export type Message = SyncMessage | EphemeralMessage | RequestMessage | DocumentUnavailableMessage;
 export type SynchronizerMessage = SyncMessage | RequestMessage | DocumentUnavailableMessage | EphemeralMessage;
-type ArriveMessage = {
+/** Notify the network that we have arrived so everyone knows our peer ID */
+export type ArriveMessage = {
+    /** Our peer ID */
     senderId: PeerId;
     type: "arrive";
 };
-type WelcomeMessage = {
+/** Respond to an arriving peer with our peer ID */
+export type WelcomeMessage = {
+    /** Our peer ID */
     senderId: PeerId;
+    /** The ID of the peer who sent the {@link ArriveMessage} we are responding to */
     targetId: PeerId;
     type: "welcome";
 };
+/** The type of messages that {@link NetworkAdapter}s send and receive to each other
+ *
+ * @remarks
+ * It is not _required_ that a {@link NetworkAdapter} use this message type.
+ * NetworkAdapters are free to use whatever message type makes sense for their
+ * transport. However, this type is a useful default.
+ * */
 export type NetworkAdapterMessage = ArriveMessage | WelcomeMessage | Message;
-export {};
 //# sourceMappingURL=messages.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/network/messages.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEhD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,IACN,WAAW,GACX,gBAAgB,GAChB,cAAc,GACd,0BAA0B,CAU7B;AAED,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,IAAI,0BAA0B,CAEvC;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,IAAI,cAAc,CAE3B;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,IAAI,WAAW,CAExB;AAED,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,qBAAqB,GAAG,eAAe,GAC/C,OAAO,IAAI,gBAAgB,GAAG,wBAAwB,CAExD;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,MAAM,MAAM,WAAW,GAAG,mBAAmB,GAAG,mBAAmB,CAAA;AAEnE,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,SAAS,CAAA;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,WAAW,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,IAAI,EAAE,UAAU,CAAA;CACjB;AAED,MAAM,MAAM,gBAAgB,GAAG,wBAAwB,GACrD,wBAAwB,CAAA;AAE1B,MAAM,WAAW,kCAAkC;IACjD,IAAI,EAAE,iBAAiB,CAAA;IACvB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,0BAA0B,GAAG,mBAAmB,GAC1D,kCAAkC,CAAA;AAEpC,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAA;IACf,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;CACvB;AAED,MAAM,MAAM,cAAc,GAAG,mBAAmB,GAAG,sBAAsB,CAAA;AAEzE,MAAM,MAAM,eAAe,GACvB,mBAAmB,GACnB,wBAAwB,GACxB,sBAAsB,GACtB,kCAAkC,CAAA;AAEtC,MAAM,MAAM,OAAO,GACf,WAAW,GACX,gBAAgB,GAChB,cAAc,GACd,0BAA0B,CAAA;AAE9B,MAAM,MAAM,mBAAmB,GAC3B,WAAW,GACX,cAAc,GACd,0BAA0B,GAC1B,gBAAgB,CAAA;AAEpB,KAAK,aAAa,GAAG;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,QAAQ,CAAA;CACf,CAAA;AAED,KAAK,cAAc,GAAG;IACpB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,SAAS,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,qBAAqB,GAAG,aAAa,GAAG,cAAc,GAAG,OAAO,CAAA"}
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/network/messages.ts"],"names":[],"mappings":"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"}

package/dist/storage/StorageAdapter.d.ts

@@ -1,12 +1,33 @@
+/** A storage adapter represents some way of storing binary data for a {@link Repo}
+ *
+ * @remarks
+ * `StorageAdapter`s are a little like a key/value store. The keys are arrays
+ * of strings ({@link StorageKey}) and the values are binary blobs.
+ */
 export declare abstract class StorageAdapter {
+    /** Load the single blob correspongind to `key` */
     abstract load(key: StorageKey): Promise<Uint8Array | undefined>;
+    /** save the blod `data` to the key `key` */
     abstract save(key: StorageKey, data: Uint8Array): Promise<void>;
+    /** remove the blob corresponding to `key` */
     abstract remove(key: StorageKey): Promise<void>;
+    /** Load all blobs with keys that start with `keyPrefix` */
     abstract loadRange(keyPrefix: StorageKey): Promise<{
         key: StorageKey;
         data: Uint8Array;
     }[]>;
+    /** Remove all blobs with keys that start with `keyPrefix` */
     abstract removeRange(keyPrefix: StorageKey): Promise<void>;
 }
+/** The type of keys for a {@link StorageAdapter}
+ *
+ * @remarks
+ * Storage keys are arrays because they are hierarchical and the storage
+ * subsystem will need to be able to do range queries for all keys that
+ * have a particular prefix. For example, incremental changes for a given
+ * document might be stored under `[<documentId>, "incremental", <SHA256>]`.
+ * `StorageAdapter` implementations should not assume any particular structure
+ * though.
+ **/
 export type StorageKey = string[];
 //# sourceMappingURL=StorageAdapter.d.ts.map

package/dist/storage/StorageAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageAdapter.d.ts","sourceRoot":"","sources":["../../src/storage/StorageAdapter.ts"],"names":[],"mappings":"AAAA,8BAAsB,cAAc;IAMlC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAC/D,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;QAAC,GAAG,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAC,EAAE,CAAC;IACzF,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAC3D;AAED,MAAM,MAAO,UAAU,GAAG,MAAM,EAAE,CAAA"}
+{"version":3,"file":"StorageAdapter.d.ts","sourceRoot":"","sources":["../../src/storage/StorageAdapter.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,8BAAsB,cAAc;IAMlC,kDAAkD;IAClD,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAC/D,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAC/D,6CAA6C;IAC7C,QAAQ,CAAC,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAO/C,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC;QAAC,GAAG,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,UAAU,CAAA;KAAC,EAAE,CAAC;IACzF,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;CAC3D;AAED;;;;;;;;;IASI;AACJ,MAAM,MAAO,UAAU,GAAG,MAAM,EAAE,CAAA"}

package/dist/storage/StorageAdapter.js

@@ -1,2 +1,8 @@
+/** A storage adapter represents some way of storing binary data for a {@link Repo}
+ *
+ * @remarks
+ * `StorageAdapter`s are a little like a key/value store. The keys are arrays
+ * of strings ({@link StorageKey}) and the values are binary blobs.
+ */
 export class StorageAdapter {
 }

package/dist/types.d.ts

@@ -1,14 +1,25 @@
+/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
+ */
 export type DocumentId = string & {
     __documentId: true;
 };
+/** A branded string representing a URL for a document
+ *
+ * @remarks
+ * An automerge URL has the form `automerge:<base58 encoded string>`. This
+ * type is returned from various routines which validate a url.
+ *
+ */
 export type AutomergeUrl = string & {
     __documentUrl: true;
 };
+/** A document ID as a Uint8Array instead of a bas58 encoded string. Typically you should use a {@link AutomergeUrl} instead.
+ */
 export type BinaryDocumentId = Uint8Array & {
     __binaryDocumentId: true;
 };
+/** A branded type for peer IDs */
 export type PeerId = string & {
     __peerId: false;
 };
-export type DistributiveOmit<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 //# sourceMappingURL=types.d.ts.map

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,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;AAEjD,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,IAAI,CAAC,SAAS,GAAG,GAChE,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GACV,KAAK,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;GACG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,CAAA;AACxD;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAA;AAC3D;GACG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IAAE,kBAAkB,EAAE,IAAI,CAAA;CAAE,CAAA;AAExE,kCAAkC;AAClC,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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>",
@@ -65,5 +65,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9c1eb5fb161eac78a71a6e866b30879994278d22"
+  "gitHead": "4f3391cd33cd0cabfebde48dbd56749ddb6922da"
 }

package/src/DocHandle.ts

@@ -21,7 +21,18 @@ import type { DocumentId, PeerId, AutomergeUrl } from "./types.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<T> //
   extends EventEmitter<DocHandleEvents<T>>
 {
@@ -30,10 +41,16 @@ export class DocHandle<T> //
   #machine: DocHandleXstateMachine<T>
   #timeoutDelay: number
 
+  /** The URL of this document
+   *
+   * @remarks
+   * This can be used to request the document from an instance of {@link Repo}
+   */
   get url(): AutomergeUrl {
     return stringifyAutomergeUrl({ documentId: this.documentId })
   }
 
+  /** @hidden */
   constructor(
     public documentId: DocumentId,
     { isNew = false, timeoutDelay = 60_000 }: DocHandleOptions = {}
@@ -248,6 +265,7 @@ export class DocHandle<T> //
   inState = (states: HandleState[]) =>
     states.some(this.#machine?.getSnapshot().matches)
 
+  /** @hidden */
   get state() {
     return this.#machine?.getSnapshot().value
   }
@@ -303,7 +321,9 @@ export class DocHandle<T> //
     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: (doc: A.Doc<T>) => A.Doc<T>) {
     this.#machine.send(UPDATE, {
       payload: { callback },
@@ -357,15 +377,19 @@ export class DocHandle<T> //
     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)
   }
@@ -391,7 +415,8 @@ export class DocHandle<T> //
 
 // WRAPPER CLASS TYPES
 
-interface DocHandleOptions {
+/** @hidden */
+export interface DocHandleOptions {
   isNew?: boolean
   timeoutDelay?: number
 }
@@ -411,10 +436,15 @@ 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>
 }
 
@@ -444,14 +474,27 @@ export interface DocHandleEvents<T> {
 
 // 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",
 } as const
 export type HandleState = (typeof HandleState)[keyof typeof HandleState]

package/src/DocUrl.ts

@@ -3,7 +3,7 @@ import {
   type BinaryDocumentId,
   type DocumentId,
 } from "./types.js"
-import { v4 as uuid } from "uuid"
+import * as Uuid from "uuid"
 import bs58check from "bs58check"
 
 export const urlPrefix = "automerge:"
@@ -20,10 +20,6 @@ export const parseAutomergeUrl = (url: AutomergeUrl) => {
   return { binaryDocumentId, documentId }
 }
 
-interface StringifyAutomergeUrlOptions {
-  documentId: DocumentId | BinaryDocumentId
-}
-
 /**
  * Given a documentId in either canonical form, return an Automerge URL
  * Throws on invalid input.
@@ -33,7 +29,7 @@ interface StringifyAutomergeUrlOptions {
  */
 export const stringifyAutomergeUrl = ({
   documentId,
-}: StringifyAutomergeUrlOptions): AutomergeUrl => {
+}: {documentId: DocumentId | BinaryDocumentId}): AutomergeUrl => {
   if (documentId instanceof Uint8Array)
     return (urlPrefix +
       binaryToDocumentId(documentId as BinaryDocumentId)) as AutomergeUrl
@@ -63,7 +59,7 @@ export const isValidAutomergeUrl = (str: string): str is AutomergeUrl => {
  */
 export const generateAutomergeUrl = (): AutomergeUrl =>
   stringifyAutomergeUrl({
-    documentId: uuid(null, new Uint8Array(16)) as BinaryDocumentId,
+    documentId: Uuid.v4(null, new Uint8Array(16)) as BinaryDocumentId,
   })
 
 export const documentIdToBinary = (
@@ -74,6 +70,14 @@ export const documentIdToBinary = (
 export const binaryToDocumentId = (docId: BinaryDocumentId): DocumentId =>
   bs58check.encode(docId) as DocumentId
 
+export const parseLegacyUUID = (str: string): AutomergeUrl | undefined => {
+  if (Uuid.validate(str)) {
+    const uuid = Uuid.parse(str) as BinaryDocumentId
+    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/src/EphemeralData.ts

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

package/src/Repo.ts

@@ -6,20 +6,36 @@ import { StorageSubsystem } from "./storage/StorageSubsystem.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
 import { type AutomergeUrl, DocumentId, PeerId } from "./types.js"
 import { v4 as uuid } from "uuid"
-import { parseAutomergeUrl, generateAutomergeUrl, isValidAutomergeUrl } from "./DocUrl.js"
+import {
+  parseAutomergeUrl,
+  generateAutomergeUrl,
+  isValidAutomergeUrl,
+  parseLegacyUUID,
+} from "./DocUrl.js"
 
 import { DocHandle } from "./DocHandle.js"
 import { EventEmitter } from "eventemitter3"
+import bs58check from "bs58check"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
-export 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 class Repo extends EventEmitter<RepoEvents> {
   #log: debug.Debugger
 
+  /** @hidden */
   networkSubsystem: NetworkSubsystem
+  /** @hidden */
   storageSubsystem?: StorageSubsystem
   #handleCache: Record<DocumentId, DocHandle<any>> = {}
 
   /** By default, we share generously with all peers. */
+  /** @hidden */
   sharePolicy: SharePolicy = async () => true
 
   constructor({ storage, network, peerId, sharePolicy }: RepoConfig) {
@@ -61,11 +77,14 @@ export class Repo extends EventEmitter<DocCollectionEvents> {
         handle.request()
       } else {
         handle.awaitNetwork()
-        this.networkSubsystem.whenReady().then(() => {
-          handle.networkReady()
-        }).catch(err => {
-          this.#log("error waiting for network", { err })
-        })
+        this.networkSubsystem
+          .whenReady()
+          .then(() => {
+            handle.networkReady()
+          })
+          .catch(err => {
+            this.#log("error waiting for network", { err })
+          })
       }
 
       // Register the document with the synchronizer. This advertises our interest in the document.
@@ -120,7 +139,7 @@ export class Repo extends EventEmitter<DocCollectionEvents> {
     })
   }
 
-    /** Returns an existing handle if we have it; creates one otherwise. */
+  /** Returns an existing handle if we have it; creates one otherwise. */
   #getHandle<T>(
     /** The documentId of the handle to look up or create */
     documentId: DocumentId,
@@ -183,7 +202,15 @@ export class Repo extends EventEmitter<DocCollectionEvents> {
     automergeUrl: AutomergeUrl
   ): DocHandle<T> {
     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)
@@ -240,23 +267,34 @@ 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>
 
 // events & payloads
-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
 }

package/src/index.ts

@@ -1,10 +1,45 @@
-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,
+  NetworkAdapterEvents,
 } from "./network/NetworkAdapter.js"
 
 // This is a bit confusing right now, but:
@@ -13,17 +48,19 @@ export type {
 // and Message is (as of this writing) a union type for EphmeralMessage and SyncMessage
 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,
@@ -31,4 +68,5 @@ export {
 } from "./DocUrl.js"
 export * from "./types.js"
 
+/** @hidden **/
 export * as cbor from "./helpers/cbor.js"