Comparing version 1.0.0 to 1.1.0
@@ -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 |
208
LICENSE.md
@@ -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" | ||
] | ||
} | ||
} |
833
README.md
@@ -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
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Network access
Supply chain riskThis module accesses the network.
Found 1 instance in 1 package
Environment variable access
Supply chain riskPackage accesses environment variables, which may be a sign of credential stuffing or data theft.
Found 2 instances in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
Dynamic require
Supply chain riskDynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.
Found 1 instance in 1 package
Environment variable access
Supply chain riskPackage accesses environment variables, which may be a sign of credential stuffing or data theft.
Found 2 instances in 1 package
Filesystem access
Supply chain riskAccesses the file system, and could potentially read sensitive data.
Found 1 instance in 1 package
2
4
4
73041
8
790
736
2
+ Addednano@6.1.3
+ Addednano@6.1.3(transitive)
+ Addedpsl@1.10.0(transitive)
- Removederrs@^0.3.0
- Removedfollow@^0.11.4
- Removedrequest@^2.53.0
- Removedunderscore@^1.7.0
- Removedpsl@1.13.0(transitive)
Updateddebug@^2.2.0