manymerge

ManyMerge

ManyMerge is a protocol for synchronizing Automerge documents. It's a replacement for Automerge.Connection that supports many-to-many and one-to-many relationships.

ManyMerge is network-opinionated, but lets you implement it yourself. It assumes you have the concept of "broadcasting", where everyone who has access to the document can be alerted of a message. It also assumes that you're keeping a unique id for each connection on your network (called the peerId).

Install

npm install --save manymerge

Usage

Manymerge comes with two different types of connections that work together: Peers and Hubs.

Peers

A Peer is a 1-1 relationship that can talk to a Hub or another Peer. Your peer will need to create a sendMsg function that takes a ManyMerge Message and sends it to the network. Typically that looks like this:

import { Peer } from "manymerge";

function sendMsg(msg) {
  MyNetwork.emit("to-server", msg);
}

const peer = new Peer(sendMsg);

When a peer wants to alert it's counterpart that it changed a document, it should call the notify function:

import Automerge from "automerge";

let myDoc = Automerge.from({ title: "cool doc" });
peer.notify(myDoc);

When a peer gets a message from the network, it should run applyMessage, which will return a new document with any changes applied.

let myDoc = Automerge.from({ title: "cool doc" });

MyNetwork.on("from-server", msg => {
  myDoc = peer.applyMessage(msg, myDoc);
});

Hubs

Hubs are a many-to-many (or 1-to-many) relationship that can talk to many Peers or other Hubs. Unlike Peers, Hubs need the ability to "broadcast" a message to everyone on the network (or at least as many people as possible).To save time, Hubs will also cache Peer's they've seen recently and directly communicate directly with them.

To set this up, create broadcastMsg and sendMsgTo functions:

import { Hub } from "manymerge";

function sendMsgTo(peerId, msg) {
  MyNetwork.to(peerId).emit("msg", msg);
}

function broadcastMsg(msg) {
  MyNetwork.on("some-channel").emit("msg", msg);
}

const hub = new Hub(sendMsgTo, broadcastMsg);

Then, hub works like a peer, it can notify others of documents:

// Tell folks about our doc
hub.notify(myDoc);

Unlike the peer, when it gets a message, it'll need to know the unique id of the connection sending it. It will use this later in the sendMsgTo function.

MyNetwork.on("msg", (from, msg) => {
  myDoc = hub.applyMessage(from, msg, myDoc);
});