### Run NAN Tests

Source: https://github.com/nodejs/nan/blob/main/README.md

Instructions for installing dependencies and running the NAN test suite.

```sh
npm install
npm run-script rebuild-tests
npm test
```

```sh
npm install
make test
```

--------------------------------

### Basic Example

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

Demonstrates how to create a custom JavaScript class `MyObject` using `Nan::ObjectWrap` in a Node.js add-on.

```APIDOC
## Basic Example

This example shows how to define a C++ class `MyObject` that inherits from `Nan::ObjectWrap` and expose it to JavaScript.

### C++ Code

```c++
#include <nan.h>

class MyObject : public Nan::ObjectWrap {
 public:
  static NAN_MODULE_INIT(Init) {
    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
    tpl->SetClassName(Nan::New("MyObject").ToLocalChecked());
    tpl->InstanceTemplate()->SetInternalFieldCount(1);

    Nan::SetPrototypeMethod(tpl, "getHandle", GetHandle);
    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);

    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
    Nan::Set(target, Nan::New("MyObject").ToLocalChecked(),
      Nan::GetFunction(tpl).ToLocalChecked());
  }

 private:
  explicit MyObject(double value = 0) : value_(value) {}
  ~MyObject() {}

  static NAN_METHOD(New) {
    if (info.IsConstructCall()) {
      double value = info[0]->IsUndefined() ? 0 : Nan::To<double>(info[0]).FromJust();
      MyObject *obj = new MyObject(value);
      obj->Wrap(info.This());
      info.GetReturnValue().Set(info.This());
    } else {
      const int argc = 1;
      v8::Local<v8::Value> argv[argc] = {info[0]};
      v8::Local<v8::Function> cons = Nan::New(constructor());
      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
    }
  }

  static NAN_METHOD(GetHandle) {
    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
    info.GetReturnValue().Set(obj->handle());
  }

  static NAN_METHOD(GetValue) {
    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
    info.GetReturnValue().Set(obj->value_);
  }

  static inline Nan::Persistent<v8::Function> & constructor() {
    static Nan::Persistent<v8::Function> my_constructor;
    return my_constructor;
  }

  double value_;
};

NODE_MODULE(objectwrapper, MyObject::Init)
```

### JavaScript Usage

```javascript
var objectwrapper = require('bindings')('objectwrapper');

var obj = new objectwrapper.MyObject(5);
console.log('Should be 5: ' + obj.getValue());
```
```

--------------------------------

### Basic Nan::ObjectWrap Example

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

Demonstrates how to create a custom C++ class `MyObject` that inherits from Nan::ObjectWrap. This example shows initialization, wrapping, and unwrapping for JavaScript interaction.

```c++
class MyObject : public Nan::ObjectWrap {
 public:
  static NAN_MODULE_INIT(Init) {
    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
    tpl->SetClassName(Nan::New("MyObject").ToLocalChecked());
    tpl->InstanceTemplate()->SetInternalFieldCount(1);

    Nan::SetPrototypeMethod(tpl, "getHandle", GetHandle);
    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);

    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
    Nan::Set(target, Nan::New("MyObject").ToLocalChecked(),
      Nan::GetFunction(tpl).ToLocalChecked());
  }

 private:
  explicit MyObject(double value = 0) : value_(value) {}
  ~MyObject() {}

  static NAN_METHOD(New) {
    if (info.IsConstructCall()) {
      double value = info[0]->IsUndefined() ? 0 : Nan::To<double>(info[0]).FromJust();
      MyObject *obj = new MyObject(value);
      obj->Wrap(info.This());
      info.GetReturnValue().Set(info.This());
    } else {
      const int argc = 1;
      v8::Local<v8::Value> argv[argc] = {info[0]};
      v8::Local<v8::Function> cons = Nan::New(constructor());
      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
    }
  }

  static NAN_METHOD(GetHandle) {
    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
    info.GetReturnValue().Set(obj->handle());
  }

  static NAN_METHOD(GetValue) {
    MyObject* obj = Nan::ObjectWrap::Unwrap<MyObject>(info.Holder());
    info.GetReturnValue().Set(obj->value_);
  }

  static inline Nan::Persistent<v8::Function> & constructor() {
    static Nan::Persistent<v8::Function> my_constructor;
    return my_constructor;
  }

  double value_;
};

NODE_MODULE(objectwrapper, MyObject::Init)

```

```javascript
var objectwrapper = require('bindings')('objectwrapper');

var obj = new objectwrapper.MyObject(5);
console.log('Should be 5: ' + obj.getValue());

```

--------------------------------

### Getter Declaration Example

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Provides an example of declaring a getter function with the correct signature for use with Node-API.

```c++
void GetterName(v8::Local<v8::String> property,
                const Nan::PropertyCallbackInfo<v8::Value>& info) {
  ...
}
```

--------------------------------

### Install NAN Package

Source: https://github.com/nodejs/nan/blob/main/README.md

Add NAN as a dependency using a package manager like npm, yarn, or bun.

```bash
$ npm install nan
```

--------------------------------

### Method Declaration Example

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Illustrates how to declare static methods within a class inheriting from Nan::ObjectWrap, intended for JavaScript exposure.

