Thoughts about passing references to the JavaScript side

[nasso]

TL/DR

we should probably allow returning references/borrowed values somehow, even if their life time cannot be tracked.

Motivation

I've been using wasm-bindgen in a project in which the core functionality (including most of our application's state) lives in the Rust/Web Assembly module. This posed many challenges, because many objects are owned by the module and live in the Web Assembly memory, but their state must ultimately still be communicated to the JavaScript side for the rendering of the UI. We also use Typescript, so we want our Typescript definitions to closely match our Rust types.

Goal

After a lot of investigation and many attempts at different approaches, we decided to manually export individual functions (not structs) manipulating raw pointers (JS still sees them as numbers). We then wrote our own idiomatic Typescript wrapper around those functions, creating our own classes that wrap those number pointers to provide a type-safe and idiomatic Typescript API. This may sound like unnecessary work, since this is essentially what wasm-bindgen aims to do for you, but we did this because we couldn't figure out a way to make wasm-bindgen generate the bindings we wanted.

Rust logic

Take the following example:

pub struct Task {
  pub name: String,
  pub done: bool,
}

pub struct Project {
  pub name: String,
  tasks: Vec<Task>,
}

impl Project {
  pub fn new(name: String) -> Self {
    Self { name, tasks: vec![] }
  }

  pub fn tasks(&self) -> &[Task] {
    self.tasks.as_slice()
  }

  pub fn tasks_mut(&mut self) -> &mut [Task] {
    self.tasks.as_mut_slice()
  }

  pub fn add_task(&mut self, name: String) {
    self.tasks.push(Task { name, done: false });
  }
}

This is a very simple, idiomatic Rust code for a basic "to-do" style application. The way one would use it in Rust is pretty straightforward, so I'm not going to show an example here, but it is interesting to look at how one might want to use it from JavaScript.

Desired usage from JavaScript

const project = new Project("world domination");

project.add_task("embrace");
project.add_task("extend");
project.add_task("extinguish");

console.log(`commencing ${project.name}.`);

for (const task of project.tasks) {
  console.log(`it's time to ${task.name}...`);
  task.done = true;
}

This is pretty close from what one would write if they had written the same application logic in JavaScript directly: Project would be a class, it would have a name member of type string, and an array of tasks, which themselves have a name and a done field of their own. The Typescript definitions might look something like this:

declare interface Task {
  name: string;
  done: boolean;
}

declare class Project {
  name: string;
  readonly tasks: ArrayLike<Task> & Iterator<Task>;

  constructor(name: string);
}

The problem

This was our goal, but wasm-bindgen makes writing code like this very difficult, as there is no way to have that project.tasks field to be generated for us. In general, it is impossible to get a reference on the JavaScript side to a Task that is owned by Project on the Rust side, even though it is possible in Rust.

Obviously, the borrow checker has no way to know that someone won't be keeping a reference to a Task after it was moved, which is why, I'm assuming, wasm-bindgen wraps objects in objects containing a raw field for the pointer: the pointer is set to null when the value is moved, resulting in an error if that object is ever used again. This is much more challenging with references, but in our specific case, we aren't keeping references for very long anywhere anyway, so this was just preventing us from reading the state of our app.

Our solution

Ultimately, our solution consists of writing our own wrapper (still using the wasm-bindgen attribute to avoid dealing with string encoding/decoding, async and error handling with Result). For the Project type, it would look like this:

/// Constructor
#[wasm_bindgen]
pub fn project_new(name: String) -> *mut Project {
  Box::into_raw(Box::new(Project::new(name)))
}

/// Destructor
#[wasm_bindgen]
pub fn project_free(project: *mut Project) {
  if !project.is_null() {
    unsafe { Box::from_raw(project) };
  }
}

/// Returns the length of the `tasks` vector.
#[wasm_bindgen]
pub fn project_tasks_len(project: *const Project) -> usize {
  unsafe { &*project }.tasks().len()
}

/// Returns a specific task by index.
#[wasm_bindgen]
pub fn project_tasks_get(project: *mut Project, index: usize) -> *mut Task {
  &mut unsafe { &mut *project }.tasks_mut()[index]
}

/// Adds a new task.
#[wasm_bindgen]
pub fn project_add_task(project: *mut Project, name: String) {
  unsafe { &mut *project }.add_task(name);
}

class Project {
  raw: number;

  private constructor(raw: number) {
    this.raw = raw;
  }

  static wrap(raw: number): Project {
    return new Project(raw);
  }

  // The constructor becomes a static method (sad 😔) because we need to have a way to "wrap" references
  static new(name: string): Project {
    return new Project(project_new(name));
  }

  free() {
    project_free(this.raw);
    this.raw = 0;
  }

  get name() {
    return project_name(this.raw);
  }

  set name(value: string) {
    project_set_name(this.raw, value);
  }

  readonly tasks = array_proxy(
    (index) => Task.wrap(project_tasks_get(this.raw, index)),
    () => project_tasks_len(this.raw)
  );

  add_task(name: string) {
    project_add_task(name);
  }
}

...where array_proxy is a utility we have that uses Proxy to create an object that implements an ArrayLike and Iterable interface over some collection. Borrowed values are wrapped in an instance of their corresponding JavaScript class (demonstrated here with Task.wrap).

Conclusion

This worked beautifully for us, and enabled us to keep our core logic in idiomatic Rust while still providing a similar Typescript interface. We've seen that it makes manipulating objects living in WASM memory from JavaScript significantly easier, as we are able to map pretty much any Rust method signature into an equivalent function that converts references into raw pointers (effectively discarding any static "lifetime" information, but I'm pretty sure this is just part of FFIs anyway). One area of improvement here would be to differentiates mutable from immutable references using Typescript, which does not sound very complicated, but we haven't explored that just yet.

Any thoughts on this? Do you think this is something that should be integrated to wasm-bindgen? Or something provided by a separate crate that would work on-top of it?