Native Abstractions for Node.js: C++ header for Node 0.8 -> 25 compatibility
npm install @agracio/nanNative Abstractions for Node.js
===============================
A header file filled with macro and utility goodness for making add-on development for Node.js easier across versions 8, 10, 12, 14, 16, 17, 18, 19, 20, 21, 22, 23 and 24.
Current version: 2.23.0
(See CHANGELOG.md for complete ChangeLog)
 
Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.12 to 4.0, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect NODE_MODULE_VERSION and get yourself into a macro-tangle.
This project also contains some helper utilities that make addon development a bit more pleasant.
* News & Updates
* Usage
* Example
* API
* Tests
* Known issues
* Governance & Contributing
bash
$ npm install nan
`
Pull in the path to NAN in your binding.gyp so that you can use #include in your .cpp files:
` python
"include_dirs" : [
"]
`
This works like a -I when compiling your addon.
Example
Just getting started with Nan? Take a look at the Node Add-on Examples.
Refer to a quick-start Nan Boilerplate for a ready-to-go project that utilizes basic Nan functionality.
For a simpler example, see the async pi estimation example in the examples directory for full code and an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of NAN.
Yet another example is nan-example-eol. It shows newline detection implemented as a native addon.
Also take a look at our comprehensive C++ test suite which has a plethora of code snippets for your pasting pleasure.
API
Additional to the NAN documentation below, please consult:
The V8 Getting Started Guide
* V8 API Documentation
* Node Add-on Documentation
$3
A _template_ is a blueprint for JavaScript functions and objects in a context. You can use a template to wrap C++ functions and data structures within JavaScript objects so that they can be manipulated from JavaScript. See the V8 Embedders Guide section on Templates for further information.
In order to expose functionality to JavaScript via a template, you must provide it to V8 in a form that it understands. Across the versions of V8 supported by NAN, JavaScript-accessible method signatures vary widely, NAN fully abstracts method declaration and provides you with an interface that is similar to the most recent V8 API but is backward-compatible with older versions that still use the now-deceased v8::Argument type.
* Method argument types
- Nan::FunctionCallbackInfo
- Nan::PropertyCallbackInfo
- Nan::ReturnValue
* Method declarations
- Method declaration
- Getter declaration
- Setter declaration
- Property getter declaration
- Property setter declaration
- Property enumerator declaration
- Property deleter declaration
- Property query declaration
- Index getter declaration
- Index setter declaration
- Index enumerator declaration
- Index deleter declaration
- Index query declaration
* Method and template helpers
- Nan::SetMethod()
- Nan::SetPrototypeMethod()
- Nan::SetAccessor()
- Nan::SetNamedPropertyHandler()
- Nan::SetIndexedPropertyHandler()
- Nan::SetTemplate()
- Nan::SetPrototypeTemplate()
- Nan::SetInstanceTemplate()
- Nan::SetCallHandler()
- Nan::SetCallAsFunctionHandler()
$3
A _local handle_ is a pointer to an object. All V8 objects are accessed using handles, they are necessary because of the way the V8 garbage collector works.
A handle scope can be thought of as a container for any number of handles. When you've finished with your handles, instead of deleting each one individually you can simply delete their scope.
The creation of HandleScope objects is different across the supported versions of V8. Therefore, NAN provides its own implementations that can be used safely across these.
- Nan::HandleScope
- Nan::EscapableHandleScope
Also see the V8 Embedders Guide section on Handles and Garbage Collection.
$3
An object reference that is independent of any HandleScope is a _persistent_ reference. Where a Local handle only lives as long as the HandleScope in which it was allocated, a Persistent handle remains valid until it is explicitly disposed.
Due to the evolution of the V8 API, it is necessary for NAN to provide a wrapper implementation of the Persistent classes to supply compatibility across the V8 versions supported.
- Nan::PersistentBase & v8::PersistentBase
- Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits
- Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits
- Nan::Persistent
- Nan::Global
- Nan::WeakCallbackInfo
- Nan::WeakCallbackType
Also see the V8 Embedders Guide section on Handles and Garbage Collection.
$3
NAN provides a Nan::New() helper for the creation of new JavaScript objects in a way that's compatible across the supported versions of V8.
- Nan::New()
- Nan::Undefined()
- Nan::Null()
- Nan::True()
- Nan::False()
- Nan::EmptyString()
$3
NAN contains functions that convert v8::Values to other v8::Value types and native types. Since type conversion is not guaranteed to succeed, they return Nan::Maybe types. These converters can be used in place of value->ToX() and value->XValue() (where X is one of the types, e.g. Boolean) in a way that provides a consistent interface across V8 versions. Newer versions of V8 use the new v8::Maybe and v8::MaybeLocal types for these conversions, older versions don't have this functionality so it is provided by NAN.
- Nan::To()
$3
The Nan::MaybeLocal and Nan::Maybe types are monads that encapsulate v8::Local handles that _may be empty_.
* Maybe Types
- Nan::MaybeLocal
- Nan::Maybe
- Nan::Nothing
- Nan::Just
* Maybe Helpers
- Nan::Call()
- Nan::ToDetailString()
- Nan::ToArrayIndex()
- Nan::Equals()
- Nan::NewInstance()
- Nan::GetFunction()
- Nan::Set()
- Nan::DefineOwnProperty()
- Nan::ForceSet()
- Nan::Get()
- Nan::GetPropertyAttributes()
- Nan::Has()
- Nan::Delete()
- Nan::GetPropertyNames()
- Nan::GetOwnPropertyNames()
- Nan::SetPrototype()
- Nan::ObjectProtoToString()
- Nan::HasOwnProperty()
- Nan::HasRealNamedProperty()
- Nan::HasRealIndexedProperty()
- Nan::HasRealNamedCallbackProperty()
- Nan::GetRealNamedPropertyInPrototypeChain()
- Nan::GetRealNamedProperty()
- Nan::CallAsFunction()
- Nan::CallAsConstructor()
- Nan::GetSourceLine()
- Nan::GetLineNumber()
- Nan::GetStartColumn()
- Nan::GetEndColumn()
- Nan::CloneElementAt()
- Nan::HasPrivate()
- Nan::GetPrivate()
- Nan::SetPrivate()
- Nan::DeletePrivate()
- Nan::MakeMaybe()
$3
NAN provides v8::Script helpers as the API has changed over the supported versions of V8.
- Nan::CompileScript()
- Nan::RunScript()
- Nan::ScriptOrigin
$3
The _JSON_ object provides the C++ versions of the methods offered by the JSON object in javascript. V8 exposes these methods via the v8::JSON object.
- Nan::JSON.Parse
- Nan::JSON.Stringify
Refer to the V8 JSON object in the V8 documentation for more information about these methods and their arguments.
$3
NAN includes helpers for creating, throwing and catching Errors as much of this functionality varies across the supported versions of V8 and must be abstracted.
Note that an Error object is simply a specialized form of v8::Value.
Also consult the V8 Embedders Guide section on Exceptions for more information.
- Nan::Error()
- Nan::RangeError()
- Nan::ReferenceError()
- Nan::SyntaxError()
- Nan::TypeError()
- Nan::ThrowError()
- Nan::ThrowRangeError()
- Nan::ThrowReferenceError()
- Nan::ThrowSyntaxError()
- Nan::ThrowTypeError()
- Nan::FatalException()
- Nan::ErrnoException()
- Nan::TryCatch
$3
NAN's node::Buffer helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility.
- Nan::NewBuffer()
- Nan::CopyBuffer()
- Nan::FreeCallback()
$3
Nan::Callback makes it easier to use v8::Function handles as callbacks. A class that wraps a v8::Function handle, protecting it from garbage collection and making it particularly useful for storage and use across asynchronous execution.
- Nan::Callback
$3
Nan::AsyncWorker, Nan::AsyncProgressWorker and Nan::AsyncProgressQueueWorker are helper classes that make working with asynchronous code easier.
- Nan::AsyncWorker
- Nan::AsyncProgressWorkerBase & Nan::AsyncProgressWorker
- Nan::AsyncProgressQueueWorker
- Nan::AsyncQueueWorker
$3
Miscellaneous string & byte encoding and decoding functionality provided for compatibility across supported versions of V8 and Node. Implemented by NAN to ensure that all encoding types are supported, even for older versions of Node where they are missing.
- Nan::Encoding
- Nan::Encode()
- Nan::DecodeBytes()
- Nan::DecodeWrite()
$3
The ObjectWrap class can be used to make wrapped C++ objects and a factory of wrapped objects.
- Nan::ObjectWrap
$3
The hooks to access V8 internals—including GC and statistics—are different across the supported versions of V8, therefore NAN provides its own hooks that call the appropriate V8 methods.
- NAN_GC_CALLBACK()
- Nan::AddGCEpilogueCallback()
- Nan::RemoveGCEpilogueCallback()
- Nan::AddGCPrologueCallback()
- Nan::RemoveGCPrologueCallback()
- Nan::GetHeapStatistics()
- Nan::SetCounterFunction()
- Nan::SetCreateHistogramFunction()
- Nan::SetAddHistogramSampleFunction()
- Nan::IdleNotification()
- Nan::LowMemoryNotification()
- Nan::ContextDisposedNotification()
- Nan::GetInternalFieldPointer()
- Nan::SetInternalFieldPointer()
- Nan::AdjustExternalMemory()
$3
- Nan::Utf8String
- Nan::GetCurrentContext()
- Nan::SetIsolateData()
- Nan::GetIsolateData()
- Nan::TypedArrayContents
$3
- Nan::AsyncResource
- Nan::MakeCallback()
- NAN_MODULE_INIT()
- Nan::Export()
$3
To run the NAN tests do:
` sh
npm install
npm run-script rebuild-tests
npm test
`
Or just:
` sh
npm install
make test
`
Known issues
$3
With new enough compilers available on OSX, the versions of V8 headers corresponding to Node.js 0.12
do not compile anymore. The error looks something like:
`
❯ CXX(target) Release/obj.target/accessors/cpp/accessors.o
In file included from ../cpp/accessors.cpp:9:
In file included from ../../nan.h:51:
In file included from /Users/ofrobots/.node-gyp/0.12.18/include/node/node.h:61:
/Users/ofrobots/.node-gyp/0.12.18/include/node/v8.h:5800:54: error: 'CreateHandle' is a protected member of 'v8::HandleScope'
return Handle(reinterpret_cast(HandleScope::CreateHandle(
~~~~~~~~~~~~~^~~~~~~~~~~~
`
This can be worked around by patching your local versions of v8.h corresponding to Node 0.12 to make
v8::Handle a friend of v8::HandleScope`. Since neither Node.js not V8 support this release line anymore
| Rod Vagg | GitHub/rvagg | Twitter/@rvagg |
|---|---|---|
| Benjamin Byholm | GitHub/kkoopa | - |
| Trevor Norris | GitHub/trevnorris | Twitter/@trevnorris |
| Nathan Rajlich | GitHub/TooTallNate | Twitter/@TooTallNate |
| Brett Lawson | GitHub/brett19 | Twitter/@brett19x |
| Ben Noordhuis | GitHub/bnoordhuis | Twitter/@bnoordhuis |
| David Siegel | GitHub/agnat | Twitter/@agnat |
| Michael Ira Krufky | GitHub/mkrufky | Twitter/@mkrufky |