• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

doc/H04-Aug-2021-3,2162,222

examples/async_pi_estimate/H04-Aug-2021-258131

test/H03-May-2022-4,4183,268

tools/H03-May-2022-3529

.dntrcH A D04-Aug-2021740 3128

.gitignoreH A D04-Aug-202120 22

.npmignoreH A D04-Aug-2021103 1110

.travis.ymlH A D04-Aug-20211.9 KiB4948

CHANGELOG.mdH A D04-Aug-202121.1 KiB542369

LICENSE.mdH A D04-Aug-20211.2 KiB148

MakefileH A D04-Aug-20213.5 KiB118108

README.mdH A D04-Aug-202127.9 KiB457318

appveyor.ymlH A D04-Aug-20211.3 KiB4741

cpplint.pyH A D04-Aug-2021248.4 KiB6,6254,375

nan.hH A D04-Aug-202186.3 KiB2,9052,377

nan_callbacks.hH A D04-Aug-20213 KiB8969

nan_callbacks_12_inl.hH A D04-Aug-202117.1 KiB515437

nan_callbacks_pre_12_inl.hH A D04-Aug-202116.7 KiB521429

nan_converters.hH A D04-Aug-20212.1 KiB7352

nan_converters_43_inl.hH A D04-Aug-20212.7 KiB6951

nan_converters_pre_43_inl.hH A D04-Aug-20211.2 KiB4327

nan_define_own_property_helper.hH A D04-Aug-20211 KiB3017

nan_implementation_12_inl.hH A D04-Aug-202114.7 KiB431324

nan_implementation_pre_12_inl.hH A D04-Aug-20217.8 KiB264169

nan_json.hH A D04-Aug-20215.6 KiB167135

nan_maybe_43_inl.hH A D04-Aug-202112.1 KiB357308

nan_maybe_pre_43_inl.hH A D04-Aug-20217 KiB269215

nan_new.hH A D04-Aug-20218.6 KiB341259

nan_object_wrap.hH A D04-Aug-20214 KiB157101

nan_persistent_12_inl.hH A D04-Aug-20213.8 KiB13399

nan_persistent_pre_12_inl.hH A D04-Aug-20216 KiB243180

nan_private.hH A D04-Aug-20212.4 KiB7459

nan_scriptorigin.hH A D04-Aug-20213 KiB7758

nan_string_bytes.hH A D04-Aug-20217.9 KiB306213

nan_typedarray_contents.hH A D04-Aug-20213 KiB9767

nan_weak.hH A D04-Aug-202115 KiB438405

package.jsonH A D04-Aug-20211.3 KiB3837

README.md

