@webassemblyjs/wasm-edit

What is @webassemblyjs/wasm-edit?

The @webassemblyjs/wasm-edit package is a toolchain for WebAssembly that allows you to manipulate WASM binaries. It provides functionalities to parse, edit, and generate WASM binaries, making it useful for tasks such as optimizing, instrumenting, or simply understanding the structure of a WebAssembly module.

What are @webassemblyjs/wasm-edit's main functionalities?

Parsing WebAssembly binaries

This feature allows you to parse a WebAssembly binary and turn it into an Abstract Syntax Tree (AST) that can be manipulated or analyzed.

const { decode } = require('@webassemblyjs/wasm-parser');
const { readFileSync } = require('fs');

const wasmBuffer = readFileSync('module.wasm');
const ast = decode(wasmBuffer);

console.log(ast);

Modifying the AST

After parsing a WASM binary into an AST, you can traverse and modify the AST. This example shows how to change the module imports.

const { traverse } = require('@webassemblyjs/ast');

traverse(ast, {
  ModuleImport(path) {
    // Modify the AST by changing module imports
    path.node.module = 'new_module';
  }
});

Generating WebAssembly binaries

Once you have an AST—either from parsing a binary or constructing it manually—you can generate a new WebAssembly binary.

const { encode } = require('@webassemblyjs/wasm-gen');

const newWasmBuffer = encode(ast);

writeFileSync('modified.wasm', newWasmBuffer);

Other packages similar to @webassemblyjs/wasm-edit

wabt

The 'wabt' package is a set of tools built around the WebAssembly Binary Toolkit. It includes functionality to convert between the binary format and a text format, validate binaries, and more. It is similar to @webassemblyjs/wasm-edit but is a more comprehensive toolkit that includes a wider range of utilities.

binaryen

Binaryen is a compiler and toolchain infrastructure library for WebAssembly, written in C++. It provides similar features for manipulating WASM binaries, including optimization and code generation. It is known for its optimization capabilities and is used by Emscripten. Compared to @webassemblyjs/wasm-edit, Binaryen offers a lower-level API and is not a JavaScript-native solution.

wasm-opt

wasm-opt is a tool that comes with Binaryen and is designed to optimize WebAssembly binaries. It can be used to improve the performance and reduce the size of WASM files. While @webassemblyjs/wasm-edit can be used for similar purposes, wasm-opt is specifically focused on optimization and is part of the Binaryen suite.

README

@webassemblyjs/wasm-edit

Rewrite a WASM binary

Replace in-place an AST node in the binary.

Installation

yarn add @webassemblyjs/wasm-edit

Usage

Update:

import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  ModuleImport({ node }) {
    node.module = "foo";
    node.name = "bar";
  }
};

const newBinary = edit(binary, visitors);

Replace:

import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  Instr(path) {
    const newNode = t.callInstruction(t.indexLiteral(0));
    path.replaceWith(newNode);
  }
};

const newBinary = edit(binary, visitors);

Remove:

import { edit } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const visitors = {
  ModuleExport({ node }) {
    path.remove()
  }
};

const newBinary = edit(binary, visitors);

Insert:

import { add } from "@webassemblyjs/wasm-edit";

const binary = [/*...*/];

const newBinary = add(actualBinary, [
  t.moduleImport("env", "mem", t.memory(t.limit(1)))
]);

Providing the AST

Providing an AST allows you to handle the decoding yourself, here is the API:

addWithAST(Program, ArrayBuffer, Array<Node>): ArrayBuffer;
editWithAST(Program, ArrayBuffer, visitors): ArrayBuffer;

Note that the AST will be updated in-place.