A promise-based wrapper around CouchDB. CouchPromised does not aim to be a full- featured CouchDB client and instead aims to provide a minimal set of methods for some of the most common interactions.
The package is available through npm and can be installed as usual:
npm install --save couch-promised
Once installed you can import the package into your script as usual:
var CouchPromised = require('couch-promised');
The CouchPromised
variable above refers to a constructor function. You must
create instance before you can interact with a database:
var couch = new CouchPromised({
host: 'example.com', // Your CouchDB server. Defaults to 127.0.0.1.
port: 5984, // Port of CouchDB server. Defaults to 5984.
path: '/my-database', // Path to a database stored on the CouchDB instance.
});
As mentioned previously, CouchPromised does not attempt to cover all possible
CouchDB functionality. At its heart is the request
method, to which all other
methods delegate. If you need more fine-grained control over a request you may
find that method useful.
Find an individual document by unique identifier:
couch.get('my-doc-id').then(function ( doc ) {
// 'doc' will be an object corresponding to the latest revision of the stored
// document.
});
Find many documents by unique identifiers. Takes an array or alternatively any number of separate parameters:
couch.fetch('my-doc-id-1', 'my-doc-id-2').then(function ( docs ) {
// 'docs' will be an array of objects corresponding the the latest revisions
// of the stored documents.
});
Create a new document. If the provided object has an _id
property that does
not already exist in the database the new document will be created with that
identifier. If a document already exists and the provided object doesn't have
a valid _ref
property an error will be thrown. The update
method is better
suited to that situation.
couch.insert({ something: 1, another: 'x' }).then(function ( res ) {
// 'res' will be an object with '_id' and '_rev' properties corresponding to
// the newly stored document.
});
Update an existing document. The provided object must have an _id
property
that corresponds to a stored document and a _rev
property that matches the
latest revision of that stored document.
couch.update({ _id: 'my-doc-id', _rev: 1 }).then(function ( res ) {
// 'res' will be an object with '_id' and '_rev' properties corresponding to
// the updated document.
});
Delete an existing document. The provided object must have an _id
property
that corresponds to a stored document and a _rev
property that matches the
latest revision of that stored document.
couch.destroy({ _id: 'my-doc-id', _rev: 1 }).then(function ( res ) {
// 'res' will be an object with '_id' and '_rev' properties corresponding to
// the deleted document.
});
Query a database view. Requires the name of a design document and the name of a view within that document. Optionally also takes a map of view parameters to their values. The parameters object can contain any of the parameters a CouchDB view normally accepts. It is converted to a querystring and appended to the request URL.
couch.view('a-design', 'a-view', { key: 'some-key' }).then(function ( rows ) {
// 'rows' will be an array of rows returned by the view. Note that the rows
// are not documents themselves but may have a 'doc' property if e.g. the
// 'include_docs' parameter was included.
});
Query a database view and return the document associated with each result. This
is effectively sugar around a call to view
with the include_docs
parameter
set.
couch.viewDocs('a-design', 'a-view').then(function ( docs ) {
// 'docs' will be an array of documents associated with the rows returned by
// the view.
});
Perform a bulk insert or update of documents. Requires an array of documents.
Any element of that array with an _id
property that corresponds to a document
already stored in the database must also have the correct _rev
property.
couch.bulk([ { x: 1 }, { y: 2 } ]).then(function ( res ) {
// 'res' will be an array of objects with '_id' and '_rev' properties
// corresponding to the inserted or updated document.
});
Send an HTTP request to the CouchDB database. Requires an HTTP method and a URL path. Optionally also takes an object representing the request body.
couch.request('GET', '/my-doc-id').then(function ( res ) {
// 'res' will be an object representing the raw HTTP response from CouchDB.
// The other CouchPromised methods take that response and resolve with the
// relevant data from within it.
});