Static
prefixedOur documentId in Automerge URL form.
Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional
context: anySends 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.
All changes to an Automerge document should be made through this method. Inside the callback, the document should be treated as mutable: all edits will be recorded using a Proxy and translated into operations as part of a single recorded "change".
Note that assignment via ES6 spread operators will result in replacing the object
instead of mutating it which will prevent clean merges. This may be what you want, but
doc.foo = { ...doc.foo, bar: "baz" }
is not equivalent to doc.foo.bar = "baz"
.
Local changes will be stored (by the StorageSubsystem) and synchronized (by the DocSynchronizer) to any peers you are sharing it with.
states to wait for, such as "LOADING". mostly for internal use.
the current state of this handle's Automerge document.
This is the recommended way to access a handle's document. Note that this waits for the handle to be ready if necessary. If loading (or synchronization) fails, this will never resolve.
Synchronously returns the current state of the Automerge document this handle manages, or
undefined. Consider using await handle.doc()
instead. Check isReady()
, or use whenReady()
if you want to make sure loading is complete first.
Not to be confused 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.
the current document, or undefined if the document is not ready.
Calls each of the listeners registered for a given event.
Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Return an array listing the events for which the emitter has registered listeners.
true if the handle is in one of the given states.
Return the number of listeners listening to a given event.
Return the listeners registered for a given event.
Optional
fn: ((...args) => void)Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional
context: anyOptional
once: booleanAdd a listener for a given event.
Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional
context: anyAdd a one-time listener for a given event.
Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional
context: anyRemove the listeners of a given event.
Optional
fn: ((...args) => void)Rest
...args: ArgumentMap<DocHandleEvents<T>>[Extract<T, keyof DocHandleEvents<T>>]Optional
context: anyOptional
once: booleana promise that resolves when the document is in one of the given states (if no states are passed, when the document is ready)
Use this to block until the document handle has finished loading. The async equivalent to
checking inState()
.
A 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. You shouldn't ever instantiate this yourself. To obtainDocHandle
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 theRepo
will save any new changes to the attached StorageAdapter and send sync messages to connected peers.