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:
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
// instantiate libraryconst perge = 'my-unique-id' // connect to a peerperge // subscribe to all docset changesperge // subscribe to a single doc's changesconst unsubscribe = perge // select and change documentsperge change { docmessage = '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
readonly peer: Peer
A reference to the underlying PeerJS instance, useful for registering lifecycle handlers.
pergepeer
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 // Apply and broadcast changes on 'foo'const newDoc = // which is roughly the same as:const oldDoc = docSet || Automergeconst newDoc = Automergepergeset
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 returns an unsubscribe functionconst unsubscribeFromFoo = instance