@automerge/automerge-repo 1.0.1 → 1.0.3

package/src/network/NetworkAdapter.ts

@@ -2,23 +2,44 @@ 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 abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents> {
   peerId?: PeerId // hmmm, maybe not
 
+  /** 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
 }
 
 // events & payloads
 
 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
 }
 

package/src/network/messages.ts

@@ -1,5 +1,6 @@
 // utilities
 import { SessionId } from "../EphemeralData.js"
+export { type SessionId } from "../EphemeralData.js"
 import { DocumentId, PeerId } from "../types.js"
 
 export function isValidMessage(
@@ -55,7 +56,28 @@ export interface SyncMessageContents {
   documentId: DocumentId
 }
 
-export type SyncMessage = SyncMessageEnvelope & SyncMessageContents
+type static_assert<T extends true> = never
+
+// export type SyncMessage = SyncMessageEnvelope & SyncMessageContents
+// we inline the definitions here rather than using the above type alias because
+// otherwise typedoc can't produce nice docs. We use this `static_assert` thing
+// to make sure the types continue to line up though.
+type _check_sync_message = static_assert<SyncMessage extends SyncMessageEnvelope & SyncMessageContents ? true : false>
+/**
+ * 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
@@ -70,8 +92,35 @@ export interface EphemeralMessageContents {
   data: Uint8Array
 }
 
-export type EphemeralMessage = EphemeralMessageEnvelope &
-  EphemeralMessageContents
+// export type EphemeralMessage = EphemeralMessageEnvelope & EphemeralMessageContents
+// Inline definitions to get good docs, but check the types line up
+type _check_ephemeral_message = static_assert<EphemeralMessage extends EphemeralMessageEnvelope & EphemeralMessageContents ? true : false>
+
+/** 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"
@@ -79,8 +128,20 @@ export interface DocumentUnavailableMessageContents {
   targetId: PeerId
 }
 
-export type DocumentUnavailableMessage = SyncMessageEnvelope &
-  DocumentUnavailableMessageContents
+
+// export type DocumentUnavailableMessage = SyncMessageEnvelope & DocumentUnavailableMessageContents
+// Inline definitions to get good docs, but check the types line up
+type _check_doc_unavailable = static_assert<DocumentUnavailableMessage extends SyncMessageEnvelope & DocumentUnavailableMessageContents ? true : false>
+/** 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"
@@ -89,7 +150,29 @@ export interface RequestMessageContents {
   documentId: DocumentId
 }
 
-export type RequestMessage = SyncMessageEnvelope & RequestMessageContents
+// export type RequestMessage = SyncMessageEnvelope & RequestMessageContents
+// Inline definitions to get good docs, but check the types line up
+type _check_request_message = static_assert<RequestMessage extends SyncMessageEnvelope & RequestMessageContents ? true : false>
+// We inline the definitions here rather than using the above type alias because
+// otherwise typedoc can't produce nice docs without exporting SyncMessageEnvelope
+// and 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
@@ -97,6 +180,7 @@ export type MessageContents =
   | RequestMessageContents
   | DocumentUnavailableMessageContents
 
+/** The type of messages that {@link Repo} sends and receive to {@link NetworkAdapter}s */
 export type Message =
   | SyncMessage
   | EphemeralMessage
@@ -109,15 +193,28 @@ export type SynchronizerMessage =
   | 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

package/src/storage/StorageAdapter.ts

@@ -1,11 +1,20 @@
+/** 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 abstract class StorageAdapter {
   // load, store, or remove a single binary blob based on an array key
   // automerge-repo mostly uses keys in the following form:
   // [documentId, "snapshot"] or [documentId, "incremental", "0"]
   // but the storage adapter is agnostic to the meaning of the key
   // and we expect to store other data in the future such as syncstates
+  /** 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>
 
   // the keyprefix will match any key that starts with the given array
@@ -13,8 +22,20 @@ export abstract class StorageAdapter {
   // or [documentId] will match all data for a given document
   // be careful! this will also match [documentId, "syncState"]!
   // (we aren't using this yet but keep it in mind.)
+  /** 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[]

package/src/types.ts

@@ -1,9 +1,17 @@
+/** The ID of a document. Typically you should use a {@link AutomergeUrl} instead.
+ */
 export type DocumentId = string & { __documentId: true } // for logging
+/** 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 } // for opening / linking
+/** 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 } // for storing / syncing
 
+/** 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

package/test/Repo.test.ts

@@ -22,6 +22,9 @@ import {
   generateLargeObject,
   LargeObject,
 } from "./helpers/generate-large-object.js"
+import { parseAutomergeUrl } from "../dist/DocUrl.js"
+
+import * as Uuid from "uuid"
 
 describe("Repo", () => {
   describe("single repo", () => {
@@ -50,6 +53,34 @@ describe("Repo", () => {
       assert.equal(handle.isReady(), true)
     })
 
+    it("can find a document once it's created", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change((d: TestDoc) => {
+        d.foo = "bar"
+      })
+
+      const handle2 = repo.find(handle.url)
+      assert.equal(handle, handle2)
+      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+    })
+
+    it("can find a document using a legacy UUID (for now)", () => {
+      const { repo } = setup()
+      const handle = repo.create<TestDoc>()
+      handle.change((d: TestDoc) => {
+        d.foo = "bar"
+      })
+
+      const url = handle.url
+      const { binaryDocumentId } = parseAutomergeUrl(url)
+      const legacyDocumentId = Uuid.stringify(binaryDocumentId) as AutomergeUrl // a white lie
+
+      const handle2 = repo.find(legacyDocumentId)
+      assert.equal(handle, handle2)
+      assert.deepEqual(handle2.docSync(), { foo: "bar" })
+    })
+
     it("can change a document", async () => {
       const { repo } = setup()
       const handle = repo.create<TestDoc>()

package/test/StorageSubsystem.test.ts

@@ -9,7 +9,7 @@ import * as A from "@automerge/automerge/next"
 import { DummyStorageAdapter } from "./helpers/DummyStorageAdapter.js"
 import { NodeFSStorageAdapter } from "@automerge/automerge-repo-storage-nodefs"
 
-import { StorageSubsystem } from "../src/index.js"
+import { StorageSubsystem } from "../src/storage/StorageSubsystem.js"
 import { generateAutomergeUrl, parseAutomergeUrl } from "../src/DocUrl.js"
 
 const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "automerge-repo-tests"))

package/typedoc.json

@@ -0,0 +1,5 @@
+{
+    "extends": "../../typedoc.base.json",
+    "entryPoints": ["src/index.ts"],
+    "readme": "none"
+}