perge
v1.2.1
Published
Perge is a minimal p2p synchronization system for [Automerge](https://github.com/automerge/automerge) documents using [PeerJS](https://github.com/peers/peerjs).
Downloads
35
Readme
Perge
Perge is a minimal p2p synchronization system for Automerge documents using PeerJS.
- Perge
- Installation
- Quick Start
- API
Perge
constructor (actorId: string, config: PergeConfig = {})
readonly docSet: Automerge.DocSet<any>;
readonly peer: Peer
connect(id: string, conn?: Peer.DataConnection, options?: Peer.PeerConnectOption): Peer.DataConnection
get<T>(id: string): Doc<T>
select<T>(id: string): (fn: Function, ...args: any[]) => Automerge.Doc<T>
subscribe<T>(idOrSetHandler: string | Automerge.DocSetHandler<T>, callback?: Automerge.ChangeFn<T>): () => void
Installation
Perge
has the following dependencies:
{
"automerge": "^0.14.1",
"peerjs": "^1.2.0"
}
Install Perge
via npm:
npm install perge
or via yarn:
yarn add perge
Quick Start
For a more complete example, see the example page.
You can run the example with yarn dev:example
which uses Parcel
import { change } from 'automerge'
import Perge from 'perge'
// instantiate library
const perge = new Perge('my-unique-id')
// connect to a peer
perge.connect('someone-elses-unique-id')
// subscribe to all docset changes
perge.subscribe((docId, doc) => {
// logs 'some-document-id', { message: 'Hey!' }
console.log(docId, doc)
})
// subscribe to a single doc's changes
const unsubscribe = perge.subscribe('some-document-id', doc => {
// { message: 'Hey!' }
console.log(doc)
// unsubscribe this callback
unsubscribe()
})
// select and change documents
perge.select('some-document-id')(
change,
doc => {
doc.message = 'Hey!'
}
)
API
Perge
Perge
is a class containing references to Automerge.Connections
, and encodes and decodes passed messages using PeerJS
and the Automerge.Connection
protocol.
constructor (actorId: string, config: PergeConfig = {})
| actorId
| string
| Required. A unique ID used to initialize the PeerJS connection. Automerge should also be initialized with with this value.
You can further configure Perge
with the following config shape. All properties are optional.
| Key | Type | Description |
| -------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| decode
| (msg: string) => any
| A function called on a WebRTC string message before it is passed to an Automerge.Connection
with receiveMsg
, defaults to JSON.parse
|
| encode
| (msg: any) => string
| A function called on Automerge.DocSet
change objects before it is sent to a peer, defaults to JSON.stringify
|
| peer
| PeerJS.Peer
| A preconfigured PeerJS.Peer
instance. |
| docSet
| Automerge.DocSet<T>
| An instantiated Automerge.DocSet
to sync between clients. |
readonly docSet: Automerge.DocSet<any>;
A reference to the synchronized Automerge.DocSet
, handy to subscribe to state changes with if you don't want to use Perge.subscribe
:
docSet.registerHandler((docId, doc) => {
// REACT TO STATE UPDATES
})
readonly peer: Peer
A reference to the underlying PeerJS instance, useful for registering lifecycle handlers.
perge.peer.on('error', (err) => {
// handle
})
connect(id: string, conn?: Peer.DataConnection, options?: Peer.PeerConnectOption): Peer.DataConnection
Connects to a PeerJS
peer with the given ID and sends outgoing Automerge.DocSet
syncronization messages using the Automerge.Connection
protocol.
Returns the DataConnection so you can register your own lifecycle callbacks.
Optionally, you can pass an existing PeerJS
connection.
If you don't pass an existing PeerJS
connection, it will connect using the given options, if any.
get<T>(id: string): Doc<T>
Gets an existing doc with given ID, or initializes a new doc with the client's actor ID.
select<T>(id: string): (fn: Function, ...args: any[]) => Automerge.Doc<T>
Returns a function that applies a given Automerge
document change method, then sets the returned document on the internal DocSet
to broadcast changes to connected peers, for example:
// Selects the document with the ID 'foo'
const exec = perge.select('foo')
// Apply and broadcast changes on 'foo'
const newDoc = exec(
Automerge.change, // apply changes
'increase counter', // commit message
doc => { // mutate proxy document and apply changes
if(!doc.counter) doc.counter = new Automerge.Counter()
else doc.counter.increment()
}
)
// which is roughly the same as:
const oldDoc = docSet.getDoc('foo') || Automerge.init(actorId)
const newDoc = Automerge.change(oldDoc, 'increase counter', doc => {
if(!doc.counter) doc.counter = new Automerge.Counter()
else doc.counter.increment()
})
perge.set.setDoc(id, newDoc)
subscribe<T>(idOrSetHandler: string | Automerge.DocSetHandler<T>, callback?: Automerge.ChangeFn<T>): () => void
Subscribe to doc updates for either the entire docSet or a specific document ID. Returns a function that, when called, unsubscribes.
const unsubscribeFromAll = instance.subscribe((id, doc) => {
// do something with the updated doc
})
// subscribe returns an unsubscribe function
const unsubscribeFromFoo = instance.subscribe('foo', (doc) => {
console.log('foo', doc)
if (doc.counter.value === 10) {
unsubscribeFromFoo()
console.log('unsubscribed from foo!')
}
})