https://github.com/1999/node-couchdb
ES2015-compatible package to interact with CouchDB
https://github.com/1999/node-couchdb
couchdb nodejs
Last synced: about 2 months ago
JSON representation
ES2015-compatible package to interact with CouchDB
- Host: GitHub
- URL: https://github.com/1999/node-couchdb
- Owner: 1999
- Created: 2013-01-08T11:43:59.000Z (over 12 years ago)
- Default Branch: master
- Last Pushed: 2023-09-16T09:12:27.000Z (over 1 year ago)
- Last Synced: 2025-03-31T13:17:36.555Z (about 2 months ago)
- Topics: couchdb, nodejs
- Language: JavaScript
- Homepage:
- Size: 329 KB
- Stars: 76
- Watchers: 4
- Forks: 29
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
Awesome Lists containing this project
README
# node-couchdb [](http://travis-ci.org/1999/node-couchdb) [](https://david-dm.org/1999/node-couchdb) [](https://david-dm.org/1999/node-couchdb#info=devDependencies) [](https://greenkeeper.io/)
`node-couchdb` package provides an easy way to interact with CouchDB using preferred cache layer:
* [process memory](https://www.npmjs.com/package/node-couchdb-plugin-memory)
* [memcached](https://www.npmjs.com/package/node-couchdb-plugin-memcached)
* place for your plugin :)
# Installation
``` bash
npm install node-couchdb --save
```
# API
## Constructor
`node-couchdb` exports constructor, which accepts one object argument with properties `host` (127.0.0.1 by default), `port` (5984 by default), `protocol` (http by default), `cache` (one of plugins, null by default), `auth` (object with properties `{user, pass}`) and `timeout` for all requests (5000 by default). All object fields are optional.
ES Module:
```javascript
import NodeCouchDb from 'node-couchdb';
```
Common JS:
```javascript
const NodeCouchDb = require('node-couchdb');
```
```javascript
// node-couchdb instance with default options
const couch = new NodeCouchDb({
auth: {
user: AUTH_USER,
pass: AUTH_PASS
}
});
// node-couchdb instance with Memcached
const MemcacheNode = require('node-couchdb-plugin-memcached');
const couchWithMemcache = new NodeCouchDb({
cache: new MemcacheNode,
auth: {
user: AUTH_USER,
pass: AUTH_PASS
}
});
// node-couchdb instance talking to external service
const couchExternal = new NodeCouchDb({
host: 'couchdb.external.service',
protocol: 'https',
port: 6984,
auth: {
user: AUTH_USER,
pass: AUTH_PASS
}
});
```
All node-couchdb methods return Promise instances which resolve if everything works as expected and reject with Error instance which usually has `code` and `body` fields. See package source and tests for more info.
## Create database
```javascript
couch.createDatabase(dbName).then(() => {...}, err => {
// request error occured
});
```
## Drop database
```javascript
couch.dropDatabase(dbName).then(() => {...}, err => {
// request error occured
});
```
## List databases
```javascript
couch.listDatabases().then(dbs => dbs.map(...), err => {
// request error occured
});
```
## Get document by its id
```javascript
couch.get("databaseName", "some_document_id").then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EDOCMISSING if document is missing
// ...or err.code=EUNKNOWN if statusCode is unexpected
});
```
## Get view results
```javascript
const dbName = "database";
const startKey = ["Ann"];
const endKey = ["George"];
const viewUrl = "_design/list/_view/by_firstname";
const queryOptions = {
startkey: startKey,
endkey: endKey
};
couch.get(dbName, viewUrl, queryOptions).then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EDOCMISSING if document is missing
// ...or err.code=EUNKNOWN if statusCode is unexpected
});
```
## Query using Mango
```javascript
const dbName = "database";
const mangoQuery = {
selector: {
firstname: {
$gte: 'Ann',
$lt: 'George'
}
}
};
couch.mango(dbName, mangoQuery).then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EDOCMISSING if document is missing
// ...or err.code=EUNKNOWN if statusCode is unexpected
});
```
## Insert a document
```javascript
couch.insert("databaseName", {
_id: "document_id",
field: ["sample", "data", true]
}).then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EDOCCONFLICT if document with the same id already exists
});
```
## Update a document
```javascript
// note that "doc" must have both "_id" and "_rev" fields
couch.update("databaseName", {
_id: "document_id",
_rev: "1-xxx"
field: "new sample data",
field2: 1
}).then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EFIELDMISSING if either _id or _rev fields are missing
});
```
## Insert an attachment
```javascript
couch.insertAttachment("databaseName", "document id", "attachment name", "attachment body", "doc revision").then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EFIELDMISSING if either _id or _rev fields are missing
});
```
## Delete an attachment
```javascript
// note that "doc" must have both "_id" and "_rev" fields
couch.update("databaseName", "document id", "attachment name", "doc revision").then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EFIELDMISSING if either _id or _rev fields are missing
});
```
## Use an update function
```javascript
couch.updateFunction("databaseName", "designDocument", "updateFunction", {optional query string}, "docid").then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EFIELDMISSING if either _id or _rev fields are missing
});
```
## Delete a document
```javascript
couch.del("databaseName", "some_document_id", "document_revision").then(({data, headers, status}) => {
// data is json response
// headers is an object with all response headers
// status is statusCode number
}, err => {
// either request error occured
// ...or err.code=EDOCMISSING if document does not exist
// ...or err.code=EUNKNOWN if response status code is unexpected
});
```
## Generate unique identifier(s)
```javascript
// get one unique id
couch.uniqid().then(ids => ids[0]);
// get N unique ids
couch.uniqid(N).then(ids => ids.map(...));
```