TypeScript Compiler API

TypeScript v5.9.3 provides a comprehensive compiler API with 1,683+ public API members for programmatically analyzing, transforming, and emitting JavaScript code.

Quick Start

Installation and Import

import * as ts from 'typescript';
// or
const ts = require('typescript');

Essential Pattern

import * as ts from 'typescript';

// 1. Parse source code into AST
const sourceFile = ts.createSourceFile(
  'example.ts',
  'const x: number = 42;',
  ts.ScriptTarget.Latest,
  true
);

// 2. Create program for type checking
const program = ts.createProgram({
  rootNames: ['example.ts'],
  options: { target: ts.ScriptTarget.ES2020 }
});

// 3. Get type checker
const checker = program.getTypeChecker();

// 4. Traverse AST
function visit(node: ts.Node) {
  console.log(ts.SyntaxKind[node.kind]);
  ts.forEachChild(node, visit);
}
visit(sourceFile);

// 5. Emit JavaScript
const emitResult = program.emit();

Common Tasks

Task: Parse and Analyze Code

Goal: Parse TypeScript source code and analyze its structure.

Pattern:

1. Use createSourceFile() to parse code into AST
2. Use createProgram() for type checking
3. Use program.getTypeChecker() for type analysis
4. Traverse AST with forEachChild() or visitNode()

APIs:

• createSourceFile() - Parse source text into AST
• createProgram() - Create compilation program
• program.getTypeChecker() - Get type checker for semantic analysis
• forEachChild() - Traverse AST nodes

See: Core Compilation APIs | AST Nodes | Type System

Task: Transform Code

Goal: Modify TypeScript code programmatically.

Pattern:

1. Create transformer factory function
2. Use transform() or integrate with program.emit() via CustomTransformers
3. Use TransformationContext.factory to create/modify nodes
4. Use visitEachChild() to traverse and transform

APIs:

• transform() - Apply transformers to source files
• TransformerFactory - Create custom transformers
• TransformationContext.factory - Node factory for transformations
• visitEachChild() - Visit and transform child nodes

See: Transformation | Node Factory

Task: Generate Code

Goal: Programmatically generate TypeScript code.

Pattern:

1. Use factory constant to create AST nodes
2. Build complete AST structure
3. Use Printer to convert AST to source code
4. Or use program.emit() to generate JavaScript

APIs:

• factory - Node factory (300+ methods)
• createPrinter() - Create printer for AST to source conversion
• program.emit() - Emit JavaScript output

See: Node Factory | Utilities

Task: Provide IDE Features

Goal: Implement editor features like completions, diagnostics, refactorings.

Pattern:

1. Create LanguageServiceHost implementation
2. Use createLanguageService() to create service
3. Call methods like getCompletionsAtPosition(), getQuickInfoAtPosition()
4. Update host when files change

APIs:

• createLanguageService() - Create language service
• LanguageService - 100+ methods for IDE features
• LanguageServiceHost - Host interface for file operations

See: Language Service

Task: Resolve Modules

Goal: Resolve module imports and type references.

Pattern:

1. Use resolveModuleName() for module resolution
2. Use resolveTypeReferenceDirective() for type references
3. Implement ModuleResolutionHost for file system operations
4. Use ModuleResolutionCache for performance

APIs:

• resolveModuleName() - Resolve module imports
• resolveTypeReferenceDirective() - Resolve type references
• ModuleResolutionHost - File system interface

See: Module Resolution

Task: Build Projects

Goal: Build TypeScript projects with incremental compilation.

Pattern:

1. Use createSolutionBuilder() for multi-project builds
2. Configure project references in tsconfig.json
3. Use incremental compilation with BuilderProgram
4. Handle diagnostics and emit results

APIs:

• createSolutionBuilder() - Multi-project builds
• createIncrementalProgram() - Incremental compilation
• BuilderProgram - Incremental program interface

See: Solution Builder | Core Compilation

Core Architecture

TypeScript's compiler API consists of these major subsystems:

1. Parser & Scanner: Lexical analysis and AST construction
2. Binder: Symbol creation and scope analysis
3. Type Checker: Type inference, checking, and semantic analysis
4. Transformer: AST transformation pipeline
5. Emitter: JavaScript and declaration file generation
6. Language Service: Editor integration (completions, diagnostics, refactorings)
7. Module Resolution: Resolving imports and type references
8. Server Protocol: TSServer communication

API Reference by Category

Core Compilation

• Compilation APIs - Program creation, compilation, emit
• Module Resolution - Import and type resolution
• Solution Builder - Multi-project builds
• Configuration Parsing - tsconfig.json parsing

AST Manipulation

• AST Nodes - Node types and traversal (359 syntax kinds)
• Node Factory - Creating AST nodes (300+ methods)
• Scanner and Parser - Lexical analysis and parsing
• Type Guards - Type guard functions for all node types

Type System

• Type Checker - TypeChecker API (150+ methods)
• Types and Symbols - Type and Symbol interfaces
• Type Utilities - Type analysis utilities
• Diagnostics - Error reporting and diagnostics

Code Transformation

• Transformers - AST transformation pipeline
• Transformation Context - Transformation context API
• Emit Helpers - Runtime helper utilities

Editor Integration

• Language Service - IDE features (100+ methods)
• Completions - Code completion APIs
• Navigation - Go to definition, find references
• Refactorings - Code refactoring APIs
• Formatting - Code formatting APIs
• TSServer Protocol - Language server protocol

Utilities

