node-couch

CouchDb library for Node.Js

Installation

npm install node-couch --save

NPM package

• https://npmjs.com/package/node-couch

Api

All methods return the current namespace and each namespace has a .parent() function so function calls can be chained. Additionally, all callback functions are bound to the current namespace, so this inside the callbacl will refer to the namespace in the client for the function that was called meaning that you can in an easy way continue to perform further operations once one operation has finished.

Setup

var nodeCouch = require('node-couch'),
        _couchDb = new nodeCouch.Client().initialize({
            credentials: {
                userName: 'userName',
                password: 'password'
            },
            database: 'node-couch',
            timeout: 30000,
            url: {
                hostName: 'localhost',
                port: 5984
            }
        });

Methods

Client level

.initialize(configuration)

Initialize the client.

Parameters:

• configuration - Object.
  • credentials - Object. Optional.
    • userName - String. User name to log in with.
    • password - String. Password to log in with.
  • database - String. Database name. Optional.
  • timeout - Number. Request timeout in milliseconds. Optional. Defaults to 30000.
  • url - Object.
    • hostName - String. Ip/domain name to connect to.
    • port - Number. Port to connect to.

_couchDb.initialize(configuration);

.configure(configuration)

Get or set the client configuration.

Parameters:

• configuration - Object. Same as the configuration object in the .initialize() function above. Optional.

_couchDb.configure(configuration);

.credentials(credentials)

Get or set the client credentials configuration.

Parameters:

• configuration - Object. Same as the credentials part of the configuration object in the .initialize() function above. Optional.

_couchDb.credentials(credentials);

Database level

.Database.create(callback)

Creates a database (using the database that is currently configured in the client).

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Database.create(function (error, response) {});

.Database.delete(callback)

Deletes a database (using the database that is currently configured in the client).

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Database.delete(function (error, response) {});

.Database.exists(callback)

Checks if a database exists (using the database that is currently configured in the client).

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Database.exists(function (error, response) {});

.Database.get(callback)

Gets information about a database (using the database that is currently configured in the client).

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Database.get(function (error, response) {});

.Database.parent()

Navigates to the parent namespace (Root level).

_couchDb.Database.parent();

.Database.select(database)

Selects a new database.

Parameters:

• database - String. New database.

_couchDb.Database.select('[Database]');

Design document level

.Design.create(designDocument, callback)

Creates a design document. All functions will be serialized to strings.

Parameters:

• designDocument - Object.
  • _id - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
  • OtherDesignDocumentProperties...
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Design.create({
    _id: '[DesignDocumentId]',
    language: 'javascript',
    views: {}
}, function (error, response) {});

.Design.delete(designDocumentInfo, callback)

Deletes a design document. All string functions will be deserialized to functions.

Parameters:

• designDocumentInfo - Object.
  • _id - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
  • _rev - String. Design document revision.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Design.delete({
    _id: '[DesignDocumentId]',
    _rev: '[DesignDocumentRevision]'
}, function (error, response) {});

.Design.exists(designDocumentId, callback)

Checks if a design document exists.

Parameters:

• designDocumentId - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Design.exists('[DesignDocumentId]', function (error, response) {});

.Design.get(designDocumentId, callback)

Gets a design document.

Parameters:

• designDocumentId - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Design.get('[DesignDocumentId]', function (error, response) {});

.Design.parent()

Navigates to the parent namespace (Root level).

_couchDb.Design.parent();

.Design.update(designDocument, callback)

Updates a design document. All functions will be serialized to strings.

Parameters:

• designDocument - Object.
  • _id - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
  • _rev - String. Design document revision.
  • OtherDesignDocumentProperties...
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Design.update({
    _id: '[DesignDocumentId]',
    _rev: '[DesignDocumentRevision]',
    language: 'javascript',
    views: {}
}, function (error, response) {});

Document level

Bulk document level

.Document.Bulk.create(documents, callback)

Bulk creates documents.

Parameters:

• documents - Array<Object>. Array of documents to create.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response - Object. Populated if successful, otherwise undefined.
      • failed - Array<Object>;. Array of status objects from CouchDb for documents that failed to create.
      • response - Array<Object>. Array of statuses from CouchDb for all documents.
      • successful - Array<Object>. Array of status objects from CouchDb for documents that succeeded to create.

_couchDb.Document.Bulk.create(documents, function (error, response) {});

.Document.Bulk.delete(documents, callback)

Bulk deletes documents. Each document in the array is expected to have the CouchDb internal properties _id & _rev. This can be be achieved by first fetching the document using .Document.get() and then passing it to this function.

Parameters:

