swc4j

swc4j provides several core capabilities for working with JavaScript/TypeScript code:

• AST (Abstract Syntax Tree) Manipulation: Inspect, navigate, and transform code using AST structures and visitor patterns.
• Source Map Support: Parse and work with source maps to map generated code positions back to original source locations, including VLQ decoding and error location tracking.
• Library Loading: Customize how native libraries are deployed and loaded, allowing for custom locations, skipping deployment for system libraries, and configuring via system properties.

The TypeScript to JVM Bytecode compiler allows TypeScript code to be executed on the JVM by bridging TypeScript syntax to JVM bytecode.

Supported Features:

• Classes and Constructors
• Inheritance and Interfaces
• Control Flow
• Fields
• Generics
• Enums
• Interoperability with Java standard library classes

A plugin host is an interface that receives the AST program as input. When a plugin host is configured in Swc4jTranspileOptions or Swc4jTransformOptions, the corresponding parse(), transform(), or transpile() methods will invoke the host to modify the AST before generating output.

Use the ISwc4jPluginHost interface to define custom logic. There is a built-in Swc4jPluginHost that manages a list of ISwc4jPlugin instances.

public interface ISwc4jPluginHost {
    boolean process(ISwc4jAstProgram<?> program);
}

A visitor plugin uses the ISwc4jAstVisitor interface to manipulate the AST at specific node levels. This provides a developer experience similar to Babel, where you can target specific node types (like assignment expressions or if statements) without managing the entire tree traversal manually.

Use Swc4jPluginVisitors to hold and manage a list of these visitors.

The test condition (the middle expression) can involve complex logic:

• No Test Condition: Results in an infinite loop (for (let i = 0; ; i++)).
• Complex Boolean Logic: Using &&, ||, and ! operators.
• Side Effects in Test: Expressions that modify state during the test evaluation (for (let i = 0; (x++) < 10; i++)).
• Short-Circuiting: Ensuring that subsequent parts of a boolean expression are not evaluated if the first part fails.
• Method Calls: Evaluating properties or methods (e.g., arr.length) on every iteration.

for (let i = 0; i < 10 && check(i); i++) { }

To support string-based switches, swc4j implements a three-phase approach similar to the JDK 17 compiler to handle hash collisions and maintain performance.

The Three Phases:

1. Phase 1 (Data Structure Building): Maps string case labels to their positions and groups strings by their hashCode() to handle potential collisions.
2. Phase 2 (Hash Switch): Generates a lookupswitch based on the hashCode() of the input string. Inside each hash block, it performs an equals() check to verify the actual string value and assigns a sequential position index.
3. Phase 3 (Position Switch): Generates a tableswitch using the sequential position indices to jump to the actual case bodies.

This ensures that hash collisions are safely handled via .equals() and that the final jump is an $O(1)$ operation.

When working with or extending the compiler, note these key differences between while and for loop implementations: