Belajar WebAssembly - JS Interop & Emscripten/Bindings

#Pendahuluan

Setelah di episode 5 kita memahami memory dan tables sebagai jembatan data dan kode — pada episode ini kita menyusun semuanya menjadi interop yang lengkap antara JavaScript dan WebAssembly. Inilah momen ketika Wasm berhenti menjadi objek abstrak dan mulai bekerja di dalam aplikasi nyata.

Mengapa interop penting? Karena dalam praktik, hampir tidak ada modul Wasm yang berdiri sendiri. Ia selalu dipanggil dari JavaScript, menerima data dari user, dan mengembalikan hasil untuk dirender di layar. Menguasai interop berarti menguasai antar muka — dan di situlah 80% bug integrasi biasanya muncul.

#API WebAssembly: compile vs instantiate

JavaScript menyediakan empat fungsi utama:

Pola instantiateStreaming (efisien)

const { instance } = await WebAssembly.instantiateStreaming(
  fetch("modul.wasm"),
  { env: { /* imports */ } },
)

Fungsi streaming mengkompilasi bytecode sambil data diunduh — bukan menunggu seluruh file selesai. Untuk modul besar, ini menghemat waktu nyata. WebAssembly.Module yang dihasilkan compile juga bisa di-cache ulang dengan murah, topik yang kembali kita bahas di episode 13.

#Instance.exports dan Passing Primitives

Setelah instansiasi, semua yang diexport modul bisa diakses lewat instance.exports:

Passing primitives

const { instance } = await WebAssembly.instantiateStreaming(
  fetch("math.wasm"),
)
 
console.log(instance.exports.tambah(2, 3))      // 5
console.log(instance.exports.kali(4, 5))        // 20
const d = instance.exports.lingkaran(2.5)       // f64
console.log(d)

Aturan passing primitives sederhana namun ketat:

• i32/i64 JS ↔ integer Wasm; f32/f64 JS ↔ float Wasm.
• Tipe harus cocok dengan (param)/(result) — JS memakai konversi longgar, tapi hasil ekstrem bisa mengejutkan.
• i64 tidak didukung penuh oleh JS (presisi BigInt); BigInt diperlukan mulai sekarang di semua engine modern.

i64 memakai BigInt

const hasil = instance.exports.fungsiI64(10n, 20n)
console.log(typeof hasil, hasil)   // bigint 30

#Import Host Functions

Arah sebaliknya: modul Wasm bisa memanggil fungsi JavaScript yang disediakan sebagai imports. Pola ini dipakai modul untuk logging, DOM, jaringan, atau apa pun yang tidak bisa ia lakukan sendiri:

(module
  (import "env" "logAngka" (func $log (param i32)))
  (func $proses (param $x i32) (result i32)
    local.get $x
    call $log
    local.get $x
    i32.const 2
    i32.mul
  )
  (export "proses" (func $proses))
)

Menyediakan host function

const { instance } = await WebAssembly.instantiateStreaming(
  fetch("impor-host.wasm"),
  {
    env: {
      logAngka: (n) => console.log("dari wasm:", n),
    },
  },
)
instance.exports.proses(21)   // log "21", return 42

Pola ini adalah dasar dari WASI (host menyediakan filesystem, clock, jaringan) yang kita bahas di episode 10.

#Data Non-Primitif: String dan Buffer

String dan objek tidak bisa langsung dilewatkan — kalian harus melewati linear memory. Alurnya:

1. Tulis string sebagai byte (mis. UTF-8) ke memory via Uint8Array.
2. Panggil fungsi Wasm dengan address dan panjang sebagai integer.
3. Modul membaca byte dari memory; hasil ditulis balik ke memory dan dibaca JS.

Mengirim string lewat memory

const memory = instance.exports.memory
const encoder = new TextEncoder()
const bytes = encoder.encode("halo dari js")
 
const buf = new Uint8Array(memory.buffer)
buf.set(bytes, 0)                       // tulis ke offset 0
instance.exports.sapaan(0, bytes.length) // address + panjang
const out = new TextDecoder().decode(
  new Uint8Array(memory.buffer, 0, 16),
)
console.log(out)

Manual, rawan error, dan membosankan — inilah alasan lahirnya glue code di bagian berikutnya.

#Glue Code: Emscripten dan wasm-bindgen

Menulis interop manual seperti di atas untuk proyek nyata tidak akan bertahan. Di sinilah peran bindings:

#Emscripten (C/C++)

Emscripten menghasilkan .wasm plus file JavaScript glue yang mengurus memory management, loading, dan marshalling secara otomatis. Kalian menulis C/C++ biasa; JS glue-nya mengurus sisanya. Detail lengkap di episode 8.

#wasm-bindgen (Rust)

wasm-bindgen menganalisis kode Rust yang diberi anotasi dan menghasilkan:

• Binding JS yang mudah dipakai (import * as wasm from "./pkg").
• Marshalling otomatis untuk string, Vec<u8> sebagai Uint8Array, dan objek JS.
• Panggilan dua arah: Rust → JS dan JS → Rust, memakai memory + tables di balik layar.

use wasm_bindgen::prelude::*;
 
#[wasm_bindgen]
pub fn greet(nama: &str) -> String {
    format!("Halo, {nama}!")
}

Kode Rust di atas otomatis menghasilkan greet yang bisa dipanggil dari JS dengan string biasa — tanpa manual marshalling. Pipeline ini kita bangun langkah demi langkah di episode 7.

#Common Pitfalls

• Buffer tidak sinkron — memory.buffer bisa di-detach setelah memory.grow; ambil ulang view setelah setiap grow.
• Aliasing — menulis ke Uint8Array yang sama saat Wasm sedang membacanya menyebabkan data race di sisi JS; gunakan salinan jika perlu.
• String encoding — selalu pakai TextEncoder/TextDecoder (UTF-8), jangan mengasumsikan ASCII.
• Lupa import — jika modul mendeklarasikan import tapi host tidak menyediakan, instansiasi melempar LinkError.

#Penutup

Pada episode 6 ini, kalian telah menguasai seluruh permukaan interop JS–Wasm: API instansiasi, exports, passing primitives, host functions, dan marshalling string lewat memory.

Inti yang harus dibawa pulang:

• instantiateStreaming adalah cara paling efisien memuat modul; compile memisahkan kompilasi dari instansiasi.
• Primitive (i32/f32/f64) langsung cocok; i64 memakai BigInt; string butuh memory + encoder.
• Imports memungkinkan modul memanggil host; ini fondasi WASI.
• Glue code (Emscripten/wasm-bindgen) menghilangkan marshalling manual.

Di episode 7 selanjutnya kita akan membangun pipeline Rust + wasm-pack dari nol — cargo new --lib, menambah target wasm32-unknown-unknown, build dengan wasm-pack, dan memahami struktur pkg/ yang dihasilkan. Sampai jumpa di episode 7!