Expose emitter with visitors and transforms

[ivogabe]

I hope that the emitter could be exposed, like requested in #10786. I played a bit with the API, and it appeared that it could be used easily, so I made this PR. With this change, people can write tools that emit or modify JavaScript or TypeScript code. I made the following changes:

• Added a new function emit(file: SourceFile, transformers: Transformer[] = nullTransformers, newLine = "\n")
• Move code of emitFiles to createPrinter, so it can be used in emit and emitFiles
• Expose most of factory.ts, in a new namespace ts.factory.
• Expose visitEachChild
• Expose transformers api.

Examples:

import * as ts from "typescript";

const file = ts.createSourceFile("test.ts", "function foo(x) { if (x === undefined) x = 2; return x * 3; }", ts.ScriptTarget.Latest, true);

// Visitor
const file1 = visit(file) as ts.SourceFile;

console.log(ts.emit(file1).result);

function visit(node: ts.Node): ts.Node {
    if (node.kind === ts.SyntaxKind.Identifier && (node as ts.Identifier).text === "undefined") {
        return ts.factory.createVoidZero();
    }
    return ts.visitEachChild(node, visit);
}

// Transforms
const transform: ts.Transformer = context => file => {
    context.enableSubstitution(ts.SyntaxKind.Identifier);
    context.onSubstituteNode = (emitContext, node) => {
        if (node.kind === ts.SyntaxKind.Identifier && (node as ts.Identifier).text === "undefined") {
            return ts.factory.createVoidZero();
        }
    };
    return file;
}

console.log(ts.emit(file, [transform]).result);

The result of both examples is: function foo(x) { if (x === void 0)\n x = 2; return x * 3; }

Fixes #10786

[HerringtonDarkholme]

@alexeagle Angular team may find this useful.

[alexeagle]

Yes! We would love to use this. cc @evmar for angular/tsickle and @jkillian for tslint.
Also cc @chuckjaz for Angular language services

[mhegazy]

Thanks @ivogabe. We intend to expose the API in future releases, but we have some cleanup work that needs to be done first. We are doing this right now, so hopefully we should have more details on the time line for this change in the next few weeks.

[ivogabe]

Thanks for the reply, @mhegazy. Would it be possible to merge the PR before the cleanup, by temporarily marking all functions as internal? I guess that the problem is that the API will change during of the cleanup, but if all functions are marked as internal that wouldn't be a problem. Merging it earlier would prevent some merge conflicts and would allow me to use a custom build, that exposes everything, to experiment with the API, as I can't wait to use it.. Then I do need to accept the risk of future changes of course. Can you tell which parts will be refactored?

[mhegazy]

Would it be possible to merge the PR before the cleanup, by temporarily marking all functions as internal?

I would rather we clean it up first before any one uses it. i would assuming using your local copy now would be an alternative.

Can you tell which parts will be refactored?

We need to change the order of the transforms, and push some transforms out. we need to update the helper logic, and how they are handled, and we need to clean up the factory and emit interfaces.

[longlho]

@mhegazy just wanna ping you on any update for this :)

[mhegazy]

We have made a whole set of changes recently. including move stuff around into ES2017 and esNext transforms, moved module transformation to the correct place, etc... A few issues still remain, namely handling of helpers (@rbuckton has a PR for this), and handling of --out transformation which will require changing the API.

We also need to clean up the printer to be able to print any subtree, though this does not gate exposing the transformation api.

Hopefully we should be able to do this soon.

[dead-claudia]

I could see this as also very useful for implementing constant folding as a third-party module.

[ctaggart]

Any update on this @mhegazy?

[mhegazy]

Handling --out is the last remaining issue. we should have this enabled soon. sorry for the delay.

[fabiandev]

@mhegazy Is there a way to already play around with it? Or would it be an option to clone this PR and then transition to the final implementation once exposed, as I would really need this to get further in a project.

Edit:
I'm temporarily using @ivogabe's PR, which works fine for now. Thanks for that!
Looking forward to the official release :)

[ctaggart]

Can this be put on the roadmap for 2.3? May be this is somewhat related to the #1564 Generator support for ES3/ES5.

[mhegazy]

Closing in favor of #13940