[email protected] release (#2059)

* Fix one unintentional possible breaking change & update readme

* Update changelog more

* Update CHANGELOG.md

Co-Authored-By: Charmander <[email protected]>

Co-authored-by: Charmander <[email protected]>

CHANGELOG.md

@@ -4,6 +4,12 @@ For richer information consult the commit log on github with referenced pull req
 
 We do not include break-fix version release in this file.
 
+### [email protected]
+
+- [Rewrote stream internals](https://github.com/brianc/node-postgres/pull/2051) to better conform to node stream semantics.  This should make pg-query-stream much better at respecting [highWaterMark](https://nodejs.org/api/stream.html#stream_new_stream_readable_options) and getting rid of some edge case bugs when using pg-query-stream as an async iterator.  Due to the size and nature of this change (effectively a full re-write) it's safest to bump the semver major here, though almost all tests remain untouched and still passing, which brings us to a breaking change to the API....
+- Changed `stream.close` to `stream.destroy` which is the [official](https://nodejs.org/api/stream.html#stream_readable_destroy_error) way to terminate a readable stream.  This is a __breaking change__ if you rely on the `stream.close` method on pg-query-stream...though should be just a find/replace type operation to upgrade as the semantics remain very similar (not exactly the same, since internals are rewritten, but more in line with how streams are "supposed" to behave).
+- Unified the `config.batchSize` and `config.highWaterMark` to both do the same thing: control how many rows are buffered in memory.  The `ReadableStream` will manage exactly how many rows are requested from the cursor at a time.  This should give better out of the box performance and help with efficient async interation.
+
 ### [email protected]
 
 - Add support for `idle_in_transaction_session_timeout` [option](https://github.com/brianc/node-postgres/pull/2049).

packages/pg-query-stream/index.js

@@ -3,9 +3,9 @@ const Cursor = require('pg-cursor')
 
 class PgQueryStream extends Readable {
   constructor(text, values, config = {}) {
-    const { batchSize = 100 } = config;
+    const { batchSize, highWaterMark = 100 } = config;
     // https://nodejs.org/api/stream.html#stream_new_stream_readable_options
-    super({ objectMode: true, emitClose: true, autoDestroy: true, highWaterMark: batchSize })
+    super({ objectMode: true, emitClose: true, autoDestroy: true, highWaterMark: batchSize || highWaterMark })
     this.cursor = new Cursor(text, values, config)
 
     // delegate Submittable callbacks to cursor

packages/pg-query-stream/test/config.js

@@ -1,8 +1,26 @@
 var assert = require('assert')
 var QueryStream = require('../')
 
-var stream = new QueryStream('SELECT NOW()', [], {
-  batchSize: 88
-})
+describe('stream config options', () => {
+  // this is mostly for backwards compatability.
+  it('sets readable.highWaterMark based on batch size', () => {
+    var stream = new QueryStream('SELECT NOW()', [], {
+      batchSize: 88
+    })
+    assert.equal(stream._readableState.highWaterMark, 88)
+  })
+
+  it('sets readable.highWaterMark based on highWaterMark config', () => {
+    var stream = new QueryStream('SELECT NOW()', [], {
+      highWaterMark: 88
+    })
+
+    assert.equal(stream._readableState.highWaterMark, 88)
+  })
 
-assert.equal(stream._readableState.highWaterMark, 88)
+  it('defaults to 100 for highWaterMark', () => {
+    var stream = new QueryStream('SELECT NOW()', [])
+
+    assert.equal(stream._readableState.highWaterMark, 100)
+  })
+})