```c++
// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static void Bar(const Nan::FunctionCallbackInfo<v8::Value>& info);
  static void Baz(const Nan::FunctionCallbackInfo<v8::Value>& info);
}


// .cc:
void Foo::Bar(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}

void Foo::Baz(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}
```

--------------------------------

### Nan::ReturnValue Example Usage

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Demonstrates setting a return value using Nan::ReturnValue in a function callback. Ensure a HandleScope is active when calling this.

```c++
void EmptyArray(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  info.GetReturnValue().Set(Nan::New<v8::Array>());
}
```

--------------------------------

### Weak Callback Implementation

Source: https://github.com/nodejs/nan/blob/main/doc/persistent.md

Example of implementing a weak callback function to free associated memory.

```c++
void weakCallback(const WeakCallbackInfo<int> &data) {
  int *parameter = data.GetParameter();
  delete parameter;
}
```

--------------------------------

### Get Start Column of V8 Message

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

Use Nan::GetStartColumn to safely retrieve the starting column of a V8 message. This helper ensures compatibility with various V8 versions.

```c++
Nan::Maybe<int> Nan::GetStartColumn(v8::Local<v8::Message> msg);
```

--------------------------------

### Nan::Get

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling v8::Object#Get() in a way compatible across supported versions of V8.

```APIDOC
## Nan::Get()

### Description
A helper method for calling [`v8::Object#Get()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a2565f03e736694f6b1e1cf22a0b4eac2) in a way compatible across supported versions of V8.

### Signature

```cpp
Nan::MaybeLocal<v8::Value> Nan::Get(v8::Local<v8::Object> obj,
                                    v8::Local<v8::Value> key);
Nan::MaybeLocal<v8::Value> Nan::Get(v8::Local<v8::Object> obj, uint32_t index);
```
```

--------------------------------

### Node.js 0.12 OSX Compilation Error Example

Source: https://github.com/nodejs/nan/blob/main/README.md

This C++ compilation error occurs when building Node.js addons against Node.js 0.12 on OSX with newer compilers. It indicates an issue with v8 headers and the 'CreateHandle' member of 'v8::HandleScope'. A workaround involves patching v8.h.

```cpp
❯   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<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
                                        ~~~~~~~~~~~~~^~~~~~~~~~~~
```

--------------------------------

### Basic Nan::Callback Usage

Source: https://github.com/nodejs/nan/blob/main/doc/callback.md

Demonstrates the basic instantiation and invocation of a Nan::Callback. Ensure the v8::Local<v8::Function> is valid before creating the callback.

```c++
v8::Local<v8::Function> function;
Nan::Callback callback(function);
callback.Call(0, 0);
```

--------------------------------

### Setting a Weak Persistent Reference

Source: https://github.com/nodejs/nan/blob/main/doc/persistent.md

Demonstrates how to set a weak persistent reference with a parameter for the callback.

```c++
Persistent<v8::Object> obj;
int *data = new int(0);
obj.SetWeak(data, callback, WeakCallbackType::kParameter);
```

--------------------------------

### Nan::GetIsolateData()

Source: https://github.com/nodejs/nan/blob/main/doc/v8_misc.md

Retrieves data associated with a V8 isolate. This function offers a consistent way to get isolate-specific data.

```APIDOC
## Nan::GetIsolateData()

### Description
A helper to provide a consistent API to `v8::Isolate#GetData()`.

### Signature
```c++
T *Nan::GetIsolateData(v8::Isolate *isolate)
```
```

--------------------------------

### Nan::NewInstance()

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling `v8::Function#NewInstance()` and `v8::ObjectTemplate#NewInstance()` in a way compatible across supported versions of V8.

```APIDOC
## Nan::NewInstance()

### Description
A helper method for calling [`v8::Function#NewInstance()`](https://v8docs.nodesource.com/node-8.16/d5/d54/classv8_1_1_function.html#ae477558b10c14b76ed00e8dbab44ce5b) and [`v8::ObjectTemplate#NewInstance()`](https://v8docs.nodesource.com/node-8.16/db/d5f/classv8_1_1_object_template.html#ad605a7543cfbc5dab54cdb0883d14ae4) in a way compatible across supported versions of V8.

### Signatures
```c++
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h, int argc, v8::Local<v8::Value> argv[]);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::ObjectTemplate> h);
```
```

--------------------------------

### Javascript Usage of Factory Object

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

Demonstrates how to require and instantiate the C++ factory object from Javascript, and call its methods.

```javascript
var wrappedobjectfactory = require('bindings')('wrappedobjectfactory');

var obj = wrappedobjectfactory.newFactoryObjectInstance(10);
console.log('Should be 10: ' + obj.getValue());
```

--------------------------------

### NAN_MODULE_INIT

Source: https://github.com/nodejs/nan/blob/main/doc/node_misc.md

Defines the entry point function for a Node.js add-on. It creates a function named `name` that accepts a `target` object, which is equivalent to the JavaScript `exports` object.

```APIDOC
## NAN_MODULE_INIT()

### Description
Used to define the entry point function to a Node add-on. Creates a function with a given `name` that receives a `target` object representing the equivalent of the JavaScript `exports` object.

