jsesc

Given some data, _jsesc_ returns a stringified representation of that data. jsesc is similar to JSON.stringify() except:

1. it outputs JavaScript instead of JSON by default, enabling support for data structures like ES6 maps and sets;
2. it offers many options to customize the output;
3. its output is ASCII-safe by default, thanks to its use of escape sequences where needed.

For any input, jsesc generates the shortest possible valid printable-ASCII-only output. Here’s an online demo.

jsesc’s output can be used instead of JSON.stringify’s 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.

Installation

Via npm:

``bash
npm install jsesc
`

In Node.js:

`js
const jsesc = require('jsesc');
`

API

$3

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:

`js
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, an object, a map, a set, or a buffer. In such cases, jsesc returns a stringified version of the value where any characters that are not printable ASCII symbols are escaped in the same way.

`js
// 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 occurrences of ' in the input string are escaped as \', so that the output can be used in a string literal wrapped in single quotes.

`js
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'.

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

If you want to use the output as part of a template literal (i.e. wrapped in backticks), set the quotes option to 'backtick'.

`js
jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
'quotes': 'backtick'
});
// → '\\Lorem\\ ipsum "dolor" sit \'amet\' etc.'
// → "\\Lorem\\ ipsum \"dolor\" sit 'amet' etc."
// → \\\Lorem\\\ ipsum "dolor" sit 'amet' etc.
`

This setting also affects the output for arrays and objects:

`js
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"]'
`

#### numbers

The default value for the numbers option is 'decimal'. This means that any numeric values are represented using decimal integer literals. Other valid options are binary, octal, and hexadecimal, which result in binary integer literals, octal integer literals, and hexadecimal integer literals, respectively.

`js
jsesc(42, {
'numbers': 'binary'
});
// → '0b101010'

jsesc(42, {
'numbers': 'octal'
});
// → '0o52'

jsesc(42, {
'numbers': 'decimal'
});
// → '42'

jsesc(42, {
'numbers': 'hexadecimal'
});
// → '0x2A'
`

#### wrap

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

`js
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 are 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).

`js
// 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 are escaped — even printable ASCII symbols.

`js
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 string literals within arrays and objects.

#### minimal

The minimal option takes a boolean value (true or false), and defaults to false (disabled). When enabled, only a limited set of symbols in the output are escaped:

* U+0000 \0
* U+0008 \b
* U+0009 \t
* U+000A \n
* U+000C \f
* U+000D \r
* U+005C \\
* U+2028 \u2028
* U+2029 \u2029
* whatever symbol is being used for wrapping string literals (based on the quotes option)
* lone surrogates

Note: with this option enabled, jsesc output is no longer guaranteed to be ASCII-safe.

`js
jsesc('foo\u2029bar\nbaz©qux𝌆flops', {
'minimal': false
});
// → 'foo\\u2029bar\\nbaz©qux𝌆flops'
`

#### isScriptContext

The isScriptContext option takes a boolean value (true or false), and defaults to false (disabled). When enabled, occurrences of and in the output are escaped as <\/script and <\/style, and