Skip to content
PouchDB live sync through websockets
JavaScript
Branch: master
Clone or download
Pull request Compare This branch is even with yldio:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
test
.eslintignore
.eslintrc
.gitignore
.istanbul.yml
.travis.yml
README.md
browser.js
client.js
index.js
package.json
server.js

README.md

pouch-websocket-sync

By Build Status

Sync several PouchDBs through websockets.

Supports reconnection, negotiation and authentication.

Demo

See here an example todo application using React and Redux.

Demo video

Install

$ npm install pouch-websocket-sync --save

Server

var PouchSync = require('pouch-websocket-sync');
var http = require('http');
var httpServer = http.createServer();
var server = PouchSync.createServer(httpServer, onRequest);
httpServer.listen(3000);

function onRequest(credentials, dbName, cb) {
  if (credentials.token == 'some token') {
    cb(null, new PouchDB(dbName));
  } else {
    cb(new Error('not allowed'));
  }
};

Client

var websocket = require('websocket-stream');
var PouchSync = require('pouch-websocket-sync');

var db = new PouchDB('todos');
var client = PouchSync.createClient();
var sync = client.sync(db, {
  remoteName: 'todos-server', // name remote db is known for
  credentials: { token: 'some token'} // arbitrary
});

client.connect('ws://somehost:someport');

API

PouchWebsocketSync.createServer(httpServer, onRequest)

Creates and returns a websocket server.

Arguments:

  • httpServer: an HTTP server to bind to
  • onRequest: a function to be called when a client requests access to a database. This function must have the following signature:
function onRequest(credentials, dbName, callback)

The arguments to expect on this function are:

  • credentials: arbitrary, whatever the client sends as credentials. Defaults to undefined.
  • dbName: the name of the database to sync into as being requested by the client.
  • callback: the callback to call once the request is to be granted or denied. If there is a problem with the requests (invalid credentials or other error), you should pass an error as first arguments. If, otherwise, the request for a database is to proceed, you should pass null or undefined as the first argument and a PouchDB database as the second.

Example of an onRequest function:

function onRequest(credentials, dbName, cb) {
  if (credentials.token == 'some token') {
    cb(null, new PouchDB(dbName));
  } else {
    cb(new Error('not allowed'));
  }
};

PouchWebsocketSync.createClient()

Creates and returns a webocket sync client.

client.connect(address)

Connect to a given websocket address.

  • address a websocket address, like wss://somehost:3000

client.sync(database, options)

Start syncing the given database. Arguments:

  • database: an instance of a PouchDB database
  • options: an object containing the follow keys and values:
    • remoteName: remote database name. Defaults to the database name.
    • PouchDB: PouchDB constructor. Defaults to database.constructor.

Returns a sync object.

client events

client.emit('connect') // when connects
client.emit('disconnect') // when gets disconnected
client.emit('reconnect') // when starts attempting to reconnect

Sync

sync.cancel()

Cancel this sync.

client.end() or client.destroy()

sync events

sync.emit('change', change)
sync.emit('paused')
sync.emit('active')
sync.emit('denied')
sync.emit('complete')
sync.emit('error', err)

License

ISC

You can’t perform that action at this time.