AST, Types, Symbols, and Node Factory APIs

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/factory/nodeFactory.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/compiler/utilitiesPublic.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/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/fourslash/fourslash.ts
• tests/cases/fourslash/server/completionsOverridingMethodCrash2.ts

This page documents the core data structures and APIs that developers interact with when using the TypeScript Compiler API. Understanding the relationship between the Abstract Syntax Tree (AST), the Type System (Types, Symbols, Signatures), and the Node Factory is essential for building tools like linters, refactoring engines, or custom transformers.

1. Abstract Syntax Tree (AST)

The AST is the foundational representation of source code. Every element in the source file, from a variable declaration to a semicolon, is represented as a Node.

SourceFile and Node Structure

A SourceFile is the root node of an AST representing a single file. It contains a collection of statements and metadata about the file (e.g., file name, language version).

• Node: The base interface for all AST elements src/compiler/types.ts743-772 Every node has a kind (of type SyntaxKind), a pos (start position), and an end position src/compiler/types.ts28-31
• SyntaxKind: An enumeration defining all possible types of nodes, tokens, and keywords src/compiler/types.ts40-420
• NodeFlags: Bitwise flags describing properties of a node, such as whether it was generated by a transform or contains a parse error src/compiler/types.ts654-706

AST Traversal

The primary way to interact with the AST is through traversal functions:

• forEachChild: Invokes a callback for each immediate child of a node src/compiler/utilities.ts156
• findAncestor: Walks up the parent pointers to find a node matching a predicate src/compiler/utilities.ts146

Natural Language to Code Entity: AST

The following diagram maps common code constructs to their internal TypeScript AST representations.

Sources: src/compiler/types.ts40-420 src/compiler/parser.ts1-300

---

2. Symbols, Types, and Signatures

While the AST represents the syntax, the Type System represents the semantics. These objects are managed by the TypeChecker.

Symbols

A Symbol represents a named declaration. Multiple declarations can contribute to the same symbol (e.g., a namespace and an interface with the same name).

• Definition: src/compiler/types.ts4460-4478
• SymbolFlags: Describe what the symbol represents (e.g., Function, BlockScopedVariable, Interface) src/compiler/types.ts4365-4458

Types

A Type represents the TypeScript type assigned to an expression or symbol.

• Definition: src/compiler/types.ts4550-4573
• ObjectFlags: Differentiate between various object types like Interface, Reference, or Anonymous src/compiler/types.ts4503-4541

Signatures

A Signature represents a call, construct, or index signature.

• Definition: src/compiler/types.ts4746-4765

Natural Language to Code Entity: Semantic Objects

This diagram illustrates how the compiler bridges a syntax node to its semantic meaning.

Sources: src/compiler/checker.ts1-135 src/compiler/types.ts4460-4765

---

3. TypeChecker API

The TypeChecker is the central engine for semantic queries. It is obtained via program.getTypeChecker() src/compiler/program.ts50

Function	Purpose
getSymbolAtLocation(node)	Retrieves the Symbol associated with a specific AST node.
getTypeAtLocation(node)	Determines the Type of an expression node.
getPropertiesOfType(type)	Returns an array of Symbol objects representing the members of a type.
getSignatureFromDeclaration(node)	Gets the Signature for a function-like declaration.
getDiagnostics()	Triggers full semantic analysis and returns errors.

Sources: src/compiler/checker.ts117-135 src/compiler/types.ts4800-5300

---

4. Node Factory API

The NodeFactory is the API used to create or update AST nodes. This is the only supported way to construct AST for use in transformers or code generation.

Key Characteristics

• Immutability: Nodes are generally treated as immutable. To "change" a node, you use factory.update... methods which return a new node if changes are necessary.
• Entry Point: Accessed via ts.factory or through the TransformationContext in a transformer src/compiler/factory/nodeFactory.ts1-100

Common Factory Methods

• factory.createIdentifier(text): Creates a new identifier src/compiler/types.ts3100-3150
• factory.createVariableStatement(modifiers, declarationList): Creates a const/let/var statement.
• factory.updateBlock(node, statements): Updates an existing block with new statements.

Data Flow: Node Construction

Sources: src/compiler/factory/nodeFactory.ts1-200 src/compiler/types.ts11-19

---

5. Summary Table: Data Object Relationships

Object	Created By	Lifetime	Role
Node	Parser / NodeFactory	Source-to-Emit	Syntactic representation of a code fragment.
Symbol	Binder	Compilation	Links declarations to a unique semantic identity.
Type	TypeChecker	On-demand (Lazy)	Represents the static type used for validation/inference.
Signature	TypeChecker	On-demand	Represents how a function or constructor can be called.

Sources: src/compiler/parser.ts1-100 src/compiler/binder.ts1-50 src/compiler/checker.ts1-135