Too many compilation targets: node-sass

• node-sass ships with support for 35 compilation targets (for different OSes, archs, Node.js versions)
• It’s a N-API native addon for libsass, a C++ library for compiling Sass to CSS
• Each Node binding is compiled separately and varies in size from ~2MB to ~19MB

Node.js equivalents in Rust

• package.json → Cargo.toml
• "package" → "crate"
• NODE_ENV=production npm run build →
  cargo build --release --target wasm32-unknown-unknown

wasm-bindgen

• wasm-bindgen is a tool that generates JS/TS bindings for Rust functions and types
• It defines interactions between wasm-compiled Rust code and JavaScript runtimes
• It support other data types beyond scalars, like classes, and struct objects
• Install it via:

cargo install -f wasm-bindgen-cli@0.2.84
cargo install -f wasm-bindgen-cli@0.2.84

• wasm-bindgen doesn’t follow semantic versioning!

• To support Wasm, Cargo.toml needs the following:

# Cargo.toml

[package]
name = "crate-name"
version = "0.1.0"
edition = "2021"

[dependencies]
wasm-bindgen = { version = "0.2.84" } # must match `wasm-bindgen-cli`

# See more: https://doc.rust-lang.org/reference/linkage.html
[lib]
crate-type = ["cdylib"] # links as a Wasm-compatible dynamically-system library
name = "crate_name"
# Cargo.toml

[package]
name = "crate-name"
version = "0.1.0"
edition = "2021"

[dependencies]
wasm-bindgen = { version = "0.2.84" } # must match `wasm-bindgen-cli`

# See more: https://doc.rust-lang.org/reference/linkage.html
[lib]
crate-type = ["cdylib"] # links as a Wasm-compatible dynamically-system library
name = "crate_name"

✅ Serialization: Numbers

use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn duplicate_u64(x: u64) -> u64 {
  x * 2
}
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn duplicate_u64(x: u64) -> u64 {
  x * 2
}

use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn duplicate_f32(x: f32) -> f32 {
  x * 2.0
}
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn duplicate_f32(x: f32) -> f32 {
  x * 2.0
}

export function duplicate_u64(x: bigint): bigint
export function duplicate_f32(x: number): number
export function duplicate_u64(x: bigint): bigint
export function duplicate_f32(x: number): number

✅ Serialization: Strings (1/2)

use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen(js_name = toUpperCase)]
pub fn to_uppercase(x: String) -> String {
  x.to_uppercase()
}
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen(js_name = toUpperCase)]
pub fn to_uppercase(x: String) -> String {
  x.to_uppercase()
}

use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn n_to_string(x: i64) -> String {
  x.to_string()
}
use wasm_bindgen::prelude::wasm_bindgen;

#[wasm_bindgen]
pub fn n_to_string(x: i64) -> String {
  x.to_string()
}

export function toUpperCase(x: string): string
export function n_to_string(x: bigint): string
export function toUpperCase(x: string): string
export function n_to_string(x: bigint): string

✅ Serialization: Strings (2/2)

// loads the *.d.ts and the *.js bindings for the *.wasm module
import * as wasm from '../wasm/playground_wasm_bindgen'

wasm.toUpperCase("node congress") // "NODE CONGRESS"

wasm.n_to_string(256n) // "256"
wasm.n_to_string("node" as unknown as bigint)
// ^ throws a SyntaxError: Cannot convert string to BigInt
// loads the *.d.ts and the *.js bindings for the *.wasm module
import * as wasm from '../wasm/playground_wasm_bindgen'

wasm.toUpperCase("node congress") // "NODE CONGRESS"

wasm.n_to_string(256n) // "256"
wasm.n_to_string("node" as unknown as bigint)
// ^ throws a SyntaxError: Cannot convert string to BigInt

🫠 Serialization: Wrapped Scalars (1/4)

#[wasm_bindgen]
pub struct Scalars {
  pub n: u32,
  pub id: u64,
  pub letter: char,
  pub toggle: bool,
}

#[wasm_bindgen]
pub fn get_letter(params: Scalars) -> char {
  params.letter
}
#[wasm_bindgen]
pub struct Scalars {
  pub n: u32,
  pub id: u64,
  pub letter: char,
  pub toggle: bool,
}

#[wasm_bindgen]
pub fn get_letter(params: Scalars) -> char {
  params.letter
}

