Add unsafe flag for straight serialisation (#37)

* Add unsafe flag for straight serialisation

* Update index.js

Fixed indentation

* Added tests and updated docs

* Fixed formatting and bumped version

* Formatting (fix last space too)

* Update package.json

* Remove venv

* Catch typo...

... and clarifying that options is an object,

* Fixed more spelling errors

I caught a few old ones too :)

Author: Bruno Herfst

README.md

@@ -11,9 +11,12 @@ Serialize JavaScript to a _superset_ of JSON that includes regular expressions,
 
 The code in this package began its life as an internal module to [express-state][]. To expand its usefulness, it now lives as `serialize-javascript` — an independent package on npm.
 
-You're probably wondering: **What about `JSON.stringify()`!?** We've found that sometimes we need to serialize JavaScript **functions**, **regexps** or **dates**. A great example is a web app that uses client-side URL routing where the route definitions are regexps that need to be shared from the server to the client.
+You're probably wondering: **What about `JSON.stringify()`!?** We've found that sometimes we need to serialize JavaScript **functions**, **regexps** or **dates**. A great example is a web app that uses client-side URL routing where the route definitions are regexps that need to be shared from the server to the client. But this module is also great for communicating between node processes.
+
+The string returned from this package's single export function is literal JavaScript which can be saved to a `.js` file, or be embedded into an HTML document by making the content of a `<script>` element.
+
+> **HTML characters and JavaScript line terminators are escaped automatically.**
 
-The string returned from this package's single export function is literal JavaScript which can be saved to a `.js` file, or be embedded into an HTML document by making the content of a `<script>` element. **HTML charaters and JavaScript line terminators are escaped automatically.**
 
 ## Installation
 
@@ -67,9 +70,11 @@ The above will produce the following string, HTML-escaped output which is safe t
 '{"haxorXSS":"\\u003C\\u002Fscript\\u003E"}'
 ```
 
+> You can pass an optional `unsafe` argument to `serialize()` for straight serialization.
+
 ### Options
 
-The `serialize()` function accepts `options` as its second argument. There are two options, both default to being `undefined`:
+The `serialize()` function accepts an `options` object as its second argument. All options are being defaulted to `undefined`:
 
 #### `options.space`
 
@@ -89,9 +94,17 @@ This option is a signal to `serialize()` that the object being serialized does n
 serialize(obj, {isJSON: true});
 ```
 
+#### `options.unsafe`
+
+This option is to signal `serialize()` that we want to do a straight conversion, without the XSS protection. This options needs to be explicitly set to `true`. HTML characters and JavaScript line terminators will not be escaped. You will have to roll your own.
+
+```js
+serialize(obj, {unsafe: true});
+```
+
 ## Deserializing
 
-For some use cases you might also need to deserialize the string. This is explicitely not part of this module. However, you can easily write it yourself:
+For some use cases you might also need to deserialize the string. This is explicitly not part of this module. However, you can easily write it yourself:
 
 ```js
 function deserialize(serializedJavascript){

index.js

@@ -30,7 +30,7 @@ function escapeUnsafeChars(unsafeChar) {
 module.exports = function serialize(obj, options) {
     options || (options = {});
 
-    // Backwards-compatability for `space` as the second argument.
+    // Backwards-compatibility for `space` as the second argument.
     if (typeof options === 'number' || typeof options === 'string') {
         options = {space: options};
     }
@@ -87,7 +87,9 @@ module.exports = function serialize(obj, options) {
     // Replace unsafe HTML and invalid JavaScript line terminator chars with
     // their safe Unicode char counterpart. This _must_ happen before the
     // regexps and functions are serialized and added back to the string.
-    str = str.replace(UNSAFE_CHARS_REGEXP, escapeUnsafeChars);
+    if (options.unsafe !== true) {
+        str = str.replace(UNSAFE_CHARS_REGEXP, escapeUnsafeChars);
+    }
 
     if (functions.length === 0 && regexps.length === 0 && dates.length === 0) {
         return str;

test/benchmark/serialize.js

@@ -39,6 +39,12 @@ new Benchmark.Suite('simpleObj', suiteConfig)
     .add('serialize( simpleObj, {isJSON: true} )', function () {
         serialize(simpleObj, {isJSON: true});
     })
+    .add('serialize( simpleObj, {unsafe: true} )', function () {
+        serialize(simpleObj, {unsafe: true});
+    })
+    .add('serialize( simpleObj, {unsafe: true, isJSON: true} )', function () {
+        serialize(simpleObj, {unsafe: true, isJSON: true});
+    })
     .add('serialize( simpleObj )', function () {
         serialize(simpleObj);
     })

test/unit/serialize.js

@@ -219,6 +219,24 @@ describe('serialize( obj )', function () {
             expect(serialize(fn, {isJSON: true})).to.equal('undefined');
             expect(serialize([1], {isJSON: true, space: 2})).to.equal('[\n  1\n]');
         });
+
+        it('should accept a `unsafe` option', function () {
+            expect(serialize('foo', {unsafe: true})).to.equal('"foo"');
+            expect(serialize('foo', {unsafe: false})).to.equal('"foo"');
+
+            function fn() { return true; }
+
+            expect(serialize(fn)).to.equal('function fn() { return true; }');
+            expect(serialize(fn, {unsafe: false})).to.equal('function fn() { return true; }');
+            expect(serialize(fn, {unsafe: undefined})).to.equal('function fn() { return true; }');
+            expect(serialize(fn, {unsafe: "true"})).to.equal('function fn() { return true; }');
+
+            expect(serialize(fn, {unsafe: true})).to.equal('function fn() { return true; }');
+            expect(serialize(["1"], {unsafe: false, space: 2})).to.equal('[\n  "1"\n]');
+            expect(serialize(["1"], {unsafe: true, space: 2})).to.equal('[\n  "1"\n]');
+            expect(serialize(["<"], {space: 2})).to.equal('[\n  "\\u003C"\n]');
+            expect(serialize(["<"], {unsafe: true, space: 2})).to.equal('[\n  "<"\n]');
+        });
     });
 
     describe('backwards-compatability', function () {