{ "version": "https://jsonfeed.org/version/1", "title": "WebAssembly from the Ground Up Blog", "home_page_url": "https://wasmgroundup.com/blog", "description": "WebAssembly from the Ground Up Blog", "items": [ { "id": "https://wasmgroundup.com/blog/wasm-vm-part-2", "content_html": "\n\n\n\n

In our last blog post, we implemented a WebAssembly interpreter that can do arithmetic and comparison operations on i32 values.

\n

In this post, we’re going to extend the interpreter: rather than only operating on literal values, we’ll add support for local and global variables. And just like before, we’re writing everything from scratch, in JavaScript — no libraries or frameworks.

\n

If that sounds like your cup of tea, keep reading.

\n

🛠️ Setup​

If you’d like to follow along by running the code yourself, then you should start by creating a file named wasm-vm-02.js. All the snippets we show will be added to that file. Let’s start with a few imports:

wasm-vm-02.js

import assert from 'node:assert';
import test from 'node:test';

We’ll also import a few definitions from the previous post:

wasm-vm-02.js

import {i32, instrImm, VM} from './wasm-vm-01.js';

If you don’t have that code in a file already, you can go to the end of that post and click “Copy up to here” under the last snippet (or copy it from StackBlitz) then paste it into a file called wasm-vm-01.js.

Okay, let’s get started.

\n

An important thing to know about WebAssembly is that inside a module, things aren’t referenced by name, but by index. Things of different types are grouped together in different index spaces, a fancy name for what is basically just an array.

\n

Local variables are no exception; they’re stored in the locals index space, which maps from an index to a value of one of the core Wasm types (i32, i64, f32, f64).

\n

To keep the code short and simple we’re going to extend the VM class and add a locals index space. It’s not really the “right way” to do it, but in the next post we’ll rewrite this class anyways, so let’s go with a simple solution:

\n
wasm-vm-02.js

class FlatFrame extends VM {
constructor(instructions, locals = []) {
super(instructions);
this.locals = locals;
}
}

\n

Now that we have a locals space, we need some instructions to work with it. Let’s define the first instruction: local.get, which takes the index as an immediate and pushes the variable’s current value onto the stack:

\n
wasm-vm-02.js

const local = {};
local.get = (index) =>
instrImm(0x20, 'local.get', index, (vm, index) => {
assertLocalIndexInRange(vm.locals, index);
const value = vm.locals[index];
vm.push(value);
});

\n

Since we don’t have an instruction to set local variables yet, let’s test it by creating a FlatFrame with a local variable initialized to 100:

\n
wasm-vm-02.js

test('local.get', () => {
const vm = new FlatFrame([local.get(0)], [i32(100)]);
vm.step();
assert.deepStrictEqual(vm.stack.items, [i32(100)]);
});

\n

In the instruction implementation above we check if the index is in bounds (i.e., it refers to an existing variable). Let’s extract that check into a separate function that can be reused for the other instructions:

\n
wasm-vm-02.js

function assertLocalIndexInRange(locals, index) {
if (index < 0 || index >= locals.length) {
throw new Error(`Invalid local index: ${index}`);
}
}

\n

Now we can implement the local.set instruction, which also takes the variable’s index as an immediate. But unlike local.get, it also requires a dynamic argument: the new value of the variable. It gets this value from the stack.

\n
wasm-vm-02.js

local.set = (index) =>
instrImm(0x21, 'local.set', index, (vm, index) => {
assertLocalIndexInRange(vm.locals, index);
const value = vm.pop();
vm.locals[index] = value;
});

\n

Let’s test it:

\n
wasm-vm-02.js

test('local.set', () => {
const vm = new FlatFrame([i32.const(42), local.set(0)], [i32(0)]);
vm.step();
vm.step();
assert.deepStrictEqual(vm.stack.items, []);
assert.strictEqual(vm.locals[0].value, 42);
});

\n

The local.set instruction pops the value from the stack, but sometimes you want to set a local variable and leave the original value in the stack too. For example, many languages (including JavaScript) support assignment expressions, which assign a value to a variable, but also produce a value:


let a = 0;
function plusOne(val) {
return val + 1;
}
plusOne(a = 6); // Returns 7
console.log(a); // Prints '6'

That’s one example of where the local.tee instruction comes in handy. We can easily implement it, by using peek() to read the top-of-stack value without popping it:

wasm-vm-02.js

local.tee = (index) =>
instrImm(0x22, 'local.tee', index, (vm, index) => {
assertLocalIndexInRange(vm.locals, index);
const value = vm.peek();
vm.locals[index] = value;
});

\n

Okay, let’s test it:

\n
wasm-vm-02.js

test('local.tee', () => {
const vm = new FlatFrame([i32.const(42), local.tee(0)], [i32(0)]);
vm.step();
vm.step();
assert.strictEqual(vm.locals[0].value, 42);
assert.deepStrictEqual(vm.stack.items, [i32(42)]);
});

\n

Now we have local variables, but local to what? Right now they are the only kinds of variables we have.

\n

The answer, of course, is that they’re local to a function — or, to be more specific, they’re local to a specific call stack frame. Hence the name of our FlatFrame class: we’re modeling a virtual machine with a single frame, rather than a stack of frames.

\n

In WebAssembly, like JavaScript, functions are grouped into modules. To make our locals truly local, we can put the FlatFrame inside a module instance. For now, we’ll still assume a single function and a single stack frame, stored in a currentFrame property.

\n

And then we can also add support for global variables, in a property named…you guessed it, globals:

\n
wasm-vm-02.js

class MonoInstance {
constructor(instructions, locals = [], globals = []) {
this.currentFrame = new FlatFrame(instructions, locals);
this.globals = globals;
}
// ...
}

\n

The MonoInstance constructor takes the same arguments as FlatFrame, plus an extra one for globals.

\n

To make all our previous instruction definitions still work and keep the new ones as simple as possible, let’s\n“wrap and forward” some of the FlatFrame methods in our new class:

\n
wasm-vm-02.js

class MonoInstance {
// ...
get locals() {
return this.currentFrame.locals;
}
get stack() {
return this.currentFrame.stack;
}
push(value) {
this.currentFrame.push(value);
}
pop() {
return this.currentFrame.pop();
}
peek() {
return this.currentFrame.peek();
}
popI32() {
return this.currentFrame.popI32();
}
popType(T) {
return this.currentFrame.popType(T);
}
step() {
const {currentFrame} = this;
const instruction = currentFrame.instructions[currentFrame.pc];
instruction.eval(this);
currentFrame.pc += 1;
}
// ...
}

\n

To make sure everything works, we can run the local.tee test from above on our new MonoInstance:

\n
wasm-vm-02.js

test('local.tee for MonoInstance', () => {
const vm = new MonoInstance([i32.const(42), local.tee(0)], [i32(0)]);
vm.step();
vm.step();
assert.strictEqual(vm.locals[0].value, 42);
assert.deepStrictEqual(vm.stack.items, [i32(42)]);
});

\n

If you compare the tests, you’ll see that the only thing that changed is what class we instantiate for the vm.

\n

With local instructions completed we can now move to the global instructions. Let’s start with global.get:

\n
wasm-vm-02.js

const global = {};
global.get = (index) =>
instrImm(0x23, 'global.get', index, (vm, index) => {
assertGlobalIndexInRange(vm.globals, index);
const value = vm.globals[index];
vm.push(value);
});

\n

You may notice that it’s almost identical to local.get. The only difference is what index space it uses.

\n

As before, we define a function to check that the index is valid:

\n
wasm-vm-02.js

function assertGlobalIndexInRange(globals, index) {
if (index < 0 || index >= globals.length) {
throw new Error(`Invalid global index: ${index}`);
}
}

\n

Okay — let’s test our new instruction:

\n
wasm-vm-02.js

test('global.get', () => {
const instance = new MonoInstance([global.get(0)], [], [i32(100)]);
instance.step();
assert.strictEqual(instance.peek().value, 100);
});

\n

Finally, we’ll define global.set:

\n
wasm-vm-02.js

global.set = (index) =>
instrImm(0x24, 'global.set', index, (vm, index) => {
assertGlobalIndexInRange(vm.globals, index);
const value = vm.pop();
vm.globals[index] = value;
});

\n

…and test it too:

\n
wasm-vm-02.js

test('global.set', () => {
const instance = new MonoInstance(
[i32.const(42), global.set(0)],
[],
[i32(0)],
);
instance.step();
instance.step();
assert.strictEqual(instance.globals[0].value, 42);
});

\n

And we are done! 🎉

\n
\n

Not bad — with a fairly small amount of code, we were able to extend our WebAssembly VM to support local and global variables. In the next post, we’ll extend it further, and add support for multiple functions.

\n

Let’s finish up by exporting everything we’ll need in the next post:

\n
wasm-vm-02.js

export * from './wasm-vm-01.js';
export {local, global};

\n
🏁 wasm-vm-02.js
Open in StackBlitz
\n
\n

If you enjoyed this post, you should check out WebAssembly from the Ground Up — an online book to learn Wasm by building a simple compiler in JavaScript.

If you’d like to be notified when we publish the next post, you can sign up for our mailing list, where we share periodic updates on the book and interesting WebAssembly tidbits.

", "url": "https://wasmgroundup.com/blog/wasm-vm-part-2", "title": "A WebAssembly interpreter (Part 2)", "summary": "Adding local and global variable support to our Wasm Interpreter", "date_modified": "2026-02-20T00:00:00.000Z", "tags": [ "code" ] }, { "id": "https://wasmgroundup.com/blog/wasm-vm-part-1", "content_html": "\n\n\n\n\n

In our last blog post, we showed you a WebAssembly compiler that fits in a tweet. In just 192 bytes of JavaScript, it takes arithmetic expression written in postfix notation — like 20 2 * 2 + — and produces a Wasm module with a single function which evaluates the expression.

\n

In this post, we’re going to look at WebAssembly from another angle: we’re going to write an interpreter for Wasm from scratch. So, rather than executing the Wasm module with Node.js, we’re going to examine the instructions and evaluate them ourselves.

\n

At the end of this post we will have a bytecode interpreter (or virtual machine) that can evaluate arithmetic and comparison expressions like 2 * 3 + 4 == 10:

\n

const vm = new VM([
i32.const(3),
i32.const(2),
i32.mul,
i32.const(4),
i32.add,
i32.const(10),
i32.eq,
]);

\n

Does this sound fun? If so, read on!

\n

The WebAssembly execution model​

If you’re not intimately familiar with WebAssembly and its execution model, a bit of background might be useful before we jump in.

At its heart, WebAssembly (or Wasm for short) is a low-level bytecode format. It’s mainly intended as a compilation target, allowing languages like C++, Go, and Rust to be executed in the browser at near-native speed.

Normally, to execute a Wasm module, a WebAssembly engine (like your browser) would translate the module’s bytecode to native machine code and execute that. But many engines include an interpreter — either in addition to a compiler, or instead of one (see wasm3).

Stack machines​

Like many other bytecode formats, WebAssembly is based on a stack machine model. This means that many instructions implicitly operate on a stack of values: popping their arguments, and pushing the result back to the stack.

Here’s a diagram showing the state of an interpreter, before and after it executes an i32.mul instruction:

Note that a fully-featured Wasm interpreter contains other state, but we won’t be dealing with any of that in this post.

\n

Alright, are you ready to start implementing the interpreter?

\n

If you’d like to follow along by running the code yourself, then you should start by creating a file named wasm-vm-01.js. All of the snippets we show will be added to that file. Let’s start with a few imports:

wasm-vm-01.js

import assert from 'node:assert';
import test from 'node:test';

\n

The first step is to decide how we’ll represent the instructions. Usually an interpreter would operate on a binary stream of data, and then parse (or decode) the data into a more structured form.

\n

In this post, we’ll skip the decoding and just work directly with the structured representation. Let’s start by defining a class to represent instructions:

\n
wasm-vm-01.js

class Instruction {
constructor(opcode, name, evalFn) {
this.opcode = opcode;
this.name = name;
this.evalFn = evalFn;
}
eval(vm) {
return this.evalFn(vm);
}
}

\n

And here’s a function to create instances in a compact way:

\n
wasm-vm-01.js

const instr = (opcode, name, evalFn) => new Instruction(opcode, name, evalFn);

\n

The Instruction fields are:

\n\n

Following the spirit of our book, let’s start with the minimum viable instruction — the one that does nothing, nop:

\n
wasm-vm-01.js

const nop = instr(0x01, 'nop', (_vm) => {});

\n

How do we test something that “does nothing”? We can evaluate it passing null as the vm argument to make sure it doesn’t use it:

\n
wasm-vm-01.js

test('nop does nothing', () => {
const vm = null;
nop.eval(vm);
});

\n

Other than doing nothing, WebAssembly deals mostly with numbers and operations on them. As we mentioned at earlier, these operations manipulate values on a stack.

\n

The next thing we’ll need is a way to push values to the stack. For that, we’ll need to support instructions that take a value as a parameter, which the spec refers to as an immediate argument (or just immediate, for short).

\n

Let’s define a new subtype of instruction that takes an immediate value:

\n
wasm-vm-01.js

class InstructionImm extends Instruction {
constructor(opcode, name, immediate, evalFn) {
super(opcode, name, evalFn);
this.immediate = immediate;
}
eval(vm) {
return this.evalFn(vm, this.immediate);
}
}

\n

And a function to create them:

\n
wasm-vm-01.js

const instrImm = (opcode, name, immediate, evalFn) =>
new InstructionImm(opcode, name, immediate, evalFn);

\n

Notice that for this type of instructions evalFn takes an extra argument, the immediate value.

\n

The last piece we need is a way to represent numbers. An interesting thing about WebAssembly is that it’s a typed assembly language. WebAssembly 1.0 has four primitive value types:

\n\n

We’ll start by defining the i32 type and add support for the rest later:

\n
wasm-vm-01.js

class I32 {
constructor(value) {
this.value = value;
}
}
const i32 = (value) => new I32(value);

\n

We are now ready to define our second instruction, i32.const, which takes an immediate (the value to be pushed to the stack).

\n
wasm-vm-01.js

i32.const = (value) =>
instrImm(0x41, 'i32.const', value, (vm, imm) => vm.push(i32(imm)));

\n

Since nop didn’t use the vm argument, we never defined a type for it. But i32.const pushes a value to the stack, so let’s define a Stack:

\n
wasm-vm-01.js

class Stack {
constructor() {
this.items = [];
}
push(value) {
this.items.push(value);
}
// ...
}

\n

Now we can test that our new instruction does the right thing:

\n
wasm-vm-01.js

test('i32.const pushes an I32 to the stack', () => {
const vm = new Stack();
const instr = i32.const(42);
instr.eval(vm);
assert.deepStrictEqual(vm.items, [i32(42)]);
});

\n

Notice that we pass an instance of Stack as the vm argument — it’s sufficient for now.

\n

With values in the stack it makes sense to want to pop them too. The drop instruction does that:

\n
wasm-vm-01.js

const drop = instr(0x1a, 'drop', (vm) => vm.pop());

\n

To complete the implementation, we need to add the pop method to Stack:

\n
wasm-vm-01.js

class Stack {
// ...
pop() {
return this.items.pop();
}
// ...
}

\n

Let’s test that we can push and pop values:

\n
wasm-vm-01.js

test('drop pops from the stack', () => {
const vm = new Stack();
run(vm, [i32.const(42), drop]);
assert.deepStrictEqual(vm.items, []);
});

\n

Here’s the definition of the run function to evaluate a list of instructions:

\n
wasm-vm-01.js

function run(vm, instructions) {
for (const instr of instructions) {
instr.eval(vm);
}
}

\n

Ok, the test should now pass!

\n

Pushing and popping values is a decent start, but what else can we do with them? We can add them together, with the i32.add instruction:

\n
wasm-vm-01.js

i32.add = instr(0x6a, 'i32.add', (vm) => {
const c2 = vm.popI32();
const c1 = vm.popI32();
const c = i32(c1.value + c2.value);
vm.push(c);
});

\n

To evaluate i32.add:

\n\n

This instruction uses a new method: popI32. Let’s extend Stack with methods to operate on the top value and check its type:

\n
wasm-vm-01.js

class Stack {
// ...
peek() {
return this.items.at(-1);
}
topIsOfType(Class) {
return this.peek() instanceof Class;
}
assertTopIsOfType(Class) {
if (!this.topIsOfType(Class)) {
throw new Error(
`Expected ${Class.name} on top of stack, got ${this.peek()}`,
);
}
}
popType(T) {
this.assertTopIsOfType(T);
return this.pop();
}
popI32() {
return this.popType(I32);
}
// ...
}

\n

Now we have everything we need to test i32.add:

\n
wasm-vm-01.js

test('i32.add pops two I32s and pushes their sum', () => {
const vm = new Stack();
run(vm, [i32.const(42), i32.const(23), i32.add]);
assert.deepStrictEqual(vm.items, [i32(65)]);
});

\n

The run function runs the instructions to completion, but it would be nice to step and inspect the intermediate states too.

\n

Let’s create a proper VM class with a stack, a list of instructions, and a program counter (pc) to keep track of the current instruction. We’ll add methods to manipulate the stack and step through instructions:

\n
wasm-vm-01.js

class VM {
constructor(instructions) {
this.stack = new Stack();
this.instructions = instructions;
this.pc = 0;
}
push(value) {
this.stack.push(value);
}
pop() {
return this.stack.pop();
}
peek() {
return this.stack.peek();
}
popI32() {
return this.stack.popI32();
}
popType(T) {
return this.stack.popType(T);
}
step() {
const instruction = this.instructions[this.pc];
instruction.eval(this);
this.pc += 1;
}
steps(count) {
for (let i = 0; i < count; i++) {
this.step();
}
}
}

\n

Notice that most of the methods delegate to the stack. An interesting one is the step method: it fetches the current instruction, evaluates it, and increments the program counter.

\n

Let’s add two numbers again, but this time, we’ll check the stack after each step:

\n
wasm-vm-01.js

test('VM executes two i32.const and an i32.add', () => {
const vm = new VM([i32.const(42), i32.const(23), i32.add]);
vm.step(); // Eval `i32.const 42`
assert.deepStrictEqual(vm.stack.items, [i32(42)]);
vm.step(); // Eval `i32.const 23`
assert.deepStrictEqual(vm.stack.items, [i32(42), i32(23)]);
vm.step(); // Eval `i32.add`
assert.deepStrictEqual(vm.stack.items, [i32(42 + 23)]);
});

\n

This test should pass.

\n

A natural next step is to implement the rest of the arithmetic operations that, like i32.add:

\n
    \n
  1. Take two values from the stack
    2. \n
  2. Perform an operation on them
    3. \n
  3. Push the result back.
    4. \n
\n

In the spec, these operations are collectively called t.binop, where t is the type — in our case, i32.

\n

Let’s create a function to define them:

\n
wasm-vm-01.js

function binop(opcode, name, fn) {
return instr(opcode, name, (vm) => {
// 2. Pop the value t.const c2 from the stack.
const c2 = vm.popI32();
// 3. Pop the value t.const c1 from the stack.
const c1 = vm.popI32();
// 4.1 Let c be a possible result of computing binop<t>(c1, c2).
const c = i32(fn(c1.value, c2.value));
// 4.2 Push the value t.const c to the stack.
vm.push(c);
});
}

\n

Let’s try it by defining i32.sub:

\n
wasm-vm-01.js

i32.sub = binop(0x6b, 'i32.sub', (c1, c2) => c1 - c2);

\n

Testing binops is as regular as defining them. Let’s create a function for testing binary operations:

\n
wasm-vm-01.js

function checkBinop(c1, c2, instruction, expected) {
const vm = new VM([i32.const(c1), i32.const(c2), instruction]);
vm.steps(3);
assert.deepStrictEqual(vm.stack.items, [i32(expected)]);
}

\n

And use it to test i32.sub:

\n
wasm-vm-01.js

test('i32.sub', () => {
checkBinop(42, 23, i32.sub, 42 - 23);
});

\n

Now let’s define i32.mul and i32.div_s, and a small test for each:

\n
wasm-vm-01.js

i32.mul = binop(0x6c, 'i32.mul', (c1, c2) => c1 * c2);
i32.div_s = binop(0x6d, 'i32.div_s', (c1, c2) => Math.trunc(c1 / c2));
test('i32.mul', () => {
checkBinop(42, 23, i32.mul, 42 * 23);
});
test('i32.div_s', () => {
checkBinop(42, 23, i32.div_s, Math.trunc(42 / 23));
checkBinop(2, -3, i32.div_s, Math.trunc(2 / -3));
});

\n

After arithmetic operations a good next step is to implement comparison operations, known in the spec as relops.

\n

A relop is like a binop in that it takes two values from the stack and pushes one back. The difference is that the value it pushes back is either i32(1) to represent true or i32(0) to represent false.

\n

Let’s create a function to define them:

\n
wasm-vm-01.js

function relop(opcode, name, fn) {
return binop(opcode, name, (c1, c2) => (fn(c1, c2) ? 1 : 0));
}

\n

We are reusing binop and wrapping the provided fn in a function that returns 1 if the call to fn(c1, c2) is truthy and 0 if not.

\n

Let’s define our first relop, i32.eq which checks if two i32s are equal:

\n
wasm-vm-01.js

i32.eq = relop(0x46, 'i32.eq', (c1, c2) => c1 === c2);

\n

And test it using checkBinop:

\n
wasm-vm-01.js

test('i32.eq', () => {
checkBinop(42, 23, i32.eq, 0);
checkBinop(23, 23, i32.eq, 1);
});

\n

We can now implement the remaining relops:

\n
wasm-vm-01.js

i32.ne = relop(0x47, 'i32.ne', (c1, c2) => c1 !== c2);
i32.lt_s = relop(0x48, 'i32.lt_s', (c1, c2) => c1 < c2);
i32.gt_s = relop(0x4a, 'i32.gt_s', (c1, c2) => c1 > c2);
i32.le_s = relop(0x4c, 'i32.le_s', (c1, c2) => c1 <= c2);
i32.ge_s = relop(0x4e, 'i32.ge_s', (c1, c2) => c1 >= c2);

\n

And that’s it for now! All the tests should be passing. We now have an interpreter that does arithmetic and comparison operations using a stack — let’s try it with a complex expression:

\n
wasm-vm-01.js

test('complex expression works', () => {
// 2 * 3 + 4 == 10;
const vm = new VM([
i32.const(3),
i32.const(2),
i32.mul,
i32.const(4),
i32.add,
i32.const(10),
i32.eq,
]);
vm.steps(3); // Eval `i32.const 3; i32.const 2; i32.mul`
assert.strictEqual(vm.stack.peek().value, 6);
vm.steps(2); // Eval `i32.const 4; i32.add`
assert.strictEqual(vm.stack.peek().value, 10);
vm.steps(2); // Eval `i32.const 10; i32.eq`
assert.deepStrictEqual(vm.stack.items, [i32(1)]);
});

🏁 wasm-vm-01.js
Open in StackBlitz
\n
\n

That’s a pretty good start! We’ve got the core of a simple interpreter for WebAssembly 1.0 instructions. In the next post, we’ll extend this interpreter, and add support for instructions that operate on local variables.

\n

Let’s finish things off by exporting all the things that we’ll use in the next post:

\n
wasm-vm-01.js

export {I32, drop, i32, instr, instrImm, nop, Stack, VM};

\n

Catch you next time!

\n
\nThanks to Job van der Zwan and Karl Weber for providing helpful feedback on this post.

\n

If you enjoyed this post, you should check out WebAssembly from the Ground Up — an online book to learn Wasm by building a simple compiler in JavaScript.

If you’d like to be notified when we publish the next post, you can sign up for our mailing list, where we share periodic updates on the book and interesting WebAssembly tidbits.

", "url": "https://wasmgroundup.com/blog/wasm-vm-part-1", "title": "A WebAssembly interpreter (Part 1)", "summary": "Implementing a Wasm Interpreter to explore its design and semantics", "date_modified": "2025-11-20T00:00:00.000Z", "tags": [ "code" ] }, { "id": "https://wasmgroundup.com/blog/wasm-compiler-in-a-tweet", "content_html": "\n\n\n\n\n

Introduction

\n

One of the initial explorations that started this book was how small and simple a compile-to-WebAssembly language implemented in JavaScript could be. Our first “WebAssembly compiler in a tweet” was 269 bytes; since then, we’ve managed to whittle it down to a measly 192 bytes.

\n

The final result is a compiler that takes an arithmetic expression — written in reverse polish notation — and compiles it down to a valid WebAssembly module. That module exports a single function which returns the result of the original arithmetic expression. Here it is:

\n

let c=(b,l)=>WebAssembly.instantiate(new Int8Array(
[,97,115,109,1,,,,1,5,1,96,,1,127,3,2,1,,7,4,1,,,,10,
l=(b=b.split` `.flatMap(t=>t>-1?[65,t]:107+'-*/'.indexOf(t)))
.length+4,1,l-2,,...b,11]))

\n

And here’s an example of how you can use it:

\n

(await c('11 11 1 - + 4 * 2 /')).instance.exports['']()

\n

But this is not just a clever trick — if you take the time to understand what this code does, you’ll learn a surprising amount about WebAssembly! In the rest of the post, we’ll explain how it all works by de-obfuscating the code one step at a time.

\n

You can play with the code in this post here: stackblitz.com/edit/rpn-to-wasm-js-compiler.

\n

Format

\n

The first thing we can do to make it more readable is to format it:

\n

let c1 = (b, l) =>
WebAssembly.instantiate(
new Int8Array([
, 97, 115, 109, 1, , , , 1, 5, 1, 96, , 1, 127, 3, 2, 1, , 7, 4, 1, , , , 10,
(l = (b = b.split` `.flatMap(
(t) => t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t)
)).length + 4),
1, l - 2, , ...b, 11
])
);

\n

While it’s still pretty unreadable, now we can at least identify different parts of the code.

\n

At a high level, what we’re doing is ‘parsing’ the expression in a very simple way, turning it into the appropriate Wasm bytecode,\nand then hand-crafting the bytes for a single-function module.

\n

In a more complex compiler you would probably use a library to generate the WebAssembly module and compile the expressions but our main metric\nhere is code size so we write the bytes directly in an array.

\n

Remove Assignment Expression

\n

The first trick to undo is the assignment expression.

\n

In JavaScript the assignment operator is an expression. This means that it generates a result after evaluating, as you can see in the following examples:

\n

let a, b;
console.log('a', a = 42);
a = b = 43;
console.log('b', b);

\n

The code above will output:

\n

a 42
b 43

\n

This is because a = 42 assigns 42 to a and the whole assignment expression evaluates to the value being assigned.

\n

In a = b = 43, we assign the result of evaluating b = 43 to a. This equivalent expression may be easier to understand: a = (b = 43).

\n

In our code, we use this trick to reuse variables and update their value in places where\nwe can also use the value being assigned. It also allows us to have our compiler in a single expression, avoiding the need for curly braces, semicolons and return statements.

\n

To undo it, we turn the body of our function into a block and do each assignment on its own line:

\n

let c2 = (b, l) => {
b = b.split` `.flatMap(
(t) => (t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t))
);
l = b.length + 4;
return WebAssembly.instantiate(
new Int8Array([
, 97, 115, 109, 1, , , , 1, 5, 1, 96, , 1, 127, 3, 2, 1, , 7, 4, 1, , , ,
10, l, 1, l - 2, , ...b, 11
]),
);
};

\n

Undo Variable Tricks

\n

Now the assignments are easier to identify but the meaning of variables and function\narguments are still hard to understand. Let’s fix that by undoing a couple of variable tricks.

\n

The first step is to stop using single letter variables, and to use more descriptive names instead. The next step is to stop reusing variables: for example, b initially holds the code to compile, but once we don’t need that any more we reuse it to hold the bytecode instructions.

\n

To undo this we are going to introduce a new instrs variable and rename b to code. We’ll also rename l to len. This variable contains a value that is close to the number of bytecodes.

\n

By declaring l in the body we can remove it from the function argument’s list. We did this\nas a trick to avoid the need to declare it with let or const, saving some bytes and the need for a function body.

\n

The trick works by adding unused arguments at the end of the function argument list and using them as local variables. Our compiler function expects a single argument with the code; l is there for us to use since we don’t expect the caller to provide any value for it.

\n

Here’s the code without this trick:

\n

let c3 = (code) => {
const instrs = code.split` `.flatMap(
(t) => (t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t))
);
const len = instrs.length + 4;
return WebAssembly.instantiate(
new Int8Array([
, 97, 115, 109, 1, , , , 1, 5, 1, 96, , 1, 127, 3, 2, 1, , 7, 4, 1, , , ,
10, len, 1, len - 2, , ...instrs, 11
]),
);
};

