
In my previous post about [Native Rust Modules for NodeJS][1], people asked me how neon bindings would compare to WASM. Let's check!



# What is WASM?

> **WebAssembly** (sometimes abbreviated **Wasm**) is an [open standard](https://en.wikipedia.org/wiki/Open_standard) that defines a [portable](https://en.wikipedia.org/wiki/Software_portability) [binary-code](https://en.wikipedia.org/wiki/Binary_code) format for [executable programs](https://en.wikipedia.org/wiki/Executable), and a corresponding [text format](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format), as well as interfaces for facilitating interactions between such programs and their host environment.The main goal of WebAssembly is to enable high-performance applications on [web pages](https://en.wikipedia.org/wiki/Web_page), but the format is designed to be executed and integrated in other environments as well, including standalone ones.- [Wikipedia](https://en.wikipedia.org/wiki/WebAssembly)

WASM (or WebAssembly) is a binary code. It is executed by a portable VM that is currently implemented in [all major browsers](https://caniuse.com/?search=wasm).

However, as Assembly, WASM is not that pleasant to write in and therefore other languages, and Rust among them, support WASM as compilation target.

The purpose of this article is to:

1. Do a quick introduction to compiling Rust into WASM
2. Benchmark Pure JS, Native Module and WASM Module implementations of the same function
3. Provide basic guidelines towards when to choose either implementation

Please make sure you've read my [previous article][1], because this one is built on it. You can find the full code for this tutorial on [GitHub][2]. Let's dive in.

# How to compile Rust to WASM

For native modules we have Neon, for WASM we have [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen). `wasm-bindgen` gives the tools needed for importing JS functions into Rust and exporting Rust function to JS. Let us look at how we can create a WASM version of our `fibonacci` function.

First, we need to make sure our `Cargo.toml` lists `wasm-bindgen` as dependency like this:

```toml
wasm-bindgen = { version = "0.2.78"}
```

After that, everything that is left, is to mark our function with a special macro, like this:

```rust
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
fn fibonacci(n: i32) -> i32 {
    return match n {
        n if n < 1 => 0,
        n if n <= 2 => 1,
        _ => fibonacci(n - 1) + fibonacci(n - 2)
    };
}
```

And that’s it! 🎉

Thank you for reading. See you in the next one.

Not really. I suggest you read the [wasm-bindgen Guide](https://rustwasm.github.io/docs/wasm-bindgen/introduction.html), there is a lot of information about how to interact with JS from Rust and vice versa and information regarding what types are supported and how you can transfer them between the two languages.

In order to build the WASM, we need another tool, called [wasm-pack](https://github.com/rustwasm/wasm-pack), We then can execute the following command `wasm-pack build --target nodejs`, which will produce a NodeJS compatible WASM (you can read more about different targets [here](https://rustwasm.github.io/wasm-pack/book/commands/build.html#target)). The resulting code will be placed in `pkg` directory and will contain 4 files:

1. `index.d.ts` – Typescript definitions for our module
2. `index.js` – The main file that will initialize the `WebAssembly` module and create a `WebAssembly` instance that we can interact with (feel free to take a look inside, its very readable)
3. `index.wasm` – The actual machine code of the WebAssembly
4. `index.wasm.d.ts` – Typescript definitions for the WASM file

You then simply require the files from `pkg` dir and use them as regular JavaScript (or TypeScript).

```js
const {fibonacci_wasm} = require("./pkg/index");
const result = fibonacci_wasm(number);
```

# What about Performance?

Ah. Performance. The thing that Javascript developers care for the most.

I’m going to use the [hyperfine](https://github.com/sharkdp/hyperfine) tool, run each `fibonacci` with 3 warmup runs, computing different numbers, taking the mean running time, and present you the results. Please note: **These are not laboratory grade benchmarks**.

All benchmarks are run on 2020 Mac Mini M1 with 16GB of memory.

| Runtime                 | 30th Fibonacci | 44th Fibonacci | 45th Fibonacci | 46th Fibonacci |
| ----------------------- |:--------------:|:--------------:|:--------------:|:--------------:|
| **JavaScript (NodeJS)** | 165.2ms        | 5.846s         | 9.358s         | 15.038s        |
| **Native Rust**         | 161.5ms        | 2.271s         | 3.578s         | 5.721s         |
| **Rust WASM**           | 163ms          | 3.286s         | 5.207s         | 8.317s         |

## Analysis

I hope no body is surprised that Rust took the 1st place, followed by WASM, while JavaScript was finishing last.

It’s interesting though to see that on low numbers, such as 30th Fibonacci number, all 3 methods performed roughly the same, with Rust being 2.23% faster and WASM being 1.33% faster. This proves again that you always need to benchmark a specific function / method before assuming that a switch to low-level languages will perform better.

However, once we go higher in the Fibonacci numbers, we can see a clear difference between the 3 methods.

We can see that for JavaScript, the jump between 44th and 45th Fibonacci numbers resulted in an increase of **60.07%** in time, while the jump from 45th to 46th number resulted in **60.69%** increase.

For Native Rust module, the increase resulted in **57.55%** and **59.89%** respectively, while for WASM the numbers were **58.46%** and **59.72%** respectively.

**Conclusion 1:** Rust was more efficient in computing the next number in the chain followed by WASM while JS taking bronze medal in this race.

Let’s continue. Native Rust was **61.15%** faster than JS in computing the 44th number, while WASM was **43.79%** faster. For 45th and 46th numbers, Rust was **61.76%** and **61.95%** faster respectively, while WASM was **44.35%** and **44.69%** faster, respectively.

**Conclusion 2:** Opting for Native Rust module, increased the performance by **60%** on average! Opting for WASM, increased the performance by almost **45%**.

Rust was **44.69%** faster than WASM in computing the 44th number; **45.52%** faster in computing the 45th number, and **45.37%** faster in computing the 46th number.

**Conclusion 3:** Rust on average was **45%** faster than WASM.

## Summary

I hate benchmarks. Especially on useless functions like Fibonacci. You should always do side-by-side comparison for **your use case**, rather than rely on benchmarks like this one. However, this benchmark can give us some base line assumptions. We can see that JavaScript is fast enough on lower Fibonacci numbers, however, it struggles as we go higher.

It’s no surprise that WebAssembly is taking a strong second place. One of its goals was to provide *near-native code execution speed*. However, considering the fact that WebAssembly is executed by a VM, it will be hard to achieve real native performance, like with Rust.

# What you should choose and when?

I won’t discuss when and why you should choose JavaScript. Chances are, if you are reading this article, that you’ve already chosen JavaScript but looking at how to improve performance in critical parts of your application. Therefore, I’ll focus on providing the differences between Native modules in Rust and WebAssembly.

## Native or WebAssembly?

First, you need to understand the major difference between the two. Native modules are modules that are written in a compiled language like Rust or C/C++ and are imported via `node-ffi` to use in NodeJS applications. They are no different from `.so` or `.dll` files that are loaded by, say, Java JNI or any other language with FFI support.

WebAssembly on the other hand is a **compilation target**. What it means is that the best way to write WASM is to actually compile another language, such as Rust or C/C++ **into** WebAssembly. Yes, you can write WASM directly, by writing a WAT (WebAssembly Text) files and then translating them to WASM by using [wabt](https://github.com/webassembly/wabt), but why would you do that? I won’t argue that x86 Assembly is a useful language to know for certain applications (for example extreme optimization cases for Games or Digital Audio Workstations), WASM, on the other hand, as a language is useless, because many higher-level languages can be compiled to WASM. And since WASM is mainly a compilation target, I *assume* the difference in performance between a C++ or Rust implementation compiled to WASM will boil down to the actual performance of the code written in C++/Rust, and how good are the tools that compile said code to WASM ([Emscripten](https://en.wikipedia.org/wiki/Emscripten) in that case). Other than that, there should be no performance difference whether the WASM was compiled from C or from Rust.

Having said that, there is one big difference between the two. When I’ve started to do the research for this article, I wanted to focus on a more realistic problem rather than Fibonacci. I’ve downloaded at 14.7MB CSV file that contains ranges of IPv4 addresses that are mapped to different countries. My idea was to parse this CSV using the 3 methods, load the data into memory as an array, and then perform a lookup of 50 random IPs to find out to which countries they belong to. This would simulate a scenario where you have huge chunk of data being loaded into memory and you need to scan it to find a specific value.

I’ve successfully completed the task for JavaScript and for Native Rust module, but when I’ve finished writing it for WASM, upon opening the CSV file from the Disk - I’ve got a `panic` call. This was the first time I’ve realized the biggest difference between Native Rust module and WASM.

### A short trip to the land called `std` - The standard library

You see, compiled languages can be compiled for different operating systems and target architectures. The two biggest architectures as of today are `x86` / `x86_64` (The standard 32bit and 64bit architecture we know, that are implemented by Intel and AMD) and `armv7` thanks to Smartphones, Raspberry PI and the recent Mac M1 processors. Each architecture handles things like floats and math differently, therefore `gcc` (the C compiler) and `rustc` (the Rust compiler) need to know how to produce the machine code suited for each architecture. On top of all that, each operating system such as Linux, MacOS and Windows, has it’s own way to manage things like file descriptors and network operations. When you write `File::open` in Rust, what it does is actually calling the OS defined method to handle file opening. It fact, the `File` struct in Rust is no more than simply

```rust
pub struct File {
    inner: fs_imp::File,
}
```

While `fs_imp::File` being the actual filesystem implementation (be it NTFS or ext4) which is handled by the OS . [^1]

`std` is very interesting, I even had some small experience implementing my own `memset`, around 10 years ago when I was toying with my own [OS kernel](https://github.com/skwee357/wrap-os/blob/master/kernel/src/klib/memory.cpp). But what’s the connection to WASM?

Well, remember I’ve said that WASM is a **compilation target**? So essentially, when you are running `wasm-pack` somewhere down the line it calls `cargo build` (which in turns calls `rustc`) and it passes `cargo` a special argument, `--target` that is equal to `wasm32-unknown-unknown`. It mens that we are compiling a `wasm` 32 bit code on an unknown vendor with unknown system (other examples of target might include things like `x86_64-pc-windows-msvc` meaning that we are compiling to an Intel/AMD 64bit architecture, on PC, for Windows using the MSVC [ABI](https://en.wikipedia.org/wiki/Application_binary_interface). You can list all supported targets with `rustc --print target-list`).

And since WASM is a compilation target with unknown vendor and system, there is no `stdlib`!

In fact, we can go to the `unsupported` system in Rust source code, and see that `File::open` actually calls to `unsupported()` [^2] function, which simply panics.

And this leads me to the biggest difference between the two — if you need to use any of the `stdlib` utils such as accessing the filesystem, accessing network, threads and anything related to the OS - **chose native Modules**. WASM simply can’t support this functionality, since it was designed to be executed by a VM that is running in a sandboxed environment.

#### Correction

*Upon reading more, I've realized that there are 2 compilation targets for WASM: `wasm32-unknown-unknown` which we've already seen and `wasm32-wasi`. [WASI](https://wasi.dev/) or Web Assembly System Interface is, a still in development, standard to get safe access to some resources of the OS such as `fd_read`, `fd_write` and etc. Some WASM VMs provide support for WASI, but for my understanding, no browser currently supports WASI as it's not fully standardized. Back to the article.*

Below is a simple guideline when to choose Native vs WebAssembly (as I don't have vast experience with both methods in order to give you a definitive flowchart).

## Comparison between Native Modules and WebAssembly

### Performance

Due to the fact that WASM is executed by a VM, native modules will, *most likely*, be more performant that their WASM counterpart.

### Reusability

Native modules are also reusable. We can use them in any other language that supports FFI. So, for example, if you have a shared logic in Rust native module, you can load it from Nodejs and from Python (using [CFFI](https://cffi.readthedocs.io/en/latest/)) or Ruby (using [Ruby FFI](https://github.com/ffi/ffi)). WebAssembly on the other hand, can only be run by WASM VM.

### Ergonomics

In my opinion, the ergonomics of `wasm_bindgen` are way better than `neon`. I like `neon`, don't get me wrong, but all you need to do in order to export a function from Rust to WASM is to add `#[wasm_bindgen]` before the function. With `neon` you need to mess with conversions. 

### Portability

Native modules depend on the host machine. WASM being run by a VM is very portable format — get a `.wasm` file and it’s guaranteed to run in any environment that has a WASM VM. Native modules need to be recompiled for each host. It’s not that big of a deal if you are using lean docker containers such as `alpine` but it is something you need to be aware of, and the *"I don’t know, it works on my machine"* becomes a real issue.

### Entry barrier for new developers

Native modules can be written, *mainly*, in two languages: C/C++ or Rust. C/C++ get a lot of hate, while Rust is the most loved language [^3]. But Rust is not simple. In C/C++ you fight with `core dumps`, in Rust you fight the `borrow checker`. It's not the most simple language to grasp for someone who is not familiar with the concepts of memory management and pointers.

WASM being a compilation target, can be produced from many languages. The main ones are C/C++ and Rust, but there is also partial support for Python, Java, Ruby and Go. And once WASM will support multi-threading and garbage collection, C# will be a candidate as well. More over, there is a special language, with TypeScript like syntax, called [AssemblyScript](https://en.wikipedia.org/wiki/AssemblyScript), that was created with one purpose — to be compiled to WASM.

So the entry barrier to WASM is simpler, in my opinion.

### Node vs Browser

While both this post and my [previous one][1] focuses mainly on NodeJS, we can’t forget the browser. JavaScript is still, and probably forever will be, king in the Browser. And Native modules can’t be executed in the browser. Or any other place that is not NodeJS runtime. JavaScript does not (yet?) support FFI.

So in case you are developing for the browser, or any other system that has access to JavaScript runtime and WASM VM – your only choice is WebAssembly.

# Conclusion

Native modules and WebAssembly are both performance optimizations to JavaScript, but they are here to solve different problems. Native modules are here to **extend** NodeJS with performant code while giving you full access to `stdlib`. WebAssembly is here to **replace** non-performant JavaScript code with a near-native performance binary that is executed in a sandboxed environment.

[1]: /supercharge-nodejs-with-rust
[2]: https://github.com/skwee357/rust-native-vs-wasm
[3]: https://github.com/rust-lang/rust/blob/master/library/std/src/fs.rs#L92
[4]: https://github.com/rust-lang/rust/blob/master/library/std/src/sys/unsupported/fs.rs#L178
[5]: https://insights.stackoverflow.com/survey/2021#technology-most-loved-dreaded-and-wanted

[^1]: [Rust fs.rs][3]
[^2]: [Rust fs.rs][4]
[^3]: [Stackoverflow 2021 survey][5]


NodeJS Native Module vs WASM


Node isn't the fastest framework out here. It's not the slowest either, v8 is doing wonders to its speed, but nevertheless, if we setup an unfair battle between Node and say Rust; Node will lose.



---
*If you are interested to compare this approach to WebAssembly, I've written a new [article](/native-rust-wasm) on WASM in comparison to native modules. [Check it out](/native-rust-wasm)!*

## What is Rust?

> Rust is a multi-paradigm, high-level, general-purpose programming language designed for performance and safety, especially safe concurrency. Rust is syntactically similar to C++, but can guarantee memory safety by using a borrow checker to validate references - [Wikipedia][1]

Rust is a strongly typed and compiled language. It supports a lot of, so called, modern features such as closure and anonymous functions, a rich standard library, types and polymorphism as well as modern tooling such as Cargo which is an equivalent to `npm` in the world of Node.

Rust is also Memory Safe language. All **safe** Rust code is memory checked during compilation so unless you opt to use unsafe Rust, you won't encounter the famous `Segmentation Fault` you'd get in C or C++ by accessing a pointer that is pointing to a memory you no longer own.

All this makes Rust a very attractive replacement to C/C++.

## Ok great and all, but I write Javascript!

Yeah, me too. And here comes the great part. We can use all the beauty of Rust in Javascript!

Oftentimes we encounter a situation when we need to run a heavy task such as PDF generation or some sort of computation. Most of the modules in NPM are Javascript based, meaning they will suffer a penalty at runtime. Usually in such situation we opt to "creative" solutions such as offloading the heavy process to a Lambda function and turning the entire process into asynchronous for the user. And yet, I rarely hear people suggest or even evaluate the solution of embedding a native module that most of the times will be faster.

Another great usage for Rust in the Javascript ecosystem - is providing shared backend for Desktop applications. Let's say you are developing an MVP in Electron and want to use SQLite for data storage. While you can use the [sqlite3][2] package which is native C++, you can also create a dynamic library (also knows as `.so` or `.dll` file in Linux and Windows respectively) in Rust. What this gives you, is the ability to later ditch Electron in favor of Native Framework for each OS while doing 0 changes to your Backend code.

## So how do I use Rust from Javascript?

I'm glad you've asked! Please meet `Neon`.

![Neon Bindings {774x300}][image-1]

[Neon][3] is a library and toolchain for embedding Rust in your Node.js applications and libraries. It is similar to creating native modules with C/C++ but with none of the fear and headaches associated with unsafe systems programming.

Let's try now to create a native Fibonacci function in Rust and call it from Node. Disclaimer: This is not a tutorial on Rust, so I'm not going to explain Rust specifics here. You can always go to the [Rust Book][4] to learn about Rust, however the syntax I'm gonna use here should be easy to understand to anyone familiar with Typescript, or any other statically typed language like C/C++, Java, Kotlin or C#. So let's dive in.

### Step 1 - Setup a project

Let's start by creating a Rust project. We will start by creating `Cargo.toml` file. It's a file that mimics the role of `package.json`:

```toml
[package]
name = "fibonacci_rs"
version = "0.1.0"
edition = "2018"

[lib]
crate-type = ["cdylib"]

[dependencies]
neon = { version = "0.9", default-features = false, features = ["napi-6"] }
```

First, we define our package. We give it a name, we define the version and what edition of Rust we are going to use.

Then we define the type of our package. Remember, Rust is a compiled language and it can produce all kinds of binary outputs. They could be executables (such as `.exe` files in Windows) or they could be library files such as `.so` or `.dll`. In our case we create a library, hence the `[lib]` declaration.  There are 2 types of libraries that most languages (including Rust) can produce: `dynamic` and `static`. In short:

* Static libraries usually have the extension of `.a` or `.lib` in Linux/MacOS and Windows respectively, Static libraries are compiled **into** the final executable. So if I produce a static library and then link my executable against it - the final output will be one file, where the static library is embedded into the executable itself. Their main purpose is to create reusable code but once the binary is compiled, you can't change the implementation of a static library without recompiling the binary.
* Dynamic libraries have the extensions of `.so`, `.dylib` and `.dll` in Linux, Mac and Windows respectively. The difference is that dynamic libraries **are not** compiled into the final binary file and instead are loaded at runtime by the OS. So when I link my binary against a dynamic library, I'll have 2 files in the output - the dynamic library and my binary. Their main use is to create a reusable code between multiple applications without locking the implementation. Also, since dynamic libraries are not compiled into the executable, I can reuse their code by having any number of executables that depend on the same dynamic libraries. Libraries such as Microsoft C/C++ runtime are dynamic libraries that are downloaded once by the user to their machine, and then used by countless applications that depend on MSVC.

Since we are not going to recompile Node.js itself, we are interested in producing a dynamic library that can be linked at runtime, rather than embedded directly into Node.js runtime. Therefore we define our `crate-type` as `cdylib` meaning that we want to create a **d**ynamic **lib**rary with C ABI (hence the "c" in the beginning). I'm not going to go into details what ABI is and what's its purpose, I'll instead drop a link to [Wikipedia][5]. Note that we can also create `dylib` which will have unstable Rust ABI that can be changed across Rust releases.

Last but not least - we define our dependencies. In our case, we depend only on `neon` library.

### Step 2 - Write our Rust Fibonacci

Since we are creating a rust library, we need to create the following file in the root of our project: `src/lib.rs`. In this file we are going to create our Fibonacci function:

```rust
fn fibonacci(n: i32) -> i32 {
	return match n {
		n if n < 1 => 0,
		n if n <= 2 => 1,
		_ => fibonacci(n - 1) + fibonacci(n - 2)
	}
}
```

A simple, recursive function that accepts a 32bit integer and returns a 32bit integer.

### Step 3 - Create a binding for our Rust Fibonacci into Javascript

Currently, we've created a Rust function. We can run `cargo build` in order to compile our code. This will download and compile `neon` and any of its dependencies, and will compile our `lib.rs` file. We will get a compilation warning saying that `fn fibonacci` is dead code, since no body uses it, but nevertheless, if you've done everything correctly, you should end up with a new directory tree of `target/debug` and inside it you will find a file named `libfibonacci_rs.{dylib,so,dll}` (the extension will depend on what type of OS you are compiling on).

Since its a dynamic library that does not extern any functionality, it is now useless. But let's put some Neon lights onto it. Edit `src/lib.rs` and add the following function:

```rust
use neon::context::{Context, FunctionContext};
use neon::types::JsNumber;
use neon::result::JsResult;

fn fibonacci(n: i32) -> i32 {
	return match n {
		n if n < 1 => 0,
		n if n <= 2 => 1,
		_ => fibonacci(n - 1) + fibonacci(n - 2)
	}
}

fn fibonacci_api(mut cx: FunctionContext) -> JsResult<JsNumber> {
	let handle = cx.argument::<JsNumber>(0).unwrap();
	let res = fibonacci(handle.value(&mut cx) as i32);
	Ok(cx.number(res))
}
```

We've added some `use neon` statements. They are similar to `import` or `require` statements in Javascript. We've also added a new function called `fibonacci_api`. This function is the conversion layer between Javascript and Rust. It accepts a `FunctionContext` since it's a function and returns a `JsResult` of `JsNumber` meaning that on successful execution, it will return a value that is equivalent to `number` type in Javascript.

`cx` is used to interface with the Javascript world. We first get a `Handle` to `JsNumber` which is the first (index 0) argument that was passed to our function. `Handle` is a safe reference to a Javascript value that is owned and managed by the Javascript engine's memory management. Since Javascript is a dynamic language and Rust is statically typed, we need to manually downcast the javascript value to a number. Since `fibonacci_api` can be called with anything (a string, an object or array) from Javascript, this downcast can fail, therefore we need to handle a situation where it fails. In my example, I just `.unwrap` the result of the downcast, since this is a tutorial and not a real world example, but in real world you'd need to handle a situation where the first argument is not a `JsNumber`.

Just a few more words on values and down/up casting and we will continue. Everything you get in Rust via Neon, initially has the type of `JsValue`. `JsValue` is sort of a catch all type that can be anything: `JsNumber`, `JsObject`, `JsNull`, `JsBuffer` and etc. A `Handle` with `JsValue` can be downcasted to a specific type by using `Handle::downcast()` or upcasted by using `Handle::upcast()`. There is a nice diagram on the [`neon::types` Documentation][6] that shows the relation between `JsValue` and other Javascript types. I'll include it here:

![javascript type hierarchy {960x480}][image-2]

Anyway, back to the code.

So now we have a `Handle<JsNumber>`. We can access the internal value by calling `Handle::value()` method, which in case of a `JsNumber` handle, returns `f64` (since `number` in Javascript is represented as float), but we safely convert it to `i32` for our Fibonacci function.

We then safely return the result as `JsNumber` by calling the `.number()` method of the `Function Context`. And we are done.

Once again, we can compile the code by running `cargo build`. It will once again warn us about dead code, but this time it will mark both `fibonacci` and `fibonacci_api` function as dead code, since no body calls them.

### Step 4 - Export our Rust function to Javascript world

We are almost done with Rust. Bear with me for a little bit more.

Right now we have a function that converts a JS call into Rust call, but we have no way to call that function from Javascript. Enter the `main`!

If you are familiar with C or C++, every executable has a `main` function. This is a special type of function that the OS will run once it loads your binary into memory. Libraries however do not have `main` functions, since libraries are not meant to be executed by themselves. However you've probably seen a Javascript module. It usually ends with `module.exports = {}`. We can treat it as `main`. And that's what Neon does.

Once again, edit our `src/lib.rs` file:

```rust
use neon::context::{Context, ModuleContext, FunctionContext};
use neon::types::JsNumber;
use neon::result::JsResult;
use neon::result::NeonResult;

fn fibonacci(n: i32) -> i32 {
	return match n {
		n if n < 1 => 0,
		n if n <= 2 => 1,
		_ => fibonacci(n - 1) + fibonacci(n - 2)
	}
}

fn fibonacci_api(mut cx: FunctionContext) -> JsResult<JsNumber> {
	let handle = cx.argument::<JsNumber>(0).unwrap();
	let res = fibonacci(handle.value(&mut cx) as i32);
	Ok(cx.number(res))
}

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
	cx.export_function("fibonacci_rs", fibonacci_api)?;
	Ok(())
}
```

We've added a small function named `main` and marked it with `neon::main` attribute to tell Neon that this is the main entry of the module. This function also accepts a context, but not `FunctionContext` like our previous function, instead it accepts `ModuleContext`. While function context is used to interface with js functions and have operation like getting arguments of a function, up/down casting `JsValue`s into specific types and generating results; Module context is used to interface with Javascript modules, and the main methods in `ModuleContext` are `ModuleContext::export_function()` and `ModuleContext::export_value()`, which are used to export functions and values from a module.

In our case we export a function and name it `fibonacci_rs`, while the actual implementation of it is `fibonacci_api` we've written earlier.

In Javascript world, this code would look something like this:

```js
function fibonacci(n) {
  ...
}
  
module.exports = {
  fibonacci_rs: fibonacci
}
```

Running `cargo build` once again will produce our library without any warnings. We are now done with Rust, let's move to Javascript.

### Step 5 - Fibonacci Javascript

Let us now create a new Javascript file: `fibonacci.js`:

```js
const value = process.argv[2] || null;
const number = parseInt(value);

if(isNaN(number)) {
	console.log("Provided value is not a number");
	return;
}

console.log(number);
```

This is a simple file that reads the first argument we pass to it from CLI, validates that it is a number and prints it back. You can execute it by `node fibonacci.js 10` .

Now we somehow need to call the fibonacci function we've created in Rust. For that we will have to create a `package.json`.

```json
{
  "name": "fibonacci_rs",
  "version": "1.0.0",
  "private": true,
  "main": "fibonacci.js",
  "scripts": {
    "build": "cargo-cp-artifact -nc index.node -- cargo build --message-format=json-render-diagnostics"
  },
  "dependencies": {
    "cargo-cp-artifact": "^0.1.5"
  },
  "devDependencies": {}
}
```

Run `npm install` to install the dependency and then run `npm run build` to generate the native module. If everything worked correctly, you should end up with `index.node` file in your root directory.

Let's explain. `cargo-cp-artifact` is a package maintained by Neon team. What this package does, is handling the extraction of the library produced by `cargo build`. Remember, `cargo build` generates different files depending on the host OS. In my case it generated `libfibonacci_rs.dylib` since I'm on Mac, but it could also generate `.so` or `.dll` files if you are on Linux or Windows. Theoretically, you can go manually to the `target` directory and copy the library file to the root of the project and name it `index.node`, but `cargo-cp-artifact` is a handy utility to do that for you.

Also note: `index.node` is not a special name. You can call it `what.ever`, but the `.node`extension is used to represent a native Node.js module.

Now lets go back to our `fibonacci.js`:

```js
const {fibonacci_rs} = require("./index.node");

const value = process.argv[2] || null;
const number = parseInt(value);

if(isNaN(number)) {
	console.log("Provided value is not a number");
	return;
}

const result = fibonacci_rs(number);
console.log(result);
```

You can run it with `node fibonacci.js 10` and you should get the result of `55`. **Note:** do not input high numbers. Since this is a very inefficient and recursive implementation of Fibonacci, it will hang on numbers above 40ish.

Let's explain. We require our `index.node` as if it was a regular Javascript module. We know that it exports only 1 function: `fibonnaci_rs` since that's what we did in `cx.export_function("fibonacci_rs", fibonacci_api)?;` in `src/lib.rs` , hence we require it and then execute it.

That's it! We've created a native module in Rust.

You can clone the entire code of this tutorial from my [GitHub][7]. You can also explore the [examples repository][8] by Neon for more robust examples like `gzip-stream` or `async sqlite`. Feel free to explore the [neon repo][9] as well, they also have a link to their Slack channel for questions and support.

## What you can do with it?

Many things. You can access native implementations that are not available in Node. You can use any Rust `crate` (equivalent to `npm` package) from [crates.io][10] (provided you implement the required neon bindings), or you can have another strong tool to evaluate when your Javascript implementation is not fast enough for your needs. I'm myself currently experimenting in writing a Desktop application using Electron for the Frontend and Rust for the Backend. This allows me to isolate my backend code into a reusable library that I can plug into any more performant UI Framework such as Qt, GTK and SwiftUI, as well as letting me access SQLite using native sqlite implementation written in C rather than Javascript.

## Things to take into account

If you are not coming from the world of compiled languages, or you knowledge of it became rusty (no pun intended), you might need to pay attention to some caveats with using native modules written in any language and not just Rust.

With Javascript, Python or Ruby, I can give you a code and you can run it (provided you have the runtime installed). Dynamic languages are easily shared between people and machines. Compiled languages are not. If I give you my binary `index.node` from this tutorial, you might or might not be able to use it. It depends on the host OS you are running. The safe bet is to compile the code yourself on the OS that you intend to run the code. This means that native modules should not be committed into your source control, but instead be built during your CI/CD. And they **must** be built on the same OS that they are going to be executed on. So if your Node application is running in Alpine Linux Docker container, it is very much advised that you compile your native modules on the same docker image.

---
That's it for today. I hope this newly acquired knowledge will help you to become a better Node developer.


[1]:	https://en.wikipedia.org/wiki/Rust_(programming_language)
[2]:	https://www.npmjs.com/package/sqlite3
[3]:	https://neon-bindings.com/
[4]:	https://doc.rust-lang.org/book/
[5]:	https://en.wikipedia.org/wiki/Application_binary_interface
[6]:	https://docs.rs/neon/0.9.1/neon/types/index.html
[7]:	https://github.com/skwee357/node-rust-supercharge
[8]:	https://github.com/neon-bindings/examples
[9]:	https://github.com/neon-bindings/neon
[10]:	https://crates.io/

[image-1]:	/images/neon.png#center
[image-2]:	/images/types.jpg#center "The Javascript Type Hierarchy"

This Week in Rust 414

Node Weekly Issue 411

Dev Weekly Issue #108

Supercharge Your NodeJS With Rust


A key to a good API design is good control of what data your controllers or API end points accepts. Another important key to a good design — is that you can take a brief look at your API end point and immediately understand how your request should look.



Now, of course you can validate all the request parameters inside the API end point itself. But this makes your end point messy and sort of violates the [SRP](https://en.wikipedia.org/wiki/Single_responsibility_principle) (your end point should not validate requests. It should only work with them and provide a response). Now, if you are old fashioned and work with XML requests / response, you can of course use XSD to validate your incoming requests. But we are in 2016 where JavaScript runs in your browser, your desktop environment, your media center, you smart watch, your smart home and soon in your brain implants. So we gonna use JSON!

*But, how do I validate JSON?* I’m glad you’ve asked. Meet [joi](https://github.com/hapijs/joi) by [hapijs](http://hapijs.com/). This small and awesome library can validate your JavaScript objects. It can do all kind of stuff like making sure that a specific key has only specific set of values, or that specific key is only required if another key exists and contains a specific value. So as always, RTFM.

We now have joi to validate our JSONs. But we still need to find an elegant way to put it inside the life cycle of our specific API end point. I’m too lazy to create a specific, generic NPM module so I’ve just dumped the current code I use in my project to a [gist](https://gist.github.com/skwee357/7e4ca3b913f4b1202f51d72fcb1ac0db). Feel free to use it or create a proper NPM module (don’t forget to mention me for being your inspiration ;)

The middleware is very simple. It defines a Bad Request Error that will be thrown if the incoming request is malformed, and what it does, it simply validate the request against a given *schema* (a bit later on that) and assigns the validated object (essentially this is *req.body* but with type conversions and modifiers applied, more on this in [joi API documentation](https://github.com/hapijs/joi/blob/v9.0.4/API.md#validatevalue-schema-options-callback)) to the req.schema (not the best name) so it can be accessed later on inside the API end point (or any next middleware in the chain).

Now lets talk about the schema and how to actually use this. Schema is just a JSON with joi rules. Lets say we have 2 API end points: One for user creation and one for user update. We define then 2 schema:

```js
module.exports = {
    create: Joi.object().keys({
        username: Joi.string().min(3).required(),
        password: Joi.string().min(3).required(),
        email: Joi.string().email().required()
    }),
    update: Joi.object().keys({
        username: Joi.string().min(3).optional()
    })
};
```

In order to create a new user we need to provide 3 required keys: username (at least 3 characters), password (at least 3 characters) and email (should be a real email). And in order to update a user we can just provide an optional new username (at least 3 characters) (side note: an empty request in such case is a valid request, it is up to your end point to make sure to do no-op if the request is empty). We then define our API end points like this:

```js
var SchemaValidationMiddleware = require('path/to/schema/middleware'),
    UserSchema = require('path/to/schema/user'),
    UserController = require('path/to/user/controller');

router.post('/users', SchemaValidationMiddleware.validate(UserSchema.create), UserController.createNew);

router.patch('/users/:id', SchemaValidationMiddleware.validate(UserSchema.update), UserController.edit);
```

And inside the controller / API end point we can use *req.schema* to access the validated schema and perform the required operations. And we can be sure that the controller / end point will be executed only if our request meets the schema we defined for it. The *UserController.createNew* will never be called if one of the keys we defined as required in our schema — missing, if they are mistyped, if there are keys that we are not expecting and etc.,

This gives the answer to the 2 design keys of a good API that I’ve outlined in the beginning:

- Controllers / end points only manipulates the request and provide a response. They are not used to validate the request. We can be sure that our controllers / end points will never be called with an invalid request.
- By looking at our *schema/user.js* we can immediately understand how our request should look. We also can give those files to our customers / put them in our API documentation.

You can extend this idea and provide validation for responses as well. By writing a joi schema for the response and adding another middleware after your actual API end point that will validate the response you want to send against a response schema, so this can help you to avoid cases where developers might mistype a response key for examples *usrename* instead of *username*. And also by having request and response schema — your API is essentially self documented.

Hope this helped you to become a better JavaScript Jedi! Please share and like! Leave a comment or hit me on [Twitter](https://twitter.com/skwee357) if you have any questions.


Nodejs

Latest Posts

NodeJS Native Module vs WASM

Supercharge Your NodeJS With Rust

Validating Requests With a Simple Middleware for Express