发射器

TypeScript 编译器提供了两个发射器：

  • emitter.ts：可能是你最感兴趣的发射器，它是 TS -> JavaScript 的发射器
  • declarationEmitter.ts：这个发射器用于为 TypeScript 源文件（.ts） 创建声明文件（.d.ts）
    本节我们介绍 emitter.ts

Promgram 对发射器的使用

Program 提供了一个 emit 函数。该函数主要将功能委托给 emitter.ts中的 emitFiles 函数。下面是调用栈：

  1. Program.emit ->
  2.     `emitWorker` （在 program.ts 中的 createProgram） ->
  3.         `emitFiles` （emitter.ts 中的函数）

emitWorker（通过 emitFiles 参数）给发射器提供一个 EmitResolver。 EmitResolver 由程序的 TypeChecker 提供，基本上它是一个来自 createChecker 的本地函数的子集。

发射器函数

emitFiles

定义在 emitter.ts 中，下面是该函数的签名：

  1. // targetSourceFile 当用户想发射项目中的某个文件时指定，保存时编译（compileOnSave）功能使用此参数
  2. export function emitFiles(resolver: EmitResolver, host: EmitHost, targetSourceFile?: SourceFile): EmitResult {

EmitHost 是 CompilerHost 的简化版（运行时，很多用例实际上都是 CompilerHost）

emitFiles 中的最有趣的调用栈如下所示：

  1. emitFiles ->
  2.     emitFile(jsFilePath, targetSourceFile) ->
  3.         emitJavaScript(jsFilePath, targetSourceFile);

emitJavaScript

该函数有良好的注释，我们下面给出它：

  1. function emitJavaScript(jsFilePath: string, root?: SourceFile) {
  2.   let writer = createTextWriter(newLine);
  3.   let write = writer.write;
  4.   let writeTextOfNode = writer.writeTextOfNode;
  5.   let writeLine = writer.writeLine;
  6.   let increaseIndent = writer.increaseIndent;
  7.   let decreaseIndent = writer.decreaseIndent;
  9.   let currentSourceFile: SourceFile;
  10.   // 导出器函数的名称，如果文件是个系统外部模块的话
  11.   // System.register([...], function (<exporter>) {...})
  12.   // System 模块中的导出像这样：
  13.   // export var x; ... x = 1
  14.   // =>
  15.   // var x;... exporter("x", x = 1)
  16.   let exportFunctionForFile: string;
  18.   let generatedNameSet: Map<string> = {};
  19.   let nodeToGeneratedName: string[] = [];
  20.   let computedPropertyNamesToGeneratedNames: string[];
  22.   let extendsEmitted = false;
  23.   let decorateEmitted = false;
  24.   let paramEmitted = false;
  25.   let awaiterEmitted = false;
  26.   let tempFlags = 0;
  27.   let tempVariables: Identifier[];
  28.   let tempParameters: Identifier[];
  29.   let externalImports: (ImportDeclaration | ImportEqualsDeclaration | ExportDeclaration)[];
  30.   let exportSpecifiers: Map<ExportSpecifier[]>;
  31.   let exportEquals: ExportAssignment;
  32.   let hasExportStars: boolean;
  34.   /** 将发射输出写入磁盘 */
  35.   let writeEmittedFiles = writeJavaScriptFile;
  37.   let detachedCommentsInfo: { nodePos: number; detachedCommentEndPos: number }[];
  39.   let writeComment = writeCommentRange;
  41.   /** 发射一个节点 */
  42.   let emit = emitNodeWithoutSourceMap;
  44.   /** 在发射节点前调用 */
  45.   let emitStart = function(node: Node) {};
  47.   /** 发射结点完成后调用 */
  48.   let emitEnd = function(node: Node) {};
  50.   /** 从 startPos 位置开始，为指定的 token 发射文本。默认写入的文本由 tokenKind 提供，
  51.    * 但是如果提供了可选的 emitFn 回调，将使用该回调来代替默认方式发射文本。
  52.    * @param tokenKind 要搜索并发射的 token 的类别
  53.    * @param startPos 源码中搜索 token 的起始位置
  54.    * @param emitFn 如果给出，会被调用来进行文本的发射。
  55.    */
  56.   let emitToken = emitTokenText;
  58.   /** 该函数因为节点，会在发射的代码中于函数或类中启用词法作用域前调用
  59.    * @param scopeDeclaration 启动词法作用域的节点
  60.    * @param scopeName 可选的作用域的名称，默认从节点声明中推导
  61.    */
  62.   let scopeEmitStart = function(scopeDeclaration: Node, scopeName?: string) {};
  64.   /** 出了作用域后调用 */
  65.   let scopeEmitEnd = function() {};
  67.   /** 会被编码的 Sourcemap 数据 */
  68.   let sourceMapData: SourceMapData;
  70.   if (compilerOptions.sourceMap || compilerOptions.inlineSourceMap) {
  71.     initializeEmitterWithSourceMaps();
  72.   }
  74.   if (root) {
  75.     // 不要直接调用 emit，那样不会设置 currentSourceFile
  76.     emitSourceFile(root);
  77.   } else {
  78.     forEach(host.getSourceFiles(), sourceFile => {
  79.       if (!isExternalModuleOrDeclarationFile(sourceFile)) {
  80.         emitSourceFile(sourceFile);
  81.       }
  82.     });
  83.   }
  85.   writeLine();
  86.   writeEmittedFiles(writer.getText(), /*writeByteOrderMark*/ compilerOptions.emitBOM);
  87.   return;
  89.   /// 一批本地函数
  90. }

它主要设置了一批本地变量和函数（这些函数构成 emitter.ts 的大部分内容），接着交给本地函数 emitSourceFile 发射文本。emitSourceFile 函数设置 currentSourceFile 然后交给本地函数 emit 去处理。

  1. function emitSourceFile(sourceFile: SourceFile): void {
  2.   currentSourceFile = sourceFile;
  3.   exportFunctionForFile = undefined;
  4.   emit(sourceFile);
  5. }

emit 函数处理 注释 和 实际 JavaScript 的发射。实际 JavaScript 的发射是 emitJavaScriptWorker 函数的工作。

emitJavaScriptWorker

完整的函数：

  1. function emitJavaScriptWorker(node: Node) {
  2.   // 检查节点是否可以忽略 ScriptTarget 发射
  3.   switch (node.kind) {
  4.     case SyntaxKind.Identifier:
  5.       return emitIdentifier(<Identifier>node);
  6.     case SyntaxKind.Parameter:
  7.       return emitParameter(<ParameterDeclaration>node);
  8.     case SyntaxKind.MethodDeclaration:
  9.     case SyntaxKind.MethodSignature:
  10.       return emitMethod(<MethodDeclaration>node);
  11.     case SyntaxKind.GetAccessor:
  12.     case SyntaxKind.SetAccessor:
  13.       return emitAccessor(<AccessorDeclaration>node);
  14.     case SyntaxKind.ThisKeyword:
  15.       return emitThis(node);
  16.     case SyntaxKind.SuperKeyword:
  17.       return emitSuper(node);
  18.     case SyntaxKind.NullKeyword:
  19.       return write('null');
  20.     case SyntaxKind.TrueKeyword:
  21.       return write('true');
  22.     case SyntaxKind.FalseKeyword:
  23.       return write('false');
  24.     case SyntaxKind.NumericLiteral:
  25.     case SyntaxKind.StringLiteral:
  26.     case SyntaxKind.RegularExpressionLiteral:
  27.     case SyntaxKind.NoSubstitutionTemplateLiteral:
  28.     case SyntaxKind.TemplateHead:
  29.     case SyntaxKind.TemplateMiddle:
  30.     case SyntaxKind.TemplateTail:
  31.       return emitLiteral(<LiteralExpression>node);
  32.     case SyntaxKind.TemplateExpression:
  33.       return emitTemplateExpression(<TemplateExpression>node);
  34.     case SyntaxKind.TemplateSpan:
  35.       return emitTemplateSpan(<TemplateSpan>node);
  36.     case SyntaxKind.JsxElement:
  37.     case SyntaxKind.JsxSelfClosingElement:
  38.       return emitJsxElement(<JsxElement | JsxSelfClosingElement>node);
  39.     case SyntaxKind.JsxText:
  40.       return emitJsxText(<JsxText>node);
  41.     case SyntaxKind.JsxExpression:
  42.       return emitJsxExpression(<JsxExpression>node);
  43.     case SyntaxKind.QualifiedName:
  44.       return emitQualifiedName(<QualifiedName>node);
  45.     case SyntaxKind.ObjectBindingPattern:
  46.       return emitObjectBindingPattern(<BindingPattern>node);
  47.     case SyntaxKind.ArrayBindingPattern:
  48.       return emitArrayBindingPattern(<BindingPattern>node);
  49.     case SyntaxKind.BindingElement:
  50.       return emitBindingElement(<BindingElement>node);
  51.     case SyntaxKind.ArrayLiteralExpression:
  52.       return emitArrayLiteral(<ArrayLiteralExpression>node);
  53.     case SyntaxKind.ObjectLiteralExpression:
  54.       return emitObjectLiteral(<ObjectLiteralExpression>node);
  55.     case SyntaxKind.PropertyAssignment:
  56.       return emitPropertyAssignment(<PropertyDeclaration>node);
  57.     case SyntaxKind.ShorthandPropertyAssignment:
  58.       return emitShorthandPropertyAssignment(<ShorthandPropertyAssignment>node);
  59.     case SyntaxKind.ComputedPropertyName:
  60.       return emitComputedPropertyName(<ComputedPropertyName>node);
  61.     case SyntaxKind.PropertyAccessExpression:
  62.       return emitPropertyAccess(<PropertyAccessExpression>node);
  63.     case SyntaxKind.ElementAccessExpression:
  64.       return emitIndexedAccess(<ElementAccessExpression>node);
  65.     case SyntaxKind.CallExpression:
  66.       return emitCallExpression(<CallExpression>node);
  67.     case SyntaxKind.NewExpression:
  68.       return emitNewExpression(<NewExpression>node);
  69.     case SyntaxKind.TaggedTemplateExpression:
  70.       return emitTaggedTemplateExpression(<TaggedTemplateExpression>node);
  71.     case SyntaxKind.TypeAssertionExpression:
  72.       return emit((<TypeAssertion>node).expression);
  73.     case SyntaxKind.AsExpression:
  74.       return emit((<AsExpression>node).expression);
  75.     case SyntaxKind.ParenthesizedExpression:
  76.       return emitParenExpression(<ParenthesizedExpression>node);
  77.     case SyntaxKind.FunctionDeclaration:
  78.     case SyntaxKind.FunctionExpression:
  79.     case SyntaxKind.ArrowFunction:
  80.       return emitFunctionDeclaration(<FunctionLikeDeclaration>node);
  81.     case SyntaxKind.DeleteExpression:
  82.       return emitDeleteExpression(<DeleteExpression>node);
  83.     case SyntaxKind.TypeOfExpression:
  84.       return emitTypeOfExpression(<TypeOfExpression>node);
  85.     case SyntaxKind.VoidExpression:
  86.       return emitVoidExpression(<VoidExpression>node);
  87.     case SyntaxKind.AwaitExpression:
  88.       return emitAwaitExpression(<AwaitExpression>node);
  89.     case SyntaxKind.PrefixUnaryExpression:
  90.       return emitPrefixUnaryExpression(<PrefixUnaryExpression>node);
  91.     case SyntaxKind.PostfixUnaryExpression:
  92.       return emitPostfixUnaryExpression(<PostfixUnaryExpression>node);
  93.     case SyntaxKind.BinaryExpression:
  94.       return emitBinaryExpression(<BinaryExpression>node);
  95.     case SyntaxKind.ConditionalExpression:
  96.       return emitConditionalExpression(<ConditionalExpression>node);
  97.     case SyntaxKind.SpreadElementExpression:
  98.       return emitSpreadElementExpression(<SpreadElementExpression>node);
  99.     case SyntaxKind.YieldExpression:
  100.       return emitYieldExpression(<YieldExpression>node);
  101.     case SyntaxKind.OmittedExpression:
  102.       return;
  103.     case SyntaxKind.Block:
  104.     case SyntaxKind.ModuleBlock:
  105.       return emitBlock(<Block>node);
  106.     case SyntaxKind.VariableStatement:
  107.       return emitVariableStatement(<VariableStatement>node);
  108.     case SyntaxKind.EmptyStatement:
  109.       return write(';');
  110.     case SyntaxKind.ExpressionStatement:
  111.       return emitExpressionStatement(<ExpressionStatement>node);
  112.     case SyntaxKind.IfStatement:
  113.       return emitIfStatement(<IfStatement>node);
  114.     case SyntaxKind.DoStatement:
  115.       return emitDoStatement(<DoStatement>node);
  116.     case SyntaxKind.WhileStatement:
  117.       return emitWhileStatement(<WhileStatement>node);
  118.     case SyntaxKind.ForStatement:
  119.       return emitForStatement(<ForStatement>node);
  120.     case SyntaxKind.ForOfStatement:
  121.     case SyntaxKind.ForInStatement:
  122.       return emitForInOrForOfStatement(<ForInStatement>node);
  123.     case SyntaxKind.ContinueStatement:
  124.     case SyntaxKind.BreakStatement:
  125.       return emitBreakOrContinueStatement(<BreakOrContinueStatement>node);
  126.     case SyntaxKind.ReturnStatement:
  127.       return emitReturnStatement(<ReturnStatement>node);
  128.     case SyntaxKind.WithStatement:
  129.       return emitWithStatement(<WithStatement>node);
  130.     case SyntaxKind.SwitchStatement:
  131.       return emitSwitchStatement(<SwitchStatement>node);
  132.     case SyntaxKind.CaseClause:
  133.     case SyntaxKind.DefaultClause:
  134.       return emitCaseOrDefaultClause(<CaseOrDefaultClause>node);
  135.     case SyntaxKind.LabeledStatement:
  136.       return emitLabelledStatement(<LabeledStatement>node);
  137.     case SyntaxKind.ThrowStatement:
  138.       return emitThrowStatement(<ThrowStatement>node);
  139.     case SyntaxKind.TryStatement:
  140.       return emitTryStatement(<TryStatement>node);
  141.     case SyntaxKind.CatchClause:
  142.       return emitCatchClause(<CatchClause>node);
  143.     case SyntaxKind.DebuggerStatement:
  144.       return emitDebuggerStatement(node);
  145.     case SyntaxKind.VariableDeclaration:
  146.       return emitVariableDeclaration(<VariableDeclaration>node);
  147.     case SyntaxKind.ClassExpression:
  148.       return emitClassExpression(<ClassExpression>node);
  149.     case SyntaxKind.ClassDeclaration:
  150.       return emitClassDeclaration(<ClassDeclaration>node);
  151.     case SyntaxKind.InterfaceDeclaration:
  152.       return emitInterfaceDeclaration(<InterfaceDeclaration>node);
  153.     case SyntaxKind.EnumDeclaration:
  154.       return emitEnumDeclaration(<EnumDeclaration>node);
  155.     case SyntaxKind.EnumMember:
  156.       return emitEnumMember(<EnumMember>node);
  157.     case SyntaxKind.ModuleDeclaration:
  158.       return emitModuleDeclaration(<ModuleDeclaration>node);
  159.     case SyntaxKind.ImportDeclaration:
  160.       return emitImportDeclaration(<ImportDeclaration>node);
  161.     case SyntaxKind.ImportEqualsDeclaration:
  162.       return emitImportEqualsDeclaration(<ImportEqualsDeclaration>node);
  163.     case SyntaxKind.ExportDeclaration:
  164.       return emitExportDeclaration(<ExportDeclaration>node);
  165.     case SyntaxKind.ExportAssignment:
  166.       return emitExportAssignment(<ExportAssignment>node);
  167.     case SyntaxKind.SourceFile:
  168.       return emitSourceFileNode(<SourceFile>node);
  169.   }
  170. }

通过简单地调用相应的 emitXXX 函数来完成递归，例如 emitFunctionDeclaration

  1. function emitFunctionDeclaration(node: FunctionLikeDeclaration) {
  2.   if (nodeIsMissing(node.body)) {
  3.     return emitOnlyPinnedOrTripleSlashComments(node);
  4.   }
  6.   if (node.kind !== SyntaxKind.MethodDeclaration && node.kind !== SyntaxKind.MethodSignature) {
  7.     // 会把注释当做方法声明的一部分去发射。
  8.     emitLeadingComments(node);
  9.   }
  11.   // 目标为 es6 之前时，使用 function 关键字来发射类函数（functions-like）声明，包括箭头函数
  12.   // 目标为 es6 时，可以发射原生的 ES6 箭头函数，并使用宽箭头代替 function 关键字.
  13.   if (!shouldEmitAsArrowFunction(node)) {
  14.     if (isES6ExportedDeclaration(node)) {
  15.       write('export ');
  16.       if (node.flags & NodeFlags.Default) {
  17.         write('default ');
  18.       }
  19.     }
  21.     write('function');
  22.     if (languageVersion >= ScriptTarget.ES6 && node.asteriskToken) {
  23.       write('*');
  24.     }
  25.     write(' ');
  26.   }
  28.   if (shouldEmitFunctionName(node)) {
  29.     emitDeclarationName(node);
  30.   }
  32.   emitSignatureAndBody(node);
  33.   if (
  34.     languageVersion < ScriptTarget.ES6 &&
  35.     node.kind === SyntaxKind.FunctionDeclaration &&
  36.     node.parent === currentSourceFile &&
  37.     node.name
  38.   ) {
  39.     emitExportMemberAssignments((<FunctionDeclaration>node).name);
  40.   }
  41.   if (node.kind !== SyntaxKind.MethodDeclaration && node.kind !== SyntaxKind.MethodSignature) {
  42.     emitTrailingComments(node);
  43.   }
  44. }

发射器源映射（SourceMaps）

如前所述 emitter.ts 的大部分是本地函数 emitJavaScript（我们之前展示过该函数的初始化例程）。它主要是设置一批本地变量并交给 emitSourceFile 处理。下面我们再看一遍这个函数，这次我们重点关注 SourceMap 的部分：

  1. function emitJavaScript(jsFilePath: string, root?: SourceFile) {
  3.     // 无关代码 ........... 已移除
  4.     let writeComment = writeCommentRange;
  6.     /** 将发射的输出写到磁盘上 */
  7.     let writeEmittedFiles = writeJavaScriptFile;
  9.     /** 发射一个节点 */
  10.     let emit = emitNodeWithoutSourceMap;
  12.     /** 节点发射前调用 */
  13.     let emitStart = function (node: Node) { };
  15.     /** 节点发射完成后调用 */
  16.     let emitEnd = function (node: Node) { };
  18.     /** 从 startPos 位置开始，为指定的 token 发射文本。默认写入的文本由 tokenKind 提供，
  19.       * 但是如果提供了可选的 emitFn 回调，将使用该回调来代替默认方式发射文本。
  20.       * @param tokenKind 要搜索并发射的 token 的类别
  21.       * @param startPos 源码中搜索 token 的起始位置
  22.       * @param emitFn 如果给出，会被调用来进行文本的发射。*/
  23.     let emitToken = emitTokenText;
  25.     /** 该函数因为节点，会在发射的代码中于函数或类中启用词法作用域前调用
  26.       * @param scopeDeclaration 启动词法作用域的节点
  27.       * @param scopeName 可选的作用域的名称，默认从节点声明中推导
  28.       */
  29.     let scopeEmitStart = function(scopeDeclaration: Node, scopeName?: string) { };
  31.     /** 出了作用域后调用 */
  32.     let scopeEmitEnd = function() { };
  34.     /** 会被编码的 Sourcemap 数据 */
  35.     let sourceMapData: SourceMapData;
  37.     if (compilerOptions.sourceMap || compilerOptions.inlineSourceMap) {
  38.         initializeEmitterWithSourceMaps();
  39.     }
  41.     if (root) {
  42.         // 不要直接调用 emit，那样不会设置 currentSourceFile
  43.         emitSourceFile(root);
  44.     }
  45.     else {
  46.         forEach(host.getSourceFiles(), sourceFile => {
  47.             if (!isExternalModuleOrDeclarationFile(sourceFile)) {
  48.                 emitSourceFile(sourceFile);
  49.             }
  50.         });
  51.     }
  53.     writeLine();
  54.     writeEmittedFiles(writer.getText(), /*writeByteOrderMark*/ compilerOptions.emitBOM);
  55.     return;

重要的函数调用是 initializeEmitterWithSourceMaps，该函数是 emitJavaScript 的本地函数，它覆盖了部分已定义的本地函数。覆盖的函数可以在 initalizeEmitterWithSourceMap 的底部找到：

  1. // `initializeEmitterWithSourceMaps` 函数的最后部分
  3. writeEmittedFiles = writeJavaScriptAndSourceMapFile;
  4. emit = emitNodeWithSourceMap;
  5. emitStart = recordEmitNodeStartSpan;
  6. emitEnd = recordEmitNodeEndSpan;
  7. emitToken = writeTextWithSpanRecord;
  8. scopeEmitStart = recordScopeNameOfNode;
  9. scopeEmitEnd = recordScopeNameEnd;
  10. writeComment = writeCommentRangeWithMap;

就是说大部分的发射器代码不关心 SourceMap，它们以相同的方式使用这些（带或不带 SourceMap 的）本地函数。

原文: https://jkchao.github.io/typescript-book-chinese/compiler/emitter.html