aboutsummaryrefslogtreecommitdiff
path: root/node_modules/uglify-js/README.md
diff options
context:
space:
mode:
authorFlorian Dold <florian.dold@gmail.com>2018-09-20 02:56:13 +0200
committerFlorian Dold <florian.dold@gmail.com>2018-09-20 02:56:13 +0200
commitbbff7403fbf46f9ad92240ac213df8d30ef31b64 (patch)
treec58400ec5124da1c7d56b01aea83309f80a56c3b /node_modules/uglify-js/README.md
parent003fb34971cf63466184351b4db5f7c67df4f444 (diff)
update packages
Diffstat (limited to 'node_modules/uglify-js/README.md')
-rw-r--r--node_modules/uglify-js/README.md97
1 files changed, 66 insertions, 31 deletions
diff --git a/node_modules/uglify-js/README.md b/node_modules/uglify-js/README.md
index 8a34f6e49..a08a36dfa 100644
--- a/node_modules/uglify-js/README.md
+++ b/node_modules/uglify-js/README.md
@@ -6,9 +6,8 @@ UglifyJS is a JavaScript parser, minifier, compressor and beautifier toolkit.
#### Note:
- **`uglify-js@3` has a simplified [API](#api-reference) and [CLI](#command-line-usage) that is not backwards compatible with [`uglify-js@2`](https://github.com/mishoo/UglifyJS2/tree/v2.x)**.
- **Documentation for UglifyJS `2.x` releases can be found [here](https://github.com/mishoo/UglifyJS2/tree/v2.x)**.
-- `uglify-js` only supports ECMAScript 5 (ES5).
-- Those wishing to minify
-ES2015+ (ES6+) should use the `npm` package [**uglify-es**](https://github.com/mishoo/UglifyJS2/tree/harmony).
+- `uglify-js` only supports JavaScript (ECMAScript 5).
+- To minify ECMAScript 2015 or above, transpile using tools like [Babel](https://babeljs.io/).
Install
-------
@@ -70,7 +69,7 @@ a double dash to prevent input files being used as option arguments:
`debug` Add debug prefix and suffix.
`domprops` Mangle property names that overlaps
with DOM properties.
- `keep_quoted` Only mangle unquoted properies.
+ `keep_quoted` Only mangle unquoted properties.
`regex` Only mangle matched property names.
`reserved` List of names that should not be mangled.
-b, --beautify [options] Beautify output/specify output options:
@@ -105,6 +104,8 @@ a double dash to prevent input files being used as option arguments:
sequences.
--config-file <file> Read `minify()` options from JSON file.
-d, --define <expr>[=value] Global definitions.
+ -e, --enclose [arg[:value]] Embed everything in a big function, with configurable
+ argument(s) & value(s).
--ie8 Support non-standard Internet Explorer 8.
Equivalent to setting `ie8: true` in `minify()`
for `compress`, `mangle` and `output` options.
@@ -119,7 +120,8 @@ a double dash to prevent input files being used as option arguments:
JS that was generated from some other original
code. Specify "inline" if the source map is
included within the sources.
- `filename` Name and/or location of the output source.
+ `filename` Filename and/or location of the output source
+ (sets `file` attribute in source map).
`includeSources` Pass this flag if you want to include
the content of source files in the
source map as sourcesContent property.
@@ -150,7 +152,9 @@ debugging your compressed JavaScript. To get a source map, pass
Additional options:
-- `--source-map "filename='<NAME>'"` to specify the name of the source map.
+- `--source-map "filename='<NAME>'"` to specify the name of the source map. The value of
+ `filename` is only used to set `file` attribute (see [the spec][sm-spec])
+ in source map file.
- `--source-map "root='<URL>'"` to pass the URL where the original files can be found.
@@ -598,24 +602,26 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
## Compress options
+- `arguments` (default: `true`) -- replace `arguments[index]` with function
+ parameter name whenever possible.
+
- `booleans` (default: `true`) -- various optimizations for boolean context,
for example `!!a ? b : c → a ? b : c`
-- `cascade` (default: `true`) -- small optimization for sequences, transform
- `x, x` into `x` and `x = something(), x` into `x = something()`
-
- `collapse_vars` (default: `true`) -- Collapse single-use non-constant variables,
side effects permitting.
- `comparisons` (default: `true`) -- apply certain optimizations to binary nodes,
- e.g. `!(a <= b) → a > b` (only when `unsafe_comps`), attempts to negate binary
- nodes, e.g. `a = !b && !c && !d && !e → a=!(b||c||d||e)` etc.
+ e.g. `!(a <= b) → a > b`, attempts to negate binary nodes, e.g.
+ `a = !b && !c && !d && !e → a=!(b||c||d||e)` etc.
- `conditionals` (default: `true`) -- apply optimizations for `if`-s and conditional
expressions
- `dead_code` (default: `true`) -- remove unreachable code
+- `directives` (default: `true`) -- remove redundant or non-standard directives
+
- `drop_console` (default: `false`) -- Pass `true` to discard calls to
`console.*` functions. If you wish to drop a specific function call
such as `console.info` and/or retain side effects from function arguments
@@ -630,7 +636,7 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
- `global_defs` (default: `{}`) -- see [conditional compilation](#conditional-compilation)
-- `hoist_funs` (default: `true`) -- hoist function declarations
+- `hoist_funs` (default: `false`) -- hoist function declarations
- `hoist_props` (default: `true`) -- hoist properties from constant object and
array literals into regular variables subject to a set of constraints. For example:
@@ -643,7 +649,13 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
- `if_return` (default: `true`) -- optimizations for if/return and if/continue
-- `inline` (default: `true`) -- embed simple functions
+- `inline` (default: `true`) -- inline calls to function with simple/`return` statement:
+ - `false` -- same as `0`
+ - `0` -- disabled inlining
+ - `1` -- inline simple functions
+ - `2` -- inline functions with arguments
+ - `3` -- inline functions with arguments and variables
+ - `true` -- same as `3`
- `join_vars` (default: `true`) -- join consecutive `var` statements
@@ -680,7 +692,8 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
pass `pure_funcs: [ 'Math.floor' ]` to let it know that this
function won't produce any side effect, in which case the whole
statement would get discarded. The current implementation adds some
- overhead (compression will be slower).
+ overhead (compression will be slower). Make sure symbols under `pure_funcs`
+ are also under `mangle.reserved` to avoid mangling.
- `pure_getters` (default: `"strict"`) -- If you pass `true` for
this, UglifyJS will assume that object property access
@@ -727,14 +740,10 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
- `unsafe` (default: `false`) -- apply "unsafe" transformations (discussion below)
-- `unsafe_comps` (default: `false`) -- Reverse `<` and `<=` to `>` and `>=` to
- allow improved compression. This might be unsafe when an at least one of two
- operands is an object with computed values due the use of methods like `get`,
- or `valueOf`. This could cause change in execution order after operands in the
- comparison are switching. Compression only works if both `comparisons` and
- `unsafe_comps` are both set to true.
+- `unsafe_comps` (default: `false`) -- compress expressions like `a <= b` assuming
+ none of the operands can be (coerced to) `NaN`.
-- `unsafe_Func` (default: `false`) -- compress and mangle `Function(args, code)`
+- `unsafe_Function` (default: `false`) -- compress and mangle `Function(args, code)`
when both `args` and `code` are string literals.
- `unsafe_math` (default: `false`) -- optimize numerical expressions like
@@ -746,6 +755,10 @@ If you're using the `X-SourceMap` header instead, you can just omit `sourceMap.u
- `unsafe_regexp` (default: `false`) -- enable substitutions of variables with
`RegExp` values the same way as if they are constants.
+- `unsafe_undefined` (default: `false`) -- substitute `void 0` if there is a
+ variable named `undefined` in scope (variable name will be mangled, typically
+ reduced to a single character)
+
- `unused` (default: `true`) -- drop unreferenced functions and variables (simple
direct variable assignments do not count as references unless set to `"keep_assign"`)
@@ -819,7 +832,7 @@ can pass additional arguments that control the code output:
when you want to generate minified code, in order to specify additional
arguments, so you can use `-b beautify=false` to override it.
-- `bracketize` (default `false`) -- always insert brackets in `if`, `for`,
+- `braces` (default `false`) -- always insert braces in `if`, `for`,
`do`, `while` or `with` statements, even if their body is a single
statement.
@@ -831,8 +844,8 @@ can pass additional arguments that control the code output:
- `indent_start` (default `0`) -- prefix all lines by that many spaces
-- `inline_script` (default `false`) -- escape the slash in occurrences of
- `</script` in strings
+- `inline_script` (default `true`) -- escape HTML comments and the slash in
+ occurrences of `</script>` in strings
- `keep_quoted_props` (default `false`) -- when turned on, prevents stripping
quotes from property names in object literals.
@@ -844,8 +857,8 @@ can pass additional arguments that control the code output:
adjust for this text. Can be used to insert a comment containing
licensing information, for example.
-- `preserve_line` (default `false`) -- pass `true` to preserve lines, but it
- only works if `beautify` is set to `false`.
+- `preserve_line` (default `false`) -- pass `true` to retain line numbering on
+ a best effort basis.
- `quote_keys` (default `false`) -- pass `true` to quote all keys in literal
objects
@@ -919,9 +932,6 @@ when this flag is on:
- `new Object()` → `{}`
- `String(exp)` or `exp.toString()` → `"" + exp`
- `new Object/RegExp/Function/Error/Array (...)` → we discard the `new`
-- `void 0` → `undefined` (if there is a variable named "undefined" in
- scope; we do it because the variable name will be mangled, typically
- reduced to a single character)
### Conditional compilation
@@ -1038,8 +1048,9 @@ var result = UglifyJS.minify(ast, {
### Working with Uglify AST
Transversal and transformation of the native AST can be performed through
-[`TreeWalker`](http://lisperator.net/uglifyjs/walk) and
-[`TreeTransformer`](http://lisperator.net/uglifyjs/transform) respectively.
+[`TreeWalker`](https://github.com/mishoo/UglifyJS2/blob/master/lib/ast.js) and
+[`TreeTransformer`](https://github.com/mishoo/UglifyJS2/blob/master/lib/transform.js)
+respectively.
### ESTree / SpiderMonkey AST
@@ -1098,3 +1109,27 @@ To enable fast minify mode with the API use:
```js
UglifyJS.minify(code, { compress: false, mangle: true });
```
+
+#### Source maps and debugging
+
+Various `compress` transforms that simplify, rearrange, inline and remove code
+are known to have an adverse effect on debugging with source maps. This is
+expected as code is optimized and mappings are often simply not possible as
+some code no longer exists. For highest fidelity in source map debugging
+disable the Uglify `compress` option and just use `mangle`.
+
+### Compiler assumptions
+
+To allow for better optimizations, the compiler makes various assumptions:
+
+- `.toString()` and `.valueOf()` don't have side effects, and for built-in
+ objects they have not been overridden.
+- `undefined`, `NaN` and `Infinity` have not been externally redefined.
+- `arguments.callee`, `arguments.caller` and `Function.prototype.caller` are not used.
+- The code doesn't expect the contents of `Function.prototype.toString()` or
+ `Error.prototype.stack` to be anything in particular.
+- Getting and setting properties on a plain object does not cause other side effects
+ (using `.watch()` or `Proxy`).
+- Object properties can be added, removed and modified (not prevented with
+ `Object.defineProperty()`, `Object.defineProperties()`, `Object.freeze()`,
+ `Object.preventExtensions()` or `Object.seal()`).