@automerge/automerge-repo 1.0.6 → 1.0.8

package/src/DocHandle.ts

@@ -14,12 +14,11 @@ import {
   TypegenDisabled,
 } from "xstate"
 import { waitFor } from "xstate/lib/waitFor.js"
-import { headsAreSame } from "./helpers/headsAreSame.js"
-import { pause } from "./helpers/pause.js"
-import { TimeoutError, withTimeout } from "./helpers/withTimeout.js"
-import type { DocumentId, PeerId, AutomergeUrl } from "./types.js"
 import { stringifyAutomergeUrl } from "./DocUrl.js"
 import { encode } from "./helpers/cbor.js"
+import { headsAreSame } from "./helpers/headsAreSame.js"
+import { withTimeout } from "./helpers/withTimeout.js"
+import type { AutomergeUrl, DocumentId, PeerId } from "./types.js"
 
 /** DocHandle is a wrapper around a single Automerge document that lets us
  * listen for changes and notify the network and storage of new changes.
@@ -290,14 +289,12 @@ export class DocHandle<T> //
   async doc(
     awaitStates: HandleState[] = [READY, UNAVAILABLE]
   ): Promise<A.Doc<T> | undefined> {
-    await pause() // yield one tick because reasons
     try {
       // wait for the document to enter one of the desired states
       await this.#statePromise(awaitStates)
     } catch (error) {
-      if (error instanceof TimeoutError)
-        throw new Error(`DocHandle: timed out loading ${this.documentId}`)
-      else throw error
+      // if we timed out (or the load has already failed), return undefined
+      return undefined
     }
     // Return the document
     return !this.isUnavailable() ? this.#doc : undefined
@@ -431,7 +428,7 @@ export class DocHandle<T> //
    * a user could have multiple tabs open and would appear as multiple PeerIds.
    * every message source must have a unique PeerId.
    */