\n

Add Missing Zeros

\n

If you look at the array in our code, you may notice that there are many commas followed by another comma instead of a value. This syntax defines “sparse arrays”. Here’s an example:

\n

const a1 = [,,];
console.log(a1.length); // Output: 2
console.log(a1); // Output: [ <2 empty items> ]

\n

Which is equivalent to:

\n

const a2 = new Array(2);
console.log(a2.length); // Output: 2
console.log(a2); // Output: [ <2 empty items> ]

\n

We use this syntactic trick to save one byte each time we need a 0 to appear in the array. This works because Typed Arrays coerce all array items to numbers, and an “empty item” will be converted to 0:

\n

new Int8Array([0, null, undefined,,0])

\n

which produces:

\n

Int8Array(5) [ 0, 0, 0, 0, 0 ]

\n

Let’s undo this trick by adding all the zeroes back:

\n

let c4 = (code) => {
const instrs = code.split` `.flatMap(
(t) => (t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t))
);
const len = instrs.length + 4;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, len, 1, len - 2, 0, ...instrs, 11
]),
);
};

\n

Remove Extra 4 bytes on Length Definition

\n

In our code, we have a variable len that contains a number that is close to the number\nof bytecodes in the compiled expression, but not exactly the same:

\n

const len = instrs.length + 4;

