Complete set of tools for synchronizing an observable key/value stores with CouchDB documents, views, and managing users or security documents. Works both in the browser and in node.js

CouchDB Emily tools synchronizes an Emily key/value observable store with a couchDB document, view or bulk of documents. It can further manipulate CouchDB User and Security documents. The exact same code will work in both the browser and in node.js, the only difference being the transport layer.

####It can manipulate CouchDB documents:

  • Get a CouchDB document and save it in a JavaScript object
  • Update the JavaScript object when the document is updated in the database
  • Upload a modified document to the database
  • Create a document
  • Remove a document
  • publishes events when a property on the JavaScript object is added/removed/updated

####It can manipulate CouchDB views:

  • Get a CouchDB view and save it in a JavaScript array
  • Update the JavaScript array when a document is added or removed from the databae
  • Update the JavaScript array when a document is updated in the database
  • publishes events when a document on the JavaScript array is added/removed/updated

####It can manupulate CouchDB bulk documents:

  • Get a CouchDB bulk of documents and save it in a JavaScript array
  • Update the JavaScript array when a document is added or removed from the databae
  • Update the JavaScript array when a document is updated in the database
  • Update the database when one of the documents is updated
  • Add or remove documents in the database when they are add or removed from the JavaScript array
  • publishes events when a document on the JavaScript array is added/removed/updated

In other words, CouchDB emily tools will reflect the status of your CouchDB in observable JavaScript data stores, and you can subscribe to their changes to update the views.

####It's a subtype of an Emily observable store:

  • It has getters/setters and update methods
  • It publishes events when a property is added/modified
  • It can be based on a JavaScript object for a key/value store
  • It can be based on a JavaScript Array for an ordered list of items
  • It can dump its current state

Synchronizing a CouchDBDocument to an existing document is as easy as:

var couchDBDocument = new CouchDBDocument();
// Transport will make the link to the node.js server that issues the request. 
couchDBDocument.sync("myDatabase", "myDocument")
.then(function () {
    // Will return the structure of the document exactly as it exists in the database 
.then(function () {
    couchDBDocument.set("myProperty", "hello");
    return couchDBDocument.upload();
.then(function () {
    // At this point, the document has been updated in CouchDB with a new property 
    couchDBDocument.toJSON(); // Will have a myProperty property 
    // and we can also remove the document from CouchDB if we want. 

##How to install it?

####In node.js

CouchDB Emily Tools is based on Emily

npm install emily couchdb-emily-tools
var emily = require("emily"),
    CouchDBTools = require("couchdb-emily-tools");
// The url to CouchDB can be configured, it's localhost by default 
CouchDBTools.configuration.hostname: "my.ip.address";
// The port can be configured too; 5984 being the default one 
CouchDBTools.configuration.port: 5984;
// Add the CouchDB handler to Emily. The handler is what issues the requests to CouchDB 
emily.handlers.set("CouchDB", CouchDBTools.handler);
// Now we can require and use the CouchDB Tools, here's an example with a document. 
var CouchDBDocument = require("tools").CouchDBDocument,
    transport = require("emily").Transport;
var cdb = new CouchDBDocument,
    transport = new Transport(emily.handlers);
cdb.sync("mydatabase", "mydocument")
.then(function () {
}, function (error) {

####On the client side

CouchDB-emily-tools requires Olives to work on the client side. Olives embeds Emily for you. It also expects you to have installed, and a store for storing sessions, like redis store, which is the only supported for now. In future implementations, redis store will probably be optional and an adapter will be accepted to any other store. An example can be found in the suggestions application

npm install olives couchdb-emily-tools

The server side has some specific configuration:

var olives = require("olives"),
    CouchDBTools = require("couchdb-emily-tools");
// sessionStore is a new redis-store: 
CouchDBTools.configuration.sessionStore = sessionStore;
// The name of the cookie sent to the client must be set too 
CouchDBTools.configuration.CookieID: "myApplication";
// Add the CouchDB handler to Olives 
olives.handlers.set("CouchDB", CouchDBTools.handler);

And on the client side:

<script src="/"></script>
<script src="emily.js"></script>
<script src="olives.js"></script>
<script src="CouchDBTools.js"></script>
var CouchDBDocument = require("tools").CouchDBDocument,
    SocketIOTransport = require("olives").SocketIOTransport;
// Create a socket 
var socket = io.connect("http://localhost"),
// Create a couchDBDocument 
cdb = new CouchDBDocument,
// And the transport that will issue the requests to CouchDB 
transport = new SocketIOTransport(socket);
cdb.sync("mydatabase", "mydocument")
.then(function () {


After you've installed CouchDB Emily tools for use either on the server or the client side, you are ready to play with it. To cope with the asynchronous nature of database operations, CouchDB Emily Tools returns a new promise for each asynchronous method call, such as 'sync', 'upload' or 'remove'.

As the tools are based on Emily, the promises are completely compliant with the Promise/A+ specs, so you know how they work. The only extra feature that is added to Promise/A+ is the ability to give an extra scope to the fulfillment/error callbacks. All the examples below are valid:

couchDBDocument.sync("database", "document")
.then(this.onSuccess, this);
// or 
.then(this.onSuccess, this.onError);
// or 
.then(this.onSuccess, this, this.onError);
// or 
.then(this.onSuccess, this, this.onError, this);
// or 
.then(this.onSuccess, this.onError, this);

Also, when a handler returns a new promise, the current promise will be resolved when the new one does. This basically allows you nicely chain operations on a couchDB tool, such as:

newDocument.sync("database", "newDocument")
.then(function () {
    // Creates the document 
    return this.upload();
}, newDocument)
.then(function () {
    // Updates the document 
    this.set("property", "hello");
    return this.upload();
}, newDocument)
.then(function () {
    // Removes the document 
}, newDocument);

##CouchDBDocument API

CouchDBDocument is designed to allow you to perform all of the operations that are possible using standard HTTP requests.

var CouchDBDocument = require("tools").CouchDBDocument,
    transport = require("emily").Transport;
var couchDBDocument = new CouchDBDocument();
// check the installation section to see how to create the transport layer 
// depending on the environment (browser or node.js) 
couchDBDocument.sync("myDatabase", "myDocument").then(...);
// this will save the following in the store's internal object: 
//{"_id":"myDocument","_rev":"50-edaa4bb883be679e9407d7c4c0da15d6","name":"couchdb emily tools"} 
couchDBDocument.get("name"); // couchdb emily tools 

You just have to add an extra JSON object that will be serialized to look like:


couchDBDocument.sync("myDatabase", "myDocument", {
    "rev": "49-2eafd494d37475e4a2ca7255f6e582f2"
couchDBDocument.sync("myDatabase", "newDocument").then(function () {
}, couchDBDocument);
couchDBDocument.sync("myDatabase", "oldDocument").then(function () {
}, couchDBDocument);
couchDBDocument.sync("myDatabase", "oldDocument").then(function () {
    // Will add or update the newField property to the document 
    this.set("newField", "myValue");
    // Will update it in CouchDB 
}, couchDBDocument);
couchDBDocument.sync("myDatabase", "oldDocument").then(funciton () {
}, couchDBDocument);
couchDBDocument.sync("myDatabase", "otherDocument").then(...);

couchDBDocuments are a subtype of Emily's Store, so they publish events. When a document is updated in CouchDB, the changes are reflected in all synchronized CouchDBDocument.

documentA.sync("myDatabase", "myDocument").then(function () {
    this.watchValue("field", function (newValue) {
        console.log(newValue); // Will log "hello!" when documentB will be uploaded! 
    }, this);
}, documentA);
documentB.sync("myDatabase", "myDocument").then(function () {
        this.set("field", "hello!");
}, documentB);

Attachements are not yet supported, but if you clap your hands enough, it will eventually come :)

##CouchDBView API

var CouchDBView = require("tools").CouchDBView,
    Transport = require("emily").Transport;
var couchDBView = new CouchDBView();
// check the installation section to see how to create the transport layer 
// depending on the environment (browser or node.js) 

A CouchDB View is readonly. Synchronizing a CouchDBView will return a list of documents that will be saved in the data store as documents in a JavaScript array. In a couchDBView, the document's properties are saved in the 'value' object.

couchDBView.sync("myDatabase", "myDesignDocument", "_view/myView").then(function () {
 // { 
 //  "id" : "documentA", 
 //  "key" : "documentA", 
 //  "value" : { 
 //     "_id" : "documentA", 
 //     "_rev" : "25-201d5eb10f46c4a85676ff44540a4f1e", 
 //     "newProperty" : "hello!" 
 //  } 
 // } 
 // The number of items in the view 

Adding parameters to the request is as easy as adding an extra object. CouchDBView will serialize it.

couchDBView.sync("myDatabase", "myDesignDocument", "_view/myView", {
    startkey: "documentA",
    endKey: "documentZ",
    limit: 10,
    skip: 10

When a new document appears in the current view, a "added" event is published"added", function onDocumentAdded(indexvalue) {
    this.get(index) === value;
}, couchDBView);

When a document is updated in CouchDB, couchDBView will publish an "updated" event"updated", function onDocumentUpdated(indexvalue) {
    this.get(index) === value;
}, couchDBView);
couchDBView.watchValue(0, function (newValueaction) {
    this.get(0) === newValue;
    action; // "updated" 

When a document is removed in CouchDB, couchDBView will publish a "deleted" event"deleted", function onDocumentDeleted(index) {
    this.get(index); // undefined 
}, couchDBView);

Unsynching is required for synchronizing the store on another view.


##CouchDBBulkDocuments API

CouchDBBulkDocuments synchronizes the data store with a bulk of documents. New documents can be added or removed to the bulk documents to alter the database. This allows for batch updates of CouchDB.

var CouchDBBulkDocuments = require("tools").CouchDBBulkDocuments,
    transport = require("emily").Transport;
var couchDBBulkDocuments = new CouchDBBulkDocuments();
// check the installation section to see how to create the transport layer 
// depending on the environment (browser or node.js) 

In a couchDBBulkDocuments, the document's properties are saved in the 'doc' object.

couchDBBulkDocuments.sync("myDatabase", {
    keys: ["document1", "document2", "document3"]
}).then(function () {
    // { 
    //  "id" : "document2", 
    //  "key" : "document2", 
    //  "value" : { 
    //      "rev" : "31-73ef4535724ff2db0a2361c1dab813e7" 
    //  }, 
    //  "doc" : { 
    //      "_id" : "document2", 
    //      "_rev" : "31-73ef4535724ff2db0a2361c1dab813e7" 
    //  } 
    // } 
    this.count(); // 3 

CouchDBBulkDocuments can also update documents in CouchDB by uploading the changes done in the data store.

// The first document now has a myProperty property with newValue 
couchDBBulkDocuments.update(0, "doc.myProperty", "newValue");
// The 4th document too 
couchDBBulkDocuments.update(3, "doc.myProperty", "newValue");
// Upload uploads all of them 

CouchDBBulkDocuments can remove one or several documents by adding them the _deleted property set to true.

couchDBBulkDocuments.loop(function (document) {
    document.doc._deleted = true;
}, this);

###3.0.0 - 16 MAR 2014

  • remove requirejs
  • now works with Emily.js and Olives.js version 2.0.0

####2.0.0 - 27 APR 2013

  • Complete refactoring of the tools. Documents, BulkDocuments and Views are in distinct files.
  • Fixed bugs in document creation/update
  • Fixed bulk docs not updating the rev id after upload
  • document.remove also returns a promise
  • When a document doesn't exist, the promise is now fulfilled instead of rejected
  • CouchDBStore doesn't exist anymore, a specific CouchDBView, CouchDBDocument or CouchDBBulkDocuments must be used instead

####1.0.6 - 27 MAR 2013

  • Aborting a non established connection doesn't fail anymore

####1.0.5 - 25 MAR 2013

  • Removed specific code imported from another application after 1.0.2
  • Updated documentation

####1.0.3 - 11 MAR 2013

  • Updated emily + requirejs

####1.0.2 - 01 JAN 2013

  • Now using Emily 1.3.1 promises wich are fully compliant with promise/A+ specs
  • Moved Emily's CouchDB handler to CouchDB Emily Tools
  • Updated tests

####1.0.1 - 08 OCT 2012

  • CouchDBStore Views are compatible with couchdb-lucene's

####1.0.0 - 07 OCT 2012

  • CouchDBStore was removed from Emily and added to CouchDB-Emily-Tools.
  • It's now a library by itself, as it concentrates more work than the rest of Emily.