export type Scalars = {
  n: number
  id: bigint
  letter: string
  toggle: boolean
}

export function get_letter(
  params: Scalars
): string {
  return params.letter
}
export type Scalars = {
  n: number
  id: bigint
  letter: string
  toggle: boolean
}

export function get_letter(
  params: Scalars
): string {
  return params.letter
}

• We actually get a different Scalars type in TS!

🫠 Serialization: Wrapped Scalars (2/4)

export class Scalars {
  // leaked internal method
  free(): void

  // Rust's `u64` is typed as `bigint`
  id: bigint

  // Rust's `char` is typed as `string`, and every
  // character after the first one is truncated
  letter: string

  // Rust's `u32` is typed as `number`
  n: number
  
  // Rust's `bool` is typed as `boolean`
  toggle: boolean
}
export class Scalars {
  // leaked internal method
  free(): void

  // Rust's `u64` is typed as `bigint`
  id: bigint

  // Rust's `char` is typed as `string`, and every
  // character after the first one is truncated
  letter: string

  // Rust's `u32` is typed as `number`
  n: number
  
  // Rust's `bool` is typed as `boolean`
  toggle: boolean
}

🫠 Serialization: Wrapped Scalars (3/4)

// loads the *.d.ts and the *.js bindings for the *.wasm module
import * as wasm from '../wasm/playground_wasm_bindgen'

let scalars = new wasm.Scalars()
scalars.free = () => {}
scalars.n = 1
scalars.id = 1n
scalars.letter = 'asd'
scalars.toggle = true

wasm.get_letter(scalars) // throws an Error
// loads the *.d.ts and the *.js bindings for the *.wasm module
import * as wasm from '../wasm/playground_wasm_bindgen'

let scalars = new wasm.Scalars()
scalars.free = () => {}
scalars.n = 1
scalars.id = 1n
scalars.letter = 'asd'
scalars.toggle = true

wasm.get_letter(scalars) // throws an Error

• Scalars cannot be instantiated as is!
• This fails with Error: null pointer passed to rust
• We need to implement a constructor in Rust

🫠 Serialization: Wrapped Scalars (4/4)

#[wasm_bindgen]
impl Scalars {
  /// In TS, this becomes the constructor of the `Scalars` class.
  #[wasm_bindgen(constructor)]
  pub fn new(n: u32, id: u64, letter: char, toggle: bool) -> Self {
    Self { n, id, letter, toggle }
  }
}
#[wasm_bindgen]
impl Scalars {
  /// In TS, this becomes the constructor of the `Scalars` class.
  #[wasm_bindgen(constructor)]
  pub fn new(n: u32, id: u64, letter: char, toggle: bool) -> Self {
    Self { n, id, letter, toggle }
  }
}

const scalars = new wasm.Scalars(1, 1n, 'asd', true)
expect(wasm.get_letter(scalars)).toEqual('a')
const scalars = new wasm.Scalars(1, 1n, 'asd', true)
expect(wasm.get_letter(scalars)).toEqual('a')

🙄 Serialization: Wrapped Strings (1/2)

#[wasm_bindgen]
pub struct StringParams {
  pub id: String,
}
#[wasm_bindgen]
pub struct StringParams {
  pub id: String,
}

export type StringParams = {
  id: string
}
export type StringParams = {
  id: string
}

But:

error[E0277]: the trait bound `String: std::marker::Copy` is not satisfied
 --> playground-wasm-bindgen/src/types/string.rs:7:11
  |
7 |   pub id: String,
  |           ^^^^^^ the trait `std::marker::Copy` is not implemented for `String`
error[E0277]: the trait bound `String: std::marker::Copy` is not satisfied
 --> playground-wasm-bindgen/src/types/string.rs:7:11
  |
7 |   pub id: String,
  |           ^^^^^^ the trait `std::marker::Copy` is not implemented for `String`

• Strings are not copyable in Rust!

🙄 Serialization: Wrapped Strings (2/2)

use wasm_bindgen::prelude::wasm_bindgen;

- #[wasm_bindgen]
+ #[wasm_bindgen(getter_with_clone)]
pub struct StringParams {
  pub id: String,
}
use wasm_bindgen::prelude::wasm_bindgen;

