MySQLTable: Implement new .insertIfNotExists() method

Author: nwoltman

README.md

@@ -522,6 +522,7 @@ A class that provides convenient methods for performing queries.
     * [.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>
+    * [.insertIfNotExists(data, keyColumns, [cb])](#MySQLTable+insertIfNotExists) ⇒ <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>
@@ -710,6 +711,65 @@ userTable.insert([['email', 'name'], users])
 ```
 
 
+---
+
+<a name="MySQLTable+insertIfNotExists"></a>
+
+### mySQLTable.insertIfNotExists(data, keyColumns, [cb]) ⇒ <code>Promise</code>
+Inserts a new row into the table if there are no existing rows in
+the table that have the same values for the specified columns.
+
+This is useful because if the row is not inserted, the table's
+`AUTO_INCREMENT` value is not increased (unlike when an insert
+fails because of a unique key constraint).
+
+
+| Param | Type | Description |
+|:--- |:--- |:--- |
+| data | <code>Object</code> | An object mapping column names to data values to insert.     The values are escaped by default. If you don't want a value to be escaped,     wrap it in a "raw" object (see the last example below). |
+| keyColumns | <code>Array.&lt;string&gt;</code> | The names of columns in the `data` object.     If there is already a row in the table with the same values for these     columns as the values being inserted, the data will not be inserted. |
+| [cb] | <code>[queryCallback](#module_mysql-plus..queryCallback)</code> | A 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.
+
+**Example**: Insert a new user if a user with the same email does not exist
+```js
+userTable.insertIfNotExists({email: 'email@example.com', name: 'John Doe'}, ['email'])
+  .then(result => result.affectedRows);
+  // 0 - If there was a row with `email` = 'email@example.com' (row not inserted)
+  // 1 - If there wasn't (row was inserted)
+
+// INSERT INTO `user` (`email`, `name`)
+// SELECT 'email@example.com', 'John Doe'
+// FROM DUAL WHERE NOT EXISTS (
+//   SELECT 1 FROM `user`
+//   WHERE `email` = 'email@example.com' LIMIT 1
+// );
+```
+
+**Example**: Insert without escaping some values
+```js
+const data = {
+  placeId: 'ChIJK2f-X1bxK4gRkB0jxyh7AwU',
+  type: 'city',
+  // IMPORTANT: You must manually escape any user-input values used in the "raw" object.
+  location: {__raw: 'POINT(-80.5204096, 43.4642578)'},
+};
+placeTable.insertIfNotExists(data, ['placeId', 'type'])
+  .then(result => result.affectedRows);
+  // 0 - If there was a row with the same `placeId` and `type` (row not inserted)
+  // 1 - If there wasn't (row was inserted)
+
+// INSERT INTO `place` (`placeId`, `type`, `location`)
+// SELECT 'ChIJK2f-X1bxK4gRkB0jxyh7AwU', 'city', POINT(-80.5204096, 43.4642578)
+// FROM DUAL WHERE NOT EXISTS (
+//   SELECT 1 FROM `place`
+//   WHERE `placeId` = 'ChIJK2f-X1bxK4gRkB0jxyh7AwU' AND `type` = 'city' LIMIT 1
+// );
+```
+
+
 ---
 
 <a name="MySQLTable+update"></a>

lib/MySQLTable.js

@@ -200,6 +200,80 @@ class MySQLTable {
     );
   }
 
+  /**
+   * Inserts a new row into the table if there are no existing rows in
+   * the table that have the same values for the specified columns.
+   *
+   * This is useful because if the row is not inserted, the table's
+   * `AUTO_INCREMENT` value is not increased (unlike when an insert
+   * fails because of a unique key constraint).
+   *
+   * @param {Object} data - An object mapping column names to data values to insert.
+   *     The values are escaped by default. If you don't want a value to be escaped,
+   *     wrap it in a "raw" object (see the last example below).
+   * @param {string[]} keyColumns - The names of columns in the `data` object.
+   *     If there is already a row in the table with the same values for these
+   *     columns as the values being inserted, the data will not be inserted.
+   * @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 of the query is returned.
+   *
+   * @example <caption>Insert a new user if a user with the same email does not exist</caption>
+   * userTable.insertIfNotExists({email: 'email@example.com', name: 'John Doe'}, ['email'])
+   *   .then(result => result.affectedRows);
+   *   // 0 - If there was a row with `email` = 'email@example.com' (row not inserted)
+   *   // 1 - If there wasn't (row was inserted)
+   *
+   * // INSERT INTO `user` (`email`, `name`)
+   * // SELECT 'email@example.com', 'John Doe'
+   * // FROM DUAL WHERE NOT EXISTS (
+   * //   SELECT 1 FROM `user`
+   * //   WHERE `email` = 'email@example.com' LIMIT 1
+   * // );
+   *
+   * @example <caption>Insert without escaping some values</caption>
+   * const data = {
+   *   placeId: 'ChIJK2f-X1bxK4gRkB0jxyh7AwU',
+   *   type: 'city',
+   *   // IMPORTANT: You must manually escape any user-input values used in the "raw" object.
+   *   location: {__raw: 'POINT(-80.5204096, 43.4642578)'},
+   * };
+   * placeTable.insertIfNotExists(data, ['placeId', 'type'])
+   *   .then(result => result.affectedRows);
+   *   // 0 - If there was a row with the same `placeId` and `type` (row not inserted)
+   *   // 1 - If there wasn't (row was inserted)
+   *
+   * // INSERT INTO `place` (`placeId`, `type`, `location`)
+   * // SELECT 'ChIJK2f-X1bxK4gRkB0jxyh7AwU', 'city', POINT(-80.5204096, 43.4642578)
+   * // FROM DUAL WHERE NOT EXISTS (
+   * //   SELECT 1 FROM `place`
+   * //   WHERE `placeId` = 'ChIJK2f-X1bxK4gRkB0jxyh7AwU' AND `type` = 'city' LIMIT 1
+   * // );
+   */
+  insertIfNotExists(data, keyColumns, cb) {
+    const db = this._db;
+    var columnNames = '';
+    var insertValues = '';
+    var whereClause = '';
+
+    for (var dataColumnName in data) {
+      columnNames += (columnNames ? ',' : '') + db.escapeId(dataColumnName);
+      insertValues += (insertValues ? ',' : '') + this._rawEscape(data[dataColumnName]);
+    }
+
+    for (var i = 0; i < keyColumns.length; i++) {
+      var keyColumnName = keyColumns[i];
+      whereClause += (i > 0 ? ' AND ' : '') +
+        db.escapeId(keyColumnName) + '=' + this._rawEscape(data[keyColumnName]);
+    }
+
+    return db.pquery(
+      `INSERT INTO ${this._escapedName} (${columnNames}) SELECT ${insertValues} FROM DUAL ` +
+        `WHERE NOT EXISTS(SELECT 1 FROM ${this._escapedName} WHERE ${whereClause} LIMIT 1)`,
+      cb
+    );
+  }
+
   /**
    * Updates data in the table.
    *
@@ -333,6 +407,12 @@ class MySQLTable {
   transacting(trxn) {
     return new MySQLTable(this.name, this.schema, this.pool, trxn);
   }
+
+  _rawEscape(value) {
+    return value && value.__raw !== undefined
+      ? value.__raw
+      : this._db.escape(value);
+  }
 }
 
 module.exports = MySQLTable;

test/unit/MySQLTable.test.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const CallbackManager = require('es6-callback-manager');
 const MySQLTable = require('../../lib/MySQLTable');
 const MySQLPlus = require('../../lib/MySQLPlus');
 
@@ -411,6 +412,131 @@ describe('MySQLTable', () => {
   });
 
 
+  describe('#insertIfNotExists()', () => {
+
+    describe('with a callback', () => {
+
+      before(done => {
+        testTable.insertIfNotExists({email: 'one@email.com'}, ['email'], done);
+      });
+
+      after(resetTable);
+
+      it('should not insert anything and not change the table if a row with the same key already exists', done => {
+        testTable.insertIfNotExists({email: 'one@email.com'}, ['email'], (err, result) => {
+          if (err) throw err;
+          result.affectedRows.should.equal(0);
+
+          testTable.query('SHOW CREATE TABLE ' + testTable.name, (err, result) => {
+            if (err) throw err;
+            result[0]['Create Table'].should.match(/ AUTO_INCREMENT=2 /);
+            done();
+          });
+        });
+      });
+
+      it('should insert the specified data into the table', done => {
+        testTable.insertIfNotExists({email: 'two@email.com'}, ['email'], (err, result) => {
+          if (err) throw err;
+          result.affectedRows.should.equal(1);
+          result.insertId.should.equal(2);
+          done();
+        });
+      });
+
+      it('should accept raw data to insert and not escape it', done => {
+        const cbManager = new CallbackManager(done);
+        const doneOnlyRaw = cbManager.registerCallback();
+        const doneDataAndRaw = cbManager.registerCallback();
+        const doneRowExists = cbManager.registerCallback();
+
+        testTable.insertIfNotExists({email: {__raw: '"three@email.com"'}}, ['email'], (err, result) => {
+          if (err) throw err;
+          result.affectedRows.should.equal(1);
+          result.insertId.should.equal(3);
+
+          testTable.select('email', 'WHERE id = 3', (err, rows) => {
+            if (err) throw err;
+            rows[0].email.should.equal('three@email.com');
+            doneOnlyRaw();
+          });
+
+          testTable.insertIfNotExists({id: 5, email: {__raw: '"five@email.com"'}}, ['id', 'email'], (err, result) => {
+            if (err) throw err;
+            result.affectedRows.should.equal(1);
+            result.insertId.should.equal(5);
+            doneDataAndRaw();
+          });
+        });
+
+        testTable.insertIfNotExists({email: {__raw: '"one@email.com"'}}, ['email'], (err, result) => {
+          if (err) throw err;
+          result.affectedRows.should.equal(0);
+          doneRowExists();
+        });
+      });
+
+    });
+
+
+    describe('with a promise', () => {
+
+      before(
+        () => testTable.insertIfNotExists({email: 'one@email.com'}, ['email'])
+      );
+
+      after(resetTable);
+
+      it('should not insert anything and not change the table if a row with the same key already exists', () => {
+        return testTable.insertIfNotExists({email: 'one@email.com'}, ['email'])
+          .then(result => {
+            result.affectedRows.should.equal(0);
+            return testTable.query('SHOW CREATE TABLE ' + testTable.name);
+          })
+          .then(result => {
+            result[0]['Create Table'].should.match(/ AUTO_INCREMENT=2 /);
+          });
+      });
+
+      it('should insert the specified data into the table', () => {
+        return testTable.insertIfNotExists({email: 'two@email.com'}, ['email'])
+          .then(result => {
+            result.affectedRows.should.equal(1);
+            result.insertId.should.equal(2);
+          });
+      });
+
+      it('should accept raw data to insert and not escape it', () => {
+        const promiseNewRow = testTable.insertIfNotExists({email: {__raw: '"three@email.com"'}}, ['email'])
+          .then(result => {
+            result.affectedRows.should.equal(1);
+            result.insertId.should.equal(3);
+
+            return Promise.all([
+              testTable.select('email', 'WHERE id = 3'),
+              testTable.insertIfNotExists({id: 5, email: {__raw: '"five@email.com"'}}, ['id', 'email']),
+            ]);
+          })
+          .then(results => {
+            results[0][0].email.should.equal('three@email.com');
+
+            results[1].affectedRows.should.equal(1);
+            results[1].insertId.should.equal(5);
+          });
+
+        const promiseRowExists = testTable.insertIfNotExists({email: {__raw: '"one@email.com"'}}, ['email'])
+          .then(result => {
+            result.affectedRows.should.equal(0);
+          });
+
+        return Promise.all([promiseNewRow, promiseRowExists]);
+      });
+
+    });
+
+  });
+
+
   describe('#update()', () => {
 
     describe('with a callback', () => {