Add .toSqlString() escape overriding

closes mysqljs#9

Author: kevinmartin

HISTORY.md

@@ -1,3 +1,8 @@
+unreleased
+==========
+
+  * Add `.toSqlString()` escape overriding
+
 2.2.0 / 2016-11-01
 ==================
 

README.md

@@ -70,6 +70,8 @@ Different value types are escaped differently, here is how:
 * Arrays are turned into list, e.g. `['a', 'b']` turns into `'a', 'b'`
 * Nested arrays are turned into grouped lists (for bulk inserts), e.g. `[['a',
   'b'], ['c', 'd']]` turns into `('a', 'b'), ('c', 'd')`
+* Objects that have a `toSqlString` method will have `.toSqlString()` called
+  and the returned value is used as the raw SQL.
 * Objects are turned into `key = 'val'` pairs for each enumerable property on
   the object. If the property's value is a function, it is skipped; if the
   property's value is an object, toString() is called on it and the returned
@@ -87,6 +89,14 @@ var sql = SqlString.format('INSERT INTO posts SET ?', post);
 console.log(sql); // INSERT INTO posts SET `id` = 1, `title` = 'Hello MySQL'
 ```
 
+And the `toSqlString` method allows you to form complex queries with functions:
+
+```js
+var CURRENT_TIMESTAMP = { toSqlString: function() { return 'CURRENT_TIMESTAMP()'; } };
+var sql = SqlString.format('UPDATE posts SET modified = ? WHERE id = ?', [CURRENT_TIMESTAMP, 42]);
+console.log(sql); // UPDATE posts SET modified = CURRENT_TIMESTAMP() WHERE id = 42
+```
+
 If you feel the need to escape queries by yourself, you can also use the escaping
 function directly:
 

lib/SqlString.js

@@ -45,6 +45,8 @@ SqlString.escape = function escape(val, stringifyObjects, timeZone) {
         return SqlString.arrayToList(val, timeZone);
       } else if (Buffer.isBuffer(val)) {
         return SqlString.bufferToString(val);
+      } else if (typeof val.toSqlString === 'function') {
+        return String(val.toSqlString());
       } else if (stringifyObjects) {
         return escapeString(val.toString());
       } else {

package.json

@@ -6,6 +6,7 @@
     "Adri Van Houdt <[email protected]>",
     "Douglas Christopher Wilson <[email protected]>",
     "fengmk2 <[email protected]> (http://fengmk2.github.com)",
+    "Kevin Jose Martin <[email protected]>",
     "Nathan Woltman <[email protected]>"
   ],
   "license": "MIT",

test/unit/test-SqlString.js

@@ -74,6 +74,18 @@ test('SqlString.escape', {
     assert.equal(SqlString.escape({a: 'b', c: function() {}}), "`a` = 'b'");
   },
 
+  'object values toSqlString is called': function() {
+    assert.equal(SqlString.escape({id: { toSqlString: function() { return 'LAST_INSERT_ID()'; } }}), '`id` = LAST_INSERT_ID()');
+  },
+
+  'objects toSqlString is called': function() {
+    assert.equal(SqlString.escape({ toSqlString: function() { return '@foo_id'; } }), '@foo_id');
+  },
+
+  'objects toSqlString is not quoted': function() {
+    assert.equal(SqlString.escape({ toSqlString: function() { return 'CURRENT_TIMESTAMP()'; } }), 'CURRENT_TIMESTAMP()');
+  },
+
   'nested objects are cast to strings': function() {
     assert.equal(SqlString.escape({a: {nested: true}}), "`a` = '[object Object]'");
   },
@@ -272,6 +284,9 @@ test('SqlString.format', {
 
     var sql = SqlString.format('?', { toString: function () { return 'hello'; } }, true);
     assert.equal(sql, "'hello'");
+
+    var sql = SqlString.format('?', { toSqlString: function () { return '@foo'; } }, true);
+    assert.equal(sql, '@foo');
   },
 
   'sql is untouched if no values are provided': function () {