Home

Awesome

PouchDB LiveFind

Build Status

Live PouchDB queries that update automatically as changes come in!

Why

The biggest problem with traditional database queries is that they don't update themselves as the data changes. This is no problem for server-side rendering where the user needs to refresh the browser for updates. But modern web app users demand that the data on the screen is up-to-date all the time!

Keeping the U.I. up-to-date with changing data is a huge challenge for developers. Using PouchDB, the most common method is to build application state from the changes feed. But this becomes slow and impractical with large data sets.

LiveFind allows you to effortlessly keep your U.I. synchronized with a subset of your data in an efficient way. It is designed to perfectly complement flux and redux type architectures.

How It Works

PouchDB LiveFind uses pouchdb-find to provide initial query results, and then checks every change after that to see if it matches your selector. You are informed every time a change adds, updates, or removes an item from your query.

LiveFind can optionally "keep state" and maintain an aggregate list of all the docs that match your query, which is passed with each update. Each change is immutable (generates a new object) so this plays really nicely with frameworks like React and Angular.

Setup

Dependencies

LiveFind requires pouchdb. In addition pouchdb-find must be loaded as a plugin.

In the browser

To use this plugin in the browser, include it after pouchdb.js and pouchdb.find.js in your HTML page:

<script src="pouchdb.js"></script>
<script src="pouchdb.find.js"></script>
<script src="pouchdb.live-find.js"></script>

You can download the necessary packages from Bower:

bower install pouchdb pouchdb-find pouchdb-live-find

In Node.js/Browserify

Or to use it in Node.js, just npm install the packages:

npm install pouchdb pouchdb-find pouchdb-live-find

And then attach it to the PouchDB object:

var PouchDB = require('pouchdb');
PouchDB.plugin(require('pouchdb-find'));
PouchDB.plugin(require('pouchdb-live-find'));

Basic Usage

var db = new PouchDB('live-find');

// This assumes you have created your find index and seeded your initial documents. 

// Start our live query
var liveFeed = db.liveFind({
  selector: {series: 'Mario'},
  sort: [{series: 'desc'}, {name: 'desc'}],
  aggregate: true
})
  
  // Called every time there is an update to the query
  .on('update', function(update, aggregate) {
    // update.action is 'ADD', 'UPDATE', or 'REMOVE'
    // update also contains id, rev, and doc
    console.log(update.action, update.id);
    // aggregate is an array of docs containing the latest state of the query
    refreshUI(aggregate);
    // (refreshUI would be a function you write to pipe the changes to your rendering engine)
  })
  
  // Called when the initial query is complete
  .on('ready', function() {
    console.log('Initial query complete.');
  })
  
  // Called when you invoke `liveFeed.cancel()`
  .on('cancelled', function() {
    console.log('LiveFind cancelled.');
  })
  
  // Called if there is any error
  .on('error', function(err) {
    console.error('Oh no!', err);
  });

For more information see examples/tutorial.js.

API

LiveFind uses the exact same API as pouchdb-find with the addition of the aggregate option. Also LiveFind has none of the sort restrictions of PouchDB Find. You can sort by any list of fields, and even with mixed sort directions. (Just make sure the fields options doesn't remove fields needed to sort.) For details, see the pouchdb-find documentation as well as Cloudant Query.

db.liveFind(request)

request is an object which contains:

Returns: liveFeed object, which contains the following methods:

Events

liveFeed is also an event emitter and fires the following events:

The update object contains the following properties:

aggregate is an array of docs representing the current state of everything that matches your query. This will only be present if you specified aggregate: true in the request options. It will also apply the sort, skip and limit options before giving you the data.

Performance Tips

If you are using aggregate to update your application U.I., you will most likely want to implement some type of debouncing. Every single change generates an update event, so you will want to wait until they stop coming to refresh the screen. Any delay less than 50ms will likely not be perceived by the user.

var debounce = require('lodash.debounce');
var debouncedRefresh = debounce(refreshUI, 50);

liveFeed.on('update', function(update, aggregate) {
  debouncedRefresh(aggregate);
});

Optimizing Your Build

pouchdb-find and pouchdb-live-find share several dependencies. You can likely reduce your build size if you build them together using a tool like Browserify or Webpack.

Release History