Native Abstractions for Node.js
C++ JavaScript Python Other
Latest commit a7aac3d Dec 21, 2016 @kkoopa kkoopa 2.5.0
Permalink
Failed to load latest commit information.
doc Rebuild documentation Dec 21, 2016
examples/async_pi_estimate fix formatting of the example js file Jan 30, 2016
test Support Private accessors Dec 21, 2016
tools Update copyright year to 2016 Jan 9, 2016
.dntrc remove 0.8.29 Aug 2, 2014
.gitignore ignore node_modules too Jul 30, 2013
.npmignore Update .npmignore Apr 27, 2016
.travis.yml Test on Node 7 (#623) Nov 3, 2016
CHANGELOG.md Prepare for 2.5.0 Dec 21, 2016
LICENSE.md Update copyright year to 2016 Jan 9, 2016
Makefile Support Private accessors Dec 21, 2016
README.md Prepare for 2.5.0 Dec 21, 2016
appveyor.yml Test on Node 7 (#623) Nov 3, 2016
cpplint.py Update cpplint Jan 17, 2015
include_dirs.js simplify the "include_dirs" binding code Nov 10, 2013
nan.h Prepare for 2.5.0 Dec 21, 2016
nan_callbacks.h Update copyright year to 2016 Jan 9, 2016
nan_callbacks_12_inl.h Update copyright year to 2016 Jan 9, 2016
nan_callbacks_pre_12_inl.h Replace NAN_INLINE with 'inline' keyword. (#577) May 31, 2016
nan_converters.h Replace NAN_INLINE with 'inline' keyword. (#577) May 31, 2016
nan_converters_43_inl.h Update copyright year to 2016 Jan 9, 2016
nan_converters_pre_43_inl.h Update copyright year to 2016 Jan 9, 2016
nan_implementation_12_inl.h Remove V8 deprecation warnings (#568) May 28, 2016
nan_implementation_pre_12_inl.h Update copyright year to 2016 Jan 9, 2016
nan_maybe_43_inl.h Replace NAN_INLINE with 'inline' keyword. (#577) May 31, 2016
nan_maybe_pre_43_inl.h Delint code. Dec 8, 2016
nan_new.h Update copyright year to 2016 Jan 9, 2016
nan_object_wrap.h Make ObjectWrap::handle() const (#574) May 28, 2016
nan_persistent_12_inl.h Delint code. Dec 8, 2016
nan_persistent_pre_12_inl.h Delint code. Dec 8, 2016
nan_private.h Support Private accessors Dec 21, 2016
nan_string_bytes.h Get rid of Handles Jul 31, 2015
nan_typedarray_contents.h abort in delete operators that shouldn't be called (#633) Dec 12, 2016
nan_weak.h Replace NAN_INLINE with 'inline' keyword. (#577) May 31, 2016
package.json 2.5.0 Dec 21, 2016

README.md

Native Abstractions for Node.js

A header file filled with macro and utility goodness for making add-on development for Node.js easier across versions 0.8, 0.10, 0.12, 1, 4, 5, 6 and 7.

Current version: 2.5.0

(See CHANGELOG.md for complete ChangeLog)

NPM NPM

Build Status Build status

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

Simply add NAN as a dependency in the package.json of your Node addon:

$ npm install --save nan

Pull in the path to NAN in your binding.gyp so that you can use #include <nan.h> in your .cpp files:

"include_dirs" : [
    "<!(node -e \"require('nan')\")"
]

This works like a -I<path-to-NAN> 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:

JavaScript-accessible methods

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.

Scopes

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.

Also see the V8 Embedders Guide section on Handles and Garbage Collection.

Persistent references

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.

Also see the V8 Embedders Guide section on Handles and Garbage Collection.

New

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.

Converters

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.

Maybe Types

The Nan::MaybeLocal and Nan::Maybe types are monads that encapsulate v8::Local handles that may be empty.

Script

NAN provides a v8::Script helpers as the API has changed over the supported versions of V8.

Errors

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.

Buffers

NAN's node::Buffer helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility.

Nan::Callback

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.

Asynchronous work helpers

Nan::AsyncWorker and Nan::AsyncProgressWorker are helper classes that make working with asynchronous code easier.

Strings & Bytes

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.

Object Wrappers

The ObjectWrap class can be used to make wrapped C++ objects and a factory of wrapped objects.

V8 internals

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.

Miscellaneous V8 Helpers

Miscellaneous Node Helpers

Tests

To run the NAN tests do:

npm install
npm run-script rebuild-tests
npm test

Or just:

npm install
make test

Governance & Contributing

NAN is governed by the io.js Addon API Working Group

Addon API Working Group (WG)

The NAN project is jointly governed by a Working Group which is responsible for high-level guidance of the project.

Members of the WG are also known as Collaborators, there is no distinction between the two, unlike other io.js projects.

The WG has final authority over this project including:

  • Technical direction
  • Project governance and process (including this policy)
  • Contribution policy
  • GitHub repository hosting
  • Maintaining the list of additional Collaborators

For the current list of WG members, see the project README.md.

Individuals making significant and valuable contributions are made members of the WG and given commit-access to the project. These individuals are identified by the WG and their addition to the WG is discussed via GitHub and requires unanimous consensus amongst those WG members participating in the discussion with a quorum of 50% of WG members required for acceptance of the vote.

Note: If you make a significant contribution and are not considered for commit-access log an issue or contact a WG member directly.

For the current list of WG members / Collaborators, see the project README.md.

Consensus Seeking Process

The WG follows a Consensus Seeking decision making model.

Modifications of the contents of the NAN repository are made on a collaborative basis. Anybody with a GitHub account may propose a modification via pull request and it will be considered by the WG. All pull requests must be reviewed and accepted by a WG member with sufficient expertise who is able to take full responsibility for the change. In the case of pull requests proposed by an existing WG member, an additional WG member is required for sign-off. Consensus should be sought if additional WG members participate and there is disagreement around a particular modification.

If a change proposal cannot reach a consensus, a WG member can call for a vote amongst the members of the WG. Simple majority wins.

Developer's Certificate of Origin 1.1

By making a contribution to this project, I certify that:

  • (a) The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or

  • (b) The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or

  • (c) The contribution was provided directly to me by some other person who certified (a), (b) or (c) and I have not modified it.

  • (d) I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved.

WG Members / Collaborators

Rod VaggGitHub/rvaggTwitter/@rvagg
Benjamin ByholmGitHub/kkoopa-
Trevor NorrisGitHub/trevnorrisTwitter/@trevnorris
Nathan RajlichGitHub/TooTallNateTwitter/@TooTallNate
Brett LawsonGitHub/brett19Twitter/@brett19x
Ben NoordhuisGitHub/bnoordhuisTwitter/@bnoordhuis
David SiegelGitHub/agnatTwitter/@agnat

Licence & copyright

Copyright (c) 2016 NAN WG Members / Collaborators (listed above).

Native Abstractions for Node.js is licensed under an MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.