### Example
```c++
NAN_MODULE_INIT(Init) {
  NAN_EXPORT(target, Foo);
}
```
```

--------------------------------

### Get External Value

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Reads the pointer stored within a v8::External object. It applies a default tag for compatibility with different V8 versions.

```c++
void* Nan::GetExternalValue(v8::Local<v8::External> ext)
```

--------------------------------

### Javascript Usage for Summing Wrapped Objects

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

Shows how to use the `sum` function exported from the C++ addon, passing it instances of the wrapped objects created previously.

```javascript
var myaddon = require('bindings')('myaddon');

var obj1 = myaddon.newFactoryObjectInstance(5);
var obj2 = myaddon.newFactoryObjectInstance(10);
console.log('sum of object values: ' + myaddon.sum(obj1, obj2));
```

--------------------------------

### Get Internal Field Pointer

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Retrieves a pointer to an internal field of a V8 object. The specific V8 API used depends on the V8 version.

```c++
void* Nan::GetInternalFieldPointer(v8::Local<v8::Object> object, int index)
```

--------------------------------

### Get Heap Statistics

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Retrieve V8's heap statistics into a provided v8::HeapStatistics object. This function wraps V8's GetHeapStatistics.

```c++
void Nan::GetHeapStatistics(v8::HeapStatistics *heap_statistics)
```

--------------------------------

### Factory of wrapped objects

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

This section demonstrates how to create a factory for wrapped C++ objects that can be instantiated and used in JavaScript.

```APIDOC
## Factory Object Creation

### Description
This section details the C++ implementation for creating a factory that produces wrapped objects. These objects can be initialized with a value and have a method to retrieve that value.

### Method Signature
`static NAN_MODULE_INIT(Init)`

### Usage in JavaScript
```javascript
var wrappedobjectfactory = require('bindings')('wrappedobjectfactory');

var obj = wrappedobjectfactory.newFactoryObjectInstance(10);
console.log('Should be 10: ' + obj.getValue());
```

### C++ Implementation Details
- `MyFactoryObject::Init`: Initializes the V8 FunctionTemplate for the object.
- `MyFactoryObject::NewInstance`: A static method to create a new instance of `MyFactoryObject`.
- `MyFactoryObject::New`: The constructor for `MyFactoryObject`, handling both direct construction and `new` calls.
- `MyFactoryObject::GetValue`: A method exposed to JavaScript to get the internal value of the object.
- `NODE_MODULE`: Exports the addon with the name 'wrappedobjectfactory'.
```

--------------------------------

### Define Node Add-on Entry Point with NAN_MODULE_INIT

Source: https://github.com/nodejs/nan/blob/main/doc/node_misc.md

Use NAN_MODULE_INIT to define the main entry point function for a Node.js add-on. It creates a function that receives a `target` object, similar to JavaScript's `module.exports`.

```c++
NAN_MODULE_INIT(Init) {
  NAN_EXPORT(target, Foo);
}
```

--------------------------------

### Nan::GetCurrentContext()

Source: https://github.com/nodejs/nan/blob/main/doc/v8_misc.md

Retrieves the current V8 context. This function provides a consistent way to get the current context across different V8 versions.

```APIDOC
## Nan::GetCurrentContext()

### Description
A call to `v8::Isolate::GetCurrent()->GetCurrentContext()` that works across all supported versions of V8.

### Signature
```c++
v8::Local<v8::Context> Nan::GetCurrentContext()
```
```

--------------------------------

### Script Helpers

Source: https://github.com/nodejs/nan/blob/main/README.md

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

```APIDOC
## Script Helpers

### `Nan::CompileScript(Local<String> source)`

Compiles a JavaScript string into a script.

### `Nan::RunScript(Local<Script> script)`

Runs a compiled JavaScript script.

### `Nan::ScriptOrigin`

A structure representing the origin of a script.
```

--------------------------------

### Get End Column of V8 Message

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

Use Nan::GetEndColumn to safely retrieve the ending column of a V8 message. This helper ensures compatibility with various V8 versions.

```c++
Nan::Maybe<int> Nan::GetEndColumn(v8::Local<v8::Message> msg);
```

--------------------------------

### Nan::GetCurrentContext() Function

Source: https://github.com/nodejs/nan/blob/main/doc/v8_misc.md

Provides a consistent way to get the current V8 context across different V8 versions. This is a wrapper around v8::Isolate::GetCurrent()->GetCurrentContext().

```c++
v8::Local<v8::Context> Nan::GetCurrentContext()
```

--------------------------------

### 1to2 Script Usage

Source: https://github.com/nodejs/nan/blob/main/tools/README.md

This script naively converts NAN 1 source code files to NAN 2. It rewrites files in place, so backups are recommended. Manual review and touch-ups are required after conversion.

```sh
$ tools/1to2.js

  Usage: 1to2 [options] <file ...>

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
```

--------------------------------

### Nan::GetStartColumn

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling `v8::Message#GetStartColumn()` in a way compatible across supported versions of V8.

```APIDOC
## Nan::GetStartColumn()

### Description
A helper method for calling `v8::Message#GetStartColumn()` in a way compatible across supported versions of V8.

