0
# AST Nodes
1

2
Complete abstract syntax tree type definitions covering all JavaScript and TypeScript syntax elements. These types represent the parsed structure of source code and are essential for AST manipulation, analysis, and transformation.
3

4
## Capabilities
5

6
### Core AST Interfaces
7

8
Base interfaces that form the foundation of the AST type system.
9

10
```typescript { .api }
11
/**
12
 * Base AST node interface
13
 */
14
interface Node {
15
  type: string;
16
}
17

18
/**
19
 * Nodes with source location information
20
 */
21
interface HasSpan {
22
  span: Span;
23
}
24

25
/**
26
 * Nodes that can have decorators
27
 */
28
interface HasDecorator {
29
  decorators?: Decorator[];
30
}
31

32
/**
33
 * Source location span
34
 */
35
interface Span {
36
  start: number;
37
  end: number;
38
  ctxt: number;
39
}
40
```
41

42
### Program Structure
43

44
Top-level program types representing complete source files.
45

46
```typescript { .api }
47
/**
48
 * Top-level program - either a module or script
49
 */
50
type Program = Module | Script;
51

52
/**
53
 * ES Module program
54
 */
55
interface Module extends Node, HasSpan, HasInterpreter {
56
  type: "Module";
57
  body: ModuleItem[];
58
}
59

60
/**
61
 * Script program
62
 */
63
interface Script extends Node, HasSpan, HasInterpreter {
64
  type: "Script";
65
  body: Statement[];
66
}
67

68
interface HasInterpreter {
69
  /** e.g. "/usr/bin/node" for "#!/usr/bin/node" */
70
  interpreter: string;
71
}
72

73
type ModuleItem = ModuleDeclaration | Statement;
74
```
75

76
### Statements
77

78
All statement types in JavaScript and TypeScript.
79

80
```typescript { .api }
81
type Statement = 
82
  | BlockStatement | EmptyStatement | DebuggerStatement
83
  | WithStatement | ReturnStatement | LabeledStatement
84
  | BreakStatement | ContinueStatement | IfStatement
85
  | SwitchStatement | ThrowStatement | TryStatement
86
  | WhileStatement | DoWhileStatement | ForStatement
87
  | ForInStatement | ForOfStatement | Declaration
88
  | ExpressionStatement;
89

90
interface BlockStatement extends Node, HasSpan {
91
  type: "BlockStatement";
92
  stmts: Statement[];
93
}
94

95
interface ExpressionStatement extends Node, HasSpan {
96
  type: "ExpressionStatement";
97
  expression: Expression;
98
}
99

100
interface EmptyStatement extends Node, HasSpan {
101
  type: "EmptyStatement";
102
}
103

104
interface IfStatement extends Node, HasSpan {
105
  type: "IfStatement";
106
  test: Expression;
107
  consequent: Statement;
108
  alternate?: Statement;
109
}
110

111
interface WhileStatement extends Node, HasSpan {
112
  type: "WhileStatement";
113
  test: Expression;
114
  body: Statement;
115
}
116

117
interface ForStatement extends Node, HasSpan {
118
  type: "ForStatement";
119
  init?: VariableDeclaration | Expression;
120
  test?: Expression;
121
  update?: Expression;
122
  body: Statement;
123
}
124

125
interface ReturnStatement extends Node, HasSpan {
126
  type: "ReturnStatement";
127
  argument?: Expression;
128
}
129

130
interface TryStatement extends Node, HasSpan {
131
  type: "TryStatement";
132
  block: BlockStatement;
133
  handler?: CatchClause;
134
  finalizer?: BlockStatement;
135
}
136

137
interface CatchClause extends Node, HasSpan {
138
  type: "CatchClause";
139
  param?: Pattern;
140
  body: BlockStatement;
141
}
142
```
143

144
### Expressions
145

146
All expression types in JavaScript and TypeScript.
147

