Uglifyjs: [3.x] deprecate low level API?

[kzc]

@alexlamsl Just throwing the idea out there... feel free to close issue if you disagree.

Consider deprecating the error-prone low level API in the 3.x release in favor of minify(). Otherwise upstream projects will continue to use the error-prone low level API.

To accomplish this goal, I propose prepending an underscore to all low level API names (i.e.: parse becomes _parse) and have minify() optionally accept and produce an AST in lieu of JS input(s). For bonus points the old low level API method names can throw an exception "Low level API functions not available in 3.x - use minify() instead".

AST node class names, utility functions, and traversers like TreeWalker can remain as is, as some uglify users analyze the AST.

[alexlamsl]

Not a bad idea at all. I think if we remove the lines from tools/export.js they will become invisible to any external users.

I am thinking of letting 3.0 out and see how grunt, webpack etc. copes with the new changes, and then when we are sure those older APIs are no longer needed, remove their export statements in 3.1.

AST node class names, utility functions, and traversers like TreeWalker can remain as is, as some uglify users analyze the AST.

I use the AST APIs in my projects, so yes they do make sense to be kept around :+1:

[kzc]

I am thinking of letting 3.0 out and see how grunt, webpack etc. copes with the new changes, and then when we are sure those older APIs are no longer needed, remove their export statements in 3.1.

I don't think that's a good idea. People will attempt to use the low level API in existing projects because it is less work. Then they will complain that the API is not 2.x compatible.

[alexlamsl]

I would be impressed, given the lack of documentation (that section is removed in 3.x IIRC), if they would manage to find and use the low level APIs.

But you have a point about accidental misuse (and the subsequent angry letters...), so I guess I'll rename them with an underscore as you suggested to prevent any inertia from 2.x migration, and then remove them completely in the near future.

[kzc]

I would be impressed, given the lack of documentation (that section is removed in 3.x IIRC), if they would manage to find and use the low level APIs.

Existing projects using the low level API (or projects forked from them) won't read the new documentation. Are you new to GitHub? :-)

I guess I'll rename them with an underscore as you suggested to prevent any inertia from 2.x migration

Thanks. I think it would save everyone a lot of grief.

[alexlamsl]

Are you new to GitHub?

Being part of Borg, I am relatively new to this concept of community with individuals. :robot:

Thanks. I think it would save everyone a lot of grief.

I'll get a PR and 3.0.1 ready after finishing my current task, which is merging harmony.