code refactoring, documentation updates, dependency updates.

lib/database.js

@@ -352,15 +352,17 @@ function Database(cn, dc, options, config) {
          * @description
          * Custom data streaming, with the help of $[pg-query-stream].
          *
-         * This method doesn't work when initialization option `pgNative` is set,
-         * because $[pg-query-stream] doesn't support $[Native Bindings].
+         * This method doesn't work with the $[Native Bindings], and if option `pgNative`
+         * is set, it will reject with `Streaming doesn't work with native bindings.`
          *
-         * And if you call this method while using option `pgNative`, it will throw {@link external:Error Error} =
-         * `Streaming doesn't work with native bindings.`
+         * @param {QueryStream} qs
+         * Stream object of type $[QueryStream].
+         *
+         * @param {streamInitCB} initCB
+         * Stream initialization callback.
+         *
+         * It is invoked with the same `this` context as the calling method.
          *
-         * @param {QueryStream} qs - stream object of type $[QueryStream].
-         * @param {Function} init - stream initialization callback, with
-         * the same `this` context as the calling method.
          * @returns {external:Promise} Result of the streaming operation.
          *
          * Once the streaming has finished successfully, the method resolves with
@@ -610,3 +612,37 @@ module.exports = function (config) {
     npm.task = npm.task || $npm.task(config);
     return Database;
 };
+
+/**
+ * @callback streamInitCB
+ * @description
+ * Stream initialization callback, used by {@link Database.stream}.
+ *
+ * @param {external:Stream} stream
+ * Stream object to initialize streaming.
+ *
+ * @example
+ * var QueryStream = require('pg-query-stream');
+ * var JSONStream = require('JSONStream');
+ *
+ * // you can also use pgp.as.format(query, values, options)
+ * // to format queries properly, via pg-promise;
+ * var qs = new QueryStream('select * from users');
+ *
+ * db.stream(qs, function (stream) {
+ *         // initiate streaming into the console:
+ *         stream.pipe(JSONStream.stringify()).pipe(process.stdout);
+ *     })
+ *     .then(function (data) {
+ *         console.log("Total rows processed:", data.processed,
+ *           "Duration in milliseconds:", data.duration);
+ *     })
+ *     .catch(function (error) {
+ *         // error;
+ *     });
+ */
+
+/**
+ * @external Stream
+ * @see https://nodejs.org/api/stream.html
+ */

lib/stream.js

@@ -8,14 +8,14 @@ var $npm = {
 ////////////////////////////////////////////
 // Streams query data into any destination,
 // with the help of pg-query-stream library.
-function $stream(ctx, qs, init, config) {
+function $stream(ctx, qs, initCB, config) {
 
     var $p = config.promise;
 
     // istanbul ignore next:
-    // we do not cover code specific to native bindings
+    // we do not provide code coverage for the Native Bindings specifics
     if (ctx.options && ctx.options.pgNative) {
-        throw new Error("Streaming doesn't work with native bindings.");
+        return $p.reject("Streaming doesn't work with native bindings.");
     }
     if (!$npm.utils.isObject(qs, ['state', '_reading'])) {
         // stream object wasn't passed in correctly;
@@ -25,8 +25,8 @@ function $stream(ctx, qs, init, config) {
         // stream object is in the wrong state;
         return $p.reject("Invalid stream state.");
     }
-    if (typeof init !== 'function') {
-        // parameter `init` must be passed as the initialization callback;
+    if (typeof initCB !== 'function') {
+        // parameter `initCB` must be passed as the initialization callback;
         return $p.reject("Invalid or missing stream initialization callback.");
     }
     var errorMsg = $npm.events.query(ctx.options, getContext());
@@ -55,12 +55,12 @@ function $stream(ctx, qs, init, config) {
             });
         };
         start = Date.now();
-        init.call(this, stream); // the stream must be initialized during the call;
+        initCB.call(this, stream); // the stream must be initialized during the call;
     } catch (err) {
         errorMsg = err;
     }
     if (errorMsg) {
-        // error thrown by init();
+        // error thrown by initCB();
         stream._fetch = fetch;
         $npm.events.error(ctx.options, errorMsg, getContext());
         return $p.reject(errorMsg);

lib/task.js

@@ -13,22 +13,15 @@ var $npm = {
  * @constructor Task
  * @extends Database
  * @description
- * Extends {@link Database} for an automatic connection session, with methods for executing
- * multiple database queries. The type isn't available directly, it can only be created via
- * methods {@link Database.task} and {@link Database.tx}.
+ * Extends {@link Database} for an automatic connection session, with methods for executing multiple database queries.
+ * The type isn't available directly, it can only be created via methods {@link Database.task} and {@link Database.tx}.
  *
- * All query methods of this library automatically manage their database connection:
- * 1. allocate a new connection from the connection pool
- * 2. execute the query
- * 3. release the connection back to the pool
- *
- * When executing more than one request at a time, such approach is no longer prudent.
- * One should allocate and release the connection only once, while executing all the
- * required queries within the same connection session. More importantly, a transaction
+ * When executing more than one request at a time, one should allocate and release the connection only once,
+ * while executing all the required queries within the same connection session. More importantly, a transaction
  * can only work within a single connection.
  *
- * This class provides an interface for tasks and transactions to implement a connection
- * session, during which you can execute multiple queries against the same connection.
+ * This class provides an interface for tasks/transactions to implement a connection session, during which you can
+ * execute multiple queries against the same connection that's released automatically when the task/transaction is finished.
  *
  * @example
  * db.task(function (t) {

package.json

@@ -39,7 +39,7 @@
     "npm": ">=1.4"
   },
   "dependencies": {
-    "pg": "^4.5.3",
+    "pg": "^4.5.5",
     "spex": "^0.4.2",
     "pg-minify": "^0.3.2"
   },