• documents - Array<Object>. Array of documents to create.
  • Document properties:
    • _id - String. Document id.
    • _rev - String. Document revision.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response - Object. Populated if successful, otherwise undefined.
      • failed - Array<Object>;. Array of status objects from CouchDb for documents that failed to create.
      • response - Array<Object>. Array of statuses from CouchDb for all documents.
      • successful - Array<Object>. Array of status objects from CouchDb for documents that succeeded to create.

_couchDb.Document.Bulk.create(documents, function (error, response) {});

.Document.Bulk.parent()

Navigates to the parent namespace (Document level).

_couchDb.Document.Bulk.parent();

.Document.Bulk.update(documents, callback)

Bulk updates documents. Each document in the array is expected to have the CouchDb internal properties _id & _rev. This can be be achieved by first fetching the document using .Document.get(), making the updates to that document and then passing it to this function.

Parameters:

• documents - Array<Object>. Array of documents to create.
  • Document properties:
    • _id - String. Document id.
    • _rev - String. Document revision.
    • OtherDocumentProperties...
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response - Object. Populated if successful, otherwise undefined.
      • failed - Array<Object>. Array of status objects from CouchDb for documents that failed to create.
      • response - Array<Object>. Array of statuses from CouchDb for all documents.
      • successful - Array<Object>. Array of status objects from CouchDb for documents that succeeded to create.

_couchDb.Document.Bulk.update(documents, function (error, response) {});

.Document.create(document, callback)

Creates a document.

Parameters:

• document - Object.
  • _id - String. Optional.
  • OtherDocumentProperties...
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Document.create(document, function (error, response) {});

.Document.delete(documentInfo, callback)

Deletes a document.

Parameters:

• documentInfo - Object.
  • _id - String. Document id.
  • _rev - String. document revision.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Document.delete(documentInfo, function (error, response) {});

.Document.exists(documentId, callback)

Checks if a document exists.

Parameters:

• documentId - String. Document id.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Document.exists(documentId, function (error, response) {});

.Document.get(documentId, callback)

Gets a document.

Parameters:

• documentId - String. Document id.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Document.get(documentId, function (error, response) {});

.Document.parent()

Navigates to the parent namespace (Root level).

_couchDb.Document.parent();

.Document.update(document, callback)

Updates a document.

Parameters:

• document - Object.
  • _id - String. Document id.
  • _rev - String. Document revision.
  • OtherDocumentProperties...
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Document.update(document, function (error, response) {});

Server level

.Server.databases(callback)

Gets a list of databases.

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Server.databases(function (error, response) {});

.Server.get(callback)

Gets information about the server.

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Server.databases(function (error, response) {});

[NotImplemented] .Server.login(callback)

Logs in to the server. Throws a NotImplemented exception.

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Server.login(function (error, response) {});

[NotImplemented] .Server.logout(callback)

Logs out of the server. Throws a NotImplemented exception.

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Server.logout(function (error, response) {});

.Server.parent()

Navigates to the parent namespace (Root level).

_couchDb.Server.parent();

[NotImplemented] .Server.session(callback)

Gets session information. Throws a NotImplemented exception.

Parameters:

• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.Server.session(function (error, response) {});

View level

.View.parent()

Navigates to the parent namespace (Root level).

_couchDb.View.parent();

.View.query(options, callback)

Queries a view. Will get each document in the view (unless limits/paging are used in the query).

Parameters:

• options - Object.
  • designDocumentId - String. Can be just an {id} or _design/{id}, _design/ will be added if it is not already there.
  • query - String. Query to pass along to the view.
  • view - String. The name of the view.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response. Passed through from CouchDb if successful, otherwise undefined.

_couchDb.View.query({
    designDocument: 'SomeType',
    query: 'key="SomeKey"',
    view: 'BySomeId'
}, function (error, response) {});

.View.transform(options, action, callback)

Transforms all documents of a view. Will transform each document in a view (unless limits/paging are used).

Parameters:

• options - Object.
  • designDocumentId - String. Can be just an {id} or _design/{id}, _design/ will be added if the option is specified and it is not already there. Defaults to null which means no design document will be used.
  • key - String. CouchDb key parameter. Used for filtering the view.
  • limit - Number. Number of items per page. Defaults to 100.
  • pages - Number. Number of pages. Defaults to null which means all.
  • view - String. The name of the view. Defaults to '_all_docs' which means all documents in the database will be used.
• action - Function. Function to apply to each document. If the function returns the (case senstitive) string Delete then the document will be deleted. Otherwise it is expected that the function will return the updated document.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response - Object. Populated if successful, otherwise undefined.
      • response - Array<Object>. Array of documents. Populated if the transformation action does not return a transformation.
      • processedDocuments - Number. Number of processed documents.
      • processedPages - Number. Number of processed pages.

