UNPKG

14.4 kBTypeScriptView Raw
1export = jsesc;
2
3/**
4 * This function takes a value and returns an escaped version of the value where any characters
5 * that are not printable ASCII symbols are escaped using the shortest possible (but valid)
6 * escape sequences for use in JavaScript strings. The first supported value type is strings.
7 * Instead of a string, the value can also be an array, an object, a map, a set, or a buffer.
8 * In such cases, jsesc returns a stringified version of the value where any characters that
9 * are not printable ASCII symbols are escaped in the same way.
10 *
11 * @example
12 * import jsesc = require('jsesc');
13 *
14 * jsesc('Ich ♥ Bücher');
15 * // → 'Ich \\u2665 B\\xFCcher'
16 *
17 * jsesc('foo 𝌆 bar');
18 * // → 'foo \\uD834\\uDF06 bar'
19 *
20 * // Escaping an array
21 * jsesc([
22 * 'Ich ♥ Bücher', 'foo 𝌆 bar'
23 * ]);
24 * // → '[\'Ich \\u2665 B\\xFCcher\',\'foo \\uD834\\uDF06 bar\']'
25 *
26 * // Escaping an object
27 * jsesc({
28 * 'Ich ♥ Bücher': 'foo 𝌆 bar'
29 * });
30 * // → '{\'Ich \\u2665 B\\xFCcher\':\'foo \\uD834\\uDF06 bar\'}'
31 */
32declare function jsesc(argument: any, opts?: jsesc.Opts): string;
33
34declare namespace jsesc {
35 /**
36 * A string representing the semantic version number.
37 */
38 const version: string;
39
40 interface Opts {
41 /**
42 * The value `'single'` for the `quotes` option means that any occurrences of `'` in the input string are
43 * escaped as `\'`, so that the output can be used in a string literal wrapped in single quotes. If you want
44 * to use the output as part of a string literal wrapped in double quotes, set the `quotes` option to
45 * `'double'`. If you want to use the output as part of a template literal (i.e. wrapped in backticks), set
46 * the `quotes` option to `'backtick'`.
47 *
48 * @default 'single'
49 *
50 * @example
51 * import jsesc = require('jsesc');
52 *
53 * jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.');
54 * // → 'Lorem ipsum "dolor" sit \\\'amet\\\' etc.'
55 *
56 * jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
57 * quotes: 'single'
58 * });
59 * // → '`Lorem` ipsum "dolor" sit \\\'amet\\\' etc.'
60 * // → "`Lorem` ipsum \"dolor\" sit \\'amet\\' etc."
61 *
62 * jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
63 * quotes: 'double'
64 * });
65 * // → '`Lorem` ipsum \\"dolor\\" sit \'amet\' etc.'
66 * // → "`Lorem` ipsum \\\"dolor\\\" sit 'amet' etc."
67 *
68 * jsesc('`Lorem` ipsum "dolor" sit \'amet\' etc.', {
69 * quotes: 'backtick'
70 * });
71 * // → '\\`Lorem\\` ipsum "dolor" sit \'amet\' etc.'
72 * // → "\\`Lorem\\` ipsum \"dolor\" sit 'amet' etc."
73 * // → `\\\`Lorem\\\` ipsum "dolor" sit 'amet' etc.`
74 *
75 * // This setting also affects the output for arrays and objects:
76 * jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
77 * quotes: 'double'
78 * });
79 * // → '{"Ich \\u2665 B\\xFCcher":"foo \\uD834\\uDF06 bar"}'
80 *
81 * jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
82 * quotes: 'double'
83 * });
84 * // → '["Ich \\u2665 B\\xFCcher","foo \\uD834\\uDF06 bar"]'
85 */
86 quotes?: "single" | "double" | "backtick" | undefined;
87
88 /**
89 * The value `'decimal'` for the `numbers` option means that any numeric values are represented using decimal
90 * integer literals. Other valid options are `binary`, `octal`, and `hexadecimal`, which result in binary
91 * integer literals, octal integer literals, and hexadecimal integer literals, respectively.
92 *
93 * @default 'decimal'
94 *
95 * @example
96 * import jsesc = require('jsesc');
97 *
98 * jsesc(42, {
99 * numbers: 'binary'
100 * });
101 * // → '0b101010'
102 *
103 * jsesc(42, {
104 * numbers: 'octal'
105 * });
106 * // → '0o52'
107 *
108 * jsesc(42, {
109 * numbers: 'decimal'
110 * });
111 * // → '42'
112 *
113 * jsesc(42, {
114 * numbers: 'hexadecimal'
115 * });
116 * // → '0x2A'
117 */
118 numbers?: "binary" | "octal" | "decimal" | "hexadecimal" | undefined;
119
120 /**
121 * When enabled, the output is a valid JavaScript string literal wrapped in quotes. The type of quotes can be
122 * specified through the `quotes` setting.
123 *
124 * @default false (disabled)
125 *
126 * @example
127 * import jsesc = require('jsesc');
128 *
129 * jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
130 * quotes: 'single',
131 * wrap: true
132 * });
133 * // → '\'Lorem ipsum "dolor" sit \\\'amet\\\' etc.\''
134 * // → "\'Lorem ipsum \"dolor\" sit \\\'amet\\\' etc.\'"
135 *
136 * jsesc('Lorem ipsum "dolor" sit \'amet\' etc.', {
137 * quotes: 'double',
138 * wrap: true
139 * });
140 * // → '"Lorem ipsum \\"dolor\\" sit \'amet\' etc."'
141 * // → "\"Lorem ipsum \\\"dolor\\\" sit \'amet\' etc.\""
142 */
143 wrap?: boolean | undefined;
144
145 /**
146 * When enabled, any astral Unicode symbols in the input are escaped using
147 * [ECMAScript 6 Unicode code point escape sequences](https://mathiasbynens.be/notes/javascript-escapes#unicode-code-point)
148 * instead of using separate escape sequences for each surrogate half. If backwards compatibility with ES5
149 * environments is a concern, don’t enable this setting. If the `json` setting is enabled, the value for the
150 * `es6` setting is ignored (as if it was `false`).
151 *
152 * @default false (disabled)
153 *
154 * @example
155 * import jsesc = require('jsesc');
156 *
157 * // By default, the `es6` option is disabled:
158 * jsesc('foo 𝌆 bar 💩 baz');
159 * // → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'
160 *
161 * // To explicitly disable it:
162 * jsesc('foo 𝌆 bar 💩 baz', {
163 * es6: false
164 * });
165 * // → 'foo \\uD834\\uDF06 bar \\uD83D\\uDCA9 baz'
166 *
167 * // To enable it:
168 * jsesc('foo 𝌆 bar 💩 baz', {
169 * es6: true
170 * });
171 * // → 'foo \\u{1D306} bar \\u{1F4A9} baz'
172 */
173 es6?: boolean | undefined;
174
175 /**
176 * When enabled, all the symbols in the output are escaped — even printable ASCII symbols.
177 * This setting also affects the output for string literals within arrays and objects.
178 *
179 * @default false (disabled)
180 *
181 * @example
182 * import jsesc = require('jsesc');
183 *
184 * jsesc('lolwat"foo\'bar', {
185 * escapeEverything: true
186 * });
187 * // → '\\x6C\\x6F\\x6C\\x77\\x61\\x74\\"\\x66\\x6F\\x6F\\\'\\x62\\x61\\x72'
188 * // → "\\x6C\\x6F\\x6C\\x77\\x61\\x74\\\"\\x66\\x6F\\x6F\\'\\x62\\x61\\x72"
189 */
190 escapeEverything?: boolean | undefined;
191
192 /**
193 * When enabled, only a limited set of symbols in the output are escaped:
194 *
195 * - U+0000 `\0`
196 * - U+0008 `\b`
197 * - U+0009 `\t`
198 * - U+000A `\n`
199 * - U+000C `\f`
200 * - U+000D `\r`
201 * - U+005C `\\`
202 * - U+2028 `\u2028`
203 * - U+2029 `\u2029`
204 * - whatever symbol is being used for wrapping string literals (based on the `quotes` option)
205 * - [lone surrogates](https://esdiscuss.org/topic/code-points-vs-unicode-scalar-values#content-14)
206 *
207 * Note: with this option enabled, jsesc output is no longer guaranteed to be ASCII-safe.
208 *
209 * @default false (disabled)
210 *
211 * @example
212 * import jsesc = require('jsesc');
213 *
214 * jsesc('foo\u2029bar\nbaz©qux𝌆flops', {
215 * minimal: false
216 * });
217 * // → 'foo\\u2029bar\\nbaz©qux𝌆flops'
218 */
219 minimal?: boolean | undefined;
220
221 /**
222 * When enabled, occurrences of [`</script` and `</style`](https://mathiasbynens.be/notes/etago) in the output
223 * are escaped as `<\/script` and `<\/style`, and [`<!--`](https://mathiasbynens.be/notes/etago#comment-8) is
224 * escaped as `\x3C!--` (or `\u003C!--` when the `json` option is enabled). This setting is useful when jsesc’s
225 * output ends up as part of a `<script>` or `<style>` element in an HTML document.
226 *
227 * @default false (disabled)
228 *
229 * @example
230 * import jsesc = require('jsesc');
231 *
232 * jsesc('foo</script>bar', {
233 * isScriptContext: true
234 * });
235 * // → 'foo<\\/script>bar'
236 */
237 isScriptContext?: boolean | undefined;
238
239 /**
240 * When enabled, the output for arrays and objects is as compact as possible; it’s not formatted nicely.
241 *
242 * @default true (enabled)
243 *
244 * @example
245 * import jsesc = require('jsesc');
246 *
247 * jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
248 * compact: true // this is the default
249 * });
250 * // → '{\'Ich \u2665 B\xFCcher\':\'foo \uD834\uDF06 bar\'}'
251 *
252 * jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
253 * compact: false
254 * });
255 * // → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
256 *
257 * jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
258 * compact: false
259 * });
260 * // → '[\n\t\'Ich \u2665 B\xFCcher\',\n\t\'foo \uD834\uDF06 bar\'\n]'
261 */
262 compact?: boolean | undefined;
263
264 /**
265 * When the `compact` setting is disabled (`false`), the value of the `indent` option is used to format the
266 * output for arrays and objects. This setting has no effect on the output for strings.
267 *
268 * @default '\t'
269 *
270 * @example
271 * import jsesc = require('jsesc');
272 *
273 * jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
274 * compact: false,
275 * indent: '\t' // this is the default
276 * });
277 * // → '{\n\t\'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
278 *
279 * jsesc({ 'Ich ♥ Bücher': 'foo 𝌆 bar' }, {
280 * compact: false,
281 * indent: ' '
282 * });
283 * // → '{\n \'Ich \u2665 B\xFCcher\': \'foo \uD834\uDF06 bar\'\n}'
284 *
285 * jsesc([ 'Ich ♥ Bücher', 'foo 𝌆 bar' ], {
286 * compact: false,
287 * indent: ' '
288 * });
289 * // → '[\n \'Ich \u2665 B\xFCcher\',\n\ t\'foo \uD834\uDF06 bar\'\n]'
290 */
291 indent?: string | undefined;
292
293 /**
294 * It represents the current indentation level, i.e. the number of times the value of the `indent` option is
295 * repeated.
296 *
297 * @default 0
298 *
299 * @example
300 * import jsesc = require('jsesc');
301 *
302 * jsesc(['a', 'b', 'c'], {
303 * compact: false,
304 * indentLevel: 1
305 * });
306 * // → '[\n\t\t\'a\',\n\t\t\'b\',\n\t\t\'c\'\n\t]'
307 *
308 * jsesc(['a', 'b', 'c'], {
309 * compact: false,
310 * indentLevel: 2
311 * });
312 * // → '[\n\t\t\t\'a\',\n\t\t\t\'b\',\n\t\t\t\'c\'\n\t\t]'
313 */
314 indentLevel?: number | undefined;
315
316 /**
317 * When enabled, the output is valid JSON.
318 * [Hexadecimal character escape sequences](https://mathiasbynens.be/notes/javascript-escapes#hexadecimal) and
319 * [the `\v` or `\0` escape sequences](https://mathiasbynens.be/notes/javascript-escapes#single) are not used.
320 * Setting `json: true` implies `quotes: 'double', wrap: true, es6: false`, although these values can still be
321 * overridden if needed — but in such cases, the output won’t be valid JSON anymore.
322 *
323 * **Note:** Using this option on objects or arrays that contain non-string values relies on `JSON.stringify()`.
324 * For legacy environments like IE ≤ 7, use [a `JSON` polyfill](http://bestiejs.github.io/json3/).
325 *
326 * @default false (disabled)
327 *
328 * @example
329 * import jsesc = require('jsesc');
330 *
331 * jsesc('foo\x00bar\xFF\uFFFDbaz', {
332 * json: true
333 * });
334 * // → '"foo\\u0000bar\\u00FF\\uFFFDbaz"'
335 *
336 * jsesc({ 'foo\x00bar\xFF\uFFFDbaz': 'foo\x00bar\xFF\uFFFDbaz' }, {
337 * json: true
338 * });
339 * // → '{"foo\\u0000bar\\u00FF\\uFFFDbaz":"foo\\u0000bar\\u00FF\\uFFFDbaz"}'
340 *
341 * jsesc([ 'foo\x00bar\xFF\uFFFDbaz', 'foo\x00bar\xFF\uFFFDbaz' ], {
342 * json: true
343 * });
344 * // → '["foo\\u0000bar\\u00FF\\uFFFDbaz","foo\\u0000bar\\u00FF\\uFFFDbaz"]'
345 *
346 * // Values that are acceptable in JSON but aren’t strings, arrays, or object
347 * // literals can’t be escaped, so they’ll just be preserved:
348 * jsesc([ 'foo\x00bar', [1, '©', { 'foo': true, 'qux': null }], 42 ], {
349 * json: true
350 * });
351 * // → '["foo\\u0000bar",[1,"\\u00A9",{"foo":true,"qux":null}],42]'
352 * // Values that aren’t allowed in JSON are run through `JSON.stringify()`:
353 * jsesc([ undefined, -Infinity ], {
354 * json: true
355 * });
356 * // → '[null,null]'
357 */
358 json?: boolean | undefined;
359
360 /**
361 * When enabled, any alphabetical hexadecimal digits in escape sequences as well as any hexadecimal integer
362 * literals (see the `numbers` option) in the output are in lowercase.
363 *
364 * @default false (disabled)
365 *
366 * @example
367 * import jsesc = require('jsesc');
368 *
369 * jsesc('Ich ♥ Bücher', {
370 * lowercaseHex: true
371 * });
372 * // → 'Ich \\u2665 B\\xfccher'
373 * // ^^
374 *
375 * jsesc(42, {
376 * numbers: 'hexadecimal',
377 * lowercaseHex: true
378 * });
379 * // → '0x2a'
380 * // ^^
381 */
382 lowercaseHex?: boolean | undefined;
383 }
384}