Upgraded to Nano 8.x

Updated stream return test to use stream event instead of callback.
Also fixed mock to use correct endpoint.

Author: ricellis

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,43 @@ 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

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);
   });