0
# Type System Integration
1

2
Types and interfaces for working with ESTree-compatible TypeScript AST nodes and TypeScript integration. This module provides the complete type system for TypeScript ESTree, including node types, token types, and conversion utilities.
3

4
## Capabilities
5

6
### Core AST Types
7

8
Fundamental types for working with ESTree-compatible TypeScript AST nodes.
9

10
```typescript { .api }
11
/**
12
 * Conditional AST type that includes optional comments and tokens based on parsing options
13
 */
14
type AST<T extends TSESTreeOptions> = 
15
  (T['comment'] extends true ? { comments: TSESTree.Comment[] } : {}) &
16
  (T['tokens'] extends true ? { tokens: TSESTree.Token[] } : {}) &
17
  TSESTree.Program;
18

19
/**
20
 * Union type of all TypeScript AST nodes  
21
 */
22
type TSNode = 
23
  | ts.ArrayBindingPattern
24
  | ts.ArrayLiteralExpression
25
  | ts.ArrowFunction
26
  | ts.AsExpression
27
  | ts.BinaryExpression
28
  | ts.Block
29
  | ts.CallExpression
30
  | ts.ClassDeclaration
31
  | ts.FunctionDeclaration
32
  | ts.Identifier
33
  | ts.IfStatement
34
  | ts.InterfaceDeclaration
35
  | ts.MethodDeclaration
36
  | ts.PropertyDeclaration
37
  | ts.TypeAliasDeclaration
38
  | ts.VariableDeclaration
39
  // ... and many more TypeScript node types
40
  ;
41

42
/**
43
 * TypeScript token type
44
 */
45
type TSToken = ts.Token<ts.SyntaxKind>;
46

47
/**
48
 * Mapping type from ESTree nodes to corresponding TypeScript nodes
49
 */
50
type TSESTreeToTSNode<T extends TSESTree.Node> = 
51
  T extends TSESTree.Program ? ts.SourceFile :
52
  T extends TSESTree.Identifier ? ts.Identifier :
53
  T extends TSESTree.FunctionDeclaration ? ts.FunctionDeclaration :
54
  // ... mappings for all node types
55
  ts.Node;
56
```
57

58
### ESTree Node and Token Types
59

60
Complete ESTree-compatible type definitions for TypeScript AST nodes.
61

62
```typescript { .api }
63
/**
64
 * ESTree AST node types enumeration
65
 */
66
enum AST_NODE_TYPES {
67
  ArrayExpression = 'ArrayExpression',
68
  ArrayPattern = 'ArrayPattern',
69
  ArrowFunctionExpression = 'ArrowFunctionExpression',
70
  AssignmentExpression = 'AssignmentExpression',
71
  BinaryExpression = 'BinaryExpression',
72
  BlockStatement = 'BlockStatement',
73
  CallExpression = 'CallExpression',
74
  ClassDeclaration = 'ClassDeclaration',
75
  FunctionDeclaration = 'FunctionDeclaration',
76
  Identifier = 'Identifier',
77
  IfStatement = 'IfStatement',
78
  Literal = 'Literal',
79
  Program = 'Program',
80
  VariableDeclaration = 'VariableDeclaration',
81
  // ... all ESTree node types
82
}
83

84
/**
85
 * ESTree token types enumeration
86
 */
87
enum AST_TOKEN_TYPES {
88
  Boolean = 'Boolean',
89
  Identifier = 'Identifier',
90
  JSXIdentifier = 'JSXIdentifier',
91
  JSXText = 'JSXText',
92
  Keyword = 'Keyword',
93
  Null = 'Null',
94
  Numeric = 'Numeric',
95
  Punctuator = 'Punctuator',
96
  RegularExpression = 'RegularExpression',
97
  String = 'String',
98
  Template = 'Template',
99
  Block = 'Block',
100
  Line = 'Line',
101
  PrivateIdentifier = 'PrivateIdentifier',
102
}
103
```
104

105
### Token Conversion and Classification
106

107
Functions and types for converting and classifying tokens between TypeScript and ESTree formats.
108

