jsesc

What is jsesc?

The jsesc npm package is a library for escaping JavaScript strings while generating the shortest possible valid ASCII-only output. It's useful for avoiding syntax errors when embedding data in JavaScript code or for preparing data to be JSON-encoded.

What are jsesc's main functionalities?

String escaping

Escapes any occurrences of U+2028 (line separator) and U+2029 (paragraph separator) among other potentially problematic characters in JavaScript strings, making the output safe for inclusion in HTML/JavaScript templates.

"jsesc('foo \u2028 bar \u2029 baz')"

JSON escaping

Converts an object to a JSON string, ensuring that the output is safe to use in JavaScript by escaping any characters that could cause syntax errors or security issues.

"jsesc({ 'foo': 'bar' }, { 'json': true })"

ASCII-only output

Escapes non-ASCII symbols into their Unicode escape sequences to produce an ASCII-only output. This is particularly useful for minimizing encoding issues or for environments that do not fully support Unicode.

"jsesc('foo © bar ≠ baz 𝌆 qux', { 'es6': false })"

Other packages similar to jsesc

he

The 'he' package is an HTML entity encoder/decoder written in JavaScript. While it focuses more on HTML entities, it shares the concept of transforming strings into a safer format, similar to what jsesc does for JavaScript strings.

escape-string-regexp

This package is designed to escape any characters that have special meaning in regular expressions. It's similar to jsesc in the sense that it makes strings safe for a specific context (regular expressions), but it does not cover the broader scope of JavaScript string escaping that jsesc does.

entities

Similar to 'he', 'entities' is another package for encoding and decoding HTML entities. It offers functionality that overlaps with jsesc's when dealing with strings intended for HTML, but jsesc provides additional features for JavaScript-specific escaping.

README

jsesc

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

This can be used to avoid mojibake and other encoding issues, or even to avoid errors when passing JSON-formatted data (which may contain U+2028 LINE SEPARATOR, U+2029 PARAGRAPH SEPARATOR, or lone surrogates) to a JavaScript parser or an UTF-8 encoder, respectively.

Feel free to fork if you see possible improvements!

Installation

Via Bower:

bower install jsesc

Via Component:

component install mathiasbynens/jsesc

Via npm:

npm install jsesc

In a browser:

<script src="jsesc.js"></script>

In Node.js and RingoJS:

var jsesc = require('jsesc');

In Narwhal:

var jsesc = require('jsesc').jsesc;

In Rhino:

load('jsesc.js');

Using an AMD loader like RequireJS:

require(
  {
    'paths': {
      'jsesc': 'path/to/jsesc'
    }
  },
  ['jsesc'],
  function(jsesc) {
    console.log(jsesc);
  }
);

API

jsesc(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:

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

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

Instead of a string, the value can also be an array, or an object. In such cases, jsesc will return a stringified version of the value where any characters that are not printable ASCII symbols are escaped in the same way.

// Escaping an array
jsesc([
  'Ich ♥ Bücher', 'foo 𝌆 bar'
]);
// → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'

// Escaping an object
jsesc({
  '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.

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

jsesc('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'.

jsesc('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:

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

jsesc([ '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.

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

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

es6

The es6 option takes a boolean value (true or false), and defaults to false (disabled). When enabled, any astral Unicode symbols in the input will be escaped using ECMAScript 6 Unicode code point escape sequences instead of using separate escape sequences for each surrogate half. If backwards compatibility with ES5 environments is a concern, don’t enable this setting. If the json setting is enabled, the value for the es6 setting is ignored (as if it was false).

// By default, the `es6` option is disabled:
jsesc('foo 𝌆 bar 💩 baz');
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To explicitly disable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': false
});
// → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'

// To enable it:
jsesc('foo 𝌆 bar 💩 baz', {
  'es6': true
});
// → 'foo \\u{1D306} bar \\u{1F4A9} baz'

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.

jsesc('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:

jsesc({ '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'}"

jsesc([ '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.

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

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

jsesc([ '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.

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

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

jsesc([ '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 is 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, es6: false, although these values can still be overridden if needed — but in such cases, the output won’t be valid JSON anymore.

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

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

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

// Values that are acceptable in JSON but aren’t strings, arrays, or object
// literals can’t be escaped, so they’ll just be preserved:
jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
  'json': true
});
// → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
// Values that aren’t allowed in JSON are run through `JSON.stringify()`:
jsesc([ undefined, -Infinity ], {
  'json': true
});
// → '[null,null]'

Note: Using this option on objects or arrays that contain non-string values relies on JSON.stringify(). For legacy environments like IE ≤ 7, use a JSON polyfill.

lowercaseHex

The lowercaseHex option takes a boolean value (true or false), and defaults to false (disabled). When enabled, the alphabetical hexadecimal digits in escape sequences in the output are in lowercase.

jsesc('Ich ♥ Bücher', {
  'lowercaseHex': true,
});
// → 'Ich \\u2665 B\\xfccher'
//                    ^^

jsesc.version

A string representing the semantic version number.

Using the jsesc binary

To use the jsesc binary in your shell, simply install jsesc globally using npm:

npm install -g jsesc

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 arrays or objects containing string values, use the -o/--object option:

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

To prettify the output in such cases, use the -p/--pretty option:

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

For valid JSON output, use the -j/--json option:

$ jsesc --json --pretty '{ "föo": "♥", "bår": "𝌆 baz" }'
{
  "f\u00F6o": "\u2665",
  "b\u00E5r": "\uD834\uDF06 baz"
}

Read a local JSON file, escape any non-ASCII symbols, and save the result to a new file:

$ jsesc --json --object < data-raw.json > data-escaped.json

Or do the same with an online JSON file:

$ curl -sL "http://git.io/aorKgQ" | 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, Firefox 3, Safari 4, Opera 10, IE 6, Node.js v0.10.0, io.js v1.0.0, Narwhal 0.3.2, RingoJS 0.8-0.11, PhantomJS 1.9.0, and Rhino 1.7RC4.

Note: Using the json option on objects or arrays that contain non-string values relies on JSON.parse(). For legacy environments like IE ≤ 7, use a JSON polyfill.

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.