Skip to content

WebAssembly Hoja de referencia

Formato binario de instrucciones para una ejecución rápida basada en web.

01

Primeros pasos

Cargar Wasm en JS

WebAssembly (Wasm) es un formato binario que corre a una velocidad casi nativa en los navegadores. instantiateStreaming carga y compila un archivo .wasm. Las exportaciones son funciones invocables desde JavaScript.

webassembly
// Load and instantiate a .wasm module
WebAssembly.instantiateStreaming(fetch('module.wasm'))
  .then(result => {
    const { instance } = result;
    // call exported functions
    console.log(instance.exports.add(2, 3)); // 5
  });

// Alternative: from ArrayBuffer
const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
WebAssembly.instantiate(bytes).then(result => {
  console.log(result.instance.exports);
});

Módulo e instancia de WebAssembly

WebAssembly.Module es la representación compilada y sin estado — segura de reutilizar entre varias instancias. WebAssembly.Instance guarda el estado en tiempo de ejecución (memoria, globales). Compilar una vez e instanciar muchas veces es eficiente para lanzar workers paralelos.

webassembly
// Two-step: compile then instantiate
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module, importObject);
console.log(instance.exports.add(1, 2));

// Module is stateless & shareable across instances
const instance2 = await WebAssembly.instantiate(module, importObject);
// Each instance has its own memory and globals

Soporte de navegadores y detección de características

WebAssembly 1.0 está soportado en cualquier navegador moderno. Las propuestas más nuevas (SIMD, excepciones, threads, GC) necesitan detección de características. WebAssembly.validate comprueba si unos bytes forman un módulo válido sin compilar.

webassembly
// Check basic WebAssembly support
if (typeof WebAssembly !== 'undefined') {
  console.log('WebAssembly is supported');
}

// Verify the engine can actually compile
WebAssembly.validate(new Uint8Array([
  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00
])); // true if valid module

// Feature-detect newer proposals
const hasSIMD = typeof WebAssembly.Module !== 'undefined';
const hasExceptions = 'exceptions' in WebAssembly;

Streaming vs no streaming

instantiateStreaming compila el módulo a medida que llega por la red — arranque más rápido. El servidor DEBE enviar 'Content-Type: application/wasm'. Si usas un CDN o un host estático sin esa cabecera, recurre a la vía del ArrayBuffer.

webassembly
// Streaming (preferred): compiles while downloading
WebAssembly.instantiateStreaming(fetch('m.wasm'), imports);

// Non-streaming: must download fully first
const res = await fetch('m.wasm');
const buf = await res.arrayBuffer();
WebAssembly.instantiate(buf, imports);

// Streaming requires correct MIME type:
//   Content-Type: application/wasm

Número mágico y cabecera de Wasm

El número mágico del binario Wasm es el string ASCII '\0asm' seguido de una versión de 4 bytes little-endian. Esta cabecera permite validar que un archivo es Wasm antes de compilar. El formato se organiza en secciones (Type, Import, Function, Memory, etc.).

webassembly
// Every .wasm file starts with this 8-byte header:
//   0x00 0x61 0x73 0x6d  -> "\0asm"
//   0x01 0x00 0x00 0x00  -> version 1
const magic = [0x00, 0x61, 0x73, 0x6d];
const version = [0x01, 0x00, 0x00, 0x00];

// Quick validity check
function isWasm(bytes) {
  return bytes[0] === 0x00 && bytes[1] === 0x61
      && bytes[2] === 0x73 && bytes[3] === 0x6d;
}

Hola Wasm (ejemplo mínimo)

Una app Wasm mínima: el módulo importa una función 'log' desde JS y exporta 'greet' que la llama. El formato WAT (WebAssembly Text) es la representación legible por humanos, compilada a binario con wat2wasm. Los navegadores solo ejecutan la forma binaria.

webassembly
<!-- index.html -->
<script>
  WebAssembly.instantiateStreaming(fetch('hello.wasm'))
    .then(({ instance }) => {
      instance.exports.greet(); // logs "Hello, Wasm!"
    });
</script>

;; hello.wat (compiled to hello.wasm via wat2wasm)
(module
  (import "console" "log" (func $log (param i32)))
  (func (export "greet")
    i32.const 72   ;; 'H'
    call $log
  )
)
02

Formato de texto WAT

Módulo y S-expresiones

WAT (formato de texto de WebAssembly) es la representación textual de Wasm. La totalidad va envuelta en una s-expresión (module ...). Las instrucciones se escriben en orden basado en pila: primero se apilan los operandos y luego la operación los consume.

webassembly
;; WAT uses s-expressions: (keyword args...)
(module
  ;; function definitions, exports, etc. go here
)