• System Interface - File system operations
• Printer - AST to source code conversion
• Transpilation - Quick TypeScript to JavaScript conversion
• Path Utilities - Path manipulation functions
• Text Utilities - Text and position utilities

Essential APIs

Program Creation

function createProgram(
  rootNames: readonly string[],
  options: CompilerOptions,
  host?: CompilerHost,
  oldProgram?: Program,
  configFileParsingDiagnostics?: readonly Diagnostic[]
): Program;

interface Program {
  getRootFileNames(): readonly string[];
  getSourceFiles(): readonly SourceFile[];
  getSourceFile(fileName: string): SourceFile | undefined;
  getTypeChecker(): TypeChecker;
  emit(
    targetSourceFile?: SourceFile,
    writeFile?: WriteFileCallback,
    cancellationToken?: CancellationToken,
    emitOnlyDtsFiles?: boolean,
    customTransformers?: CustomTransformers
  ): EmitResult;
  getSemanticDiagnostics(sourceFile?: SourceFile): readonly Diagnostic[];
  getSyntacticDiagnostics(sourceFile?: SourceFile): readonly Diagnostic[];
  getCompilerOptions(): CompilerOptions;
}

AST Nodes and Traversal

enum SyntaxKind {
  Unknown = 0,
  Identifier = 80,
  // ... 359 syntax kinds total
}

interface Node {
  readonly kind: SyntaxKind;
  readonly flags: NodeFlags;
  readonly parent: Node;
  getSourceFile(): SourceFile;
  getText(sourceFile?: SourceFile): string;
  forEachChild<T>(cbNode: (node: Node) => T | undefined): T | undefined;
}

function forEachChild<T>(
  node: Node,
  cbNode: (node: Node) => T | undefined
): T | undefined;

Type System

interface TypeChecker {
  getTypeAtLocation(node: Node): Type;
  getSymbolAtLocation(node: Node): Symbol | undefined;
  getTypeOfSymbolAtLocation(symbol: Symbol, node: Node): Type;
  getPropertiesOfType(type: Type): Symbol[];
  getSignaturesOfType(type: Type, kind: SignatureKind): readonly Signature[];
  typeToString(type: Type, enclosingDeclaration?: Node, flags?: TypeFormatFlags): string;
  // ... 150+ more methods
}

interface Type {
  flags: TypeFlags;
  symbol: Symbol;
  getProperties(): Symbol[];
  getCallSignatures(): readonly Signature[];
}

Node Factory

const factory: NodeFactory;

interface NodeFactory {
  createSourceFile(statements: readonly Statement[], endOfFileToken: EndOfFileToken, flags: NodeFlags): SourceFile;
  createIdentifier(text: string): Identifier;
  createVariableStatement(modifiers: readonly Modifier[] | undefined, declarationList: VariableDeclarationList): VariableStatement;
  createFunctionDeclaration(modifiers: readonly ModifierLike[] | undefined, asteriskToken: AsteriskToken | undefined, name: string | Identifier | undefined, typeParameters: readonly TypeParameterDeclaration[] | undefined, parameters: readonly ParameterDeclaration[], type: TypeNode | undefined, body: Block | undefined): FunctionDeclaration;
  // ... 300+ more factory functions
}

Language Service

function createLanguageService(
  host: LanguageServiceHost,
  documentRegistry?: DocumentRegistry,
  syntaxOnlyOrLanguageServiceMode?: boolean | LanguageServiceMode
): LanguageService;

interface LanguageService {
  getCompletionsAtPosition(fileName: string, position: number, options?: GetCompletionsAtPositionOptions): WithMetadata<CompletionInfo> | undefined;
  getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined;
  getDefinitionAtPosition(fileName: string, position: number): readonly DefinitionInfo[] | undefined;
  findReferences(fileName: string, position: number): ReferencedSymbol[] | undefined;
  getApplicableRefactors(fileName: string, positionOrRange: number | TextRange, preferences?: UserPreferences): ApplicableRefactorInfo[];
  // ... 100+ more methods
}

Transformation

type TransformerFactory<T extends Node> = (
  context: TransformationContext
) => Transformer<T>;

type Transformer<T extends Node> = (node: T) => T;

interface TransformationContext {
  factory: NodeFactory;
  getCompilerOptions(): CompilerOptions;
  hoistFunctionDeclaration(node: FunctionDeclaration): void;
  hoistVariableDeclaration(node: Identifier): void;
  requestEmitHelper(helper: EmitHelper): void;
  enableSubstitution(kind: SyntaxKind): void;
  enableEmitNotification(kind: SyntaxKind): void;
}

function transform<T extends Node>(
  source: T | T[],
  transformers: TransformerFactory<T>[],
  compilerOptions?: CompilerOptions
): TransformationResult<T>;

Key Enumerations

• SyntaxKind (359 values) - All AST node types
• TypeFlags - Type classification flags
• SymbolFlags - Symbol classification flags
• ScriptTarget - JavaScript target versions
• ModuleKind - Module system types
• ModuleResolutionKind - Module resolution strategies
• DiagnosticCategory - Error, Warning, Suggestion, Message
• NodeFlags - Node metadata flags

Version Information

TypeScript v5.9.3 includes:

• 64 enumerations
• 803 interfaces
• 269 type aliases
• 510 functions
• 21 constants
• 10 classes
• 6 namespaces

Getting Help

For specific tasks:

• Parsing code: See Scanner and Parser
• Type checking: See Type System
• Code transformation: See Transformation
• Building projects: See Solution Builder
• IDE features: See Language Service
• Module resolution: See Module Resolution