Add JS builtin examples (#40)

Chrome 130 supports [WebAssembly JS String builtins](https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md). This PR adds some examples to accompany the documentation I am writing for JS String builtins, plus an update to the readme to explain how to successfully compile the wasm modules.
mdn · Dec 12, 2024 · 01fcd00 · 01fcd00
1 parent 7e4038f
commit 01fcd00
Show file tree

Hide file tree

Showing 21 changed files with 212 additions and 1 deletion.
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ Code examples that accompany the MDN WebAssembly documentation — see https://d
 The examples can be tested locally by running a [local server](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Tools_and_setup/set_up_a_local_testing_server#using_python) to serve your directory of choice.
 
 If you modify any `.wat` files for testing you will need to generate a corresponding `.wasm` file, replacing the existing version in the folder.
-This can be done using the `wat2wasm` tool, which is part of the [WABT: The WebAssembly Binary Toolkit](https://github.com/WebAssembly/wabt/) (for setup/usage see [Converting the text .wat into a binary .wasm file](https://developer.mozilla.org/en-US/docs/WebAssembly/Text_format_to_Wasm#converting_the_text_.wat_into_a_binary_.wasm_file) on MDN and the readme in the WABT GitHub repo.
+For most examples, this can be done using the `wat2wasm` tool, which is part of the [WABT: The WebAssembly Binary Toolkit](https://github.com/WebAssembly/wabt/) (for setup/usage see [Converting the text .wat into a binary .wasm file](https://developer.mozilla.org/en-US/docs/WebAssembly/Text_format_to_Wasm#converting_the_text_.wat_into_a_binary_.wasm_file) on MDN and the readme in the WABT GitHub repo.
 
 Note that some examples use features that are still considered optional.
 These are listed in the [supported proposals](https://github.com/WebAssembly/wabt/#supported-proposals) section on the WABT README.md, along with the flags used to invoke them.

diff --git a/js-builtin-examples/README.md b/js-builtin-examples/README.md
@@ -0,0 +1,17 @@
+# WebAssembly JavaScript builtins examples
+
+WebAssembly JavaScript builtins examples.
+
+## Testing/modifying the JavaScript builtins examples
+
+The `wat2wasm` tool does not support the [JS builtins](https://github.com/WebAssembly/js-string-builtins/blob/main/proposals/js-string-builtins/Overview.md) examples. To compile `.wat` files that make use of JavaScript builtins, you need to use the `wasm-as` tool, which is part of the [Binaryen library](https://github.com/WebAssembly/binaryen). You'll need to run `wasm-as` with reference types and GC enabled for these examples to compile successfully:
+
+```sh
+wasm-as --enable-reference-types -–enable-gc module.wat -o module.wasm
+```
+
+Or you can use the `-all` flag in place of `--enable-reference-types -–enable-gc`:
+
+```sh
+wasm-as -all module.wat -o module.wasm
+```
diff --git a/js-builtin-examples/compile-streaming/index.html b/js-builtin-examples/compile-streaming/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/compile-streaming/index.js b/js-builtin-examples/compile-streaming/index.js
@@ -0,0 +1,16 @@
+const importObject = { // Regular import
+    m: {
+        log: console.log
+    }
+};
+
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+WebAssembly.compileStreaming(fetch("log-concat.wasm"), compileOptions)
+    .then(module => WebAssembly.instantiate(module, importObject))
+    .then(instance => instance.exports.main());
+
+
diff --git a/js-builtin-examples/compile-streaming/log-concat.wasm b/js-builtin-examples/compile-streaming/log-concat.wasm
diff --git a/js-builtin-examples/compile/index.html b/js-builtin-examples/compile/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/compile/index.js b/js-builtin-examples/compile/index.js
@@ -0,0 +1,18 @@
+const importObject = { // Regular import
+    m: {
+        log: console.log
+    }
+};
+
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+fetch("log-concat.wasm")
+    .then(response => response.arrayBuffer())
+    .then(bytes => WebAssembly.compile(bytes, compileOptions))
+    .then(module => WebAssembly.instantiate(module, importObject))
+    .then(instance => instance.exports.main());
+
+
diff --git a/js-builtin-examples/compile/log-concat.wasm b/js-builtin-examples/compile/log-concat.wasm
diff --git a/js-builtin-examples/instantiate-streaming/index.html b/js-builtin-examples/instantiate-streaming/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/instantiate-streaming/index.js b/js-builtin-examples/instantiate-streaming/index.js
@@ -0,0 +1,15 @@
+const importObject = { // Regular import
+    m: {
+        log: console.log
+    }
+};
+
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+WebAssembly.instantiateStreaming(fetch("log-concat.wasm"), importObject, compileOptions)
+    .then(result => result.instance.exports.main());
+
+
diff --git a/js-builtin-examples/instantiate-streaming/log-concat.wasm b/js-builtin-examples/instantiate-streaming/log-concat.wasm
diff --git a/js-builtin-examples/instantiate/index.html b/js-builtin-examples/instantiate/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/instantiate/index.js b/js-builtin-examples/instantiate/index.js
@@ -0,0 +1,17 @@
+const importObject = { // Regular import
+    m: {
+        log: console.log
+    }
+};
+
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+fetch("log-concat.wasm")
+    .then(response => response.arrayBuffer())
+    .then(bytes => WebAssembly.instantiate(bytes, importObject, compileOptions))
+    .then(result => result.instance.exports.main());
+
+
diff --git a/js-builtin-examples/instantiate/log-concat.wasm b/js-builtin-examples/instantiate/log-concat.wasm
diff --git a/js-builtin-examples/log-concat.wat b/js-builtin-examples/log-concat.wat
@@ -0,0 +1,9 @@
+(module
+  (global $h (import "#" "hello ") externref)
+  (global $w (import "#" "world!") externref)
+  (func $concat (import "wasm:js-string" "concat")
+    (param externref externref) (result (ref extern)))
+  (func $log (import "m" "log") (param externref))
+  (func (export "main")
+    (call $log (call $concat (global.get $h) (global.get $w))))
+)
diff --git a/js-builtin-examples/module-constructor/index.html b/js-builtin-examples/module-constructor/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/module-constructor/index.js b/js-builtin-examples/module-constructor/index.js
@@ -0,0 +1,18 @@
+const importObject = { // Regular import
+    m: {
+        log: console.log
+    }
+};
+
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+fetch("log-concat.wasm")
+    .then(response => response.arrayBuffer())
+    .then(bytes => {
+        const module = new WebAssembly.Module(bytes, compileOptions);
+        WebAssembly.instantiate(module, importObject)
+            .then(instance => instance.exports.main());
+    })
diff --git a/js-builtin-examples/module-constructor/log-concat.wasm b/js-builtin-examples/module-constructor/log-concat.wasm
diff --git a/js-builtin-examples/validate/index.html b/js-builtin-examples/validate/index.html
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="utf-8">
+  <title>WebAssembly JS String Builtins example</title>
+
+  <script defer src="index.js"></script>
+</head>
+
+<body>
+  <p>My template</p>
+</body>
+
+</html>
diff --git a/js-builtin-examples/validate/index.js b/js-builtin-examples/validate/index.js
@@ -0,0 +1,11 @@
+const compileOptions = {
+    builtins: ["js-string"],      // Opt-in to get magic imported functions
+    importedStringConstants: "#"  // Opt-in to get magic imported globals
+}
+
+fetch("log-concat.wasm")
+    .then(response => response.arrayBuffer())
+    .then(bytes => WebAssembly.validate(bytes, compileOptions))
+    .then(result => console.log(`wasm module valid: ${result}`));
+
+
diff --git a/js-builtin-examples/validate/log-concat.wasm b/js-builtin-examples/validate/log-concat.wasm