WasmBuilder

0.0.16 verified Sat Apr 25 auth: no javascript abandoned

WasmBuilder is a JavaScript package initially released in 2019, designed for the manual construction of WebAssembly (WASM) modules. It operates at an extremely low level, requiring developers to specify WASM bytecode directly in hexadecimal format. The library provides a programmatic interface to define functions, memory, and tables, offering fine-grained control over the WASM module's internal structure without relying on higher-level language compilation. Its last recorded update was in October 2019, with version 0.0.16, indicating the project is no longer actively maintained. This low-level approach differentiates it from compilers and makes it suitable primarily for educational purposes, deep dives into WASM internals, or highly specialized niche use cases requiring byte-level WASM manipulation.

Common errors

error ReferenceError: require is not defined ↓

cause Attempting to use `require('wasmbuilder')` in an ECMAScript Module (ESM) context (e.g., in a file with `"type": "module"` in `package.json` or a `.mjs` file).

fix

Change your file to a CommonJS context (e.g., remove "type": "module" from package.json, use a .cjs file extension, or run with older Node.js versions). If forced to use ESM, consider dynamic import('wasmbuilder') or a build process to convert CJS to ESM.

error TypeError: WebAssembly.instantiate(): Wasm code is not valid: unknown opcode ↓

cause The hexadecimal bytecode provided to `addFunction` or other builder methods contains invalid WASM opcodes, incorrect operand types, or an improperly structured function body, leading to an invalid WASM module.

fix

Double-check the WASM specification for correct opcodes and their arguments. Use a WASM disassembler on known-good WASM binaries to understand correct structure and hex representations for your desired logic. Ensure function parameters, return types, and local variables are correctly declared and used in the bytecode.

error TypeError: instance.exports.yourFunctionName is not a function ↓

cause The `exportFunction` method was not called for the desired function, or the function name provided to `exportFunction` does not match the name used in `addFunction`, preventing it from being callable from JavaScript.

fix

Verify that builder.exportFunction('internalName', 'externalName') is called for every function you wish to expose, and that 'internalName' exactly matches the first argument given to builder.addFunction.

Warnings

breaking The `wasmbuilder` package has been abandoned since its last update in October 2019 (version 0.0.16). It is not maintained, may contain unpatched security vulnerabilities, and is unlikely to be compatible with newer JavaScript/Node.js features or WASM specifications without significant manual intervention. ↓

fix Consider using actively maintained WASM compilation tools (e.g., Emscripten, Rust/Wasm-bindgen, AssemblyScript) or more recent low-level WASM libraries for production use cases. For learning purposes, be aware of its outdated nature.

gotcha This library requires deep knowledge of WebAssembly bytecode and its hexadecimal representation. Constructing WASM modules manually via hex strings is error-prone and complex, even for simple operations. ↓

fix Thoroughly consult the WebAssembly specification for instruction opcodes and module structure. Utilize WASM disassemblers and validators for debugging custom bytecode. Be prepared for extensive manual debugging.

gotcha The library primarily uses CommonJS (`require`) syntax. Attempting to use it directly in a modern ESM (`import`) environment will result in errors. ↓

fix Ensure your project is configured for CommonJS, or use a build tool like Webpack/Rollup that can handle CJS modules in an ESM context. Alternatively, create a CJS wrapper file that exports the `WasmBuilder` class for ESM consumption.

Install

npm install wasmbuilder

yarn add wasmbuilder

pnpm add wasmbuilder

Imports

WasmBuilder
wrong
```
import { WasmBuilder } from 'wasmbuilder';
```
correct
```
const WasmBuilder = require('wasmbuilder');
```
The library primarily uses CommonJS `require` syntax as it was last updated in 2019. Direct ESM `import` is not natively supported without a transpilation step or a wrapper.
WasmBuilder instance
```
const builder = new WasmBuilder();
```
The main functionality is exposed through instantiating the WasmBuilder class.

Quickstart

This quickstart demonstrates how to create a simple WASM module containing an 'add' function, export it, build the binary, and then instantiate and execute it from JavaScript using direct WASM bytecode.

const WasmBuilder = require('wasmbuilder');
const fs = require('fs');

// Initialize the builder
const builder = new WasmBuilder();

// Define an 'add' function that takes two i32 and returns one i32.
// Its body in WASM bytecode (hex): (local.get 0) (local.get 1) (i32.add) (end)
// This translates to the hex string: "200020016a0b"
builder.addFunction(
  "add",                  // function name for internal use
  ["i32", "i32"],         // parameter types (two 32-bit integers)
  ["i32"],                // return type (one 32-bit integer)
  "200020016a0b"          // WASM bytecode as hex string
);

// Export the 'add' function so it can be called from JavaScript
builder.exportFunction("add", "add");

// Build the WASM module to get its binary representation
const wasmBinary = builder.build();

// Optionally, write the WASM binary to a file
fs.writeFileSync('add.wasm', wasmBinary);
console.log('add.wasm created successfully.');

// Instantiate and use the generated WASM module
(async () => {
  try {
    const { instance } = await WebAssembly.instantiate(wasmBinary, {});
    const addResult = instance.exports.add(5, 7);
    console.log(`Result of add(5, 7): ${addResult}`); // Expected output: 12
  } catch (e) {
    console.error("Error instantiating or running WASM module:", e);
  }
})();