AST Structure and Transformations

Relevant source files

• src/ast/expr.rs
• src/ast/import_record.rs
• src/ast/s.rs
• src/ast/symbol.rs
• src/ini/lib.rs
• src/js_parser/fold.rs
• src/js_parser/lib.rs
• src/js_parser/lower/lower_decorators.rs
• src/js_parser/lower/lower_esm_exports_hmr.rs
• src/js_parser/p.rs
• src/js_parser/parse/mod.rs
• src/js_parser/parse/parse_entry.rs
• src/js_parser/parse/parse_stmt.rs
• src/js_parser/parser.rs
• src/js_parser/scan/scan_imports.rs
• src/js_parser/scan/scan_side_effects.rs
• src/js_parser/visit/mod.rs
• src/js_parser/visit/visit_expr.rs
• src/js_parser/visit/visit_stmt.rs
• src/js_parser_jsc/Macro.rs
• src/js_printer/lib.rs
• src/runtime/cli/upgrade_command.rs
• test/bundler/transpiler/es-decorators.test.ts
• test/bundler/transpiler/transpiler.test.js
• test/js/node/fs/cp-symlink-target.test.ts
• test/js/node/fs/cp.test.ts
• test/regression/issue/03830.test.ts

This document describes the Abstract Syntax Tree (AST) structure used throughout Bun's JavaScript toolchain and the transformation passes applied during transpilation and bundling. The AST is the core data structure that represents parsed JavaScript/TypeScript code and is manipulated by the parser, bundler, and printer.

For information about the lexer and parser that construct the AST, see Lexer and Parser. For information about how the AST is converted back to source code, see Code Generation and Printing.

Overview of AST Architecture

Bun's AST is organized around three fundamental node types: Expr (expressions), Stmt (statements), and Binding (binding patterns). Each node type is defined as a struct with a tagged union containing the node's specific data.

Figure: AST Core Node Types

The parser (defined in src/js_parser/p.rs) uses generic instantiation P<'a, TS, SCAN> to handle different syntax modes while constructing these nodes.

Sources: src/js_parser/p.rs35-42 src/js_parser/p.rs95-96

Core AST Node Types

Expr (Expression)

The Expr struct represents any JavaScript expression that produces a value. It contains a data field (a tagged union of type E) and a Loc field for source location tracking.

Key Expression Variants in E namespace:

Variant	Description	Struct Type
Identifier	Variable reference	E::Identifier with ref: Ref
Binary	Binary operation	E::Binary with left: Expr, right: Expr, op: OpCode
Call	Function call	E::Call with target: Expr, args: ExprNodeList
Dot	Property access	E::Dot with target: Expr, name: StoreStr
If	Conditional (ternary)	E::If with test: Expr, yes: Expr, no: Expr
JSXElement	JSX element	E::JsxElement

The parser allocates new Expr nodes using p.new_expr(data, loc).

Sources: src/js_parser/p.rs36-39 src/js_parser/p.rs55 src/js_parser/visit/visit_expr.rs57-83

Stmt (Statement)

The Stmt struct represents any JavaScript statement. Like Expr, it contains a data field (tagged union of type S) and a Loc field.

Key Statement Variants in S namespace:

Variant	Description	Struct Type
Local	Variable declaration	S::Local with kind: LocalKind, decls: DeclList
Expr	Expression statement	S::Expr with value: Expr
Return	Return statement	S::Return with value: Option<Expr>
If	If statement	S::If with test: Expr, yes: Stmt, no: Option<Stmt>
Function	Function declaration	S::Function with func: G::Fn

Sources: src/js_parser/p.rs36-39 src/js_parser/visit/visit_stmt.rs89-124

Binding

A Binding represents a binding pattern used in variable declarations and destructuring.

Key Binding Variants (B namespace):

Variant	Description	Example
Identifier	Simple identifier	x
Array	Array destructuring	[a, b]
Object	Object destructuring	{x, y}

Sources: src/js_parser/p.rs36-39 src/js_parser/lower/lower_decorators.rs177

Visitor Pattern and Transformations

Bun applies transformations using a visitor pattern implemented in src/js_parser/visit/. This pass occurs after parsing and handles symbol resolution, dead code elimination (DCE), and constant folding.

visit_expr and visit_stmt

The primary entry points are visit_expr and visit_and_append_stmt. These methods recursively traverse the AST, applying transformations in-place where possible.

• visit_expr: Dispatches to specific e_* helpers (e.g., e_call, e_binary) based on the expression tag. src/js_parser/visit/visit_expr.rs34-84
• visit_and_append_stmt: Processes statements and appends them to a StmtList. It handles block scoping and conditional removal of statements (e.g., dropping debugger if configured). src/js_parser/visit/visit_stmt.rs47-125

Constant Folding and DCE

During the visit pass, Bun performs several optimizations:

1. Define Substitution: Replaces identifiers or property accesses with constant values defined in the transpiler options (e.g., process.env.NODE_ENV). src/js_parser/visit/visit_expr.rs141-161
2. Dead Code Elimination: Statements in unreachable branches (like if (false) { ... }) are identified using SideEffects analysis and can be omitted from the output. src/js_parser/visit/mod.rs30-32
3. Property Access Inlining: Simple array/object access on constants can be folded (e.g., ["hey"][0] becomes "hey"). test/bundler/transpiler/transpiler.test.js128-142

Figure: Transformation Flow in P::visit

Sources: src/js_parser/visit/visit_expr.rs149-158 src/js_parser/visit/visit_stmt.rs76-79 src/js_parser/visit/visit_stmt.rs82-84

TypeScript and Decorator Lowering

TypeScript Erasure

TypeScript-specific nodes like STypeScript (interfaces, type aliases) are simply dropped during the statement visit pass. src/js_parser/visit/visit_stmt.rs76-79

Decorator Lowering

Bun implements the TC39 standard ES decorators by lowering them into a series of variable declarations and runtime helper calls. This logic is contained in src/js_parser/lower/lower_decorators.rs.

• Class Decorators: The class is wrapped in a call to a runtime helper (e.g., __decorateClass).
• Private Element Lowering: Private fields and methods involved in decoration are mapped using PrivateLoweredMap. src/js_parser/lower/lower_decorators.rs22-42

Sources: src/js_parser/lower/lower_decorators.rs161-166 src/js_parser/lower/lower_decorators.rs176-186

Macro Expansion

Macros are expanded during the visit pass. When the visitor encounters a call expression that resolves to a macro, it executes the macro and replaces the call with a Substitution.

• Macro Execution: Handled via MacroJSCtx in the JavaScriptCore integration.
• Nested Transpilation: Macros can themselves invoke Bun.Transpiler, which must be handled carefully to avoid freeing shared printer resources. test/regression/issue/03830.test.ts40-44

Sources: test/bundler/transpiler/transpiler.test.js15-21 test/regression/issue/03830.test.ts46-54

Memory Management

The AST is stored in a bun_alloc::Arena (a bump allocator). Lists of nodes are represented as BumpVec or StmtNodeList, which are slices pointing directly into arena-allocated memory. This allows for extremely fast allocation and bulk deallocation of the entire AST once the transpilation of a file is complete.

Sources: src/js_parser/p.rs8-10 src/js_parser/p.rs42-44 src/js_parser/visit/visit_stmt.rs29-35