Connection: Extend with the .pquery() method

Fix up related .pquery() stuff in PoolPlus

Gruntfile.js

@@ -79,7 +79,7 @@ module.exports = function(grunt) {
           'sort-by': ['order'],
           template: require('fs').readFileSync('jsdoc2md/README.hbs', 'utf8'),
         },
-        src: ['lib/MySQLPlus.js', 'lib/PoolPlus.js', 'lib/MySQLTable.js'],
+        src: ['lib/MySQLPlus.js', 'lib/PoolPlus.js', 'lib/Connection.js', 'lib/MySQLTable.js'],
         dest: 'README.md',
       },
     },

README.md

@@ -21,6 +21,7 @@ This module extends the popular [`mysql`](https://www.npmjs.com/package/mysql) m
     + [mysql-plus](#module_mysql-plus)
   + Classes
     + [PoolPlus](#PoolPlus)
+    + [Connection](#Connection)
     + [MySQLTable](#MySQLTable)
   + Info
     + [Migration Strategies](#migration-strategies)
@@ -120,6 +121,11 @@ db.sync((err) => {
 <dt><a href="#PoolPlus">PoolPlus</a> ⇐ <code>Pool</code></dt>
 <dd><p>A class that extends the <code>mysql</code> module&#39;s <code>Pool</code> class with the ability to define tables.</p>
 </dd>
+<dt><a href="#Connection">Connection</a></dt>
+<dd><p>The <code>mysql</code> module&#39;s <code>Connection</code> class extended with one extra method. Returned by
+<a href="https://github.com/mysqljs/mysql#establishing-connections"><code>mysql.createConnection()</code></a>,
+and <a href="https://github.com/mysqljs/mysql#pooling-connections"><code>pool.getConnection()</code></a>.</p>
+</dd>
 <dt><a href="#MySQLTable">MySQLTable</a></dt>
 <dd><p>A class that provides convenient methods for performing queries.</p>
 </dd>
@@ -336,7 +342,7 @@ pool.sync(function(err) {
 <a name="PoolPlus+pquery"></a>
 
 ### poolPlus.pquery(sql, [values], [cb]) ⇒ <code>Promise</code>
-The same `query` method as on the original mysql pool except when not passed a
+The same as the `query` method on the original mysql Pool except when not passed a
 callback it returns a promise that resolves with the results of the query.
 
 
@@ -349,7 +355,7 @@ callback it returns a promise that resolves with the results of the query.
 **Returns**: <code>?Promise</code> - If the `cb` parameter is omitted, a promise that will resolve with the results
     of the query is returned.  
 **See**: [https://github.com/mysqljs/mysql#performing-queries](https://github.com/mysqljs/mysql#performing-queries)  
-**Example**: Promise example
+**Example**:
 ```js
 pool.pquery('SELECT * FROM `books` WHERE `author` = "David"')
   .then((results) => {
@@ -360,13 +366,44 @@ pool.pquery('SELECT * FROM `books` WHERE `author` = "David"')
   });
 ```
 
-**Example**: Callback example
+
+---
+
+<a name="Connection"></a>
+
+## Connection
+The `mysql` module's `Connection` class extended with one extra method. Returned by
+[`mysql.createConnection()`](https://github.com/mysqljs/mysql#establishing-connections),
+and [`pool.getConnection()`](https://github.com/mysqljs/mysql#pooling-connections).
+
+
+---
+
+<a name="Connection+pquery"></a>
+
+### connection.pquery(sql, [values], [cb]) ⇒ <code>Promise</code>
+The same as the `query` method except when not passed a callback it returns
+a promise that resolves with the results of the query.
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| sql | <code>string</code> &#124; <code>Object</code> | An SqlString or options object. |
+| [values] | <code>Array</code> | Values to replace placeholders in the SqlString. |
+| [cb] | <code>[queryCallback](#module_mysql-plus..queryCallback)</code> | An optional callback that gets called with     the results of the query. |
+
+**Returns**: <code>?Promise</code> - If the `cb` parameter is omitted, a promise that will resolve with the results
+    of the query is returned.  
+**See**: [https://github.com/mysqljs/mysql#performing-queries](https://github.com/mysqljs/mysql#performing-queries)  
+**Example**:
 ```js
-pool.pquery('SELECT * FROM `books` WHERE `author` = "David"', (error, results, fields) => {
-  // error will be an Error if one occurred during the query
-  // results will contain the results of the query
-  // fields will contain information about the returned results fields (if any)
-});
+connection.pquery('SELECT * FROM `books` WHERE `author` = "David"')
+  .then((results) => {
+    // results will contain the results of the query
+  })
+  .catch((error) => {
+    // error will be the Error that occurred during the query
+  });
 ```
 
 

jsdoc2md/README.hbs

@@ -21,6 +21,7 @@ This module extends the popular [`mysql`](https://www.npmjs.com/package/mysql) m
     + [mysql-plus](#module_mysql-plus)
   + Classes
     + [PoolPlus](#PoolPlus)
+    + [Connection](#Connection)
     + [MySQLTable](#MySQLTable)
   + Info
     + [Migration Strategies](#migration-strategies)

lib/Connection.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const Connection = require('mysql/lib/Connection');
+
+/**
+ * @class Connection
+ * @classdesc The `mysql` module's `Connection` class extended with one extra method. Returned by
+ * {@link https://github.com/mysqljs/mysql#establishing-connections|`mysql.createConnection()`},
+ * and {@link https://github.com/mysqljs/mysql#pooling-connections|`pool.getConnection()`}.
+ */
+
+ /**
+  * The same as the `query` method except when not passed a callback it returns
+  * a promise that resolves with the results of the query.
+  *
+  * @param {string|Object} sql - An SqlString or options object.
+  * @param {Array} [values] - Values to replace placeholders in the SqlString.
+  * @param {module:mysql-plus~queryCallback} [cb] - An optional callback that gets called with
+  *     the results of the query.
+  * @return {?Promise} If the `cb` parameter is omitted, a promise that will resolve with the results
+  *     of the query is returned.
+  * @see {@link https://github.com/mysqljs/mysql#performing-queries}
+  *
+  * @example
+  * connection.pquery('SELECT * FROM `books` WHERE `author` = "David"')
+  *   .then((results) => {
+  *     // results will contain the results of the query
+  *   })
+  *   .catch((error) => {
+  *     // error will be the Error that occurred during the query
+  *   });
+  */
+Connection.prototype.pquery = function pquery(sql, values, cb) {
+  if (typeof (cb || values || sql) === 'function') {
+    return this.query(sql, values, cb);
+  }
+
+  return new Promise((resolve, reject) => {
+    this.query(sql, values, (error, results) => {
+      if (error) {
+        reject(error);
+      } else {
+        resolve(results);
+      }
+    });
+  });
+};

lib/MySQLPlus.js

@@ -6,6 +6,8 @@ const PoolPlus = require('./PoolPlus');
 const mysql = require('mysql');
 const util = require('util');
 
+require('./Connection'); // Extends mysql Connection
+
 /**
  * This module.
  * @module mysql-plus

lib/PoolPlus.js

@@ -134,7 +134,7 @@ class PoolPlus extends Pool {
   }
 
   /**
-   * The same `query` method as on the original mysql pool except when not passed a
+   * The same as the `query` method on the original mysql Pool except when not passed a
    * callback it returns a promise that resolves with the results of the query.
    *
    * @param {string|Object} sql - An SqlString or options object.
@@ -145,21 +145,14 @@ class PoolPlus extends Pool {
    *     of the query is returned.
    * @see {@link https://github.com/mysqljs/mysql#performing-queries}
    *
-   * @example <caption>Promise example</caption>
+   * @example
    * pool.pquery('SELECT * FROM `books` WHERE `author` = "David"')
    *   .then((results) => {
    *     // results will contain the results of the query
    *   })
    *   .catch((error) => {
    *     // error will be the Error that occurred during the query
    *   });
-   *
-   * @example <caption>Callback example</caption>
-   * pool.pquery('SELECT * FROM `books` WHERE `author` = "David"', (error, results, fields) => {
-   *   // error will be an Error if one occurred during the query
-   *   // results will contain the results of the query
-   *   // fields will contain information about the returned results fields (if any)
-   * });
    */
   pquery(sql, values, cb) {
     if (typeof (cb || values || sql) === 'function') {

test/unit/Connection.test.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const config = require('../config');
+const mysql = require('mysql');
+const sinon = require('sinon');
+
+describe('Connection', () => {
+
+  const connection = mysql.createConnection(config);
+
+  describe('#pquery()', () => {
+
+    it('should behave like #query() when passed a callback', () => {
+      const expectedSql = 'SELECT 1 as ??';
+      const expectedValues = ['solution'];
+      function expectedCb() { /* no-op */ }
+
+      sinon.stub(connection, 'query', function(sql, values, cb) {
+        sql.should.equal(expectedSql);
+        values.should.equal(expectedValues);
+        cb.should.equal(expectedCb);
+      });
+
+      connection.pquery(expectedSql, expectedValues, expectedCb);
+      connection.query.should.be.called();
+
+      connection.query.restore();
+    });
+
+    it('should return a working Promise', done => {
+      connection.pquery('SELECT "a" as solution')
+        .then(results => {
+          results.length.should.equal(1);
+          results[0].solution.should.equal('a');
+
+          connection.pquery('SELECT "a" as ??', ['solution'])
+            .then(results2 => {
+              results2.length.should.equal(1);
+              results2[0].solution.should.equal('a');
+
+              connection.pquery('SELECT a as solution')
+                .then(() => done(new Error()))
+                .catch(() => done());
+            })
+            .catch(done);
+        })
+        .catch(done);
+    });
+
+  });
+
+});

test/unit/PoolPlus.test.js

@@ -218,16 +218,19 @@ describe('PoolPlus', () => {
         .then(results => {
           results.length.should.equal(1);
           results[0].solution.should.equal('a');
+
+          pool.pquery('SELECT "a" as ??', ['solution'])
+            .then(results2 => {
+              results2.length.should.equal(1);
+              results2[0].solution.should.equal('a');
+
+              pool.pquery('SELECT a as solution')
+                .then(() => done(new Error()))
+                .catch(() => done());
+            })
+            .catch(done);
         })
-        .catch(done)
-        .then(() => pool.pquery('SELECT "a" as ??'), ['solution'])
-        .then(results => {
-          results.length.should.equal(1);
-          results[0].solution.should.equal('a');
-        })
-        .then(() => pool.pquery('SELECT a as solution'))
-        .then(() => done(new Error()))
-        .catch(() => done());
+        .catch(done);
     });
 
   });