pouch-clerk
PouchDB worker reacting to document changes.
Each document has a state. A clerk listens to changes in one or more PouchDB databases and react to document state changes.
When reacting to a document state change, the clerk can:
- change the document
- say what the next state is going to be
Install
$ npm install pouch-clerk --save
Use
Require package and create clerk:
var Clerk = ; var transitions = // document defining state transition handlers; var options = initialState: 'start' // defaults to `start` finalState: 'finished' // defaults to `finish` reconnectMaxTimeoutMS: 3000 // defaults to 3000 ms transitions: transitions; var clerk = ;
Options
initialState
(string): the state to give new documents with no state yetfinalState
(string or string array): the end state (or states, if you pass an array)reconnectMaxTimeoutMS
(number): the maximum number of miliseconds to wait before trying to (re)connecttransitions
(object): the state transition handlers. Object where the keys are the state names and the values are functions.asyncUpdaters
: an array of functions that start and stop async updaters. See Async Updaters section.
The state transition handlers
The options.transitions
should contain an object with a key for each state.
The value for each state should be a handler function, like this:
var transitions = { // ... }
Example:
var transitions = { ; } { // ... }
Reentering the same state
You can force reentry on the same state (watch out for infinite loops), by passing a true
as third argument to the next
callback:
var transitions = { ; }
Adding and removing databases
A clerk can react to one or more databases. During runtime you just add or remove a database:
var PouchDB = ;var db = 'somedatabase'; clerk;
clerk;
Name databases
You can also remove by database name:
clerk;clerk;
You can also find out if a named database exists:
if !clerk clerk;
Async updaters
You can push async updates into documents like this:
var asyncUpdater = { this_interval = ; } { ; } var options = asyncUpdaters: asyncUpdater ; var clerk = ;
(Each document creates an async updater instance, which you can reference by this
inside the start
or stop
methods).
Async updater API
The Async Updater start
method gets a doc
instance for each document that is being handled. Using this document you can:
get the ID of the document
{ console;}
get the latest document version:
{ doc}
update the document:
{ doc;}
merge some attributes into the latest version of the document:
{ doc;}
Error handling
The error handling strategy depends on the type of error happening.
User-land errors
If an error occurs while you're processing a state transition, you should call the next
callback with that error as the first argument:
var transitions = { ; };
This will make the document transition into the error
state.
You should define an error state handler (if you don't that error will be handled as an internal error — see the next section about internal errors).
var transitions = { // you can recover from error: ; }
Internal errors
Internal errors can occurr when saving document changes. You can listen for those errors on the clerk object:
clerk;
(if you don't, an uncaught exception will be thrown);
Stop clerk
clerk;
License
ISC