feat: add a startup event to ensure the WebAssembly binding can be used

ctron · ctron · commit 9678faa9015b · 2024-05-02T10:36:39.000+02:00
Closes #788
diff --git a/examples/initializer/index.html b/examples/initializer/index.html
@@ -11,4 +11,10 @@
 <body>
     <link data-trunk rel="rust" href="Cargo.toml" data-wasm-opt="z" data-bin="initializer-example" data-initializer="src/initializer.mjs"/>
 </body>
+<script type="module">
+    // you will still get the TrunkApplicationStarted event
+    addEventListener("TrunkApplicationStarted", (event) => {
+        console.log("application started - bindings:", window.wasmBindings, "event:", event);
+    });
+</script>
 </html>
diff --git a/examples/vanilla/Cargo.toml b/examples/vanilla/Cargo.toml
@@ -7,4 +7,11 @@ edition = "2018"
 [dependencies]
 console_error_panic_hook = "0.1"
 wasm-bindgen = "0.2"
-web-sys = { version = "0.3", features = ["Window", "Document", "HtmlElement", "Node", "Text"] }
+web-sys = { version = "0.3", features = [
+    "console",
+    "Document",
+    "HtmlElement",
+    "Node",
+    "Text",
+    "Window",
+] }
diff --git a/examples/vanilla/index.html b/examples/vanilla/index.html
@@ -16,4 +16,14 @@
     <script data-trunk src="src/script.mjs" type="module"></script>
 </body>
 <script>testFromJavaScript();</script>
+
+<script type="module">
+    addEventListener("TrunkApplicationStarted", (event) => {
+        console.log("application started - bindings:", window.wasmBindings, "WASM:", event.detail.wasm);
+        window.wasmBindings.wasm_ffi();
+        // You can also run this via the WASM instance in the details
+        // event.detail.wasm.wasm_ffi();
+    });
+</script>
+
 </html>
diff --git a/examples/vanilla/src/main.rs b/examples/vanilla/src/main.rs
@@ -19,6 +19,11 @@ extern "C" {
     fn snippetTest();
 }
 
