Neighbourhood Party Manager
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    string-escapepublic

    jsesc Build status Dependency status

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

    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 a regular expression, 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 a regular expression
    jsesc(/©𝌆/g);
    // â†’ '/\\xA9\\uD834\\uDF06/g'
     
    // 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.\""

    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\']'

    This setting has no effect on the output for regular expressions. Those only use escape sequences for non-printable ASCII symbols and non-ASCII symbols, regardless of the value of the escapeEverything setting.

    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 or regular expressions.

    json

    The json option takes a boolean value (true or false), and defaults to false (disabled). When enabled, the output is always 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.

    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 aren’t strings, regular expressions, 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]'

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

    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-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.

    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

    twitter/mathias
    Mathias Bynens

    License

    This library is available under the MIT license.

    Keywords

    none

    install

    npm i string-escape

    Downloadsweekly downloads

    30

    version

    0.3.0

    license

    none

    repository

    githubgithub

    last publish

    collaborators

    • avatar