@automerge/automerge-repo 1.0.5 → 1.0.7

package/src/EphemeralData.ts

@@ -1,5 +1,5 @@
 import { DocumentId, PeerId } from "./index.js"
-import { EphemeralMessageContents } from "./network/messages.js"
+import { EphemeralMessage, MessageContents } from "./network/messages.js"
 
 // types
 /** A randomly generated string created when the {@link Repo} starts up */
@@ -12,6 +12,6 @@ export interface EphemeralDataPayload {
 }
 
 export type EphemeralDataMessageEvents = {
-  message: (event: EphemeralMessageContents) => void
+  message: (event: MessageContents<EphemeralMessage>) => void
   data: (event: EphemeralDataPayload) => void
 }

package/src/Repo.ts

@@ -5,7 +5,7 @@ import { StorageAdapter } from "./storage/StorageAdapter.js"
 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,
@@ -15,7 +15,7 @@ import {
 
 import { DocHandle } from "./DocHandle.js"
 import { EventEmitter } from "eventemitter3"
-import bs58check from "bs58check"
+import { next as Automerge } from "@automerge/automerge"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -106,9 +106,9 @@ export class Repo extends EventEmitter<RepoEvents> {
     // The synchronizer uses the network subsystem to keep documents in sync with peers.
     const synchronizer = new CollectionSynchronizer(this)
 
-    // When the synchronizer emits sync messages, send them to peers
+    // When the synchronizer emits messages, send them to peers
     synchronizer.on("message", message => {
-      this.#log(`sending sync message to ${message.targetId}`)
+      this.#log(`sending ${message.type} message to ${message.targetId}`)
       networkSubsystem.send(message)
     })
 
@@ -193,6 +193,44 @@ export class Repo extends EventEmitter<RepoEvents> {
     return handle
   }
 
+  /** Create a new DocHandle by cloning the history of an existing DocHandle.
+   *
+   * @param clonedHandle - The handle to clone
+   *
+   * @remarks This is a wrapper around the `clone` function in the Automerge library.
+   * The new `DocHandle` will have a new URL but will share history with the original,
+   * which means that changes made to the cloned handle can be sensibly merged back
+   * into the original.
+   *
+   * Any peers this `Repo` is connected to for whom `sharePolicy` returns `true` will
+   * be notified of the newly created DocHandle.
+   *
+   * @throws if the cloned handle is not yet ready or if
+   * `clonedHandle.docSync()` returns `undefined` (i.e. the handle is unavailable).
+   */
+  clone<T>(clonedHandle: DocHandle<T>) {
+    if (!clonedHandle.isReady()) {
+      throw new Error(
+        `Cloned handle is not yet in ready state.
+        (Try await handle.waitForReady() first.)`
+      )
+    }
+
+    const sourceDoc = clonedHandle.docSync()
+    if (!sourceDoc) {
+      throw new Error("Cloned handle doesn't have a document.")
+    }
+
+    const handle = this.create<T>()
+
+    handle.update(() => {
+      // we replace the document with the new cloned one
+      return Automerge.clone(sourceDoc)
+    })
+
+    return handle
+  }
+
   /**
    * Retrieves a document by id. It gets data from the local system, but also emits a `document`
    * event to advertise interest in the document.
@@ -202,7 +240,7 @@ export class Repo extends EventEmitter<RepoEvents> {
     automergeUrl: AutomergeUrl
   ): DocHandle<T> {
     if (!isValidAutomergeUrl(automergeUrl)) {
-      let maybeAutomergeUrl = parseLegacyUUID(automergeUrl)
+      const maybeAutomergeUrl = parseLegacyUUID(automergeUrl)
       if (maybeAutomergeUrl) {
         console.warn(
           "Legacy UUID document ID detected, converting to AutomergeUrl. This will be removed in a future version."
@@ -236,17 +274,13 @@ export class Repo extends EventEmitter<RepoEvents> {
     /** The documentId of the handle to delete */
     id: DocumentId | AutomergeUrl
   ) {
-    if (isValidAutomergeUrl(id)) {
-      ;({ documentId: id } = parseAutomergeUrl(id))
-    }
+    if (isValidAutomergeUrl(id)) id = parseAutomergeUrl(id).documentId
 
     const handle = this.#getHandle(id, false)
     handle.delete()
 
     delete this.#handleCache[id]
-    this.emit("delete-document", {
-      documentId: id,
-    })
+    this.emit("delete-document", { documentId: id })
   }
 }
 
@@ -267,7 +301,7 @@ export interface RepoConfig {
   sharePolicy?: SharePolicy
 }
 
