automerge-react-suspense-hooks

A set of React hooks for working with Automerge documents using React's Suspense-based APIs.

Note that Automerge includes a first-party React hooks integration; you may want to use that instead.

The official hooks do not integrate with Suspense, but see this pull request.

Installing

pnpm add automerge-react-suspense-hooks

Usage

All hooks must be used in children of the WithRepo context component:

1import { Repo } from "@automerge/automerge-repo";
2import { WithRepo } from "automerge-react-suspense-hooks";
3
4export function AutomergeApp({ repo }: { repo: Repo }) {
5  return (
6    <WithRepo repo={repo}>
7      <DocumentView>
8    </WithRepo>
9  )
10}

Note that this component also acts as a Suspense boundary (though you may add other Suspense boundaries nested under it).

useDocument

To get the state of a single document, use useDocument:

1/**
2 * Retrieves the current state of the document (and causes a re-render whenever
3 * the document changes). Suspends until the document is loaded.
4 *
5 * @param id the document to load
6 * @throws @type DocumentDeletedException if the document is deleted
7 * @throws @type DocumentUnavailableException if the document is unavailable
8 * @returns the loaded document
9 */
10function useDocument<Document>(id: AnyDocumentId): Doc<Document>;

useDocumentSelection

To derive a state from several documents, or for watching a subset of a single document, use useDocumentSelection:

1/**
2 * Reduce the given set of documents to a single Selection. Watches the
3 * specified documents for changes, but will only cause a re-render if
4 * the changes effect a change in the Selection.
5 *
6 * @param ids list of documents to monitor
7 * @param opts options (see @type UseDocumentsOpts)
8 * @returns the derived Selection
9 */
10function useDocumentSelection<Document, Selection>(
11  ids: AnyDocumentId[],
12  opts?: UseDocumentsOpts<Document, Selection>,
13): Selection;

The options are as follows:

1/**
2 * Options to useDocuments hook.
3 */
4type UseDocumentsOpts<Document, Selection = Document> = {
5  /**
6   * Selector to use (see below).
7   */
8  selector?: Selector<Document, Selection>;
9  /**
10   * Equality function to use with Selections, in order to determine whether to
11   * re-render based on the new Selection.
12   */
13  equal?: EqualFn<Selection>;
14};

Selectors transform a list of documents to a Selection:

1/**
2 * Reduce a list of documents to a selection.
3 */
4type Selector<Document, Selection> = (
5  items: DocHandle<Document>[],
6) => Selection;

The default selector returns a map of Automerge URL to current document state. The default equal implementation is a built-in deepEqual function.

useCreateDocument

1/**
2 * Returns a function that can be used to create documents in the current repo.
3 *
4 * @returns function that accepts an initial value and returns the new document's url
5 */
6function useCreateDocument<Document>();

useUpdateDocument

1/**
2 * Returns a function to update the given document. The function will be passed
3 * the document's current state to mutate.
4 *
5 * @param id of document to update
6 * @returns function to update the document
7 */
8export function useUpdateDocument<Document>(id: AnyDocumentId);