\n

In the WebAssembly module we need to use the number of bytes in the function body (the expression to evaluate) in two places:

\n\n

Since there’s only one function in the code section both values are similar:

\n\n

To avoid writing b.length twice we assign to l the value of b.length + 4 in the place where we need the code section byte count\nand then calculate l - 2 (b.length + 2) where we need the function body byte count.

\n

[
...
l=(b=b.split` `.flatMap(t=>t>-1?[65,t]:107+'-*/'.indexOf(t))).length+4,1,l-2
...
]

\n

This is all a trick to avoid having to write b.length twice.

\n

let’s assign the length to len and calculate the right value in each place:

\n

let c5 = (code) => {
const instrs = code.split` `.flatMap(
(t) => (t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t))
);
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

Remove String Template Literal Instead of Function Call

\n

The next trick to undo is code.split` `. In this case, we use the Tagged Template feature of String Template Literals.

\n

Let’s see how it works by creating a simple tagged template that turns the string to uppercase:

\n

function upper(s) {
return s[0].toUpperCase();
}

\n

And use it:

\n

upper`Hello, World!`
> \"HELLO, WORLD!\"

\n

As you can see, the first argument to the tagged template function is an array. Luckily for us, the first argument of String.prototype.split is handled in the following way:

\n
\n

All values that are not undefined or objects with a [Symbol.split]() method are coerced to strings.