- #[wasm_bindgen]
+ #[wasm_bindgen(getter_with_clone)]
pub struct StringParams {
  pub id: String,
}

export class StringParams {
  free(): void
  id: string
}
export class StringParams {
  free(): void
  id: string
}

• We need to use #[wasm_bindgen(getter_with_clone)]
• We still get a TypeScript class with a leaked free() method

✅ Serialization: Enums (C-style)

#[wasm_bindgen]
pub enum Provider {
  Postgres,
  MySQL,
  SQLite,
}
#[wasm_bindgen]
pub enum Provider {
  Postgres,
  MySQL,
  SQLite,
}

export type Provider
  = 'postgres'
  | 'mysql'
  | 'sqlite'
export type Provider
  = 'postgres'
  | 'mysql'
  | 'sqlite'

What we get:

export enum Provider {
  Postgres = 0,
  MySQL = 1,
  SQLite = 2,
}
export enum Provider {
  Postgres = 0,
  MySQL = 1,
  SQLite = 2,
}

• There are plenty of talks about the drawbacks of enums in TypeScript

❌ Serialization: Enums (ADTs)

#[wasm_bindgen]
pub enum Either {
  Ok(i32),
  Err(String),
}
#[wasm_bindgen]
pub enum Either {
  Ok(i32),
  Err(String),
}

export type Either
  = { _tag: 'ok', value: number }
  | { _tag: 'err', value: string }
export type Either
  = { _tag: 'ok', value: number }
  | { _tag: 'err', value: string }

• Discriminated Unions are a popular TS pattern where a literal type is used to discriminate between different union members

But:

error: only C-Style enums allowed with #[wasm_bindgen]
--> wasm-bindgen-playground/src/types/unsupported.rs:18:5
   |
18 |   Ok(i32),
   |
error: only C-Style enums allowed with #[wasm_bindgen]
--> wasm-bindgen-playground/src/types/unsupported.rs:18:5
   |
18 |   Ok(i32),
   |

🫠 Serialization: Vectors

• Rust’s Vec<T> (if T is numeric) becomes a TypedArray buffer, e.g.:

  • Vec<i8> becomes Int8Array
  • Vec<u32> becomes Uint32Array
  • Vec<f32> becomes Float32Array

• Vectors of non-primitive types (String included) are not supported

• Nested vectors (Vec<Vec<T>> for some type T) are not supported

• Tuples (non-homogeneous vectors of finite length, like [number, string] in TypeScript)
  are not supported

🫠 serde + serde_json

• We can expose String → String functions to Wasm that accept and return JSON strings
• We can leverage the automatic serde's (de)serialization via the macro annotation
  #[derive(Serialize, Deserialize)]
