MySQLTable: Implement a .exists() method

nwoltman · nwoltman · commit a01e6fb23625 · 2017-04-25T17:14:43.000-04:00
diff --git a/README.md b/README.md
@@ -540,6 +540,7 @@ an instance, use [`poolPlus.defineTable()`](#PoolPlus+defineTable) or
     * [.pool](#MySQLTable+pool) : <code>[PoolPlus](#PoolPlus)</code>
     * [.trxn](#MySQLTable+trxn) : <code>?[Connection](#Connection)</code>
     * [.select(columns, [sqlString], [values], [cb])](#MySQLTable+select) ⇒ <code>Promise</code>
+    * [.exists(sqlString, [values], [cb])](#MySQLTable+exists) ⇒ <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>
@@ -650,6 +651,44 @@ userTable.select('COUNT(*) AS `highScorers`', 'WHERE `points` > 10000')
 ```
 
 
+---
+
+<a name="MySQLTable+exists"></a>
+
+### mySQLTable.exists(sqlString, [values], [cb]) ⇒ <code>Promise</code>
+Checks if rows in the table exist.
+
+
+| Param | Type | Description |
+|:--- |:--- |:--- |
+| sqlString | <code>string</code> | SQL that specifies rows to check for existence.<br>     The first example shows how this parameter is used in the query. |
+| [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 where the `results` will be either `true` or `false`. |
+
+**Returns**: <code>?Promise</code> - If the `cb` parameter is omitted, a promise that will
+    resolve with either `true` or `false` is returned.
+
+**Example**: Using a promise
+```js
+userTable.exists('WHERE `id` > 10')
+  .then(exists => console.log(exists)); // true or false
+
+// SELECT EXISTS (
+//   SELECT 1 FROM `user`
+//   WHERE `id` > 10  # This is where `sqlString` gets inserted
+//   LIMIT 1
+// )
+```
+
+**Example**: Using a callback and the `values` argument
+```js
+userTable.exists('WHERE `id` = ?', [10], (err, exists) => {
+  if (err) throw err;
+  console.log(exists); // true or false
+});
+```
+
+
 ---
 
 <a name="MySQLTable+insert"></a>
diff --git a/lib/MySQLTable.js b/lib/MySQLTable.js
@@ -101,6 +101,57 @@ class MySQLTable {
     );
   }
 
+ /**
+  * Checks if rows in the table exist.
+  *
+  * @param {string} sqlString - SQL that specifies rows to check for existence.<br>
+  *     The first example shows how this parameter is used in the query.
+  * @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 where the `results` will be either `true` or `false`.
+  * @returns {?Promise} If the `cb` parameter is omitted, a promise that will
+  *     resolve with either `true` or `false` is returned.
+  *
+  * @example <caption>Using a promise</caption>
+  * userTable.exists('WHERE `id` > 10')
+  *   .then(exists => console.log(exists)); // true or false
+  *
+  * // SELECT EXISTS (
+  * //   SELECT 1 FROM `user`
+  * //   WHERE `id` > 10  # This is where `sqlString` gets inserted
+  * //   LIMIT 1
+  * // )
+  *
+  * @example <caption>Using a callback and the `values` argument</caption>
+  * userTable.exists('WHERE `id` = ?', [10], (err, exists) => {
+  *   if (err) throw err;
+  *   console.log(exists); // true or false
+  * });
+  */
+  exists(sqlString, values, cb) {
+    if (typeof values === 'function') {
+      cb = values;
+      values = undefined;
+    }
+
+    sqlString = 'SELECT EXISTS ( SELECT 1 FROM ' + this._escapedName + ' ' + sqlString + ' LIMIT 1 ) as `exists`';
+
+    if (!cb) {
+      return this._db.pquery(sqlString, values).then(checkExists);
+    }
+
+    this._db.query(sqlString, values, (err, rows) => {
+      if (err) {
+        cb(err);
+        return;
+      }
+
+      cb(null, checkExists(rows));
+    });
+
+    return undefined;
+  }
+
   /**
    * Inserts data into a new row in the table.
    *
@@ -417,4 +468,10 @@ class MySQLTable {
   }
 }
 
+function checkExists(rows) {
+  // Must convert the result to a number because mysql will return a string if the
+  // user set the "supportBigNumbers" and "bigNumberStrings" options to `true`.
+  return +rows[0].exists === 1;
+}
+
 module.exports = MySQLTable;
diff --git a/test/unit/MySQLTable.test.js b/test/unit/MySQLTable.test.js
@@ -8,6 +8,9 @@ const config = require('../config');
 const should = require('should');
 const sinon = require('sinon');
 
+const expect = should;
+
+should.Assertion.addChain('to');
 should.config.checkProtoEql = false;
 
 describe('MySQLTable', () => {
@@ -70,7 +73,7 @@ describe('MySQLTable', () => {
 
 
     it('should be undefined if not passed to the constructor', () => {
-      should(testTable.trxn).be.undefined();
+      expect(testTable.trxn).to.be.undefined();
     });
 
 
@@ -763,6 +766,96 @@ describe('MySQLTable', () => {
   });
 
 
+  describe('#exists()', () => {
+
+    before(done => {
+      const insertSQL = 'INSERT INTO `mysql_table_test_table` (`email`) VALUES ("one@email.com")';
+      testTable.query(insertSQL, done);
+    });
+
+    after(resetTable);
+
+    describe('with a callback', () => {
+
+      it('should resolve with `true` if rows exist (without using the `values` argument)', done => {
+        testTable.exists('WHERE `id` < 3', (err, exists) => {
+          if (err) throw err;
+          exists.should.be.true();
+          done();
+        });
+      });
+
+      it('should resolve with `true` if rows exist (with using the `values` argument)', done => {
+        testTable.exists('WHERE `email` = ?', ['one@email.com'], (err, exists) => {
+          if (err) throw err;
+          exists.should.be.true();
+          done();
+        });
+      });
+
+      it('should resolve with `false` if rows exist (without using the `values` argument)', done => {
+        testTable.exists('WHERE `id` > 3', (err, exists) => {
+          if (err) throw err;
+          exists.should.be.false();
+          done();
+        });
+      });
+
+      it('should resolve with `false` if rows exist (with using the `values` argument)', done => {
+        testTable.exists('WHERE `email` = ?', ['two@email.com'], (err, exists) => {
+          if (err) throw err;
+          exists.should.be.false();
+          done();
+        });
+      });
+
+      it('should resolve with an error if an error occurrs', done => {
+        const error = new Error('exists error');
+        sinon.stub(pool, 'query').yieldsAsync(error);
+
+        testTable.exists('WHERE `email` = 1', (err, exists) => {
+          err.should.equal(error);
+          expect(exists).to.be.undefined();
+
+          pool.query.restore();
+          done();
+        });
+      });
+
+    });
+
+
+    describe('with a promise', () => {
+
+      it('should resolve with `true` if rows exist (without using the `values` argument)', () => {
+        return testTable.exists('WHERE `id` < 3').then(exists => {
+          exists.should.be.true();
+        });
+      });
+
+      it('should resolve with `true` if rows exist (with using the `values` argument)', () => {
+        return testTable.exists('WHERE `email` = ?', ['one@email.com']).then(exists => {
+          exists.should.be.true();
+        });
+      });
+
+      it('should resolve with `false` if rows exist (without using the `values` argument)', () => {
+        return testTable.exists('WHERE `id` > 3').then(exists => {
+          exists.should.be.false();
+        });
+      });
+
+      it('should resolve with `false` if rows exist (with using the `values` argument)', () => {
+        return testTable.exists('WHERE `email` = ?', ['two@email.com']).then(exists => {
+          exists.should.be.false();
+        });
+      });
+
+    });
+
+  });
+
+
   describe('#query()', () => {
 
     beforeEach(() => {
