Adds the visitor API foundation for tree transformations.

[rbuckton]

This provides the basic foundation for tree transformations. The additions include:

• factory.ts - Which will include a growing list of node factory functions used by various transformations.
• visitor.ts - The various visitor functions used for visiting the tree.

The visitNode function is used to visit single-node branches of a tree. It also provides a facility for converting an array of nodes (in the form of a NodeArrayNode) into a single node, for cases such as converting a single-statement branch of an IterationStatement into a Block.

The visitNodes function is used to visit an array of nodes. If there are no changes to any node in the array (all visited nodes have the same reference and the same number of nodes were written), then the original array is returned. This allows for faster change detection in visitEachChild by way of reference equality checks.

The visitEachNode function is used as a fallback mechanism to recursively apply a visitor to each branch of the tree. This function leverages nodeEdgeTraversalMap, which is used to describe which properties should be traversed as well as how to verify the tree.

The LexicalEnvironment interface will be leveraged in a later revision to provide a mechanism for hoisting temporary variables and function declarations.

Examples

The following is an example of a visitor that could be used with these helpers:

function visitor(node: Node) {
  switch (node.kind) {
    case SyntaxKind.BinaryExpression:
      return visitBinaryExpression(<BinaryExpression>node);
    ...
    default:
      return visitEachChild(node, visitor);
  }
}
function visitBinaryExpression(node: BinaryExpression) {
  if (node.operatorToken.kind === SyntaxKind.AsteriskAsteriskToken) {
    return createCall(
      createPropertyAccess(createIdentifier("Math"), "pow"),
      [
        visitNode(node.left, visitor, isExpressionNode),
        visitNode(node.right, visitor, isExpressionNode)
      ]
    );
  }
  else {
    return visitEachChild(node, visitor);
  }
}

Related Pull Requests:

• Adds the visitor API foundation for tree transformations. #6892 - Adds the visitor API foundation for tree transformations.
• Adds the Transform Flags concept for tree transformations #6983 - Adds the Transform Flags concept for tree transformations.
• Adds the transformFiles API for tree transformations #6986 - Adds the transformFiles API for tree transformations.
• Adds a simplified pretty printer for tree transformations #6987 - Adds a simplified pretty printer for tree transformations.
• Adds the TypeScript transformer #7191 - Adds the TypeScript transformer.
• Adds the JSX transformer #7192 - Adds the JSX transformer.
• Adds the ES7 transformer #7193 - Adds the ES7 transformer.
• Adds the ES6 transformer #7194 - Adds the ES6 transformer.
• Adds the Module transformers #7206 - Adds the Module transformer.

[rbuckton]

@mhegazy, @ahejlsberg I will be publishing a series of pull requests targeting the transforms branch, which is a recent branch of master. This way I am able to break up this work into smaller, more easily reviewed chunks. I also will regularly merge from master into transforms to keep it in sync. Once the transformation work is fully integrated into transforms, there will be a single PR to merge transforms into master.

[rbuckton]

Another PR with the second layer of the transformations API will be published tomorrow.

[rbuckton]

CC: @yuit, @DanielRosenwasser, @RyanCavanaugh, @vladima

I want to make sure I have a lot of eyes on this implementation as we move forward.

[DanielRosenwasser]

Can you feed NodeArrayNode<T> as a type argument instead?

[rbuckton]

It would end up being createNodeArray<T | NodeArrayNode<T>, NodeArrayNode<T>>(elements)), which isn't as clear.

[rbuckton]

CC: @sandersn

[DanielRosenwasser]

Is there any reason you need to do this again instead of leveraging ts.createNode?

[rbuckton]

This is partly performance related, as the ts namespace is horribly deoptimized in v8, but also due to the fact I have a slightly different call signature.