1Native Abstractions for Node.js
2===============================
3
4**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, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 and 16.**
5
6***Current version: 2.15.0***
7
8*(See [CHANGELOG.md](https://github.com/nodejs/nan/blob/master/CHANGELOG.md) for complete ChangeLog)*
9
10[![NPM](https://nodei.co/npm/nan.png?downloads=true&downloadRank=true)](https://nodei.co/npm/nan/) [![NPM](https://nodei.co/npm-dl/nan.png?months=6&height=3)](https://nodei.co/npm/nan/)
11
12[![Build Status](https://api.travis-ci.com/nodejs/nan.svg?branch=master)](https://travis-ci.com/nodejs/nan)
13[![Build status](https://ci.appveyor.com/api/projects/status/kh73pbm9dsju7fgh)](https://ci.appveyor.com/project/RodVagg/nan)
14
15Thanks 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.
16
17This project also contains some helper utilities that make addon development a bit more pleasant.
18
19 * **[News & Updates](#news)**
20 * **[Usage](#usage)**
21 * **[Example](#example)**
22 * **[API](#api)**
23 * **[Tests](#tests)**
24 * **[Known issues](#issues)**
25 * **[Governance & Contributing](#governance)**
26
27<a name="news"></a>
28
29## News & Updates
30
31<a name="usage"></a>
32
33## Usage
34
35Simply add **NAN** as a dependency in the *package.json* of your Node addon:
36
37``` bash
38$ npm install --save nan
39```
40
41Pull in the path to **NAN** in your *binding.gyp* so that you can use `#include <nan.h>` in your *.cpp* files:
42
43``` python
44"include_dirs" : [
45    "<!(node -e \"require('nan')\")"
46]
47```
48
49This works like a `-I<path-to-NAN>` when compiling your addon.
50
51<a name="example"></a>
52
53## Example
54
55Just getting started with Nan? Take a look at the **[Node Add-on Examples](https://github.com/nodejs/node-addon-examples)**.
56
57Refer to a [quick-start **Nan** Boilerplate](https://github.com/fcanas/node-native-boilerplate) for a ready-to-go project that utilizes basic Nan functionality.
58
59For a simpler example, see the **[async pi estimation example](https://github.com/nodejs/nan/tree/master/examples/async_pi_estimate)** 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**.
60
61Yet another example is **[nan-example-eol](https://github.com/CodeCharmLtd/nan-example-eol)**. It shows newline detection implemented as a native addon.
62
63Also take a look at our comprehensive **[C++ test suite](https://github.com/nodejs/nan/tree/master/test/cpp)** which has a plethora of code snippets for your pasting pleasure.
64
65<a name="api"></a>
66
67## API
68
69Additional to the NAN documentation below, please consult:
70
71* [The V8 Getting Started * Guide](https://v8.dev/docs/embed)
72* [V8 API Documentation](https://v8docs.nodesource.com/)
73* [Node Add-on Documentation](https://nodejs.org/api/addons.html)
74
75<!-- START API -->
76
77### JavaScript-accessible methods
78
79A _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](https://github.com/v8/v8/wiki/Embedder%27s-Guide#templates) for further information.
80
81In 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.
82
83* **Method argument types**
84 - <a href="doc/methods.md#api_nan_function_callback_info"><b><code>Nan::FunctionCallbackInfo</code></b></a>
85 - <a href="doc/methods.md#api_nan_property_callback_info"><b><code>Nan::PropertyCallbackInfo</code></b></a>
86 - <a href="doc/methods.md#api_nan_return_value"><b><code>Nan::ReturnValue</code></b></a>
87* **Method declarations**
88 - <a href="doc/methods.md#api_nan_method"><b>Method declaration</b></a>
89 - <a href="doc/methods.md#api_nan_getter"><b>Getter declaration</b></a>
90 - <a href="doc/methods.md#api_nan_setter"><b>Setter declaration</b></a>
91 - <a href="doc/methods.md#api_nan_property_getter"><b>Property getter declaration</b></a>
92 - <a href="doc/methods.md#api_nan_property_setter"><b>Property setter declaration</b></a>
93 - <a href="doc/methods.md#api_nan_property_enumerator"><b>Property enumerator declaration</b></a>
94 - <a href="doc/methods.md#api_nan_property_deleter"><b>Property deleter declaration</b></a>
95 - <a href="doc/methods.md#api_nan_property_query"><b>Property query declaration</b></a>
96 - <a href="doc/methods.md#api_nan_index_getter"><b>Index getter declaration</b></a>
97 - <a href="doc/methods.md#api_nan_index_setter"><b>Index setter declaration</b></a>
98 - <a href="doc/methods.md#api_nan_index_enumerator"><b>Index enumerator declaration</b></a>
99 - <a href="doc/methods.md#api_nan_index_deleter"><b>Index deleter declaration</b></a>
100 - <a href="doc/methods.md#api_nan_index_query"><b>Index query declaration</b></a>
101* Method and template helpers
102 - <a href="doc/methods.md#api_nan_set_method"><b><code>Nan::SetMethod()</code></b></a>
103 - <a href="doc/methods.md#api_nan_set_prototype_method"><b><code>Nan::SetPrototypeMethod()</code></b></a>
104 - <a href="doc/methods.md#api_nan_set_accessor"><b><code>Nan::SetAccessor()</code></b></a>
105 - <a href="doc/methods.md#api_nan_set_named_property_handler"><b><code>Nan::SetNamedPropertyHandler()</code></b></a>
106 - <a href="doc/methods.md#api_nan_set_indexed_property_handler"><b><code>Nan::SetIndexedPropertyHandler()</code></b></a>
107 - <a href="doc/methods.md#api_nan_set_template"><b><code>Nan::SetTemplate()</code></b></a>
108 - <a href="doc/methods.md#api_nan_set_prototype_template"><b><code>Nan::SetPrototypeTemplate()</code></b></a>
109 - <a href="doc/methods.md#api_nan_set_instance_template"><b><code>Nan::SetInstanceTemplate()</code></b></a>
110 - <a href="doc/methods.md#api_nan_set_call_handler"><b><code>Nan::SetCallHandler()</code></b></a>
111 - <a href="doc/methods.md#api_nan_set_call_as_function_handler"><b><code>Nan::SetCallAsFunctionHandler()</code></b></a>
112
113### Scopes
114
115A _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.
116
117A 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.
118
119The 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.
120
121 - <a href="doc/scopes.md#api_nan_handle_scope"><b><code>Nan::HandleScope</code></b></a>
122 - <a href="doc/scopes.md#api_nan_escapable_handle_scope"><b><code>Nan::EscapableHandleScope</code></b></a>
123
124Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://github.com/v8/v8/wiki/Embedder%27s%20Guide#handles-and-garbage-collection).
125
126### Persistent references
127
128An 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.
129
130Due 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.
131
132 - <a href="doc/persistent.md#api_nan_persistent_base"><b><code>Nan::PersistentBase & v8::PersistentBase</code></b></a>
133 - <a href="doc/persistent.md#api_nan_non_copyable_persistent_traits"><b><code>Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits</code></b></a>
134 - <a href="doc/persistent.md#api_nan_copyable_persistent_traits"><b><code>Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits</code></b></a>
135 - <a href="doc/persistent.md#api_nan_persistent"><b><code>Nan::Persistent</code></b></a>
136 - <a href="doc/persistent.md#api_nan_global"><b><code>Nan::Global</code></b></a>
137 - <a href="doc/persistent.md#api_nan_weak_callback_info"><b><code>Nan::WeakCallbackInfo</code></b></a>
138 - <a href="doc/persistent.md#api_nan_weak_callback_type"><b><code>Nan::WeakCallbackType</code></b></a>
139
140Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://developers.google.com/v8/embed#handles).
141
142### New
143
144NAN provides a `Nan::New()` helper for the creation of new JavaScript objects in a way that's compatible across the supported versions of V8.
145
146 - <a href="doc/new.md#api_nan_new"><b><code>Nan::New()</code></b></a>
147 - <a href="doc/new.md#api_nan_undefined"><b><code>Nan::Undefined()</code></b></a>
148 - <a href="doc/new.md#api_nan_null"><b><code>Nan::Null()</code></b></a>
149 - <a href="doc/new.md#api_nan_true"><b><code>Nan::True()</code></b></a>
150 - <a href="doc/new.md#api_nan_false"><b><code>Nan::False()</code></b></a>
151 - <a href="doc/new.md#api_nan_empty_string"><b><code>Nan::EmptyString()</code></b></a>
152
153
154### Converters
155
156NAN contains functions that convert `v8::Value`s 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.
157
158 - <a href="doc/converters.md#api_nan_to"><b><code>Nan::To()</code></b></a>
159
160### Maybe Types
161
162The `Nan::MaybeLocal` and `Nan::Maybe` types are monads that encapsulate `v8::Local` handles that _may be empty_.
163
164* **Maybe Types**
165  - <a href="doc/maybe_types.md#api_nan_maybe_local"><b><code>Nan::MaybeLocal</code></b></a>
166  - <a href="doc/maybe_types.md#api_nan_maybe"><b><code>Nan::Maybe</code></b></a>
167  - <a href="doc/maybe_types.md#api_nan_nothing"><b><code>Nan::Nothing</code></b></a>
168  - <a href="doc/maybe_types.md#api_nan_just"><b><code>Nan::Just</code></b></a>
169* **Maybe Helpers**
170  - <a href="doc/maybe_types.md#api_nan_call"><b><code>Nan::Call()</code></b></a>
171  - <a href="doc/maybe_types.md#api_nan_to_detail_string"><b><code>Nan::ToDetailString()</code></b></a>
172  - <a href="doc/maybe_types.md#api_nan_to_array_index"><b><code>Nan::ToArrayIndex()</code></b></a>
173  - <a href="doc/maybe_types.md#api_nan_equals"><b><code>Nan::Equals()</code></b></a>
174  - <a href="doc/maybe_types.md#api_nan_new_instance"><b><code>Nan::NewInstance()</code></b></a>
175  - <a href="doc/maybe_types.md#api_nan_get_function"><b><code>Nan::GetFunction()</code></b></a>
176  - <a href="doc/maybe_types.md#api_nan_set"><b><code>Nan::Set()</code></b></a>
177  - <a href="doc/maybe_types.md#api_nan_define_own_property"><b><code>Nan::DefineOwnProperty()</code></b></a>
178  - <a href="doc/maybe_types.md#api_nan_force_set"><del><b><code>Nan::ForceSet()</code></b></del></a>
179  - <a href="doc/maybe_types.md#api_nan_get"><b><code>Nan::Get()</code></b></a>
180  - <a href="doc/maybe_types.md#api_nan_get_property_attribute"><b><code>Nan::GetPropertyAttributes()</code></b></a>
181  - <a href="doc/maybe_types.md#api_nan_has"><b><code>Nan::Has()</code></b></a>
182  - <a href="doc/maybe_types.md#api_nan_delete"><b><code>Nan::Delete()</code></b></a>
183  - <a href="doc/maybe_types.md#api_nan_get_property_names"><b><code>Nan::GetPropertyNames()</code></b></a>
184  - <a href="doc/maybe_types.md#api_nan_get_own_property_names"><b><code>Nan::GetOwnPropertyNames()</code></b></a>
185  - <a href="doc/maybe_types.md#api_nan_set_prototype"><b><code>Nan::SetPrototype()</code></b></a>
186  - <a href="doc/maybe_types.md#api_nan_object_proto_to_string"><b><code>Nan::ObjectProtoToString()</code></b></a>
187  - <a href="doc/maybe_types.md#api_nan_has_own_property"><b><code>Nan::HasOwnProperty()</code></b></a>
188  - <a href="doc/maybe_types.md#api_nan_has_real_named_property"><b><code>Nan::HasRealNamedProperty()</code></b></a>
189  - <a href="doc/maybe_types.md#api_nan_has_real_indexed_property"><b><code>Nan::HasRealIndexedProperty()</code></b></a>
190  - <a href="doc/maybe_types.md#api_nan_has_real_named_callback_property"><b><code>Nan::HasRealNamedCallbackProperty()</code></b></a>
191  - <a href="doc/maybe_types.md#api_nan_get_real_named_property_in_prototype_chain"><b><code>Nan::GetRealNamedPropertyInPrototypeChain()</code></b></a>
192  - <a href="doc/maybe_types.md#api_nan_get_real_named_property"><b><code>Nan::GetRealNamedProperty()</code></b></a>
193  - <a href="doc/maybe_types.md#api_nan_call_as_function"><b><code>Nan::CallAsFunction()</code></b></a>
194  - <a href="doc/maybe_types.md#api_nan_call_as_constructor"><b><code>Nan::CallAsConstructor()</code></b></a>
195  - <a href="doc/maybe_types.md#api_nan_get_source_line"><b><code>Nan::GetSourceLine()</code></b></a>
196  - <a href="doc/maybe_types.md#api_nan_get_line_number"><b><code>Nan::GetLineNumber()</code></b></a>
197  - <a href="doc/maybe_types.md#api_nan_get_start_column"><b><code>Nan::GetStartColumn()</code></b></a>
198  - <a href="doc/maybe_types.md#api_nan_get_end_column"><b><code>Nan::GetEndColumn()</code></b></a>
199  - <a href="doc/maybe_types.md#api_nan_clone_element_at"><b><code>Nan::CloneElementAt()</code></b></a>
200  - <a href="doc/maybe_types.md#api_nan_has_private"><b><code>Nan::HasPrivate()</code></b></a>
201  - <a href="doc/maybe_types.md#api_nan_get_private"><b><code>Nan::GetPrivate()</code></b></a>
202  - <a href="doc/maybe_types.md#api_nan_set_private"><b><code>Nan::SetPrivate()</code></b></a>
203  - <a href="doc/maybe_types.md#api_nan_delete_private"><b><code>Nan::DeletePrivate()</code></b></a>
204  - <a href="doc/maybe_types.md#api_nan_make_maybe"><b><code>Nan::MakeMaybe()</code></b></a>
205
206### Script
207
208NAN provides `v8::Script` helpers as the API has changed over the supported versions of V8.
209
210 - <a href="doc/script.md#api_nan_compile_script"><b><code>Nan::CompileScript()</code></b></a>
211 - <a href="doc/script.md#api_nan_run_script"><b><code>Nan::RunScript()</code></b></a>
212 - <a href="doc/script.md#api_nan_script_origin"><b><code>Nan::ScriptOrigin</code></b></a>
213
214
215### JSON
216
217The _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.
218
219 - <a href="doc/json.md#api_nan_json_parse"><b><code>Nan::JSON.Parse</code></b></a>
220 - <a href="doc/json.md#api_nan_json_stringify"><b><code>Nan::JSON.Stringify</code></b></a>
221
222Refer to the V8 JSON object in the [V8 documentation](https://v8docs.nodesource.com/node-8.16/da/d6f/classv8_1_1_j_s_o_n.html) for more information about these methods and their arguments.
223
224### Errors
225
226NAN includes helpers for creating, throwing and catching Errors as much of this functionality varies across the supported versions of V8 and must be abstracted.
227
228Note that an Error object is simply a specialized form of `v8::Value`.
229
230Also consult the V8 Embedders Guide section on [Exceptions](https://developers.google.com/v8/embed#exceptions) for more information.
231
232 - <a href="doc/errors.md#api_nan_error"><b><code>Nan::Error()</code></b></a>
233 - <a href="doc/errors.md#api_nan_range_error"><b><code>Nan::RangeError()</code></b></a>
234 - <a href="doc/errors.md#api_nan_reference_error"><b><code>Nan::ReferenceError()</code></b></a>
235 - <a href="doc/errors.md#api_nan_syntax_error"><b><code>Nan::SyntaxError()</code></b></a>
236 - <a href="doc/errors.md#api_nan_type_error"><b><code>Nan::TypeError()</code></b></a>
237 - <a href="doc/errors.md#api_nan_throw_error"><b><code>Nan::ThrowError()</code></b></a>
238 - <a href="doc/errors.md#api_nan_throw_range_error"><b><code>Nan::ThrowRangeError()</code></b></a>
239 - <a href="doc/errors.md#api_nan_throw_reference_error"><b><code>Nan::ThrowReferenceError()</code></b></a>
240 - <a href="doc/errors.md#api_nan_throw_syntax_error"><b><code>Nan::ThrowSyntaxError()</code></b></a>
241 - <a href="doc/errors.md#api_nan_throw_type_error"><b><code>Nan::ThrowTypeError()</code></b></a>
242 - <a href="doc/errors.md#api_nan_fatal_exception"><b><code>Nan::FatalException()</code></b></a>
243 - <a href="doc/errors.md#api_nan_errno_exception"><b><code>Nan::ErrnoException()</code></b></a>
244 - <a href="doc/errors.md#api_nan_try_catch"><b><code>Nan::TryCatch</code></b></a>
245
246
247### Buffers
248
249NAN's `node::Buffer` helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility.
250
251 - <a href="doc/buffers.md#api_nan_new_buffer"><b><code>Nan::NewBuffer()</code></b></a>
252 - <a href="doc/buffers.md#api_nan_copy_buffer"><b><code>Nan::CopyBuffer()</code></b></a>
253 - <a href="doc/buffers.md#api_nan_free_callback"><b><code>Nan::FreeCallback()</code></b></a>
254
255### Nan::Callback
256
257`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.
258
259 - <a href="doc/callback.md#api_nan_callback"><b><code>Nan::Callback</code></b></a>
260
261### Asynchronous work helpers
262
263`Nan::AsyncWorker`, `Nan::AsyncProgressWorker` and `Nan::AsyncProgressQueueWorker` are helper classes that make working with asynchronous code easier.
264
265 - <a href="doc/asyncworker.md#api_nan_async_worker"><b><code>Nan::AsyncWorker</code></b></a>
266 - <a href="doc/asyncworker.md#api_nan_async_progress_worker"><b><code>Nan::AsyncProgressWorkerBase &amp; Nan::AsyncProgressWorker</code></b></a>
267 - <a href="doc/asyncworker.md#api_nan_async_progress_queue_worker"><b><code>Nan::AsyncProgressQueueWorker</code></b></a>
268 - <a href="doc/asyncworker.md#api_nan_async_queue_worker"><b><code>Nan::AsyncQueueWorker</code></b></a>
269
270### Strings & Bytes
271
272Miscellaneous 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.
273
274 - <a href="doc/string_bytes.md#api_nan_encoding"><b><code>Nan::Encoding</code></b></a>
275 - <a href="doc/string_bytes.md#api_nan_encode"><b><code>Nan::Encode()</code></b></a>
276 - <a href="doc/string_bytes.md#api_nan_decode_bytes"><b><code>Nan::DecodeBytes()</code></b></a>
277 - <a href="doc/string_bytes.md#api_nan_decode_write"><b><code>Nan::DecodeWrite()</code></b></a>
278
279
280### Object Wrappers
281
282The `ObjectWrap` class can be used to make wrapped C++ objects and a factory of wrapped objects.
283
284 - <a href="doc/object_wrappers.md#api_nan_object_wrap"><b><code>Nan::ObjectWrap</code></b></a>
285
286
287### V8 internals
288
289The 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.
290
291 - <a href="doc/v8_internals.md#api_nan_gc_callback"><b><code>NAN_GC_CALLBACK()</code></b></a>
292 - <a href="doc/v8_internals.md#api_nan_add_gc_epilogue_callback"><b><code>Nan::AddGCEpilogueCallback()</code></b></a>
293 - <a href="doc/v8_internals.md#api_nan_remove_gc_epilogue_callback"><b><code>Nan::RemoveGCEpilogueCallback()</code></b></a>
294 - <a href="doc/v8_internals.md#api_nan_add_gc_prologue_callback"><b><code>Nan::AddGCPrologueCallback()</code></b></a>
295 - <a href="doc/v8_internals.md#api_nan_remove_gc_prologue_callback"><b><code>Nan::RemoveGCPrologueCallback()</code></b></a>
296 - <a href="doc/v8_internals.md#api_nan_get_heap_statistics"><b><code>Nan::GetHeapStatistics()</code></b></a>
297 - <a href="doc/v8_internals.md#api_nan_set_counter_function"><b><code>Nan::SetCounterFunction()</code></b></a>
298 - <a href="doc/v8_internals.md#api_nan_set_create_histogram_function"><b><code>Nan::SetCreateHistogramFunction()</code></b></a>
299 - <a href="doc/v8_internals.md#api_nan_set_add_histogram_sample_function"><b><code>Nan::SetAddHistogramSampleFunction()</code></b></a>
300 - <a href="doc/v8_internals.md#api_nan_idle_notification"><b><code>Nan::IdleNotification()</code></b></a>
301 - <a href="doc/v8_internals.md#api_nan_low_memory_notification"><b><code>Nan::LowMemoryNotification()</code></b></a>
302 - <a href="doc/v8_internals.md#api_nan_context_disposed_notification"><b><code>Nan::ContextDisposedNotification()</code></b></a>
303 - <a href="doc/v8_internals.md#api_nan_get_internal_field_pointer"><b><code>Nan::GetInternalFieldPointer()</code></b></a>
304 - <a href="doc/v8_internals.md#api_nan_set_internal_field_pointer"><b><code>Nan::SetInternalFieldPointer()</code></b></a>
305 - <a href="doc/v8_internals.md#api_nan_adjust_external_memory"><b><code>Nan::AdjustExternalMemory()</code></b></a>
306
307
308### Miscellaneous V8 Helpers
309
310 - <a href="doc/v8_misc.md#api_nan_utf8_string"><b><code>Nan::Utf8String</code></b></a>
311 - <a href="doc/v8_misc.md#api_nan_get_current_context"><b><code>Nan::GetCurrentContext()</code></b></a>
312 - <a href="doc/v8_misc.md#api_nan_set_isolate_data"><b><code>Nan::SetIsolateData()</code></b></a>
313 - <a href="doc/v8_misc.md#api_nan_get_isolate_data"><b><code>Nan::GetIsolateData()</code></b></a>
314 - <a href="doc/v8_misc.md#api_nan_typedarray_contents"><b><code>Nan::TypedArrayContents</code></b></a>
315
316
317### Miscellaneous Node Helpers
318
319 - <a href="doc/node_misc.md#api_nan_asyncresource"><b><code>Nan::AsyncResource</code></b></a>
320 - <a href="doc/node_misc.md#api_nan_make_callback"><b><code>Nan::MakeCallback()</code></b></a>
321 - <a href="doc/node_misc.md#api_nan_module_init"><b><code>NAN_MODULE_INIT()</code></b></a>
322 - <a href="doc/node_misc.md#api_nan_export"><b><code>Nan::Export()</code></b></a>
323
324<!-- END API -->
325
326
327<a name="tests"></a>
328
329### Tests
330
331To run the NAN tests do:
332
333``` sh
334npm install
335npm run-script rebuild-tests
336npm test
337```
338
339Or just:
340
341``` sh
342npm install
343make test
344```
345
346<a name="issues"></a>
347
348## Known issues
349
350### Compiling against Node.js 0.12 on OSX
351
352With new enough compilers available on OSX, the versions of V8 headers corresponding to Node.js 0.12
353do not compile anymore. The error looks something like:
354
355```
356❯   CXX(target) Release/obj.target/accessors/cpp/accessors.o
357In file included from ../cpp/accessors.cpp:9:
358In file included from ../../nan.h:51:
359In file included from /Users/ofrobots/.node-gyp/0.12.18/include/node/node.h:61:
360/Users/ofrobots/.node-gyp/0.12.18/include/node/v8.h:5800:54: error: 'CreateHandle' is a protected member of 'v8::HandleScope'
361  return Handle<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
362                                        ~~~~~~~~~~~~~^~~~~~~~~~~~
363```
364
365This can be worked around by patching your local versions of v8.h corresponding to Node 0.12 to make
366`v8::Handle` a friend of `v8::HandleScope`. Since neither Node.js not V8 support this release line anymore
367this patch cannot be released by either project in an official release.
368
369For this reason, we do not test against Node.js 0.12 on OSX in this project's CI. If you need to support
370that configuration, you will need to either get an older compiler, or apply a source patch to the version
371of V8 headers as a workaround.
372
373<a name="governance"></a>
374
375## Governance & Contributing
376
377NAN is governed by the [Node.js Addon API Working Group](https://github.com/nodejs/CTC/blob/master/WORKING_GROUPS.md#addon-api)
378
379### Addon API Working Group (WG)
380
381The NAN project is jointly governed by a Working Group which is responsible for high-level guidance of the project.
382
383Members of the WG are also known as Collaborators, there is no distinction between the two, unlike other Node.js projects.
384
385The WG has final authority over this project including:
386
387* Technical direction
388* Project governance and process (including this policy)
389* Contribution policy
390* GitHub repository hosting
391* Maintaining the list of additional Collaborators
392
393For the current list of WG members, see the project [README.md](./README.md#collaborators).
394
395Individuals 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.
396
397_Note:_ If you make a significant contribution and are not considered for commit-access log an issue or contact a WG member directly.
398
399For the current list of WG members / Collaborators, see the project [README.md](./README.md#collaborators).
400
401### Consensus Seeking Process
402
403The WG follows a [Consensus Seeking](https://en.wikipedia.org/wiki/Consensus-seeking_decision-making) decision making model.
404
405Modifications 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.
406
407If a change proposal cannot reach a consensus, a WG member can call for a vote amongst the members of the WG. Simple majority wins.
408
409<a id="developers-certificate-of-origin"></a>
410
411## Developer's Certificate of Origin 1.1
412
413By making a contribution to this project, I certify that:
414
415* (a) The contribution was created in whole or in part by me and I
416  have the right to submit it under the open source license
417  indicated in the file; or
418
419* (b) The contribution is based upon previous work that, to the best
420  of my knowledge, is covered under an appropriate open source
421  license and I have the right under that license to submit that
422  work with modifications, whether created in whole or in part
423  by me, under the same open source license (unless I am
424  permitted to submit under a different license), as indicated
425  in the file; or
426
427* (c) The contribution was provided directly to me by some other
428  person who certified (a), (b) or (c) and I have not modified
429  it.
430
431* (d) I understand and agree that this project and the contribution
432  are public and that a record of the contribution (including all
433  personal information I submit with it, including my sign-off) is
434  maintained indefinitely and may be redistributed consistent with
435  this project or the open source license(s) involved.
436
437<a name="collaborators"></a>
438
439### WG Members / Collaborators
440
441<table><tbody>
442<tr><th align="left">Rod Vagg</th><td><a href="https://github.com/rvagg">GitHub/rvagg</a></td><td><a href="http://twitter.com/rvagg">Twitter/@rvagg</a></td></tr>
443<tr><th align="left">Benjamin Byholm</th><td><a href="https://github.com/kkoopa/">GitHub/kkoopa</a></td><td>-</td></tr>
444<tr><th align="left">Trevor Norris</th><td><a href="https://github.com/trevnorris">GitHub/trevnorris</a></td><td><a href="http://twitter.com/trevnorris">Twitter/@trevnorris</a></td></tr>
445<tr><th align="left">Nathan Rajlich</th><td><a href="https://github.com/TooTallNate">GitHub/TooTallNate</a></td><td><a href="http://twitter.com/TooTallNate">Twitter/@TooTallNate</a></td></tr>
446<tr><th align="left">Brett Lawson</th><td><a href="https://github.com/brett19">GitHub/brett19</a></td><td><a href="http://twitter.com/brett19x">Twitter/@brett19x</a></td></tr>
447<tr><th align="left">Ben Noordhuis</th><td><a href="https://github.com/bnoordhuis">GitHub/bnoordhuis</a></td><td><a href="http://twitter.com/bnoordhuis">Twitter/@bnoordhuis</a></td></tr>
448<tr><th align="left">David Siegel</th><td><a href="https://github.com/agnat">GitHub/agnat</a></td><td><a href="http://twitter.com/agnat">Twitter/@agnat</a></td></tr>
449<tr><th align="left">Michael Ira Krufky</th><td><a href="https://github.com/mkrufky">GitHub/mkrufky</a></td><td><a href="http://twitter.com/mkrufky">Twitter/@mkrufky</a></td></tr>
450</tbody></table>
451
452## Licence &amp; copyright
453
454Copyright (c) 2018 NAN WG Members / Collaborators (listed above).
455
456Native 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.
457