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
```