148
```typescript { .api }
149
type Expression = 
150
  | ThisExpression | ArrayExpression | ObjectExpression
151
  | FunctionExpression | UnaryExpression | UpdateExpression
152
  | BinaryExpression | AssignmentExpression | MemberExpression
153
  | SuperPropExpression | ConditionalExpression | CallExpression
154
  | NewExpression | SequenceExpression | Identifier | Literal
155
  | TemplateLiteral | TaggedTemplateExpression | ArrowFunctionExpression
156
  | ClassExpression | YieldExpression | MetaProperty | AwaitExpression
157
  | ParenthesisExpression | JSXMemberExpression | JSXNamespacedName
158
  | JSXEmptyExpression | JSXElement | JSXFragment | TsTypeAssertion
159
  | TsConstAssertion | TsNonNullExpression | TsAsExpression
160
  | TsSatisfiesExpression | TsInstantiation | PrivateName
161
  | OptionalChainingExpression | Invalid;
162

163
interface Identifier extends ExpressionBase {
164
  type: "Identifier";
165
  value: string;
166
  optional: boolean;
167
}
168

169
interface BinaryExpression extends ExpressionBase {
170
  type: "BinaryExpression";
171
  operator: BinaryOperator;
172
  left: Expression;
173
  right: Expression;
174
}
175

176
interface CallExpression extends ExpressionBase {
177
  type: "CallExpression";
178
  callee: Super | Import | Expression;
179
  arguments: Argument[];
180
  typeArguments?: TsTypeParameterInstantiation;
181
}
182

183
interface MemberExpression extends ExpressionBase {
184
  type: "MemberExpression";
185
  object: Expression;
186
  property: Identifier | PrivateName | ComputedPropName;
187
}
188

189
interface ArrowFunctionExpression extends ExpressionBase {
190
  type: "ArrowFunctionExpression";
191
  params: Pattern[];
192
  body: BlockStatement | Expression;
193
  async: boolean;
194
  generator: boolean;
195
  typeParameters?: TsTypeParameterDeclaration;
196
  returnType?: TsTypeAnnotation;
197
}
198
```
199

200
### Declarations
201

202
Declaration statement types including functions, classes, and variables.
203

204
```typescript { .api }
205
type Declaration = 
206
  | ClassDeclaration | FunctionDeclaration | VariableDeclaration
207
  | TsInterfaceDeclaration | TsTypeAliasDeclaration | TsEnumDeclaration
208
  | TsModuleDeclaration;
209

210
interface FunctionDeclaration extends Fn {
211
  type: "FunctionDeclaration";
212
  identifier: Identifier;
213
  declare: boolean;
214
}
215

216
interface ClassDeclaration extends Class, Node {
217
  type: "ClassDeclaration";
218
  identifier: Identifier;
219
  declare: boolean;
220
}
221

222
interface VariableDeclaration extends Node, HasSpan {
223
  type: "VariableDeclaration";
224
  kind: VariableDeclarationKind;
225
  declare: boolean;
226
  declarations: VariableDeclarator[];
227
}
228

229
type VariableDeclarationKind = "var" | "let" | "const";
230

231
interface VariableDeclarator extends Node, HasSpan {
232
  type: "VariableDeclarator";
233
  id: Pattern;
234
  init?: Expression;
235
  definite: boolean;
236
}
237
```
238

239
### Classes
240

241
Class-related AST nodes including members, methods, and properties.
242

243
```typescript { .api }
244
interface Class extends HasSpan, HasDecorator {
245
  body: ClassMember[];
246
  superClass?: Expression;
247
  isAbstract: boolean;
248
  typeParams?: TsTypeParameterDeclaration;
249
  superTypeParams?: TsTypeParameterInstantiation;
250
  implements: TsExpressionWithTypeArguments[];
251
}
252

253
type ClassMember = 
254
  | Constructor | ClassMethod | PrivateMethod
255
  | ClassProperty | PrivateProperty | TsIndexSignature
256
  | EmptyStatement | StaticBlock;
257

258
interface ClassProperty extends ClassPropertyBase {
259
  type: "ClassProperty";
260
  key: PropertyName;
261
  isAbstract: boolean;
262
  declare: boolean;
263
}
264

265
interface ClassMethod extends ClassMethodBase {
266
  type: "ClassMethod";
267
  key: PropertyName;
268
}
269

270
interface Constructor extends Node, HasSpan {
271
  type: "Constructor";
272
  key: PropertyName;
273
  params: (TsParameterProperty | Param)[];
274
  body?: BlockStatement;
275
  accessibility?: Accessibility;
276
  isOptional: boolean;
277
}
278

279
interface StaticBlock extends Node, HasSpan {
280
  type: "StaticBlock";
281
  body: BlockStatement;
282
}
283

284
type Accessibility = "public" | "protected" | "private";
285
type MethodKind = "method" | "getter" | "setter";
286
```
287