### Signature
```cpp
Nan::Maybe<int> Nan::GetStartColumn(v8::Local<v8::Message> msg);
```
```

--------------------------------

### Get Local Reference from Persistent

Source: https://github.com/nodejs/nan/blob/main/doc/persistent.md

Use Nan::New to obtain a v8::Local reference from a PersistentBase or Persistent object. This is useful when you need to interact with the object within a HandleScope.

```c++
v8::Local<v8::Object> object = Nan::New(persistent);
```

--------------------------------

### Reference V8 Undefined with Nan::Undefined()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Get a reference to the V8 undefined primitive value using Nan::Undefined(). This helper ensures compatibility across different V8 versions.

```c++
v8::Local<v8::Primitive> Nan::Undefined()
```

--------------------------------

### Nan::MakeCallback Signatures (Deprecated)

Source: https://github.com/nodejs/nan/blob/main/doc/node_misc.md

Shows the deprecated signatures for Nan::MakeCallback, which are wrappers around legacy Node.js APIs. Use Nan::AsyncResource::runInAsyncScope instead for proper async context preservation.

```c++
NAN_DEPRECATED
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::Function> func,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
NAN_DEPRECATED
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       v8::Local<v8::String> symbol,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
NAN_DEPRECATED
v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
                                       const char* method,
                                       int argc,
                                       v8::Local<v8::Value>* argv);
```

--------------------------------

### Get Private Property from V8 Object

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

Use Nan::GetPrivate to safely retrieve the value of a private property from a V8 object using a specific key. This method ensures compatibility with various V8 versions.

```c++
Nan::MaybeLocal<v8::Value> Nan::GetPrivate(v8::Local<v8::Object> object, v8::Local<v8::String> key);
```

--------------------------------

### Set Add Histogram Sample Function

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Sets the callback function for V8's histogram sample functionality. This is used for performance profiling.

```c++
void Nan::SetAddHistogramSampleFunction(v8::AddHistogramSampleCallback cb)
```

--------------------------------

### Declare GC Callbacks with NAN_GC_CALLBACK

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Use NAN_GC_CALLBACK to define functions that will be invoked during V8 garbage collection. These callbacks receive GC type and flags. The example shows how to set up a persistent function and add a prologue callback.

```c++
static Nan::Persistent<Function> callback;

NAN_GC_CALLBACK(gcPrologueCallback) {
  v8::Local<Value> argv[] = { Nan::New("prologue").ToLocalChecked() };
  Nan::MakeCallback(Nan::GetCurrentContext()->Global(), Nan::New(callback), 1, argv);
}

NAN_METHOD(Hook) {
  callback.Reset(To<Function>(args[0]).ToLocalChecked());
  Nan::AddGCPrologueCallback(gcPrologueCallback);
  info.GetReturnValue().Set(info.Holder());
}
```

--------------------------------

### Declare Index Query Callback

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

JavaScript-accessible index query methods should be declared with this signature to form a Nan::IndexQueryCallback. A HandleScope is implicitly created.

```c++
typedef void(*IndexQueryCallback)(uint32_t,
                                  const PropertyCallbackInfo<v8::Integer>&);
```

```c++
void IndexQueryName(uint32_t index, const PropertyCallbackInfo<v8::Integer>& info);
```

--------------------------------

### Set Named Property Handler with Nan::SetNamedPropertyHandler

Source: https://github.com/nodejs/nan/blob/main/README.md

Use Nan::SetNamedPropertyHandler to define handlers for all named property access (get, set, etc.) on an object. This provides a way to intercept and manage property access dynamically.

```cpp
Nan::SetNamedPropertyHandler(tpl->InstanceTemplate(), NamedPropertyGetter, NamedPropertySetter, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr);

```

--------------------------------

### Nan::NewInstance Variants

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

Helper methods for calling v8::Function#NewInstance() and v8::ObjectTemplate#NewInstance() compatibly across V8 versions.

```c++
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::Function> h, int argc, v8::Local<v8::Value> argv[]);
Nan::MaybeLocal<v8::Object> Nan::NewInstance(v8::Local<v8::ObjectTemplate> h);
```

--------------------------------

### Set JavaScript Accessor with Nan::SetAccessor

Source: https://github.com/nodejs/nan/blob/main/README.md

Use Nan::SetAccessor to define getters and setters for JavaScript properties backed by C++ functions. This allows JavaScript to get and set properties on objects using native code.

```cpp
Nan::SetAccessor(tpl->InstanceTemplate(), "myProperty", MyGetter, MySetter);

```

--------------------------------

### Declare Property Query Callback

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

JavaScript-accessible property query methods should be declared with this signature to form a Nan::PropertyQueryCallback. A HandleScope is implicitly created.

```c++
typedef void(*PropertyQueryCallback)(v8::Local<v8::String>,
                                     const PropertyCallbackInfo<v8::Integer>&);
```

```c++
void PropertyQueryName(v8::Local<v8::String> property,
                       const Nan::PropertyCallbackInfo<v8::Integer>& info);
```

--------------------------------

### Reference V8 False Boolean with Nan::False()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Get a reference to the V8 boolean false value using Nan::False(). This function ensures consistent access to the false boolean primitive across V8 versions.

```c++
v8::Local<v8::Boolean> Nan::False()
```

--------------------------------

### Method Definition Substitution

Source: https://github.com/nodejs/nan/wiki/Semi-automatic-porting-of-existing-code

Replaces V8 Handle and Arguments with NAN_METHOD for method definitions. Ensures correct parameter handling.

```regex
(v8\:\:)?Handle<(v8\:\:)?Value>\s*(\S+)\s*\(\s*const\s+(v8\:\:)?Arguments\s*&\s*args\s*)
NAN_METHOD(\3)
```

--------------------------------

### Nan::New()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Helper for creating new JavaScript objects compatible across V8 versions. Refer to V8 documentation for specific argument types.

```APIDOC
## Nan::New()

