WasmEdge for Node.js Addon

The WasmEdge (previously known as Second State VM, SSVM) is a high-performance WebAssembly runtime optimized for server-side applications. This project provides support for accessing WasmEdge as a Node.js addon. It allows Node.js applications to call WebAssembly functions written in Rust or other high-performance languages. Why do you want to run WebAssembly on the server-side? The WasmEdge addon could interact with the wasm files generated by the rustwasmc compiler tool.

NOTICE

In the current stage, our prebuilt version only supports x86_64 and aarch64 Linux. Or you could use --build-from-source flag to build from the source during addon installation.

WasmEdge versions

There are mappings of wasmedge-core versoins and corresponding WasmEdge versions:

wasmedge-core	WasmEdge
0.8.1	0.8.1
0.8.2-rc.1	0.8.1
0.8.2	0.8.2
0.8.3	0.8.2
0.9.0-rc.1	0.9.0-rc.1
0.9.0	0.9.0

Development Requirements

Users should install the dependencies by the following requirments:

• boost >= 1.65.0
• llvm >= 10
• liblld-10-dev >= 10
• libstdc++6 >= 6.0.28 (GLIBCXX >= 3.4.28)
• g++ version >= 9.0 (Optional, if you have to build from source)

Prepare the environment

Use our docker image (recommended)

docker pull wasmedge/wasmedge

For ubuntu 20.04

# Tools and libraries
sudo apt install -y \
	software-properties-common \
	cmake \
	libboost-all-dev

# And you will need to install llvm for wasmedge-aot tools
sudo apt install -y \
	llvm-dev \
	liblld-10-dev

# WasmEdge supports both clang++ and g++ compilers
# You can choose one of them for building this project
sudo apt install -y gcc g++
sudo apt install -y clang

Verify the version of llvm

sudo apt list | grep llvm

# Expected output
...omitted...
llvm-dev/focal,now 1:10.0-50~exp1 amd64 [installed]
llvm-runtime/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
llvm/focal,now 1:10.0-50~exp1 amd64 [installed,automatic]
...omitted...

# If the version is 1:10.x, then your llvm version is correct.

Verify the version of libstdc++6

strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX

# Expected output
...omitted...
GLIBCXX_3.4.24
GLIBCXX_3.4.25
GLIBCXX_3.4.26
GLIBCXX_3.4.27
GLIBCXX_3.4.28
GLIBCXX_DEBUG_MESSAGE_LENGTH

# If you can find GLIBCXX_3.4.28 in the output, then your libstdc++6 version is correct.

Running on MacOS Darwin

To run on MacOS you will need to build from source by following the steps mentioned below,

• Install WasmEdge library using the installation script
• Install all the necessary packages
• Clone the wasmedge-core project to your local environment
• Run npm install

Works with Rust library using Wasm-Bindgen

Please refer to Tutorial: A Wasm-Bindgen application.

Works with Rust application using standalone wasm32-wasi backend

Please refer to Tutorial: A standalone wasm32-wasi application.

APIs

Constructor: wasmedge.VM(wasm, wasmedge_options) -> vm_instance

• Create a WasmEdge instance by given wasm file and options.
• Arguments:
  • wasm: Input wasm file, can be the following three formats:
    1. Wasm file path (String, e.g. /tmp/hello.wasm)
    2. Wasm bytecode format which is the content of a wasm binary file (Uint8Array)
  • options: An options object for setup the WasmEdge execution environment.
    • options
      • args : An array of strings that the Wasm application will get as function arguments. Default: [].
      • env : An object like process.env that Wasm application will get as its environment variables. Default: {}.
      • preopens : An object which maps '<guest_path>:<host_path>'. E.g. {'/sandbox': '/some/real/path/that/wasm/can/access'} Default: {}.
      • EnableWasiStartFunction : This option will disable wasm-bindgen mode and prepare the working environment for the standalone wasm program. If you want to run an application with main(), you should set this to true. Default: false.
      • EnableAOT : This option will enable WasmEdge AoT mode. Default: false.
      • EnableMeasurement : This option will enable measurement but decrease its performance. Default: false.
      • AllowCommands : An array of strings that indicate what commands are allowed to execute in the WasmEdge Process Module. Default [].
      • AllowAllCommands : Allow users to call any command in the WasmEdge Process Module. This option will overwrite the AllowCommands. Default: false.
• Return value:
  • vm_instance: A WasmEdge instance.

Methods

Start() -> Integer

• Emit _start() and expect the return value type is Integer which represents the error code from main().
• Arguments:
  • If you want to append arguments for the standalone wasm program, please set the args in wasi options.
• Example:

let error_code = Start();

Run(function_name, args...) -> void

• Emit function_name with args and expect the return value type is void.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

Run("Print", 1234);

RunInt(function_name, args...) -> Integer

• Emit function_name with args and expect the return value type is Integer (Int32).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunUInt(function_name, args...) -> Integer

• Emit function_name with args and expect the return value type is Integer (UInt32).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunInt64(function_name, args...) -> BigInt

• Emit function_name with args and expect the return value type is BigInt (Int64).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunUInt64(function_name, args...) -> BigInt

• Emit function_name with args and expect the return value type is BigInt (UInt64).
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunInt("Add", 1, 2);
// result should be 3

RunString(function_name, args...) -> String

• Emit function_name with args and expect the return value type is String.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunString("PrintMathScore", "Amy", 98);
// result: "Amy’s math score is 98".

RunUint8Array(function_name, args...) -> Uint8Array

• Emit function_name with args and expect the return value type is Uint8Array.
• Arguments:
  • function_name : The function name which users want to emit.
  • args <Integer/String/Uint8Array>*: The function arguments. The delimiter is ,
• Example:

let result = RunUint8Array("Hash", "Hello, world!");
// result: "[12, 22, 33, 42, 51]".

Compile(output_filename) -> boolean

• Compile a given wasm file (can be a file path or a byte array) into a native binary whose name is the given output_filename.
• This function uses WasmEdge AoT compiler.
• Return false when the compilation failed.

// Compile only
let vm = wasmedge.VM("/path/to/wasm/file", options);
vm.Compile("/path/to/aot/file");

// When you want to run the compiled file
let vm = wasmedge.VM("/path/to/aot/file", options);
vm.RunXXX("Func", args);

GetStatistics() -> Object

• If you want to enable measurement, set the option EnableMeasurement to true. But please notice that enabling measurement will significantly affect performance.
• Get the statistics of execution runtime.
• Return Value Statistics
  • Measure -> : To show if the measurement is enabled or not.
  • TotalExecutionTime -> : Total execution time (Wasm exeuction time + Host function execution time) in `` unit.
  • WasmExecutionTime -> : Wasm instructions execution time in ns unit.
  • HostFunctionExecutionTime -> : Host functions (e.g. eei or wasi functions) execution time in ns unit.
  • InstructionCount -> : The number of executed instructions in this execution.
  • TotalGasCost -> : The cost of this execution.
  • InstructionPerSecond -> : The instructions per second of this execution.

  let result = RunInt("Add", 1, 2);
  // result should be 3
  let stat = GetStatistics();
  /*
  If the `EnableMeasurement: true`:
  
  stat = Statistics:  {
    Measure: true,
    TotalExecutionTime: 1512,
    WasmExecutionTime: 1481,
    HostFunctionExecutionTime: 31,
    InstructionCount: 27972,
    TotalGasCost: 27972,
    InstructionPerSecond: 18887238.35246455
  }
  
  Else:
  
  stat = Statistics:  {
    Measure: false
  }
  */