Error Handling & Exceptions

When your WebAssembly (WASM) module interacts with JavaScript, things can go wrong. Maybe a calculation fails, an input is invalid, or a browser API call doesn't work as expected.

Proper error handling ensures your application remains stable and provides meaningful feedback to users or developers. It's about gracefully managing unexpected situations across language boundaries.

WebAssembly itself doesn't have a concept of "exceptions" like JavaScript or Java. Instead, languages compiled to WASM (like Rust or C++) often use return types or specific data structures to signal errors.

• Rust: Employs the Result<T, E> enum, which can be either Ok(T) for success or Err(E) for failure.
• C/C++: Often uses return values (e.g., -1 for error) or sets global error indicators.

Our focus is on how these language-specific error patterns translate across the WASM-JavaScript boundary.

The goal is to make errors originating in your WASM module appear as standard JavaScript Error objects. This allows JavaScript to use its familiar try...catch mechanism.

Tools like wasm-bindgen help bridge this gap by automatically converting Rust's Result::Err variants into JavaScript exceptions. It's crucial for seamless interoperation.

Here's a Rust function compiled to WASM that might return an error. Notice the Result<i32, JsValue> return type. JsValue is a generic type for anything that can cross the JS boundary.

Once your WASM module propagates an error, JavaScript can catch it using a standard try...catch block. The error object caught will be a JavaScript Error, allowing you to inspect its message and potentially other properties.

This makes integrating WASM errors into your existing JavaScript error handling flow very straightforward and familiar.

This JavaScript code loads our WASM module and attempts to call the divide_numbers function. Observe how the try...catch block handles the division-by-zero error from WASM.

What if your WASM module calls a JavaScript function (a "callback") that then throws an error? How does WASM react?

When a JavaScript function invoked by WASM throws an error, that error is typically caught by the wasm-bindgen glue code and propagated back into the WASM side as a JsValue error. Your Rust code can then handle it using the Result type, just like errors originating in Rust.

Here's a Rust function that calls a JavaScript callback. The JavaScript callback might fail, and the Rust code handles that potential error.

For more specific error handling, you can define custom error types in Rust and map them to JavaScript Error types. wasm-bindgen allows you to control how your Rust errors are represented in JavaScript.

This improves clarity for JavaScript consumers, allowing them to differentiate between various error conditions originating from your WASM module.

• Define specific Rust enums for errors.
• Implement From<YourError> for JsValue to convert them.
• Use #[wasm_bindgen(js_name = MyCustomError)] for custom JS error names.

Effective error handling is key for maintainable and robust WASM applications:

• Be Explicit: Clearly define error conditions and return types in your WASM code.
• Log Errors: Use console.error or a logging utility in JavaScript to record WASM errors.
• Graceful Degradation: Design your application to continue functioning, even if a WASM component encounters a non-critical error.
• Test Error Paths: Ensure your error handling logic is thoroughly tested to cover all failure scenarios.

Consider the following Rust WebAssembly function and the JavaScript code that interacts with it. What will the JavaScript console output when runExample() is called?

Rust WASM Module (lib.rs):

use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn check_value(value: i32) -> Result<String, JsValue> {
    if value < 0 {
        Err(JsValue::from_str("Value cannot be negative!"))
    } else if value == 0 {
        Ok("Value is zero.".into())
    } else {
        Ok(format!("Value is positive: {}", value))
    }
}

JavaScript Host Code:

// Assume 'wasm' is the loaded WASM module via wasm-bindgen
async function runExample() {
  // For context, 'wasm' would be loaded like this:
  // const wasm = await import('./my_wasm_module.js'); 

  // For this question, assume 'wasm.check_value' behaves as defined in Rust.
  const wasm = {
    check_value: (val) => {
      if (val < 0) throw new Error("Value cannot be negative!");
      if (val === 0) return "Value is zero.";
      return `Value is positive: ${val}`;
    }
  };

  try {
    console.log(wasm.check_value(5));
    console.log(wasm.check_value(-1)); // This will throw
  } catch (e) {
    console.error("Caught error:", e.message);
  }
  console.log(wasm.check_value(0)); // This line is outside the try...catch
}
runExample();

In this lesson, we explored how to handle errors and exceptions when interoperating between WebAssembly and JavaScript. We learned:

• WASM's host languages use specific patterns (like Rust's Result type) for errors.
• wasm-bindgen automates the propagation of WASM errors to JavaScript Error objects.
• JavaScript's try...catch can effectively handle errors thrown by WASM modules.
• WASM can also handle errors from JavaScript callbacks it invokes.

Mastering error handling is crucial for building reliable and user-friendly WASM applications.