JSweet Documentation

The JSweet core API provides the necessary building blocks to program JavaScript applications using Java. It is organized into Maven projects categorized by JavaScript version (e.g., ES5). Each version-specific project provides four primary packages:

• def.js: Contains the core JavaScript language APIs for that specific version.
• def.dom: Contains the W3C DOM APIs for that specific version.
• jsweet.lang: Provides JSweet-specific language extensions for Java, primarily consisting of annotations.
• jsweet.util: Contains various utility helper classes.

JSweet is a Java to JavaScript transpiler that allows you to write rich, responsive web applications in Java. It uses a two-step transpilation process: Java $\rightarrow$ TypeScript $\rightarrow$ JavaScript.

By leveraging TypeScript, JSweet provides type-checking and generates fully type-checked JavaScript programs that can run in browsers, mobile Web views, or Node.js.

To bridge JavaScript libraries into Java, JSweet uses "candies"—well-typed descriptions of JavaScript APIs (often automatically generated from TypeScript definition files) that act like C-style header files for Java developers.

When an object type represents a shared entity that needs to be used across multiple contexts, use the @Interface annotation instead of @ObjectType. This is the recommended approach for reusable typing entities.

@Interface
public class Indexed {
    int index;
}

public class C {
    public void m(Indexed param) { ... }
}

// Usage:
C c = ...;
c.m(new Indexed {{ index = 2; }});

TypeScript intersection types (A & B) represent a type that contains members of both A and B. Because intersection types are difficult to implement directly in Java, JSweet represents them using Union types (Union<A, B>).

To access the members of the intersected types, you must use the jsweet.util.Lang.union helper method to cast the value to either A or B.

Tuple types represent JavaScript arrays where each element has a specific, tracked type. JSweet provides parameterized auxiliary classes TupleN<T0, ... TN-1> in the jsweet.util.tuple package.

Elements are accessed via public fields named $0, $1, up to $N-1.

• Tuple2 through Tuple6 are provided by default.
• Larger tuples are automatically generated in candy APIs or can be manually added to the jsweet.util.tuple package.

Tuple2<String, Integer> tuple = new Tuple2<String, Integer>("test", 10);

assert tuple.$0 == "test";
assert tuple.$1 == 10;
tuple.$0 = "ok";
tuple.$1--;
assert tuple.$1 == 9;

JSweet supports both instance and static initializers, behaving similarly to Java:

• Instance Initializers: Evaluated when the class is instantiated.
• Static Initializers: Lazily evaluated to avoid forward-dependency issues, mimicking Java behavior.

Note: Because of lazy evaluation, it is possible to define a static field or initializer that relies on a static field that has not yet been initialized.

public class C1 {
    int n;
    {
        n = 4;
    }
}

public class C2 {
    static int n;
    static {
        n = 4;
    }
}

Since Java does not have a concept of global variables or functions, JSweet provides the Globals classes and globals packages to handle JavaScript's global scope.

Use these for two primary purposes:

1. Generating global code: To create global variables or functions (though this is generally discouraged in Java patterns).
2. Binding to existing JS code: To interact with existing JavaScript frameworks that define variables or functions in the global scope.

In TypeScript, object types are often inlined and anonymous (e.g., { index: number }). Since Java requires named types, JSweet uses the @ObjectType annotation to simulate this behavior.

Use @ObjectType on a class (which can be an inner class) when you want to represent a lightweight, anonymous object structure that is erased at runtime. This is useful for passing simple data structures to methods without the overhead of a full interface.

Note: Object types are erased at runtime, similar to interfaces.

public class C {
    @ObjectType
    public static class Indexed {
        int index;
    }
    public void m(Indexed param) { ... }
}

// Usage:
C c = ...;
c.m(new Indexed() {{ index = 2; }});

In standard JavaScript, variables used inside a lambda (like an event listener) can be modified by the outer scope, leading to unexpected behavior in loops.

JSweet handles this by re-scoping variables in lambda expressions to behave like final Java variables. This ensures that the variable captured by the lambda holds the value it had at the time the lambda was created, matching Java's expected behavior.

NodeList nodes = document.querySelectorAll(".control");
for (int i = 0; i < nodes.length; i++) {
    HTMLElement element = (HTMLElement) nodes.$get(i);
    element.addEventListener("keyup", (evt) -> {
        // In JSweet, 'element' is re-scoped and won't change
        element.classList.add("hit");
    });
}