What is nan?
The 'nan' package stands for 'Native Abstractions for Node.js'. It is a header file that wraps Node.js and V8 APIs, providing a set of utilities for native module developers to create and maintain native addons across Node.js versions.
What are nan's main functionalities?
Simple Asynchronous Operations
This feature allows developers to perform asynchronous operations in their native addons. The code sample demonstrates how to create an asynchronous worker using 'NanAsyncWorker' and queue it with 'NanAsyncQueueWorker'.
const { NanAsyncWorker, NanAsyncQueueWorker } = require('nan');
class MyWorker extends NanAsyncWorker {
constructor(callback) {
super(callback);
}
Execute() {
// perform heavy task
}
HandleOKCallback() {
this->callback().Call(0, nullptr);
}
}
NanAsyncQueueWorker(new MyWorker(new NanCallback(callback)));
Persistent References
This feature provides a way to create persistent references to V8 objects that won't be garbage collected until explicitly cleared. The code sample shows how to create, reset, check, and clear a persistent reference.
const { NanPersistent } = require('nan');
let persistent = new NanPersistent<v8::Object>();
persistent.Reset(obj); // obj is a V8 object
persistent.IsEmpty(); // checks if the persistent handle is empty
persistent.Clear(); // clears the persistent handle
Callbacks
This feature allows native module developers to store and invoke callbacks. The code sample illustrates how to create a 'NanCallback' from a V8 function and invoke it with no arguments.
const { NanCallback } = require('nan');
let callback = new NanCallback(info[0].As<v8::Function>());
callback.Call(0, nullptr);
Other packages similar to nan
node-addon-api
node-addon-api is an alternative to 'nan' that provides a C++ wrapper classes which simplify the use of the Node.js Addon API. It aims to provide a more stable API across Node.js versions and is recommended by the Node.js team as the primary interface for writing native addons.
ffi-napi
ffi-napi is a Node.js addon for loading and calling dynamic libraries using pure JavaScript. It is similar to 'nan' in that it allows interaction with native code, but it focuses on foreign function interfaces rather than providing abstractions for writing native modules.
ref-napi
ref-napi is a package that provides a way to create, access, and manipulate binary data in Buffer instances in Node.js. It is similar to 'nan' in that it deals with native memory management, but it is more focused on buffer manipulation rather than abstracting Node.js and V8 APIs.
1to2 naively converts source code files from NAN 1 to NAN 2. There will be erroneous conversions,
false positives and missed opportunities. The input files are rewritten in place. Make sure that
you have backups. You will have to manually review the changes afterwards and do some touchups.
$ tools/1to2.js
Usage: 1to2 [options] <file ...>
Options:
-h, --help output usage information
-V, --version output the version number