@esmbly/transformer-wasm

Transform TypeScript programs to WebAssembly, Wat, Asm.js and AssemblyScript. The @esmbly/transformer-wasm can be used directly on TypeScript files, or chained together with other transformers that generates TypeScript output.

Installation

# Using Yarn:
yarn add @esmbly/transformer-wasm

# Or, using NPM:
npm install @esmbly/transformer-wasm --save

Getting Started

Check out Using the WebAssembly transformer for a step-by-step guide on how to get started with @esmbly/transformer-wasm and the command-line interface.

Try

Try it out in the Esmbly version of WebAssembly Studio!

Usage

The @esmbly/transformer-wasm transforms TypeScript programs to WebAssembly, Wat, Asm.js and AssemblyScript. In order to use it, make sure you have @esmbly/cli installed.

The following Esmbly configuration will transform the file add.js located in the src directory, first to TypeScript using @esmbly/transformer-jsdoc, and then to WebAssembly and Wat using @esmbly/transformer-wasm. Two output formats are specified, which will output add.wat and add.wasm to the dist directory.

// esmbly.config.js

const JSDoc = require('@esmbly/transformer-jsdoc');
const Wasm = require('@esmbly/transformer-wasm');

module.exports = {
  input: ['./src/add.js'],
  transformers: [
    JSDoc.createTransformer(),
    Wasm.createTransformer(),
  ],
  output: [
    {
      format: '.wat',
      outFile: path.join(__dirname, 'dist', 'add.wat'),
    },
    {
      format: '.wasm',
      outFile: path.join(__dirname, 'dist', 'add.wasm'),
    },
  ],
};

Configuration

The createTransformer() method accepts an optional configuration object (see the WasmTransformerOptions interface). Under the hood, @esmbly/transformer-wasm uses the AssemblyScript compiler to output WebAssembly, Wat and Asm.js. The following configuration options correspond to the specified asc flags.

Option	Description	Type	Asc flag
optimize (optional)	Optimizes the module.	string	--optimize
optimizeLevel (optional)	How much to focus on optimizing code. [0-3].	number	--optimizeLevel
shrinkLevel (optional)	How much to focus on shrinking code size. [0-2, s=1, z=2].	number	--shrinkLevel
validate (optional)	Validates the module using Binaryen. Exits if invalid.	boolean	-validate
use (optional)	Aliases a global object under another name, e.g., to switch the default 'Math' implementation used: ['Math=JSMath'].	string[]	--use
memory (optional)	See Memory options below	Object
customRules (optional)	An object containing any custom rules which should be applied (existing rules can be overridden). Check out the custom-rule example for further details.	CustomRules

Memory options

For further details about memory layout and management, have a look at the AssemblyScript Wiki.

{ 
  import: boolean;
  export: boolean;
  allocator: string;
}

Option	Description	Type
import (optional)	Imports the memory instance provided by the embedder. (asc flag: --importMemory)	boolean
export (optional)	Exports memory by injecting export { memory }; to the top of the TypeScript files before running asc.	boolean
allocator (optional)	Imports the specified allocator by injecting an import statement to the top of the TypeScript files before running asc. Ex: import "allocator/tlsf";	string

Examples

• Add (JSDoc): Transforming a simple JavaScript program with JSDoc comments to WebAssembly by chaining @esmbly/transformer-jsdoc and @esmbly/transformer-wasm.
• Add (Flow): Transforming a simple Flow program to WebAssembly by chaining @esmbly/transformer-flow and @esmbly/transformer-wasm.
• Add (V8): Transforming a simple JavaScript program that is covered by a test suite to WebAssembly by chaining @esmbly/transformer-v8 and @esmbly/transformer-wasm.
• Conway's Game of Life: Transforming Conway's Game of Life (ported from the AssemblyScript project to JSDoc) to WebAssembly by chaining @esmbly/transformer-jsdoc and @esmbly/transformer-wasm.
• Insertion Sort: Transforming an insertion sort algorithm to WebAssembly by chaining @esmbly/transformer-jsdoc and @esmbly/transformer-wasm.
• Browser Example: Using esmbly in the browser using Webpack. Uses @esmbly/transformer-flow and @esmbly/transformer-wasm.
• Lodash: Transforming one lodash method to WebAssembly.
• Pad: Transforming a string pad program to WebAssembly by chaining @esmbly/transformer-flow and @esmbly/transformer-wasm.
• Radians: Transforming a utility program for transforming between radians and degrees to WebAssembly by chaining @esmbly/transformer-v8 and @esmbly/transformer-wasm.
• Repeat: Transforming a utility program for repeating strings to WebAssembly by chaining @esmbly/transformer-v8 and @esmbly/transformer-wasm.

Contributing

All types of contributions are very much welcome. Check out our Contributing Guide for instructions on how to get started.