288
### Patterns and Destructuring
289

290
Pattern types used for destructuring assignments and function parameters.
291

292
```typescript { .api }
293
type Pattern = 
294
  | BindingIdentifier | ArrayPattern | RestElement
295
  | ObjectPattern | AssignmentPattern | Invalid | Expression;
296

297
interface BindingIdentifier extends PatternBase {
298
  type: "Identifier";
299
  value: string;
300
  optional: boolean;
301
}
302

303
interface ArrayPattern extends PatternBase {
304
  type: "ArrayPattern";
305
  elements: (Pattern | undefined)[];
306
  optional: boolean;
307
}
308

309
interface ObjectPattern extends PatternBase {
310
  type: "ObjectPattern";
311
  properties: ObjectPatternProperty[];
312
  optional: boolean;
313
}
314

315
interface AssignmentPattern extends PatternBase {
316
  type: "AssignmentPattern";
317
  left: Pattern;
318
  right: Expression;
319
}
320

321
interface RestElement extends PatternBase {
322
  type: "RestElement";
323
  rest: Span;
324
  argument: Pattern;
325
}
326

327
type ObjectPatternProperty = 
328
  | KeyValuePatternProperty | AssignmentPatternProperty | RestElement;
329
```
330

331
### Literals
332

333
Literal value types in JavaScript.
334

335
```typescript { .api }
336
type Literal = 
337
  | StringLiteral | BooleanLiteral | NullLiteral
338
  | NumericLiteral | BigIntLiteral | RegExpLiteral | JSXText;
339

340
interface StringLiteral extends Node, HasSpan {
341
  type: "StringLiteral";
342
  value: string;
343
  raw?: string;
344
}
345

346
interface NumericLiteral extends Node, HasSpan {
347
  type: "NumericLiteral";
348
  value: number;
349
  raw?: string;
350
}
351

352
interface BooleanLiteral extends Node, HasSpan {
353
  type: "BooleanLiteral";
354
  value: boolean;
355
}
356

357
interface BigIntLiteral extends Node, HasSpan {
358
  type: "BigIntLiteral";
359
  value: bigint;
360
  raw?: string;
361
}
362

363
interface RegExpLiteral extends Node, HasSpan {
364
  type: "RegExpLiteral";
365
  pattern: string;
366
  flags: string;
367
}
368
```
369

370
### Module System
371

372
Module import/export declarations and specifiers.
373

374
```typescript { .api }
375
type ModuleDeclaration = 
376
  | ImportDeclaration | ExportDeclaration | ExportNamedDeclaration
377
  | ExportDefaultDeclaration | ExportDefaultExpression | ExportAllDeclaration
378
  | TsImportEqualsDeclaration | TsExportAssignment | TsNamespaceExportDeclaration;
379

380
interface ImportDeclaration extends Node, HasSpan {
381
  type: "ImportDeclaration";
382
  specifiers: ImportSpecifier[];
383
  source: StringLiteral;
384
  typeOnly: boolean;
385
  asserts?: ObjectExpression;
386
}
387

388
interface ExportNamedDeclaration extends Node, HasSpan {
389
  type: "ExportNamedDeclaration";
390
  specifiers: ExportSpecifier[];
391
  source?: StringLiteral;
392
  typeOnly: boolean;
393
  asserts?: ObjectExpression;
394
}
395

396
type ImportSpecifier = 
397
  | NamedImportSpecifier | ImportDefaultSpecifier | ImportNamespaceSpecifier;
398

399
type ExportSpecifier = 
400
  | ExportNamespaceSpecifier | ExportDefaultSpecifier | NamedExportSpecifier;
401

402
interface NamedImportSpecifier extends Node, HasSpan {
403
  type: "ImportSpecifier";
404
  local: Identifier;
405
  imported?: ModuleExportName;
406
  isTypeOnly: boolean;
407
}
408

409
type ModuleExportName = Identifier | StringLiteral;
410
```
411