-/** A function that determines whether we should share a document with a peer 
+/** 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

package/src/helpers/cbor.ts

@@ -1,10 +1,10 @@
-import { Encoder, decode as cborXdecode } from "cbor-x";
+import { Encoder, decode as cborXdecode } from "cbor-x"
 
-export function encode(obj: any): Buffer {
-  let encoder = new Encoder({tagUint8Array: false})
+export function encode(obj: unknown): Buffer {
+  const encoder = new Encoder({ tagUint8Array: false })
   return encoder.encode(obj)
 }
 
-export function decode(buf: Buffer | Uint8Array): any {
+export function decode<T = unknown>(buf: Buffer | Uint8Array): T {
   return cborXdecode(buf)
 }

package/src/helpers/pause.ts

@@ -1,9 +1,14 @@
 export const pause = (t = 0) =>
   new Promise<void>(resolve => setTimeout(() => resolve(), t))
 
-export function rejectOnTimeout<T>(promise: Promise<T>, millis: number): Promise<T> {
+export function rejectOnTimeout<T>(
+  promise: Promise<T>,
+  millis: number
+): Promise<T> {
   return Promise.race([
     promise,
-    pause(millis).then(() => { throw new Error("timeout exceeded") }),
+    pause(millis).then(() => {
+      throw new Error("timeout exceeded")
+    }),
   ])
 }

package/src/helpers/tests/network-adapter-tests.ts

@@ -1,7 +1,7 @@
-import { PeerId, Repo, type NetworkAdapter, DocumentId } from "../../index.js"
+import assert from "assert"
+import { describe, it } from "vitest"
+import { PeerId, Repo, type NetworkAdapter } from "../../index.js"
 import { eventPromise, eventPromises } from "../eventPromise.js"
-import { assert } from "chai"
-import { describe, it } from "mocha"
 import { pause } from "../pause.js"
 
 /**

package/src/helpers/withTimeout.ts

@@ -6,7 +6,7 @@ export const withTimeout = async <T>(
   promise: Promise<T>,
   t: number
 ): Promise<T> => {
-  let timeoutId: ReturnType<typeof setTimeout>
+  let timeoutId: ReturnType<typeof setTimeout> | undefined
   const timeoutPromise = new Promise<never>((_, reject) => {
     timeoutId = setTimeout(
       () => reject(new TimeoutError(`withTimeout: timed out after ${t}ms`)),
@@ -16,7 +16,7 @@ export const withTimeout = async <T>(
   try {
     return await Promise.race([promise, timeoutPromise])
   } finally {
-    clearTimeout(timeoutId!)
+    clearTimeout(timeoutId)
   }
 }
 

package/src/index.ts

@@ -16,9 +16,9 @@
  *
  * ```typescript
  * import { Repo } from "@automerge/automerge-repo";
- * 
+ *
  * const repo = new Repo({
- *   storage: <storage adapter>, 
+ *   storage: <storage adapter>,
  *   network: [<network adapter>, <network adapter>]
  * })
  *
@@ -26,47 +26,54 @@
  * ```
  */
 
-export { DocHandle, type HandleState, type DocHandleOptions, type DocHandleEvents } from "./DocHandle.js"
-export type { 
+export { Repo } from "./Repo.js"
+export { DocHandle } from "./DocHandle.js"
+export { NetworkAdapter } from "./network/NetworkAdapter.js"
+export { StorageAdapter } from "./storage/StorageAdapter.js"
+export {
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
+  stringifyAutomergeUrl,
+} from "./DocUrl.js"
+export { isValidRepoMessage } from "./network/messages.js"
+
+/** @hidden **/
+export * as cbor from "./helpers/cbor.js"
+
+// types
+
+export type {
   DocHandleChangePayload,
   DocHandleDeletePayload,
+  DocHandleEncodedChangePayload,
   DocHandleEphemeralMessagePayload,
+  DocHandleEvents,
+  DocHandleOptions,
   DocHandleOutboundEphemeralMessagePayload,
-  DocHandleEncodedChangePayload,
+  HandleState,
 } from "./DocHandle.js"
-export { NetworkAdapter } from "./network/NetworkAdapter.js"
 export type {
+  DeleteDocumentPayload,
+  DocumentPayload,
+  RepoConfig,
+  RepoEvents,
+  SharePolicy,
+} from "./Repo.js"
+export type {
+  NetworkAdapterEvents,
   OpenPayload,
   PeerCandidatePayload,
   PeerDisconnectedPayload,
-  NetworkAdapterEvents,
 } from "./network/NetworkAdapter.js"
-
-// This is a bit confusing right now, but:
-// Message is the type for messages used outside of the network adapters
-// there are some extra internal network adapter-only messages on NetworkAdapterMessage
-// and Message is (as of this writing) a union type for EphmeralMessage and SyncMessage
 export type {
-  Message,
   ArriveMessage,
-  WelcomeMessage,
-  NetworkAdapterMessage,
+  DocumentUnavailableMessage,
   EphemeralMessage,
+  Message,
+  RepoMessage,
   RequestMessage,
-  DocumentUnavailableMessage,
   SyncMessage,
-  SessionId,
+  WelcomeMessage,
 } from "./network/messages.js"
-export { isValidMessage } from "./network/messages.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 {
-  parseAutomergeUrl,
-  isValidAutomergeUrl,
-  stringifyAutomergeUrl as generateAutomergeUrl,
-} from "./DocUrl.js"
+export type { StorageKey } from "./storage/StorageAdapter.js"
 export * from "./types.js"