+#[wasm_bindgen]
+pub fn wasm_ffi() {
+    web_sys::console::log_1(&"Hello from WASM!".into());
+}
+
 fn main() {
     set_panic_hook();
     snippetTest();
diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md
@@ -14,7 +14,11 @@
 * [Assets](assets/index.md)
   * [Minification](assets/minification.md)
   * [Sub-resource integrity](assets/sri.md)
-
+* [Advanced](advanced/index.md)
+  * [JavaScript interoperability](advanced/javascript_interop.md)
+  * [Startup event](advanced/startup_event.md)
+  * [Application initializer](advanced/initializer.md)
+  * [Library crate](advanced/library.md)
 ---
 
 [Contributing](contributing.md)
diff --git a/guide/src/advanced/index.md b/guide/src/advanced/index.md
@@ -0,0 +1,3 @@
+# Advanced
+
+There are some more advanced topics, which will be described in the following subsections. 
diff --git a/guide/src/advanced/initializer.md b/guide/src/advanced/initializer.md
@@ -0,0 +1,43 @@
+
+# Initializer
+
+Since: `0.19.0-alpha.1`.
+
+Trunk supports tapping into the initialization process of the WebAssembly application. By
+default, this is not active and works the same way as with previous versions.
+
+The default process is that trunk injects a small JavaScript snippet, which imports the JavaScript loader generated
+by `wasm_bindgen` and calls the `init` method. That will fetch the WASM blob and run it.
+
+The downside of this is, that during this process, there's no feedback for the user. Neither when it takes a bit longer
+to load the WASM file, nor when something goes wrong.
+
+Now it is possible to tap into this process by setting `data-initializer` to a JavaScript module file. This module file
+is required to (default) export a function, which returns the "initializer" instance. Here is an example:
+
+```javascript
+export default function myInitializer () {
+  return {
+    onStart: () => {
+      // called when the loading starts
+    },
+    onProgress: ({current, total}) => {
+      // the progress while loading, will be called periodically.
+      // "current" will contain the number of bytes of the WASM already loaded
+      // "total" will either contain the total number of bytes expected for the WASM, or if the server did not provide
+      //   the content-length header it will contain 0.
+    },
+    onComplete: () => {
+      // called when the initialization is complete (successfully or failed)
+    },
+    onSuccess: (wasm) => {
+      // called when the initialization is completed successfully, receives the `wasm` instance
+    },
+    onFailure: (error) => {
+      // called when the initialization is completed with an error, receives the `error`
+    }
+  }
+};
+```
+
+For a full example, see: <https://github.com/trunk-rs/trunk/tree/main/examples/initializer>.
diff --git a/guide/src/advanced/javascript_interop.md b/guide/src/advanced/javascript_interop.md
@@ -0,0 +1,21 @@
+# JavaScript interoperability
+
+Trunk will create the necessary JavaScript code to bootstrap and run the WebAssembly based application. It will also
+include all JavaScript snippets generated by `wasm-bindgen` for interfacing with JavaScript functionality.
+
+By default, functions exported from Rust, using `wasm-bingen`, can be accessed in the JavaScript code through the global
+variable `window.wasmBindings`. This behavior can be disabled, and the name can be customized. For more information
+see the [`rust` asset type](@/assets.md#rust).
+
+## Order of initialization
+
+The bindings will only be available and working when the application initialization has been completed.
+
+If your WebAssembly application renders code into the web page/DOM tree, which then calls from JavaScript into the
+WebAssembly application, then this will not be an issue, as the application is already initialized.
+
+However, if you want to call into the WebAssembly application from, for example, the `index.html` file itself, then
+you must delay that call until the application is started.
+
+This can be ensured by executing that code with the `TrunkApplicationStartup` event. Also see
+[Startup Event](startup_event.md). 
diff --git a/guide/src/advanced/library.md b/guide/src/advanced/library.md
@@ -0,0 +1,17 @@
+
+# Library crate
+
+Aside from having a `main` function, it is also possible to up your project as a `cdylib` project. In order to do that,
+add the following to your `Cargo.toml`:
+
+```toml
+[lib]
+crate-type = ["cdylib", "rlib"]
+```
+
+And then, define the entrypoint in your `lib.rs` like (does not need to be `async`):
+
+```rust
+#[wasm_bindgen(start)]
+pub async fn run() {}
+```
diff --git a/guide/src/advanced/startup_event.md b/guide/src/advanced/startup_event.md
@@ -0,0 +1,37 @@
+# Startup event
+
+The initializer code snippet of Trunk will emit an event when the WebAssembly application has been loaded and started.
+
+```admonish note
+This event is independent of the initializer functionality.
+```
+
+## Definition
+
+The event is called `TrunkApplicationStarted` and is executed after the WebAssembly has been loaded and initialized.
+
+The event will have custom details:
+
+```javascript
+{
+  wasm // The web assembly instance
+}
+```
+
+## Example
+
+The following snippet can be used to run code after the initialization of the WebAssembly application:
+
+```html
+<script type="module">
+  addEventListener("TrunkApplicationStarted", (event) => {
+  console.log("application started - bindings:", window.wasmBindings, "WASM:", event.detail.wasm);
+  // wasm_ffi is a function exported from WASM to JavaScript
+  window.wasmBindings.wasm_ffi();
+  // You can also run this via the WASM instance in the details
+  // event.detail.wasm.wasm_ffi();
+});
+</script>
+```
+
+Also see the vanilla example: <https://github.com/trunk-rs/trunk/tree/main/examples/vanilla>.
diff --git a/src/pipelines/rust/output.rs b/src/pipelines/rust/output.rs
@@ -126,12 +126,20 @@ window.{bindings} = bindings;
             false => ("", String::new()),
         };
 
+        // the code to fire the `TrunkApplicationStarted` event
+        let fire = r#"
+dispatchEvent(new CustomEvent("TrunkApplicationStarted", {detail: {wasm}}));
+"#;
+
         match &self.initializer {
             None => format!(
                 r#"
 <script type="module">
 import init{import} from '{base}{js}';
-init('{base}{wasm}');{bind}
+const wasm = await init('{base}{wasm}');
+
+{bind}
+{fire}
 </script>"#
             ),
             Some(initializer) => format!(
@@ -142,9 +150,10 @@ init('{base}{wasm}');{bind}
 import init{import} from '{base}{js}';
 import initializer from '{base}{initializer}';
 
-await __trunkInitializer(init, '{base}{wasm}', {size}, initializer());
+const wasm = await __trunkInitializer(init, '{base}{wasm}', {size}, initializer());
 
 {bind}
+{fire}
 </script>"#,
                 init = include_str!("initializer.js"),
                 size = self.wasm_size,

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# Advanced`
	`2`	`+`
	`3`	`+There are some more advanced topics, which will be described in the following subsections.`