JavaScript and WebAssembly should be a joy to use together.
This project aims to provide a simple, easy to learn, technology-agnostic way bridge the Rust and Javascript using an extremely minimal setup with out-of-box cargo compilation tools. My hope is almost any Rust developer familiar with JavaScript could learn how to use it in a lazy afternoon.
Let's just look at a basic example of how to put things in the console:
bash
cargo new helloworld --lib
cd helloworld
cargo add js
vim src/lib.rs
```rust use js::*;
pub fn main() { js!("function(str){ console.log(str) }") .invoke(&["Hello, World!".into()]); } ```
Notice the basic syntax is building up a function, and then invoking it with an array of parameters. Underneath the covers, this is an array of enums called InvokeParameter, i've made little converters for various types (see below) to help the data cross the barrier. For the most part you can convert data using .into() for InvokeParameter.
bash
vim index.html
html
<html>
<head>
<meta charset="utf-8">
<script src="https://unpkg.com/js-wasm/js-wasm.js"></script>
<script type="application/wasm" src="helloworld.wasm"></script>
</head>
<body>
Open my console.
</body>
</html>
This library has a fairly simple mechanism for executing your WebAssembly during page load.
bash
vim Cargo.toml
```toml
[lib] crate-type =["cdylib"]
[profile.release]
lto = true
bash
cargo build --target wasm32-unknown-unknown --release
cp target/wasm32-unknown-unknown/release/helloworld.wasm .
python3 -m http.server
```
Full example is here.
The js crate makes it really easy to instantiate a javascript function and pass it parameters. Right now this crate supports these types as parameters:
Below are several examples that show common operations one might want to do.
Here's a more complex example that invokes functions that return references to DOM objects
```rust use js::*;
fn queryselector(selector: &str) -> ExternRef { let queryselector = js!(r#" function(selector){ return document.querySelector(selector); }"#); queryselector.invokeandreturnobject(&[selector.into()]) }
fn canvasgetcontext(canvas: &ExternRef) -> ExternRef { let getcontext = js!(r#" function(canvas){ return canvas.getContext("2d"); }"#); getcontext.invokeandreturn_object(&[canvas.into()]) }
fn canvassetfillstyle(ctx: &ExternRef, color: &str) { let setfillstyle = js!(r#" function(ctx, color){ ctx.fillStyle = color; }"#); setfill_style.invoke(&[ctx.into(), color.into()]); }
fn canvasfillrect(ctx: &ExternRef, x: f64, y: f64, width: f64, height: f64) { let fillrect = js!(r#" function(ctx, x, y, width, height){ ctx.fillRect(x, y, width, height); }"#); fillrect.invoke(&[ctx.into(), x.into(), y.into(), width.into(), height.into()]); }
pub fn main() { let screen = queryselector("#screen"); let ctx = canvasgetcontext(&screen); canvassetfillstyle(&ctx, "red"); canvasfillrect(&ctx, 10.0, 10.0, 100.0, 100.0); canvassetfillstyle(&ctx, "green"); canvasfillrect(&ctx, 20.0, 20.0, 100.0, 100.0); canvassetfillstyle(&ctx, "blue"); canvasfillrect(&ctx, 30.0, 30.0, 100.0, 100.0); } ```
The invocation invoke_and_return_object returns a structure called an ExternRef that is an indirect reference to something received from JavaScript. You can pass around this reference to other JavaScript invocations that will receive the option. When the structure dropped according to Rust lifetimes, it's handle is released from the JavaScript side.
This library is not opinionated about how to callback into Rust. There are several methods one can use. Here's a simple example.
```rust use js::*;
fn consolelog(s: &str) { let consolelog = js!(r#" function(s){ console.log(s); }"#); console_log.invoke(&[s.into()]); }
fn random() -> f64 { let random = js!(r#" function(){ return Math.random(); }"#); random.invoke(&[]) }
pub fn main() { let startloop = js!(r#" function(){ window.setInterval(()=>{ this.module.instance.exports.runloop(); }, 1000) }"#); start_loop.invoke(&[]); }
pub fn runloop(){ consolelog(&format!("⏰ {}", random())); } ```
Notice how in the start_loop function, this actually references a context object that can be used to perform useful functions (see below) and for the importance of this demo, get ahold of the WebAssembly module so we can callback functions on it.
Let's focus on one last example. A button that when you click it, fetches data from the public Pokemon API and put's it on the screen.
```rust use js::*;
fn queryselector(selector: &str) -> ExternRef { let queryselector = js!(r#" function(selector){ return document.querySelector(selector); }"#); queryselector.invokeandreturnobject(&[selector.into()]) }
fn addclicklistener(element: &ExternRef, callback: &str) { let addclicklistener = js!(r#" function(element, callback){ element.addEventListener("click", ()=>{ this.module.instance.exportscallback; }); }"#); addclicklistener.invoke(&[element.into(), callback.into()]); }
fn elementsetinnerhtml(element: &ExternRef, html: &str) { let setinnerhtml = js!(r#" function(element, html){ element.innerHTML = html; }"#); setinner_html.invoke(&[element.into(), html.into()]); }
fn fetch(url: &str, callback: &str) { let fetch = js!(r#" function(url, callback){ fetch(url).then((response)=>{ return response.text(); }).then((text)=>{ const allocationId = this.writeUtf8ToMemory(text); this.module.instance.exportscallback; }); }"#); fetch.invoke(&[url.into(), callback.into()]); }
pub fn main() { let button = queryselector("#fetchbutton"); addclicklistener(&button, "button_clicked"); }
pub fn buttonclicked() { // get pokemon data let url = "https://pokeapi.co/api/v2/pokemon/1/"; fetch(url, "fetchcallback"); }
pub fn fetchcallback(textallocationid: usize) { let text = extractstringfrommemory(textallocationid); let result = queryselector("#dataoutput"); elementsetinner_html(&result, &text); } ```
Notice in the fetch function handling, we have a function specifically for helping put strings inside of WebAssembly writeUtf8ToMemory. This returns back an ID that can be used to rebuild the string on WebAssembly side extract_string_from_memory.
web crateIf you don't feel like recreating the wheel, there's an ongoing collection of commonly used functions accumulationg in web.
```rust use web::*;
fn main() { consolelog("Hello world!"); let body = queryselector("body"); elementaddclicklistener(&body, |e| { consolelog(format!("Clicked at {}, {}", e.offsetx, e.offsety).asstr()); }); elementaddmousemovelistener(&body, |e| { consolelog(format!("Mouse moved to {}, {}", e.offsetx, e.offsety).asstr()); }); elementaddmousedownlistener(&body, |e| { consolelog(format!("Mouse down at {}, {}", e.offsetx, e.offsety).asstr()); }); elementaddmouseuplistener(&body, |e| { consolelog(format!("Mouse up at {}, {}", e.offsetx, e.offsety).asstr()); }); elementaddkeydownlistener(&body, |e| { consolelog(format!("Key down: {}", e.keycode).asstr()); }); elementaddkeyuplistener(&body, |e| { consolelog(format!("Key up: {}", e.keycode).as_str()); }); }
```
Check out the documentation here
This project is licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in js-wasm by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.