-
-/** @hidden **/
-export * as cbor from "./helpers/cbor.js"

package/src/network/NetworkAdapter.ts

@@ -1,6 +1,6 @@
 import { EventEmitter } from "eventemitter3"
 import { PeerId } from "../types.js"
-import { Message } from "./messages.js"
+import { RepoMessage } from "./messages.js"
 
 /** An interface representing some way to connect to other peers
  *
@@ -22,7 +22,7 @@ export abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents>
    *
    * @argument message - the message to send
    */
-  abstract send(message: Message): void
+  abstract send(message: RepoMessage): void
 
   /** Called by the {@link Repo} to disconnect from the network */
   abstract disconnect(): void
@@ -33,14 +33,18 @@ export abstract class NetworkAdapter extends EventEmitter<NetworkAdapterEvents>
 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
+  message: (payload: RepoMessage) => void
 }
 
 export interface OpenPayload {

package/src/network/NetworkSubsystem.ts

@@ -1,18 +1,15 @@
+import debug from "debug"
 import { EventEmitter } from "eventemitter3"
-import { PeerId } from "../types.js"
+import { PeerId, SessionId } from "../types.js"
 import { NetworkAdapter, PeerDisconnectedPayload } from "./NetworkAdapter.js"
-
 import {
   EphemeralMessage,
-  isEphemeralMessage,
-  isValidMessage,
-  Message,
+  RepoMessage,
   MessageContents,
+  isEphemeralMessage,
+  isValidRepoMessage,
 } from "./messages.js"
 
-import debug from "debug"
-import { SessionId } from "../EphemeralData.js"
-
 type EphemeralMessageSource = `${PeerId}:${SessionId}`
 
 const getEphemeralMessageSource = (message: EphemeralMessage) =>
@@ -69,7 +66,7 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
     })
 
     networkAdapter.on("message", msg => {
-      if (!isValidMessage(msg)) {
+      if (!isValidRepoMessage(msg)) {
         this.#log(`invalid message: ${JSON.stringify(msg)}`)
         return
       }
@@ -110,25 +107,36 @@ export class NetworkSubsystem extends EventEmitter<NetworkSubsystemEvents> {
       this.#log(`Tried to send message but peer not found: ${message.targetId}`)
       return
     }
-    this.#log(`Sending message to ${message.targetId}`)
 
-    if (isEphemeralMessage(message)) {
-      const outbound =
-        "count" in message
-          ? message
-          : {
+    /** Messages come in without a senderId and other required information; this is where we make
+     * sure they have everything they need.
+     */
+    const prepareMessage = (message: MessageContents): RepoMessage => {
+      if (message.type === "ephemeral") {
+        if ("count" in message) {
+          // existing ephemeral message from another peer; pass on without changes
+          return message as EphemeralMessage
+        } else {
+          // new ephemeral message from us; add our senderId as well as a counter and session id
+          return {
             ...message,
             count: ++this.#count,
             sessionId: this.#sessionId,
             senderId: this.peerId,
-          }
-      this.#log("Ephemeral message", outbound)
-      peer.send(outbound)
-    } else {
-      const outbound = { ...message, senderId: this.peerId }
-      this.#log("Sync message", outbound)
-      peer.send(outbound)
+          } as EphemeralMessage
+        }
+      } else {
+        // other message type; just add our senderId
+        return {
+          ...message,
+          senderId: this.peerId,
+        } as RepoMessage
+      }
     }
+
+    const outbound = prepareMessage(message)
+    this.#log("sending message", outbound)
+    peer.send(outbound as RepoMessage)
   }
 
   isReady = () => {
@@ -157,7 +165,7 @@ function randomPeerId() {
 export interface NetworkSubsystemEvents {
   peer: (payload: PeerPayload) => void
   "peer-disconnected": (payload: PeerDisconnectedPayload) => void
-  message: (payload: Message) => void
+  message: (payload: RepoMessage) => void
   ready: () => void
 }