/WebAssembly-prototype

[OUTDATED] JavaScript tools for working with WebAssembly (WASM) binaries.

Primary LanguageJavaScriptApache License 2.0Apache-2.0

WebAssembly

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.

Build Status

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

Feel free to contribute!

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