JavaScript string escape

This is a JavaScript library for escaping JavaScript strings while generating the shortest possible valid output. Here’s an online demo.

Feel free to fork if you see possible improvements!

Installation

Via Bower:

bower install string-escape

Via Component:

component install mathiasbynens/javascript-string-escape

Via npm:

npm install string-escape

In a browser:

<script src="string-escape.js"></script>

In Node.js and RingoJS:

var stringEscape = require('string-escape');

In Narwhal:

var stringEscape = require('string-escape').stringEscape;

In Rhino:

load('string-escape.js');

Using an AMD loader like RequireJS:

require(
  {
    'paths': {
      'string-escape': 'path/to/string-escape'
    }
  },
  ['string-escape'],
  function(stringEscape) {
    console.log(stringEscape);
  }
);

API

stringEscape(value, options)

This function takes a value and returns an escaped version of the value where any characters that are not printable ASCII symbols are escaped using the shortest possible (but valid) escape sequences for use in JavaScript strings. The first supported value type is strings:

stringEscape('Ich ♥ Bücher');
// → 'Ich \\u2665 B\\xFCcher'

stringEscape('foo 𝌆 bar');
// → 'foo \\uD834\\uDF06 bar'

Instead of a string, the value can also be a flat object containing only string values. In that case, stringEscape will return a stringified version of the object where any characters that are not printable ASCII symbols are escaped in the same way.

stringEscape({
  'Ich ♥ Bücher': 'foo 𝌆 bar'
});
// → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'

Instead of a string or an object, the value can also be a flat array containing only string values. In that case, stringEscape will return a stringified version of the array where any characters that are not printable ASCII symbols are escaped in the same way.

stringEscape([
  'Ich ♥ Bücher': 'foo 𝌆 bar'
]);
// → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'

The optional options argument accepts an object with the following options:

quotes

The default value for the quotes option is 'single'. This means that any occurences of ' in the input string will be escaped as \', so that the output can be used in a string literal wrapped in single quotes.

stringEscape('Lorem ipsum "dolor" sit \'amet\' etc.');
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'

stringEscape('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single'
});
// → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
// → "Lorem ipsum \"dolor\" sit \\'amet\\' etc."

If you want to use the output as part of a string literal wrapped in double quotes, set the quotes option to 'double'.

stringEscape('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double'
});
// → 'Lorem ipsum \\"dolor\\" sit \'amet\' etc.'
// → "Lorem ipsum \\\"dolor\\\" sit 'amet' etc."

This setting also affects the output for arrays and objects:

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'quotes': 'double'
});
// → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'

stringEscape([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'quotes': 'double'
});
// → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'

wrap

The wrap option takes a boolean value (true or false), and defaults to false (disabled). When enabled, the output will be a valid JavaScript string literal wrapped in quotes. The type of quotes can be specified through the quotes setting.

stringEscape('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'single',
  'wrap': true
});
// → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
// → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"

stringEscape('Lorem ipsum "dolor" sit \'amet\' etc.', {
  'quotes': 'double',
  'wrap': true
});
// → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
// → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""

escapeEverything

The escapeEverything option takes a boolean value (true or false), and defaults to false (disabled). When enabled, all the symbols in the output will be escaped, even printable ASCII symbols.

stringEscape('lolwat"foo\'bar', {
  'escapeEverything': true
});
// → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
// → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"

This setting also affects the output for arrays and objects:

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'escapeEverything': true
});
// → '{\'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72\':\'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72\'}'
// → "{'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72':'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72'}"

stringEscape([ 'Ich ♥ Bücher': 'foo 𝌆 bar' ], {
  'escapeEverything': true
});
// → '[\'\x49\x63\x68\x20\u2665\x20\x42\xFC\x63\x68\x65\x72\',\'\x66\x6F\x6F\x20\uD834\uDF06\x20\x62\x61\x72\']'

compact

The compact option takes a boolean value (true or false), and defaults to true (enabled). When enabled, the output for arrays and objects will be as compact as possible; it won’t be formatted nicely.

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': true // this is the default
});
// → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

stringEscape([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false
});
// → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'

This setting has no effect on the output for strings.

indent

The indent option takes a string value, and defaults to '\t'. When the compact setting is enabled (true), the value of the indent option is used to format the output for arrays and objects.

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '\t' // this is the default
});
// → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

stringEscape({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
  'compact': false,
  'indent': '  '
});
// → '{\n  \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'

stringEscape([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
  'compact': false,
  'indent': '  '
});
// → '[\n  \'Ich \u2665 B\xFCcher\',\n\  t\'foo \uD834\uDF06 bar\'\n]'

This setting has no effect on the output for strings.

json

The json option takes a boolean value (true or false), and defaults to false (disabled). When enabled, the output will always be valid JSON. Hexadecimal character escape sequences and the \v or \0 escape sequences will not be used. Setting json: true implies quotes: 'double', wrap: true.

stringEscape('foo\x00bar\xFF\uFFFDbaz', {
  'json': true
});
// → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'

stringEscape({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
  'json': true
});
// → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'

stringEscape([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
  'json': true
});
// → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'

stringEscape.version

A string representing the semantic version number.

Using the jsesc binary

To use the jsesc binary in your shell, simply install javascript-string-escape globally using npm:

npm install -g string-escape

After that you will be able to escape strings from the command line:

$ jsesc 'föo ♥ bår 𝌆 baz'
f\xF6o \u2665 b\xE5r \uD834\uDF06 baz

To escape flat arrays containing only string values or flat objects containing only string values, use the -o/--object option:

$ jsesc '{ "föo": "♥", "bår": "𝌆 baz" }'
f\xF6o \u2665 b\xE5r \uD834\uDF06 baz

Create a version of a JSON file where any non-ASCII symbols are escaped:

$ cat data-raw.json | jsesc --json --object > data-escaped.json

See jsesc --help for the full list of options.

Support

This library has been tested in at least Chrome 27-29, Firefox 3-22, Safari 4-6, Opera 10-12, IE 6-10, Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, PhantomJS 1.9.0, and Rhino 1.7RC4.

Unit tests & code coverage

After cloning this repository, run npm install to install the dependencies needed for development and testing. You may want to install Istanbul globally using npm install istanbul -g.

Once that’s done, you can run the unit tests in Node using npm test or node tests/tests.js. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use grunt test.

To generate the code coverage report, use grunt cover.

Author

Mathias Bynens

License

This library is available under the MIT license.