@esmbly/transformer-wasm NPM

`@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`