wabt.js
=======

**wabt.js** is a port of [WABT](https://github.com/WebAssembly/wabt) to the Web, allowing you to manipulate WebAssembly modules using a JavaScript API.

Usage
-----

```
$> npm install wabt
```

```js
require("wabt")().then(wabt => {
  var wasm = ...; // a buffer holding the contents of a wasm file

  var myModule = wabt.readWasm(wasm, { readDebugNames: true });
  myModule.applyNames();

  var wast = myModule.toText({ foldExprs: false, inlineExport: false });

  console.log(wast);
});
```

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

```
$> npm install --save-exact wabt@nightly
```

or you can use one of the [previous versions](https://github.com/AssemblyScript/wabt.js/tags) instead if necessary. Note the `--save-exact` when using a nightly.

### Usage with a CDN

  * From GitHub via [jsDelivr](https://www.jsdelivr.com):
    `https://cdn.jsdelivr.net/gh/AssemblyScript/wabt.js@VERSION/index.js`
  * From npm via [jsDelivr](https://www.jsdelivr.com):
    `https://cdn.jsdelivr.net/npm/wabt@VERSION/index.js`
  * From npm via [UNPKG](https://unpkg.com):
    `https://unpkg.com/wabt@VERSION/index.js`

  Replace `VERSION` with a [specific version](https://github.com/AssemblyScript/wabt.js/releases) or omit it (not recommended in production) to use main/latest.


API
---

* **parseWat**(filename: `string`, buffer: `string | Uint8Array`, options?: `WasmFeatures`): `WasmModule`
  Parses a WebAssembly text format source to a module.
* **readWasm**(buffer: `Uint8Array`, options: `ReadWasmOptions & WasmFeatures`): `WasmModule`
  Reads a WebAssembly binary to a module.

* **WasmModule**
  A class representing a WebAssembly module.

  * **validate**(): `void`
    Validates the module. Throws if not valid.
  * **resolveNames**(): `void`
    Resolves names to indexes.
  * **generateNames**(): `void`
    Generates textual names for function types, globals, labels etc.
  * **applyNames**(): `void`
    Applies textual names. Throws on error.
  * **toText**(options: `ToTextOptions`): `string`
    Converts the module to wat text format.
  * **toBinary**(options: `ToBinaryOptions`): `ToBinaryResult`
    Converts the module to a wasm binary.
  * **destroy**(): `void`
    Disposes the module and frees its resources.

* **ReadWasmOptions**
  Options modifying the behavior of `readWasm`.

   * **readDebugNames**: `boolean`
     Reads textual names from the name section.

* **ToTextOptions**
  Options modifying the behavior of `WasmModule#toText`.

  * **foldExprs**: `boolean`
  * **inlineExport**: `boolean`

* **ToBinaryOptions**
  Options modifying the behavior of `WasmModule#toBinary`.

  * **log**: `boolean`
  * **canonicalize_lebs**: `boolean`
  * **relocatable**: `boolean`
  * **write_debug_names**: `boolean`

* **ToBinaryResult**
  Result object of `WasmModule#toBinary`.

  * **buffer**: `Uint8Array`
    The wasm binary buffer.
  * **log**: `string`
    Generated log output.

* **WasmFeatures**
  WebAssembly features to legalize. Finished features are enabled by default.

  * **exceptions**: `boolean`
    Exception handling ([proposal](https://github.com/WebAssembly/exception-handling)).
  * **mutable_globals**: `boolean`
    Import/Export mutable globals ([proposal](https://github.com/WebAssembly/mutable-global)).
  * **sat_float_to_int**: `boolean`
    Non-trapping Float-to-int Conversions ([proposal](https://github.com/WebAssembly/nontrapping-float-to-int-conversions)).
  * **sign_extension**: `boolean`
    Sign-extension operators ([proposal](https://github.com/WebAssembly/sign-extension-ops)).
  * **simd**: `boolean`
    128-bit packed SIMD ([proposal](https://github.com/WebAssembly/simd)).
  * **threads**: `boolean`
    Threading ([proposal](https://github.com/WebAssembly/threads)).
  * **function_references**: `boolean`
    Typed function references ([proposal](https://github.com/WebAssembly/function-references)).
  * **multi_value**: `boolean`
    Multi-value ([proposal](https://github.com/WebAssembly/multi-value)).
  * **tail_call**: `boolean`
    Tail Call ([proposal](https://github.com/WebAssembly/tail-call)).
  * **bulk_memory**: `boolean`
    Bulk Memory Operations and Conditional Segment Initialization ([proposal](https://github.com/WebAssembly/bulk-memory-operations)).
  * **reference_types**: `boolean`
    Reference Types ([proposal](https://github.com/WebAssembly/reference-types)).
  * **annotations**: `boolean`
    Custom Annotation Syntax for the Wasm Text Format ([proposal](https://github.com/WebAssembly/annotations)).
  * **code_metadata**: `boolean`
    Code metadata ([convention](https://github.com/WebAssembly/tool-conventions/blob/main/CodeMetadata.md)).
  * **gc**: `boolean`
    Garbage collection ([proposal](https://github.com/WebAssembly/gc)).
  * **memory64**: `boolean`
    64-bit memory ([proposal](https://github.com/WebAssembly/memory64)).
  * **extended_const**: `boolean`
    Extended constant expressions ([proposal](https://github.com/WebAssembly/extended-const)).
  * **relaxed_simd**: `boolean`
    Relaxed SIMD ([proposal](https://github.com/WebAssembly/relaxed-simd)).

CLI
---

Node.js ports of the following command line tools are included in the package as well:

* [wasm2c](https://webassembly.github.io/wabt/doc/wasm2c.1.html) converts a WebAssembly binary file to a C source and header.
* [wasm2wat](https://webassembly.github.io/wabt/doc/wasm2wat.1.html) translates from WebAssembly binary format to text format.
* [wat2wasm](https://webassembly.github.io/wabt/doc/wat2wasm.1.html) translates from WebAssembly text format to binary format.
* [wasm-decompile](https://webassembly.github.io/wabt/doc/wasm-decompile.1.html) decompiles a wasm binary into readable C-like syntax.
* [wasm-interp](https://webassembly.github.io/wabt/doc/wasm-interp.1.html) decodes and runs a WebAssembly binary file using a stack-based interpreter.
* [wasm-objdump](https://webassembly.github.io/wabt/doc/wasm-objdump.1.html) prints information about a wasm binary. Similiar to objdump.
* [wasm-stats](https://webassembly.github.io/wabt/doc/wasm-stats.1.html) shows stats for a WebAssembly module.
* [wasm-strip](https://webassembly.github.io/wabt/doc/wasm-strip.1.html) removes sections of a WebAssembly binary file.
* [wasm-validate](https://webassembly.github.io/wabt/doc/wasm-validate.1.html) validates a file in WebAssembly binary format.

The tools can also be run ad hoc (without explicitly installing the package), for example with:

```
$> npx -p wabt wasm2wat myModule.wasm -o myModule.wat
```
