CouchDB library with a simple, functional-programing-friendly API, returning Bluebird promises
CouchDB library with a simple, functional-programing-friendly API, returning Bluebird promises.
Forked from Cot
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 = {
// MUST
hostname: 'localhost'
port: 5984,
// MAY
ssl: true // default: false
gzip: true // default: false
// logs the generated URLs, body, and response time
debug: true // default: false
// use one of the two:
// together
auth: 'username:password'
// or separated
user: 'username'
pass: 'password'
}
const getDbApi = bluecot(config)
const db = getDbApi('some-db-name')
To handle database and design documents creation, see couch-init2
GET /<dbName>
const promise = db.info()
GET /<dbName>/<docId>
Takes a document id and optionaly a rev id to get a specific version:
db.get('doc-1')
.then(function (lastDocVersion) {
// do something
})
db.get('doc-1', '2-b8476e8877ff5707de9e62e70a8e0aeb')
.then(function (specificVersion) {
// doc._rev === '2-b8476e8877ff5707de9e62e70a8e0aeb'
})
Missing documents are treated as an error, and thus return a rejected promise.
POST /<dbName>
const promise = 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 promise = 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 promise = 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
db.put(doc)
.then(response => {
if (!response.ok) {
// there was a conflict
}
})
GET /<dbName>/<docId>
const promise = 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 promise = 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 promise = 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.
If updateFunction needs to do asynchronous work, it may return a promise.
POST /<dbName>/_bulk_docs
const promise = db.bulk(docs)
See CouchDB documentation for more information
GET /<dbName>/_all_docs?<properly encoded query>
const promise = 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 promise = db.allDocsKeys(keys, query)
Takes doc ids, returns docs
db.fetch([ 'doc-1', 'doc-2', 'doc-3' ])
.then(function (docs) {
docs[0]._id === 'doc-1' // true
docs[1]._id === 'doc-2' // true
docs[2]._id === 'doc-3' // true
})
(That's pretty much the same thing as db.allDocsKeys but with the query object set to { include_docs: true })
Queries the changes feed given the specified query. query may contain the following keys:
filter: filter function to useinclude_docs: if true, results will contain entire documentlimit: the maximum number of change rows this query should returnsince: results will start immediately after the sequence number provided herelongpoll: if true, query will send feed=longpolltimeout: timeout in milliseconds for logpoll queriesSee CouchDB changes feed documentation
Takes a doc id, returns the doc's rev infos
db.listRevs('doc-1')
.then(function (revsInfo) {
// do your thing
})
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.
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
db.delete(docId, docRev)
.then(res => db.undelete(docId))
.then(res => db.get(docId))
.then(restoredDoc => // celebrate)
: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 promise = 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 following keys:
For more information, refer to Couchdb documentation
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
Since v3.4.3, authentification relies on Cookie Sessions instead of Basic Auth for better performance. By default, sessions timeout after 10 minutes of inactivity, but this can be adjusted.
Indeed, from our benchmark:
FAQs
CouchDB library with a simple, functional-programing-friendly API, returning promises
The npm package blue-cot receives a total of 12 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.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.
Security News
require(esm) backported to Node.js 20, easing the transition to ESM-only packages and reducing complexity for developers as Node 18 nears end-of-life.
Security News
PyPI now supports iOS and Android wheels, making it easier for Python developers to distribute mobile packages.