Expose printing functionality of emitter as a public API

[rbuckton]

This exposes a new public createPrinter export on the ts namespace that can be used to print a TypeScript AST as-is (without transformation):

// public API
declare namespace ts {
  // subset of CompilerOptions
  interface PrinterOptions {
    target?: ScriptTarget;
    removeComments?: boolean;
    newLine?: NewLineKind;
  }

  // custom hooks for name generation, emit notification, and substitution
  interface PrintHandlers {
    hasGlobalName?: (name: string) => boolean;
    onEmitNode?: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void;
    onSubstituteNode?: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void;
  }

  // printer service
  interface Printer {
    printNode(hint: EmitHint, node: Node, sourceFile: SourceFile): string;
    printFile(sourceFile: SourceFile): string;
    printBundle(bundle: Bundle): string;
  }
  
  // printer factory
  function createPrinter(printerOptions?: PrinterOptions, handlers?: PrintHandlers): Printer;

  // bundles output (for --outFile)
  interface Bundle extends Node {
    kind: SyntaxKind.Bundle;
    sourceFiles: SourceFile[];
  }
}

To support our internal emit needs, we also have the following internal API for printing:

// internal API
declare namespace ts {
  // internal hooks to support source map and helper emit
  interface PrintHandlers {
    /*@internal*/ onEmitSourceMapOfNode?: (hint: EmitHint, node: Node, emitCallback: (hint: EmitHint, node: Node) => void) => void;
    /*@internal*/ onEmitSourceMapOfToken?: (node: Node, token: SyntaxKind, pos: number, emitCallback: (token: SyntaxKind, pos: number) => number) => number;
    /*@internal*/ onEmitSourceMapOfPosition?: (pos: number) => void;
    /*@internal*/ onEmitHelpers?: (node: Node, writeLines: (text: string) => void) => void;
    /*@internal*/ onSetSourceFile?: (node: SourceFile) => void;
  }

  // subset of compiler options needed to support source map emit
  export interface PrinterOptions {
    /*@internal*/ sourceMap?: boolean;
    /*@internal*/ inlineSourceMap?: boolean;
    /*@internal*/ extendedDiagnostics?: boolean;
  }

  // print a node, file, or bundle to an existing EmitTextWriter
  export interface Printer {
    /*@internal*/ writeNode(hint: EmitHint, node: Node, sourceFile: SourceFile, writer: EmitTextWriter): void;
    /*@internal*/ writeFile(sourceFile: SourceFile, writer: EmitTextWriter): void;
    /*@internal*/ writeBundle(bundle: Bundle, writer: EmitTextWriter): void;
  }  
}

The public API for printing does not support source maps currently as this is heavily tied into the emitter. We may choose to support this via a later PR.

This further extends the work started in #5595 with the overall goal of making significant portions of the new transformation and emit pipeline part of the public API. This is also intended to help support ongoing effort into refactoring and code actions.

Fixes #13762

[sandersn]

Can you explain the changes in emitter.ts a bit more? I see the reorganisation to expose the new public API, but it looks like there's two other things going on too:

1. Refactor the pipeline* internals To make them more obviously asynchronous or something? It looks like what I would call continuation-passing style, which it didn't beforehand.
2. Other small improvements inside, for example, emitSignatureAndBody and emitTypeAssertionExpression and the rest of the file. I think these are unrelated to the API change.

Am I totally off-base about (1) and (2)? I think more explanation would help me.

[vladima]

why this check (and other checks below) are necessary? If emitPos can be undefined, can you please reflect this in its type?

[rbuckton]

Source map support is not currently exposed publicly, so a printer created through the public API would not be able to provide an emitPos callback. I'll amend the parameter to include undefined.

[mhegazy]

LGTM, I would like to know the plan for making the transforms API public as well, and how it would be used with the printer

[mhegazy]

Please add some comments on how the callbacks are used.

[rbuckton]

@mhegazy The tasks involved in making the API public can be found here.

[rbuckton]

@sandersn both (1) and (2) are incorrect, there were no changes to that functionality of emitter, other than moving createPrinter out of emitFiles. Github is just showing a significant amount of changes due to some minor reorganization as most of the existing functions were moved down and emitHelpers was moved up as they are now in different closures.

[zpdDG4gta8XKpMCd]

nice