This overhauls our node factory API to provide the following benefits:

• Allows us to leverage the factory API from within the parser.
  • This is intended to help us ensure that the property layout of each kind ofNode is stable between the parser, checker, and transformers to reduce polymorphism, as well as to provide a "single source of truth" with respect to how nodes are created.
• Allows us to streamline transform flag aggregation into node creation.
  • This allows us to remove transform flag logic frombinder.ts andtransformer.ts and ensures that transform flags willalways be correctly aggregated during transformations.
• Extracts our auto-parenthesization logic out of the node factories.
  • This allows us to use the new node factories in the parser without the undue overhead incurred by the parenthesizer rules.
• Allows us to deprecate older node factory APIs and reduce node factory overloads.

In the future, this will also allow us to better isolate which transformer was responsible for creating nodes, as well as to possibly leverage transformers outside of the emit pipeline.

As part of these changes, all of the existingcreate* andupdate* factory functions in thets namespace are being moved to aNodeFactory object that can be created via the internalcreateNodeFactory function. Authors of transformers can access theNodeFactory associated with their transformation via theTransformationContext provided to their transformer:

import*astsfrom"typescript";functionmyTransformer(context:ts.TransformationContext){// old: createIdentifier("foo");// new (option 1):const{ factory}=context;factory.createIdentifier("foo");// new (option 2):const{factory:{ createIdentifier}}=context;createIdentifier("foo");// same as old}

In addition, thets.factory object is a singletonNodeFactory instance, which can be used to create synthetic nodesoutside of a transformer.

So as not to break compatibility with older API consumers, the existingcreate* andupdate* factory functions will also be available to consumers of the TypeScript language service and the TS Server API. However, these functions are considered deprecated, and will be phased out using the following (tentative) plan:

• 4.0 - Existing factory functions are marked with a@deprecated JSDoc comment and are no longer used by TypeScript internals.
• 4.1 (?) - The first time a deprecated factory function is called, the Language Service will attempt to write a deprecation warning message (depending on the host and whether a suitableconsole.log-like logger is available).
• 4.2 (?) - Whenever a deprecated factory function is called, an exception will be thrown.
• 4.3 (?) - Deprecated factory functions will be removed.

Remaining TODO items:

• Consider renaming concise functions likecreateParen to a more expressive (and less ambiguous) name such ascreateParenthesizedExpression.
• Consider making most properties of nodesreadonly, as one goal is to treat a TypeScript AST as immutable (and should be "changed" via visitors).
• Verify performance of parser use of new API.