Add raw method to wrap raw strings for escape overriding

closes #13
closes #21

Author: SeregPie

HISTORY.md

@@ -2,6 +2,7 @@ unreleased
 ==========
 
   * Add `.toSqlString()` escape overriding
+  * Add `raw` method to wrap raw strings for escape overriding
   * Small performance improvement on `escapeId`
 
 2.2.0 / 2016-11-01

README.md

@@ -101,6 +101,19 @@ var sql = SqlString.format('UPDATE posts SET modified = ? WHERE id = ?', [CURREN
 console.log(sql); // UPDATE posts SET modified = CURRENT_TIMESTAMP() WHERE id = 42
 ```
 
+To generate objects with a `toSqlString` method, the `SqlString.raw()` method can
+be used. This creates an object that will be left un-touched when using in a `?`
+placeholder, useful for using functions as dynamic values:
+
+**Caution** The string provided to `SqlString.raw()` will skip all escaping
+functions when used, so be careful when passing in unvalidated input.
+
+```js
+var CURRENT_TIMESTAMP = SqlString.raw('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

@@ -177,6 +177,16 @@ SqlString.objectToValues = function objectToValues(object, timeZone) {
   return sql;
 };
 
+SqlString.raw = function raw(sql) {
+  if (typeof sql !== 'string') {
+    throw new TypeError('argument sql must be a string');
+  }
+
+  return {
+    toSqlString: function toSqlString() { return sql; }
+  };
+};
+
 function escapeString(val) {
   var chunkIndex = CHARS_GLOBAL_REGEXP.lastIndex = 0;
   var escapedVal = '';

test/unit/test-SqlString.js

@@ -66,6 +66,10 @@ test('SqlString.escape', {
     assert.equal(SqlString.escape(5), '5');
   },
 
+  'raw not escaped': function () {
+    assert.equal(SqlString.escape(SqlString.raw('NOW()')), 'NOW()');
+  },
+
   'objects are turned into key value pairs': function() {
     assert.equal(SqlString.escape({a: 'b', c: 'd'}), "`a` = 'b', `c` = 'd'");
   },
@@ -299,3 +303,29 @@ test('SqlString.format', {
     assert.equal(sql, 'SELECT COUNT(*) FROM table');
   }
 });
+
+test('SqlString.raw', {
+  'creates object': function() {
+    assert.equal(typeof SqlString.raw('NOW()'), 'object');
+  },
+
+  'rejects number': function() {
+    assert.throws(function () {
+      SqlString.raw(42);
+    });
+  },
+
+  'rejects undefined': function() {
+    assert.throws(function () {
+      SqlString.raw();
+    });
+  },
+
+  'object has toSqlString': function() {
+    assert.equal(typeof SqlString.raw('NOW()').toSqlString, 'function');
+  },
+
+  'toSqlString returns sql as-is': function() {
+    assert.equal(SqlString.raw("NOW() AS 'current_time'").toSqlString(), "NOW() AS 'current_time'");
+  }
+});