_couchDb.View.transform({}, function (document) {}, function (error, response) {});

.View.traverse(options, callback)

Traverses a view. Will traverse each document in a view (unless limits/paging are used), optionally applying an action to each of them.

Parameters:

• options - Object.
  • action - Function. Function to apply to each document. If the function returns the (case senstitive) string Delete then the document will be deleted. Otherwise it is expected that the function will return the updated document.
  • designDocumentId - String. Can be just an {id} or _design/{id}, _design/ will be added if the option is specified and it is not already there. Defaults to null which means no design document will be used.
  • key - String. CouchDb key parameter. Used for filtering the view.
  • limit - Number. Number of items per page. Defaults to 100.
  • pages - Number. Number of pages. Defaults to null which means all.
  • view - String. The name of the view. Defaults to '_all_docs' which means all documents in the database will be used.
• callback - Function. Optional.
  • Callback parameters:
    • error - Object. Populated if an error occurred, otherwise null.
    • response - Object. Populated if successful, otherwise undefined.
      • response - Array<Object>. Array of documents. Populated if the transformation action does not return a transformation.
      • processedDocuments - Number. Number of processed documents.
      • processedPages - Number. Number of processed pages.

_couchDb.View.traverse({}, function (error, response) {});

Mappers

nodeCouch.Mappers.Response.View

Maps a view response into an array of documents, optionally removing the CouchDb internal properties.

var _viewResponseMapper = new nodeCouch.Mappers.Response.View(),
        _removeInternalProperties = false,
        _documents = _viewResponseMapper.map(viewResponse, _removeInternalProperties);

nodeCouch.Mappers.Response.Document

Maps a document response into a document object, optionally removing the CouchDb internal properties.

var _documentResponseMapper = new nodeCouch.Mappers.Response.Document(),
        _removeInternalProperties = false,
        _documents = _documentResponseMapper.map(documentResponse, _removeInternalProperties);

Examples

View Traverser

Traverse view && return all data

var nodeCouch = require('node-couch'),
        _couchDb = new nodeCouch.Client().initialize({
            credentials: {
                userName: 'userName',
                password: 'password'
            },
            database: 'node-couch',
            url: {
                hostName: 'localhost',
                port: 5984
            }
        });
 
_couchDb.View.traverse({
    designDocumentId: 'SomeType',
    view: 'BySomeId'
}, function (error, response) {
    if (error) {
        console.log(error);
 
        return;
    }
 
    var data = new nodeCouch.Mappers.Response.View().map(response.data),
            _documentMapper = new nodeCouch.Mappers.Response.Document();
 
    for (var d in data) {
        if (!data.hasOwnProperty(d)) continue;
 
        console.log(_documentMapper.map(data[d]));
    }
});

View Transformer

Traverse view && apply update to each document

var nodeCouch = require('node-couch'),
        _couchDb = new nodeCouch.Client().initialize({
            credentials: {
                userName: 'userName',
                password: 'password'
            },
             database: 'node-couch',
             url: {
                 hostName: 'localhost',
                 port: 5984
             }
        });
 
_couchDb.View.transform({
    designDocumentId: 'SomeType',
    view: 'BySomeId'
}, function (document) {
    if (!document.dummy) {
        document.dummy = 'asdf';
    }
    else {
        delete document['dummy'];
    }
 
    return document;
}, function (error, response) {
    if (error) {
        console.log(error);
 
        return;
    }
 
    console.log(response);
});

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality.

Release History

• 2019-04-12 v2.5.0 UrlEncode keys used for paging.
• 2018-09-21 v2.4.1 Corrected view examples in README.
• 2018-05-23 v2.4.0 Keep view traverser & transformer from proceeding to the next page until all document modifications have completed.
• 2017-10-12 v2.3.0 Added support for specifying request timeout.
• 2017-09-27 v2.2.2 Updated documentation.
• 2017-09-13 v2.2.1 Minor bugfix.
• 2017-09-12 v2.2.0 Deserialize functions when getting design documents.
• 2017-09-06 v2.1.0 Serialize functions when creating or updating design documents.
• 2017-09-06 v2.0.0 2.0.0 Rewrite.
• 2016-09-21 v1.0.6 Fixed view response mapper.
• 2016-08-19 v1.0.5 Fix for weird GitHub Markdown syntax.
• 2016-08-19 v1.0.4 Fixed typo.
• 2016-08-19 v1.0.3 Added more docs.
• 2016-08-19 v1.0.2 Added more docs and removed peerDependencies.
• 2016-06-13 v1.0.1 Fixed peerDependencies.
• 2016-05-11 v1.0.0 Initial version.