binaryen.js

binaryen.js is a port of Binaryen to the Web, allowing you to generate WebAssembly using a JavaScript API.

Usage

$> npm install binaryen

import binaryen from "binaryen";

// Create a module with a single function
var myModule = new binaryen.Module();

myModule.addFunction("add", binaryen.createType([ binaryen.i32, binaryen.i32 ]), binaryen.i32, [ binaryen.i32 ],
  myModule.block(null, [
    myModule.local.set(2,
      myModule.i32.add(
        myModule.local.get(0, binaryen.i32),
        myModule.local.get(1, binaryen.i32)
      )
    ),
    myModule.return(
      myModule.local.get(2, binaryen.i32)
    )
  ])
);
myModule.addFunctionExport("add", "add");

// Optimize the module using default passes and levels
myModule.optimize();

// Validate the module
if (!myModule.validate())
  throw new Error("validation error");

// Generate text format and binary
var textData = myModule.emitText();
var wasmData = myModule.emitBinary();

// Example usage with the WebAssembly API
var compiled = new WebAssembly.Module(wasmData);
var instance = new WebAssembly.Instance(compiled, {});
console.log(instance.exports.add(41, 1));

The buildbot also publishes nightly versions once a day if there have been changes. The latest nightly can be installed through

$> npm install binaryen@nightly

or you can use one of the previous versions instead if necessary.

Usage with a CDN

From GitHub via jsDelivr: https://cdn.jsdelivr.net/gh/AssemblyScript/binaryen.js@VERSION/index.js
From npm via jsDelivr: https://cdn.jsdelivr.net/npm/binaryen@VERSION/index.js
From npm via unpkg: https://unpkg.com/binaryen@VERSION/index.js

Replace VERSION with a specific version or omit it (not recommended in production) to use main/latest.

Command line

The package includes Node.js builds of Binaryen's command line tools: wasm-shell, wasm-opt, wasm-metadce, wasm2js, wasm-as, wasm-dis, wasm-ctor-eval, wasm-reduce and wasm-merge.

API

Please note that the Binaryen API is evolving fast and that definitions and documentation provided by the package tend to get out of sync despite our best efforts. It's a bot after all. If you rely on binaryen.js and spot an issue, please consider sending a PR our way by updating index.d.ts and README.md to reflect the current API.

Types
Module construction
Module manipulation
Module validation
Module optimization
Module creation
Expression construction
Expression manipulation
Relooper
Source maps
Debugging

Future features 🦄 might not be supported by all runtimes.

Types

none: Type The none type, e.g., void.
i32: Type 32-bit integer type.
i64: Type 64-bit integer type.
f32: Type 32-bit float type.
f64: Type 64-bit float (double) type.
v128: Type 128-bit vector type. 🦄
funcref: Type A function reference. 🦄
externref: Type An external (host) reference. 🦄
anyref: Type Any (top type) reference. 🦄
eqref: Type Equal reference. 🦄
i31ref: Type i31 reference. 🦄
structref: Type Structure reference. 🦄
stringref: Type String reference. 🦄
unreachable: Type Special type indicating unreachable code when obtaining information about an expression.
auto: Type Special type used in Module#block exclusively. Lets the API figure out a block's result type automatically.
createType(types: Type[]): Type Creates a multi-value type from an array of types.
expandType(type: Type): Type[] Expands a multi-value type to an array of types.

Module construction

new Module() Constructs a new module.
parseText(text: string): Module Creates a module from Binaryen's s-expression text format (not official stack-style text format).
readBinary(data: Uint8Array): Module Creates a module from binary data.

Module manipulation

Module#addFunction(name: string, params: Type, results: Type, vars: Type[], body: ExpressionRef): FunctionRef Adds a function. vars indicate additional locals, in the given order.
Module#getFunction(name: string): FunctionRef Gets a function, by name,
Module#removeFunction(name: string): void Removes a function, by name.
Module#getNumFunctions(): number Gets the number of functions within the module.
Module#getFunctionByIndex(index: number): FunctionRef Gets the function at the specified index.
Module#addFunctionImport(internalName: string, externalModuleName: string, externalBaseName: string, params: Type, results: Type): void Adds a function import.
Module#addTableImport(internalName: string, externalModuleName: string, externalBaseName: string): void Adds a table import. There's just one table for now, using name "0".
Module#addMemoryImport(internalName: string, externalModuleName: string, externalBaseName: string): void Adds a memory import. There's just one memory for now, using name "0".
Module#addGlobalImport(internalName: string, externalModuleName: string, externalBaseName: string, globalType: Type): void Adds a global variable import. Imported globals must be immutable.
Module#addFunctionExport(internalName: string, externalName: string): ExportRef Adds a function export.
Module#addTableExport(internalName: string, externalName: string): ExportRef Adds a table export. There's just one table for now, using name "0".
Module#addMemoryExport(internalName: string, externalName: string): ExportRef Adds a memory export. There's just one memory for now, using name "0".
Module#addGlobalExport(internalName: string, externalName: string): ExportRef Adds a global variable export. Exported globals must be immutable.
Module#getNumExports(): number Gets the number of exports witin the module.
Module#getExportByIndex(index: number): ExportRef Gets the export at the specified index.
Module#removeExport(externalName: string): void Removes an export, by external name.
Module#addGlobal(name: string, type: Type, mutable: number, value: ExpressionRef): GlobalRef Adds a global instance variable.
Module#getGlobal(name: string): GlobalRef Gets a global, by name,
Module#removeGlobal(name: string): void Removes a global, by name.
Module#setMemory(initial: number, maximum: number, exportName: string | null, segments: MemorySegment[], shared?: boolean): void Sets the memory. There's just one memory for now, using name "0". Providing exportName also creates a memory export.
- MemorySegment#offset: ExpressionRef
- MemorySegment#data: Uint8Array
- MemorySegment#passive: boolean
Module#getNumMemorySegments(): number Gets the number of memory segments within the module.
Module#getMemorySegmentInfo(name: string): MemorySegmentInfo Gets information about the memory segment at the specified index.

Binaryen.js

Install / Use

README