dcodeIO / WebAssembly-prototype

WebAssembly is a new, portable, size- and load-time-efficient format suitable for compilation to the web, designed in a collaborative afford under the umbrella of the W3C (see).

This package aims to provide tools for working with WebAssembly binaries, providing interested developers with an easy way to experiment with the technology from within JavaScript itself.

Contents

• Type definitions
  Relevant type and opcode definitions.

• Reflection structure
  Classes to represent the different sections of a WASM binary.

• Statement types
  Classes to represent the different statement and expression types.

• Statement and expression behaviors
  Classes describing the wire-format of any statement or expression in an easy to grasp way.

• Reader
  A streaming reader for disassembling WASM binaries into their respective reflection structure.

• AstReader
  A streaming reader for disassembling function bodies into their respective AST.

• Writer
  A streaming writer for assembling WASM binaries from their respective reflection structure.

• AstWriter
  A streaming writer for assembling function bodies from their respective AST.

Compatibility

For now this library aims to be compatible with what can be learned from the polyfill prototype, but is written in plain JavaScript and does not contain any compiled code.

While this package is built for the node.js platform, it should be trivial to also package it for browsers using browserify.

Please note that the WebAssembly design is still in flux and that binary encoding and AST semantics may change at any time.

Usage

Parsing a WASM binary including ASTs

var webassembly = require("webassembly"),
    Reader = webassembly.Reader;

var reader = new Reader();

reader.on("functionDefinition", function(definition, index) {
    ...
});

reader.on("end", function() {
    var myAssembly = reader.assembly;
    ...
});

// Write your WASM data to it
// - either manually:
reader.write(wasmBinaryData);
// - or pipe it:
require("fs").createReadStream("wasmBinaryFile.wasm").pipe(reader);

Just indexing a WASM binary, parsing ASTs on demand

var webassembly = require("webassembly"),
    Reader = webassembly.Reader,
    AstReader = webassembly.ast.Reader;

var reader = new Reader({
    skipAhead: true // Tells the AstReader not to generate statements, skipping ahead
});

reader.on("end", function() {
    reader.assembly.functionDeclarations.forEach(function(declaration) {
        var definition = declaration.definition;
        ...

        // And create an AstReader from the definition manually,
        // piping in the relevant portion of bytes:
        var astReader = new AstReader(definition);
        astReader.on("ast", function(ast) {
            ...
        });

        astReader.createReadStream("wasmBinaryFile.wasm", {
            start: definition.byteOffset,
            end: definition.byteOffset + definition.byteLength
        }).pipe(reader);
    });
});

...

Documentation

• Binary Format
• Opcodes
• Reader

Feel free to contribute!

License: Apache License, Version 2.0 - Logo derived from W3C HTML5 Logos (CC A 3.0)