Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

cloudant

Package Overview
Dependencies
Maintainers
3
Versions
24
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

cloudant - npm Package Compare versions

Comparing version 1.0.0 to 1.1.0

cloudant.js

17

CONTRIBUTING.md

@@ -1,5 +0,14 @@

# DCO
# Contributor License Agreement
To contribute to this project you must accept our [developer certificate of origin](https://github.com/dscape/nano/blob/master/README.md)
In order for us to accept pull-requests, the contributor must first complete a Contributor License Agreement (CLA). This clarifies the intellectual property license granted with any contribution. It is for your protection as a Contributor as well as the protection of IBM and its customers; it does not change your rights to use your own Contributions for any other purpose.
This is a quick process: one option is signing using Preview on a Mac, then sending a copy to us via email. Signing this agreement covers both CDTDatastore and sync-android.
You can download the CLAs here:
- [Individual](http://cloudant.github.io/cloudant-sync-eap/cla/cla-individual.pdf)
- [Corporate](http://cloudant.github.io/cloudant-sync-eap/cla/cla-corporate.pdf)
If you are an IBMer, please contact us directly as the contribution process is slightly different.
# Contributing

@@ -9,3 +18,3 @@

1. Create an [issue][2] on github so the community can comment on your idea
1. Create an [issue](http://github.com/cloudant/nodejs-cloudant/issues) on github so the community can comment on your idea
2. Fork `nano` in github

@@ -32,3 +41,1 @@ 3. Create a new branch `git checkout -b my_branch`

You can turn nocks on and off using the `NOCK_OFF` environment variable.
[issues]: http://github.com/cloudant/nodejs-cloudant/issues

@@ -1,15 +0,201 @@

# The Apache License, version 2.0
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
copyright 2014 nuno job <nunojob.com> (oO)--',--
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
licensed under the apache license, version 2.0 (the "license");
you may not use this file except in compliance with the license.
you may obtain a copy of the license at
1. Definitions.
http://www.apache.org/licenses/LICENSE-2.0
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
unless required by applicable law or agreed to in writing, software
distributed under the license is distributed on an "as is" basis,
without warranties or conditions of any kind, either express or implied.
see the license for the specific language governing permissions and
limitations under the license.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "{}"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright {yyyy} {name of copyright owner}
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

@@ -7,4 +7,7 @@ {

"repository": "git://github.com/cloudant/nodejs-cloudant",
"version": "1.0.0",
"version": "1.1.0",
"author": "Jason Smith <jason@cloudant.com>",
"contributors": [
"Glynn Bird <glynn.bird@gmail.com>"
],
"keywords": [

@@ -18,41 +21,22 @@ "cloudant",

"dependencies": {
"request": "^2.53.0",
"follow": "^0.11.4",
"errs": "^0.3.0",
"underscore": "^1.7.0",
"debug": "^2.0.0"
"debug": "^2.2.0",
"nano": "6.1.3"
},
"devDependencies": {
"async": "^0.9.0",
"tape": "^3.0.0",
"istanbul": "^0.3.2",
"jshint": "^2.5.6",
"jscs": "^1.7.0",
"dotenv": "^1.1.0",
"mocha": "^2.2.5",
"nock": "^0.48.1",
"endswith": "^0.0.0",
"tape-it": "^0.3.1",
"pre-commit": "0.0.9"
"should": "^6.0.3"
},
"scripts": {
"test-cloudant": "tape tests/integration/cloudant/*.js",
"test-cloudant-live": "NOCK_OFF=true tape tests/integration/cloudant/*.js",
"test": "DEBUG=* NOCK_OFF=true istanbul cover tape tests/*/*/*.js",
"unmocked": "NOCK_OFF=true tape tests/*/*/*.js",
"mocked": "tape tests/*/*/*.js",
"jshint": "jshint tests/*/*/*.js lib/*.js",
"codestyle": "jscs -p google tests/*/*/*.js lib/*.js",
"coverage": "open coverage/lcov-report/index.html",
"checkcoverage": "istanbul check-coverage --statements 100 --functions 100 --lines 100 --branches 100"
"test": "mocha tests/*.js",
"test-verbose": "env DEBUG='*,-mocha:*' npm run test",
"test-live": "NOCK_OFF=true mocha --timeout=5000 tests/*.js",
"test-live-verbose": "env DEBUG='*,-mocha:*' npm run test-live"
},
"main": "./lib/nano.js",
"main": "./cloudant.js",
"engines": {
"node": ">=0.8.0"
},
"pre-commit": [
"jshint",
"codestyle",
"mocked",
"test",
"checkcoverage"
]
}
}

@@ -7,7 +7,26 @@ # Cloudant Node.js Client

* [Getting Started](#getting-started)
* [Initialization](#initialization)
* [Callback Signature](#callback-signature)
* [Password Authentication](#password-authentication)
* [Cloudant Local](#cloudant-local)
* [API Reference](#api-reference)
* [Authorization and API Keys](#authorization-and-api-keys)
* [Generate an API key](#generate-an-api-key)
* [Use an API Key](#use-an-api-key)
* [CORS](#cors)
* [Cloudant Query](#cloudant-query)
* [Cloudant Search](#cloudant-search)
* [Cookie Authentication](#cookie-authentication)
* [Advanced Features](#advanced-features)
* [Advanced Configuration](#advanced-configuration)
* [Pool size and open sockets](#pool-size-and-open-sockets)
* [Extending the Cloudant Library](#extending-the-cloudant-library)
* [Pipes](#pipes)
* [Development](#development)
* [Test Suite](#test-suite)
* [Using in Other Projects](#using-in-other-projects)
* [License](#license)
* [Security Note](#security-note)
* [License](#license)
* [Reference](#reference)

@@ -32,3 +51,2 @@ ## Installation and Usage

~~~ js
var Cloudant = require('cloudant')

@@ -38,8 +56,6 @@ var me = 'jhs' // Set this to your own account

Cloudant({account:me, password:password}, function(err, cloudant) {
console.log('Connected to Cloudant')
var cloudant = require('cloudant')({account:me, password:password});
cloudant.db.list(function(err, all_dbs) {
console.log('All my databases: %s', all_dbs.join(', '))
})
cloudant.db.list(function(err, all_dbs) {
console.log('All my databases: %s', all_dbs.join(', '))
})

@@ -50,4 +66,3 @@ ~~~

Connected to Cloudant
All my databases: example_db, jasons_stuff, scores
All my databases: example_db, jasons_stuff, scores

@@ -74,26 +89,19 @@ Upper-case `Cloudant` is this package you load using `require()`, while lower-case `cloudant` represents an authenticated, confirmed connection to your Cloudant service.

var me = process.env.cloudant_username
var password = process.env.cloudant_password
// Clean up the database we created previously.
cloudant.db.destroy('alice', function() {
// Create a new database.
cloudant.db.create('alice', function() {
// specify the database we are going to use
var alice = cloudant.db.use('alice')
// and insert a document in it
alice.insert({ crazy: true }, 'rabbit', function(err, body, header) {
if (err)
return console.log('[alice.insert] ', err.message)
Cloudant({account:me, password:password}, function(er, cloudant) {
if (er)
return console.log('Error connecting to Cloudant account %s: %s', me, er.message)
// Clean up the database we created previously.
cloudant.db.destroy('alice', function() {
// Create a new database.
cloudant.db.create('alice', function() {
// specify the database we are going to use
var alice = cloudant.use('alice')
// and insert a document in it
alice.insert({ crazy: true }, 'rabbit', function(err, body, header) {
if (err)
return console.log('[alice.insert] ', err.message)
console.log('you have inserted the rabbit.')
console.log(body)
})
console.log('you have inserted the rabbit.')
console.log(body)
})
})
})
~~~

@@ -108,54 +116,3 @@

## API Reference
- [Initialization](#initialization)
- [Callback Signature](#callback-signature)
- [Password Authentication](#password-authentication)
- [Cloudant Local](#cloudant-local)
- [Authorization and API Keys](#authorization-and-api-keys)
- [Generate an API Key](#generate-an-api-key)
- [Use an API Key](#use-an-api-key)
- [Database Functions](#database-functions)
- [cloudant.db.create(name, [callback])](#Cloudantdbcreatename-callback)
- [cloudant.db.get(name, [callback])](#Cloudantdbgetname-callback)
- [cloudant.db.destroy(name, [callback])](#Cloudantdbdestroyname-callback)
- [cloudant.db.list([callback])](#Cloudantdblistcallback)
- [cloudant.db.compact(name, [designname], [callback])](#Cloudantdbcompactname-designname-callback)
- [cloudant.db.replicate(source, target, [opts], [callback])](#Cloudantdbreplicatesource-target-opts-callback)
- [cloudant.db.changes(name, [params], [callback])](#Cloudantdbchangesname-params-callback)
- [cloudant.db.follow(name, [params], [callback])](#Cloudantdbfollowname-params-callback)
- [Cloudant.use(name)](#Cloudantusename)
- [Cloudant.request(opts, [callback])](#Cloudantrequestopts-callback)
- [Cloudant.config](#Cloudantconfig)
- [Cloudant.updates([params], [callback])](#Cloudantupdatesparams-callback)
- [Cloudant.follow_updates([params], [callback])](#Cloudantfollow_updatesparams-callback)
- [Document Functions](#document-functions)
- [db.insert(doc, doc_id, [callback])](#dbinsertdoc-doc_id-callback)
- [db.destroy(doc_id, rev, [callback])](#dbdestroydoc_id-rev-callback)
- [db.get(doc_id, [params], [callback])](#dbgetdoc_id-params-callback)
- [db.head(doc_id, [callback])](#dbheaddoc_id-callback)
- [db.copy(src_doc, dest_doc, opts, [callback])](#dbcopysrc_doc-dest_doc-opts-callback)
- [db.bulk(docs, [params], [callback])](#dbbulkdocs-params-callback)
- [db.list([params], [callback])](#dblistparams-callback)
- [db.fetch(doc_ids, [params], [callback])](#dbfetchdoc_ids-params-callback)
- [db.fetch_revs(doc_ids, [params], [callback])](#dbfetch_revsdoc_ids-params-callback)
- [Multipart Functions](#multipart-functions)
- [db.multipart.insert(doc, attachments, [params], [callback])](#dbmultipartinsertdoc-attachments-params-callback)
- [db.multipart.get(doc_id, [params], [callback])](#dbmultipartgetdoc_id-params-callback)
- [Attachment Functions](#attachments-functions)
- [db.attachment.insert(doc_id, attname, att, contenttype, [params], [callback])](#dbattachmentinsertdoc_id-attname-att-contenttype-params-callback)
- [db.attachment.get(doc_id, attname, [params], [callback])](#dbattachmentgetdoc_id-attname-params-callback)
- [db.attachment.destroy(doc_id, attname, rev, [callback])](#dbattachmentdestroydoc_id-attname-rev-callback)
- [Design Document Functions](#design-document-functions)
- [db.view(designname, viewname, [params], [callback])](#dbviewdesignname-viewname-params-callback)
- [db.search(designname, viewname, [params], [callback])](#dbsearchdesignname-searchname-params-callback)
- [Cloudant Search](#cloudant-search)
- [Cloudant Query](#cloudant-query)
- [Cookie Authentication](#cookie-authentication)
- [Advanced Configuration](#advanced-configuration)
- [Advanced Features](#advanced-features)
- [Extending the Cloudant Library](#extending-the-cloudant-library)
- [Pipes](#pipes)
- [Tests](#tests)
### Initialization

@@ -166,21 +123,13 @@

~~~ js
var Cloudant = require('cloudant')
var Cloudant = require('cloudant')({account:me, password:password});
~~~
// Connect to Cloudant.
Cloudant({account:me, password:password}, function(er, cloudant) {
if (er)
return console.log('Error connecting to Cloudant account %s: %s', me, er.message)
If you would prefer, you can also initialize Cloudant with a URL:
console.log('Connected to cloudant')
/*
* The rest of my code goes here.
*/
})
~~~ js
var Cloudant = require('cloudant')("https://MYUSERNAME:MYPASSWORD@MYACCOUNT.cloudant.com");
~~~
If you would prefer, you can also initialize Cloudant synchronously by omitting the callback.
This can help avoid messy code if you are requiring the Cloudant library in many places in your app.
This can help avoid messy code if you are requiring the Cloudant library in many places in your app. You should note that this method does not verify that your Cloudant credentials are correct - you would have to use the [ping](#cloudantpingcallback) for that.
A simple example of initializing sychronously is:

@@ -190,3 +139,3 @@ ~~~ js

var db = Cloudant.use("animals");
var db = Cloudant.db.use("animals");

@@ -200,16 +149,2 @@ db.get("dog", function(err, data) {

### cloudant.ping([callback])
Ping Cloudant. If this succeeds, then you have a good connection to Cloudant, and if you provided authentication credentials, they are valid.
~~~ js
cloudant.ping(function(er, reply) {
if (er)
return console.log('Failed to ping Cloudant')
console.log('Server version = %s', reply.version)
console.log('I am %s and my roles are %j', reply.userCtx.name, reply.userCtx.roles)
})
~~~
### Callback Signature

@@ -252,2 +187,35 @@

## API Reference
Cloudant is a wrapper around the Nano library and as such, Nano's documentation should be consulted for:
- [Database functions](https://github.com/dscape/nano#database-functions)
- [Document functions](https://github.com/dscape/nano#document-functions)
- [Multipart functions](https://github.com/dscape/nano#multipart-functions)
- [Attachment functions](https://github.com/dscape/nano#attachments-functions)
- [View and Design functions](https://github.com/dscape/nano#views-and-design-functions)
This library adds documentation for the following:
- [Authorization and API Keys](#authorization-and-api-keys)
- [Generate an API key](#generate-an-api-key)
- [Use an API Key](#use-an-api-key)
- [CORS](#cors)
- [Cloudant Query](#cloudant-query)
- [Cloudant Search](#cloudant-search)
- [Cookie Authentication](#cookie-authentication)
- [Advanced Features](#advanced-features)
- [Advanced Configuration](#advanced-configuration)
- [Pool size and open sockets](#pool-size-and-open-sockets)
- [Extending the Cloudant Library](#extending-the-cloudant-library)
- [Pipes](#pipes)
- [Development](#development)
- [Test Suite](#test-suite)
- [Using in Other Projects](#using-in-other-projects)
- [License](#license)
- [Reference](#reference)
## Authorization and API Keys

@@ -341,8 +309,3 @@

~~~ js
Cloudant({account:"me", key:api.key, password:api.password}, function(er, cloudant, reply) {
if (er)
throw er
console.log('Connected with API key %s', reply.userCtx.name)
})
var cloudant = require('cloudant')({account:"me", key:api.key, password:api.password});
~~~

@@ -357,3 +320,3 @@

~~~ js
cloudant.cors({ enable_cors: true, allow_credentials: true, origins: ["*"]}, function(err, data) {
cloudant.set_cors({ enable_cors: true, allow_credentials: true, origins: ["*"]}, function(err, data) {
console.log(err, data);

@@ -366,3 +329,3 @@ };

~~~ js
cloudant.cors({ enable_cors: true, allow_credentials: true, origins: [ "https://mydomain.com","https://mysubdomain.mydomain.com"]}, function(err, data) {
cloudant.set_cors_({ enable_cors: true, allow_credentials: true, origins: [ "https://mydomain.com","https://mysubdomain.mydomain.com"]}, function(err, data) {
console.log(err, data);

@@ -375,3 +338,3 @@ };

~~~ js
cloudant.cors({ enable_cors: false }, function(err, data) {
cloudant.set_cors({ enable_cors: false }, function(err, data) {
console.log(err, data);

@@ -381,391 +344,15 @@ };

See <https://docs.cloudant.com/api.html#cors> for further details.
or to fetch the current CORS configuration
## Database Functions
Once Cloudant is initialized without errors, your callback has a `cloudant` object representing your connection to the server. To work with databases, use these database functions. (To work with data *inside* the databases, see below.)
### cloudant.db.create(name, [callback])
Create a Cloudant database with the given `name`.
~~~ js
cloudant.db.create('alice', function(err, body) {
if (!err)
console.log('database alice created!')
})
~~~
### cloudant.db.get(name, [callback])
Get information about `name`.
~~~ js
cloudant.db.get('alice', function(err, body) {
if (!err)
console.log(body)
})
~~~
### cloudant.db.destroy(name, [callback])
Destroy database named `name`.
~~~ js
cloudant.db.destroy('alice', function(err) {
if (!err)
console.log('Destroyed database alice')
})
~~~
### cloudant.db.list([callback])
List all the databases in Cloudant server.
~~~ js
cloudant.db.list(function(err, body) {
// body is an array
body.forEach(function(db) {
console.log(db)
})
})
~~~
### cloudant.db.replicate(source, target, [opts], [callback])
Replicates `source` to `target` with options `opts`. `target`
must exist, add `create_target:true` to `opts` to create it prior to
replication.
~~~ js
cloudant.db.replicate('alice', 'http://admin:password@otherhost.com:5984/alice',
{ create_target:true }, function(err, body) {
if (!err)
console.log(body)
})
~~~
### cloudant.db.changes(name, [params], [callback])
Asks for the changes feed of `name`, `params` contains additions
to the query string.
~~~ js
cloudant.db.changes('alice', function(err, body) {
if (!err)
console.log(body)
})
~~~
### cloudant.db.follow(name, [params], [callback])
Use [Follow][follow] to create a solid changes feed. Please consult the Follow documentation for more information as this is a very complete api on it's own.
~~~ js
var feed = db.follow({since: "now"})
feed.on('change', function (change) {
console.log("change: ", change);
})
feed.follow();
process.nextTick(function () {
db.insert({"bar": "baz"}, "bar");
// get CORS configuration
cloudant.get_cors(function(err, data) {
console.log(data);
});
// { enable_cors: true, allow_credentials: true, origins: [ '*' ] }
~~~
### cloudant.db.use(name)
See <https://docs.cloudant.com/api.html#cors> for further details.
Create a new database object for operating within the scope of a specific database.
~~~ js
var alice = cloudant.db.use('alice')
alice.insert({ crazy: true }, 'rabbit', function(err, body) {
// do something
})
~~~
### cloudant.request(opts, [callback])
Make a custom request to Cloudant, the available `opts` are:
* `opts.db` – the database name
* `opts.method` – the http method, defaults to `get`
* `opts.path` – the full path of the request, overrides `opts.doc` and
`opts.att`
* `opts.doc` – the document name
* `opts.att` – the attachment name
* `opts.qs` – query string parameters, appended after any existing `opts.path`, `opts.doc`, or `opts.att`
* `opts.content_type` – the content type of the request, default to `json`
* `opts.headers` – additional http headers, overrides existing ones
* `opts.body` – the document or attachment body
* `opts.encoding` – the encoding for attachments
* `opts.multipart` – array of objects for multipart request
### cloudant.config
An object containing the Cloudant configurations, possible keys are:
* `url` - the Cloudant url
* `db` - the database name
### cloudant.updates([params], [callback])
Listen to db updates, the available `params` are:
* `params.feed` – Type of feed. Can be one of
* `longpoll`: Closes the connection after the first event.
* `continuous`: Send a line of JSON per event. Keeps the socket open until timeout.
* `eventsource`: Like, continuous, but sends the events in EventSource format.
* `params.timeout` – Number of seconds until CouchDB closes the connection. Default is 60.
* `params.heartbeat` – Whether CouchDB will send a newline character (\n) on timeout. Default is true.
### Cloudant.followUpdates([params], [callback])
Uses [follow](https://github.com/iriscouch/follow) to create a solid
[`_db_updates`](http://docs.couchdb.org/en/latest/api/server/common.html?highlight=db_updates#get--_db_updates) feed.
please consult follow documentation for more information as this is a very complete api on it's own
~~~ js
var feed = Cloudant.followUpdates({since: "now"})
feed.on('change', function (change) {
console.log("change: ", change)
})
feed.follow()
process.nextTick(function () {
cloudant.db.create('alice')
})
~~~
## Document functions
Once you run [cloudant.db.use('db_name')](#cloudant-db-use-db-name), use the returned object to work with documents in the database.
### db.insert(doc, doc_id, [callback])
Insert `doc` in the database. The first parameter (an object) is the document body. The second parameter is the document ID.
~~~ js
var alice = cloudant.use('alice')
alice.insert({ crazy: true }, 'rabbit', function(err, body) {
if (!err)
console.log(body)
})
~~~
### db.get(doc_id, [params], [callback])
Get `doc_id` from the database with optional query string additions `params`.
~~~ js
alice.get('rabbit', { revs_info: true }, function(err, body) {
if (!err)
console.log(body);
});
~~~
### db.destroy(doc_id, rev, [callback])
Remove revision `rev` of `doc_id` from the Cloudant database.
~~~ js
alice.destroy('rabbit', '3-66c01cdf99e84c83a9b3fe65b88db8c0', function(err, body) {
if (!err)
console.log(body)
})
~~~
### db.head(doc_id, [callback])
Same as `get` but lightweight version that returns headers only.
~~~ js
alice.head('rabbit', function(err, _body, headers) {
// In fact, _body is empty.
if (!err)
console.log(headers)
})
~~~
### db.copy(src_doc, dest_doc, opts, [callback])
`copy` the contents (and attachments) of a document
to a new document, or overwrite an existing target document
~~~ js
alice.copy('rabbit', 'rabbit2', { overwrite: true }, function(err, _, headers) {
if (!err)
console.log(headers)
})
~~~
### db.bulk(docs, [params], [callback])
Bulk operations(update/delete/insert) on the database, refer to the
[Documentation](http://docs.couchdb.org/en/latest/api/database/bulk-api.html).
### db.list([params], [callback])
List all the docs in the database with optional query string additions `params`.
~~~ js
alice.list(function(err, body) {
if (!err) {
body.rows.forEach(function(doc) {
console.log(doc)
})
}
})
~~~
### db.fetch(doc_ids, [params], [callback])
Bulk fetch of the database documents, `doc_ids` are specified as per
[CouchDB doc](http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs).
Additional query string `params` can be specified, `include_docs` is always set
to `true`.
### db.fetchRevs(doc_ids, [params], [callback])
Bulk fetch of the revisions of the database documents, `doc_ids` are specified as per
[CouchDB doc](http://docs.couchdb.org/en/latest/api/database/bulk-api.html#post--db-_all_docs).
Additional query string `params` can be specified, this is the same method as fetch but
`include_docs` is not automatically set to `true`.
## Multipart Functions
The multipart functions are for efficiently working with documents and attachments, by using a special feature of HTTP: the "multipart/related" content type. Requests that use multipart/related separate the content into different pieces, with each piece encoded in a different way. In practice, this means sending a JSON document plus binary attachments to Cloudant in a single, efficient, request.
### db.multipart.insert(doc, attachments, params, [callback])
Insert a `doc` together with `attachments` and optional `params`. If params is a string, its assumed as the intended document name. if params is an object, its passed as query string parameters and `docName` is checked for defining the document name. Refer to the [CouchDB multipart documentation](http://docs.couchdb.org/en/latest/api/document/common.html?highlight=multipart#creating-multiple-attachments) for more details.
`attachments` must be an array of objects with `name`, `data` and `content_type` properties. For example:
~~~ js
var fs = require('fs')
fs.readFile('rabbit.png', function(err, data) {
if (!err) {
var img = {name:'rabbit.png', content_type:'image/png', data:data}
var attachments = [img] // An array with one attachment, the rabbit image
alice.multipart.insert({ ears: 2 }, attachments, 'rabbit', function(err, body) {
if (!err)
console.log(body)
})
}
})
~~~
### db.multipart.get(doc_id, [params], [callback])
Get `doc_id` together with its attachments via `multipart/related` request with optional query string additions
`params`. Refer to the [doc](http://docs.couchdb.org/en/latest/api/document/common.html?highlight=multipart#efficient-multiple-attachments-retrieving) for more details. The multipart response body is a `Buffer`.
~~~ js
alice.multipart.get('rabbit', function(err, buffer) {
if (!err)
console.log(buffer.toString())
})
~~~
## Attachment Functions
### db.attachment.insert(doc_id, attname, att, contenttype, [params], [callback])
Inserts an attachment `attname` to `doc_id`. In most cases `params.rev` is required. Refer to the [doc](http://docs.couchdb.org/en/latest/api/document/common.html?highlight=multipart#retrieving-attachments-content) for more details.
~~~ js
var fs = require('fs')
fs.readFile('rabbit.png', function(err, data) {
if (!err) {
alice.attachment.insert('rabbit', 'rabbit.png', data, 'image/png',
{ rev: '12-150985a725ec88be471921a54ce91452' }, function(err, body) {
if (!err)
console.log(body)
})
}
})
~~~
If you use `null` as the data parameter, then this function returns a writable stream, to which you can pipe the attachment data.
~~~ js
var fs = require('fs')
var img_stream = fs.createReadStream('rabbit.png')
var attachment = alice.attachment.insert('new', 'rabbit.png', null, 'image/png')
img_stream.pipe(attachment)
~~~
### db.attachment.get(doc_id, attname, [params], [callback])
Get `doc_id`'s attachment `attname` with optional query string additions `params`.
~~~ js
var fs = require('fs')
alice.attachment.get('rabbit', 'rabbit.png', function(err, body) {
if (!err)
fs.writeFile('rabbit.png', body)
})
~~~
This function also returns a readable stream, which you may pipe to a writable stream.
Or using `pipe`:
~~~ js
var fs = require('fs')
var img_stream = fs.createWriteStream('rabbit.png')
var attachment = alice.attachment.get('rabbit', 'rabbit.png')
attachment.pipe(img_stream)
~~~
### db.attachment.destroy(docname, attname, [params], [callback])
Destroy attachment `attname` of `docname`'s revision `rev`.
~~~ js
var rev = '1-4701d73a08ce5c2f2983bf7c9ffd3320'
alice.attachment.destroy('rabbit', 'rabbit.png', {'rev':rev}, function(err, body) {
if (!err)
console.log(body)
})
~~~
## Design Document Functions
These functions are for working with views and design documents, including querying the database using map-reduce views, [Cloudant Search](#cloudant-search), and [Cloudant Query](#cloudant-query).
### db.view(designname, viewname, [params], [callback])
Call a view of the specified design with optional query string additions
`params`. If you're looking to filter the view results by key(s) pass an array of keys, e.g
`{ keys: ['key1', 'key2', 'key_n'] }`, as `params`.
~~~ js
alice.view('characters', 'crazy_ones', function(err, body) {
if (!err)
body.rows.forEach(function(doc) {
console.log(doc.value)
})
})
~~~
### db.search(designname, searchname, [params], [callback])
Call a view of the specified design with optional query string additions `params`. See the [Cloudant Search](#cloudant-search) section below for more details.
~~~ js
alice.search('characters', 'crazy_ones', { q: 'cat' }, function(err, doc) {
if (!err) {
console.log(doc);
}
});
~~~
## Cloudant Query

@@ -775,6 +362,6 @@

As with Nano, when working with a database (as opposed to the root server), run the `.use()` method.
As with Nano, when working with a database (as opposed to the root server), run the `.db.use()` method.
~~~ js
var db = cloudant.use('my_db')
var db = cloudant.db.use('my_db')
~~~

@@ -839,3 +426,3 @@

~~~ js
var db = cloudant.use('my_db')
var db = cloudant.db.use('my_db')
~~~

@@ -901,18 +488,16 @@

Cloudant({account:username, password:userpass}, function(err, cloudant) {
var cloudant = require('cloudant')({account:username, password:userpass});
// In this example, we authenticate using the same username/userpass as above.
// However, you can use a different combination to authenticate as other users
// in your database. This can be useful for using a less-privileged account.
cloudant.auth(username, userpass, function(err, body, headers) {
if (err)
return console.log('Failed to connect to Cloudant: ' + err.message)
return console.log('Error authenticating: ' + err.message)
// In this example, we authenticate using the same username/userpass as above.
// However, you can use a different combination to authenticate as other users
// in your database. This can be useful for using a less-privileged account.
cloudant.auth(username, userpass, function(err, body, headers) {
if (err)
return console.log('Error authenticating: ' + err.message)
console.log('Got cookie for %s: %s', username, headers['set-cookie'])
console.log('Got cookie for %s: %s', username, headers['set-cookie'])
// Store the authentication cookie for later.
cookies[username] = headers['set-cookie']
})
// Store the authentication cookie for later.
cookies[username] = headers['set-cookie']
})

@@ -925,18 +510,15 @@ ~~~

// Make a new connection with the cookie.
Cloudant({account:username, cookie:cookies[username]}, function(err, other_cloudant) {
if (err)
return console.log('Failed to connect to Cloudant: ' + err.message)
console.log('Connected to Cloudant using a cookie!')
var cloudant = require('cloudant')({account:username, cookie:cookies[username]});
var alice = other_cloudant.use('alice')
alice.insert({_id:"my_doc"}, function (err, body, headers) {
if (err)
return console.log('Failed to insert into alice database: ' + err.message)
var alice = other_cloudant.db.use('alice')
alice.insert({_id:"my_doc"}, function (err, body, headers) {
if (err)
return console.log('Failed to insert into alice database: ' + err.message)
// Change the cookie if Cloudant tells us to.
if (headers && headers['set-cookie'])
cookies[username] = headers['set-cookie']
})
// Change the cookie if Cloudant tells us to.
if (headers && headers['set-cookie'])
cookies[username] = headers['set-cookie']
})
~~~

@@ -947,5 +529,5 @@

~~~javascript
var Cloudant = require('Cloudant')({url: 'http://localhost:5984', cookie: 'AuthSession=' + auth});
var cloudant = require('cloudant')({url: 'http://localhost:5984', cookie: 'AuthSession=' + auth});
Cloudant.session(function(err, session) {
cloudant.session(function(err, session) {
if (err) {

@@ -960,2 +542,28 @@ return console.log('oh noes!')

## Advanced Features
### Debugging
If you wish to see further information about what the nodejs-cloudant library is doing, then its debugging output can be sent to the console by simply setting an environement variable:
export DEBUG=cloudant
# then run your Node.js application
Debug messages will be displayed to indicate each of the Cloudant-specific function calls. If you want to see all debug messages, including calls made by the underlying `nano` library, then simply change the environment variable to
export DEBUG=cloudant,nano
# then run your Node.js application
Similarly, if you only want `nano`-level debugging:
export DEBUG=nano
# then run your Node.js application
The environment variable can also be defined on the same line as the Node.js script you are running e.g.:
DEBUG="*" node myscript.js
### Advanced Configuration

@@ -966,3 +574,2 @@

~~~ js
var Cloudant = require('Cloudant')

@@ -975,6 +582,5 @@ // Use an HTTP proxy to connect to Cloudant.

}
var cloudant = require('cloudant')(opts);
// Now using the HTTP proxy...
Cloudant(options, function(err, cloudant) {
// Now using the HTTP proxy...
})
~~~

@@ -1005,10 +611,6 @@

var Cloudant = require('cloudant')
Cloudant({account:"me", password:"secret", requestDefaults:{agent:myagent}}, function(err, cloudant) {
// Using Cloudant with myagent...
})
var cloudant = require('cloudant')({account:"me", password:"secret", request_defaults:{agent:myagent}});
// Using Cloudant with myagent...
~~~
## Advanced Features
### Extending the Cloudant Library

@@ -1042,20 +644,3 @@

## tests
to run (and configure) the test suite simply:
~~~ sh
cd Cloudant
npm install
npm test
~~~
after adding a new test you can run it individually (with verbose output) using:
~~~ sh
Cloudant_env=testing node tests/doc/list.js list_doc_params
~~~
where `list_doc_params` is the test name.
## Development

@@ -1070,93 +655,107 @@

## Test Suite
### Test Suite
We use npm to handle running the test suite. To run the comprehensive test suite, just run `npm test`. However, to run only the Cloudant-specific bits, we have a custom `test-cloudant` script.
We use npm to handle running the test suite. To run the comprehensive test suite, just run `npm test`.
$ npm run test-cloudant
or after adding a new test you can run it individually (with verbose output) using:
> cloudant@5.10.1 test-cloudant /Users/jhs/src/cloudant/nodejs-cloudant
> env NOCK=on sh tests/cloudant/run-tests.sh
~~~ sh
npm test-verbose
~~~
Test against mocked local database
This runs against a local "mock" web server, called Nock. However the test suite can also run against a live Cloudant service. I have registered "nodejs.cloudant.com" for this purpose.
/tests/cloudant/auth.js
~~~ sh
$ npm test-live
~~~
✔ 5/5 cloudant:generate_api_key took 196ms
✔ 3/3 cloudant:set_permissions took 7ms
✔ 8/8 summary took 224ms
<...cut a bunch of test output...>
Get the password from Jason somehow, and set it a file called `.env` at the root of this project:
This runs against a local "mock" web server, called Nock. However the test suite can also run against a live Cloudant service. I have registered "nodejs.cloudant.com" for this purpose. To use it, run the `test-cloudant-live` script.
cloudant_password=thisisthepassword
$ npm run test-cloudant-live
### Using in Other Projects
> cloudant@5.10.1 test-cloudant-live /Users/jhs/src/cloudant/nodejs-cloudant
> sh tests/cloudant/run-tests.sh
If you work on this project plus another one, your best bet is to clone from GitHub and then *link* this project to your other one. With linking, your other project depends on this one; but instead of a proper install, npm basically symlinks this project into the right place.
Test against mocked local database
Go to this project and "link" it into the global namespace (sort of an "export").
/tests/cloudant/auth.js
$ cd cloudant
$ npm link
/Users/jhs/.nvm/v0.10.25/lib/node_modules/cloudant -> /Users/jhs/src/cloudant/nodejs-cloudant
✔ 5/5 cloudant:generate_api_key took 192ms
✔ 3/3 cloudant:set_permissions took 7ms
✔ 8/8 summary took 221ms
<...cut a bunch of test output...>
Go to your project and "link" it into there (sort of an "import").
Unfortunately you need to know the password.
$ cd ../my-project
$ npm link cloudant
/Users/jhs/src/my-project/node_modules/cloudant -> /Users/jhs/.nvm/v0.10.25/lib/node_modules/cloudant -> /Users/jhs/src/cloudant/nodejs-cloudant
$ npm run test-cloudant-live
Now your project has the dependency in place, however you can work on both of them in tandem.
> cloudant@5.10.1 test-cloudant-live /Users/jhs/src/cloudant/nodejs-cloudant
> sh tests/cloudant/run-tests.sh
### Security Note
Test against remote Cloudant database
No password configured for remote Cloudant database. Please run:
**DO NOT hard-code your password and commit it to Git**. Storing your password directly in your source code (even in old commits) is a serious security risk to your data. Whoever gains access to your software will now also have read, write, and delete access to your data. Think about GitHub security bugs, or contractors, or disgruntled employees, or lost laptops at a conference. If you check in your password, all of these situations become major liabilities. (Also, note that if you follow these instructions, the `export` command with your password will likely be in your `.bash_history` now, which is kind of bad. However, if you input a space before typing the command, it will not be stored in your history.)
npm config set cloudant_password "<your-password>"
Here is simple but complete example of working with data:
npm ERR! cloudant@5.10.1 test-cloudant-live: `sh tests/cloudant/run-tests.sh`
<...cut npm error messages...>
~~~ js
var Cloudant = require('Cloudant')
Get the password from Jason somehow, and set it as an npm variable.
var me = 'jhs' // Set this to your own account
var password = process.env.cloudant_password
# Note the leading space to keep this command out of the Bash history.
$ HISTCONTROL="$HISTCONTROL:ignorespace"
$ npm config set cloudant_password "ask jason for the password" # <- Not the real password
$ npm run test-cloudant-live
<...cut successful test suite run...>
Cloudant({account:me, password:password}, function(er, cloudant) {
if (er)
return console.log('Error connecting to Cloudant account %s: %s', me, er.message)
## Using in Other Projects
// Clean up the database we created previously.
cloudant.db.destroy('alice', function() {
// Create a new database.
cloudant.db.create('alice', function() {
// specify the database we are going to use
var alice = cloudant.db.use('alice')
// and insert a document in it
alice.insert({ crazy: true }, 'rabbit', function(err, body, header) {
if (err)
return console.log('[alice.insert] ', err.message)
If you work on this project plus another one, your best bet is to clone from GitHub and then *link* this project to your other one. With linking, your other project depends on this one; but instead of a proper install, npm basically symlinks this project into the right place.
console.log('you have inserted the rabbit.')
console.log(body)
})
})
})
})
~~~
Go to this project and "link" it into the global namespace (sort of an "export").
If you run this example, you will see:
$ cd cloudant
$ npm link
/Users/jhs/.nvm/v0.10.25/lib/node_modules/cloudant -> /Users/jhs/src/cloudant/nodejs-cloudant
you have inserted the rabbit.
{ ok: true,
id: 'rabbit',
rev: '1-6e4cb465d49c0368ac3946506d26335d' }
Go to your project and "link" it into there (sort of an "import").
## License
$ cd ../my-project
$ npm link cloudant
/Users/jhs/src/my-project/node_modules/cloudant -> /Users/jhs/.nvm/v0.10.25/lib/node_modules/cloudant -> /Users/jhs/src/cloudant/nodejs-cloudant
Copyright (c) 2015 IBM Cloudant, Inc. All rights reserved.
Now your project has the dependency in place, however you can work on both of them in tandem.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file
except in compliance with the License. You may obtain a copy of the License at
## License
http://www.apache.org/licenses/LICENSE-2.0
Copyright 2014 Cloudant, an IBM company.
Unless required by applicable law or agreed to in writing, software distributed under the
License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
either express or implied. See the License for the specific language governing permissions
and limitations under the License.
Licensed under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at
http://www.apache.org/licenses/LICENSE-2.0.html
## Reference
Unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or conditions of any kind, either express or implied. See the license for the specific language governing permissions and limitations under the license.
[nano]: https://github.com/dscape/nano
[query]: http://docs.cloudant.com/api/cloudant-query.html
[search]: http://docs.cloudant.com/api/search.html
[auth]: http://docs.cloudant.com/api/authz.html
[issues]: https://github.com/cloudant/nodejs-cloudant/issues
[follow]: https://github.com/iriscouch/follow
[request]: https://github.com/mikeal/request
* [Nano Library](https://github.com/dscape/nano)
* [Cloudant Documentation](https://docs.cloudant.com/)
* [Cloudant Query](https://docs.cloudant.com/cloudant_query.html)
* [Cloudant Search](https://docs.cloudant.com/search.html)
* [Authentication](https://docs.cloudant.com/authentication.html)
* [Authorization](https://docs.cloudant.com/authorization.html)
* [CORS](https://docs.cloudant.com/cors.html)
* [Issues](https://github.com/cloudant/nodejs-cloudant/issues)
* [Follow library](https://github.com/iriscouch/follow)

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc