DocHandle is a wrapper around a single Automerge document that lets us listen for changes and notify the network and storage of new changes.

Remarks

A DocHandle represents a document which is being managed by a Repo. To obtain DocHandle use Repo.find or Repo.create.

To modify the underlying document use either DocHandle.change or DocHandle.changeAt. These methods will notify the Repo that some change has occured and the Repo will save any new changes to the attached StorageAdapter and send sync messages to connected peers.

Type Parameters

  • T

Hierarchy

Properties

documentId: DocumentId
prefixed: string | boolean

Accessors

Methods

  • Type Parameters

    Parameters

    • event: T
    • fn: ((...args) => void)
    • Optional context: any

    Returns this

  • broadcast sends an arbitrary ephemeral message out to all reachable peers who would receive sync messages from you it has no guarantee of delivery, and is not persisted to the underlying automerge doc in any way. messages will have a sending PeerId but this is not a useful user identifier. a user could have multiple tabs open and would appear as multiple PeerIds. every message source must have a unique PeerId.

    Parameters

    • message: unknown

    Returns void

  • Make a change as if the document were at heads

    Parameters

    • heads: Heads
    • callback: ChangeFn<T>
    • options: ChangeOptions<T> = {}

    Returns undefined | string[]

    A set of heads representing the concurrent change that was made.

  • Returns the current state of the Automerge document this handle manages. Note that this waits for the handle to be ready if necessary, and currently, if loading (or synchronization) fails, will never resolve.

    Parameters

    Returns Promise<undefined | Doc<T>>

  • Returns the current state of the Automerge document this handle manages, or undefined. Useful in a synchronous context. Consider using await handle.doc() instead, check isReady(), or use whenReady() if you want to make sure loading is complete first.

    Do not confuse this with the SyncState of the document, which describes the state of the synchronization process.

    Note that undefined is not a valid Automerge document so the return from this function is unambigous.

    Returns undefined | Doc<T>

    the current document, or undefined if the document is not ready

  • Calls each of the listeners registered for a given event.

    Type Parameters

    Parameters

    Returns boolean

  • Return an array listing the events for which the emitter has registered listeners.

    Returns (keyof DocHandleEvents<T>)[]

  • Checks if this document has been marked as deleted. Deleted documents are removed from local storage and the sync process. It's not currently possible at runtime to undelete a document.

    Returns boolean

    true if the document has been marked as deleted

  • Checks if the document is ready for accessing or changes. Note that for documents already stored locally this occurs before synchronization with any peers. We do not currently have an equivalent whenSynced().

    Returns boolean

  • Return the number of listeners listening to a given event.

    Parameters

    Returns number

  • Return the listeners registered for a given event.

    Type Parameters

    Parameters

    • event: T

    Returns ((...args) => void)[]

  • Merge another document into this document

    Parameters

    • otherHandle: DocHandle<T>

      the handle of the document to merge into this one

    Returns void

    Remarks

    This is a convenience method for handle.change(doc => A.merge(doc, otherHandle.docSync())). Any peers whom we are sharing changes with will be notified of the changes resulting from the merge.

    Throws

    if either document is not ready or if otherHandle is unavailable (otherHandle.docSync() === undefined)

  • Type Parameters

    Parameters

    • event: T
    • Optional fn: ((...args) => void)
    • Optional context: any
    • Optional once: boolean

    Returns this

  • Add a listener for a given event.

    Type Parameters

    Parameters

    • event: T
    • fn: ((...args) => void)
    • Optional context: any

    Returns this

  • Add a one-time listener for a given event.

    Type Parameters

    Parameters

    • event: T
    • fn: ((...args) => void)
    • Optional context: any

    Returns this

  • Remove all listeners, or those of the specified event.

    Parameters

    • Optional event: keyof DocHandleEvents<T>

    Returns this

  • Remove the listeners of a given event.

    Type Parameters

    Parameters

    • event: T
    • Optional fn: ((...args) => void)
    • Optional context: any
    • Optional once: boolean

    Returns this

  • Use this to block until the document handle has finished loading. The async equivalent to checking inState().

    Parameters

    Returns Promise<void>

Generated using TypeDoc