@webassemblyjs/ast

What is @webassemblyjs/ast?

The @webassemblyjs/ast package is a toolchain for WebAssembly manipulation which allows you to parse, validate, and generate WebAssembly code. It provides an Abstract Syntax Tree (AST) representation of WebAssembly modules, enabling programmatic analysis and transformation of Wasm code.

What are @webassemblyjs/ast's main functionalities?

Parsing WebAssembly binary

This feature allows you to parse a WebAssembly binary into an AST. The code sample demonstrates how to use the wasm-parser submodule to decode a binary representation of a WebAssembly module.

"use strict";\nconst { decode } = require('@webassemblyjs/wasm-parser');\nconst binary = new Uint8Array([0x00, 0x61, 0x73, 0x6d, ...]);\nconst ast = decode(binary);\nconsole.log(ast);

Generating WebAssembly binary

This feature enables you to generate a WebAssembly binary from an AST. The code sample shows how to create an empty WebAssembly module using the ast submodule and then encode it into a binary with wasm-gen.

"use strict";\nconst { encode } = require('@webassemblyjs/wasm-gen');\nconst t = require('@webassemblyjs/ast');\nconst module = t.module([], []);\nconst binary = encode(module);\nconsole.log(new Uint8Array(binary));

Traversing and modifying the AST

This feature is for traversing the AST and applying modifications. The code sample illustrates how to traverse an existing AST and log each ModuleImport node encountered.

"use strict";\nconst { traverse } = require('@webassemblyjs/ast');\nconst ast = ...; // Assume this is an existing AST\ntraverse(ast, {\n  ModuleImport(path) {\n    console.log(path.node);\n  }\n});

Other packages similar to @webassemblyjs/ast

wast-parser

The wast-parser package is similar to @webassemblyjs/ast in that it can parse WebAssembly text format (WAT) into an AST. However, it focuses on the text format rather than the binary format and does not provide binary generation capabilities.

binaryen

Binaryen is a compiler and toolchain infrastructure library for WebAssembly, written in C++. It has bindings for JavaScript and provides similar functionalities such as parsing, optimization, and generation of WebAssembly code. Compared to @webassemblyjs/ast, Binaryen offers a broader range of optimization tools and is implemented in a different programming language.

wabt

WABT (The WebAssembly Binary Toolkit) is a suite of tools for WebAssembly, including a decoder, an interpreter, and a binary format validator. It is similar to @webassemblyjs/ast in that it allows manipulation of WebAssembly binaries but is a standalone toolkit rather than an npm package.

README

@webassemblyjs/ast

AST utils for webassemblyjs

Installation

yarn add @webassemblyjs/ast

Usage

Traverse

import { traverse } from "@webassemblyjs/ast";

traverse(ast, {
  Module(path) {
    console.log(path.node);
  }
});

Instruction signatures

import { signatures } from "@webassemblyjs/ast";

console.log(signatures);

Path methods

• findParent: NodeLocator
• replaceWith: Node => void
• remove: () => void
• insertBefore: Node => void
• insertAfter: Node => void
• stop: () => void

AST utils

• function module(id, fields, metadata)
• function moduleMetadata(sections, functionNames, localNames)
• function moduleNameMetadata(value)
• function functionNameMetadata(value, index)
• function localNameMetadata(value, localIndex, functionIndex)
• function binaryModule(id, blob)
• function quoteModule(id, string)
• function sectionMetadata(section, startOffset, size, vectorOfSize)
• function loopInstruction(label, resulttype, instr)
• function instruction(id, args, namedArgs)
• function objectInstruction(id, object, args, namedArgs)
• function ifInstruction(testLabel, test, result, consequent, alternate)
• function stringLiteral(value)
• function numberLiteralFromRaw(value, raw)
• function longNumberLiteral(value, raw)
• function floatLiteral(value, nan, inf, raw)
• function elem(table, offset, funcs)
• function indexInFuncSection(index)
• function valtypeLiteral(name)
• function typeInstruction(id, functype)
• function start(index)
• function globalType(valtype, mutability)
• function leadingComment(value)
• function blockComment(value)
• function data(memoryIndex, offset, init)
• function global(globalType, init, name)
• function table(elementType, limits, name, elements)
• function memory(limits, id)
• function funcImportDescr(id, signature)
• function moduleImport(module, name, descr)
• function moduleExportDescr(exportType, id)
• function moduleExport(name, descr)
• function limit(min, max)
• function signature(params, results)
• function program(body)
• function identifier(value, raw)
• function blockInstruction(label, instr, result)
• function callInstruction(index, instrArgs)
• function callIndirectInstruction(signature, intrs)
• function byteArray(values)
• function func(name, signature, body, isExternal, metadata)
• ConstantisModule
• ConstantisModuleMetadata
• ConstantisModuleNameMetadata
• ConstantisFunctionNameMetadata
• ConstantisLocalNameMetadata
• ConstantisBinaryModule
• ConstantisQuoteModule
• ConstantisSectionMetadata
• ConstantisLoopInstruction
• ConstantisInstruction
• ConstantisObjectInstruction
• ConstantisIfInstruction
• ConstantisStringLiteral
• ConstantisNumberLiteral
• ConstantisLongNumberLiteral
• ConstantisFloatLiteral
• ConstantisElem
• ConstantisIndexInFuncSection
• ConstantisValtypeLiteral
• ConstantisTypeInstruction
• ConstantisStart
• ConstantisGlobalType
• ConstantisLeadingComment
• ConstantisBlockComment
• ConstantisData
• ConstantisGlobal
• ConstantisTable
• ConstantisMemory
• ConstantisFuncImportDescr
• ConstantisModuleImport
• ConstantisModuleExportDescr
• ConstantisModuleExport
• ConstantisLimit
• ConstantisSignature
• ConstantisProgram
• ConstantisIdentifier
• ConstantisBlockInstruction
• ConstantisCallInstruction
• ConstantisCallIndirectInstruction
• ConstantisByteArray
• ConstantisFunc
• ConstantassertModule
• ConstantassertModuleMetadata
• ConstantassertModuleNameMetadata
• ConstantassertFunctionNameMetadata
• ConstantassertLocalNameMetadata
• ConstantassertBinaryModule
• ConstantassertQuoteModule
• ConstantassertSectionMetadata
• ConstantassertLoopInstruction
• ConstantassertInstruction
• ConstantassertObjectInstruction
• ConstantassertIfInstruction
• ConstantassertStringLiteral
• ConstantassertNumberLiteral
• ConstantassertLongNumberLiteral
• ConstantassertFloatLiteral
• ConstantassertElem
• ConstantassertIndexInFuncSection
• ConstantassertValtypeLiteral
• ConstantassertTypeInstruction
• ConstantassertStart
• ConstantassertGlobalType
• ConstantassertLeadingComment
• ConstantassertBlockComment
• ConstantassertData
• ConstantassertGlobal
• ConstantassertTable
• ConstantassertMemory
• ConstantassertFuncImportDescr
• ConstantassertModuleImport
• ConstantassertModuleExportDescr
• ConstantassertModuleExport
• ConstantassertLimit
• ConstantassertSignature
• ConstantassertProgram
• ConstantassertIdentifier
• ConstantassertBlockInstruction
• ConstantassertCallInstruction
• ConstantassertCallIndirectInstruction
• ConstantassertByteArray
• ConstantassertFunc