109
```typescript { .api }
110
/**
111
 * Converts a TypeScript token to ESTree-compatible token
112
 * @param token - TypeScript token to convert
113
 * @param ast - Source file for location calculation
114
 * @returns ESTree-compatible token
115
 */
116
function convertToken(token: ts.Token<ts.TokenSyntaxKind>, ast: ts.SourceFile): TSESTree.Token;
117

118
/**
119
 * Converts all tokens in a TypeScript source file to ESTree format
120
 * @param ast - TypeScript source file
121
 * @returns Array of ESTree-compatible tokens
122
 */
123
function convertTokens(ast: ts.SourceFile): TSESTree.Token[];
124

125
/**
126
 * Gets the ESTree token type for a TypeScript token
127
 * @param token - TypeScript token or identifier
128
 * @returns ESTree token type
129
 */
130
function getTokenType(token: ts.Identifier | ts.Token<ts.SyntaxKind>): AST_TOKEN_TYPES;
131
```
132

133
**Usage Examples:**
134

135
```typescript
136
import { 
137
  parseAndGenerateServices,
138
  convertTokens,
139
  AST_NODE_TYPES,
140
  AST_TOKEN_TYPES
141
} from "@typescript-eslint/typescript-estree";
142

143
// Parse with tokens
144
const result = parseAndGenerateServices('const x = 42;', {
145
  tokens: true,
146
  loc: true,
147
  range: true
148
});
149

150
// Access ESTree tokens
151
if ('tokens' in result.ast) {
152
  result.ast.tokens.forEach(token => {
153
    console.log(`Token: ${token.type} = "${token.value}"`);
154
  });
155
}
156

157
// Check node types
158
result.ast.body.forEach(node => {
159
  if (node.type === AST_NODE_TYPES.VariableDeclaration) {
160
    console.log('Found variable declaration');
161
  }
162
});
163
```
164

165
### TypeScript Integration Types
166

167
Types specifically for integration with TypeScript compiler API and services.
168

169
```typescript { .api }
170
/**
171
 * ESTree namespace containing all TypeScript-compatible AST node interfaces
172
 */
173
declare namespace TSESTree {
174
  interface BaseNode {
175
    type: string;
176
    loc?: SourceLocation;
177
    range?: Range;
178
    parent?: Node;
179
  }
180
  
181
  interface Program extends BaseNode {
182
    type: AST_NODE_TYPES.Program;
183
    body: Statement[];
184
    sourceType: 'module' | 'script';
185
    comments?: Comment[];
186
    tokens?: Token[];
187
  }
188
  
189
  interface Identifier extends BaseNode {
190
    type: AST_NODE_TYPES.Identifier;
191
    name: string;
192
    typeAnnotation?: TSTypeAnnotation;
193
    optional?: boolean;
194
  }
195
  
196
  interface FunctionDeclaration extends BaseNode {
197
    type: AST_NODE_TYPES.FunctionDeclaration;
198
    id: Identifier | null;
199
    params: Parameter[];
200
    body: BlockStatement;
201
    generator: boolean;
202
    async: boolean;
203
    returnType?: TSTypeAnnotation;
204
    typeParameters?: TSTypeParameterDeclaration;
205
  }
206
  
207
  // ... all ESTree node interfaces with TypeScript extensions
208
  
209
  interface Token {
210
    type: AST_TOKEN_TYPES;
211
    value: string;
212
    range: Range;
213
    loc: SourceLocation;
214
  }
215
  
216
  interface Comment {
217
    type: 'Block' | 'Line';
218
    value: string;
219
    range: Range;
220
    loc: SourceLocation;
221
  }
222
}
223
```
224

225
### Utility Types for Type Mapping
226

227
Utility types for mapping between different AST representations and type safety.
228

229
```typescript { .api }
230
/**
231
 * Utility type for creating branded types (internal use)
232
 */
233
type Brand<T, B> = T & { __brand: B };
234

235
/**
236
 * Maps TypeScript operators to their text representations
237
 */
238
interface BinaryOperatorToText {
239
  [ts.SyntaxKind.AmpersandAmpersandToken]: '&&';
240
  [ts.SyntaxKind.BarBarToken]: '||';
241
  [ts.SyntaxKind.QuestionQuestionToken]: '??';
242
  [ts.SyntaxKind.PlusToken]: '+';
243
  [ts.SyntaxKind.MinusToken]: '-';
244
  [ts.SyntaxKind.AsteriskToken]: '*';
245
  [ts.SyntaxKind.SlashToken]: '/';
246
  // ... all binary operators
247
}
248

249
/**
250
 * Maps TypeScript assignment operators to their text representations
251
 */
252
interface AssignmentOperatorToText {
253
  [ts.SyntaxKind.EqualsToken]: '=';
254
  [ts.SyntaxKind.PlusEqualsToken]: '+=';
255
  [ts.SyntaxKind.MinusEqualsToken]: '-=';
256
  [ts.SyntaxKind.AsteriskEqualsToken]: '*=';
257
  // ... all assignment operators
258
}
259

260
/**
261
 * Maps TypeScript punctuator tokens to their text representations  
262
 */
263
interface PunctuatorTokenToText {
264
  [ts.SyntaxKind.OpenBraceToken]: '{';
265
  [ts.SyntaxKind.CloseBraceToken]: '}';
266
  [ts.SyntaxKind.OpenParenToken]: '(';
267
  [ts.SyntaxKind.CloseParenToken]: ')';
268
  // ... all punctuator tokens
269
}
270
```
271

