https://github.com/d3lm/js-wasm-tools

Low level tooling for WebAssembly in JavaScript using wasm-tools
https://github.com/d3lm/js-wasm-tools

Last synced: 18 days ago
JSON representation

Low level tooling for WebAssembly in JavaScript using wasm-tools

• Host: GitHub
• URL: https://github.com/d3lm/js-wasm-tools
• Owner: d3lm
• License: mit
• Created: 2022-11-24T20:14:40.000Z (almost 2 years ago)
• Default Branch: master
• Last Pushed: 2024-01-26T20:04:44.000Z (10 months ago)
• Last Synced: 2024-10-12T08:22:51.754Z (about 1 month ago)
• Language: Rust
• Homepage:
• Size: 31.3 KB
• Stars: 69
• Watchers: 1
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# js-wasm-tools

`js-wasm-tools` compiles some of the API of [wasm-tools](https://github.com/bytecodealliance/wasm-tools) to JavaScript and WebAssembly via [`wasm-bindgen`](https://github.com/rustwasm/wasm-bindgen). This offers low level tooling for WebAssembly in JavaScript, such as parsing WAT (WebAssembly Text Format) into bytes, translating the WebAssembly binary format to text, and more.

## Install

```sh

npm install js-wasm-tools

```

## Playground

You can try it out live on [StackBlitz.com](https://stackblitz.com/edit/js-wasm-tools?file=index.js).

## Usage

Using [Vite](https://vitejs.dev/):

```js

import initWasmTools, * as wasmTools from 'js-wasm-tools';

import WASM_TOOLS_WASM_URL from 'js-wasm-tools/wasm_tools_js_bg.wasm?url';

await initWasmTools(WASM_TOOLS_WASM_URL);

const source = '(module)';

const binary = wasmTools.parseWat(source);

```

With Node.js:

```js

import initWasmTools, * as wasmTools from 'js-wasm-tools';

import fs from 'node:fs';

import path from 'node:path';

import * as url from 'node:url';

const __dirname = url.fileURLToPath(new URL('.', import.meta.url));

const bytes = fs.readFileSync(path.join(__dirname, 'node_modules/js-wasm-tools/dist/js_wasm_tools_bg.wasm'));

await initWasmTools(bytes);

const source = '(module)';

const binary = wasmTools.parseWat(source);

console.log(binary);

```

## API

### parseWat(source: string): Uint8Array

Parses a string as the WebAssembly Text format, returning the WebAssembly binary format.

### parseBytes(bytes: Uint8Array): Uint8Array

Parses bytes as either the WebAssembly Text format, or a binary WebAssembly module.

This function will attempt to interpret the given bytes as one of two options:

- A utf-8 string which is a \*.wat file to be parsed

- A binary WebAssembly file starting with `b"\0asm"`

```js

const encoder = new TextEncoder();

const bytes = wasmTools.parseWat(encoder.encode('(module)'));

expect(bytes).toEqual([0, 97, 115, 109, 1, 0, 0, 0]);

```

```js

const bytes = wasmTools.parseWat([0, 97, 115, 109, 1, 0, 0, 0]);

expect(bytes).toEqual([0, 97, 115, 109, 1, 0, 0, 0]);

```

### printBytes(bytes: Uint8Array): string

Prints a Wasm binary blob into a string which is its textual representation.

```js

const wat = wasmTools.printBytes(new Uint8Array([0, 97, 115, 109, 1, 0, 0, 0]));

expect(wat).toEqual('(module)');

```

### desugarWat(source: string): { wat: string, bytes: Uint8Array }

Parses a string as the WebAssembly Text format, and desugars the module, e.g. unfolding expressions.

```js

const { wat, bytes } = wasmTools.desugarWat(`

  (module

    (func $foo

      (call $bar (i32.const 1) (i32.const 2))

    )

    (func $bar (param i32 i32))

  )

`);

expect(wat).toEqual(`

  (module

    (type (;0;) (func))

    (type (;1;) (func (param i32 i32)))

    (func $foo (;0;) (type 0)

      i32.const 1

      i32.const 2

      call $bar

    )

    (func $bar (;1;) (type 1) (param i32 i32))

  )

`);

```

### validate(bytes: Uint8Array): Types

Test whether the given buffer contains a valid WebAssembly module or component, analogous to `WebAssembly.validate` in the JS API.

Upon success returns the type information for the top-level module or component.

```js

const encoder = new TextEncoder();

const types = wasmTools.validate(

  encoder.encode(`

    (module

      (func $foo (result f32)

        f32.const 1

      )

      (func $bar (param i32 i32))

    )

  `)

);

expect(types).toEqual({

  types: [

    {

      type: 'Func',

      params: [],

      results: ['f32'],

    },

    {

      type: 'Func',

      params: ['i32', 'i32'],

      results: [],

    },

  ],

  functions: [

    {

      params: [],

      results: ['f32'],

    },

    {

      params: ['i32', 'i32'],

      results: [],

    },

  ],

  globals: [],

  memories: [],

  tables: [],

  elements: [],

});

```