| 1 |
# Importing a class from JS |
| 2 |
|
| 3 |
Just like with functions after we've started exporting we'll also want to |
| 4 |
import! Now that we've exported a `class` to JS we'll want to also be able to |
| 5 |
import classes in Rust as well to invoke methods and such. Since JS classes are |
| 6 |
in general just JS objects the bindings here will look pretty similar to the JS |
| 7 |
object bindings describe above. |
| 8 |
|
| 9 |
As usual though, let's dive into an example! |
| 10 |
|
| 11 |
```rust |
| 12 |
#[wasm_bindgen(module = "./bar")] |
| 13 |
extern "C" { |
| 14 |
type Bar; |
| 15 |
|
| 16 |
#[wasm_bindgen(constructor)] |
| 17 |
fn new(arg: i32) -> Bar; |
| 18 |
|
| 19 |
#[wasm_bindgen(js_namespace = Bar)] |
| 20 |
fn another_function() -> i32; |
| 21 |
|
| 22 |
#[wasm_bindgen(method)] |
| 23 |
fn get(this: &Bar) -> i32; |
| 24 |
|
| 25 |
#[wasm_bindgen(method)] |
| 26 |
fn set(this: &Bar, val: i32); |
| 27 |
|
| 28 |
#[wasm_bindgen(method, getter)] |
| 29 |
fn property(this: &Bar) -> i32; |
| 30 |
|
| 31 |
#[wasm_bindgen(method, setter)] |
| 32 |
fn set_property(this: &Bar, val: i32); |
| 33 |
} |
| 34 |
|
| 35 |
fn run() { |
| 36 |
let bar = Bar::new(Bar::another_function()); |
| 37 |
let x = bar.get(); |
| 38 |
bar.set(x + 3); |
| 39 |
|
| 40 |
bar.set_property(bar.property() + 6); |
| 41 |
} |
| 42 |
``` |
| 43 |
|
| 44 |
Unlike our previous imports, this one's a bit more chatty! Remember that one of |
| 45 |
the goals of `wasm-bindgen` is to use native Rust syntax wherever possible, so |
| 46 |
this is mostly intended to use the `#[wasm_bindgen]` attribute to interpret |
| 47 |
what's written down in Rust. Now there's a few attribute annotations here, so |
| 48 |
let's go through one-by-one: |
| 49 |
|
| 50 |
* `#[wasm_bindgen(module = "./bar")]` - seen before with imports this is declare |
| 51 |
where all the subsequent functionality is imported from. For example the `Bar` |
| 52 |
type is going to be imported from the `./bar` module. |
| 53 |
* `type Bar` - this is a declaration of JS class as a new type in Rust. This |
| 54 |
means that a new type `Bar` is generated which is "opaque" but is represented |
| 55 |
as internally containing a `JsValue`. We'll see more on this later. |
| 56 |
* `#[wasm_bindgen(constructor)]` - this indicates that the binding's name isn't |
| 57 |
actually used in JS but rather translates to `new Bar()`. The return value of |
| 58 |
this function must be a bare type, like `Bar`. |
| 59 |
* `#[wasm_bindgen(js_namespace = Bar)]` - this attribute indicates that the |
| 60 |
function declaration is namespaced through the `Bar` class in JS. |
| 61 |
* `#[wasm_bindgen(static_method_of = SomeJsClass)]` - this attribute is similar |
| 62 |
to `js_namespace`, but instead of producing a free function, produces a static |
| 63 |
method of `SomeJsClass`. |
| 64 |
* `#[wasm_bindgen(method)]` - and finally, this attribute indicates that a |
| 65 |
method call is going to happen. The first argument must be a JS struct, like |
| 66 |
`Bar`, and the call in JS looks like `Bar.prototype.set.call(...)`. |
| 67 |
|
| 68 |
With all that in mind, let's take a look at the JS generated. |
| 69 |
|
| 70 |
```js |
| 71 |
import * as wasm from './foo_bg'; |
| 72 |
|
| 73 |
import { Bar } from './bar'; |
| 74 |
|
| 75 |
// other support functions omitted... |
| 76 |
|
| 77 |
export function __wbg_s_Bar_new() { |
| 78 |
return addHeapObject(new Bar()); |
| 79 |
} |
| 80 |
|
| 81 |
const another_function_shim = Bar.another_function; |
| 82 |
export function __wbg_s_Bar_another_function() { |
| 83 |
return another_function_shim(); |
| 84 |
} |
| 85 |
|
| 86 |
const get_shim = Bar.prototype.get; |
| 87 |
export function __wbg_s_Bar_get(ptr) { |
| 88 |
return shim.call(getObject(ptr)); |
| 89 |
} |
| 90 |
|
| 91 |
const set_shim = Bar.prototype.set; |
| 92 |
export function __wbg_s_Bar_set(ptr, arg0) { |
| 93 |
set_shim.call(getObject(ptr), arg0) |
| 94 |
} |
| 95 |
|
| 96 |
const property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').get; |
| 97 |
export function __wbg_s_Bar_property(ptr) { |
| 98 |
return property_shim.call(getObject(ptr)); |
| 99 |
} |
| 100 |
|
| 101 |
const set_property_shim = Object.getOwnPropertyDescriptor(Bar.prototype, 'property').set; |
| 102 |
export function __wbg_s_Bar_set_property(ptr, arg0) { |
| 103 |
set_property_shim.call(getObject(ptr), arg0) |
| 104 |
} |
| 105 |
``` |
| 106 |
|
| 107 |
Like when importing functions from JS we can see a bunch of shims are generated |
| 108 |
for all the relevant functions. The `new` static function has the |
| 109 |
`#[wasm_bindgen(constructor)]` attribute which means that instead of any |
| 110 |
particular method it should actually invoke the `new` constructor instead (as |
| 111 |
we see here). The static function `another_function`, however, is dispatched as |
| 112 |
`Bar.another_function`. |
| 113 |
|
| 114 |
The `get` and `set` functions are methods so they go through `Bar.prototype`, |
| 115 |
and otherwise their first argument is implicitly the JS object itself which is |
| 116 |
loaded through `getObject` like we saw earlier. |
| 117 |
|
| 118 |
Some real meat starts to show up though on the Rust side of things, so let's |
| 119 |
take a look: |
| 120 |
|
| 121 |
```rust |
| 122 |
pub struct Bar { |
| 123 |
obj: JsValue, |
| 124 |
} |
| 125 |
|
| 126 |
impl Bar { |
| 127 |
fn new() -> Bar { |
| 128 |
extern "C" { |
| 129 |
fn __wbg_s_Bar_new() -> u32; |
| 130 |
} |
| 131 |
unsafe { |
| 132 |
let ret = __wbg_s_Bar_new(); |
| 133 |
Bar { obj: JsValue::__from_idx(ret) } |
| 134 |
} |
| 135 |
} |
| 136 |
|
| 137 |
fn another_function() -> i32 { |
| 138 |
extern "C" { |
| 139 |
fn __wbg_s_Bar_another_function() -> i32; |
| 140 |
} |
| 141 |
unsafe { |
| 142 |
__wbg_s_Bar_another_function() |
| 143 |
} |
| 144 |
} |
| 145 |
|
| 146 |
fn get(&self) -> i32 { |
| 147 |
extern "C" { |
| 148 |
fn __wbg_s_Bar_get(ptr: u32) -> i32; |
| 149 |
} |
| 150 |
unsafe { |
| 151 |
let ptr = self.obj.__get_idx(); |
| 152 |
let ret = __wbg_s_Bar_get(ptr); |
| 153 |
return ret |
| 154 |
} |
| 155 |
} |
| 156 |
|
| 157 |
fn set(&self, val: i32) { |
| 158 |
extern "C" { |
| 159 |
fn __wbg_s_Bar_set(ptr: u32, val: i32); |
| 160 |
} |
| 161 |
unsafe { |
| 162 |
let ptr = self.obj.__get_idx(); |
| 163 |
__wbg_s_Bar_set(ptr, val); |
| 164 |
} |
| 165 |
} |
| 166 |
|
| 167 |
fn property(&self) -> i32 { |
| 168 |
extern "C" { |
| 169 |
fn __wbg_s_Bar_property(ptr: u32) -> i32; |
| 170 |
} |
| 171 |
unsafe { |
| 172 |
let ptr = self.obj.__get_idx(); |
| 173 |
let ret = __wbg_s_Bar_property(ptr); |
| 174 |
return ret |
| 175 |
} |
| 176 |
} |
| 177 |
|
| 178 |
fn set_property(&self, val: i32) { |
| 179 |
extern "C" { |
| 180 |
fn __wbg_s_Bar_set_property(ptr: u32, val: i32); |
| 181 |
} |
| 182 |
unsafe { |
| 183 |
let ptr = self.obj.__get_idx(); |
| 184 |
__wbg_s_Bar_set_property(ptr, val); |
| 185 |
} |
| 186 |
} |
| 187 |
} |
| 188 |
|
| 189 |
impl WasmBoundary for Bar { |
| 190 |
// ... |
| 191 |
} |
| 192 |
|
| 193 |
impl ToRefWasmBoundary for Bar { |
| 194 |
// ... |
| 195 |
} |
| 196 |
``` |
| 197 |
|
| 198 |
In Rust we're seeing that a new type, `Bar`, is generated for this import of a |
| 199 |
class. The type `Bar` internally contains a `JsValue` as an instance of `Bar` |
| 200 |
is meant to represent a JS object stored in our module's stack/slab. This then |
| 201 |
works mostly the same way that we saw JS objects work in the beginning. |
| 202 |
|
| 203 |
When calling `Bar::new` we'll get an index back which is wrapped up in `Bar` |
| 204 |
(which is itself just a `u32` in memory when stripped down). Each function then |
| 205 |
passes the index as the first argument and otherwise forwards everything along |
| 206 |
in Rust. |