412
### Operators
413

414
Operator type definitions for expressions.
415

416
```typescript { .api }
417
type BinaryOperator = 
418
  | "==" | "!=" | "===" | "!==" | "<" | "<=" | ">" | ">="
419
  | "<<" | ">>" | ">>>" | "+" | "-" | "*" | "/" | "%"
420
  | "|" | "^" | "&" | "||" | "&&" | "in" | "instanceof" | "**" | "??";
421

422
type AssignmentOperator = 
423
  | "=" | "+=" | "-=" | "*=" | "/=" | "%=" | "<<=" | ">>=" | ">>>="
424
  | "|=" | "^=" | "&=" | "**=" | "&&=" | "||=" | "??=";
425

426
type UpdateOperator = "++" | "--";
427

428
type UnaryOperator = "-" | "+" | "!" | "~" | "typeof" | "void" | "delete";
429
```
430

431
### Utility Interfaces
432

433
Supporting interfaces used throughout the AST.
434

435
```typescript { .api }
436
interface ExpressionBase extends Node, HasSpan { }
437

438
interface PatternBase extends Node, HasSpan {
439
  typeAnnotation?: TsTypeAnnotation;
440
}
441

442
interface Fn extends HasSpan, HasDecorator {
443
  params: Param[];
444
  body?: BlockStatement;
445
  generator: boolean;
446
  async: boolean;
447
  typeParameters?: TsTypeParameterDeclaration;
448
  returnType?: TsTypeAnnotation;
449
}
450

451
interface Param extends Node, HasSpan, HasDecorator {
452
  type: "Parameter";
453
  pat: Pattern;
454
}
455

456
interface Decorator extends Node, HasSpan {
457
  type: "Decorator";
458
  expression: Expression;
459
}
460

461
interface Invalid extends Node, HasSpan {
462
  type: "Invalid";
463
}
464

465
interface Output {
466
  code: string;
467
  map?: string;
468
}
469

470
/**
471
 * Expression or spread element for object properties and array elements
472
 */
473
interface ExprOrSpread {
474
  spread?: Span;
475
  expression: Expression;
476
}
477

478
/**
479
 * Function call argument with optional spread
480
 */
481
interface Argument {
482
  spread?: Span;
483
  expression: Expression;
484
}
485

486
/**
487
 * Spread element for arrays, objects, and function calls
488
 */
489
interface SpreadElement extends Node {
490
  type: "SpreadElement";
491
  spread: Span;
492
  arguments: Expression;
493
}
494

495
/**
496
 * Computed property name for dynamic object keys
497
 */
498
interface ComputedPropName {
499
  type: "ComputedPropName";
500
  expression: Expression;
501
}
502

503
/**
504
 * Pattern matching interface (empty placeholder)
505
 */
506
interface MatchPattern { }
507
```
508

509
**Usage Examples:**
510

511
```typescript
512
import type { Program, Statement, Expression, Identifier } from "@swc/types";
513

514
// Type-safe AST traversal
515
function findIdentifiers(node: Program): Identifier[] {
516
  const identifiers: Identifier[] = [];
517
  
518
  function visit(node: any) {
519
    if (node && typeof node === 'object') {
520
      if (node.type === 'Identifier') {
521
        identifiers.push(node as Identifier);
522
      }
523
      
524
      for (const key in node) {
525
        const child = node[key];
526
        if (Array.isArray(child)) {
527
          child.forEach(visit);
528
        } else if (child && typeof child === 'object') {
529
          visit(child);
530
        }
531
      }
532
    }
533
  }
534
  
535
  visit(node);
536
  return identifiers;
537
}
538

539
// AST node creation
540
function createStringLiteral(value: string): StringLiteral {
541
  return {
542
    type: "StringLiteral",
543
    span: { start: 0, end: 0, ctxt: 0 },
544
    value,
545
    raw: `"${value}"`
546
  };
547
}
548
```