ECMAScript Downleveling

Relevant source files

• src/compiler/transformers/destructuring.ts
• src/compiler/transformers/es2015.ts
• src/compiler/transformers/es2017.ts
• src/compiler/transformers/esnext.ts
• src/compiler/transformers/generators.ts
• src/compiler/transformers/jsx.ts
• src/compiler/transformers/module/module.ts
• src/compiler/transformers/module/system.ts
• src/compiler/transformers/ts.ts
• tests/baselines/reference/emitter.asyncGenerators.classMethods.es2015.js
• tests/baselines/reference/emitter.asyncGenerators.functionDeclarations.es2015.js
• tests/baselines/reference/emitter.asyncGenerators.functionExpressions.es2015.js
• tests/baselines/reference/emitter.asyncGenerators.objectLiteralMethods.es2015.js

Purpose and Scope

This document describes the ECMAScript downleveling transformers in the TypeScript compiler. These transformers convert modern JavaScript features from ES2015 through ESNext to older JavaScript versions (primarily ES5 and ES3) to ensure compatibility with older runtime environments.

ECMAScript downleveling occurs after TypeScript-specific syntax has been removed (see TypeScript Transformation) and before module format transformation (see Module Transformation). The downleveling transformers handle features like classes, arrow functions, destructuring, async/await, generators, and other modern JavaScript constructs.

Related Pages:

• For the overall transformer architecture and pipeline, see Transformer Architecture
• For TypeScript-specific transformations (enums, namespaces, type elision), see TypeScript Transformation
• For module format conversion (CommonJS, AMD, UMD), see Module Transformation

---

Transformer Chain Ordering

ECMAScript downleveling transformers are applied in reverse chronological order—from newest to oldest language versions. This ensures that newer features are transformed to intermediate forms that can then be further downleveled by older transformers.

Transformer Chain Diagram

Sources: getScriptTransformers logic in src/compiler/transformer.ts127-189 (implied by target checks).

---

ES2015 Transformer (transformES2015)

The ES2015 transformer is the most comprehensive downleveling transformer, handling the majority of ES2015 (ES6) features. It transforms classes, arrow functions, destructuring patterns, for-of loops, spread operators, template literals, and block-scoped bindings.

Key Features Transformed

Feature Transformation Overview

Sources: src/compiler/transformers/es2015.ts488-547 (visitor logic).

Class Transformation

ES2015 classes are transformed into ES5 constructor functions with prototype assignments. The transformer handles:

• Class declarations and expressions
• Static and instance properties
• Inheritance via extends clause
• Super calls in constructors and methods
• Computed property names
• Accessors (getters/setters)

The main entry point is visitClassDeclaration at src/compiler/transformers/es2015.ts880-975 which:

1. Determines if the class needs complex transformation via getClassFacts (e.g., if it has decorators or static properties).
2. For simple classes, updates members directly.
3. For complex classes, transforms to a constructor function pattern, often wrapped in an IIFE.

Arrow Function Transformation

Arrow functions are transformed to regular function expressions, with special handling for lexical this binding.

Sources: src/compiler/transformers/es2015.ts1163-1191 (visitArrowFunction).

Destructuring Transformation

Destructuring patterns (both array and object) are flattened into sequential assignments. This is handled by the shared destructuring transformer.

Destructuring Flattening Example Flow

Sources: src/compiler/transformers/destructuring.ts99-195 (flattenDestructuringAssignment), src/compiler/transformers/es2015.ts2142-2217

For-Of Loop Transformation

For-of loops are transformed into traditional for loops that work with iterators.

Sources: src/compiler/transformers/es2015.ts1876-2090 (visitForOfStatement).

Block-Scoped Bindings

Block-scoped variables (let and const) are transformed to var declarations with special handling for loop closures. When a loop contains block-scoped bindings that are captured by closures and potentially modified, the transformer creates a per-iteration function to preserve correct binding semantics.

Sources: src/compiler/transformers/es2015.ts266-365 (Loop closure logic).

---

ES2017 Transformer (transformES2017)

The ES2017 transformer primarily handles async/await syntax, transforming it into generator-based state machines with promise wrapping.

Async/Await Transformation

Async Function Transformation Flow

Sources: src/compiler/transformers/es2017.ts119-282 (transformES2017 and visitors).

For async methods with super calls, additional helpers (__asyncSuperHelper, __advancedAsyncSuperHelper) are emitted to properly handle super property access in the async context src/compiler/transformers/es2017.ts465-652

---

Generator Transformer (transformGenerators)

The generator transformer converts generator functions into state machines that can be executed in ES5 environments.

State Machine Transformation

The generator transformer works by:

1. Building an intermediate representation of the generator body with operations like .yield, .return, .br (break/jump), .try, .catch, .finally.
2. Assigning labels to mark jump targets in the code.
3. Tracking code blocks (loops, try/catch, labeled statements) to handle control flow correctly.
4. Compiling to a switch statement where each case represents a state in the state machine.
5. Wrapping in the __generator helper that manages iteration protocol.

Sources: src/compiler/transformers/generators.ts336-2474 (state machine construction logic).

The main transformation function is transformGeneratorFunctionBody src/compiler/transformers/generators.ts666-760

---

ESNext Transformer (transformESNext)

The ESNext transformer handles features in the ESNext stage, currently focused on using declarations and explicit resource management.

Using Declaration Transformation

Sources: src/compiler/transformers/esnext.ts71-334 (transformESNext and visitSourceFile).

The transformer wraps code containing using declarations in try-finally blocks to ensure proper resource disposal, using the __addDisposableResource and __disposeResources helpers.

---

Module Transformation Integration

While this page focuses on ECMAScript version downleveling, these transformers often interact with module transformers. For example, the transformModule function in src/compiler/transformers/module/module.ts174-188 handles the conversion of ES modules to CommonJS, AMD, or UMD.

SystemJS modules have a unique shape handled in src/compiler/transformers/module/system.ts137-176 where the module body is wrapped in System.register.

---

Emit Helpers

Downleveling transformers rely on emit helpers—runtime functions injected into the output.

Feature	Helper Functions	Purpose
Classes	__extends	Prototype chain inheritance
Async/Await	__awaiter, __generator	Manages generator execution and promises
Generators	__generator	State machine runtime
Async Generators	__asyncGenerator, __await	Combined async + generator runtime
Spread/Rest	__spreadArray, __rest, __assign	Object/Array operations
Using	__addDisposableResource, __disposeResources	Resource management

Sources: src/compiler/transformers/es2015.ts src/compiler/transformers/es2017.ts src/compiler/transformers/generators.ts src/compiler/transformers/esnext.ts

Test baselines like tests/baselines/reference/emitter.asyncGenerators.functionDeclarations.es2015.js34-46 demonstrate the injection of __await and __asyncGenerator helpers into the generated JavaScript.