• It needs serde_json::{from_str, to_string} to convert between JSON strings and Rust types

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = { version = "1.0.93" }
wasm-bindgen = { version = "0.2.84" }
[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = { version = "1.0.93" }
wasm-bindgen = { version = "0.2.84" }

🙄 serde-wasm-bindgen

• serde-wasm-bindgen is a native integration of serde with wasm-bindgen
• Faster than JSON-strings for (de)serialization
• It needs serde_wasm_bindgen::{from_value, to_value} to convert between
  JsValues and Rust types

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde-wasm-bindgen = { version = "0.5.0" }
wasm-bindgen = { version = "0.2.84" }
[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde-wasm-bindgen = { version = "0.5.0" }
wasm-bindgen = { version = "0.2.84" }

We get support for more data types…

…casting to and from JsValue via serde…

Rust

use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
pub struct Scalars {
  pub letter: char,
}

use serde_wasm_bindgen::Error as WasmError;
use wasm_bindgen::{prelude::wasm_bindgen, JsValue};

/// Given a `Scalars` instance, return its `letter` member.
#[wasm_bindgen]
pub fn get_letter(params: JsValue) -> Result<JsValue, WasmError> {
  let params: Scalars = serde_wasm_bindgen::from_value(params)?;
  let result: char = params.letter;
  serde_wasm_bindgen::to_value(&result)
}
use serde::{Deserialize, Serialize};

#[derive(Deserialize, Serialize)]
pub struct Scalars {
  pub letter: char,
}

use serde_wasm_bindgen::Error as WasmError;
use wasm_bindgen::{prelude::wasm_bindgen, JsValue};

/// Given a `Scalars` instance, return its `letter` member.
#[wasm_bindgen]
pub fn get_letter(params: JsValue) -> Result<JsValue, WasmError> {
  let params: Scalars = serde_wasm_bindgen::from_value(params)?;
  let result: char = params.letter;
  serde_wasm_bindgen::to_value(&result)
}

…but we lose strongly-typed definitions 😰

• With serde-wasm-bindgen:

export function get_letter(params: any): any
export function get_letter(params: any): any

• With wasm-bindgen:

export function get_letter(params: Scalars): string
export function get_letter(params: Scalars): string

😍 tsify

• tsify is a library for generating TypeScript definitions from Rust types
• It supports everything serde-wasm-bindgen supports, but with stronger typing
• Exposing Rust data types to Wasm is a bit more involved…
• …but exposing Rust functions is more ergonomic

[dependencies]
serde = { version = "1.0", features = ["derive"] }
tsify = { version = "0.4.3", features = ["js"] }
wasm-bindgen = { version = "0.2.84" }
[dependencies]
serde = { version = "1.0", features = ["derive"] }
tsify = { version = "0.4.3", features = ["js"] }
wasm-bindgen = { version = "0.2.84" }

✅ tsify: Enums (ADTs) (1/2)

use serde::{Deserialize, Serialize};
use tsify::Tsify;

#[derive(Serialize, Deserialize, Tsify)]
#[tsify(into_wasm_abi, from_wasm_abi)]
#[serde(tag = "_tag", content = "value")]
pub enum Either {
  Ok(i32),
  Err(String),
}
use serde::{Deserialize, Serialize};
use tsify::Tsify;

#[derive(Serialize, Deserialize, Tsify)]
#[tsify(into_wasm_abi, from_wasm_abi)]
#[serde(tag = "_tag", content = "value")]
pub enum Either {
  Ok(i32),
  Err(String),
}

export type Either
  = { _tag: 'ok', value: number }
  | { _tag: 'err', value: string }
export type Either
  = { _tag: 'ok', value: number }
  | { _tag: 'err', value: string }

✅ tsify: Enums (ADTs) (2/2)

#[wasm_bindgen]
pub fn to_string(either: Either) -> String {
  match either {
    Either::Ok(ok) => format!("Ok({})", ok),
    Either::Err(err) => format!("Err({})", err),
  }
}
#[wasm_bindgen]
pub fn to_string(either: Either) -> String {
  match either {
    Either::Ok(ok) => format!("Ok({})", ok),
    Either::Err(err) => format!("Err({})", err),
  }
}

export function to_string(
  either: Either
): string
export function to_string(
  either: Either
): string

import * as wasm from '../wasm/playground_wasm_tsify'

const either: wasm.Either = {
  _tag: 'ok',
  value: 1,
}
wasm.to_string(either) // "Ok(1)"
import * as wasm from '../wasm/playground_wasm_tsify'

const either: wasm.Either = {
  _tag: 'ok',
  value: 1,
}
wasm.to_string(either) // "Ok(1)"

Takeaways

• WebAssembly is useful and here to remain, but it’s non-trivial to integrate in your Node.js workflow
  • I/O support is in its infancy (WASI), so it you need it stick with N-API for now
• wasm-bindgen is a fundamental tool for Rust → Wasm, but is limited to a few basic types
• serde-wasm-bindgen overcomes most of these limitations, but it’s not type-safe (in general) and it requires manual casting from and to JsValue in Rust
• serde_json is a another non type-safe option, and it requires manual casting from and to JSON strings in Node.js
• tsify provides the best DX experience for Rust → Wasm → TypeScript integration, but it’s new kid in the block and relies on lots of macros to do its magic 🪄
• For any serde approach, generic containers like Vec<T> or HashMap<K, T> need to be manually specialized and wrapped in a struct / enum before being used in functions

Success Story: Lyra

See how I’ve used tsify in Lyra: github.com/LyraSearch/lyra/pull/194

”

The Wasm implementation is a LOT faster!

Learn more about Rust + Wasm

• What is WebAssembly? (video)
• Rust+Wasm CPU-heavy improvement over Node.js
• Rust Linkage (cdylib vs others)
• Crate types for Wasm
• wasm-bindgen
• tsify
• Wasm @ Prisma
• Wasm @ Figma
• Wasm @ Amazon Prime Video