0
# TypeScript ESTree
1
2
TypeScript ESTree is a parser that converts TypeScript source code into an ESTree-compatible Abstract Syntax Tree (AST) format. It serves as a crucial bridge between TypeScript's native compiler API and the ESTree AST specification used by JavaScript tooling ecosystems like ESLint. The parser handles TypeScript-specific syntax features including type annotations, interfaces, generics, decorators, and advanced TypeScript constructs while maintaining compatibility with ESLint's plugin architecture.
3
4
## Package Information
5
6
- **Package Name**: @typescript-eslint/typescript-estree
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @typescript-eslint/typescript-estree`
10
11
## Core Imports
12
13
```typescript
14
import { parse, parseAndGenerateServices } from "@typescript-eslint/typescript-estree";
15
import type { TSESTreeOptions, ParserServices } from "@typescript-eslint/typescript-estree";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { parse, parseAndGenerateServices } = require("@typescript-eslint/typescript-estree");
22
```
23
24
## Basic Usage
25
26
```typescript
27
import { parse, parseAndGenerateServices } from "@typescript-eslint/typescript-estree";
28
29
// Simple parsing without type information
30
const code = `const x: number = 42;`;
31
const ast = parse(code, {
32
loc: true,
33
range: true
34
});
35
36
// Full parsing with TypeScript services
37
const result = parseAndGenerateServices(code, {
38
loc: true,
39
range: true,
40
project: "./tsconfig.json"
41
});
42
43
console.log(result.ast.type); // "Program"
44
console.log(result.services.program !== null); // true if project provided
45
```
46
47
## Architecture
48
49
TypeScript ESTree is built around several key components:
50
51
- **Parser Functions**: Core parsing functions (`parse`, `parseAndGenerateServices`) for different use cases
52
- **TypeScript Program Management**: Sophisticated caching and program creation for performance
53
- **AST Conversion**: Conversion layer from TypeScript AST to ESTree-compatible format
54
- **Parser Services**: Optional type information services when working with TypeScript projects
55
- **Utility Functions**: Helper functions for AST traversal, node inspection, and version compatibility
56
- **Cache Management**: Comprehensive caching system for programs, configurations, and parsing results
57
58
## Capabilities
59
60
### Core Parsing
61
62
Primary parsing functions that convert TypeScript source code into ESTree-compatible AST format.
63
64
```typescript { .api }
65
function parse<T extends TSESTreeOptions = TSESTreeOptions>(
66
code: string,
67
options?: T
68
): AST<T>;
69
70
function parseAndGenerateServices<T extends TSESTreeOptions = TSESTreeOptions>(
71
code: string | ts.SourceFile,
72
options: T
73
): ParseAndGenerateServicesResult<T>;
74
```
75
76
[Core Parsing](./parsing.md)
77
78
### Parser Configuration
79
80
Configuration options and services for controlling parsing behavior and accessing TypeScript type information.
81
82
```typescript { .api }
83
interface TSESTreeOptions {
84
loc?: boolean;
85
range?: boolean;
86
tokens?: boolean;
87
comment?: boolean;
88
project?: boolean | string | string[] | null;
89
projectService?: boolean | ProjectServiceOptions;
90
filePath?: string;
91
jsx?: boolean;
92
// ... additional options
93
}
94
95
interface ParserServices {
96
program: ts.Program | null;
97
esTreeNodeToTSNodeMap: ParserWeakMapESTreeToTSNode;
98
tsNodeToESTreeNodeMap: ParserWeakMap<TSNode | TSToken, TSESTree.Node>;
99
// ... additional services when program available
100
}
101
```
102
103
[Parser Configuration](./configuration.md)
104
105
### TypeScript Program Management
106
107
Functions for creating and managing TypeScript programs with sophisticated caching.
108
109
```typescript { .api }
110
function createProgram(configFile: string): ts.Program;
111
function getCanonicalFileName(fileName: string): string;
112
function clearCaches(): void;
113
```
114
115
[Program Management](./program-management.md)
116
117
### AST Utilities
118
119
Utility functions for working with TypeScript and ESTree AST nodes.
120
121
```typescript { .api }
122
function simpleTraverse(
123
startingNode: TSESTree.Node,
124
options: SimpleTraverseOptions,
125
setParentPointers?: boolean
126
): void;
127
128
function getModifiers(
129
node: ts.Node | null | undefined,
130
includeIllegalModifiers?: boolean
131
): ts.Modifier[] | undefined;
132
133
function getScriptKind(filePath: string, jsx: boolean): ts.ScriptKind;
134
```
135
136
[AST Utilities](./ast-utilities.md)
137
138
### Type System Integration
139
140
Types and interfaces for working with ESTree-compatible TypeScript AST nodes and TypeScript integration.
141
142
```typescript { .api }
143
type AST<T extends TSESTreeOptions> =
144
(T['comment'] extends true ? { comments: TSESTree.Comment[] } : {}) &
145
(T['tokens'] extends true ? { tokens: TSESTree.Token[] } : {}) &
146
TSESTree.Program;
147
148
interface ParseAndGenerateServicesResult<T extends TSESTreeOptions> {
149
ast: AST<T>;
150
services: ParserServices;
151
}
152
```
153
154
[Type System](./type-system.md)
155
156
## Types
157
158
```typescript { .api }
159
// Core result types
160
type AST<T extends TSESTreeOptions> =
161
(T['comment'] extends true ? { comments: TSESTree.Comment[] } : {}) &
162
(T['tokens'] extends true ? { tokens: TSESTree.Token[] } : {}) &
163
TSESTree.Program;
164
165
interface ParseAndGenerateServicesResult<T extends TSESTreeOptions> {
166
ast: AST<T>;
167
services: ParserServices;
168
}
169
170
// Parser services union type
171
type ParserServices =
172
| ParserServicesWithoutTypeInformation
173
| ParserServicesWithTypeInformation;
174
175
// Error class for parsing errors
176
class TSError extends Error {
177
constructor(
178
message: string,
179
fileName: string,
180
location: {
181
start: { line: number; column: number; offset: number };
182
end: { line: number; column: number; offset: number };
183
}
184
);
185
}
186
187
// Version compatibility object
188
const typescriptVersionIsAtLeast: Record<'4.7' | '4.8' | '4.9' | '5.0' | '5.1' | '5.2' | '5.3' | '5.4', boolean>;
189
```