react/compiler/packages/babel-plugin-react-compiler/docs/passes/01-lower.md

lower (BuildHIR)

File

src/HIR/BuildHIR.ts

Purpose

Converts a Babel AST function node into a High-level Intermediate Representation (HIR), which represents code as a control-flow graph (CFG) with basic blocks, instructions, and terminals. This is the first major transformation pass in the React Compiler pipeline, enabling precise expression-level memoization analysis.

Input Invariants

• Input must be a valid Babel NodePath<t.Function> (FunctionDeclaration, FunctionExpression, or ArrowFunctionExpression)
• The function must be a component or hook (determined by the environment)
• Babel scope analysis must be available for binding resolution
• An Environment instance must be provided with compiler configuration
• Optional bindings map for nested function lowering (recursive calls)
• Optional capturedRefs map for context variables captured from outer scope

Output Guarantees

• Returns Result<HIRFunction, CompilerError> - either a successfully lowered function or compilation errors
• The HIR function contains:
  • A complete CFG with basic blocks (body.blocks: Map<BlockId, BasicBlock>)
  • Each block has an array of instructions and exactly one terminal
  • All control flow is explicit (if/else, loops, switch, logical operators, ternary)
  • Parameters are converted to Place or SpreadPattern
  • Context captures are tracked in context array
  • Function metadata (id, async, generator, directives)
• All identifiers get unique IdentifierId values
• Instructions have placeholder instruction IDs (set to 0, assigned later)
• Effects are null (populated by later inference passes)

Algorithm

The lowering algorithm uses a recursive descent pattern with a HIRBuilder helper class:

1. Initialization: Create an HIRBuilder with environment and optional bindings. Process captured context variables.

2. Parameter Processing: For each function parameter:

   • Simple identifiers: resolve binding and create Place
   • Patterns (object/array): create temporary Place, then emit destructuring assignments
   • Rest elements: wrap in SpreadPattern
   • Unsupported: emit Todo error

3. Body Processing:

   • Arrow function expressions: lower body expression to temporary, emit implicit return
   • Block statements: recursively lower each statement

4. Statement Lowering (lowerStatement): Handle each statement type:

   • Control flow: Create separate basic blocks for branches, loops connect back to conditional blocks
   • Variable declarations: Create DeclareLocal/DeclareContext or StoreLocal/StoreContext instructions
   • Expressions: Lower to temporary and discard result
   • Hoisting: Detect forward references and emit DeclareContext for hoisted identifiers

5. Expression Lowering (lowerExpression): Convert expressions to InstructionValue:

   • Identifiers: Create LoadLocal, LoadContext, or LoadGlobal based on binding
   • Literals: Create Primitive values
   • Operators: Create BinaryExpression, UnaryExpression etc.
   • Calls: Distinguish CallExpression vs MethodCall (member expression callee)
   • Control flow expressions: Create separate value blocks for branches (ternary, logical, optional chaining)
   • JSX: Lower to JsxExpression with lowered tag, props, and children

6. Block Management: The builder maintains:

   • A current work-in-progress block accumulating instructions
   • Completed blocks map
   • Scope stack for break/continue resolution
   • Exception handler stack for try/catch

7. Termination: Add implicit void return at end if no explicit return

Key Data Structures

HIRBuilder (from HIRBuilder.ts)

• #current: WipBlock - Work-in-progress block being populated
• #completed: Map<BlockId, BasicBlock> - Finished blocks
• #scopes: Array<Scope> - Stack for break/continue target resolution (LoopScope, LabelScope, SwitchScope)
• #exceptionHandlerStack: Array<BlockId> - Stack of catch handlers for try/catch
• #bindings: Bindings - Map of variable names to their identifiers
• #context: Map<t.Identifier, SourceLocation> - Captured context variables
• Methods: push(), reserve(), enter(), terminate(), terminateWithContinuation()

Core HIR Types

• BasicBlock: Contains instructions: Array<Instruction>, terminal: Terminal, preds: Set<BlockId>, phis: Set<Phi>, kind: BlockKind
• Instruction: Contains id, lvalue (Place), value (InstructionValue), effects (null initially), loc
• Terminal: Block terminator - if, branch, goto, return, throw, for, while, switch, ternary, logical, etc.
• Place: Reference to a value - {kind: 'Identifier', identifier, effect, reactive, loc}
• InstructionValue: The operation - LoadLocal, StoreLocal, CallExpression, BinaryExpression, FunctionExpression, etc.

Block Kinds

• block - Regular sequential block
• loop - Loop header/test block
• value - Block that produces a value (ternary/logical branches)
• sequence - Sequence expression block
• catch - Exception handler block

Edge Cases

1. Hoisting: Forward references to let/const/function declarations emit DeclareContext before the reference, enabling correct temporal dead zone handling

2. Context Variables: Variables captured by nested functions use LoadContext/StoreContext instead of LoadLocal/StoreLocal

3. For-of/For-in Loops: Synthesize iterator instructions (GetIterator, IteratorNext, NextPropertyOf)

4. Optional Chaining: Creates nested OptionalTerminal structures with short-circuit branches

5. Logical Expressions: Create branching structures where left side stores to temporary, right side only evaluated if needed

6. Try/Catch: Adds MaybeThrowTerminal after each instruction in try block, modeling potential control flow to handler

7. JSX in fbt: Tracks fbtDepth counter to handle whitespace differently in fbt/fbs tags

8. Unsupported Syntax: var declarations, with statements, inline class declarations, eval - emit appropriate errors

TODOs

• returnTypeAnnotation: null, // TODO: extract the actual return type node if present
• TODO(gsn): In the future, we could only pass in the context identifiers that are actually used by this function and its nested functions
• Multiple // TODO remove type cast in destructuring pattern handling
• // TODO: should JSX namespaced names be handled here as well?

Example

Input JavaScript:

export default function foo(x, y) {
  if (x) {
    return foo(false, y);
  }
  return [y * 10];
}

Output HIR (simplified):

foo(<unknown> x$0, <unknown> y$1): <unknown> $12
bb0 (block):
  [1] <unknown> $6 = LoadLocal <unknown> x$0
  [2] If (<unknown> $6) then:bb2 else:bb1 fallthrough=bb1

bb2 (block):
  predecessor blocks: bb0
  [3] <unknown> $2 = LoadGlobal(module) foo
  [4] <unknown> $3 = false
  [5] <unknown> $4 = LoadLocal <unknown> y$1
  [6] <unknown> $5 = Call <unknown> $2(<unknown> $3, <unknown> $4)
  [7] Return Explicit <unknown> $5

bb1 (block):
  predecessor blocks: bb0
  [8] <unknown> $7 = LoadLocal <unknown> y$1
  [9] <unknown> $8 = 10
  [10] <unknown> $9 = Binary <unknown> $7 * <unknown> $8
  [11] <unknown> $10 = Array [<unknown> $9]
  [12] Return Explicit <unknown> $10

Key observations:

• The function has 3 basic blocks: entry (bb0), consequent (bb2), alternate/fallthrough (bb1)
• The if statement creates an IfTerminal at the end of bb0
• Each branch ends with its own ReturnTerminal
• All values are stored in temporaries ($N) or named identifiers (x$0, y$1)
• Instructions have sequential IDs within blocks
• Types and effects are <unknown> at this stage (populated by later passes)