### Description
Helper for creating new JavaScript objects compatible across V8 versions. Refer to V8 documentation for specific argument types.

### Signatures

Empty objects:
```c++
Nan::New<T>();
```

Generic single and multiple-argument:
```c++
Nan::New<T>(A0 arg0);
Nan::New<T>(A0 arg0, A1 arg1);
Nan::New<T>(A0 arg0, A1 arg1, A2 arg2);
Nan::New<T>(A0 arg0, A1 arg1, A2 arg2, A3 arg3);
```

For creating `v8::FunctionTemplate` and `v8::Function` objects:
```c++
Nan::New<T>(Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>());
Nan::New<T>(Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>(), A2 a2 = A2());
```

Native number types:
```c++
v8::Local<v8::Boolean> Nan::New<T>(bool value);
v8::Local<v8::Int32> Nan::New<T>(int32_t value);
v8::Local<v8::Uint32> Nan::New<T>(uint32_t value);
v8::Local<v8::Number> Nan::New<T>(double value);
```

String types:
```c++
Nan::MaybeLocal<v8::String> Nan::New<T>(std::string const& value);
Nan::MaybeLocal<v8::String> Nan::New<T>(const char * value, int length);
Nan::MaybeLocal<v8::String> Nan::New<T>(const char * value);
Nan::MaybeLocal<v8::String> Nan::New<T>(const uint16_t * value);
Nan::MaybeLocal<v8::String> Nan::New<T>(const uint16_t * value, int length);
```

Specialized types:
```c++
v8::Local<v8::String> Nan::New<T>(v8::String::ExternalStringResource * value);
v8::Local<v8::String> Nan::New<T>(Nan::ExternalOneByteStringResource * value);
v8::Local<v8::RegExp> Nan::New<T>(v8::Local<v8::String> pattern, v8::RegExp::Flags flags);
```
```

--------------------------------

### Nan::GetOwnPropertyNames

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling v8::Object#GetOwnPropertyNames() in a way compatible across supported versions of V8.

```APIDOC
## Nan::GetOwnPropertyNames()

### Description
A helper method for calling [`v8::Object#GetOwnPropertyNames()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a79a6e4d66049b9aa648ed4dfdb23e6eb) in a way compatible across supported versions of V8.

### Signature

```cpp
Nan::MaybeLocal<v8::Array> Nan::GetOwnPropertyNames(v8::Local<v8::Object> obj);
```
```

--------------------------------

### Local New Substitution

Source: https://github.com/nodejs/nan/wiki/Semi-automatic-porting-of-existing-code

Replaces V8 Local::New with NanNew for creating local handles. This is a general substitution for creating local V8 objects.

```regex
(v8\:\:)?Local\s*<\s*(\S*)>\s*::\s*New\s*
NanNew<\2>(
```

--------------------------------

### Nan::TryCatch

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

A RAII wrapper for V8's `TryCatch` mechanism, simplifying exception handling.

```APIDOC
## Nan::TryCatch

### Description
`Nan::TryCatch` is a C++ class that acts as a RAII (Resource Acquisition Is Initialization) wrapper around V8's `v8::TryCatch` class. It simplifies the process of catching and handling JavaScript exceptions thrown within a specific scope.

### Usage
```c++
Nan::TryCatch try_catch;

// Code that might throw an exception
// ...

if (try_catch.HasCaught()) {
  // Handle the exception
  // v8::Local<v8::Value> exception = try_catch.Exception();
  // ...
}
```
```

--------------------------------

### Create a new SyntaxError object with Nan::SyntaxError()

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

Use this to create a SyntaxError object. It accepts a C-style string or a v8::Local<v8::String> as input.

```c++
v8::Local<v8::Value> Nan::SyntaxError(const char *msg);
v8::Local<v8::Value> Nan::SyntaxError(v8::Local<v8::String> msg);
```

--------------------------------

### Method Declaration (Nan::FunctionCallback)

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Defines the signature for JavaScript-accessible methods in C++.

```APIDOC
## Method declaration

### Description
JavaScript-accessible methods should be declared with the following signature to form a `Nan::FunctionCallback`:

### Signature
```c++
typedef void(*FunctionCallback)(const FunctionCallbackInfo<v8::Value>&);
```

### Example
```c++
void MethodName(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  // ...
}
```

You do not need to declare a new `HandleScope` within a method as one is implicitly created for you.

#### Example usage
```c++
// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static void Bar(const Nan::FunctionCallbackInfo<v8::Value>& info);
  static void Baz(const Nan::FunctionCallbackInfo<v8::Value>& info);
}


// .cc:
void Foo::Bar(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}

void Foo::Baz(const Nan::FunctionCallbackInfo<v8::Value>& info) {
  ...
}
```

A helper macro `NAN_METHOD(methodname)` exists, compatible with NAN v1 method declarations.

#### Example usage with `NAN_METHOD(methodname)`
```c++
// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static NAN_METHOD(Bar);
  static NAN_METHOD(Baz);
}


// .cc:
NAN_METHOD(Foo::Bar) {
  ...
}

