Signal finder

examples/react-counter/src/main.tsx

@@ -38,7 +38,7 @@ declare global {
 const rootDocUrl = `${document.location.hash.substring(1)}`
 let handle
 if (isValidAutomergeUrl(rootDocUrl)) {
-  handle = repo.find(rootDocUrl)
+  handle = await repo.find(rootDocUrl)
 } else {
   handle = repo.create<{ count: number }>({ count: 0 })
 }

examples/react-todo/package.json

@@ -19,7 +19,8 @@
     "classnames": "^2.3.2",
     "postcss": "^8.4.21",
     "react": "^18.2.0",
-    "react-dom": "^18.2.0"
+    "react-dom": "^18.2.0",
+    "react-error-boundary": "^5.0.0"
   },
   "devDependencies": {
     "tailwindcss": "^3.2.4"

examples/react-todo/src/App.tsx

@@ -1,7 +1,7 @@
 import { AutomergeUrl } from "@automerge/automerge-repo"
 import { useDocument, useRepo } from "@automerge/automerge-repo-react-hooks"
 import cx from "classnames"
-import { useRef, useState } from "react"
+import { Suspense, useRef, useState } from "react"
 
 import { Todo } from "./Todo.js"
 import { ExtendedArray, Filter, State, TodoData } from "./types.js"
@@ -28,7 +28,7 @@ export function App({ url }: { url: AutomergeUrl }) {
     if (!state) return []
     return state.todos.filter(async url => {
       if (filter === Filter.all) return true
-      const todo = await repo.find<TodoData>(url).doc()
+      const todo = (await repo.find<TodoData>(url)).doc()
       if (filter === Filter.completed) return todo.completed
       if (filter === Filter.incomplete) return !todo.completed
       return false
@@ -38,7 +38,7 @@ export function App({ url }: { url: AutomergeUrl }) {
   const destroyCompleted = async () => {
     if (!state) return
     for (const url of await getFilteredTodos(Filter.completed)) {
-      const todo = await repo.find<TodoData>(url).doc()
+      const todo = (await repo.find<TodoData>(url)).doc()
       if (todo.completed) destroy(url)
     }
   }
@@ -89,16 +89,18 @@ export function App({ url }: { url: AutomergeUrl }) {
 
           {/* todos */}
           <section>
-            <ul className="border-y divide-y divide-solid">
-              {state.todos.map(url => (
-                <Todo
-                  key={url}
-                  url={url}
-                  onDestroy={url => destroy(url)}
-                  filter={filter}
-                />
-              ))}
-            </ul>
+            <Suspense fallback={<li>Loading todo items...</li>}>
+              <ul className="border-y divide-y divide-solid">
+                {state.todos.map(url => (
+                  <Todo
+                    key={url}
+                    url={url}
+                    onDestroy={url => destroy(url)}
+                    filter={filter}
+                  />
+                ))}
+              </ul>
+            </Suspense>
           </section>
 
           {/* footer tools */}

examples/react-todo/src/main.tsx

@@ -3,7 +3,8 @@ import { BroadcastChannelNetworkAdapter } from "@automerge/automerge-repo-networ
 import { BrowserWebSocketClientAdapter } from "@automerge/automerge-repo-network-websocket"
 import { RepoContext } from "@automerge/automerge-repo-react-hooks"
 import { IndexedDBStorageAdapter } from "@automerge/automerge-repo-storage-indexeddb"
-import React from "react"
+import React, { Suspense } from "react"
+import { ErrorBoundary } from "react-error-boundary"
 import ReactDOM from "react-dom/client"
 import { App } from "./App.js"
 import { State } from "./types.js"
@@ -27,7 +28,7 @@ declare global {
 const rootDocUrl = `${document.location.hash.substring(1)}`
 let handle
 if (isValidAutomergeUrl(rootDocUrl)) {
-  handle = repo.find(rootDocUrl)
+  handle = await repo.find(rootDocUrl)
 } else {
   handle = repo.create<State>({ todos: [] })
 }
@@ -38,7 +39,11 @@ window.repo = repo
 ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
   <RepoContext.Provider value={repo}>
     <React.StrictMode>
-      <App url={docUrl} />
+      <ErrorBoundary fallback={<div>Something went wrong</div>}>
+        <Suspense fallback={<div>Loading...</div>}>
+          <App url={docUrl} />
+        </Suspense>
+      </ErrorBoundary>
     </React.StrictMode>
   </RepoContext.Provider>
 )

packages/automerge-repo-network-websocket/test/Websocket.test.ts

@@ -518,8 +518,7 @@ describe("Websocket adapters", () => {
       })
 
       // make a change to the handle on the sync server
-      const handle = repo.find<{ foo: string }>(url)
-      await handle.whenReady()
+      const handle = await repo.find<{ foo: string }>(url)
       handle.change(d => (d.foo = "baz"))
 
       // Okay, so now there is a document on both the client and the server
@@ -621,7 +620,7 @@ describe("Websocket adapters", () => {
 
       let localHeads = A.getHeads(clientDoc)
       let remoteHeads = handle.heads()
-      if (!headsAreSame(localHeads, remoteHeads)) {
+      if (!headsAreSame(localHeads, remoteHeads || [])) {
         throw new Error("heads not equal")
       }
     })

packages/automerge-repo-react-hooks/README.md

@@ -19,6 +19,6 @@ Most hooks depend on RepoContext being available.
 
 Return a document & updater fn, by ID.
 
-#### [useHandle](./src/useHandle.ts)
+#### [useDocHandle](./src/useDocHandle.ts)
 
 Return a handle, by ID.

packages/automerge-repo-react-hooks/package.json

@@ -22,8 +22,10 @@
     "react-usestateref": "^1.0.8"
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^14.0.0",
     "jsdom": "^22.1.0",
+    "react-error-boundary": "^5.0.0",
     "rollup-plugin-visualizer": "^5.9.3",
     "vite-plugin-dts": "^3.9.1"
   },

packages/automerge-repo-react-hooks/src/index.ts

@@ -11,9 +11,9 @@
  * Most hooks depend on RepoContext being available.
  *
  * #### {@link useDocument}
- * Return the current state of a document (or undefined) and a change function.
+ * Return the current state of a document and a change function.
  *
- * #### {@link useHandle}
+ * #### {@link useDocHandle}
  * Return a DocHandle by passing in a DocumentURL.
  *
  * #### {@link useLocalAwareness} & {@link useRemoteAwareness}
@@ -25,7 +25,7 @@
  */
 export { useDocument } from "./useDocument.js"
 export { useDocuments } from "./useDocuments.js"
-export { useHandle } from "./useHandle.js"
+export { useDocHandle } from "./useDocHandle.js"
 export { RepoContext, useRepo } from "./useRepo.js"
 export {
   useLocalAwareness,

packages/automerge-repo-react-hooks/src/useDocHandle.ts

@@ -0,0 +1,97 @@
+import {
+  AnyDocumentId,
+  compute,
+  DocHandle,
+  Signal,
+} from "@automerge/automerge-repo/slim"
+import { PromiseWrapper, wrapPromise } from "./wrapPromise.js"
+import { useRepo } from "./useRepo.js"
+import { useEffect, useRef, useState } from "react"
+import { abortable } from "@automerge/automerge-repo/helpers/abortable.js"
+import { FindProgress } from "../../automerge-repo/dist/FindProgress.js"
+
+// Shared with useDocHandles
+export const promiseCache = new Map<
+  AnyDocumentId,
+  PromiseWrapper<DocHandle<unknown>>
+>()
+
+interface UseDocHandleSuspendingParams {
+  suspense: true
+}
+interface UseDocHandleSynchronousParams {
+  suspense: false
+}
+
+type UseDocHandleParams =
+  | UseDocHandleSuspendingParams
+  | UseDocHandleSynchronousParams
+export function useDocHandle<T>(
+  id: AnyDocumentId,
+  options: UseDocHandleSuspendingParams
+): DocHandle<T>
+export function useDocHandle<T>(
+  id: AnyDocumentId,
+  { suspense }: UseDocHandleParams = { suspense: false }
+): DocHandle<T> | undefined {
+  const repo = useRepo()
+  const controllerRef = useRef<AbortController>()
+
+  // Cleanup effect for when id changes or component unmounts
+  useEffect(() => {
+    return () => {
+      controllerRef.current?.abort()
+      promiseCache.delete(id)
+    }
+  }, [id])
+
+  // Get current progress
+  const progSig = repo.findWithSignalProgress<T>(id)
+  const progress = progSig.peek()
+
+  // For ready state, we can return the handle immediately
+  if (progress.state === "ready") {
+    return progress.handle as DocHandle<T>
+  }
+
+  // For non-suspense mode, return undefined
+  if (!suspense) {
+    return undefined
+  }
+
+  // If we're here, we're in suspense mode and not ready.
+  let wrapper = promiseCache.get(id) as PromiseWrapper<DocHandle<T>> | undefined
+  if (!wrapper) {
+    controllerRef.current?.abort()
+    controllerRef.current = new AbortController()
+
+    const promise = handlePromise<T>(progSig, id)
+    const abortPromise = abortable(controllerRef.current?.signal)
+    wrapper = wrapPromise(Promise.race([promise, abortPromise]))
+
+    promiseCache.set(id, wrapper as any)
+  }
+
+  return wrapper.read()
+}
+
+function handlePromise<T>(
+  progSig: Signal<FindProgress<T>>,
+  id: AnyDocumentId
+): Promise<DocHandle<T>> {
+  return new Promise<DocHandle<T>>((resolve, reject) => {
+    compute(get => {
+      const prog = get(progSig)
+
+      if (prog.state === "ready") {
+        resolve(prog.handle as DocHandle<T>)
+      } else if (prog.state === "failed") {
+        reject(prog.error)
+      } else if (prog.state === "unavailable") {
+        reject(new Error(`Document ${id} is unavailable`))
+      }
+
+      return prog
+    })
+  })
+}

packages/automerge-repo-react-hooks/src/useDocHandles.ts

@@ -0,0 +1,75 @@
+import { AutomergeUrl, DocHandle } from "@automerge/automerge-repo/slim"
+import { useState, useEffect } from "react"
+import { useRepo } from "./useRepo.js"
+import { PromiseWrapper, wrapPromise } from "./wrapPromise.js"
+import { promiseCache } from "./useDocHandle.js"
+
+interface UseDocHandlesParams {
+  suspense?: boolean
+}
+
+type DocHandleMap<T> = Map<AutomergeUrl, DocHandle<T> | undefined>
+
+export function useDocHandles<T>(
+  ids: AutomergeUrl[],
+  { suspense = false }: UseDocHandlesParams = {}
+): DocHandleMap<T> {
+  const repo = useRepo()
+  const [handleMap, setHandleMap] = useState<DocHandleMap<T>>(() => new Map())
+
+  const pendingPromises: PromiseWrapper<DocHandle<T>>[] = []
+  const nextHandleMap = new Map<AutomergeUrl, DocHandle<T> | undefined>()
+
+  // Check if we need any new wrappers
+  for (const id of ids) {
+    let wrapper = promiseCache.get(id)!
+    if (!wrapper) {
+      try {
+        const promise = repo.find<T>(id)
+        wrapper = wrapPromise(promise)
+        promiseCache.set(id, wrapper)
+      } catch (e) {
+        continue
+      }
+    }
+
+    // Try to read each wrapper.
+    // Update handleMap with any available handles,
+    // and collect any pending promises
+    try {
+      const handle = wrapper.read() as DocHandle<T>
+      nextHandleMap.set(id, handle)
+    } catch (e) {
+      if (e instanceof Promise) {
+        pendingPromises.push(wrapper as PromiseWrapper<DocHandle<T>>)
+      } else {
+        nextHandleMap.set(id, undefined)
+      }
+    }
+  }
+
+  // If any promises are pending, suspend with Promise.all
+  if (suspense && pendingPromises.length > 0) {
+    throw Promise.all(pendingPromises.map(p => p.promise))
+  }
+
+  useEffect(() => {
+    if (pendingPromises.length > 0) {
+      void Promise.allSettled(pendingPromises.map(p => p.promise)).then(
+        handles => {
+          handles.forEach(r => {
+            if (r.status === "fulfilled") {
+              const h = r.value as DocHandle<T>
+              nextHandleMap.set(h.url, h)
+            }
+          })
+          setHandleMap(nextHandleMap)
+        }
+      )
+    } else {
+      setHandleMap(nextHandleMap)
+    }
+  }, [suspense, ids])
+
+  return handleMap
+}