CouchDB library with a simple, functional-programing-friendly API, returning promises
CouchDB library with a simple, functional-programing-friendly API.
Forked from Cot, and renamed blue-cot in reference to the Bluebird promises it was returning until v4.0.0 (it returns native promises since).
npm install blue-cot
Especially compared to Cot from which it is forked
blue-cot is this-free: no need to bind functions contexts!4xx and 5xx responses will return rejected promises (should be handled with .catch)const bluecot = require('blue-cot')
const config = {
// Required
protocol: 'http',
hostname: 'localhost',
port: 5984,
// Required if the database you are querying requires authentification
username: 'your-couchdb-username',
password: 'your-couchdb-password',
// Optinonal
// Logs the generated URLs, body, and response time
debug: true, // default: false
// The default http agent already sets keepAlive=true
// but if for some reason you want to pass your own http agent, you can.
// Some documentation on the subject of http agents
// https://nodejs.org/api/http.html#http_class_http_agent
// https://github.com/bitinn/node-fetch#custom-agent
// And the recommandations of the official CouchDB NodeJS lib
// https://github.com/apache/couchdb-nano#pool-size-and-open-sockets
agent: myAgent
}
const getDbApi = bluecot(config)
const db = getDbApi('some-db-name')
From v4.0.0, blue-cot stopped returning Bluebird promises, but if you miss that feature, you can recover it by initializing bluebird before blue-cot:
global.Promise = require('bluebird')
const bluecot = require('blue-cot')
const getDbApi = bluecot(config)
const db = getDbApi('some-db-name')
To handle database and design documents creation, see couch-init2
GET /<dbName>
const data = await db.info()
GET /<dbName>/<docId>
Takes a document id and optionaly a rev id to get a specific version:
const latestDocVersion = await db.get('doc-1')
const specificVersion = await db.get('doc-1', '2-b8476e8877ff5707de9e62e70a8e0aeb')
Missing documents are treated as an error, and thus return a rejected promise.
POST /<dbName>
const res = await db.post(doc)
Creates a new document or updates an existing document. If doc._id is undefined, CouchDB will generate a new ID for you.
On 201, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}
All other status codes (including 409, conflict) are treated as errors, and thus return a rejected promise.
PUT /<dbName>/<doc._id>
const res = await db.put(doc)
On 409 (conflict) returns result from CouchDB which looks like: {"error":"conflict"}
On 201, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}
All other status codes are treated as errors, and thus return a rejected promise.
DELETE /<dbName>/<docId>?rev=<rev>
const res = await db.delete(docId, rev)
On 200, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>", "rev":"<docRev>"}
All other status codes are treated as errors, and thus return a rejected promise.
If you wish to gracefully handle update conflicts while deleting, use db.put() on a document with _deleted set to true:
doc._deleted = true
const res = await db.put(doc)
if (!res.ok) {
// something went wrong, possibly a conflict
}
POST /<dbName>/_find_ (endpoint available in CouchDB >= 2.0)
Takes a _find query object
const { docs, bookmark } = await db.find({
selector: {
year: { $gt: 2010 }
},
fields: [ '_id', '_rev', 'year', 'title' ],
sort: [ { year: 'asc' } ],
limit: 2,
skip: 0,
use_index: [ 'some_design_doc_name', 'some_index_name' ],
execution_stats: true
})
By default, this function will throw if receiving a warning; this behavior can be disable by passing strict=false:
const query = {
selector: {
year: { $gt: 2010 }
}
}
const { docs, bookmark, warning } = await db.find(query, { strict: false })
To send the same query to the _explain endpoint instead, use the explain flag:
const query = {
selector: { name: 'foo' }
}
const { docs, bookmark, warning } = await db.find(query, { explain: true )
POST /<dbName>/_index
const { result } = await db.postIndex({
index: {
fields: [ 'type' ]
},
ddoc: 'some_ddoc_name',
name: 'by_type'
})
GET /<dbName>/<docId>
const res = await db.exists(docId)
Returns a promise resolving to true if it exist, or a rejected promise if it doesn't.
POST /<dbName>?batch=ok
const res = await db.batch(doc)
doc: Batch Mode
Creates or updates a document but doesn't wait for success. Conflicts will not be detected.
On 202, returns result from CouchDB which looks like: {"ok":true, "id":"<docId>"}
The rev isn't returned because CouchDB returns before checking for conflicts. If there is a conflict, the update will be silently lost.
All other status codes are treated as errors, and thus return a rejected promise.
const res = await db.update(docId, updateFunction)
Gets the specified document, passes it to updateFunction, and then saves the results of updateFunction over the document
The process loops if there is an update conflict.
By default, db.update only accepts to update existing docs, but this can be changed by setting createIfMissing=true:
const res = await db.update(docId, updateFunction, { createIfMissing: true })
POST /<dbName>/_bulk_docs
const res = await db.bulk(docs)
See CouchDB documentation for more information
GET /<dbName>/_all_docs?<properly encoded query>
const { rows } = await db.allDocs(query)
Queries the _all_docs view. query supports the same keys as in db.view.
Loads documents with the specified keys and query parameters
const { rows } = await db.allDocsKeys(keys, query)
Takes doc ids, returns docs.
const { docs, errors } = await db.fetch([ 'doc-1', 'doc-2', 'doc-3', 'some-non-existing-doc' ])
docs[0]._id === 'doc-1' // true
docs[1]._id === 'doc-2' // true
docs[2]._id === 'doc-3' // true
errors[0].key === 'some-non-existing-doc' // true
errors[0].error === 'not_found' // true
Queries the changes given the specified query parameters.
const latestChanges = await db.changes({ descending: true, limit: 10 })
:warning: the feed mode is not supported as a feed can not be returned as a stream. To follow a change feed, see cloudant-follow
Takes a doc id, returns the doc's rev infos
const revsInfo = await db.listRevs('doc-1')
revsInfo will look something like:
[
{ rev: '3-6a8869bc7fff815987ff9b7fda3e10e3', status: 'available' },
{ rev: '2-88476e8877ff5707de9e62e70a8e0aeb', status: 'available' },
{ rev: '1-a8bdf0ef0b7049d35c781210723b9ff9', status: 'available' }
]
Takes a doc id and reverts its last change, recovering the previous version. Only works if there is a previous version and if it is still available in the database (that is, if it wasn't deleted by a database compaction). It doesn't delete the last version, it simply creates a new version that is exactly like the version before the current one.
const res = await db.revertLastChange('doc-1')
Takes a doc id and a function, and reverts to the last version returning a truthy result when passed through this function.
Same warnings apply as for revertLastChange.
const desiredVersionTestFunction = doc => doc.foo === 2
db.revertToLastVersionWhere('doc-1', desiredVersionTestFunction)
Mistakes happen
await db.delete(docId, docRev)
await db.undelete(docId))
const restoredDoc = await db.get(docId))
:warning: this will obviously not work if the version before deletion isn't in the database (because the database was compressed or it's a freshly replicated database), or if the database was purged from deleted documents.
GET /<dbName>/_desgin/<designName>/_view/<viewName>?<properly encoded query>
const { rows, total_rows, offset } = db.view(designName, viewName, query)
Queries a view with the given name in the given design doc. query should be an object with any of the query parameters
const { rows } = await db.view('someDesignDocName', 'someViewName', {
keys: [ 'a', 'b', 'c' ],
include_docs: true,
limit: 5,
skip: 1
})
Those functions are pre-filled versions of the view functions above for the most common operations, like to get all the documents associated to an array of ids.
To access those, pass a design doc name as second argument
const db = getDbApi('some-db-name', 'some-design-doc-name')
If you find this module useful, consider making a PR to improve the documentation
you might want to consider using couchdb-nano, the now offical (but bloated ;p) CouchDB NodeJS lib
FAQs
CouchDB library with a simple, functional-programing-friendly API, returning promises
The npm package blue-cot receives a total of 14 weekly downloads. As such, blue-cot popularity was classified as not popular.
We found that blue-cot demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.