NAN_METHOD(Foo::Baz) {
  ...
}
```

Use [`Nan::SetPrototypeMethod`](#api_nan_set_prototype_method) to attach a method to a JavaScript function prototype or [`Nan::SetMethod`](#api_nan_set_method) to attach a method directly on a JavaScript object.
```

--------------------------------

### Buffers API

Source: https://github.com/nodejs/nan/blob/main/README.md

Helpers for Node.js Buffers, ensuring compatibility across Node versions.

```APIDOC
## Nan::NewBuffer()

### Description
Creates a new Node.js Buffer.

### Method
`Nan::NewBuffer()`

### Endpoint
N/A (C++ API)
```

```APIDOC
## Nan::CopyBuffer()

### Description
Copies data into a Node.js Buffer.

### Method
`Nan::CopyBuffer()`

### Endpoint
N/A (C++ API)
```

```APIDOC
## Nan::FreeCallback()

### Description
Callback for freeing buffer memory.

### Method
`Nan::FreeCallback()`

### Endpoint
N/A (C++ API)
```

--------------------------------

### Create JavaScript Object with Arguments using Nan::New()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Instantiate new JavaScript objects with one or more arguments using Nan::New<T>(). The types and number of arguments depend on the specific V8 object type T being created.

```c++
Nan::New<T>(A0 arg0);
Nan::New<T>(A0 arg0, A1 arg1);
Nan::New<T>(A0 arg0, A1 arg1, A2 arg2);
Nan::New<T>(A0 arg0, A1 arg1, A2 arg2, A3 arg3);
```

--------------------------------

### JSON API

Source: https://github.com/nodejs/nan/blob/main/README.md

Provides C++ versions of JavaScript's JSON methods, exposed via v8::JSON.

```APIDOC
## Nan::JSON.Parse

### Description
Parses a JSON string.

### Method
`Nan::JSON.Parse`

### Endpoint
N/A (C++ API)

### Parameters
Refer to V8 documentation for arguments.
```

```APIDOC
## Nan::JSON.Stringify

### Description
Converts a JavaScript value to a JSON string.

### Method
`Nan::JSON.Stringify`

### Endpoint
N/A (C++ API)

### Parameters
Refer to V8 documentation for arguments.
```

--------------------------------

### Add GC Prologue Callback

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Register a callback function to be executed before a garbage collection event. This function wraps V8's AddGCPrologueCallback.

```c++
void Nan::AddGCPrologueCallback(v8::Isolate::GCPrologueCallback, v8::GCType gc_type_filter callback)
```

--------------------------------

### Include NAN Path in binding.gyp

Source: https://github.com/nodejs/nan/blob/main/README.md

Pull in the path to NAN in your binding.gyp file to use #include <nan.h> in your .cpp files. This functions as a -I<path-to-NAN> flag during compilation.

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

--------------------------------

### Convert v8::Value to String or Double

Source: https://github.com/nodejs/nan/blob/main/doc/converters.md

Demonstrates converting a v8::Local<v8::Value> to a Nan::MaybeLocal<v8::String> and a Nan::Maybe<double>. Use these converters when the type conversion is not guaranteed to succeed.

```c++
v8::Local<v8::Value> val;
Nan::MaybeLocal<v8::String> str = Nan::To<v8::String>(val);
Nan::Maybe<double> d = Nan::To<double>(val);
```

--------------------------------

### NAN_METHOD Macro Usage

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Shows the usage of the NAN_METHOD macro for declaring methods, compatible with older NAN v1 declarations. This simplifies method definition syntax.

```c++
// .h:
class Foo : public Nan::ObjectWrap {
  ...

  static NAN_METHOD(Bar);
  static NAN_METHOD(Baz);
}


// .cc:
NAN_METHOD(Foo::Bar) {
  ...
}

NAN_METHOD(Foo::Baz) {
  ...
}
```

--------------------------------

### Create One-Byte String with Nan::NewOneByteString()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Implement v8::String::NewFromOneByte() for consistent availability across V8 versions. This function allocates a new string from Latin-1 encoded data.

```c++
Nan::MaybeLocal<v8::String> Nan::NewOneByteString(const uint8_t * value,
                                                  int length = -1)
```

--------------------------------

### Nan::PropertyCallbackInfo

Source: https://github.com/nodejs/nan/blob/main/doc/methods.md

Represents callback information for property accessors, used in place of v8::PropertyCallbackInfo.

```APIDOC
## Nan::PropertyCallbackInfo

### Description
`Nan::PropertyCallbackInfo` should be used in place of `v8::PropertyCallbackInfo`, even with older versions of Node where `v8::PropertyCallbackInfo` does not exist.

### Definition
```c++
template<typename T>
class PropertyCallbackInfo : public PropertyCallbackInfoBase<T> {
 public:
  ReturnValue<T> GetReturnValue() const;
  v8::Isolate* GetIsolate() const;
  v8::Local<v8::Value> Data() const;
  v8::Local<v8::Object> This() const;
  v8::Local<v8::Object> Holder() const;
};
```

See the [`v8::PropertyCallbackInfo`](https://v8docs.nodesource.com/node-8.16/d7/dc5/classv8_1_1_property_callback_info.html) documentation for usage details on these. See [`Nan::ReturnValue`](#api_nan_return_value) for further information on how to set a return value from property accessor methods.
```

