Hypermerge
Hypermerge is a Javascript library for building p2p collaborative applications without any server infrastructure. It combines Automerge, a CRDT, with hypercore, a distributed append-only log.
Example Usage
See examples/chat/channel.js for example usage.
API
You can also view the generated API docs.
var hm = new Hypermerge([options])
Creates a new Hypermerge instance that manages a set of documents. All previously opened documents are automatically re-opened.
options
:
{
path: string, // directory where the documents should be stored
immutableApi: false, // whether to use Automerge Immutable.js documents
defaultMetadata: {} // default metadata that should be written for created documents. Can be set later with `hypermergeInstance.defaultMetadata = {}`
}
hm.joinSwarm([options])
Joins the network swarm for all documents managed by this Hypermerge instance. Must be called after 'ready'
has been emitted. options
are passed to discovery-swarm
.
var doc = hm.create([metadata])
Creates a new document (and hypercore) tracked by the hypermerge instance. If an object is passed, it will be associated with the newly created document. Some metadata properties are assigned automatically by hypermerge:
docId // An id for this document. Forking a document creates a new docId.groupId // An id for this group of documents. Forking a document keeps the groupId.
hm.open(docId)
Opens the document specified by docId
. Will download the document over the network if hm.joinSwarm()
was called. The document is opened asynchronously; listen for the 'document:ready'
event to get the document when it has finished opening.
hm.update(doc)
Records any local changes made to the document (via Automerge.change
).
var newDoc = hm.change(doc, changeFn)
Shorthand for hm.update(Automerge.change(doc, changeFn))
.
var doc = hm.fork(parentId, [metadata])
Creates a new document based on the document referenced by parentId
.
The metadata of the new document will contain a parentId
property.
var mergedDoc = hm.merge(destDocId, sourceDocId)
Merges changes from the document referenced by sourceDocId
into the document referenced by destDocId
. Returns the merged document.
The source and destination docs must have come from the same root document.
e.g. The source doc was a .fork()
of the destination doc, or visa-versa.
hm.find(docId)
Returns the document for the given docId. Throws if the document has not been opened yet.
hm.getId(doc)
Returns the docId
for the given doc
.
hm.metadatas(docId)
Returns the list of metadata objects corresponding to the list of actors that have edited this document.
hm.has(docId)
Returns true
if docId
has been opened.
hm.any([function])
Returns true
if any docs satisfy the given function. If a function is not passed, returns true if any docs exist.
hm.isMissingDeps(docId)
Returns true
if the document specified by docId
is missing changes from other actors. They may still be downloading from the network.
Events
hm.on('ready', hm)
Emitted when all document metadata has been loaded from storage, and the hypermerge instance is ready for use. Documents will continue loading from storage and the network. Required before .create()
, .open()
, etc. can be used.
hm.on('document:ready', docId, doc)
Emitted when a document has been fully loaded.
hm.on('document:updated', docId, doc, prevDoc)
Emitted when a document has been updated via changes received over the network. Not emitted after local calls to .update()
or .change()
.
hm.on('peer:joined', actorId, peer)
Emitted when a network peer has connected.
hm.on('peer:left', actorId, peer)
Emitted when a network peer has disconnected.