Struct Browser

pub struct Browser(/* private fields */);

A WSDOM client.

You can use this to call JS functions on the JS client (the web browser). Every JsValue holds a Browser object which they internally use for calling methods, etc.

Browser uses Arc internally, so cloning is cheap and a cloned Browser points to the same client.

Use with Integration Library

You can obtain Browser from the WSDOM integration library (for example, wsdom-axum).

Manual Usage

If there is no WSDOM integration library for your framework, you can instead create Browser manually with the new() method.

Manually created Browsers need to be “driven”

• Browser implements the Stream trait with String. You must take items from the stream and send it to the WSDOM JS client over WebSocket or other transport of your choice.
• Browser has a receive_incoming_message(msg: String) method. Everything sent by the WSDOM JS client must be fed into this method.

The counter-manual example in our repo shows manual usage with Tokio.

Implementations

impl Browser

pub fn op_add(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsValue

The JavaScript + operator

pub fn op_sub(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript - operator

pub fn op_mul(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript * operator

pub fn op_div(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript / operator

pub fn op_remainder(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript % operator

pub fn op_exponent(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript ** operator

pub fn op_bitwise_and( &self, a: &dyn UseInJsCode, b: &dyn UseInJsCode, ) -> JsNumber

The JavaScript & operator

pub fn op_bitwise_or( &self, a: &dyn UseInJsCode, b: &dyn UseInJsCode, ) -> JsNumber

The JavaScript | operator

pub fn op_bitwise_xor( &self, a: &dyn UseInJsCode, b: &dyn UseInJsCode, ) -> JsNumber

The JavaScript ^ operator

pub fn op_lshift2(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript << operator

pub fn op_rshift2(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript >> operator

pub fn op_rshift3(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsNumber

The JavaScript >>> operator

pub fn op_logical_and( &self, a: &dyn UseInJsCode, b: &dyn UseInJsCode, ) -> JsValue

The JavaScript && operator

pub fn op_logical_or(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsValue

The JavaScript || operator

pub fn op_eq2(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript == operator

pub fn op_neq1(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript != operator

pub fn op_eq3(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript === operator

pub fn op_neq2(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript !== operator

pub fn op_gt(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript > operator

pub fn op_gte(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript >= operator

pub fn op_lt(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript < operator

pub fn op_lte(&self, a: &dyn UseInJsCode, b: &dyn UseInJsCode) -> JsBoolean

The JavaScript <= operator

pub fn op_neg(&self, a: &dyn UseInJsCode) -> JsNumber

The JavaScript - operator

pub fn op_bitwise_not(&self, a: &dyn UseInJsCode) -> JsNumber

The JavaScript ~ operator

pub fn op_logical_not(&self, a: &dyn UseInJsCode) -> JsBoolean

The JavaScript ! operator

impl Browser

pub fn new() -> Self

Create a new Browser object.

This is only needed if you intend to go the “manual” route described above.

pub fn receive_incoming_message(&self, message: String)

Receive a message sent from the WSDOM JS client.

This is only needed if you intend to go the “manual” route described above. If you use an integration library, messages are handled automatically.

pub fn take_error(&self) -> Option<Error>

If the Browser has errored, this will return the error.

The Error type is not Clone, so after the first call returning Some(_), this method will return None.

impl Browser

pub fn call_function<'a>( &'a self, function_name: &'a str, args: impl IntoIterator<Item = &'a dyn UseInJsCode>, last_arg_variadic: bool, ) -> JsValue

Call a standalone JavaScript function.

fn example(browser: Browser) {
    let _return_value = browser.call_function(
        "alert",
        [&"hello world" as &_],
        false
    );
}

This method is “low-level” and you shouldn’t need to use it. Instead, use the wsdom crate which provides mostly type-safe wrappers to the Web API.

If you still want to use call_function, be aware that the first argument (function_name) is NOT escaped. Do NOT allow user-supplied function name.

pub fn call_constructor<'a>( &'a self, class_name: &'a str, args: impl IntoIterator<Item = &'a dyn UseInJsCode>, last_arg_variadic: bool, ) -> JsValue

Call constructor for a class.

fn example(browser: Browser) {
    let _regexp_object = browser.call_constructor(
        "RegExp",
        [&"hello" as &_],
        false
    );
}

This method is “low-level” and you shouldn’t need to use it. Instead, use the wsdom crate which provides mostly type-safe wrappers to the Web API.

If you still want to use call_constructor, be aware that the first argument (class_name) is NOT escaped. Do NOT allow user-supplied class name.

pub fn get_field( &self, base_obj: &dyn UseInJsCode, property: &dyn UseInJsCode, ) -> JsValue

Get a field in an object.

This returns the value of base_obj[property].

pub fn set_field( &self, base_obj: &dyn UseInJsCode, property: &dyn UseInJsCode, value: &dyn UseInJsCode, )

Set a field in an object.

This executes the JavaScript code base_obj[property]=value;

pub fn new_value<'a, T: JsCast>(&'a self, value: &'a dyn ToJs<T>) -> T

Create a new value on the JavaScript side from a ToJs type.

pub fn run_raw_code<'a>(&'a self, code: Arguments<'a>)

Executes arbitrary JavaScript code.

Don’t use this unless you really have to.

pub fn value_from_raw_code<'a>(&'a self, code: Arguments<'a>) -> JsValue

Executes arbitrary JavaScript expression and return the result.

Don’t use this unless you really have to.

Trait Implementations

impl Clone for Browser

fn clone(&self) -> Browser

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Browser

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Stream for Browser

The stream of messages that should be sent over WebSocket (or your transport of choice) to the JavaScript WSDOM client.

type Item = String

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.