--------------------------------

### Callback API

Source: https://github.com/nodejs/nan/blob/main/README.md

`Nan::Callback` wraps `v8::Function` handles for safe use as callbacks, especially across asynchronous operations.

```APIDOC
## Nan::Callback

### Description
A class that wraps a `v8::Function` handle, protecting it from garbage collection and enabling its use across asynchronous execution.

### Method
`Nan::Callback`

### Endpoint
N/A (C++ API)
```

--------------------------------

### Nan::NewOneByteString()

Source: https://github.com/nodejs/nan/blob/main/doc/new.md

Allocates a new string from Latin-1 data, provided for consistent availability across V8 versions.

```APIDOC
## Nan::NewOneByteString()

### Description
Allocates a new string from Latin-1 data, provided for consistent availability across V8 versions.

### Signature
```c++
Nan::MaybeLocal<v8::String> Nan::NewOneByteString(const uint8_t * value, int length = -1)
```
```

--------------------------------

### Handle Nan::FatalException

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

Replaces node::FatalException for use with Nan::TryCatch. Ensures compatibility across Node.js versions.

```c++
void Nan::FatalException(const Nan::TryCatch& try_catch);
```

--------------------------------

### Nan::ObjectProtoToString

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling v8::Object#ObjectProtoToString() in a way compatible across supported versions of V8.

```APIDOC
## Nan::ObjectProtoToString()

### Description
A helper method for calling [`v8::Object#ObjectProtoToString()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ab7a92b4dcf822bef72f6c0ac6fea1f0b) in a way compatible across supported versions of V8.

### Signature

```cpp
Nan::MaybeLocal<v8::String> Nan::ObjectProtoToString(v8::Local<v8::Object> obj);
```
```

--------------------------------

### Nan::GetPropertyAttributes

Source: https://github.com/nodejs/nan/blob/main/doc/maybe_types.md

A helper method for calling v8::Object#GetPropertyAttributes() in a way compatible across supported versions of V8.

```APIDOC
## Nan::GetPropertyAttributes()

