pouchdb-live-find
v0.4.0
Published
Live PouchDB queries that update automatically as changes come in!
Downloads
152
Maintainers
Readme
PouchDB LiveFind
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:
selector
(object
) thepouchdb-find
selector to filter your resultsfields
(array
, optional) a list of fields you want to receive. (Don't leave out the fields needed to sort your list.)aggregate
(boolean
, optional) iftrue
outputs an aggregate list on everyupdate
eventsort
(array
, optional) defines the sort order (aggregate list only)limit
(number
, optional) maximum number of docs to return (aggregate list only)skip
(number
, optional) the number of docs to skip (aggregate list only)
Returns: liveFeed
object, which contains the following methods:
liveFeed.cancel()
stops the query and removes all listenersliveFeed.then(...)
hooks into thepouchdb-find
promise and resolves when the initial query is completeliveFeed.catch(...)
hooks into thepouchdb-find
promise and catches any errors with the initial queryliveFeed.sort(list)
a convenience function to sort any list in place by thesort
order you provided. (This will mutate the Array.)liveFeed.paginate(options)
updates the pagination and sorting of the aggregate list and immediately returns the updated list. Available options aresort
,skip
, andlimit
.
Events
liveFeed
is also an event emitter and fires the following events:
update
: (update
,aggregate
) fired every time there are changes in your query results (explained below)ready
: fired after the initial query is completecancelled
: fired when you cancel the query usingliveFeed.cancel()
error
: (err
) fired in case of any error that occurs while listening to changes
The update
object contains the following properties:
action
: (string
) one of'ADD'
,'UPDATE'
, or'REMOVE'
.id
,rev
, anddoc
: these are the standard properties from the CouchDB changes feed. The fields insidedoc
will be filtered if you specified thefields
option in your request.
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
- 0.4.0 (2017-01-13) - Fixed breaking changes caused by
pouchdb-find
integration into mono-repo - 0.3.0 (2017-01-13) - Upgraded dependencies to support
pouchdb-find v0.10.x
andpouchdb v.6.x.x
- 0.2.0 (2016-05-25) - Added pagination and the ability to sort by any list of fields with mixed directions
- 0.1.0 (2016-05-19) - Initial Release