What are the core concepts covered in TypeScript Compiler API & AST Code Transformation?

The architecture of the TypeScript Compiler: Scanner (Tokens), Parser (AST), Binder (Symbols), Checker (Types), and Emitter (JS); Creating and inspecting AST nodes using `ts.createSourceFile()` and AST Explorer; Writing custom code transformers using `ts.visitNode()` and `ts.visitEachChild()`; Injecting automatic logging, performance tracing, or schema validation via compiler transformers

Advanced 26 min readModule: Module 14: TypeScript Compiler API & AST Metaprogramming

TypeScript Compiler API & AST Code Transformation

Inspect, traverse, and transform TypeScript code programmatically using the official TypeScript Compiler API, ts.createSourceFile, AST Visitor patterns, and custom transformer plugins.

What You Will Learn in This Lesson

The architecture of the TypeScript Compiler: Scanner (Tokens), Parser (AST), Binder (Symbols), Checker (Types), and Emitter (JS)
Creating and inspecting AST nodes using `ts.createSourceFile()` and AST Explorer
Writing custom code transformers using `ts.visitNode()` and `ts.visitEachChild()`
Injecting automatic logging, performance tracing, or schema validation via compiler transformers

Introduction & Core Concept

The TypeScript Compiler ('tsc') is not a black box; it is fully exposed as an open npm package ('typescript'). The TypeScript Compiler API allows developers to write custom linters, code generators, automated refactoring tools, and AST transformers (like ttypescript or ts-patch) that rewrite TypeScript syntax during the build phase.

WHY DOES THIS MATTER IN THE REAL WORLD?

Frameworks like TypeORM, NestJS, and TS-to-Zod generators use the Compiler API to extract type metadata and generate validation schemas automatically, eliminating manual sync errors.

Syntax & Structure

typescript

const sourceFile = ts.createSourceFile('file.ts', code, ts.ScriptTarget.Latest);
ts.forEachChild(sourceFile, node => { ... });

Traversing and Analyzing AST Nodes with TypeScript Compiler API

typescript

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
// TypeScript Compiler API: AST Inspection Demonstration
import ts from "typescript";
 
const sampleCode = `
  interface CourseMetadata {
    id: string;
    title: string;
    modulesCount: number;
  }
 
  function launchCourse(track: CourseMetadata): boolean {
    console.log("Launching:", track.title);
    return true;
  }
`;
 
// 1. Parse raw code into an Abstract Syntax Tree (AST) SourceFile
const sourceFile = ts.createSourceFile(
  "sample.ts",
  sampleCode,
  ts.ScriptTarget.ES2022,
  true /* setParentNodes */
);
 
console.log("=== TypeScript AST Traversal ===");
 
// 2. AST Visitor function
function inspectNode(node: ts.Node, depth: number = 0) {
  const indent = "  ".repeat(depth);
  const syntaxKindName = ts.SyntaxKind[node.kind];
 
  if (ts.isInterfaceDeclaration(node)) {
    console.log(`${indent}📦 Interface Declaration: ${node.name.text}`);
  } else if (ts.isFunctionDeclaration(node)) {
    console.log(`${indent}⚡ Function Declaration: ${node.name?.text}()`);
  } else if (ts.isPropertySignature(node)) {
    console.log(`${indent}  - Property: ${(node.name as ts.Identifier).text}`);
  }
 
  ts.forEachChild(node, (child) => inspectNode(child, depth + 1));
}
 
inspectNode(sourceFile);

Line-by-Line Technical Breakdown

1Custom Transformer Pipeline: A custom transformer (`ts.TransformerFactory<ts.SourceFile>`) intercepts AST nodes during the emit phase. You can rewrite syntax (e.g. converting decorators to wrapper functions or stripping private metadata) before emitting clean JavaScript code.

Try It Yourself (Interactive Editor)

Modify the code in real-time and click Run to test live browser output and console logs.

Intelligent Code Runner & Live Sandbox[TYPESCRIPT]

TYPESCRIPT SOURCE EDITOR

Interactive Live Code

// TypeScript Compiler API: AST Inspection Demonstration
import ts from "typescript";

const sampleCode = `
  interface CourseMetadata {
    id: string;
    title: string;
    modulesCount: number;
  }

function launchCourse(track: CourseMetadata): boolean {
    console.log("Launching:", track.title);
    return true;
  }
`;

// 1. Parse raw code into an Abstract Syntax Tree (AST) SourceFile
const sourceFile = ts.createSourceFile(
  "sample.ts",
  sampleCode,
  ts.ScriptTarget.ES2022,
  true /* setParentNodes */
);

console.log("=== TypeScript AST Traversal ===");

// 2. AST Visitor function
function inspectNode(node: ts.Node, depth: number = 0) {
  const indent = "  ".repeat(depth);
  const syntaxKindName = ts.SyntaxKind[node.kind];

if (ts.isInterfaceDeclaration(node)) {
    console.log(`${indent}📦 Interface Declaration: ${node.name.text}`);
  } else if (ts.isFunctionDeclaration(node)) {
    console.log(`${indent}⚡ Function Declaration: ${node.name?.text}()`);
  } else if (ts.isPropertySignature(node)) {
    console.log(`${indent}  - Property: ${(node.name as ts.Identifier).text}`);
  }

ts.forEachChild(node, (child) => inspectNode(child, depth + 1));
}

inspectNode(sourceFile);

>[TYPESCRIPT Runtime Initialized]

>Program compiled and executed with 0 errors.

>Output generated successfully.

Common Mistakes & How to Avoid Them

#1: Mutating existing AST nodes directly in-place instead of creating updated clone nodes with `ts.factory`.

TypeScript AST nodes are immutable structures. Always use `ts.factory.create*` or `ts.factory.update*` methods when transforming ASTs.

Incorrect / Antipattern

node.name.text = 'renamed'; // Dangerous AST corruption

Correct / Professional Solution

return ts.factory.updateFunctionDeclaration(node, ..., ts.factory.createIdentifier('renamed'), ...);

Industry Best Practices & Professional Standards

Use AST Explorer (astexplorer.net) with the TypeScript parser to inspect node hierarchy interactively.
Use `ts.factory` for creating new or modified AST nodes in transformers.
Leverage the TypeChecker (`program.getTypeChecker()`) when symbol and type resolution is required.

Lesson Summary & Core Takeaways

TypeScript Compiler API exposes Scanner, Parser, Binder, Checker, and Emitter.
AST Visitor patterns analyze and inspect code syntax programmatically.
Custom transformers modify and generate code during compilation builds.