uglyfly-js - npm explorer

UglyflyJS
==========

Tool to parse/compress/minify/beautify JavaScript

UglyflyJS is a fork of Mihai Bazon's UglifyJS2 library. He deserves a lion's share of the credit for the functionality provided by this.

Either library can be used for parsing, compressing, minifying, or beautifying javascript. The outputs for these libraries should be very similar or identical in most cases, but differences are explained below.

Installation and Typical Usage in Node
--------------------------------------

Enter your existing node project's directory.

Install the node module as a dependency (and save the dependency to package.json):
``npm install uglyfly-js --save`

In your code, you'll need to require uglyfly-js and pass it's minify function the appropriate arguments and callback.

The first parameter must fit one of the following descriptions:

1. A string specifying the disk filepath for the file to be minified or an array of such strings.

2. An object with a string "path" property specifying the filepath of the file and a string "contents" property with the javascript code to be minified or an array of such objects. (Note: a vinyl file has these properties.)

3. A string specifying the javascript code to be minified or an array of such strings. (Highly discouraged. Only works if using "fromString" option. Note that if you are also choosing the sourcemaps option the maps may contain bad "fakepath#.js" sources since the actual paths are not provided.)

The next parameter is optional and has the same impact as options for UglifyJS.minify's options argument. This is documented here (API Reference / The simple way). Note that options.output has a number of advanced options which are documented here on UglifyJS's website (somewhat confusingly as the "options" object). At any point where options are not passed in or are passed in as null, UglyflyJS will use sane defaults just like UglifyJS2 does.

The next and final parameter must be the callback that will receive the results.

Example:`javascript var minify = require('uglyfly').minify;

var f = '/path/to/code.js'; //see above for other formats

var options = { //see above for links to documentation about more options. output: { comments: true //minify wouldn't preserve comments in the code otherwise } };

function callback(err, data) { // do whatever you want... // err would contains info about any errors that occurred // otherwise... // data.code would be a string of the minified js code (if it was generated) // data.map would be a string of the sourcemap (if it was generated) }

minify(f, options, callback);

In addition to minify, UglyflyJS exposes beautify which is essentially the same as minify but with its default options set in such a way that it will beautify code instead.

Why use UglyflyJS over UglifyJS2?
-------------------------------

UglifyJS2 is indeed pretty great, but this fork does have some advantages.

More Node.js-friendly (more modular, more async, less hacky)

Despite UglifyJS2's general awesomeness, it currently does some kind of hacky things internally that can be problematic.

One example is that it synchronously reads in basically all its main code from disk and then loads them into a javascript vm which it then wraps and exposes. The vm part of that is a hack that was hard to avoid given the way the internal code was structured -- almost everything in all the files was defined in the global scope and assumed everything else was in there too.

Since the internal code was modularized for this fork, UglyflyJS avoids that kind of hackiness and any issues/difficulties/performance costs that might be caused by the layer of indirection (having the code running in a vm).

The modularization also allows internal components to be required directly in Node by requiring their paths. They now double as AMD modules so they can also be used in the browser more easily.

This fork also avoids the synchronous file-reads for the sourcecode and sourcemaps specified to it by filepaths. These are now all loaded asynchronously. Avoiding synchronous operations is important in Node if you want to avoid having a library block the rest of the process it's used in while the slow IO takes place.

Bug Fixes!

Everything that's fixed in UglifyJS2 as of version 2.4.17 (Mar. 10, 2015) should be fixed here as well in UglyflyJS version 3.2.2. This also contains some additional fixes for some things such as filenames/source-map handling which aren't fixed yet in UglifyJS2 (at least as of the creation of this fork).

This plays nice with named content it is passed (e.g. vinyl files which are used in tools like gulp).

Cleaner library code

Code is now modularized, as mentioned earlier. This, among other benefits, helps with dependency tracking. The code was also cleaned up in some other ways. It's significantly more jslint/jshint friendly if that's something you care about. I think its generally just easier to read/follow/debug if you ever find yourself needing to do so. The vast, vast majority of the code differences between this library and UglifyJS2 actually just come down to code reorganization and cleanup.

Easy Client-side Integration for Browsers -- No Need for Flaky Browserify Hacks

Since the core of this has been rewritten into AMD modules. It's fairly easy to get it up and running on the client-side. Check out the demo code! While browserify in itself is an impressive tool, the approach taken here requires less code and is cleaner, more flexible, and far less fragile.

Why is this being forked instead of being submitted as a pull request to UglifyJS2?
-----------------------------------------------------------------------------------

UglyflyJS was redesigned for Node.js and it's API is purposefully asynchronous whereas UglifyJS2 is synchronous.

It is technically not possible to make any asynchronous version of the functionality a drop-in replacement for UglifyJS2, because by definition, code depending on it would have to be rewritten (potentially significantly) to have the usage of the library inside a callback. This means that UglifyJS2 can't technically take advantage of non-blocking asynchronous goodness right now without causing a large breaking change to consuming code. It can of course release the code in here the next time they bump the major version, but in any case, users would be stuck in their version until they rewrite the consuming code to use a callback. UglifyJS2 is of course more than welcome to borrow code from here. The majority of the changes in this fork are to more internal code that shouldn't break their API.

What are potential shortcomings in comparison to UglifyJS2?
-----------------------------------------------------------

Asynchronous API (actually superior if consuming in a callback isn't an issue for you)

This is actually superior because it's non-blocking over IO operations, but it means that you can't use the functionality provided by passing the library synchronously. You must use a callback.

Command Line Interface Not Included

I've looked at the code for the CLI in UglifyJS2 and think it will be straightforward to tweak it to work with this. However, I honestly don't know if that functionality really belongs in this particular package.

For usage in a CLI, the asynchronous benefits of this library are less meaningful, but if significant interest is expressed for it, myself or someone else will probably create another package (with this as a dependency) which provides that functionality.

Questionable Library Name

I'm sorry. sort of. but not really.

Bug Me
------

If I missed some shortcoming or there's some other issue, create an issue for it! If some feature/fix has emerged in the main UglifyJS2 repo that this library is missing, please feel free to create an issue for that, but do link to the associated issues/commits in UglifyJS2 since it is likely to be quite helpful in getting them closed quickly! Also, please remember to mention related issues in any pull requests you send me!

I'm releasing my changes under the same license as the UglifyJS2 library it's forked from: BSD 2-Clause License