### Description
A helper method for calling [`v8::Object#GetPropertyAttributes()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a9b898894da3d1db2714fd9325a54fe57) in a way compatible across supported versions of V8.

### Signature

```cpp
Nan::Maybe<v8::PropertyAttribute> Nan::GetPropertyAttributes(
    v8::Local<v8::Object> obj,
    v8::Local<v8::Value> key);
```
```

--------------------------------

### HandleScope Substitution

Source: https://github.com/nodejs/nan/wiki/Semi-automatic-porting-of-existing-code

Replaces V8 HandleScope with NanScope for managing V8 handles. This is a direct substitution.

```regex
(v8\:\:)?HandleScope\s+scope
NanScope()
```

--------------------------------

### Nan::TryCatch Class

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

A wrapper for v8::TryCatch, providing a compatible interface across V8 versions. Use for catching exceptions within C++ addons.

```c++
class Nan::TryCatch {
 public:
  Nan::TryCatch();

  bool HasCaught() const;

  bool CanContinue() const;

  v8::Local<v8::Value> ReThrow();

  v8::Local<v8::Value> Exception() const;

  // Nan::MaybeLocal for older versions of V8
  v8::MaybeLocal<v8::Value> StackTrace() const;

  v8::Local<v8::Message> Message() const;

  void Reset();

  void SetVerbose(bool value);

  void SetCaptureMessage(bool value);
};
```

--------------------------------

### Create a new ReferenceError object with Nan::ReferenceError()

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

Use this to create a ReferenceError object. It accepts a C-style string or a v8::Local<v8::String> as input.

```c++
v8::Local<v8::Value> Nan::ReferenceError(const char *msg);
v8::Local<v8::Value> Nan::ReferenceError(v8::Local<v8::String> msg);
```

--------------------------------

### Nan::TryCatch

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

A wrapper around `v8::TryCatch` providing a compatible interface across V8 versions for exception handling.

```APIDOC
## Nan::TryCatch

### Description
A simple wrapper around [`v8::TryCatch`](https://v8docs.nodesource.com/node-8.16/d4/dc6/classv8_1_1_try_catch.html) compatible with all supported versions of V8. Can be used as a direct replacement in most cases. See also [`Nan::FatalException()`](#api_nan_fatal_exception) for an internal use compatible with `node::FatalException`.

### Signature
```c++
class Nan::TryCatch {
 public:
  Nan::TryCatch();

  bool HasCaught() const;

  bool CanContinue() const;

  v8::Local<v8::Value> ReThrow();

  v8::Local<v8::Value> Exception() const;

  // Nan::MaybeLocal for older versions of V8
  v8::MaybeLocal<v8::Value> StackTrace() const;

  v8::Local<v8::Message> Message() const;

  void Reset();

  void SetVerbose(bool value);

  void SetCaptureMessage(bool value);
};
```
```

--------------------------------

### C++ Factory for Wrapped Objects

Source: https://github.com/nodejs/nan/blob/main/doc/object_wrappers.md

Defines a C++ class `MyFactoryObject` that wraps a double value, making it usable as a Node.js object. Includes initialization and method exposure.

```c++
class MyFactoryObject : public Nan::ObjectWrap {
 public:
  static NAN_MODULE_INIT(Init) {
    v8::Local<v8::FunctionTemplate> tpl = Nan::New<v8::FunctionTemplate>(New);
    tpl->InstanceTemplate()->SetInternalFieldCount(1);

    Nan::SetPrototypeMethod(tpl, "getValue", GetValue);

    constructor().Reset(Nan::GetFunction(tpl).ToLocalChecked());
  }

  static NAN_METHOD(NewInstance) {
    v8::Local<v8::Function> cons = Nan::New(constructor());
    double value = info[0]->IsNumber() ? Nan::To<double>(info[0]).FromJust() : 0;
    const int argc = 1;
    v8::Local<v8::Value> argv[1] = {Nan::New(value)};
    info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
  }

  // Needed for the next example:
  inline double value() const {
    return value_;
  }

 private:
  explicit MyFactoryObject(double value = 0) : value_(value) {}
  ~MyFactoryObject() {}

  static NAN_METHOD(New) {
    if (info.IsConstructCall()) {
      double value = info[0]->IsNumber() ? Nan::To<double>(info[0]).FromJust() : 0;
      MyFactoryObject * obj = new MyFactoryObject(value);
      obj->Wrap(info.This());
      info.GetReturnValue().Set(info.This());
    } else {
      const int argc = 1;
      v8::Local<v8::Value> argv[argc] = {info[0]};
      v8::Local<v8::Function> cons = Nan::New(constructor());
      info.GetReturnValue().Set(Nan::NewInstance(cons, argc, argv).ToLocalChecked());
    }
  }

  static NAN_METHOD(GetValue) {
    MyFactoryObject* obj = ObjectWrap::Unwrap<MyFactoryObject>(info.Holder());
    info.GetReturnValue().Set(obj->value_);
  }

  static inline Nan::Persistent<v8::Function> & constructor() {
    static Nan::Persistent<v8::Function> my_constructor;
    return my_constructor;
  }

  double value_;
};

NAN_MODULE_INIT(Init) {
  MyFactoryObject::Init(target);
  Nan::Set(target,
    Nan::New<v8::String>("newFactoryObjectInstance").ToLocalChecked(),
    Nan::GetFunction(
      Nan::New<v8::FunctionTemplate>(MyFactoryObject::NewInstance)).ToLocalChecked()
  );
}

NODE_MODULE(wrappedobjectfactory, Init)
```

--------------------------------

### Nan::AsyncResource

Source: https://github.com/nodejs/nan/blob/main/doc/node_misc.md

Manages asynchronous operations by providing an RAII wrapper around Node.js async_hooks APIs. It ensures callbacks into JavaScript are executed in the correct async context, which is crucial for mechanisms like domains and async_hooks.

```APIDOC
## Nan::AsyncResource

### Description
This class is analogous to the `AsyncResource` JavaScript class exposed by Node's [async_hooks][] API. It provides an RAII wrapper around `node::EmitAsyncInit`, `node::EmitAsyncDestroy`, and `node::MakeCallback` to ensure callbacks into JavaScript are executed in the correct async context.

### Definition
```c++
class AsyncResource {
 public:
  AsyncResource(v8::Local<v8::String> name, v8::Local<v8::Object> resource = New<v8::Object>());
  AsyncResource(const char* name, v8::Local<v8::Object> resource = New<v8::Object>());
  ~AsyncResource();

  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, v8::Local<v8::Function> func, int argc, v8::Local<v8::Value>* argv);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, v8::Local<v8::String> symbol, int argc, v8::Local<v8::Value>* argv);
  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target, const char* method, int argc, v8::Local<v8::Value>* argv);
};
```

### Parameters
* `name` (v8::Local<v8::String> | const char*): Identifier for the resource, recommended to include the owning module name as a prefix.
* `resource` (v8::Local<v8::Object>): An optional object associated with the async work, passed to the [async_hooks][] `init` hook. If omitted, an object is created automatically.

### Usage
Use `runInAsyncScope` to execute callbacks in the correct async execution context. `AsyncDestroy` is called automatically when the `AsyncResource` object is destroyed.
```

--------------------------------

### Nan::FatalException()

Source: https://github.com/nodejs/nan/blob/main/doc/errors.md

Handles fatal exceptions in V8, ensuring proper cleanup and reporting.

```APIDOC
## Nan::FatalException()

### Description
This function is used to handle fatal exceptions within the V8 environment. It ensures that critical errors are managed appropriately.

### Signature
```c++
void Nan::FatalException(v8::Isolate* isolate, v8::TryCatch* try_catch);
```
```

--------------------------------

### Nan::TryEncode Function Signature

Source: https://github.com/nodejs/nan/blob/main/doc/string_bytes.md

A wrapper for node::TryEncode, available only in Node 24 and higher. Use Nan::Encode for earlier versions.

```c++
Nan::MaybeLocal<v8::Value> Nan::TryEncode(const void *buf,
                                 size_t len,
                                 enum Nan::Encoding encoding = BINARY);
```

--------------------------------

### Set Create Histogram Function

Source: https://github.com/nodejs/nan/blob/main/doc/v8_internals.md

Set a callback function for creating V8 histograms. This function wraps V8's SetCreateHistogramFunction.

```c++
void Nan::SetCreateHistogramFunction(v8::CreateHistogramCallback cb)
```