\n
\n

And coercing an array with one string in it is the same as the string itself:

\n

[\"hello\"].toString()
> \"hello\"

\n

[\" \"].toString()
> \" \"

\n

Since the function we want to call takes a single string argument, we can use it as a tagged template and save the parentheses in the function call.

\n

Let’s write it as a function call instead:

\n

let c6 = (code) => {
const instrs = code.split(' ').flatMap(
(t) => (t > -1 ? [65, t] : 107 + \"-*/\".indexOf(t))
);
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

Remove the Ternary Operator

\n

Next, let’s undo the Ternary Operator and turn it into an if statement.

\n

The ternary operator has expressions on each branch saving us the return statements. Here’s what the code looks like when we use an if statement instead:

\n

let c7 = (code) => {
const instrs = code.split(\" \").flatMap((t) => {
if (t > -1) {
return [65, t];
} else {
return 107 + \"-*/\".indexOf(t);
}
});
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

Remove Number Check With Coercion

\n

The next trick to undo is the one present twice in the following code:

\n

if (t > -1) {
return [65, t];
}

\n

First we use coercion in t > -1 to check if the token t is a string representing a\npositive number. Then we use coercion again in [65, t] to let JavaScript turn t into a Number in the Int8Array:

\n

new Int8Array([65, '42'])

\n

The code above evaluates to:

\n

Int8Array(2) [ 65, 42 ]

\n

Let’s write the parsing and checking explicitly:

\n

let c8 = (code) => {
const instrs = code.split(\" \").flatMap((t) => {
const num = parseInt(t, 10);
if (Number.isFinite(num)) {
return [65, num];
} else {
return 107 + \"-*/\".indexOf(t);
}
});
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

The semantics of our compiler change a little bit here. The original version will only accept\npositive integers as input; if you want a negative number you have to subtract from zero: 0 - 1 to get -1. The new version allows negative numbers since it checks with Number.isFinite(num) instead of t > -1.

\n

Remove indexOf -1 Trick

\n

The next trick is in the else branch:

\n

return 107 + \"-*/\".indexOf(t);

\n

Our calculator compiler only accepts four arithmetic operations: +, -, *, and /. But\nin the code above you can only see three: -*/ and a magical number: 107. Here’s how it works — these are the bytecode numbers for arithmetic operations in WebAssembly:

\n\n

We only enter this branch if the token t is not a number, which means it can only be\none of the arithmetic operators above. So, given a single character which is one of those four operators, we want to produce the appropriate opcode.

\n

We could have written 106 + \"+-*/\".indexOf(t). That is, we find the symbol’s index in the string:

\n\n

…and add 106 to it to get the bytecode number. But when t is not in the string, \"+-*/\" indexOf returns -1. We can use that to our advantage, and treat -1 to mean “plus or any other token”:

\n\n

And that’s why we add 107 instead of 106. Let’s undo the -1 trick:

\n

let c9 = (code) => {
const instrs = code.split(\" \").flatMap((t) => {
const num = parseInt(t, 10);
if (Number.isFinite(num)) {
return [65, num];
} else {
return 106 + \"+-*/\".indexOf(t);
}
});
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

Here again the semantics change a little bit. Before, if the token t wasn’t found, the expression would evaluate to 107 + -1 which would map to an addition. Now it will evaluate to 106 + -1 which will map to bytecode 105 which is the popcnt instruction.

\n

But don’t worry, we’ll fix it in the next step.

\n

Remove indexOf Trick

\n

After explaining how the indexOf trick works and removing the -1 part, let’s\ngo ahead and remove the trick completely. To do it we are going to create an object that maps from an arithmetic operation token to its bytecode:

\n

const OP_TO_BYTECODE = {
\"+\": 106,
\"-\": 107,
\"*\": 108,
\"/\": 109,
};
let c10 = (code) => {
const instrs = code.split(\" \").flatMap((t) => {
const num = parseInt(t, 10);
if (Number.isFinite(num)) {
return [65, num];
} else {
return OP_TO_BYTECODE[t] ?? 106;
}
});
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 4, 1, 0, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

To keep the initial semantics, if the token is not a valid operation we return the bytecode for +: in OP_TO_BYTECODE[t] ?? 106.

\n

Remove the Empty Export Name

\n

From the usage example at the beginning of the post, you may have noticed that the exported\nfunction’s name is the empty string:

\n

(await c('11 11 1 - + 4 * 2 /')).instance.exports['']()

\n

We did this to save us the bytes needed to specify the export name,\nbut also to save an extra byte/character in the code because with the length of the export name being 0\nwe can use the sparse array syntax to leave an empty spot in the WebAssembly module array.

\n

To revert this trick we are going to name the exported function as a, which in UTF-8 is the byte 97:

\n

> new TextEncoder().encode('a')[0]
97

\n

const OP_TO_BYTECODE = {
\"+\": 106,
\"-\": 107,
\"*\": 108,
\"/\": 109,
};
let c11 = (code) => {
const instrs = code.split(\" \").flatMap((t) => {
const num = parseInt(t, 10);
if (Number.isFinite(num)) {
return [65, num];
} else {
return OP_TO_BYTECODE[t] ?? 106;
}
});
const len = instrs.length;
return WebAssembly.instantiate(
new Int8Array([
0, 97, 115, 109, 1, 0, 0, 0, 1, 5, 1, 96, 0, 1, 127, 3, 2, 1, 0, 7, 5, 1, 1, 97, 0, 0,
10, 4 + len, 1, 2 + len, 0, ...instrs, 11
]),
);
};

\n

We can now call it with a nicer name:

\n

(await c11('11 11 1 - + 4 * 2 /')).instance.exports.a()

\n

Implicit Design Decisions

\n

Our initial implementation only supported positive numbers, but that’s not the only number restriction in our compiler.

\n

To keep WebAssembly modules as small as possible, numbers are encoded using a variable-length encoding algorithm called LEB128. You can tell we are not implementing the whole algorithm by looking at the part of the code that encodes numbers: [65,t]. We’re assuming the number being encoded fits in 7 bits, the shortest possible LEB128 representation.

\n

Let’s try the limits of our implementation:

\n

(await c('63')).instance.exports['']();
> 63

\n

(await c('64')).instance.exports['']();
> -64

\n

This means the only numbers that will be parsed correctly are from 0 to 63.

\n

(await c('127')).instance.exports['']();
> -1

\n

(await c('128')).instance.exports['']();

\n

Fails with:

\n
\n

Uncaught CompileError: WebAssembly.instantiate(): Compiling function #0 failed: function body must end with “end” opcode @+33

\n
\n

In the last one we went over the 7 bits and the module was rejected during validation.

\n

Explaining and implementing LEB128 takes a lot of text and code. If you want to read more\nabout it we have a whole deep dive on LEB128 in our book.

\n

A Trick that Almost Worked

\n

During the code golfing phase I had a literal shower thought but sadly it didn’t work.

\n

The idea was to simplify 106 + \"+-*/\".indexOf(t) by using the UTF-8 character code plus an offset like this: 63 + t.charCodeAt() and saving 3 bytes in the process. The reason it didn’t work is that the characters +-*/ don’t appear in the same order in UTF-8 and WebAssembly bytecode.

\n

Explaining the Numbers in the Array

\n

The last part to expand/explain is the array of numbers used to build the WebAssembly module.

\n

It takes a big part of a specification to explain every byte in the array, but here’s a commented version that should give you a high level idea of what each part does:

\n

[
// Wasm module magic number '\\0asm'
[0, 97, 115, 109],
// Wasm version 1.0
[1, 0, 0, 0],
// ----- type section -----
1, // Section identifier
5, // Section size in bytes
1, // Number of entries that follow
// type section - entry 0
96, // Type `function`
0, // Number of parameters
1, // Number of return values
127, // return type i32
// ----- function section -----
3, // Section identifier
2, // Section size in bytes
1, // Number of entries that follow
// function section - entry 0
0, // Index of the type section entry
// ----- export section -----
7, // Section identifier
5, // Section size in bytes
1, // Number of entries that follow
// export section - entry 0
1, // Name size in bytes
97, // String as utf-8 bytes for 'a'
0, // Export type `function`
0, // Function Index
// ----- code section -----
10, // Section identifier
4 + len, // Section size in bytes
1, // Number of entries that follow
// code section - entry 0
2 + len, // Entry size in bytes
0, // Number of local variables
...instrs,
11, // `end` instruction
]

\n

Conclusion

\n

There you go! We’ve turned a rather opaque 192-byte snippet into something that’s almost readable. And in the process, you hopefully learned a little bit about WebAssembly.

\n

If we dropped the size restrictions, there are lots of things we might want to improve in this compiler: handle numbers greater than 127, add nicer syntax, add support for conditionals, loops, etc. If you’re interested in what that might look like, I encourage you to check out our book WebAssembly from the Ground Up. You’ll learn the ins and outs of WebAssembly by writing a real compiler for a simple programming language. It’s a lot of fun!

\n

Special thanks to lexi for contributing some of the tricks used above.

", "url": "https://wasmgroundup.com/blog/wasm-compiler-in-a-tweet", "title": "A WebAssembly compiler that fits in a tweet", "summary": "Starting with a 192-byte one-liner that implements a Reverse Polish Notation arithmetic compiler, we'll work backward to transform it into readable JavaScript by removing one code golf trick at a time", "date_modified": "2025-01-24T00:00:00.000Z", "tags": [ "code" ] } ] }