Jawsm

Jawsm (pronounced like "awesome") is a JavaScript to WebAssembly compiler written in Rust. It is similar to porffor in a way it also results in a standalone WASM binary that can be executed without an interpreter, but it takes a different implementation approach.

It's an experimental tool and it's not ready for production. A lot of the language features and builtin types are missing or incomplete. That said, my goal is to eventually support 100% of the language.

Why Jawsm?

I started this project while working on a stress testing tool called Crows that runs WebAssembly scenarios. At the moment it only supports code compiled from Rust to WASM. As much as I love writing Rust, I also know it's not a widely popular language and besides, small tests are often easier to write in interpreted languages. The problem is, running scripting languages on top of WASM is not ideal at the moment. You have to either include an interpreter, which automatically makes the binary at least a few MBs in size and the memory usage even bigger, or use a variation of the language you're targetting (like TinyGo instead of Go, or AssemblyScript instead of TypeScript/JavaScript).

I believe that with modern WASM proposals it is possible to implement 100% of JavaScript features without the need to use a compiled interpreter, as WASM runtimes are already interpreters.

If you want to see it happen, please consider sponsoring my work

What works

At the moment JAWSM passes about 25% of test262 test suite.

When I started the project I listed four features of the language that I think are crucial to implement in order to test the viability of the project

Scopes/closures
try/catch
async/await
generators

All of these are now implemented and thus I will now be focusing on implementing more of the smaller features and more builtins.

A non exhaustive list of other stuff that should work:

declaring and assigning: var, let, const
all of the loops: do..while, while, for, for..in, for..of
switch statement
limited support for break and continue (it works, but may be buggy)
string literals, adding string literals
numbers and basic operators (+, -, *, /)
booleans and basic boolean operators
arrays and most of the Array related functions
object literals
new keyword
async and await
limited support from Promise APIs
generator functions
try/catch
very basic BigInt support

A few notable things that are missing at the moment:

most of the builtins and most of the methods on existing builtins
RegExp expressions
BigInt arithmetic

Host requirements

As Jawsm is built with a few relatively recent WASM proposals, the generated binaries are not really portable between runtimes yet. I'm aiming to implement it with WASIp2 in mind, but the only runtime capable of running components and WASIp2, ie. Wasmtime, does not support some other things I use, like parts of the WASM GC proposal or exception handling.

In order to make it easier to develop before the runtimes catch up with standardized proposals, I decided to use V8 (through Chromium or Node) with a Javascript polyfill for WASIp2 features that I need. There is a script run.js in the repo that allows to run binaries generated by Jawsm. Eventually it should be possible to run them on any runtime implementing WASM GC, exception handling and WASIp2 API (or by using a WASIp2 pollyfill).

How to use it?

Unless you want to contribute you probably shouldn't, but after cloning the repo you can use an execute.sh script like:

./execute.sh --cargo-run path/to/script.js

It will generate a WAT file, compile it to a binary and then run using Node.js.

It requires Rust's cargo, relatively new version of wasm-tools and Node.js v23.0.0 or newer. Passing --cargo-run will make the script use cargo run command to first compile and then run the project, otherwise it will try to run the release build (so you have to run cargo build --release prior to running ./execute.sh without --cargo-run option)

What's next?

The current plan is to implement the following:

Basic regexp support (ie. RegExp literals and some very basic functions on the RegExp object)
BigInt literals and basic support for BigInts
Better support for automatic casting, for example when checking equality or using various operators
More functions for basic builtins: arrays, strings etc.

How does it work?

The project is essentially translating JavaScript syntax into WASM instructions, leveraging instructions added by WASM GC, exception handling and tail call optimizations proposals. On top of the Rust code that is translating a script, there is also a set of types and functions that are the plumbing needed to translate JavaScript semantics into WASM. Most of the WASM instructions are generated using tarnik - a Rust macro that generates WASM instructions based on a Rust-like syntax.

To give an example, let's consider scopes and closures. WASM has support for passing function references, structs, and arrays, but it doesn't have the scopes semantics that JavaScript has. Thus, we need to simulate how scopes work, by adding extra WASM code. Imagine the following JavaScript code:

let a = "foo";

function bar() {
  console.log(a);
}

bar();

In JavaScript, because a function definition inherits the scope in which it's defined, the bar() function has access to the a variable. Thus, this script should print out the string "foo". We could translate it to roughly the following pseudo code:

// first we create a global scope, that has no parents
let scope = newScope(null);

// then we set the variable `a` on the scope
declareVariable(scope, "a", "foo");

// now we define the  bar function saving a reference to the function
let func = function(parentScope: Scope, arguments: JSArguments, this: Any) -> Any {
  // inside a function declaration we start a new scope, but keeping
  // a reference to the parentScope
  let scope = newScope(parentScope);

  // now we translate console.log call retreiving the variable from the scope
  // this will search for the `a` variable on the current scope and all of the
  // parent scopes
  console.log(retrieve(scope, "a"));
}
// when running a function we have to consider the scope
// in which it was defined
let fObject = createFunctionObject(func, scope);
// and now we also set `bar` on the current scope
declareVariable(scope, "bar", fObject)

// now we need to fetch the `bar` function from the scop
// and run it
let f = retrieve(scope, "bar");
call(f);

Sponsors

While working on this project I have received support on GitHub Sponsors by the following people. Thank you for all the support!

License

The code is licensed under Apache 2.0 license

jawsm

jawsm