MySQLTable: Allow .insert() to accept a string as the first parameter

Author: nwoltman

README.md

@@ -523,7 +523,7 @@ A class that provides convenient methods for performing queries.
     * [.pool](#MySQLTable+pool) : <code>[PoolPlus](#PoolPlus)</code>
     * [.trxn](#MySQLTable+trxn) : <code>?[Connection](#Connection)</code>
     * [.select(columns, [sqlString], [values], [cb])](#MySQLTable+select) ⇒ <code>Promise</code>
-    * [.insert(data, [sqlString], [values], [cb])](#MySQLTable+insert) ⇒ <code>Promise</code>
+    * [.insert([data], [sqlString], [values], [cb])](#MySQLTable+insert) ⇒ <code>Promise</code>
     * [.update([data], [sqlString], [values], [cb])](#MySQLTable+update) ⇒ <code>Promise</code>
     * [.delete([sqlString], [values], [cb])](#MySQLTable+delete) ⇒ <code>Promise</code>
     * [.query()](#MySQLTable+query) ⇒ <code>Promise</code>
@@ -631,14 +631,17 @@ userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000', (err, ro
 
 <a name="MySQLTable+insert"></a>
 
-### mySQLTable.insert(data, [sqlString], [values], [cb]) ⇒ <code>Promise</code>
+### mySQLTable.insert([data], [sqlString], [values], [cb]) ⇒ <code>Promise</code>
 Inserts data into a new row in the table.
 
+__Note:__ The `data` and `sqlString` arguments are individually
+optional but at least one of them must be specified.
+
 
 | Param | Type | Description |
 |:--- |:--- |:--- |
-| data | <code>Object</code> &#124; <code>Array</code> | An object of (column name)-(data value) pairs or     an array containing either 1) an array of arrays of data values or 2) an array     of column names and the data array from 1). |
-| [sqlString] | <code>string</code> | SQL to be appended to the query.<br>This would only be used to add     an `ON DUPLICATE KEY UPDATE` clause. |
+| [data] | <code>Object</code> &#124; <code>Array</code> | An object of (column name)-(data value) pairs or     an array containing either 1) an array of arrays of data values or 2) an array     of column names and the data array from 1). |
+| [sqlString] | <code>string</code> | SQL to be appended to the query. If `data` is provided, it is appended     directly after the formatted data, otherwise it is appended after `"INSERT INTO tableName"`. |
 | [values] | <code>Array</code> | Values to replace the placeholders in `sqlString`. |
 | [cb] | <code>[queryCallback](#module_mysql-plus..queryCallback)</code> | A callback that gets called with the results of the query. |
 

lib/MySQLTable.js

@@ -97,11 +97,14 @@ class MySQLTable {
   /**
    * Inserts data into a new row in the table.
    *
-   * @param {Object|Array} data - An object of (column name)-(data value) pairs or
+   * __Note:__ The `data` and `sqlString` arguments are individually
+   * optional but at least one of them must be specified.
+   *
+   * @param {Object|Array} [data] - An object of (column name)-(data value) pairs or
    *     an array containing either 1) an array of arrays of data values or 2) an array
    *     of column names and the data array from 1).
-   * @param {string} [sqlString] - SQL to be appended to the query.<br>This would only be used to add
-   *     an `ON DUPLICATE KEY UPDATE` clause.
+   * @param {string} [sqlString] - SQL to be appended to the query. If `data` is provided, it is appended
+   *     directly after the formatted data, otherwise it is appended after `"INSERT INTO tableName"`.
    * @param {Array} [values] - Values to replace the placeholders in `sqlString`.
    * @param {module:mysql-plus~queryCallback} [cb] - A callback that gets called with the results of the query.
    * @returns {?Promise} If the `cb` parameter is omitted, a promise that will resolve with the results
@@ -143,6 +146,14 @@ class MySQLTable {
    * });
    */
   insert(data, sqlString, values, cb) {
+    if (typeof data === 'string') {
+      return this._db.pquery(
+        'INSERT INTO ' + this._escapedName + ' ' + data,
+        sqlString,
+        values
+      );
+    }
+
     if (cb) {
       sqlString = this._db.format(sqlString, values);
     } else if (values) {

test/unit/MySQLTable.test.js

@@ -281,6 +281,19 @@ describe('MySQLTable', () => {
         });
       });
 
+      it('should allow the first parameter to be a string', done => {
+        testTable.insert("(`email`) VALUES ('six@email.com'), ('seven@email.com')", (err, result1) => {
+          if (err) throw err;
+          result1.affectedRows.should.equal(2);
+
+          testTable.insert('SET ?? = ?', ['email', 'eight@email.com'], (err, result2) => {
+            if (err) throw err;
+            result2.affectedRows.should.equal(1);
+            done();
+          });
+        });
+      });
+
     });
 
 
@@ -342,6 +355,16 @@ describe('MySQLTable', () => {
           });
       });
 
+      it('should allow the first parameter to be a string', () => {
+        return Promise.all([
+          testTable.insert("(`email`) VALUES ('six@email.com'), ('seven@email.com')"),
+          testTable.insert('SET ?? = ?', ['email', 'eight@email.com']),
+        ]).then(results => {
+          results[0].affectedRows.should.equal(2);
+          results[1].affectedRows.should.equal(1);
+        });
+      });
+
     });
 
   });