Zig-to-JavaScript Transpilation

Ztack's Zig-to-JavaScript transpiler is a core component designed to eliminate the "context switch" problem often encountered in full-stack web development. Traditionally, developers switch between languages like Zig (for the backend) and JavaScript (for the frontend), leading to increased cognitive load and potential for errors. Ztack addresses this by enabling a significant portion of frontend logic, particularly browser event handlers, to be written directly in Zig.

Purpose

The primary purpose of the transpiler is to allow developers to leverage Zig's type safety, performance, and familiar syntax for client-side interactions. Instead of writing JavaScript for tasks like button clicks, form submissions, or dynamic content updates, you can define these handlers in Zig. The transpiler then converts this Zig code into executable JavaScript that can run in the browser. This fosters a more unified development experience, where both server-side and client-side logic adhere to a single language paradigm.

Key Features

The Ztack transpiler, primarily implemented in src/modules/transpiler.zig, supports a carefully selected subset of Zig features to ensure reliable and efficient conversion to JavaScript. Key features include:

• Function Declarations: Converts Zig pub fn declarations into standard JavaScript functions.
• Variable Declarations: Handles Zig var and const declarations, mapping them to JavaScript let and const respectively.
• Arithmetic and Comparison Operators: Supports common arithmetic (+, -, *, /) and comparison operators (==, !=, <, >, <=, >=).
• Control Flow: Transpiles if statements and for loops into their JavaScript equivalents, enabling conditional logic and iteration.
• Function Calls: Converts Zig function calls, utilizing a symbol mapping system to resolve references correctly in the JavaScript output.
• Warning System: Includes a robust warning system that identifies and flags unsupported Zig constructs, guiding developers to write compatible code.

Transpilation Example

To illustrate the process, consider the following Zig code snippet intended for a browser event handler:

Zig Code

This Zig code, when processed by the Ztack transpiler, generates the following JavaScript output:

Transpiles to JavaScript

As seen in the example, the transpiler successfully converts the Zig function definition, variable declaration, and assignment into their direct JavaScript counterparts.

Zig Script Subset and Unsupported Features

To ensure predictability and maintainability, the transpiler operates on a defined "Zig Script Subset." This subset specifies which Zig language features are fully supported for transpilation and which are not. Developers can refer to the ZIG_SCRIPT_SUBSET.md documentation for a detailed specification of this subset.

When the transpiler encounters a Zig feature outside this defined subset (an "unsupported feature"), it will typically issue a warning or an error, preventing the generation of invalid or unpredictable JavaScript. This strict validation helps maintain the integrity of the client-side code.

Symbol Mapping

A crucial aspect of transpilation is symbol mapping. This mechanism ensures that references to functions, variables, or other entities within the Zig code are correctly translated to their corresponding names or representations in the generated JavaScript. This allows functions defined in Zig to be invoked seamlessly from the browser's event model.

Integration with HTML Builders and Event Delegation

The transpiler works in conjunction with Ztack's HTML builders and event delegation system. Frontend event handlers written in Zig are referenced using data-on attributes in the HTML, for example:

The handleClick function here would be the Zig function that the transpiler converts to JavaScript. Ztack's built-in EVENT_DELEGATION_SCRIPT then uses this data-on attribute to dispatch browser events to the corresponding transpiled JavaScript functions.

For more details on the transpiler's API, refer to the [Ztack API Reference].