Merge pull request #363 from cloudant/nano8

Nano8

Author: ricellis

.gitignore

@@ -4,3 +4,4 @@
 node_modules/
 coverage/
 /.env
+test/typescript/cloudant.js

CHANGES.md

@@ -1,6 +1,13 @@
 # UNRELEASED
 - [NEW] Added option for client to authenticate with IAM token server.
 - [FIXED] Case where `.resume()` was called on an undefined response.
+- [BREAKING CHANGE] Nano 7 accepted a callback to the `*AsStream` functions, but
+  the correct behaviour when using the `request` object from `*AsStream`
+  functions is to use event handlers. Users of the `*AsStream` functions should
+  ensure they are using event handlers not callbacks before moving to this
+  version.
+- [UPGRADED] Apache CouchDB Nano to a minimum of version 8 for `*AsStream`
+  function fixes.
 
 # 3.0.2 (2019-01-07)
 - [FIXED] Remove unnecessary `@types/nano` dependancy.

README.md

@@ -980,6 +980,25 @@ getpandarev('4-2e6cdc4c7e26b745c2881a24e0eeece2', function(err, body) {
 })
 ~~~
 
+### Pipes
+
+When using the `*AsStream` functions instead of a `Promise` a `request` object
+is returned that may be piped as a stream. For example:
+
+```js
+cloudant.db.listAsStream()
+  .on('error', function(error) {
+    console.log('ERROR');
+  })
+  .on('end', function(error) {
+    console.log('DONE');
+  })
+  .pipe(process.stdout);
+```
+
+Note that there are no callbacks when using these streams and event listeners
+must be used instead.
+
 ## Development and Contribution
 
 This is an open-source library, published under the Apache 2.0 license. We very

api-migration.md

@@ -5,6 +5,65 @@ has breaking API changes. Each section covers migrating from one major version
 to another. The section titles state the versions between which the change was
 made.
 
+## 3.x → 4.x
+
+[Apache CouchDB Nano](https://www.npmjs.com/package/nano) version 7 used in
+`nodejs-cloudant` 3.x had an API error that allowed specifying a callback when
+using `*AsStream` functions. Using a callback with the `request` object caused a
+`Buffer` allocation attempt for the entire response size, which would fail for
+large streams. The correct approach is to use event listeners on the response
+stream.
+
+To prevent incorrect usage the option of providing a callback was removed from
+the Apache CouchDB Nano API in version 8 and consequently nodejs-cloudant 4.x.
+Consumers of the `*AsStream` functions using callbacks need to adapt their code
+to use event listeners instead. For example:
+
+```js
+cloudant.db.listAsStream(function(error, response, body) {
+  if (error) {
+    console.log('ERROR');
+  } else {
+    console.log('DONE');
+  }
+}).pipe(process.stdout);
+```
+
+may be replaced with:
+
+```js
+cloudant.db.listAsStream()
+  .on('error', function(error) {
+    console.log('ERROR');
+  })
+  .on('end', function(error) {
+    console.log('DONE');
+  })
+  .pipe(process.stdout);
+```
+
+## 2.x → 3.x
+
+We've upgraded our [nano](https://www.npmjs.com/package/nano) dependency. This
+means all return types are now a `Promise` (except for the `...AsStream`
+functions). The `promise` plugin is no longer required. It is silently ignored
+when specified in the client configuration.
+
+Example:
+```js
+var cloudant = new Cloudant({ url: myUrl, plugins: [ 'retry' ] });
+
+// Lists all the databases.
+cloudant.db.list().then((dbs) => {
+  dbs.forEach((db) => {
+    console.log(db);
+  });
+}).catch((err) => { console.log(err); });
+```
+
+Nano is responsible for resolving or rejecting all promises. Any errors thrown
+are created from within Nano. The old `CloudantError` type no longer exists.
+
 ## 1.x → 2.x
 
 This change introduces multiple plugin support by using a request interceptor
@@ -49,25 +108,3 @@ var cloudant = new Cloudant({ url: myUrl, plugins: [] });
 
 Finally, the `promise` plugin now throws a `CloudantError` (extended from
 `Error`) rather than a `string` which was considered bad practice.
-
-## 2.x → 3.x
-
-We've upgraded our [nano](https://www.npmjs.com/package/nano) dependency. This
-means all return types are now a `Promise` (except for the `...AsStream`
-functions). The `promise` plugin is no longer required. It is silently ignored
-when specified in the client configuration.
-
-Example:
-```js
-var cloudant = new Cloudant({ url: myUrl, plugins: [ 'retry' ] });
-
-// Lists all the databases.
-cloudant.db.list().then((dbs) => {
-  dbs.forEach((db) => {
-    console.log(db);
-  });
-}).catch((err) => { console.log(err); });
-```
-
-Nano is responsible for resolving or rejecting all promises. Any errors thrown
-are created from within Nano. The old `CloudantError` type no longer exists.

package-lock.json

@@ -28,7 +28,7 @@
     "concat-stream": "^1.6.0",
     "debug": "^3.1.0",
     "lockfile": "1.0.3",
-    "nano": "^7.1.1",
+    "nano": "^8.0.0",
     "request": "^2.81.0",
     "tmp": "0.0.33"
   },

package.json

@@ -113,12 +113,13 @@ describe('retry-on-429 plugin #db', function() {
     setTimeout(done, 1000);
   });
 
-  it('should return a stream', function(done) {
+  it.only('should return a stream', function(done) {
     var mocks = nock(SERVER)
-        .get('/' + dbName).reply(200, { ok: true });
+        .get('/_all_dbs').reply(200, ['_replicator','_users']);
     var cloudant = Cloudant({plugins: 'retry', url: SERVER, username: ME, password: PASSWORD});
-    var dbs = cloudant.db.listAsStream(function() {
-      done();
+    var dbs = cloudant.db.listAsStream()
+    .once('end', function() {
+      done()
     });
     assert.equal(dbs instanceof PassThroughDuplex, true);
   });