-  broadcast(message: any) {
+  broadcast(message: unknown) {
     this.emit("ephemeral-message-outbound", {
       handle: this,
       data: encode(message),
@@ -474,14 +471,14 @@ export interface DocHandleChangePayload<T> {
   patchInfo: A.PatchInfo<T>
 }
 
-export interface DocHandleEphemeralMessagePayload {
-  handle: DocHandle<any>
+export interface DocHandleEphemeralMessagePayload<T> {
+  handle: DocHandle<T>
   senderId: PeerId
   message: unknown
 }
 
-export interface DocHandleOutboundEphemeralMessagePayload {
-  handle: DocHandle<any>
+export interface DocHandleOutboundEphemeralMessagePayload<T> {
+  handle: DocHandle<T>
   data: Uint8Array
 }
 
@@ -490,9 +487,9 @@ export interface DocHandleEvents<T> {
   change: (payload: DocHandleChangePayload<T>) => void
   delete: (payload: DocHandleDeletePayload<T>) => void
   unavailable: (payload: DocHandleDeletePayload<T>) => void
-  "ephemeral-message": (payload: DocHandleEphemeralMessagePayload) => void
+  "ephemeral-message": (payload: DocHandleEphemeralMessagePayload<T>) => void
   "ephemeral-message-outbound": (
-    payload: DocHandleOutboundEphemeralMessagePayload
+    payload: DocHandleOutboundEphemeralMessagePayload<T>
   ) => void
 }
 

package/src/DocUrl.ts

@@ -29,7 +29,9 @@ export const parseAutomergeUrl = (url: AutomergeUrl) => {
  */
 export const stringifyAutomergeUrl = ({
   documentId,
-}: {documentId: DocumentId | BinaryDocumentId}): AutomergeUrl => {
+}: {
+  documentId: DocumentId | BinaryDocumentId
+}): AutomergeUrl => {
   if (documentId instanceof Uint8Array)
     return (urlPrefix +
       binaryToDocumentId(documentId as BinaryDocumentId)) as AutomergeUrl

package/src/Repo.ts

@@ -1,21 +1,20 @@
+import { next as Automerge } from "@automerge/automerge"
 import debug from "debug"
-import { NetworkAdapter } from "./network/NetworkAdapter.js"
-import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
-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 { EventEmitter } from "eventemitter3"
+import { DocHandle, DocHandleEncodedChangePayload } from "./DocHandle.js"
 import {
-  parseAutomergeUrl,
   generateAutomergeUrl,
   isValidAutomergeUrl,
+  parseAutomergeUrl,
   parseLegacyUUID,
 } from "./DocUrl.js"
-
-import { DocHandle } from "./DocHandle.js"
-import { EventEmitter } from "eventemitter3"
-import { next as Automerge } from "@automerge/automerge"
+import { throttle } from "./helpers/throttle.js"
+import { NetworkAdapter } from "./network/NetworkAdapter.js"
+import { NetworkSubsystem } from "./network/NetworkSubsystem.js"
+import { StorageAdapter } from "./storage/StorageAdapter.js"
+import { StorageSubsystem } from "./storage/StorageSubsystem.js"
+import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
+import { DocumentId, PeerId, type AutomergeUrl } from "./types.js"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -32,6 +31,11 @@ export class Repo extends EventEmitter<RepoEvents> {
   networkSubsystem: NetworkSubsystem
   /** @hidden */
   storageSubsystem?: StorageSubsystem
+
+  /** The debounce rate is adjustable on the repo. */
+  /** @hidden */
+  saveDebounceRate = 100
+
   #handleCache: Record<DocumentId, DocHandle<any>> = {}
 
   /** By default, we share generously with all peers. */
@@ -49,10 +53,17 @@ export class Repo extends EventEmitter<RepoEvents> {
     // up a document by ID. We listen for it in order to wire up storage and network synchronization.
     this.on("document", async ({ handle, isNew }) => {
       if (storageSubsystem) {
-        // Save when the document changes
-        handle.on("heads-changed", async ({ handle, doc }) => {
-          await storageSubsystem.saveDoc(handle.documentId, doc)
-        })
+        // Save when the document changes, but no more often than saveDebounceRate.
+        const saveFn = ({
+          handle,
+          doc,
+        }: DocHandleEncodedChangePayload<any>) => {
+          void storageSubsystem.saveDoc(handle.documentId, doc)
+        }
+        const debouncedSaveFn = handle.on(
+          "heads-changed",
+          throttle(saveFn, this.saveDebounceRate)
+        )
 
         if (isNew) {
           // this is a new document, immediately save it
@@ -106,9 +117,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)
     })
 
@@ -198,9 +209,9 @@ export class Repo extends EventEmitter<RepoEvents> {
    * @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. 
+   * 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.
@@ -223,7 +234,7 @@ export class Repo extends EventEmitter<RepoEvents> {
 
     const handle = this.create<T>()
 
-    handle.update((doc: Automerge.Doc<T>) => {
+    handle.update(() => {
       // we replace the document with the new cloned one
       return Automerge.clone(sourceDoc)
     })
@@ -240,7 +251,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."
@@ -274,17 +285,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 })
   }
 }
 

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/debounce.ts

@@ -0,0 +1,25 @@
+/** throttle( callback, rate )
+ * Returns a throttle function with a build in debounce timer that runs after `wait` ms.
+ *
+ * Note that the args go inside the parameter and you should be careful not to
+ * recreate the function on each usage. (In React, see useMemo().)
+ *
+ *
+ * Example usage:
+ * const callback = throttle((ev) => { doSomethingExpensiveOrOccasional() }, 100)
+ * target.addEventListener('frequent-event', callback);
+ *
+ */
+
+export const throttle = <F extends (...args: Parameters<F>) => ReturnType<F>>(
+  fn: F,
+  rate: number
+) => {
+  let timeout: ReturnType<typeof setTimeout>
+  return function (...args: Parameters<F>) {
+    clearTimeout(timeout)
+    timeout = setTimeout(() => {
+      fn.apply(null, args)
+    }, rate)
+  }
+}

package/src/helpers/headsAreSame.ts

@@ -1,4 +1,4 @@
-import {Heads} from "@automerge/automerge/next"
+import { Heads } from "@automerge/automerge/next"
 import { arraysAreEqual } from "./arraysAreEqual.js"
 
 export const headsAreSame = (a: Heads, b: Heads) => {

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/throttle.ts

@@ -0,0 +1,43 @@
+/** Throttle
+ * Returns a function with a built in throttle timer that runs after `delay` ms.
+ *
+ * This function differs from a conventional `throttle` in that it ensures the final
+ * call will also execute and delays sending the first one until `delay` ms to allow
+ * additional work to accumulate.
+ *
+ * Here's a diagram:
+ *
+ * calls +----++++++-----++----
+ * dlay  ^--v ^--v^--v   ^--v
+ * execs ---+----+---+------+--
+ *
+ * The goal in this design is to create batches of changes without flooding
+ * communication or storage systems while still feeling responsive.
+ * (By default we communicate at 10hz / every 100ms.)
+ *
+ * Note that the args go inside the parameter and you should be careful not to
+ * recreate the function on each usage. (In React, see useMemo().)
+ *
+ *
+ * Example usage:
+ * const callback = debounce((ev) => { doSomethingExpensiveOrOccasional() }, 100)
+ * target.addEventListener('frequent-event', callback);
+ *
+ */
+
+export const throttle = <F extends (...args: Parameters<F>) => ReturnType<F>>(
+  fn: F,
+  delay: number
+) => {
+  let lastCall = Date.now()
+  let wait
+  let timeout: ReturnType<typeof setTimeout>
+  return function (...args: Parameters<F>) {
+    wait = lastCall + delay - Date.now()
+    clearTimeout(timeout)
+    timeout = setTimeout(() => {
+      fn.apply(null, args)
+      lastCall = Date.now()
+    }, wait)
+  }
+}

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 { DocHandle } from "./DocHandle.js"
+export {
+  isValidAutomergeUrl,
+  parseAutomergeUrl,
+  stringifyAutomergeUrl,
+} from "./DocUrl.js"
+export { Repo } from "./Repo.js"
+export { NetworkAdapter } from "./network/NetworkAdapter.js"
+export { isValidRepoMessage } from "./network/messages.js"
+export { StorageAdapter } from "./storage/StorageAdapter.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,
   MessageContents,
+  RepoMessage,
+  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
 }