272
### Advanced Type Operations
273

274
Advanced types for working with optional chaining, type assertion, and other TypeScript-specific features.
275

276
```typescript { .api }
277
/**
278
 * Determines if an ESTree node is a chain expression (optional chaining)
279
 * @param node - ESTree node to check
280
 * @returns True if chain expression
281
 */
282
function isChainExpression(node: TSESTree.Node): node is TSESTree.ChainExpression;
283

284
/**
285
 * Determines if a child node should be unwrapped from optional chain
286
 * @param node - Parent TypeScript node
287
 * @param child - Child ESTree node  
288
 * @returns True if should unwrap optional chain
289
 */
290
function isChildUnwrappableOptionalChain(
291
  node: ts.CallExpression | ts.ElementAccessExpression | ts.NonNullExpression | ts.PropertyAccessExpression,
292
  child: TSESTree.Node
293
): boolean;
294

295
/**
296
 * Gets TypeScript node accessibility level
297
 * @param node - TypeScript node to inspect
298
 * @returns Accessibility modifier or undefined
299
 */
300
function getTSNodeAccessibility(node: ts.Node): 'private' | 'protected' | 'public' | undefined;
301

302
/**
303
 * Gets variable declaration kind from TypeScript flags
304
 * @param node - TypeScript variable declaration list
305
 * @returns Declaration kind (const, let, var, using, await using)
306
 */
307
function getDeclarationKind(node: ts.VariableDeclarationList): 'const' | 'let' | 'var' | 'using' | 'await using';
308
```
309

310
**Usage Examples:**
311

312
```typescript
313
import { 
314
  parseAndGenerateServices,
315
  isChainExpression,
316
  getTSNodeAccessibility,
317
  getDeclarationKind
318
} from "@typescript-eslint/typescript-estree";
319

320
const result = parseAndGenerateServices(`
321
  class Example {
322
    private x = 42;
323
    public method?(): void {}
324
  }
325
  const y = obj?.prop?.method?.();
326
`, { 
327
  project: './tsconfig.json',
328
  loc: true 
329
});
330

331
// Check for optional chaining
332
result.ast.body.forEach(node => {
333
  // Traverse to find chain expressions
334
  if (node.type === 'ExpressionStatement' && isChainExpression(node.expression)) {
335
    console.log('Found optional chaining');
336
  }
337
});
338

339
// Access TypeScript-specific information via services
340
if (result.services.program) {
341
  const classNode = result.ast.body[0];
342
  const tsClassNode = result.services.esTreeNodeToTSNodeMap.get(classNode);
343
  
344
  if (tsClassNode && ts.isClassDeclaration(tsClassNode)) {
345
    tsClassNode.members.forEach(member => {
346
      const accessibility = getTSNodeAccessibility(member);
347
      console.log(`Member accessibility: ${accessibility}`);
348
    });
349
  }
350
}
351
```
352

353
## Version String
354

355
```typescript { .api }
356
/**
357
 * Current package version string
358
 */
359
const version: string;
360
```
361

362
**Usage Example:**
363

364
```typescript
365
import { version } from "@typescript-eslint/typescript-estree";
366

367
console.log(`Using @typescript-eslint/typescript-estree version ${version}`);
368
```
369

370
## Complete Type Definitions
371

372
```typescript { .api }
373
// Export all types from @typescript-eslint/types
374
export {
375
  AST_NODE_TYPES,
376
  AST_TOKEN_TYPES,
377
  TSESTree
378
} from '@typescript-eslint/types';
379

380
// Export enhanced types with TypeScript compiler integration
381
export type {
382
  TSNode,
383
  TSToken,
384
  TSESTreeToTSNode
385
};
386

387
// Re-export visitor keys
388
export { visitorKeys } from '@typescript-eslint/visitor-keys';
389
```