;; Nested expressions form the instruction sequence
(module
  (func $add (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add
  )
  (export "add" (func $add))
)

Comentarios en WAT

WAT soporta dos estilos de comentario: ';;' para una línea y '(; ... ;)' para bloques. Los comentarios de bloque pueden anidar y ocupar varias líneas — útil para desactivar trozos de código durante el desarrollo.

webassembly
;; Single-line comment (starts with ;;)
(func (export "f")
  i32.const 1  ;; push 1
  drop         ;; discard
)

(; Block comment
   can span
   multiple lines ;)
(func (export "g")
  nop
)

Sintaxis de definición de funciones

Las funciones se declaran con (func ...). Los parámetros usan (param $name type) y los resultados (result type). El '$name' es opcional — sin él, funciones/locales se referencian por índice numérico. Los retornos multi-valor requieren la propuesta multi-value (ampliamente soportada).

webassembly
;; Named function with params and result
(func $name (param $p1 i32) (param $p2 f64) (result i32)
  ;; body
)

;; Anonymous function (referenced by index)
(func (param i32) (result i32)
  local.get 0
)

;; Multiple results (multi-value proposal)
(func $swap (param i32 i32) (result i32 i32)
  local.get 1
  local.get 0
)

Export e import en línea

WAT soporta las anotaciones en línea (export "name") y (import "module" "field") sobre funciones, memorias, tablas y globales — un atajo de las formas expandidas (export ...) / (import ...). Ambas compilan a una salida binaria idéntica.

webassembly
;; Inline export on a function
(func (export "add") (param i32 i32) (result i32)
  local.get 0
  local.get 1
  i32.add
)

;; Inline import
(func $log (import "env" "log") (param i32))

;; Inline export on memory
(memory (export "mem") 1)

;; Expanded form (equivalent)
(func $add (param i32 i32) (result i32) ...)
(export "add" (func $add))

Segmentos de datos

Los segmentos de datos inicializan la memoria lineal en la instanciación (activos) o de forma perezosa vía memory.init (pasivos). Los strings incluyen secuencias de escape como \00 para el terminador nulo y \n para el salto de línea. data.drop libera el almacenamiento del segmento tras copiarlo.

webassembly
;; Initialize memory with bytes at offset 0
(memory 1)
(data (i32.const 0) "Hello, Wasm!\00")

;; Named data segment (active)
(data $msg (i32.const 0) "Hello\00")

;; Passive data segment (used with memory.init)
(data $passive "lazy-loaded bytes")

;; Drop a data segment to free its memory
(data.drop $msg)

Conversión wat2wasm y wasm2wat

WABT (WebAssembly Binary Toolkit) ofrece wat2wasm (texto→binario), wasm2wat (binario→texto), wasm-validate y wasm-objdump. Son esenciales para inspeccionar, depurar y escribir módulos Wasm a mano. La forma .wat es para humanos; la forma .wasm es la que ejecutan los navegadores.

webassembly
# Install the WebAssembly Binary Toolkit (WABT)
# macOS:  brew install wabt
# Ubuntu: apt install wabt

# Convert text -> binary
wat2wasm hello.wat -o hello.wasm

# Convert binary -> text (disassemble)
wasm2wat hello.wasm -o hello.wat

# Validate a .wasm file
wasm-validate hello.wasm

# Print module structure
wasm-objdump -x hello.wasm
03

Tipos de valor

Tipos de valor básicos (i32/i64/f32/f64)

Wasm solo tiene cuatro tipos de valor básicos: i32, i64, f32, f64. El signo de los enteros lo determina la operación (p. ej., i32.div_s vs i32.div_u), no el tipo. Esto mantiene el sistema de tipos mínimo y predecible.

webassembly
;; Wasm has exactly four basic value types:
;;   i32  - 32-bit integer
;;   i64  - 64-bit integer
;;   f32  - 32-bit float
;;   f64  - 64-bit float

(func (param i32) (param i64) (param f32) (param f64)
  (result f64)
  local.get 2   ;; f32
  f64.promote_f32
)

;; Integers are signed or unsigned PER OPERATION,
;; not per type. Use i32.add_s / i32.div_u etc.

Literales numéricos en WAT

Los literales numéricos en WAT soportan las formas decimal, hex (0x) y binaria (0b). Los floats soportan notación científica, infinito (inf) y NaN. Los literales de WAT son sin signo por defecto — los enteros negativos se codifican con un '-' inicial.

webassembly
;; Integer literals
i32.const 42
i32.const -7
i32.const 0xff       ;; hex
i32.const 0b1010     ;; binary

;; Float literals
f64.const 3.14
f64.const 1e10
f64.const -0.0
f64.const inf
f64.const nan

;; 64-bit
i64.const 9007199254740992  ;; 2^53

Conversiones de tipos

Las conversiones usan un esquema de nombres consistente: extend (de menor→mayor), wrap (de mayor→menor), convert (int↔float), reinterpret (cast a nivel de bits), demote/promote (precisión float). Las variantes signadas usan _s y las no signadas _u.

webassembly
;; Extend i32 to i64
i64.extend_i32_s      ;; sign-extend
i64.extend_i32_u      ;; zero-extend

;; Wrap i64 to i32
i32.wrap_i64

;; Integer <-> Float
f32.convert_i32_s
f64.convert_i64_u
i32.trunc_f32_s       ;; truncate (toward zero)
i32.reinterpret_f32   ;; bit-level reinterpret

;; Demote / promote floats
f32.demote_f64
f64.promote_f32

Tipo SIMD v128

El tipo v128 empaqueta 16 bytes en un único registro SIMD. Los lanes se direccionan como i32x4 (4×int32), f32x4 (4×float32), i16x8, i8x16, f64x2. SIMD acelera las cargas de imagen/audio/criptografía al operar sobre varios valores por instrucción.

webassembly
;; SIMD: 128-bit vector type (fixed-width SIMD proposal)
(module
  (func (param v128) (result v128)
    local.get 0
    v128.not            ;; bitwise NOT
  )
  (func (result v128)
    v128.const i32x4 1 2 3 4
  )
)

;; Vector operations: i32x4, i16x8, i8x16, f32x4, f64x2
v128.const f32x4 1.0 2.0 3.0 4.0
i32x4.add

Tipos de referencia (funcref/externref)

La propuesta de reference types añade funcref (puntero a función) y externref (referencia opaca al host). externref es potente: permite que Wasm guarde objetos de JS sin copiarlos ni serializarlos. Combinado con tablas, habilita patrones de callbacks flexibles.

webassembly
;; Reference types proposal adds:
;;   funcref   - reference to a function (in a table)
;;   externref - opaque reference to a host (JS) object

(module
  (table 1 funcref)
  (func (param externref) (result externref)
    local.get 0    ;; pass through a JS object
  )
)

;; In JS, externref lets you pass arbitrary objects
;; through Wasm without serialization:
instance.exports.store({ hello: 'world' });
04

Funciones

Definir y llamar funciones

Las funciones son la unidad fundamental de código. call invoca una función por nombre/índice. Los argumentos se apilan antes de la llamada; los resultados quedan en la pila cuando la función retorna. La pila debe coincidir con la declaración (result ...).

webassembly
(module
  (func $add (param $a i32) (param $b i32) (result i32)
    local.get $a
    local.get $b
    i32.add
  )
  (func $double (param $x i32) (result i32)
    local.get $x
    local.get $x
    i32.add      ;; or: i32.const 2  i32.mul
  )
  (func (export "use")
    i32.const 5
    i32.const 7
    call $add     ;; -> 12 on stack
    drop
  )
)

Parámetros y variables locales

Los parámetros son locales inmutables indexados desde 0. Los locales declarados (local $name type) se inicializan a cero y son mutables. Usa local.get, local.set y local.tee (asignar + dejar en la pila). Los locales son el único almacenamiento mutable de Wasm fuera de memoria/globales.

webassembly
(func $f (param $a i32) (param $b i32) (result i32)
  (local $sum i32)         ;; mutable local
  (local $i i32)
  local.get $a
  local.get $b
  i32.add
  local.set $sum           ;; store into local
  i32.const 0
  local.set $i
  local.get $sum
)

;; tee: set and keep on stack
local.tee $sum             ;; $sum = top; stays on stack

Múltiples valores de retorno

La propuesta multi-value permite que las funciones devuelvan varios valores (y acepten cero). Los motores importantes la soportan desde 2020. Elimina la necesidad de parámetros de salida vía memoria y hace naturales modismos como swap/minmax.

webassembly
;; Multi-value: return two i32 values
(func $minmax (param $a i32) (param $b i32) (result i32 i32)
  local.get $a
  local.get $b
  i32.lt_s
  if (result i32 i32)
    local.get $a
    local.get $b
  else
    local.get $b
    local.get $a
  end
)

;; Caller receives both on the stack
(func (export "use")
  i32.const 3
  i32.const 8
  call $minmax
  ;; stack: [min=3, max=8]
  drop drop
)

Recursión

Wasm soporta la recursión directa — una función puede llamarse a sí misma. No hay optimización de llamada final (tail-call) en el Wasm MVP (la propuesta tail-call añade return_call). La recursión profunda arriesga desbordamiento de pila, así que prefiere bucles iterativos en código de producción.

webassembly
(module
  (func $fact (param $n i32) (result i32)
    local.get $n
    i32.const 1
    i32.le_s
    if (result i32)
      i32.const 1
    else
      local.get $n
      local.get $n
      i32.const 1
      i32.sub
      call $fact     ;; recursive call
      i32.mul
    end
  )
  (export "factorial" (func $fact))
)

Export en línea y llamadas con nombre

El (export "name") en línea sobre una definición de función es un atajo de una declaración (export ...) aparte. call_ref (propuesta de reference types) invoca una función vía una funcref directamente, habilitando funciones como valores de primera clase sin consulta de tabla.

webassembly
(module
  ;; Inline export on definition
  (func $add (export "add") (param i32 i32) (result i32)
    local.get 0
    local.get 1
    i32.add
  )

  ;; call_ref: call via funcref (reference types)
  (func $caller (param $f funcref) (param i32) (result i32)
    local.get 1
    local.get 0
    call_ref (param i32) (result i32)
  )
)

Función start

Un módulo puede declarar una función (start $func) que corre automáticamente al instanciar — útil para inicialización. No toma argumentos ni devuelve nada. Solo se permite una función start por módulo.

webassembly
(module
  (func $init
    ;; runs once at instantiation
    i32.const 0
    i32.const 42
    i32.store
  )
  (start $init)        ;; declare as start function
  (memory (export "mem") 1)
)

;; The start function runs automatically after
;; instantiation, before instantiate() resolves.
;; It takes no params and returns nothing.
05

Memoria

Declarar memoria lineal

La memoria lineal es una región contigua tipo ArrayBuffer, que crece en páginas de 64KiB. (memory 1 10) declara initial=1, max=10. La memoria es la única forma de pasar datos en bloque (strings, arrays) entre Wasm y JS. Expórtala para acceder desde JS.

webassembly
(module
  ;; 1 page = 64KiB. Declare 1 page, max 10.
  (memory $mem 1 10)
  (export "memory" (memory $mem))

  ;; JS-side: read/write the exported memory
  ;; const buf = new Uint8Array(instance.exports.memory.buffer);
)

Crecimiento de memoria

memory.grow añade páginas y devuelve el tamaño anterior (en páginas), o -1 si falla. Crucialmente, crecer desacopla el ArrayBuffer subyacente — todas las vistas TypedArray existentes quedan inservibles. Recrea siempre las vistas tras cualquier llamada a grow.

webassembly
(func $grow (result i32)
  i32.const 1            ;; request 1 more page
  memory.grow            ;; returns previous size (or -1)
)

;; In JS, growing detaches the old buffer!
const prev = instance.exports.grow();
const buf = new Uint8Array(instance.exports.memory.buffer);
// OLD buf references are now detached — re-create views!

Operaciones load y store

Los loads/stores tienen variantes por tamaño (8/16/32/64 bits) y extensión de signo (_s/_u). offset=N añade una constante al operando de dirección; align= es una pista (debe ser ≤ al tamaño). Todas las direcciones son offsets en bytes dentro de la memoria lineal.

webassembly
;; Load: read from memory at address (top of stack)
i32.load  offset=0 align=2     ;; 4-byte aligned load
i32.load8_u                    ;; 1 byte, zero-extended
i32.load16_s                   ;; 2 bytes, sign-extended
f64.load                       ;; 8-byte float load

;; Store: write value at address
i32.const 100        ;; address
i32.const 42         ;; value
i32.store            ;; mem[100] = 42

i32.const 100
i32.const 0xFF
i32.store8           ;; write 1 byte

Tamaños de memoria y alineación

La alineación en Wasm es una pista de rendimiento, no una restricción de corrección — el acceso no alineado siempre funciona. El valor 'align' no debe superar el tamaño natural de la operación. memory.size devuelve el número actual de páginas (cada una de 64KiB).

webassembly
;; Each load/store has a natural alignment:
;;   i32.load   -> 4 bytes
;;   i64.load   -> 8 bytes
;;   f32.load   -> 4 bytes
;;   i32.load8  -> 1 byte

;; Explicit alignment hint (does not affect correctness)
i32.load align=2    ;; may be slower but still works

;; memory.size returns current pages
(func $pages (result i32)
  memory.size
)

Memoria compartida y atómicos

La memoria compartida (la propuesta threads) permite que varias instancias/Workers de Wasm compartan una misma memoria para paralelismo. Las operaciones atómicas (i32.atomic.load/store/rmw.add/cmpxchg) aportan sincronización. Requiere aislamiento cross-origin (cabeceras COOP/COEP) en los navegadores.

webassembly
(module
  ;; Shared memory (threads proposal)
  (memory 1 1 shared)
  (export "memory" (memory 0))

  ;; Atomic operations
  (func (param i32 i32)
    local.get 0       ;; address
    local.get 1       ;; value
    i32.atomic.store
  )
  (func (param i32) (result i32)
    local.get 0
    i32.atomic.load
  )
  (func (param i32) (result i32)
    local.get 0
    i32.const 1
    i32.atomic.rmw.add   ;; atomic read-modify-write
  )
)

Leer strings de memoria

Wasm no tiene tipo string nativo — los strings son secuencias de bytes en la memoria lineal, típicamente pasados como pares (puntero, longitud). TextEncoder/TextDecoder manejan la conversión UTF-8. Asegúrate siempre de que la región de memoria sea lo bastante grande antes de escribir.

webassembly
// Wasm has no string type — strings live in linear memory.
// Decode UTF-8 from a (ptr, len) pair returned by Wasm:

function readString(memory, ptr, len) {
  const bytes = new Uint8Array(memory.buffer, ptr, len);
  return new TextDecoder('utf-8').decode(bytes);
}

// Writing a string into Wasm memory:
function writeString(memory, str, ptr) {
  const bytes = new TextEncoder().encode(str);
  const view = new Uint8Array(memory.buffer, ptr, bytes.length);
  view.set(bytes);
  return bytes.length; // return length
}
06

Tablas

Declarar tablas

Las tablas son arrays de referencias (normalmente funcref) usadas para llamadas indirectas y despacho dinámico. A diferencia de la memoria (que guarda bytes), las tablas guardan referencias opacas que Wasm no puede falsificar. Los segmentos (elem ...) inicializan los slots de la tabla al instanciar.

webassembly
(module
  ;; A table of function references, initial size 1
  (table 1 funcref)
  (export "table" (table 0))

  ;; With max size
  (table $t 4 16 funcref)

  ;; elem segment: initialize table slots
  (elem (i32.const 0) $fn1 $fn2 $fn3)
  (func $fn1)
  (func $fn2)
  (func $fn3)
)

Tablas funcref y call_indirect

call_indirect despacha una llamada a través de una entrada de la tabla por índice. La declaración (type ...) es obligatoria — Wasm comprueba en tiempo de ejecución que la firma de la función coincide (un desajuste de firma provoca un trap). Es la base de las vtables y del despacho orientado a objetos en Wasm.

webassembly
(module
  (type $bin (func (param i32 i32) (result i32)))
  (table 3 funcref)

  (func $add (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (func $sub (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.sub)
  (func $mul (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.mul)

  (elem (i32.const 0) $add $sub $mul)

  (func (export "dispatch") (param i32 i32 i32) (result i32)
    local.get 0      ;; arg a
    local.get 1      ;; arg b
    local.get 2      ;; table index
    call_indirect (type $bin)
  )
)

Crecer, obtener y fijar tablas

table.grow añade slots y devuelve el tamaño anterior (o -1). table.get/table.set leen/escriben entradas por índice. Hacer crecer una tabla permite registrar callbacks en tiempo de ejecución. Tamaño inicial + límites máximos de crecimiento para evitar asignaciones desbocadas.

webassembly
(func $addSlot (param funcref) (result i32)
  local.get 0
  i32.const 1            ;; grow by 1
  table.grow             ;; returns old size, or -1
)

(func $read (param i32) (result funcref)
  local.get 0
  table.get
)

(func $write (param i32 funcref)
  local.get 0     ;; index
  local.get 1     ;; funcref
  table.set
)

Tablas externref para objetos del host

Las tablas externref almacenan referencias opacas a objetos del host (JS) — Wasm puede guardarlas y pasarlas, pero no puede inspeccionar su contenido. Ideal para registro de callbacks, tablas de handles de JS y para tender puentes entre APIs de JS orientadas a objetos y Wasm.

webassembly
(module
  ;; Table holding opaque JS objects
  (table 8 externref)
  (export "table" (table 0))

  (func $store (param i32 externref)
    local.get 0
    local.get 1
    table.set
  )
  (func $load (param i32) (result externref)
    local.get 0
    table.get
  )
)

// JS: pass arbitrary objects
instance.exports.store(2, { callback: () => 42 });

Patrón de despacho dinámico

El patrón de despacho dinámico: guarda las operaciones en una tabla y luego call_indirect por índice. Combinado con la comprobación de tipos obligatoria, da un polimorfismo seguro estilo vtable. Así implementan el despacho los enums de Rust, las funciones virtuales de C++ y los intérpretes.

webassembly
(module
  (type $op (func (param i32 i32) (result i32)))
  (table 4 funcref)
  (elem (i32.const 0) $add $sub $mul $div)

  (func $add (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (func $sub (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.sub)
  (func $mul (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.mul)
  (func $div (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.div_s)

  (func (export "apply") (param $op i32) (param $a i32) (param $b i32)
    (result i32)
    local.get $a
    local.get $b
    local.get $op
    call_indirect (type $op)
  )
)
07

Globales

Declarar globales

Los globales son valores únicos a nivel de módulo, inmutables (por defecto) o mutables (mut). Persisten entre llamadas a funciones y son útiles para contadores, flags de configuración y constantes. Los globales mutables son el único estado mutable compartido fuera de memoria/tablas.

webassembly
(module
  ;; Immutable global (const)
  (global $counter (mut i32) (i32.const 0))

  ;; Read-only global
  (global $pi f64 (f64.const 3.14159265))

  (func $increment
    global.get $counter
    i32.const 1
    i32.add
    global.set $counter
  )
)

Globales mutables vs inmutables

Sin 'mut', un global es inmutable y global.set es un error de compilación. El inicializador debe ser una expresión constante (p. ej., i32.const, ref.null, global.get de un global importado inmutable). Elige inmutable por defecto por seguridad.

webassembly
(module
  ;; (global $name type init)        -> immutable
  ;; (global $name (mut type) init)  -> mutable

  (global $version i32 (i32.const 3))
  ;; global.set $version  ;; ERROR: immutable

  (global $state (mut i32) (i32.const 0))
  (func (export "toggle")
    global.get $state
    i32.eqz
    if
      i32.const 1  global.set $state
    else
      i32.const 0  global.set $state
    end
  )
)

Importar globales

Los globales importados permiten al host inyectar valores de configuración (u objetos WebAssembly.Global) en un módulo al instanciar. Los globales importados inmutables pueden inicializar otros globales. WebAssembly.Global es el envoltorio visible desde JS para globales compartidos mutables.

webassembly
(module
  ;; Import a global from JS
  (global $env (import "env" "version") i32)

  ;; Mutable imported global
  (global $flag (import "env" "flag") (mut i32))

  (func (export "ver") (result i32)
    global.get $env
  )
)

// JS side
const imports = {
  env: {
    version: 3,
    flag: new WebAssembly.Global({ value: 'i32', mutable: true }, 0)
  }
};

Exportar y compartir globales

Los globales exportados son accesibles desde JS como objetos WebAssembly.Global con una propiedad .value (legible y, si es mutable, escribible). Compartir un objeto Global entre varias instancias de módulo es una forma limpia de coordinar estado sin tocar la memoria.

webassembly
(module
  (global $g (export "counter") (mut i32) (i32.const 0))
  (func (export "inc")
    global.get $g
    i32.const 1
    i32.add
    global.set $g
  )
)

// JS reads/writes the global directly
const g = instance.exports.counter;
g.value;        // 0
instance.exports.inc();
g.value;        // 1
g.value = 100;  // write directly

Casos de uso de los globales

Los globales encajan en tres patrones: (1) constantes de configuración importadas, (2) contadores/estado persistentes compartidos entre instancias, (3) resultados de cálculo cacheados. Son más simples que la memoria para valores únicos y visibles para varias instancias si se comparten vía JS.

webassembly
(module
  ;; Configuration constants
  (global $maxSize (import "config" "maxSize") i32)
  (global $debug   (import "config" "debug")   i32)

  ;; Persistent counters
  (global $calls (mut i32) (i32.const 0))

  (func (export "handle") (result i32)
    global.get $calls
    i32.const 1
    i32.add
    global.set $calls
    global.get $calls
  )
)
08

Imports y exports

Importar funciones

Los imports permiten que Wasm llame a funciones del host (JS). Cada import se identifica con un nombre de dos niveles (module, field). El objeto de imports pasado a instantiate debe coincidir con esos nombres. Los imports son la forma en que Wasm alcanza el exterior — I/O, logging, planificación.

webassembly
(module
  ;; Import a function under module.field naming
  (func $log (import "console" "log") (param i32))
  (func $now (import "env" "now") (result f64))

  (func (export "run")
    i32.const 42
    call $log        ;; -> console.log(42)
    call $now
    drop
  )
)

// JS
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
  console: { log: x => console.log('wasm:', x) },
  env:     { now: () => performance.now() }
});

Importar memoria

Importar memoria permite que varios módulos Wasm (y JS) compartan una región de memoria — la base de las 'librerías' Wasm. Un módulo asigna y escribe; otro lee. Esto compone módulos sin copiar datos y es el precursor del component model.

webassembly
(module
  (memory (import "env" "memory") 1)
  (func (export "writeHi")
    i32.const 0
    i32.const 72     ;; 'H'
    i32.store8
  )
)

// Shared memory across multiple modules:
const memory = new WebAssembly.Memory({ initial: 1 });
WebAssembly.instantiateStreaming(fetch('a.wasm'), { env: { memory } });
WebAssembly.instantiateStreaming(fetch('b.wasm'), { env: { memory } });
// Both modules read/write the SAME memory

Importar globales y tablas

Los globales y las tablas también pueden importarse, habilitando estado compartido y tablas de punteros a funciones entre módulos. WebAssembly.Table es el constructor de JS. Los globales importados mutables permiten al host influir dinámicamente en el comportamiento de Wasm sin recompilar el módulo.

webassembly
(module
  (global $seed (import "env" "seed") i32)
  (table (import "env" "table") 4 funcref)

  (func (export "rand") (result i32)
    global.get $seed
    i32.const 1103515245
    i32.mul
    i32.const 12345
    i32.add
    ;; (truncated LCG step)
  )
)

// JS provides the imports
const imports = {
  env: {
    seed: 42,
    table: new WebAssembly.Table({
      element: 'funcref', initial: 4, maximum: 16
    })
  }
};

Exportar funciones, memoria y tablas

Cualquier cosa declarada en un módulo puede exportarse: funciones, memoria, tablas, globales. Las exportaciones se convierten en propiedades de instance.exports. Las exportaciones de memoria dan a JS una vista del heap lineal; las de globales exponen objetos WebAssembly.Global; las de tablas exponen referencias a funciones.

webassembly
(module
  (memory 1)
  (table 2 funcref)
  (global $c (mut i32) (i32.const 0))

  (func (export "add") (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add)
  (export "memory" (memory 0))
  (export "table"  (table 0))
  (export "counter" (global $c))
)

// JS usage
const { add, memory, table, counter } = instance.exports;
add(2, 3);                              // 5
new Uint8Array(memory.buffer);          // raw bytes
table.get(0);                           // funcref
counter.value;                          // 0

Imports y exports en línea

Las anotaciones en línea (import "m" "f") y (export "name") son azúcar sintáctico — compilan al mismo binario que las formas independientes (import ...)/(export ...). Una única definición puede llevar un export en línea, pero los imports y exports de los elementos importados se declaran por separado.

webassembly
(module
  ;; Inline import (compact form)
  (func $log (import "env" "log") (param i32))

  ;; Inline export on function
  (func (export "add") (param i32 i32) (result i32)
    local.get 0  local.get 1  i32.add
  )

  ;; Inline export on memory
  (memory (export "mem") 1)

  ;; Inline import + export combined is NOT allowed;
  ;; a definition imports OR exports, not both.
)

Buenas prácticas del objeto de imports

Estructura el objeto de imports para que coincida con los nombres (module, field) del módulo. Valida los imports obligatorios antes de instanciar para dar errores claros. Envuelve las funciones del host con try/catch donde convenga — una excepción no capturada dentro de un import provoca un trap en el llamador Wasm.

webassembly
// Build a typed import object
const imports = {
  env: {
    log:       (i) => console.log('[wasm]', i),
    now:       () => performance.now(),
    abort:     () => { throw new Error('wasm abort'); },
    memory:    new WebAssembly.Memory({ initial: 1 }),
    seed:      42,
  }
};

// Validate imports before instantiation:
function checkImports(imports, required) {
  for (const [mod, fields] of Object.entries(required)) {
    for (const f of fields) {
      if (!imports[mod]?.[f] === undefined) {
        throw new Error(`Missing import: ${mod}.${f}`);
      }
    }
  }
}
09

Flujo de control

block

block crea un ámbito etiquetado del que salen las ramas (vía br). Las ramas en Wasm son estructuradas — solo pueden saltar al final de un block/loop/if que las contenga. Un block con (result ...) deja su valor en la pila al saltar hacia él o al caer en su fin.

webassembly
;; block: a labeled group with a single exit
(block $b
  i32.const 1
  i32.const 2
  i32.add
  ;; br $b exits the block (with optional value)
  br $b
  ;; unreachable code
)
;; stack now has the result of the block

;; Blocks can produce a value (multi-value):
(block $b (result i32)
  i32.const 42
  br $b
)

loop

loop es como block, pero br $loop salta al PRINCIPIO del bucle (continuando la iteración) en lugar del final. Es lo contrario de block. Wasm no tiene palabras clave for/while — la iteración se construye con loop + un br_if condicional.

webassembly
;; loop: a block whose br jumps back to the TOP
(func $count (param $n i32) (result i32)
  (local $i i32) (local $sum i32)
  i32.const 0  local.set $i
  i32.const 0  local.set $sum
  (loop $loop
    local.get $i
    local.get $n
    i32.lt_s
    if
      local.get $sum
      local.get $i
      i32.add
      local.set $sum
      local.get $i
      i32.const 1
      i32.add
      local.set $i
      br $loop        ;; jump back to loop start
    end
  )
  local.get $sum
)

if / else

if consume un i32 de la pila (distinto de cero = true). La cláusula (result ...) hace que el if produzca un valor cuando ambas ramas coinciden en tipo. Se permite un if sin else; la rama puede estar vacía. if es azúcar de block + br_if.

webassembly
;; if consumes a condition from the stack
(func $abs (param $x i32) (result i32)
  local.get $x
  if (result i32)
    local.get $x
  else
    i32.const 0
    local.get $x
    i32.sub       ;; negate
  end
)

;; if without else (no result)
(func (param i32)
  local.get 0
  if
    ;; do something only if non-zero
  end
)

br y br_if

br $etiqueta salta al FINAL del block/if nombrado (o al PRINCIPIO de un loop). br_if hace lo mismo condicionalmente. Las etiquetas también pueden ser numéricas (br 0 = la más interna). Ramificar con un valor lo deja en la pila — la forma idiomática de Wasm para retornar antes.

webassembly
;; br: unconditional branch to a label
(block $outer
  (block $inner
    br $inner       ;; exits inner
    br $outer       ;; exits outer (unreachable here)
  )
)

;; br_if: branch only if top of stack is non-zero
(func $clamp (param $x i32) (result i32)
  (block $done (result i32)
    local.get $x
    i32.const 100
    i32.gt_s
    br_if $done          ;; if x > 100, branch with...
    i32.const 100        ;; ...100 on the stack
    local.get $x
    i32.const 0
    i32.lt_s
    br_if $done          ;; if x < 0, branch with...
    i32.const 0          ;; ...0
    local.get $x         ;; else x
  )
)

br_table (switch)

br_table implementa un switch: consume un índice i32 y salta a una de las etiquetas listadas, o a la última (por defecto) si está fuera de rango. Anida los bloques de fuera hacia dentro para que cada caso pueda devolver su valor. Es la forma más eficiente de despachar según una etiqueta.

webassembly
;; br_table: jump table (like a C switch)
(func $dayName (param $d i32) (result i32)
  (block $default
    (block $sat
      (block $sun
        local.get $d
        br_table $sun $sat $default
      )
      i32.const 0  ;; Sunday
      return
    )
    i32.const 6   ;; Saturday
    return
  )
  i32.const -1    ;; default
)

;; br_table $l0 $l1 $l2 ... $default
;; index 0 -> $l0, 1 -> $l1, ... out-of-range -> $default

return y unreachable

return sale inmediatamente de la función con el valor en la pila. unreachable siempre provoca un trap (lanza una excepción en tiempo de ejecución) — sirve para marcar rutas de código que nunca deberían ejecutarse, similar a assert(false). Ambos son válvulas de escape del flujo de control más allá del modelo estructurado de bloques.

webassembly
(func $find (param $arr i32) (param $len i32) (param $key i32)
  (result i32)
  (local $i i32)
  i32.const 0  local.set $i
  (block $notFound
    (loop $loop
      local.get $i
      local.get $len
      i32.ge_s
      br_if $notFound
      ;; load arr[i] and compare...
      local.get $i
      i32.const 1
      i32.add
      local.set $i
      br $loop
    )
  )
  unreachable        ;; traps if reached
)

;; return: early exit from the function
;; unreachable: always traps (used to mark bugs)
10

Interoperabilidad con JS

Pasar números

i32/f32/f64 se mapean directamente a números de JS. i64 se mapea a BigInt de JS (los enteros grandes exceden el rango seguro de Number). Usa siempre BigInt para parámetros/retornos i64. La conversión es sin copias en la frontera, pero cruzarla con frecuencia tiene sobrecarga — agrupa operaciones dentro de Wasm.

webassembly
// Numbers pass directly across the Wasm/JS boundary.
const exports = instance.exports;

exports.add(2, 3);          // 5  (i32 -> JS number)
exports.square(4);          // 16
exports.compute(1.5, 2.5);  // f64 -> JS number

// i64 caveat: before BigInt integration, i64 returns
// caused problems. Now Wasm i64 maps to JS BigInt:
const big = exports.bigResult();  // 9007199254740993n

// Passing a BigInt to an i64 param:
exports.takeBigInt(123n);

Pasar strings

Los strings cruzan la frontera como secuencias de bytes UTF-8: JS los codifica en la memoria de Wasm y luego pasa (puntero, longitud). A menudo Wasm exporta helpers alloc/free, o empaquetas ambos en un único i64 (32 bajos = ptr, 32 altos = len). Libera o reutiliza siempre el buffer para evitar fugas.

webassembly
// Wasm has no string type. Encode UTF-8 into memory,
// pass (ptr, len) to Wasm:

function passString(memory, str) {
  const bytes = new TextEncoder().encode(str);
  const ptr = instance.exports.alloc(bytes.length);
  new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);
  instance.exports.processString(ptr, bytes.length);
  instance.exports.dealloc(ptr, bytes.length);
}

// Receiving a string back:
function recvString(memory, ptrLen) {
  const ptr = ptrLen >>> 0;
  const len = ptrLen >>> 32;
  const bytes = new Uint8Array(memory.buffer, ptr, len);
  return new TextDecoder().decode(bytes);
}

Pasar arrays y datos en bloque

Para datos numéricos en bloque, mira la memoria de Wasm como un TypedArray del tipo adecuado (Float32Array, Int32Array, etc.) y usa .set() para copiar. Es la vía más rápida — tipo memcpy. Recuerda la alineación de punteros (4 bytes para i32/f32, 8 para i64/f64) y libera siempre la memoria.

webassembly
// Write a JS array into Wasm memory:
function passArray(memory, arr) {
  const view = new Float32Array(memory.buffer);
  const ptr = instance.exports.alloc(arr.length * 4);
  const offset = ptr / 4;
  for (let i = 0; i < arr.length; i++) view[offset + i] = arr[i];
  return ptr;
}

// Faster: use TypedArray.set with a subarray
function passArrayFast(memory, arr) {
  const ptr = instance.exports.alloc(arr.length * 4);
  new Float32Array(memory.buffer, ptr, arr.length).set(arr);
  return ptr;
}

Gestión de memoria a través de la frontera

La memoria de Wasm se gestiona manualmente — no hay recolector de basura. Si Wasm exporta alloc/free (o usas un helper tipo malloc), envuelve el acceso de JS en try/finally para garantizar la liberación. Vigila que memory.grow desacopla las vistas del ArrayBuffer — recrea las vistas tras crecer.

webassembly
// Wasm has no GC — JS must manage allocations.
// Pattern: Wasm exports alloc/free, JS uses them:

const { memory, alloc, free, process } = instance.exports;

function withBuffer(size, fn) {
  const ptr = alloc(size);
  try {
    return fn(new Uint8Array(memory.buffer, ptr, size));
  } finally {
    free(ptr, size);
  }
}

// CAUTION: TypedArray views become detached after
// memory.grow — re-create them after any grow call.

WebAssembly.Global

WebAssembly.Global es un envoltorio de JS alrededor de un valor global de Wasm. Crear uno y pasarlo a varias instancias de módulo comparte estado mutable de forma limpia sin tocar la memoria. La propiedad .value lee/escribe el i32/i64/f32/f64 subyacente (o v128/externref).

webassembly
// Create a global on the JS side
const counter = new WebAssembly.Global(
  { value: 'i32', mutable: true },
  0
);

// Pass to Wasm at instantiation
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
  env: { counter }
});

// Read/write from JS
counter.value;        // 0
counter.value = 10;   // set
counter.value++;      // 11

// Share across multiple instances
WebAssembly.instantiateStreaming(fetch('m2.wasm'), {
  env: { counter }    // same Global object
});

WebAssembly.Table y errores

WebAssembly.Table guarda referencias a funciones accesibles tanto desde JS como desde Wasm — útil para registros de callbacks y tablas de despacho. Los traps de Wasm (división por cero, memoria fuera de rango, desbordamiento de pila) se manifiestan como WebAssembly.RuntimeError en JS — envuelve las llamadas riesgosas en try/catch.

webassembly
// Table of function references, callable from JS indirectly
const table = new WebAssembly.Table({
  element: 'funcref',
  initial: 4,
  maximum: 16
});

// Set a slot to a Wasm-exported function
table.set(0, instance.exports.add);
table.get(0)(2, 3);  // 5

// Errors propagate as 'RuntimeError' across the boundary:
try {
  instance.exports.divide(1, 0);
} catch (e) {
  // e instanceof WebAssembly.RuntimeError
  console.error('Wasm trapped:', e.message);
}
11

Compilar C/C++ a Wasm

Configuración de Emscripten

Emscripten es el toolchain canónico para compilar C/C++ (y lenguajes LLVM) a Wasm. Agrupa Clang, Binaryen y una libc/libstdc++ portada al navegador. Activa el entorno en cada sesión de shell con emsdk_env. Se actualiza con frecuencia — reinstala periódicamente.

webassembly
# Install the Emscripten SDK
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh   # Linux/macOS
# Windows: emsdk_env.bat

# Verify
emcc --version
# emcc (Emscripten gcc/clang-like replacement)

Hola mundo en C

El C estándar funciona tal cual — printf escribe en un terminal virtual que Emscripten proporciona. main() se invoca automáticamente cuando el módulo carga. Las funciones llamadas desde JS deben exportarse con EMSCRIPTEN_KEEPALIVE o con el flag -s EXPORTED_FUNCTIONS.

webassembly
// hello.c
#include <stdio.h>

int add(int a, int b) {
    return a + b;
}

int main() {
    printf("Hello from C!\n");
    printf("2 + 3 = %d\n", add(2, 3));
    return 0;
}

Compilar con emcc

emcc dirige la compilación. -O3 activa optimizaciones agresivas (inlining, eliminación de código muerto). EXPORTED_FUNCTIONS lista los símbolos C (con _ inicial) a exponer. MODULARIZE envuelve el cargador como una fábrica para usarlo en bundlers. Formatos de salida: solo .wasm, glue .js + .wasm, o demo .html.

webassembly
# Standalone .wasm (no main, exported functions only)
emcc add.c -O3 -o add.wasm \
  -s EXPORTED_FUNCTIONS='["_add"]' \
  -s ALLOW_MEMORY_GROWTH=1

# HTML + JS + Wasm bundle (auto-runs main)
emcc hello.c -o hello.html

# With optimizations and a specific output
emcc hello.c -O3 -s WASM=1 -o hello.js

# Common flags:
#   -O0/-O1/-O2/-O3/-Os   optimization level
#   -s MODULARIZE=1       export as JS module
#   -s EXPORT_ES6=1       ES module output
#   -s ENVIRONMENT=web    target only the web

Salida HTML y módulo de Emscripten

El objeto 'Module' de Emscripten es el runtime del lado JS: expone las funciones C con prefijo _, gestiona la memoria (_malloc/_free) y ofrece hooks (print, onRuntimeInitialized). MODULARIZE lo convierte en una fábrica que devuelve una Promise, apta para bundlers y carga asíncrona.

webassembly
// Generate a runnable HTML demo
//   emcc hello.c -o hello.html
// Then open hello.html in a browser.

// Modularized loader (use from JS):
//   emcc hello.c -o hello.js -s MODULARIZE=1 -s EXPORT_NAME='createModule'

import createModule from './hello.js';

const Module = await createModule({
  print: (text) => console.log('C said:', text),
  onRuntimeInitialized: () => {
    Module._main();          // call main
    const sum = Module._add(2, 3);
    console.log('sum:', sum);  // 5
  }
});

Llamar a JS desde C (EM_JS / EM_ASM)

EM_JS define una función JS en línea que C puede llamar directamente — eficiente y síncrono. EM_ASM incrusta un fragmento JS en línea. Usa $0, $1, ... para los argumentos. Estas macros pegan C a las APIs del navegador (DOM, fetch, Web Audio) sin escribir bindings JS aparte.

webassembly
#include <emscripten.h>

// EM_JS: define a JS function callable from C
EM_JS(void, callAlert, (int x), {
  alert("Value from C: " + x);
});

// EM_ASM: inline JS (use $n for arguments)
void logValue(int n) {
  EM_ASM({
    console.log("C passed:", $0);
  }, n);
}

int main() {
  callAlert(42);
  logValue(99);
  return 0;
}

Soporte de sistema de archivos (MEMFS)

Emscripten ofrece MEMFS, un sistema de archivos virtual en memoria. fopen/fread/fwrite funcionan como en C. Usa --preload-file para incrustar recursos en el sidecar .data en tiempo de compilación. Para almacenamiento persistente, IDBFS sincroniza con IndexedDB; NODERAWFS expone el sistema de archivos real en Node.

webassembly
#include <stdio.h>
#include <emscripten.h>

int main() {
    // MEMFS: a virtual in-memory filesystem
    FILE *f = fopen("/tmp/data.txt", "w");
    fprintf(f, "Hello, MEMFS!\n");
    fclose(f);

    f = fopen("/tmp/data.txt", "r");
    char buf[64];
    fgets(buf, sizeof(buf), f);
    fclose(f);
    printf("%s", buf);
    return 0;
}

// Preload files at compile time:
//   emcc app.c -o app.html \
//     --preload-file assets/data.txt
12

Compilar Rust a Wasm

Configuración de wasm-pack

Rust compila a Wasm mediante el target wasm32-unknown-unknown. wasm-pack es la herramienta recomendada — envuelve a cargo, ejecuta wasm-bindgen y produce un paquete listo para npm. Para targets WASI, usa wasm32-wasi en su lugar.

webassembly
# Install Rust (rustup)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Add the wasm32 target
rustup target add wasm32-unknown-unknown

# Install wasm-pack (the canonical Wasm tool for Rust)
cargo install wasm-pack
# or: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Verify
wasm-pack --version

Estructura de librería Rust

wasm-bindgen es el puente entre Rust y JS. #[wasm_bindgen] marca los elementos a exportar. Los strings, Vec<u8> y objetos JS se convierten automáticamente. El atributo de constructor expone new() como constructor de JS. Genera el glue de JS que hace que Rust se sienta nativo.

webassembly
// src/lib.rs
use wasm_bindgen::prelude::*;

// Export a function callable from JS
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

// Export a struct with methods
#[wasm_bindgen]
pub struct Counter {
    count: i32,
}

#[wasm_bindgen]
impl Counter {
    #[wasm_bindgen(constructor)]
    pub fn new() -> Counter {
        Counter { count: 0 }
    }
    pub fn increment(&mut self) -> i32 {
        self.count += 1;
        self.count
    }
}

Compilar con wasm-pack

wasm-pack build produce un paquete npm publicable: el binario .wasm, el glue de JS y los archivos .d.ts de TypeScript. --target web da un módulo ES autocontenido para uso directo en el navegador; --target bundler se integra con webpack/vite. Los tipos generados dan autocompletado completo de TS.

webassembly
# Build for the browser (npm package output)
wasm-pack build --target web

# Targets:
#   --target web       ES module, modern browsers
#   --target bundler   for webpack/rollup/vite
#   --target nodejs    CommonJS for Node.js
#   --target no-modules  global-based

# Output goes to ./pkg/
#   my_crate.js       JS glue
#   my_crate_bg.wasm  the binary
#   my_crate.d.ts     TypeScript types

# Use in JS:
import init, { add } from './pkg/my_crate.js';
await init();           // load the .wasm
console.log(add(2, 3)); // 5

wasm-bindgen: interoperabilidad con JS

Los bloques extern importan funciones y clases de JS a Rust. js_namespace = console llama a console.log. method expone las funciones miembro de JS sobre tipos importados. wasm-bindgen se encarga de las conversiones de strings (&str de Rust <-> string de JS) y de la propiedad — sin malabares manuales de memoria.

webassembly
use wasm_bindgen::prelude::*;

// Call a JS function from Rust
#[wasm_bindgen]
extern "C" {
    #[wasm_bindgen(js_namespace = console)]
    fn log(s: &str);
}

#[wasm_bindgen]
pub fn run() {
    log("Hello from Rust!");
}

// Import a JS class
#[wasm_bindgen(module = "/js/util.js")]
extern "C" {
    pub type JsCounter;
    #[wasm_bindgen(constructor)]
    pub fn new() -> JsCounter;
    #[wasm_bindgen(method)]
    pub fn tick(this: &JsCounter) -> i32;
}

Llamar a JS desde Rust y panics

Las funciones JS importadas aparecen como funciones Rust ordinarias. Usa console_error_panic_hook para obtener backtraces legibles de panics de Rust en la consola del navegador (por defecto los panics hacen trap sin mensaje). El atributo #[wasm_bindgen(start)] ejecuta main() al instanciar — como el main de C.

webassembly
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
extern "C" {
    fn alert(s: &str);
}

#[wasm_bindgen]
pub fn greet(name: &str) {
    alert(&format!("Hello, {}!", name));
}

// Install a panic hook for readable errors:
#[wasm_bindgen(start)]
pub fn main() {
    console_error_panic_hook::set_once();
}
13

AssemblyScript

Configuración y hola mundo

AssemblyScript es un lenguaje parecido a TypeScript que compila a Wasm. Apunta a desarrolladores que quieren el rendimiento de Wasm sin aprender C/Rust. La sintaxis imita a TS pero con tipos estrictos (i32 en lugar de number). Usa el loader o importa el .wasm directamente.

webassembly
# Install AssemblyScript compiler
npm install -g assemblyscript
# or use the boilerplate:
npm init assemblyscript my-app
cd my-app
npm install
npm run asbuild

// assembly/index.ts
export function add(a: i32, b: i32): i32 {
  return a + b;
}

// Load from JS:
import { instantiate } from "@assemblyscript/loader";
const module = await instantiate(fetch("build/release.wasm"));
console.log(module.exports.add(2, 3)); // 5

Tipos en AssemblyScript

A diferencia de TypeScript, AssemblyScript exige tipos numéricos concretos: i32, i64, f32, f64, u8, u16, u32, etc. 'number' se rechaza en compilación. StaticArray evita el GC; ArrayBuffer/TypedArray imitan las APIs de JS. El tipado estricto es lo que permite compilar a un Wasm eficiente.

webassembly
// Distinct numeric types (NOT just 'number')
let a: i32 = 42;
let b: i64 = 9007199254740993n;
let f: f64 = 3.14;
let u: u32 = 100;

// Bool, string, arrays
let flag: bool = true;
let s: string = "hi";
let arr: i32[] = [1, 2, 3];

// Static arrays (no GC overhead)
let sa: StaticArray<i32> = [1, 2, 3];

// TypedArray-like
let buf: ArrayBuffer = new ArrayBuffer(8);

Memoria y strings

AssemblyScript tiene un pequeño GC para objetos gestionados (Array, Map, String). Usa __retain/__release para controlar los ciclos de vida al cruzar a JS. @assemblyscript/loader ofrece __getString, __newString, __getArray, etc., para tender el puente a través de la frontera.

webassembly
// Strings are UTF-16 in AssemblyScript memory
export function greet(name: string): string {
  return "Hello, " + name + "!";
}

// Manual memory management for buffers
export function process(len: i32): i32 {
  let buf = new ArrayBuffer(len);
  // ...fill buf...
  let result = __retain(buf);  // prevent GC
  return result;
}

// In JS, use the loader's __getString/__newString:
const ptr = module.exports.greet("World");
console.log(module.exports.__getString(ptr));

Exports y puntos de entrada

Las funciones y clases marcadas como export se convierten en exportaciones Wasm. Las clases se mapean a objetos compatibles con JS vía el loader. _start es el punto de entrada convencional (como el main de C). La stdlib de AssemblyScript imita Math, Array, Map de JS — haciendo suave la curva de migración.

webassembly
// assembly/index.ts
export function fib(n: i32): i32 {
  if (n < 2) return n;
  return fib(n - 1) + fib(n - 2);
}

export class Vector {
  constructor(public x: f32, public y: f32) {}
  magnitude(): f32 {
    return Math.sqrt(this.x * this.x + this.y * this.y);
  }
}

// Module start function (runs at instantiation)
export function _start(): void {
  // initialization code
}

Compilación y optimizaciones

asc es el compilador de AssemblyScript. --optimize (-O) ejecuta wasm-opt de Binaryen. --runtime controla el GC: 'full' (por defecto), 'half' (menor), 'none' (manual). --importMemory permite compartir memoria entre módulos. Los source maps permiten depurar en el código .ts original.

webassembly
# Build debug vs release
npm run asbuild           # both debug and release
# or:
asc assembly/index.ts --outFile release.wasm --optimize

# Common flags
asc index.ts -o release.wasm \
  --optimize \
  --noAssert \
  --runtime half          # smaller GC runtime
  --importMemory          # use imported memory
  --sourceMap             # emit source map

# Optimize for size:
asc index.ts -o tiny.wasm --optimize --runtime none \
  --conformance --noDebug
14

WASI (WebAssembly System Interface)

Qué es WASI

WASI es una interfaz de sistema portable y basada en capacidades para Wasm fuera del navegador. A diferencia de la web, donde Wasm llama a JS, WASI da a Wasm acceso directo (y aislado) a archivos, red y entorno. La seguridad basada en capacidades significa que un programa solo puede tocar los recursos que se le preabren explícitamente.

webassembly
// WASI = WebAssembly System Interface
// A standardized API for Wasm to access OS capabilities:
//   - filesystem (files, directories)
//   - network sockets (preview2)
//   - environment variables, args
//   - clocks, random numbers
//   - process exit

// Capability-based security: a Wasm program can
// ONLY access resources it was explicitly granted.

// Targets:
//   wasm32-wasi           (preview1)
//   wasm32-wasip1         (preview1, new name)
//   wasm32-wasip2         (preview2, component model)

// Runtimes: wasmtime, wasmer, WasmEdge, browser_wasi_shim

Runtime wasmtime

wasmtime es el runtime de referencia para WASI del Bytecode Alliance. --dir preabre un directorio del host (concediendo acceso a archivos). --env pasa variables de entorno. --net activa la red en preview2. Sin concesiones explícitas, el programa Wasm no ve nada — ahí está la seguridad por capacidades en acción.

webassembly
# Install wasmtime (the reference WASI runtime)
# macOS:  brew install wasmtime
# Linux:  curl https://wasmtime.dev/install.sh -sSf | bash
# Windows: scoop install wasmtime

# Run a WASI module
wasmtime hello.wasm

# Pass arguments
wasmtime hello.wasm arg1 arg2

# Preopen a directory (grant filesystem access)
wasmtime --dir=. app.wasm

# Set environment variables
wasmtime --env FOO=bar app.wasm

# Allow network (preview2)
wasmtime --net allow app.wasm

Ejecutar Wasm con WASI (ejemplo en C)

Los programas escritos para WASI parecen programas C ordinarios que usan libc. Compila con clang --target=wasm32-wasi y un sysroot WASI (descarga la release de wasi-sdk). El mismo .wasm corre en wasmtime, wasmer, WasmEdge y otros hosts WASI sin recompilar — portabilidad real.

webassembly
// wasi_hello.c
#include <stdio.h>
#include <unistd.h>

int main(int argc, char *argv[]) {
    printf("Hello from WASI!\n");
    printf("argc = %d\n", argc);
    for (int i = 0; i < argc; i++) printf("  argv[%d] = %s\n", i, argv[i]);
    return 0;
}

# Compile with the WASI SDK
clang --target=wasm32-wasi \
  --sysroot=/path/to/wasi-sysroot \
  -o hello.wasm wasi_hello.c

# Run
wasmtime hello.wasm foo bar
# Hello from WASI!
# argc = 3
#   argv[0] = hello.wasm
#   argv[1] = foo
#   argv[2] = bar

Acceso al sistema de archivos con WASI

WASI expone una API de sistema de archivos tipo POSIX (open, read, write, close). Los archivos fuera de los directorios preabiertos son invisibles. Usa --dir=ruta:alias para conceder acceso y renombrar. WASI preview2 introduce interfaces del component model (wasi filesystem, wasi sockets) para APIs más ricas.

webassembly
// wasi_fs.c — read a file passed via --dir
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>

int main() {
    int fd = open("input.txt", O_RDONLY);
    if (fd < 0) { perror("open"); return 1; }
    char buf[256];
    ssize_t n = read(fd, buf, sizeof(buf) - 1);
    if (n > 0) { buf[n] = '\0'; printf("%s", buf); }
    close(fd);
    return 0;
}

# Grant access, then run:
#   wasmtime --dir=. wasi_fs.wasm

Entorno y argumentos de WASI

WASI proporciona args y variables de entorno vía las interfaces estándar de C (argv, environ, getenv). El host controla qué se ve — --env concede variables concretas. Esto hace que los programas Wasm sean configurables sin cambios de código y limita la fuga de secretos del host.

webassembly
// wasi_env.c
#include <stdio.h>
#include <stdlib.h>

extern char **environ;

int main(int argc, char *argv[]) {
    printf("Args:\n");
    for (int i = 0; i < argc; i++) printf("  %s\n", argv[i]);

    printf("Env:\n");
    for (char **e = environ; *e; e++) printf("  %s\n", *e);

    const char *home = getenv("HOME");
    printf("HOME=%s\n", home ? home : "(unset)");
    return 0;
}

# Run with env vars:
#   wasmtime --env HOME=/tmp --env FOO=bar wasi_env.wasm a b c

Sockets WASI (preview)

Los sockets WASI forman parte de preview2 (component model). wasi:sockets/tcp y wasi:sockets/udp ofrecen red; wasi:http aporta un cliente HTTP de más alto nivel. Las APIs se están estabilizando — prefiere wasi:http hoy por portabilidad. Runtimes como wasmtime y WasmEdge los implementan.

webassembly
// WASI preview2 adds TCP/UDP sockets.
// In Rust (using wasi crate):
use wasi::sockets::network::{IpAddress, IpSocketAddress};

// Component-model based sockets:
//   - wasi:sockets/tcp
//   - wasi:sockets/udp
//   - wasi:sockets/ip-name-lookup

# Compile a Rust program for preview2:
cargo build --target wasm32-wasip2 --release

# Run with network access:
wasmtime --net allow target/wasm32-wasip2/release/myapp.wasm

// Note: socket APIs are still stabilizing.
// Use HTTP via wasi:http/types for stability.
15

Depuración

wasm-objdump

wasm-objdump (de WABT) imprime la estructura de un módulo: tipos, imports, exports, firmas de funciones, desensamblado del código y tamaños de secciones. -x da un resumen de alto nivel; -d desensambla los cuerpos de las funciones en instrucciones tipo WAT. Esencial para entender qué contiene realmente un módulo.

webassembly
# Inspect a .wasm file's structure
wasm-objdump -x module.wasm       # everything
wasm-objdump -d module.wasm       # disassemble functions
wasm-objdump -s module.wasm       # raw section contents
wasm-objdump -j Import -x m.wasm  # only the Import section

# Sample -x output:
# Section Type (1) at 0x0008:
#   type[0] (i32, i32) -> i32
# Section Function (3) at 0x0015:
#   func[0] type=0

wasm2wat para inspección

wasm2wat convierte un .wasm binario de vuelta a WAT legible por humanos. Es inestimable para entender módulos de terceros, depurar comportamientos inesperados e ingeniería inversa. El viaje de ida y vuelta (wasm2wat → editar → wat2wasm) preserva el comportamiento, haciendo de WAT un verdadero formato fuente.

webassembly
# Disassemble binary to readable text
wasm2wat module.wasm -o module.wat

# View in your editor
cat module.wat

# Round-trip: edit .wat, recompile
wat2wasm module.wat -o module.wasm

# Common inspection: find exports
grep "(export" module.wat

# Find imports
grep "(import" module.wat

DevTools del navegador

La totalidad de los navegadores importantes pueden depurar Wasm en DevTools: ver el WAT desensamblado, fijar breakpoints, inspeccionar locales y la pila de llamadas. Con source maps (Rust, AssemblyScript, Emscripten -g), DevTools mapea de vuelta al código fuente original. La información de depuración DWARF habilita una depuración más rica para C/C++/Rust.

webassembly
// Chrome/Edge/Firefox DevTools support Wasm debugging:
//   1. Sources tab -> file tree shows .wasm entries
//   2. Click a .wasm to view disassembled WAT
//   3. Set breakpoints on function entries
//   4. Inspect the call stack and locals

// With source maps (Rust/AS), DevTools shows the
// ORIGINAL source (.rs / .ts) instead of WAT.

// Enable in chrome://flags:
//   "WebAssembly debugging: Support DWARF"

// Console logging from Wasm:
//   Import a JS log function and call it from WAT.
//   Rust: wasm_logger / console_log crate.
//   AS:   console.log via env import.

Source maps

Los source maps vinculan las instrucciones Wasm de vuelta al lenguaje fuente original. Rust los emite vía wasm-pack; AssemblyScript vía --sourceMap; Emscripten vía -g4. El comentario sourceMappingURL en el .wasm (sección personalizada) le dice a DevTools dónde encontrar el .map. Sin él, depuras WAT crudo.

webassembly
# Rust: source maps come automatically with wasm-pack
wasm-pack build --target web --dev

# AssemblyScript: emit source maps
asc index.ts -o release.wasm --sourceMap \
  --sourceMap include 'src/**/*.ts'

# Emscripten: include debug info and source map
emcc app.c -g4 -O0 -o app.js \
  --source-map-base http://localhost:8000/

# The .map file points DevTools back to the
# original .rs / .ts / .c source files.

# Validate a source map exists:
wasm-objdump -x app.wasm | grep sourceMappingURL

Errores y traps comunes

Errores de Wasm recurrentes: imports faltantes (nombres/tipos que no coinciden), traps (unreachable, memoria fuera de rango, desbordamiento de entero al dividir por cero), ArrayBuffers desacoplados (tras grow) y problemas de frontera con i64. Envuelve las llamadas riesgosas en try/catch y valida imports/punteros de entrada para destapar problemas pronto.

webassembly
// 1. LinkError: "import not found"
//    Cause: import object missing a name.
const imports = { env: { log: console.log } };
// Must match (import "env" "log" ...) exactly.

// 2. RuntimeError: "unreachable"
//    Cause: Wasm executed unreachable / panic / assert.

// 3. RuntimeError: "out of bounds memory access"
//    Cause: load/store at an invalid address.
//    Fix: check ptr/len before access; grow memory.

// 4. CompileError: "section size mismatch"
//    Cause: corrupted or truncated .wasm file.

// 5. TypeError: "i64 not supported"
//    Cause: i64 returns without BigInt integration.
//    Fix: use BigInt, or return two i32 values.

// 6. "detached ArrayBuffer"
//    Cause: used a TypedArray view after memory.grow.
//    Fix: re-create views after grow.
16

Optimización de rendimiento

Inlining y flags -O

-O3 activa el inlining agresivo y las optimizaciones de bucles. wasm-opt (Binaryen) ejecuta pasadas adicionales a nivel Wasm (inlining, código muerto, plegado de constantes) — ejecútalo siempre en producción. -Os/-Oz cambian algo de velocidad por descargas menores. -flto habilita la optimización de programa completo.

webassembly
# Compilation optimization levels
emcc app.c -O0 -o app.wasm   # no optimization (debug)
emcc app.c -O1 -o app.wasm   # basic
emcc app.c -O2 -o app.wasm   # standard
emcc app.c -O3 -o app.wasm   # aggressive (inlining)
emcc app.c -Os -o app.wasm   # optimize for size
emcc app.c -Oz -o app.wasm   # max size reduction

# Post-optimize with Binaryen
wasm-opt -O3 app.wasm -o app.opt.wasm
wasm-opt -Os app.wasm -o app.small.wasm

# LTO across translation units (C/C++)
emcc app.c -flto -O3 -o app.wasm

Layout de memoria y patrones de acceso

La memoria lineal de Wasm es simplemente un ArrayBuffer — se aplica el comportamiento de la caché de CPU. Los patrones de acceso contiguos (row-major para datos row-major) son dramáticamente más rápidos que el acceso con saltos. Mantén la alineación natural (4 bytes para i32) para que los loads/stores encajen en instrucciones únicas.

webassembly
// Cache-friendly access: linear, contiguous iteration
// GOOD: row-major traversal of a 2D array
for (i32 row = 0; row < rows; row++) {
  for (i32 col = 0; col < cols; col++) {
    sum += data[row * cols + col];
  }
}

// BAD: column-major traversal (cache misses)
for (i32 col = 0; col < cols; col++) {
  for (i32 row = 0; row < rows; row++) {
    sum += data[row * cols + col];
  }
}

// Prefer aligned access (4-byte for i32, 8 for i64).
// Allocators should respect natural alignment.

Minimizar cruces de la frontera con JS

Cada llamada JS→Wasm tiene sobrecarga (empaquetado de argumentos, preparación de pila). Para bucles ajustados, mueve el bucle DENTRO de Wasm y llámalo una vez con un buffer. Este es el mayor consejo de rendimiento de Wasm — las operaciones en bloque superan por órdenes de magnitud a las llamadas por elemento.

webassembly
// BAD: call Wasm per element (boundary overhead)
for (let i = 0; i < arr.length; i++) {
  result[i] = exports.process(arr[i]);
}

// GOOD: batch — one call for the whole array
const ptr = exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
exports.processBatch(ptr, arr.length);   // single call
const out = Array.from(new Float32Array(memory.buffer, ptr, arr.length));
exports.free(ptr, arr.length * 4);

// Each crossing costs ~tens of nanoseconds.
// Batch loops to amortize the overhead.

SIMD (una instrucción, múltiples datos)

SIMD (v128) procesa 4 floats o 4 int32 por instrucción — aceleraciones de 4x para matemáticas de imagen/audio/matrices. Emscripten lo activa con -msimd128; Rust usa intrínsecos de std::arch::wasm32. La auto-vectorización puede ayudar, pero los intrínsecos explícitos dan victorias predecibles. Ampliamente soportado en navegadores.

webassembly
// C/C++ with Emscripten auto-vectorization
#include <emscripten/simd.h>
void addArrays(float *a, float *b, float *out, int n) {
    for (int i = 0; i < n; i += 4) {
        v128_t va = wasm_v128_load(a + i);
        v128_t vb = wasm_v128_load(b + i);
        wasm_v128_store(out + i, wasm_f32x4_add(va, vb));
    }
}

# Compile with SIMD enabled
emcc simd.c -O3 -msimd128 -o simd.wasm

// Rust: use std::arch::wasm32 intrinsics
use std::arch::wasm32::*;
unsafe { let v = f32x4_splat(1.0); }

Threads y SharedArrayBuffer

Los threads de Wasm comparten una Memory entre Web Workers, usando atómicos para sincronizar. Requiere cabeceras COOP/COEP (aislamiento cross-origin). El -pthread de Emscripten emula pthreads; el std::thread de Rust funciona en wasm32-wasi-threads. Genial para trabajo paralelo intensivo de CPU — procesamiento de imagen, códecs, inferencia de ML.

webassembly
// Enable threads in Emscripten
# emcc app.c -O3 -pthread -s PTHREAD_POOL_SIZE=4 -o app.js

// Browser requires cross-origin isolation:
//   /_headers (Cloudflare/Netlify)
//   Cross-Origin-Opener-Policy: same-origin
//   Cross-Origin-Embedder-Policy: require-corp

// Spawn workers sharing Wasm memory:
const memory = new WebAssembly.Memory({
  initial: 10, maximum: 100, shared: true
});
// Each Worker instantiates the module with this memory
// and uses Atomics for synchronization.

Profiling y benchmarks

Perfila con performance.now() y la pestaña Performance de DevTools — Wasm aparece en los flame charts como JS. Calienta antes de medir (la sobrecarga de compilación es de una sola vez). Compara con JS optimizado — el V8 moderno es rápido; Wasm gana en rendimiento predecible, kernels numéricos y cargas grandes, no en microtareas.

webassembly
// Use performance.now() for high-res timing
const t0 = performance.now();
exports.heavyWork(ptr, len);
const t1 = performance.now();
console.log(`Wasm: ${(t1 - t0).toFixed(2)}ms`);

// Compare against JS equivalent
const t2 = performance.now();
jsEquivalent(data);
console.log(`JS:   ${(performance.now() - t2).toFixed(2)}ms`);

// Chrome DevTools Performance tab: profile Wasm
// like JS — flame charts show function time.

// Avoid microbenchmarks pitfalls:
//   - warm up first (JIT compilation)
//   - run many iterations
//   - compare against OPTIMIZED JS, not naive JS
17

Wasm vs JavaScript

Comparación de rendimiento

Wasm brilla en el trabajo numérico intensivo de cómputo (procesamiento de imagen, códecs, criptografía, ML) — típicamente 2-10x más rápido que JS. Para DOM, JSON o trabajo con muchos strings, JS suele ser más rápido porque el trabajo ya está en código nativo (el JSON.parse de V8, el DOM del navegador). Perfila para decidir — nunca asumas que Wasm siempre es más rápido.

webassembly
// Wasm vs JS — typical scenarios:
//
// Image processing (8MB):
//   JS:          120 ms
//   Wasm (-O3):   35 ms    ~3.4x faster
//
// SHA-256 (1MB):
//   JS:           45 ms
//   Wasm:          8 ms    ~5.6x faster
//
// DOM manipulation:
//   JS:            5 ms
//   Wasm:         20 ms    SLOWER (DOM is JS-native)
//
// JSON parse:
//   JS:            3 ms
//   Wasm:         15 ms    SLOWER (JSON.parse is C++ in V8)
//
// Rule of thumb: Wasm wins on compute-heavy numeric
// workloads; JS wins on DOM/JSON/string-heavy tasks.

Casos de uso de Wasm

Wasm destaca en: portar bases de código C/C++/Rust existentes (Figma, Photoshop web), kernels numéricos intensivos de cómputo (imagen/ML/criptografía) y plugins aislados. Victorias reales: Figma (renderizador), Photoshop (port de la app completa) y Google Meet (desenfoque de fondo). Para apps de DOM puro, JS suele ser la elección correcta.

webassembly
// Strong Wasm use cases:
//   - Image/video/audio processing (FFmpeg, OpenCV)
//   - Games & 3D engines (Unity, Unreal)
//   - Cryptography (hashing, encryption, ZK proofs)
//   - Machine learning inference (ONNX, TFLite)
//   - Codecs (AV1, VP9, MP3)
//   - Emulators (DOSBox, retro consoles)
//   - Heavy math (physics simulations, linear algebra)
//   - Reusing C/C++/Rust libraries (FFI alternative)
//   - Sandboxed plugins in editors (Figma, Photoshop)

// Figma: rendering engine in Wasm
// Photoshop: web port of full desktop app
// Google Meet: video background blur

Cuándo usar JS

JS sigue siendo la elección correcta para UI, DOM, APIs del navegador y la mayoría de lógica de apps web — V8 está fuertemente optimizado. Recurre a Wasm cuando el profiling revele un hotspot que JS no pueda eliminar, o al portar una base de código nativa existente. Un enfoque híbrido (UI en JS + hotspots en Wasm) suele ser lo ideal.

webassembly
// JS is better when:
//   - DOM manipulation dominates
//   - Working with browser APIs (fetch, IndexedDB, WebRTC)
//   - Heavy string/JSON processing
//   - Small utilities and glue code
//   - Rapid prototyping (no compile step)
//   - Team lacks C/Rust expertise
//   - Module size matters more than runtime speed

// JS engines (V8, SpiderMonkey, JSC) are highly
// optimized. For most web apps, JS is fast enough
// AND simpler to ship and maintain.

// Hybrid: keep UI in JS, offload hotspots to Wasm.

Carga y coste de arranque

Wasm tiene un coste de arranque fijo (descarga + compilación + instanciación) que JS evita. Mitígalo con compilación en streaming, cacheando módulos compilados vía la Cache API y con carga perezosa del Wasm no crítico. Tras el calentamiento, las llamadas a funciones Wasm son tan rápidas como las de JS — el coste es inicial y lo reembolsa una ejecución más rápida.

webassembly
// Wasm has upfront costs JS doesn't:
//   1. Download the .wasm binary
//   2. Compile to machine code (~10-50 ms for small modules)
//   3. Instantiate (initialize memory, run start function)

// Mitigations:
//   - Cache compiled modules (WebAssembly.compileStreaming + Cache API)
//   - Stream compilation (instantiateStreaming)
//   - Lazy-load non-critical Wasm on demand
//   - Use Web Workers to compile off the main thread

// Streaming compile of a 1MB module:
//   ~30 ms download + ~10 ms compile (parallel)
// Cached: ~5 ms (re-instantiate from cached module)

Coste de interoperabilidad y sobrecarga de la frontera

Las llamadas JS↔Wasm son baratas pero no gratuitas (~10-100ns cada una, más con strings). Para eventos de alta frecuencia, agrupa en JS y llama a Wasm una vez con un buffer. Evita pasar objetos de JS por llamada — usa externref o copia bytes a memoria. La frontera es rápida para números, lenta para datos serializados.

webassembly
// Each JS<->Wasm call costs ~10-100 ns:
//   - Marshal arguments (i32/f64 fast; strings/objects slow)
//   - Stack frame setup
//   - Inlined trampoline in the engine

// Implications:
//   - Don't call Wasm 1M times for tiny work — batch!
//   - Don't pass large objects per-call — copy once, share memory
//   - For DOM events, keep handlers in JS, call Wasm with batched data

// Pseudocode: batched event handling
let pendingEvents = [];
button.addEventListener('click', e => {
  pendingEvents.push(...);
  if (pendingEvents.length >= 100) {
    exports.processBatch(ptr, pendingEvents.length);
    pendingEvents = [];
  }
});
18

Modelo de seguridad

Modelo de sandbox

La base de seguridad de Wasm es el sandbox: un módulo no puede acceder a la memoria, archivos, red ni dispositivos del host salvo que este le provea explícitamente funciones para ello vía imports. Esto hace seguro ejecutar código no confiable — solo puede hacer lo que sus imports permiten. Combinado con la seguridad de tipos, previene desbordamientos de buffer y RCE.

webassembly
// Wasm executes in a sandboxed virtual machine:
//   - No direct access to host memory (only its linear memory)
//   - No syscalls (must go through imported functions)
//   - No I/O unless the host provides it
//   - Control flow is structured (no arbitrary jumps)
//   - Type-checked at compile and run time

// All host access is EXPLICIT through imports.
// A module that didn't import "fs" cannot read files.

// Code:
//   (module
//     (import "env" "log" (func (param i32)))
//     ;; the ONLY host capability this module has is log()
//   )

Política de mismo origen y fetch

Wasm no escapa del modelo de seguridad del navegador — la política de mismo origen y CORS se aplican a los fetch de .wasm igual que a cualquier recurso. El Wasm cross-origin exige cabeceras CORS adecuadas y el tipo MIME application/wasm. Wasm tampoco puede saltarse CSP, cookies ni ningún otro mecanismo de seguridad del navegador.

webassembly
// Wasm modules obey the same-origin policy:
//   - fetch('https://other-origin/x.wasm') needs CORS headers
//   - The remote server must send:
//       Access-Control-Allow-Origin: *
//   - And the correct MIME: application/wasm

// Load cross-origin Wasm with streaming:
const { instance } = await WebAssembly.instantiateStreaming(
  fetch('https://cdn.example.com/lib.wasm', {
    mode: 'cors'
  }),
  imports
);

// Wasm cannot bypass CORS — it's subject to the
// browser's normal security model.

Aislamiento de memoria

La memoria de Wasm se comprueba con límites en tiempo de ejecución — cualquier acceso fuera de rango provoca un trap inmediato en lugar de corromper memoria. Los módulos no pueden leer la memoria de otros, el heap de JS ni direcciones arbitrarias del host. Los punteros a función (call_indirect) se comprueban por tipo, previniendo la falsificación de destinos de llamada. Esto elimina clases enteras de vulnerabilidades de C/C++.

webassembly
// Each Wasm instance has its OWN linear memory.
//   - Out-of-bounds access traps (RuntimeError)
//   - One module's memory cannot read another's
//   - JS writes via TypedArray views are bounds-checked

// Even shared memory (threads) requires explicit
// opt-in and is still bounded:
const mem = new WebAssembly.Memory({ initial: 1, maximum: 10 });

// Wasm code CANNOT:
//   - Read JS heap
//   - Read other instances' memory
//   - Forge function pointers (call_indirect type-checks)
//   - Read arbitrary host memory addresses

// All memory access is bounds-checked at runtime.

Seguridad basada en capacidades

Wasm sigue la seguridad basada en capacidades: el objeto de imports ES la capacidad del módulo. Eligiendo con cuidado qué importar, das al módulo el mínimo privilegio. Un plugin que solo importa log() no puede hacer nada más. Es la base de los sistemas de plugins seguros (Figma, Shopify functions, etc.).

webassembly
// Capability security: a module can ONLY do what
// the host explicitly grants via imports.

// Strict imports = minimal privilege
const imports = {
  env: {
    log: msg => console.log('[wasm]', msg)
    // NO file IO, NO network, NO timers
  }
};
WebAssembly.instantiateStreaming(fetch('plugin.wasm'), imports);

// The plugin can ONLY call log(). It cannot:
//   - Access the DOM
//   - Make network requests
//   - Read files
//   - Spawn workers
// unless you import those capabilities.

CSP y Trusted Types

Content Security Policy trata a Wasm como eval — por defecto, CSP lo bloquea. Añade 'wasm-unsafe-eval' a script-src para permitir Wasm manteniendo eval() bloqueado. Es más permisivo que unsafe-eval y recomendado para producción. La compatibilidad con Trusted Types exige envolver cualquier glue dinámico de JS en una policy.

webassembly
// Content Security Policy applies to Wasm:
//   - 'wasm-unsafe-eval' is required for instantiation
//   - Without it, CSP blocks WebAssembly.compile

// HTTP header:
//   Content-Security-Policy:
//     default-src 'self';
//     script-src 'self' 'wasm-unsafe-eval';

// Wasm output (e.g., Emscripten) often uses eval-like
// patterns for instantiation — CSP 'wasm-unsafe-eval'
// specifically allows Wasm while still blocking eval().

// Trusted Types: Wasm glue code must produce
// trusted scripts; use policy.createScript() for
// any dynamically generated JS that loads Wasm.
19

Cadena de herramientas

WABT (wat2wasm, wasm2wat)

WABT es el toolkit canónico para trabajar con los formatos de texto y binario de Wasm. wat2wasm/wasm2wat van de ida y vuelta; wasm-objdump inspecciona la estructura; wasm-interp ejecuta módulos en un intérprete de referencia. wasm-decompile produce una forma legible tipo C. Esencial para escribir a mano, depurar y enseñar.

webassembly
# WABT = WebAssembly Binary Toolkit
# Install:
#   macOS:  brew install wabt
#   Ubuntu: apt install wabt
#   Windows: scoop install wabt

# Tools included:
wat2wasm hello.wat -o hello.wasm       # text -> binary
wasm2wat hello.wasm -o hello.wat       # binary -> text
wasm-validate hello.wasm               # validate
wasm-objdump -x hello.wasm             # inspect structure
wasm-interp hello.wasm                 # interpret (run)
wasm-decompile hello.wasm -o hello.dly # decompile to C-like

# Online: https://webassembly.github.io/wabt/demo/

Emscripten SDK

Emscripten es el toolchain de Wasm más maduro — compila C/C++, Fortran y otros lenguajes LLVM. emcc/em++ envuelven a Clang; emcmake/emconfigure permiten construir proyectos CMake/Autotools existentes sin modificar. También aporta puertos de libc, SDL, OpenGL (vía WebGL) y pthreads por compatibilidad.

webassembly
# Emscripten: compile C/C++/LLVM languages to Wasm
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest
source ./emsdk_env.sh

# Key tools:
emcc        # C/C++ compiler (gcc/clang-like)
em++        # C++ compiler
emcmake     # wrapper for cmake
emconfigure # wrapper for ./configure
emranlib    # archive tool
emar        # archiver

# Common output:
emcc app.c -O3 -o app.js   # JS glue + .wasm
emcc app.c -o app.html     # runnable HTML demo

wasm-pack (Rust)

wasm-pack es la herramienta oficial de Rust→Wasm: compila, ejecuta wasm-bindgen, genera tipos de TypeScript y empaqueta para npm. --target elige el formato de módulo JS. wasm-pack test corre pruebas de Rust en navegadores reales vía webdriver. Usa wasm-pack-template para un andamiaje de proyecto listo.

webassembly
# wasm-pack: build, test, publish Rust Wasm packages
cargo install wasm-pack

# Build for various targets
wasm-pack build --target web       # modern browsers
wasm-pack build --target bundler   # webpack/vite
wasm-pack build --target nodejs    # Node.js

# Test in a headless browser
wasm-pack test --headless --chrome

# Publish to npm
wasm-pack publish

# Generate a template project
cargo generate --git https://github.com/rustwasm/wasm-pack-template

Binaryen (wasm-opt)

Binaryen es el toolkit de optimización que Emscripten y wasm-pack usan internamente. wasm-opt ejecuta pasadas a nivel Wasm (inlining, eliminación de código muerto, plegado de constantes) — ejecútalo siempre en los builds de producción. -O3 para velocidad, -Oz para tamaño mínimo. wasm-metadce elimina exportaciones sin usar entre módulos.

webassembly
# Binaryen: Wasm optimization toolkit
# Often installed via Emscripten or standalone:
npm install -g binaryen

# wasm-opt: optimize .wasm files
wasm-opt -O3 input.wasm -o output.wasm       # speed
wasm-opt -Os input.wasm -o output.wasm       # size
wasm-opt -Oz input.wasm -o output.wasm       # min size

# Other tools:
wasm-as input.wat -o output.wasm             # assemble
wasm-dis input.wasm -o output.wat            # disassemble
wasm-merge a.wasm b.wasm -o merged.wasm      # link
wasm-shell input.wat                         # interpreter
wasm-metadce input.wasm -o output.wasm       # aggressive dead-code

wasm-tools (Bytecode Alliance)

wasm-tools es un toolkit moderno basado en Rust del Bytecode Alliance. Parsea/imprime/valida, pero su función estrella es el soporte del component model (component new/embed/describe). Es más estricto y rápido que WABT para muchas operaciones y es la herramienta recomendada para trabajo con el component model.

webassembly
# wasm-tools: modern Rust-based Wasm toolkit
cargo install wasm-tools

# Subcommands:
wasm-tools parse input.wat -o output.wasm      # text -> binary
wasm-tools print input.wasm -o output.wat      # binary -> text
wasm-tools validate input.wasm                 # validate
wasm-tools component new input.wasm -o c.wasm  # wrap as component
wasm-tools strip input.wasm -o stripped.wasm   # remove debug info
wasm-tools objdump input.wasm                  # inspect
wasm-tools smith                                # generate random modules (fuzzing)

# Component model support is a key feature.
# Stronger WAT parsing than WABT in edge cases.

Runtimes (wasmtime, wasmer, WasmEdge)

Tres runtimes independientes principales: wasmtime (referencia del Bytecode Alliance, mejor soporte del component model), wasmer (varios backends incluido LLVM para máximo rendimiento, bindings de JS), WasmEdge (CNCF, optimizado para cloud-native e inferencia de IA). Cada uno implementa WASI, así que el mismo .wasm corre entre ellos. Elige según el ecosistema que te convenga.

webassembly
# wasmtime — Bytecode Alliance reference runtime
curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime app.wasm

# wasmer — cross-platform, multiple backends
curl https://get.wasmer.io -sSf | sh
wasmer run app.wasm

# WasmEdge — CNCF, optimized for cloud/edge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
wasmedge app.wasm

# Comparison:
#   wasmtime:  reference, WASI preview1+2, components
#   wasmer:   multiple backends (Cranelift, LLVM), JS API
#   WasmEdge:  AI/ML extensions, Kubernetes-friendly

// All three run WASI modules portably.
20

Componentes y buenas prácticas

Panorama de componentes Wasm

El Component Model es la evolución de Wasm: un formato de módulo que permite a los componentes comunicarse con tipos ricos (strings, records, listas) sin empaquetado manual a través de la memoria lineal. Los componentes se componen como librerías entre lenguajes (componente Rust + componente JS). Soportado por wasmtime, WasmEdge y el ecosistema del Bytecode Alliance.

webassembly
// Component Model: a higher-level module format
// that lets Wasm modules talk to each other and hosts
// using rich types (strings, records, variants),
// not just (i32, f64).

// Core Wasm module:  exports raw functions over memory.
// Component:         wraps a core module, exposes typed
//   interfaces described in WIT (Wasm Interface Type).

// Build flow:
//   1. Write WIT interface
//   2. Generate bindings for your language (Rust, C, JS)
//   3. Implement, compile to core .wasm
//   4. Wrap into a component with wasm-tools

// Tooling:
wasm-tools component new app.wasm -o app.wasm

// Run with wasmtime:
wasmtime app.wasm  # uses component interfaces

WIT (Wasm Interface Type)

WIT (Wasm Interface Type) es el IDL de los componentes — declara records, variants, enums, resources y funciones. wit-bindgen genera bindings específicos por lenguaje (Rust, C, JS, Python). La palabra clave 'world' agrupa los imports y exports que un componente provee/consume. Es la base de las librerías Wasm portables y agnósticas al lenguaje.

webassembly
// example.wit — describe a component's interface
package example:greeter;

interface api {
    // A record type
    record person {
        name: string,
        age: u32,
    }

    // A function taking/returning rich types
    greet: func(p: person) -> string;
}

world greeter-world {
    export api;
}

# Generate bindings:
#   Rust:     cargo component bindings
#   JS:       jco transpile
#   C/C++:    wit-bindgen c component.wit

# wit-bindgen is the binding generator
cargo install wit-bindgen-cli

Buena práctica: módulos pequeños y enfocados

Prefiere varios módulos Wasm pequeños y enfocados a un monolito. Los módulos menores se descargan más rápido, cachean mejor y pueden cargarse con pereza (carga el módulo de audio solo cuando haga falta). Comparte memoria entre módulos vía imports, o usa el component model para llamadas entre módulos con seguridad de tipos. Ejecuta wasm-opt -Oz en cada uno.

webassembly
// GOOD: One focused .wasm per concern
//   - renderer.wasm (drawing)
//   - audio.wasm (mixing)
//   - physics.wasm (simulation)
// Loaded lazily as needed.

// BAD: One giant monolithic .wasm
//   - app.wasm (1MB+, includes everything)

// Benefits of small modules:
//   - Faster initial load (only what's needed)
//   - Better caching (changed modules re-download)
//   - Easier parallel development
//   - Smaller attack surface per module

// Use wasm-opt -Oz to minimize each module.
// Share memory across modules via imports.

Buena práctica: manejo de errores

Los traps de Wasm (división por cero, memoria fuera de rango, unreachable) no pueden capturarse desde dentro de Wasm — abortan la función. Diseña las funciones exportadas para devolver códigos de error o tipos Result en lugar de trapear. Captura WebAssembly.RuntimeError del lado JS como último recurso. El component model soporta variantes de error tipadas de forma nativa.

webassembly
// Wasm traps are unrecoverable — handle errors gracefully.

// BAD: let divide crash
(func (export "div") (param i32 i32) (result i32)
  local.get 0  local.get 1  i32.div_s  ;; traps on 0
)

// GOOD: return a sentinel or error code
(func (export "div") (param i32 i32) (result i32)
  local.get 1
  i32.eqz
  if (result i32)
    i32.const -1   ;; error sentinel
  else
    local.get 0
    local.get 1
    i32.div_s
  end
)

// In Rust/AS: use Result<T, E> and export
// error variants via the component model.

Buena práctica: gestión de memoria

Trata la memoria de Wasm como en C: cada alloc necesita su free correspondiente. Exporta helpers alloc/free y envuelve el uso de buffers del lado JS en try/finally. Recrea las vistas TypedArray tras cualquier memory.grow (el ArrayBuffer se desacopla). Documenta la propiedad: ¿quién es responsable de liberar — el llamador o el llamado? Las fugas degradan el rendimiento con el tiempo.

webassembly
// Export alloc/free and use them consistently.
// C/C++ (Emscripten): _malloc / _free
// Rust:               wasm_bindgen's __alloc / __free
// AssemblyScript:     __new / __retain / __release

// JS wrapper for safe buffer passing:
function withBuffer(size, fn) {
  const ptr = exports.alloc(size);
  try {
    return fn(new Uint8Array(memory.buffer, ptr, size));
  } finally {
    exports.free(ptr, size);
  }
}

// NEVER leak:
//   - Re-create TypedArray views after memory.grow
//   - Free buffers passed in from JS
//   - For long-lived allocations, document ownership

Buena práctica: pruebas y CI

Prueba Wasm en entornos reales: wasm-pack test corre pruebas de Rust en navegadores headless; AssemblyScript y Emscripten tienen sus propios runners. Añade wasm-validate y comprobaciones de tamaño al CI. Usa -s ASSERTIONS=1 (Emscripten) y builds de depuración para atrapar problemas pronto. Lintea con wat2wasm y ejecuta siempre wasm-opt sobre los artefactos de release.

webassembly
# Test Wasm just like any other code.

# Rust: wasm-pack test runs in a real browser
wasm-pack test --headless --chrome --firefox

# AssemblyScript: use the built-in test framework
npm run test

# C/C++ (Emscripten): use emcc with -s ASSERTIONS=1
#   and write tests in C, run with node:
node tests.js

# Validate .wasm in CI:
wasm-validate module.wasm

# Check size budgets:
ls -la module.wasm  # e.g., must be < 200KB

# Lint WAT with wat2wasm (catches syntax errors)
# Run wasm-opt -O3 to ensure optimization is applied

# GitHub Actions example:
# - uses: actions-rs/toolchain@v1
# - run: cargo install wasm-pack
# - run: wasm-pack test --headless

Was this helpful?