Programmatic Compilation (createProgram and Hosts)

Relevant source files

• src/compiler/binder.ts
• src/compiler/checker.ts
• src/compiler/commandLineParser.ts
• src/compiler/core.ts
• src/compiler/diagnosticMessages.json
• src/compiler/emitter.ts
• src/compiler/moduleNameResolver.ts
• src/compiler/moduleSpecifiers.ts
• src/compiler/parser.ts
• src/compiler/program.ts
• src/compiler/resolutionCache.ts
• src/compiler/scanner.ts
• src/compiler/sys.ts
• src/compiler/types.ts
• src/compiler/utilities.ts
• src/harness/client.ts
• src/harness/fourslashImpl.ts
• src/harness/fourslashInterfaceImpl.ts
• src/harness/harnessLanguageService.ts
• src/server/editorServices.ts
• src/server/project.ts
• src/server/protocol.ts
• src/server/scriptInfo.ts
• src/server/scriptVersionCache.ts
• src/server/session.ts
• src/server/utilities.ts
• src/services/codefixes/importFixes.ts
• src/services/completions.ts
• src/services/exportInfoMap.ts
• src/services/findAllReferences.ts
• src/services/goToDefinition.ts
• src/services/importTracker.ts
• src/services/services.ts
• src/services/types.ts
• src/services/utilities.ts
• src/testRunner/unittests/publicApi.ts
• src/testRunner/unittests/tsserver/exportMapCache.ts
• tests/baselines/reference/api/typescript.d.ts
• tests/baselines/reference/tsserver/exportMapCache/invalidates-the-cache-when-a-file-is-opened-with-different-contents.js
• tests/cases/compiler/APILibCheck.ts
• tests/cases/fourslash/fourslash.ts
• tests/cases/fourslash/server/completionsOverridingMethodCrash2.ts

The TypeScript compiler API provides a programmatic interface for orchestrating the compilation process. This allows developers to integrate TypeScript's type checking, transformation, and code generation into custom build tools, linters, and IDE extensions. The primary entry point for this process is the Program object, which coordinates the interaction between source files, compiler options, and the host environment.

Overview of the Compilation Flow

The programmatic compilation process typically follows a standard sequence: parsing configuration, creating a host to interface with the file system, and instantiating a Program to execute the compiler phases (parsing, binding, checking, and emitting).

Data Flow Diagram

The following diagram illustrates the flow from configuration to final output.

"Compilation Data Flow"

Sources: src/compiler/program.ts1-50 src/compiler/commandLineParser.ts1-100

---

Key Entry Points

1. parseJsonConfigFileContent

Before compiling, the compiler must resolve the configuration. While CompilerOptions can be created manually, most tools use parseJsonConfigFileContent to convert a raw tsconfig.json object into a ParsedCommandLine object.

• Function: parseJsonConfigFileContent src/compiler/commandLineParser.ts1-2550
• Role: Handles inheritance (extends), resolves glob patterns in include/exclude, and validates that the options are mutually compatible.

2. createCompilerHost

The CompilerHost is an abstraction layer that the Program uses to interact with the environment (e.g., reading files, checking case sensitivity, resolving modules).

• Function: createCompilerHost(options: CompilerOptions, setParentNodes?: boolean): CompilerHost src/compiler/program.ts1000-1100
• Implementation: The default host uses sys (the system abstraction) to access the physical disk. However, for in-memory compilation (like in a web browser or test runner), a custom host can be provided.

3. createProgram

The Program is the central coordinator. It is immutable; if files change, a new Program must be created (potentially using an old program as a baseline for incremental speed).

• Function: createProgram(rootNames: readonly string[], options: CompilerOptions, host?: CompilerHost, oldProgram?: Program, configFileParsingDiagnostics?: readonly Diagnostic[]): Program src/compiler/program.ts1200-1300
• Role: Triggers the discovery of all files in the compilation unit, creates SourceFile objects via the parser, and initializes the TypeChecker.

---

The Role of Hosts

Hosts decouple the compiler logic from the underlying platform (Node.js, Browser, VS Code).

Interface	Purpose	Key Methods
System	Low-level OS abstraction.	readFile, writeFile, directoryExists
CompilerHost	High-level compiler environment.	getSourceFile, getDefaultLibFileName, resolveModuleNames
LanguageServiceHost	Used for IDE features.	getScriptSnapshot, getScriptVersion

Sources: src/compiler/sys.ts1-100 src/compiler/types.ts4000-4500

---

Implementation Detail: Program Lifecycle

The Program instance orchestrates the four main phases of the compiler.

Phase 1: Parsing

The program calls host.getSourceFile. This triggers the createSourceFile function in parser.ts, which converts text into an Abstract Syntax Tree (AST).

• Function: createSourceFile src/compiler/parser.ts50-150

Phase 2: Binding

Once the AST is ready, the Binder walks the tree to identify symbols and create the scope hierarchy. This is necessary before type checking can begin.

• Function: bindSourceFile src/compiler/binder.ts10-100

Phase 3: Type Checking

The TypeChecker is instantiated via createTypeChecker. It performs semantic analysis, calculates types, and produces Diagnostic objects.

• Function: createTypeChecker src/compiler/checker.ts100-500

Phase 4: Emit

Finally, the Emitter transforms the AST (applying transformers for things like JSX or decorators) and writes the output files.

• Function: emitFiles src/compiler/emitter.ts1-200

---

Code Entity Mapping

The following diagram maps the high-level compilation stages to the specific internal functions and classes that handle them.

"Compiler API Internal Mapping"

Sources: src/compiler/types.ts1-500 src/compiler/program.ts500-1000 src/compiler/checker.ts1-200

---

Usage Example: Minimal Programmatic Emit

This sequence demonstrates how the core functions interact to produce JavaScript output.

Sources: src/testRunner/unittests/publicApi.ts1-100 src/compiler/program.ts100-300

Diagnostic Management

Diagnostics are gathered from multiple stages:

1. Syntactic Diagnostics: Found during parsing (e.g., missing closing brace). src/compiler/parser.ts100-200
2. Global Diagnostics: Found during program initialization (e.g., conflicting compiler options). src/compiler/program.ts1500-1600
3. Semantic Diagnostics: Found during type checking (e.g., assigning a string to a number). src/compiler/checker.ts500-1000
4. Emit Diagnostics: Found during code generation (e.g., file write errors). src/compiler/emitter.ts200-300

Sources: src/compiler/program.ts1400-1800 src/compiler/types.ts1-100