diff options
Diffstat (limited to 'node_modules/nan/doc')
| -rw-r--r-- | node_modules/nan/doc/asyncworker.md | 146 | ||||
| -rw-r--r-- | node_modules/nan/doc/buffers.md | 54 | ||||
| -rw-r--r-- | node_modules/nan/doc/callback.md | 76 | ||||
| -rw-r--r-- | node_modules/nan/doc/converters.md | 41 | ||||
| -rw-r--r-- | node_modules/nan/doc/errors.md | 226 | ||||
| -rw-r--r-- | node_modules/nan/doc/json.md | 62 | ||||
| -rw-r--r-- | node_modules/nan/doc/maybe_types.md | 583 | ||||
| -rw-r--r-- | node_modules/nan/doc/methods.md | 664 | ||||
| -rw-r--r-- | node_modules/nan/doc/new.md | 147 | ||||
| -rw-r--r-- | node_modules/nan/doc/node_misc.md | 123 | ||||
| -rw-r--r-- | node_modules/nan/doc/object_wrappers.md | 263 | ||||
| -rw-r--r-- | node_modules/nan/doc/persistent.md | 296 | ||||
| -rw-r--r-- | node_modules/nan/doc/scopes.md | 73 | ||||
| -rw-r--r-- | node_modules/nan/doc/script.md | 58 | ||||
| -rw-r--r-- | node_modules/nan/doc/string_bytes.md | 62 | ||||
| -rw-r--r-- | node_modules/nan/doc/v8_internals.md | 199 | ||||
| -rw-r--r-- | node_modules/nan/doc/v8_misc.md | 85 |
17 files changed, 3158 insertions, 0 deletions
diff --git a/node_modules/nan/doc/asyncworker.md b/node_modules/nan/doc/asyncworker.md new file mode 100644 index 0000000..04231f8 --- /dev/null +++ b/node_modules/nan/doc/asyncworker.md @@ -0,0 +1,146 @@ +## Asynchronous work helpers + +`Nan::AsyncWorker`, `Nan::AsyncProgressWorker` and `Nan::AsyncProgressQueueWorker` are helper classes that make working with asynchronous code easier. + + - <a href="#api_nan_async_worker"><b><code>Nan::AsyncWorker</code></b></a> + - <a href="#api_nan_async_progress_worker"><b><code>Nan::AsyncProgressWorkerBase & Nan::AsyncProgressWorker</code></b></a> + - <a href="#api_nan_async_progress_queue_worker"><b><code>Nan::AsyncProgressQueueWorker</code></b></a> + - <a href="#api_nan_async_queue_worker"><b><code>Nan::AsyncQueueWorker</code></b></a> + +<a name="api_nan_async_worker"></a> +### Nan::AsyncWorker + +`Nan::AsyncWorker` is an _abstract_ class that you can subclass to have much of the annoying asynchronous queuing and handling taken care of for you. It can even store arbitrary V8 objects for you and have them persist while the asynchronous work is in progress. + +This class internally handles the details of creating an [`AsyncResource`][AsyncResource], and running the callback in the +correct async context. To be able to identify the async resources created by this class in async-hooks, provide a +`resource_name` to the constructor. It is recommended that the module name be used as a prefix to the `resource_name` to avoid +collisions in the names. For more details see [`AsyncResource`][AsyncResource] documentation. The `resource_name` needs to stay valid for the lifetime of the worker instance. + +Definition: + +```c++ +class AsyncWorker { + public: + explicit AsyncWorker(Callback *callback_, const char* resource_name = "nan:AsyncWorker"); + + virtual ~AsyncWorker(); + + virtual void WorkComplete(); + + void SaveToPersistent(const char *key, const v8::Local<v8::Value> &value); + + void SaveToPersistent(const v8::Local<v8::String> &key, + const v8::Local<v8::Value> &value); + + void SaveToPersistent(uint32_t index, + const v8::Local<v8::Value> &value); + + v8::Local<v8::Value> GetFromPersistent(const char *key) const; + + v8::Local<v8::Value> GetFromPersistent(const v8::Local<v8::String> &key) const; + + v8::Local<v8::Value> GetFromPersistent(uint32_t index) const; + + virtual void Execute() = 0; + + uv_work_t request; + + virtual void Destroy(); + + protected: + Persistent<v8::Object> persistentHandle; + + Callback *callback; + + virtual void HandleOKCallback(); + + virtual void HandleErrorCallback(); + + void SetErrorMessage(const char *msg); + + const char* ErrorMessage(); +}; +``` + +<a name="api_nan_async_progress_worker"></a> +### Nan::AsyncProgressWorkerBase & Nan::AsyncProgressWorker + +`Nan::AsyncProgressWorkerBase` is an _abstract_ class template that extends `Nan::AsyncWorker` and adds additional progress reporting callbacks that can be used during the asynchronous work execution to provide progress data back to JavaScript. + +Previously the definition of `Nan::AsyncProgressWorker` only allowed sending `const char` data. Now extending `Nan::AsyncProgressWorker` will yield an instance of the implicit `Nan::AsyncProgressWorkerBase` template with type `<char>` for compatibility. + +`Nan::AsyncProgressWorkerBase` & `Nan::AsyncProgressWorker` is intended for best-effort delivery of nonessential progress messages, e.g. a progress bar. The last event sent before the main thread is woken will be delivered. + +Definition: + +```c++ +template<class T> +class AsyncProgressWorkerBase<T> : public AsyncWorker { + public: + explicit AsyncProgressWorkerBase(Callback *callback_, const char* resource_name = ...); + + virtual ~AsyncProgressWorkerBase(); + + void WorkProgress(); + + class ExecutionProgress { + public: + void Signal() const; + void Send(const T* data, size_t count) const; + }; + + virtual void Execute(const ExecutionProgress& progress) = 0; + + virtual void HandleProgressCallback(const T *data, size_t count) = 0; + + virtual void Destroy(); +}; + +typedef AsyncProgressWorkerBase<T> AsyncProgressWorker; +``` + +<a name="api_nan_async_progress_queue_worker"></a> +### Nan::AsyncProgressQueueWorker + +`Nan::AsyncProgressQueueWorker` is an _abstract_ class template that extends `Nan::AsyncWorker` and adds additional progress reporting callbacks that can be used during the asynchronous work execution to provide progress data back to JavaScript. + +`Nan::AsyncProgressQueueWorker` behaves exactly the same as `Nan::AsyncProgressWorker`, except all events are queued and delivered to the main thread. + +Definition: + +```c++ +template<class T> +class AsyncProgressQueueWorker<T> : public AsyncWorker { + public: + explicit AsyncProgressQueueWorker(Callback *callback_, const char* resource_name = "nan:AsyncProgressQueueWorker"); + + virtual ~AsyncProgressQueueWorker(); + + void WorkProgress(); + + class ExecutionProgress { + public: + void Send(const T* data, size_t count) const; + }; + + virtual void Execute(const ExecutionProgress& progress) = 0; + + virtual void HandleProgressCallback(const T *data, size_t count) = 0; + + virtual void Destroy(); +}; +``` + +<a name="api_nan_async_queue_worker"></a> +### Nan::AsyncQueueWorker + +`Nan::AsyncQueueWorker` will run a `Nan::AsyncWorker` asynchronously via libuv. Both the `execute` and `after_work` steps are taken care of for you. Most of the logic for this is embedded in `Nan::AsyncWorker`. + +Definition: + +```c++ +void AsyncQueueWorker(AsyncWorker *); +``` + +[AsyncResource]: node_misc.md#api_nan_asyncresource diff --git a/node_modules/nan/doc/buffers.md b/node_modules/nan/doc/buffers.md new file mode 100644 index 0000000..8d8d25c --- /dev/null +++ b/node_modules/nan/doc/buffers.md @@ -0,0 +1,54 @@ +## Buffers + +NAN's `node::Buffer` helpers exist as the API has changed across supported Node versions. Use these methods to ensure compatibility. + + - <a href="#api_nan_new_buffer"><b><code>Nan::NewBuffer()</code></b></a> + - <a href="#api_nan_copy_buffer"><b><code>Nan::CopyBuffer()</code></b></a> + - <a href="#api_nan_free_callback"><b><code>Nan::FreeCallback()</code></b></a> + +<a name="api_nan_new_buffer"></a> +### Nan::NewBuffer() + +Allocate a new `node::Buffer` object with the specified size and optional data. Calls `node::Buffer::New()`. + +Note that when creating a `Buffer` using `Nan::NewBuffer()` and an existing `char*`, it is assumed that the ownership of the pointer is being transferred to the new `Buffer` for management. +When a `node::Buffer` instance is garbage collected and a `FreeCallback` has not been specified, `data` will be disposed of via a call to `free()`. +You _must not_ free the memory space manually once you have created a `Buffer` in this way. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Object> Nan::NewBuffer(uint32_t size) +Nan::MaybeLocal<v8::Object> Nan::NewBuffer(char* data, uint32_t size) +Nan::MaybeLocal<v8::Object> Nan::NewBuffer(char *data, + size_t length, + Nan::FreeCallback callback, + void *hint) +``` + + +<a name="api_nan_copy_buffer"></a> +### Nan::CopyBuffer() + +Similar to [`Nan::NewBuffer()`](#api_nan_new_buffer) except that an implicit memcpy will occur within Node. Calls `node::Buffer::Copy()`. + +Management of the `char*` is left to the user, you should manually free the memory space if necessary as the new `Buffer` will have its own copy. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Object> Nan::CopyBuffer(const char *data, uint32_t size) +``` + + +<a name="api_nan_free_callback"></a> +### Nan::FreeCallback() + +A free callback that can be provided to [`Nan::NewBuffer()`](#api_nan_new_buffer). +The supplied callback will be invoked when the `Buffer` undergoes garbage collection. + +Signature: + +```c++ +typedef void (*FreeCallback)(char *data, void *hint); +``` diff --git a/node_modules/nan/doc/callback.md b/node_modules/nan/doc/callback.md new file mode 100644 index 0000000..f7af0bf --- /dev/null +++ b/node_modules/nan/doc/callback.md @@ -0,0 +1,76 @@ +## 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. + + - <a href="#api_nan_callback"><b><code>Nan::Callback</code></b></a> + +<a name="api_nan_callback"></a> +### Nan::Callback + +```c++ +class Callback { + public: + Callback(); + + explicit Callback(const v8::Local<v8::Function> &fn); + + ~Callback(); + + bool operator==(const Callback &other) const; + + bool operator!=(const Callback &other) const; + + v8::Local<v8::Function> operator*() const; + + MaybeLocal<v8::Value> operator()(AsyncResource* async_resource, + v8::Local<v8::Object> target, + int argc = 0, + v8::Local<v8::Value> argv[] = 0) const; + + MaybeLocal<v8::Value> operator()(AsyncResource* async_resource, + int argc = 0, + v8::Local<v8::Value> argv[] = 0) const; + + void SetFunction(const v8::Local<v8::Function> &fn); + + v8::Local<v8::Function> GetFunction() const; + + bool IsEmpty() const; + + void Reset(const v8::Local<v8::Function> &fn); + + void Reset(); + + MaybeLocal<v8::Value> Call(v8::Local<v8::Object> target, + int argc, + v8::Local<v8::Value> argv[], + AsyncResource* async_resource) const; + MaybeLocal<v8::Value> Call(int argc, + v8::Local<v8::Value> argv[], + AsyncResource* async_resource) const; + + // Deprecated versions. Use the versions that accept an async_resource instead + // as they run the callback in the correct async context as specified by the + // resource. If you want to call a synchronous JS function (i.e. on a + // non-empty JS stack), you can use Nan::Call instead. + v8::Local<v8::Value> operator()(v8::Local<v8::Object> target, + int argc = 0, + v8::Local<v8::Value> argv[] = 0) const; + + v8::Local<v8::Value> operator()(int argc = 0, + v8::Local<v8::Value> argv[] = 0) const; + v8::Local<v8::Value> Call(v8::Local<v8::Object> target, + int argc, + v8::Local<v8::Value> argv[]) const; + + v8::Local<v8::Value> Call(int argc, v8::Local<v8::Value> argv[]) const; +}; +``` + +Example usage: + +```c++ +v8::Local<v8::Function> function; +Nan::Callback callback(function); +callback.Call(0, 0); +``` diff --git a/node_modules/nan/doc/converters.md b/node_modules/nan/doc/converters.md new file mode 100644 index 0000000..d20861b --- /dev/null +++ b/node_modules/nan/doc/converters.md @@ -0,0 +1,41 @@ +## Converters + +NAN 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. + + - <a href="#api_nan_to"><b><code>Nan::To()</code></b></a> + +<a name="api_nan_to"></a> +### Nan::To() + +Converts a `v8::Local<v8::Value>` to a different subtype of `v8::Value` or to a native data type. Returns a `Nan::MaybeLocal<>` or a `Nan::Maybe<>` accordingly. + +See [maybe_types.md](./maybe_types.md) for more information on `Nan::Maybe` types. + +Signatures: + +```c++ +// V8 types +Nan::MaybeLocal<v8::Boolean> Nan::To<v8::Boolean>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::Int32> Nan::To<v8::Int32>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::Integer> Nan::To<v8::Integer>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::Object> Nan::To<v8::Object>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::Number> Nan::To<v8::Number>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::String> Nan::To<v8::String>(v8::Local<v8::Value> val); +Nan::MaybeLocal<v8::Uint32> Nan::To<v8::Uint32>(v8::Local<v8::Value> val); + +// Native types +Nan::Maybe<bool> Nan::To<bool>(v8::Local<v8::Value> val); +Nan::Maybe<double> Nan::To<double>(v8::Local<v8::Value> val); +Nan::Maybe<int32_t> Nan::To<int32_t>(v8::Local<v8::Value> val); +Nan::Maybe<int64_t> Nan::To<int64_t>(v8::Local<v8::Value> val); +Nan::Maybe<uint32_t> Nan::To<uint32_t>(v8::Local<v8::Value> val); +``` + +### Example + +```c++ +v8::Local<v8::Value> val; +Nan::MaybeLocal<v8::String> str = Nan::To<v8::String>(val); +Nan::Maybe<double> d = Nan::To<double>(val); +``` + diff --git a/node_modules/nan/doc/errors.md b/node_modules/nan/doc/errors.md new file mode 100644 index 0000000..843435b --- /dev/null +++ b/node_modules/nan/doc/errors.md @@ -0,0 +1,226 @@ +## 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](https://developers.google.com/v8/embed#exceptions) for more information. + + - <a href="#api_nan_error"><b><code>Nan::Error()</code></b></a> + - <a href="#api_nan_range_error"><b><code>Nan::RangeError()</code></b></a> + - <a href="#api_nan_reference_error"><b><code>Nan::ReferenceError()</code></b></a> + - <a href="#api_nan_syntax_error"><b><code>Nan::SyntaxError()</code></b></a> + - <a href="#api_nan_type_error"><b><code>Nan::TypeError()</code></b></a> + - <a href="#api_nan_throw_error"><b><code>Nan::ThrowError()</code></b></a> + - <a href="#api_nan_throw_range_error"><b><code>Nan::ThrowRangeError()</code></b></a> + - <a href="#api_nan_throw_reference_error"><b><code>Nan::ThrowReferenceError()</code></b></a> + - <a href="#api_nan_throw_syntax_error"><b><code>Nan::ThrowSyntaxError()</code></b></a> + - <a href="#api_nan_throw_type_error"><b><code>Nan::ThrowTypeError()</code></b></a> + - <a href="#api_nan_fatal_exception"><b><code>Nan::FatalException()</code></b></a> + - <a href="#api_nan_errno_exception"><b><code>Nan::ErrnoException()</code></b></a> + - <a href="#api_nan_try_catch"><b><code>Nan::TryCatch</code></b></a> + + +<a name="api_nan_error"></a> +### Nan::Error() + +Create a new Error object using the [v8::Exception](https://v8docs.nodesource.com/node-8.16/da/d6a/classv8_1_1_exception.html) class in a way that is compatible across the supported versions of V8. + +Note that an Error object is simply a specialized form of `v8::Value`. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::Error(const char *msg); +v8::Local<v8::Value> Nan::Error(v8::Local<v8::String> msg); +``` + + +<a name="api_nan_range_error"></a> +### Nan::RangeError() + +Create a new RangeError object using the [v8::Exception](https://v8docs.nodesource.com/node-8.16/da/d6a/classv8_1_1_exception.html) class in a way that is compatible across the supported versions of V8. + +Note that an RangeError object is simply a specialized form of `v8::Value`. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::RangeError(const char *msg); +v8::Local<v8::Value> Nan::RangeError(v8::Local<v8::String> msg); +``` + + +<a name="api_nan_reference_error"></a> +### Nan::ReferenceError() + +Create a new ReferenceError object using the [v8::Exception](https://v8docs.nodesource.com/node-8.16/da/d6a/classv8_1_1_exception.html) class in a way that is compatible across the supported versions of V8. + +Note that an ReferenceError object is simply a specialized form of `v8::Value`. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::ReferenceError(const char *msg); +v8::Local<v8::Value> Nan::ReferenceError(v8::Local<v8::String> msg); +``` + + +<a name="api_nan_syntax_error"></a> +### Nan::SyntaxError() + +Create a new SyntaxError object using the [v8::Exception](https://v8docs.nodesource.com/node-8.16/da/d6a/classv8_1_1_exception.html) class in a way that is compatible across the supported versions of V8. + +Note that an SyntaxError object is simply a specialized form of `v8::Value`. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::SyntaxError(const char *msg); +v8::Local<v8::Value> Nan::SyntaxError(v8::Local<v8::String> msg); +``` + + +<a name="api_nan_type_error"></a> +### Nan::TypeError() + +Create a new TypeError object using the [v8::Exception](https://v8docs.nodesource.com/node-8.16/da/d6a/classv8_1_1_exception.html) class in a way that is compatible across the supported versions of V8. + +Note that an TypeError object is simply a specialized form of `v8::Value`. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::TypeError(const char *msg); +v8::Local<v8::Value> Nan::TypeError(v8::Local<v8::String> msg); +``` + + +<a name="api_nan_throw_error"></a> +### Nan::ThrowError() + +Throw an Error object (a specialized `v8::Value` as above) in the current context. If a `msg` is provided, a new Error object will be created. + +Signature: + +```c++ +void Nan::ThrowError(const char *msg); +void Nan::ThrowError(v8::Local<v8::String> msg); +void Nan::ThrowError(v8::Local<v8::Value> error); +``` + + +<a name="api_nan_throw_range_error"></a> +### Nan::ThrowRangeError() + +Throw an RangeError object (a specialized `v8::Value` as above) in the current context. If a `msg` is provided, a new RangeError object will be created. + +Signature: + +```c++ +void Nan::ThrowRangeError(const char *msg); +void Nan::ThrowRangeError(v8::Local<v8::String> msg); +void Nan::ThrowRangeError(v8::Local<v8::Value> error); +``` + + +<a name="api_nan_throw_reference_error"></a> +### Nan::ThrowReferenceError() + +Throw an ReferenceError object (a specialized `v8::Value` as above) in the current context. If a `msg` is provided, a new ReferenceError object will be created. + +Signature: + +```c++ +void Nan::ThrowReferenceError(const char *msg); +void Nan::ThrowReferenceError(v8::Local<v8::String> msg); +void Nan::ThrowReferenceError(v8::Local<v8::Value> error); +``` + + +<a name="api_nan_throw_syntax_error"></a> +### Nan::ThrowSyntaxError() + +Throw an SyntaxError object (a specialized `v8::Value` as above) in the current context. If a `msg` is provided, a new SyntaxError object will be created. + +Signature: + +```c++ +void Nan::ThrowSyntaxError(const char *msg); +void Nan::ThrowSyntaxError(v8::Local<v8::String> msg); +void Nan::ThrowSyntaxError(v8::Local<v8::Value> error); +``` + + +<a name="api_nan_throw_type_error"></a> +### Nan::ThrowTypeError() + +Throw an TypeError object (a specialized `v8::Value` as above) in the current context. If a `msg` is provided, a new TypeError object will be created. + +Signature: + +```c++ +void Nan::ThrowTypeError(const char *msg); +void Nan::ThrowTypeError(v8::Local<v8::String> msg); +void Nan::ThrowTypeError(v8::Local<v8::Value> error); +``` + +<a name="api_nan_fatal_exception"></a> +### Nan::FatalException() + +Replaces `node::FatalException()` which has a different API across supported versions of Node. For use with [`Nan::TryCatch`](#api_nan_try_catch). + +Signature: + +```c++ +void Nan::FatalException(const Nan::TryCatch& try_catch); +``` + +<a name="api_nan_errno_exception"></a> +### Nan::ErrnoException() + +Replaces `node::ErrnoException()` which has a different API across supported versions of Node. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::ErrnoException(int errorno, + const char* syscall = NULL, + const char* message = NULL, + const char* path = NULL); +``` + + +<a name="api_nan_try_catch"></a> +### Nan::TryCatch + +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); +}; +``` + diff --git a/node_modules/nan/doc/json.md b/node_modules/nan/doc/json.md new file mode 100644 index 0000000..55beb26 --- /dev/null +++ b/node_modules/nan/doc/json.md @@ -0,0 +1,62 @@ +## JSON + +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. + + - <a href="#api_nan_json_parse"><b><code>Nan::JSON.Parse</code></b></a> + - <a href="#api_nan_json_stringify"><b><code>Nan::JSON.Stringify</code></b></a> + +Refer 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. + +<a name="api_nan_json_parse"></a> + +### Nan::JSON.Parse + +A simple wrapper around [`v8::JSON::Parse`](https://v8docs.nodesource.com/node-8.16/da/d6f/classv8_1_1_j_s_o_n.html#a936310d2540fb630ed37d3ee3ffe4504). + +Definition: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::JSON::Parse(v8::Local<v8::String> json_string); +``` + +Use `JSON.Parse(json_string)` to parse a string into a `v8::Value`. + +Example: + +```c++ +v8::Local<v8::String> json_string = Nan::New("{ \"JSON\": \"object\" }").ToLocalChecked(); + +Nan::JSON NanJSON; +Nan::MaybeLocal<v8::Value> result = NanJSON.Parse(json_string); +if (!result.IsEmpty()) { + v8::Local<v8::Value> val = result.ToLocalChecked(); +} +``` + +<a name="api_nan_json_stringify"></a> + +### Nan::JSON.Stringify + +A simple wrapper around [`v8::JSON::Stringify`](https://v8docs.nodesource.com/node-8.16/da/d6f/classv8_1_1_j_s_o_n.html#a44b255c3531489ce43f6110209138860). + +Definition: + +```c++ +Nan::MaybeLocal<v8::String> Nan::JSON::Stringify(v8::Local<v8::Object> json_object, v8::Local<v8::String> gap = v8::Local<v8::String>()); +``` + +Use `JSON.Stringify(value)` to stringify a `v8::Object`. + +Example: + +```c++ +// using `v8::Local<v8::Value> val` from the `JSON::Parse` example +v8::Local<v8::Object> obj = Nan::To<v8::Object>(val).ToLocalChecked(); + +Nan::JSON NanJSON; +Nan::MaybeLocal<v8::String> result = NanJSON.Stringify(obj); +if (!result.IsEmpty()) { + v8::Local<v8::String> stringified = result.ToLocalChecked(); +} +``` + diff --git a/node_modules/nan/doc/maybe_types.md b/node_modules/nan/doc/maybe_types.md new file mode 100644 index 0000000..142851a --- /dev/null +++ b/node_modules/nan/doc/maybe_types.md @@ -0,0 +1,583 @@ +## Maybe Types + +The `Nan::MaybeLocal` and `Nan::Maybe` types are monads that encapsulate `v8::Local` handles that _may be empty_. + +* **Maybe Types** + - <a href="#api_nan_maybe_local"><b><code>Nan::MaybeLocal</code></b></a> + - <a href="#api_nan_maybe"><b><code>Nan::Maybe</code></b></a> + - <a href="#api_nan_nothing"><b><code>Nan::Nothing</code></b></a> + - <a href="#api_nan_just"><b><code>Nan::Just</code></b></a> +* **Maybe Helpers** + - <a href="#api_nan_call"><b><code>Nan::Call()</code></b></a> + - <a href="#api_nan_to_detail_string"><b><code>Nan::ToDetailString()</code></b></a> + - <a href="#api_nan_to_array_index"><b><code>Nan::ToArrayIndex()</code></b></a> + - <a href="#api_nan_equals"><b><code>Nan::Equals()</code></b></a> + - <a href="#api_nan_new_instance"><b><code>Nan::NewInstance()</code></b></a> + - <a href="#api_nan_get_function"><b><code>Nan::GetFunction()</code></b></a> + - <a href="#api_nan_set"><b><code>Nan::Set()</code></b></a> + - <a href="#api_nan_define_own_property"><b><code>Nan::DefineOwnProperty()</code></b></a> + - <a href="#api_nan_force_set"><del><b><code>Nan::ForceSet()</code></b></del></a> + - <a href="#api_nan_get"><b><code>Nan::Get()</code></b></a> + - <a href="#api_nan_get_property_attribute"><b><code>Nan::GetPropertyAttributes()</code></b></a> + - <a href="#api_nan_has"><b><code>Nan::Has()</code></b></a> + - <a href="#api_nan_delete"><b><code>Nan::Delete()</code></b></a> + - <a href="#api_nan_get_property_names"><b><code>Nan::GetPropertyNames()</code></b></a> + - <a href="#api_nan_get_own_property_names"><b><code>Nan::GetOwnPropertyNames()</code></b></a> + - <a href="#api_nan_set_prototype"><b><code>Nan::SetPrototype()</code></b></a> + - <a href="#api_nan_object_proto_to_string"><b><code>Nan::ObjectProtoToString()</code></b></a> + - <a href="#api_nan_has_own_property"><b><code>Nan::HasOwnProperty()</code></b></a> + - <a href="#api_nan_has_real_named_property"><b><code>Nan::HasRealNamedProperty()</code></b></a> + - <a href="#api_nan_has_real_indexed_property"><b><code>Nan::HasRealIndexedProperty()</code></b></a> + - <a href="#api_nan_has_real_named_callback_property"><b><code>Nan::HasRealNamedCallbackProperty()</code></b></a> + - <a href="#api_nan_get_real_named_property_in_prototype_chain"><b><code>Nan::GetRealNamedPropertyInPrototypeChain()</code></b></a> + - <a href="#api_nan_get_real_named_property"><b><code>Nan::GetRealNamedProperty()</code></b></a> + - <a href="#api_nan_call_as_function"><b><code>Nan::CallAsFunction()</code></b></a> + - <a href="#api_nan_call_as_constructor"><b><code>Nan::CallAsConstructor()</code></b></a> + - <a href="#api_nan_get_source_line"><b><code>Nan::GetSourceLine()</code></b></a> + - <a href="#api_nan_get_line_number"><b><code>Nan::GetLineNumber()</code></b></a> + - <a href="#api_nan_get_start_column"><b><code>Nan::GetStartColumn()</code></b></a> + - <a href="#api_nan_get_end_column"><b><code>Nan::GetEndColumn()</code></b></a> + - <a href="#api_nan_clone_element_at"><b><code>Nan::CloneElementAt()</code></b></a> + - <a href="#api_nan_has_private"><b><code>Nan::HasPrivate()</code></b></a> + - <a href="#api_nan_get_private"><b><code>Nan::GetPrivate()</code></b></a> + - <a href="#api_nan_set_private"><b><code>Nan::SetPrivate()</code></b></a> + - <a href="#api_nan_delete_private"><b><code>Nan::DeletePrivate()</code></b></a> + - <a href="#api_nan_make_maybe"><b><code>Nan::MakeMaybe()</code></b></a> + +<a name="api_nan_maybe_local"></a> +### Nan::MaybeLocal + +A `Nan::MaybeLocal<T>` is a wrapper around [`v8::Local<T>`](https://v8docs.nodesource.com/node-8.16/de/deb/classv8_1_1_local.html) that enforces a check that determines whether the `v8::Local<T>` is empty before it can be used. + +If an API method returns a `Nan::MaybeLocal`, the API method can potentially fail either because an exception is thrown, or because an exception is pending, e.g. because a previous API call threw an exception that hasn't been caught yet, or because a `v8::TerminateExecution` exception was thrown. In that case, an empty `Nan::MaybeLocal` is returned. + +Definition: + +```c++ +template<typename T> class Nan::MaybeLocal { + public: + MaybeLocal(); + + template<typename S> MaybeLocal(v8::Local<S> that); + + bool IsEmpty() const; + + template<typename S> bool ToLocal(v8::Local<S> *out); + + // Will crash if the MaybeLocal<> is empty. + v8::Local<T> ToLocalChecked(); + + template<typename S> v8::Local<S> FromMaybe(v8::Local<S> default_value) const; +}; +``` + +See the documentation for [`v8::MaybeLocal`](https://v8docs.nodesource.com/node-8.16/d8/d7d/classv8_1_1_maybe_local.html) for further details. + +<a name="api_nan_maybe"></a> +### Nan::Maybe + +A simple `Nan::Maybe` type, representing an object which may or may not have a value, see https://hackage.haskell.org/package/base/docs/Data-Maybe.html. + +If an API method returns a `Nan::Maybe<>`, the API method can potentially fail either because an exception is thrown, or because an exception is pending, e.g. because a previous API call threw an exception that hasn't been caught yet, or because a `v8::TerminateExecution` exception was thrown. In that case, a "Nothing" value is returned. + +Definition: + +```c++ +template<typename T> class Nan::Maybe { + public: + bool IsNothing() const; + bool IsJust() const; + + // Will crash if the Maybe<> is nothing. + T FromJust(); + + T FromMaybe(const T& default_value); + + bool operator==(const Maybe &other); + + bool operator!=(const Maybe &other); +}; +``` + +See the documentation for [`v8::Maybe`](https://v8docs.nodesource.com/node-8.16/d9/d4b/classv8_1_1_maybe.html) for further details. + +<a name="api_nan_nothing"></a> +### Nan::Nothing + +Construct an empty `Nan::Maybe` type representing _nothing_. + +```c++ +template<typename T> Nan::Maybe<T> Nan::Nothing(); +``` + +<a name="api_nan_just"></a> +### Nan::Just + +Construct a `Nan::Maybe` type representing _just_ a value. + +```c++ +template<typename T> Nan::Maybe<T> Nan::Just(const T &t); +``` + +<a name="api_nan_call"></a> +### Nan::Call() + +A helper method for calling a synchronous [`v8::Function#Call()`](https://v8docs.nodesource.com/node-8.16/d5/d54/classv8_1_1_function.html#a9c3d0e4e13ddd7721fce238aa5b94a11) in a way compatible across supported versions of V8. + +For asynchronous callbacks, use Nan::Callback::Call along with an AsyncResource. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::Call(v8::Local<v8::Function> fun, v8::Local<v8::Object> recv, int argc, v8::Local<v8::Value> argv[]); +Nan::MaybeLocal<v8::Value> Nan::Call(const Nan::Callback& callback, v8::Local<v8::Object> recv, + int argc, v8::Local<v8::Value> argv[]); +Nan::MaybeLocal<v8::Value> Nan::Call(const Nan::Callback& callback, int argc, v8::Local<v8::Value> argv[]); +``` + + +<a name="api_nan_to_detail_string"></a> +### Nan::ToDetailString() + +A helper method for calling [`v8::Value#ToDetailString()`](https://v8docs.nodesource.com/node-8.16/dc/d0a/classv8_1_1_value.html#a2f9770296dc2c8d274bc8cc0dca243e5) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::String> Nan::ToDetailString(v8::Local<v8::Value> val); +``` + + +<a name="api_nan_to_array_index"></a> +### Nan::ToArrayIndex() + +A helper method for calling [`v8::Value#ToArrayIndex()`](https://v8docs.nodesource.com/node-8.16/dc/d0a/classv8_1_1_value.html#acc5bbef3c805ec458470c0fcd6f13493) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Uint32> Nan::ToArrayIndex(v8::Local<v8::Value> val); +``` + + +<a name="api_nan_equals"></a> +### Nan::Equals() + +A helper method for calling [`v8::Value#Equals()`](https://v8docs.nodesource.com/node-8.16/dc/d0a/classv8_1_1_value.html#a08fba1d776a59bbf6864b25f9152c64b) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::Equals(v8::Local<v8::Value> a, v8::Local<v8::Value>(b)); +``` + + +<a name="api_nan_new_instance"></a> +### Nan::NewInstance() + +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. + +Signature: + +```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); +``` + + +<a name="api_nan_get_function"></a> +### Nan::GetFunction() + +A helper method for calling [`v8::FunctionTemplate#GetFunction()`](https://v8docs.nodesource.com/node-8.16/d8/d83/classv8_1_1_function_template.html#a56d904662a86eca78da37d9bb0ed3705) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Function> Nan::GetFunction(v8::Local<v8::FunctionTemplate> t); +``` + + +<a name="api_nan_set"></a> +### Nan::Set() + +A helper method for calling [`v8::Object#Set()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a67604ea3734f170c66026064ea808f20) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::Set(v8::Local<v8::Object> obj, + v8::Local<v8::Value> key, + v8::Local<v8::Value> value) +Nan::Maybe<bool> Nan::Set(v8::Local<v8::Object> obj, + uint32_t index, + v8::Local<v8::Value> value); +``` + + +<a name="api_nan_define_own_property"></a> +### Nan::DefineOwnProperty() + +A helper method for calling [`v8::Object#DefineOwnProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a6f76b2ed605cb8f9185b92de0033a820) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::DefineOwnProperty(v8::Local<v8::Object> obj, + v8::Local<v8::String> key, + v8::Local<v8::Value> value, + v8::PropertyAttribute attribs = v8::None); +``` + + +<a name="api_nan_force_set"></a> +### <del>Nan::ForceSet()</del> + +Deprecated, use <a href="#api_nan_define_own_property"><code>Nan::DefineOwnProperty()</code></a>. + +<del>A helper method for calling [`v8::Object#ForceSet()`](https://v8docs.nodesource.com/node-0.12/db/d85/classv8_1_1_object.html#acfbdfd7427b516ebdb5c47c4df5ed96c) in a way compatible across supported versions of V8.</del> + +Signature: + +```c++ +NAN_DEPRECATED Nan::Maybe<bool> Nan::ForceSet(v8::Local<v8::Object> obj, + v8::Local<v8::Value> key, + v8::Local<v8::Value> value, + v8::PropertyAttribute attribs = v8::None); +``` + + +<a name="api_nan_get"></a> +### Nan::Get() + +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: + +```c++ +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); +``` + + +<a name="api_nan_get_property_attribute"></a> +### Nan::GetPropertyAttributes() + +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: + +```c++ +Nan::Maybe<v8::PropertyAttribute> Nan::GetPropertyAttributes( + v8::Local<v8::Object> obj, + v8::Local<v8::Value> key); +``` + + +<a name="api_nan_has"></a> +### Nan::Has() + +A helper method for calling [`v8::Object#Has()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ab3c3d89ea7c2f9afd08965bd7299a41d) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::Has(v8::Local<v8::Object> obj, v8::Local<v8::String> key); +Nan::Maybe<bool> Nan::Has(v8::Local<v8::Object> obj, uint32_t index); +``` + + +<a name="api_nan_delete"></a> +### Nan::Delete() + +A helper method for calling [`v8::Object#Delete()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a48e4a19b2cedff867eecc73ddb7d377f) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::Delete(v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +Nan::Maybe<bool> Nan::Delete(v8::Local<v8::Object> obj, uint32_t index); +``` + + +<a name="api_nan_get_property_names"></a> +### Nan::GetPropertyNames() + +A helper method for calling [`v8::Object#GetPropertyNames()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#aced885270cfd2c956367b5eedc7fbfe8) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Array> Nan::GetPropertyNames(v8::Local<v8::Object> obj); +``` + + +<a name="api_nan_get_own_property_names"></a> +### Nan::GetOwnPropertyNames() + +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: + +```c++ +Nan::MaybeLocal<v8::Array> Nan::GetOwnPropertyNames(v8::Local<v8::Object> obj); +``` + + +<a name="api_nan_set_prototype"></a> +### Nan::SetPrototype() + +A helper method for calling [`v8::Object#SetPrototype()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a442706b22fceda6e6d1f632122a9a9f4) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::SetPrototype(v8::Local<v8::Object> obj, + v8::Local<v8::Value> prototype); +``` + + +<a name="api_nan_object_proto_to_string"></a> +### Nan::ObjectProtoToString() + +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: + +```c++ +Nan::MaybeLocal<v8::String> Nan::ObjectProtoToString(v8::Local<v8::Object> obj); +``` + + +<a name="api_nan_has_own_property"></a> +### Nan::HasOwnProperty() + +A helper method for calling [`v8::Object#HasOwnProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ab7b7245442ca6de1e1c145ea3fd653ff) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::HasOwnProperty(v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +``` + + +<a name="api_nan_has_real_named_property"></a> +### Nan::HasRealNamedProperty() + +A helper method for calling [`v8::Object#HasRealNamedProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ad8b80a59c9eb3c1e6c3cd6c84571f767) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::HasRealNamedProperty(v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +``` + + +<a name="api_nan_has_real_indexed_property"></a> +### Nan::HasRealIndexedProperty() + +A helper method for calling [`v8::Object#HasRealIndexedProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#af94fc1135a5e74a2193fb72c3a1b9855) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::HasRealIndexedProperty(v8::Local<v8::Object> obj, + uint32_t index); +``` + + +<a name="api_nan_has_real_named_callback_property"></a> +### Nan::HasRealNamedCallbackProperty() + +A helper method for calling [`v8::Object#HasRealNamedCallbackProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#af743b7ea132b89f84d34d164d0668811) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::HasRealNamedCallbackProperty( + v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +``` + + +<a name="api_nan_get_real_named_property_in_prototype_chain"></a> +### Nan::GetRealNamedPropertyInPrototypeChain() + +A helper method for calling [`v8::Object#GetRealNamedPropertyInPrototypeChain()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a8700b1862e6b4783716964ba4d5e6172) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::GetRealNamedPropertyInPrototypeChain( + v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +``` + + +<a name="api_nan_get_real_named_property"></a> +### Nan::GetRealNamedProperty() + +A helper method for calling [`v8::Object#GetRealNamedProperty()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a84471a824576a5994fdd0ffcbf99ccc0) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::GetRealNamedProperty(v8::Local<v8::Object> obj, + v8::Local<v8::String> key); +``` + + +<a name="api_nan_call_as_function"></a> +### Nan::CallAsFunction() + +A helper method for calling [`v8::Object#CallAsFunction()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ad3ffc36f3dfc3592ce2a96bc047ee2cd) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::CallAsFunction(v8::Local<v8::Object> obj, + v8::Local<v8::Object> recv, + int argc, + v8::Local<v8::Value> argv[]); +``` + + +<a name="api_nan_call_as_constructor"></a> +### Nan::CallAsConstructor() + +A helper method for calling [`v8::Object#CallAsConstructor()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a50d571de50d0b0dfb28795619d07a01b) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::CallAsConstructor(v8::Local<v8::Object> obj, + int argc, + v8::Local<v8::Value> argv[]); +``` + + +<a name="api_nan_get_source_line"></a> +### Nan::GetSourceLine() + +A helper method for calling [`v8::Message#GetSourceLine()`](https://v8docs.nodesource.com/node-8.16/d9/d28/classv8_1_1_message.html#a849f7a6c41549d83d8159825efccd23a) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::String> Nan::GetSourceLine(v8::Local<v8::Message> msg); +``` + + +<a name="api_nan_get_line_number"></a> +### Nan::GetLineNumber() + +A helper method for calling [`v8::Message#GetLineNumber()`](https://v8docs.nodesource.com/node-8.16/d9/d28/classv8_1_1_message.html#adbe46c10a88a6565f2732a2d2adf99b9) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<int> Nan::GetLineNumber(v8::Local<v8::Message> msg); +``` + + +<a name="api_nan_get_start_column"></a> +### Nan::GetStartColumn() + +A helper method for calling [`v8::Message#GetStartColumn()`](https://v8docs.nodesource.com/node-8.16/d9/d28/classv8_1_1_message.html#a60ede616ba3822d712e44c7a74487ba6) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<int> Nan::GetStartColumn(v8::Local<v8::Message> msg); +``` + + +<a name="api_nan_get_end_column"></a> +### Nan::GetEndColumn() + +A helper method for calling [`v8::Message#GetEndColumn()`](https://v8docs.nodesource.com/node-8.16/d9/d28/classv8_1_1_message.html#aaa004cf19e529da980bc19fcb76d93be) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<int> Nan::GetEndColumn(v8::Local<v8::Message> msg); +``` + + +<a name="api_nan_clone_element_at"></a> +### Nan::CloneElementAt() + +A helper method for calling [`v8::Array#CloneElementAt()`](https://v8docs.nodesource.com/node-4.8/d3/d32/classv8_1_1_array.html#a1d3a878d4c1c7cae974dd50a1639245e) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Object> Nan::CloneElementAt(v8::Local<v8::Array> array, uint32_t index); +``` + +<a name="api_nan_has_private"></a> +### Nan::HasPrivate() + +A helper method for calling [`v8::Object#HasPrivate()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#af68a0b98066cfdeb8f943e98a40ba08d) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::HasPrivate(v8::Local<v8::Object> object, v8::Local<v8::String> key); +``` + +<a name="api_nan_get_private"></a> +### Nan::GetPrivate() + +A helper method for calling [`v8::Object#GetPrivate()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a169f2da506acbec34deadd9149a1925a) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::GetPrivate(v8::Local<v8::Object> object, v8::Local<v8::String> key); +``` + +<a name="api_nan_set_private"></a> +### Nan::SetPrivate() + +A helper method for calling [`v8::Object#SetPrivate()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ace1769b0f3b86bfe9fda1010916360ee) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::SetPrivate(v8::Local<v8::Object> object, v8::Local<v8::String> key, v8::Local<v8::Value> value); +``` + +<a name="api_nan_delete_private"></a> +### Nan::DeletePrivate() + +A helper method for calling [`v8::Object#DeletePrivate()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a138bb32a304f3982be02ad499693b8fd) in a way compatible across supported versions of V8. + +Signature: + +```c++ +Nan::Maybe<bool> Nan::DeletePrivate(v8::Local<v8::Object> object, v8::Local<v8::String> key); +``` + +<a name="api_nan_make_maybe"></a> +### Nan::MakeMaybe() + +Wraps a `v8::Local<>` in a `Nan::MaybeLocal<>`. When called with a `Nan::MaybeLocal<>` it just returns its argument. This is useful in generic template code that builds on NAN. + +Synopsis: + +```c++ + MaybeLocal<v8::Number> someNumber = MakeMaybe(New<v8::Number>(3.141592654)); + MaybeLocal<v8::String> someString = MakeMaybe(New<v8::String>("probably")); +``` + +Signature: + +```c++ +template <typename T, template <typename> class MaybeMaybe> +Nan::MaybeLocal<T> Nan::MakeMaybe(MaybeMaybe<T> v); +``` diff --git a/node_modules/nan/doc/methods.md b/node_modules/nan/doc/methods.md new file mode 100644 index 0000000..9642d02 --- /dev/null +++ b/node_modules/nan/doc/methods.md @@ -0,0 +1,664 @@ +## 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](https://github.com/v8/v8/wiki/Embedder%27s-Guide#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** + - <a href="#api_nan_function_callback_info"><b><code>Nan::FunctionCallbackInfo</code></b></a> + - <a href="#api_nan_property_callback_info"><b><code>Nan::PropertyCallbackInfo</code></b></a> + - <a href="#api_nan_return_value"><b><code>Nan::ReturnValue</code></b></a> +* **Method declarations** + - <a href="#api_nan_method"><b>Method declaration</b></a> + - <a href="#api_nan_getter"><b>Getter declaration</b></a> + - <a href="#api_nan_setter"><b>Setter declaration</b></a> + - <a href="#api_nan_property_getter"><b>Property getter declaration</b></a> + - <a href="#api_nan_property_setter"><b>Property setter declaration</b></a> + - <a href="#api_nan_property_enumerator"><b>Property enumerator declaration</b></a> + - <a href="#api_nan_property_deleter"><b>Property deleter declaration</b></a> + - <a href="#api_nan_property_query"><b>Property query declaration</b></a> + - <a href="#api_nan_index_getter"><b>Index getter declaration</b></a> + - <a href="#api_nan_index_setter"><b>Index setter declaration</b></a> + - <a href="#api_nan_index_enumerator"><b>Index enumerator declaration</b></a> + - <a href="#api_nan_index_deleter"><b>Index deleter declaration</b></a> + - <a href="#api_nan_index_query"><b>Index query declaration</b></a> +* Method and template helpers + - <a href="#api_nan_set_method"><b><code>Nan::SetMethod()</code></b></a> + - <a href="#api_nan_set_prototype_method"><b><code>Nan::SetPrototypeMethod()</code></b></a> + - <a href="#api_nan_set_accessor"><b><code>Nan::SetAccessor()</code></b></a> + - <a href="#api_nan_set_named_property_handler"><b><code>Nan::SetNamedPropertyHandler()</code></b></a> + - <a href="#api_nan_set_indexed_property_handler"><b><code>Nan::SetIndexedPropertyHandler()</code></b></a> + - <a href="#api_nan_set_template"><b><code>Nan::SetTemplate()</code></b></a> + - <a href="#api_nan_set_prototype_template"><b><code>Nan::SetPrototypeTemplate()</code></b></a> + - <a href="#api_nan_set_instance_template"><b><code>Nan::SetInstanceTemplate()</code></b></a> + - <a href="#api_nan_set_call_handler"><b><code>Nan::SetCallHandler()</code></b></a> + - <a href="#api_nan_set_call_as_function_handler"><b><code>Nan::SetCallAsFunctionHandler()</code></b></a> + +<a name="api_nan_function_callback_info"></a> +### Nan::FunctionCallbackInfo + +`Nan::FunctionCallbackInfo` should be used in place of [`v8::FunctionCallbackInfo`](https://v8docs.nodesource.com/node-8.16/dd/d0d/classv8_1_1_function_callback_info.html), even with older versions of Node where `v8::FunctionCallbackInfo` does not exist. + +Definition: + +```c++ +template<typename T> class FunctionCallbackInfo { + public: + ReturnValue<T> GetReturnValue() const; + v8::Local<v8::Function> Callee(); // NOTE: Not available in NodeJS >= 10.0.0 + v8::Local<v8::Value> Data(); + v8::Local<v8::Object> Holder(); + bool IsConstructCall(); + int Length() const; + v8::Local<v8::Value> operator[](int i) const; + v8::Local<v8::Object> This() const; + v8::Isolate *GetIsolate() const; +}; +``` + +See the [`v8::FunctionCallbackInfo`](https://v8docs.nodesource.com/node-8.16/dd/d0d/classv8_1_1_function_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 methods. + +**Note:** `FunctionCallbackInfo::Callee` is removed in Node.js after `10.0.0` because it is was deprecated in V8. Consider using `info.Data()` to pass any information you need. + +<a name="api_nan_property_callback_info"></a> +### Nan::PropertyCallbackInfo + +`Nan::PropertyCallbackInfo` should be used in place of [`v8::PropertyCallbackInfo`](https://v8docs.nodesource.com/node-8.16/d7/dc5/classv8_1_1_property_callback_info.html), 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. + +<a name="api_nan_return_value"></a> +### Nan::ReturnValue + +`Nan::ReturnValue` is used in place of [`v8::ReturnValue`](https://v8docs.nodesource.com/node-8.16/da/da7/classv8_1_1_return_value.html) on both [`Nan::FunctionCallbackInfo`](#api_nan_function_callback_info) and [`Nan::PropertyCallbackInfo`](#api_nan_property_callback_info) as the return type of `GetReturnValue()`. + +Example usage: + +```c++ +void EmptyArray(const Nan::FunctionCallbackInfo<v8::Value>& info) { + info.GetReturnValue().Set(Nan::New<v8::Array>()); +} +``` + +Definition: + +```c++ +template<typename T> class ReturnValue { + public: + // Handle setters + template <typename S> void Set(const v8::Local<S> &handle); + template <typename S> void Set(const Nan::Global<S> &handle); + + // Fast primitive setters + void Set(bool value); + void Set(double i); + void Set(int32_t i); + void Set(uint32_t i); + + // Fast JS primitive setters + void SetNull(); + void SetUndefined(); + void SetEmptyString(); + + // Convenience getter for isolate + v8::Isolate *GetIsolate() const; +}; +``` + +See the documentation on [`v8::ReturnValue`](https://v8docs.nodesource.com/node-8.16/da/da7/classv8_1_1_return_value.html) for further information on this. + +<a name="api_nan_method"></a> +### Method declaration + +JavaScript-accessible methods should be declared with the following signature to form a `Nan::FunctionCallback`: + +```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. + +<a name="api_nan_getter"></a> +### Getter declaration + +JavaScript-accessible getters should be declared with the following signature to form a `Nan::GetterCallback`: + +```c++ +typedef void(*GetterCallback)(v8::Local<v8::String>, + const PropertyCallbackInfo<v8::Value>&); +``` + +Example: + +```c++ +void GetterName(v8::Local<v8::String> property, + const Nan::PropertyCallbackInfo<v8::Value>& info) { + ... +} +``` + +You do not need to declare a new `HandleScope` within a getter as one is implicitly created for you. + +A helper macro `NAN_GETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on [Accessors](https://developers.google.com/v8/embed#accesssors). + +<a name="api_nan_setter"></a> +### Setter declaration + +JavaScript-accessible setters should be declared with the following signature to form a <b><code>Nan::SetterCallback</code></b>: + +```c++ +typedef void(*SetterCallback)(v8::Local<v8::String>, + v8::Local<v8::Value>, + const PropertyCallbackInfo<void>&); +``` + +Example: + +```c++ +void SetterName(v8::Local<v8::String> property, + v8::Local<v8::Value> value, + const Nan::PropertyCallbackInfo<void>& info) { + ... +} +``` + +You do not need to declare a new `HandleScope` within a setter as one is implicitly created for you. + +A helper macro `NAN_SETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on [Accessors](https://developers.google.com/v8/embed#accesssors). + +<a name="api_nan_property_getter"></a> +### Property getter declaration + +JavaScript-accessible property getters should be declared with the following signature to form a <b><code>Nan::PropertyGetterCallback</code></b>: + +```c++ +typedef void(*PropertyGetterCallback)(v8::Local<v8::String>, + const PropertyCallbackInfo<v8::Value>&); +``` + +Example: + +```c++ +void PropertyGetterName(v8::Local<v8::String> property, + const Nan::PropertyCallbackInfo<v8::Value>& info) { + ... +} +``` + +You do not need to declare a new `HandleScope` within a property getter as one is implicitly created for you. + +A helper macro `NAN_PROPERTY_GETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on named property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_property_setter"></a> +### Property setter declaration + +JavaScript-accessible property setters should be declared with the following signature to form a <b><code>Nan::PropertySetterCallback</code></b>: + +```c++ +typedef void(*PropertySetterCallback)(v8::Local<v8::String>, + v8::Local<v8::Value>, + const PropertyCallbackInfo<v8::Value>&); +``` + +Example: + +```c++ +void PropertySetterName(v8::Local<v8::String> property, + v8::Local<v8::Value> value, + const Nan::PropertyCallbackInfo<v8::Value>& info); +``` + +You do not need to declare a new `HandleScope` within a property setter as one is implicitly created for you. + +A helper macro `NAN_PROPERTY_SETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on named property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_property_enumerator"></a> +### Property enumerator declaration + +JavaScript-accessible property enumerators should be declared with the following signature to form a <b><code>Nan::PropertyEnumeratorCallback</code></b>: + +```c++ +typedef void(*PropertyEnumeratorCallback)(const PropertyCallbackInfo<v8::Array>&); +``` + +Example: + +```c++ +void PropertyEnumeratorName(const Nan::PropertyCallbackInfo<v8::Array>& info); +``` + +You do not need to declare a new `HandleScope` within a property enumerator as one is implicitly created for you. + +A helper macro `NAN_PROPERTY_ENUMERATOR(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on named property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_property_deleter"></a> +### Property deleter declaration + +JavaScript-accessible property deleters should be declared with the following signature to form a <b><code>Nan::PropertyDeleterCallback</code></b>: + +```c++ +typedef void(*PropertyDeleterCallback)(v8::Local<v8::String>, + const PropertyCallbackInfo<v8::Boolean>&); +``` + +Example: + +```c++ +void PropertyDeleterName(v8::Local<v8::String> property, + const Nan::PropertyCallbackInfo<v8::Boolean>& info); +``` + +You do not need to declare a new `HandleScope` within a property deleter as one is implicitly created for you. + +A helper macro `NAN_PROPERTY_DELETER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on named property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_property_query"></a> +### Property query declaration + +JavaScript-accessible property query methods should be declared with the following signature to form a <b><code>Nan::PropertyQueryCallback</code></b>: + +```c++ +typedef void(*PropertyQueryCallback)(v8::Local<v8::String>, + const PropertyCallbackInfo<v8::Integer>&); +``` + +Example: + +```c++ +void PropertyQueryName(v8::Local<v8::String> property, + const Nan::PropertyCallbackInfo<v8::Integer>& info); +``` + +You do not need to declare a new `HandleScope` within a property query method as one is implicitly created for you. + +A helper macro `NAN_PROPERTY_QUERY(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on named property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_index_getter"></a> +### Index getter declaration + +JavaScript-accessible index getter methods should be declared with the following signature to form a <b><code>Nan::IndexGetterCallback</code></b>: + +```c++ +typedef void(*IndexGetterCallback)(uint32_t, + const PropertyCallbackInfo<v8::Value>&); +``` + +Example: + +```c++ +void IndexGetterName(uint32_t index, const PropertyCallbackInfo<v8::Value>& info); +``` + +You do not need to declare a new `HandleScope` within a index getter as one is implicitly created for you. + +A helper macro `NAN_INDEX_GETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on indexed property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_index_setter"></a> +### Index setter declaration + +JavaScript-accessible index setter methods should be declared with the following signature to form a <b><code>Nan::IndexSetterCallback</code></b>: + +```c++ +typedef void(*IndexSetterCallback)(uint32_t, + v8::Local<v8::Value>, + const PropertyCallbackInfo<v8::Value>&); +``` + +Example: + +```c++ +void IndexSetterName(uint32_t index, + v8::Local<v8::Value> value, + const PropertyCallbackInfo<v8::Value>& info); +``` + +You do not need to declare a new `HandleScope` within a index setter as one is implicitly created for you. + +A helper macro `NAN_INDEX_SETTER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on indexed property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_index_enumerator"></a> +### Index enumerator declaration + +JavaScript-accessible index enumerator methods should be declared with the following signature to form a <b><code>Nan::IndexEnumeratorCallback</code></b>: + +```c++ +typedef void(*IndexEnumeratorCallback)(const PropertyCallbackInfo<v8::Array>&); +``` + +Example: + +```c++ +void IndexEnumeratorName(const PropertyCallbackInfo<v8::Array>& info); +``` + +You do not need to declare a new `HandleScope` within a index enumerator as one is implicitly created for you. + +A helper macro `NAN_INDEX_ENUMERATOR(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on indexed property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_index_deleter"></a> +### Index deleter declaration + +JavaScript-accessible index deleter methods should be declared with the following signature to form a <b><code>Nan::IndexDeleterCallback</code></b>: + +```c++ +typedef void(*IndexDeleterCallback)(uint32_t, + const PropertyCallbackInfo<v8::Boolean>&); +``` + +Example: + +```c++ +void IndexDeleterName(uint32_t index, const PropertyCallbackInfo<v8::Boolean>& info); +``` + +You do not need to declare a new `HandleScope` within a index deleter as one is implicitly created for you. + +A helper macro `NAN_INDEX_DELETER(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on indexed property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_index_query"></a> +### Index query declaration + +JavaScript-accessible index query methods should be declared with the following signature to form a <b><code>Nan::IndexQueryCallback</code></b>: + +```c++ +typedef void(*IndexQueryCallback)(uint32_t, + const PropertyCallbackInfo<v8::Integer>&); +``` + +Example: + +```c++ +void IndexQueryName(uint32_t index, const PropertyCallbackInfo<v8::Integer>& info); +``` + +You do not need to declare a new `HandleScope` within a index query method as one is implicitly created for you. + +A helper macro `NAN_INDEX_QUERY(methodname)` exists, compatible with NAN v1 method declarations. + +Also see the V8 Embedders Guide documentation on indexed property [Interceptors](https://developers.google.com/v8/embed#interceptors). + +<a name="api_nan_set_method"></a> +### Nan::SetMethod() + +Sets a method with a given name directly on a JavaScript object where the method has the `Nan::FunctionCallback` signature (see <a href="#api_nan_method">Method declaration</a>). + +Signature: + +```c++ +void Nan::SetMethod(v8::Local<v8::Object> recv, + const char *name, + Nan::FunctionCallback callback, + v8::Local<v8::Value> data = v8::Local<v8::Value>()) +void Nan::SetMethod(v8::Local<v8::Template> templ, + const char *name, + Nan::FunctionCallback callback, + v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +<a name="api_nan_set_prototype_method"></a> +### Nan::SetPrototypeMethod() + +Sets a method with a given name on a `FunctionTemplate`'s prototype where the method has the `Nan::FunctionCallback` signature (see <a href="#api_nan_method">Method declaration</a>). + +Signature: + +```c++ +void Nan::SetPrototypeMethod(v8::Local<v8::FunctionTemplate> recv, + const char* name, + Nan::FunctionCallback callback, + v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +<a name="api_nan_set_accessor"></a> +### Nan::SetAccessor() + +Sets getters and setters for a property with a given name on an `ObjectTemplate` or a plain `Object`. Accepts getters with the `Nan::GetterCallback` signature (see <a href="#api_nan_getter">Getter declaration</a>) and setters with the `Nan::SetterCallback` signature (see <a href="#api_nan_setter">Setter declaration</a>). + +Signature: + +```c++ +void SetAccessor(v8::Local<v8::ObjectTemplate> tpl, + v8::Local<v8::String> name, + Nan::GetterCallback getter, + Nan::SetterCallback setter = 0, + v8::Local<v8::Value> data = v8::Local<v8::Value>(), + v8::AccessControl settings = v8::DEFAULT, + v8::PropertyAttribute attribute = v8::None, + imp::Sig signature = imp::Sig()); +bool SetAccessor(v8::Local<v8::Object> obj, + v8::Local<v8::String> name, + Nan::GetterCallback getter, + Nan::SetterCallback setter = 0, + v8::Local<v8::Value> data = v8::Local<v8::Value>(), + v8::AccessControl settings = v8::DEFAULT, + v8::PropertyAttribute attribute = v8::None) +``` + +See the V8 [`ObjectTemplate#SetAccessor()`](https://v8docs.nodesource.com/node-8.16/db/d5f/classv8_1_1_object_template.html#aca0ed196f8a9adb1f68b1aadb6c9cd77) and [`Object#SetAccessor()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ae91b3b56b357f285288c89fbddc46d1b) for further information about how to use `Nan::SetAccessor()`. + +<a name="api_nan_set_named_property_handler"></a> +### Nan::SetNamedPropertyHandler() + +Sets named property getters, setters, query, deleter and enumerator methods on an `ObjectTemplate`. Accepts: + +* Property getters with the `Nan::PropertyGetterCallback` signature (see <a href="#api_nan_property_getter">Property getter declaration</a>) +* Property setters with the `Nan::PropertySetterCallback` signature (see <a href="#api_nan_property_setter">Property setter declaration</a>) +* Property query methods with the `Nan::PropertyQueryCallback` signature (see <a href="#api_nan_property_query">Property query declaration</a>) +* Property deleters with the `Nan::PropertyDeleterCallback` signature (see <a href="#api_nan_property_deleter">Property deleter declaration</a>) +* Property enumerators with the `Nan::PropertyEnumeratorCallback` signature (see <a href="#api_nan_property_enumerator">Property enumerator declaration</a>) + +Signature: + +```c++ +void SetNamedPropertyHandler(v8::Local<v8::ObjectTemplate> tpl, + Nan::PropertyGetterCallback getter, + Nan::PropertySetterCallback setter = 0, + Nan::PropertyQueryCallback query = 0, + Nan::PropertyDeleterCallback deleter = 0, + Nan::PropertyEnumeratorCallback enumerator = 0, + v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +See the V8 [`ObjectTemplate#SetNamedPropertyHandler()`](https://v8docs.nodesource.com/node-8.16/db/d5f/classv8_1_1_object_template.html#a33b3ebd7de641f6cc6414b7de01fc1c7) for further information about how to use `Nan::SetNamedPropertyHandler()`. + +<a name="api_nan_set_indexed_property_handler"></a> +### Nan::SetIndexedPropertyHandler() + +Sets indexed property getters, setters, query, deleter and enumerator methods on an `ObjectTemplate`. Accepts: + +* Indexed property getters with the `Nan::IndexGetterCallback` signature (see <a href="#api_nan_index_getter">Index getter declaration</a>) +* Indexed property setters with the `Nan::IndexSetterCallback` signature (see <a href="#api_nan_index_setter">Index setter declaration</a>) +* Indexed property query methods with the `Nan::IndexQueryCallback` signature (see <a href="#api_nan_index_query">Index query declaration</a>) +* Indexed property deleters with the `Nan::IndexDeleterCallback` signature (see <a href="#api_nan_index_deleter">Index deleter declaration</a>) +* Indexed property enumerators with the `Nan::IndexEnumeratorCallback` signature (see <a href="#api_nan_index_enumerator">Index enumerator declaration</a>) + +Signature: + +```c++ +void SetIndexedPropertyHandler(v8::Local<v8::ObjectTemplate> tpl, + Nan::IndexGetterCallback getter, + Nan::IndexSetterCallback setter = 0, + Nan::IndexQueryCallback query = 0, + Nan::IndexDeleterCallback deleter = 0, + Nan::IndexEnumeratorCallback enumerator = 0, + v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +See the V8 [`ObjectTemplate#SetIndexedPropertyHandler()`](https://v8docs.nodesource.com/node-8.16/db/d5f/classv8_1_1_object_template.html#ac89f06d634add0e890452033f7d17ff1) for further information about how to use `Nan::SetIndexedPropertyHandler()`. + +<a name="api_nan_set_template"></a> +### Nan::SetTemplate() + +Adds properties on an `Object`'s or `Function`'s template. + +Signature: + +```c++ +void Nan::SetTemplate(v8::Local<v8::Template> templ, + const char *name, + v8::Local<v8::Data> value); +void Nan::SetTemplate(v8::Local<v8::Template> templ, + v8::Local<v8::String> name, + v8::Local<v8::Data> value, + v8::PropertyAttribute attributes) +``` + +Calls the `Template`'s [`Set()`](https://v8docs.nodesource.com/node-8.16/db/df7/classv8_1_1_template.html#ae3fbaff137557aa6a0233bc7e52214ac). + +<a name="api_nan_set_prototype_template"></a> +### Nan::SetPrototypeTemplate() + +Adds properties on an `Object`'s or `Function`'s prototype template. + +Signature: + +```c++ +void Nan::SetPrototypeTemplate(v8::Local<v8::FunctionTemplate> templ, + const char *name, + v8::Local<v8::Data> value); +void Nan::SetPrototypeTemplate(v8::Local<v8::FunctionTemplate> templ, + v8::Local<v8::String> name, + v8::Local<v8::Data> value, + v8::PropertyAttribute attributes) +``` + +Calls the `FunctionTemplate`'s _PrototypeTemplate's_ [`Set()`](https://v8docs.nodesource.com/node-8.16/db/df7/classv8_1_1_template.html#a2db6a56597bf23c59659c0659e564ddf). + +<a name="api_nan_set_instance_template"></a> +### Nan::SetInstanceTemplate() + +Use to add instance properties on `FunctionTemplate`'s. + +Signature: + +```c++ +void Nan::SetInstanceTemplate(v8::Local<v8::FunctionTemplate> templ, + const char *name, + v8::Local<v8::Data> value); +void Nan::SetInstanceTemplate(v8::Local<v8::FunctionTemplate> templ, + v8::Local<v8::String> name, + v8::Local<v8::Data> value, + v8::PropertyAttribute attributes) +``` + +Calls the `FunctionTemplate`'s _InstanceTemplate's_ [`Set()`](https://v8docs.nodesource.com/node-8.16/db/df7/classv8_1_1_template.html#a2db6a56597bf23c59659c0659e564ddf). + +<a name="api_nan_set_call_handler"></a> +### Nan::SetCallHandler() + +Set the call-handler callback for a `v8::FunctionTemplate`. +This callback is called whenever the function created from this FunctionTemplate is called. + +Signature: + +```c++ +void Nan::SetCallHandler(v8::Local<v8::FunctionTemplate> templ, Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +Calls the `FunctionTemplate`'s [`SetCallHandler()`](https://v8docs.nodesource.com/node-8.16/d8/d83/classv8_1_1_function_template.html#ab7574b298db3c27fbc2ed465c08ea2f8). + +<a name="api_nan_set_call_as_function_handler"></a> +### Nan::SetCallAsFunctionHandler() + +Sets the callback to be used when calling instances created from the `v8::ObjectTemplate` as a function. +If no callback is set, instances behave like normal JavaScript objects that cannot be called as a function. + +Signature: + +```c++ +void Nan::SetCallAsFunctionHandler(v8::Local<v8::ObjectTemplate> templ, Nan::FunctionCallback callback, v8::Local<v8::Value> data = v8::Local<v8::Value>()) +``` + +Calls the `ObjectTemplate`'s [`SetCallAsFunctionHandler()`](https://v8docs.nodesource.com/node-8.16/db/d5f/classv8_1_1_object_template.html#a5e9612fc80bf6db8f2da199b9b0bd04e). + diff --git a/node_modules/nan/doc/new.md b/node_modules/nan/doc/new.md new file mode 100644 index 0000000..0f28a0e --- /dev/null +++ b/node_modules/nan/doc/new.md @@ -0,0 +1,147 @@ +## 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. + + - <a href="#api_nan_new"><b><code>Nan::New()</code></b></a> + - <a href="#api_nan_undefined"><b><code>Nan::Undefined()</code></b></a> + - <a href="#api_nan_null"><b><code>Nan::Null()</code></b></a> + - <a href="#api_nan_true"><b><code>Nan::True()</code></b></a> + - <a href="#api_nan_false"><b><code>Nan::False()</code></b></a> + - <a href="#api_nan_empty_string"><b><code>Nan::EmptyString()</code></b></a> + + +<a name="api_nan_new"></a> +### Nan::New() + +`Nan::New()` should be used to instantiate new JavaScript objects. + +Refer to the specific V8 type in the [V8 documentation](https://v8docs.nodesource.com/node-8.16/d1/d83/classv8_1_1_data.html) for information on the types of arguments required for instantiation. + +Signatures: + +Return types are mostly omitted from the signatures for simplicity. In most cases the type will be contained within a `v8::Local<T>`. The following types will be contained within a `Nan::MaybeLocal<T>`: `v8::String`, `v8::Date`, `v8::RegExp`, `v8::Script`, `v8::UnboundScript`. + +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: + +_The definition of `Nan::FunctionCallback` can be found in the [Method declaration](./methods.md#api_nan_method) documentation._ + +```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); +``` + +Note that `Nan::ExternalOneByteStringResource` maps to [`v8::String::ExternalOneByteStringResource`](https://v8docs.nodesource.com/node-8.16/d9/db3/classv8_1_1_string_1_1_external_one_byte_string_resource.html), and `v8::String::ExternalAsciiStringResource` in older versions of V8. + + +<a name="api_nan_undefined"></a> +### Nan::Undefined() + +A helper method to reference the `v8::Undefined` object in a way that is compatible across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::Primitive> Nan::Undefined() +``` + +<a name="api_nan_null"></a> +### Nan::Null() + +A helper method to reference the `v8::Null` object in a way that is compatible across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::Primitive> Nan::Null() +``` + +<a name="api_nan_true"></a> +### Nan::True() + +A helper method to reference the `v8::Boolean` object representing the `true` value in a way that is compatible across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::Boolean> Nan::True() +``` + +<a name="api_nan_false"></a> +### Nan::False() + +A helper method to reference the `v8::Boolean` object representing the `false` value in a way that is compatible across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::Boolean> Nan::False() +``` + +<a name="api_nan_empty_string"></a> +### Nan::EmptyString() + +Call [`v8::String::Empty`](https://v8docs.nodesource.com/node-8.16/d2/db3/classv8_1_1_string.html#a7c1bc8886115d7ee46f1d571dd6ebc6d) to reference the empty string in a way that is compatible across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::String> Nan::EmptyString() +``` + + +<a name="api_nan_new_one_byte_string"></a> +### Nan::NewOneByteString() + +An implementation of [`v8::String::NewFromOneByte()`](https://v8docs.nodesource.com/node-8.16/d2/db3/classv8_1_1_string.html#a5264d50b96d2c896ce525a734dc10f09) provided for consistent availability and API across supported versions of V8. Allocates a new string from Latin-1 data. + +Signature: + +```c++ +Nan::MaybeLocal<v8::String> Nan::NewOneByteString(const uint8_t * value, + int length = -1) +``` diff --git a/node_modules/nan/doc/node_misc.md b/node_modules/nan/doc/node_misc.md new file mode 100644 index 0000000..17578e3 --- /dev/null +++ b/node_modules/nan/doc/node_misc.md @@ -0,0 +1,123 @@ +## Miscellaneous Node Helpers + + - <a href="#api_nan_asyncresource"><b><code>Nan::AsyncResource</code></b></a> + - <a href="#api_nan_make_callback"><b><code>Nan::MakeCallback()</code></b></a> + - <a href="#api_nan_module_init"><b><code>NAN_MODULE_INIT()</code></b></a> + - <a href="#api_nan_export"><b><code>Nan::Export()</code></b></a> + +<a name="api_nan_asyncresource"></a> +### Nan::AsyncResource + +This class is analogous to the `AsyncResource` JavaScript class exposed by Node's [async_hooks][] API. + +When calling back into JavaScript asynchronously, special care must be taken to ensure that the runtime can properly track +async hops. `Nan::AsyncResource` is a class that provides an RAII wrapper around `node::EmitAsyncInit`, `node::EmitAsyncDestroy`, +and `node::MakeCallback`. Using this mechanism to call back into JavaScript, as opposed to `Nan::MakeCallback` or +`v8::Function::Call` ensures that the callback is executed in the correct async context. This ensures that async mechanisms +such as domains and [async_hooks][] function correctly. + +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); +}; +``` + +* `name`: Identifier for the kind of resource that is being provided for diagnostics information exposed by the [async_hooks][] + API. This will be passed to the possible `init` hook as the `type`. To avoid name collisions with other modules we recommend + that the name include the name of the owning module as a prefix. For example `mysql` module could use something like + `mysql:batch-db-query-resource`. +* `resource`: An optional object associated with the async work that will be passed to the possible [async_hooks][] + `init` hook. If this parameter is omitted, or an empty handle is provided, this object will be created automatically. +* When calling JS on behalf of this resource, one can use `runInAsyncScope`. This will ensure that the callback runs in the + correct async execution context. +* `AsyncDestroy` is automatically called when an AsyncResource object is destroyed. + +For more details, see the Node [async_hooks][] documentation. You might also want to take a look at the documentation for the +[N-API counterpart][napi]. For example usage, see the `asyncresource.cpp` example in the `test/cpp` directory. + +<a name="api_nan_make_callback"></a> +### Nan::MakeCallback() + +Deprecated wrappers around the legacy `node::MakeCallback()` APIs. Node.js 10+ +has deprecated these legacy APIs as they do not provide a mechanism to preserve +async context. + +We recommend that you use the `AsyncResource` class and `AsyncResource::runInAsyncScope` instead of using `Nan::MakeCallback` or +`v8::Function#Call()` directly. `AsyncResource` properly takes care of running the callback in the correct async execution +context – something that is essential for functionality like domains, async_hooks and async debugging. + +Signatures: + +```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); +``` + + +<a name="api_nan_module_init"></a> +### NAN_MODULE_INIT() + +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. + +See example below. + +<a name="api_nan_export"></a> +### Nan::Export() + +A simple helper to register a `v8::FunctionTemplate` from a JavaScript-accessible method (see [Methods](./methods.md)) as a property on an object. Can be used in a way similar to assigning properties to `module.exports` in JavaScript. + +Signature: + +```c++ +void Export(v8::Local<v8::Object> target, const char *name, Nan::FunctionCallback f) +``` + +Also available as the shortcut `NAN_EXPORT` macro. + +Example: + +```c++ +NAN_METHOD(Foo) { + ... +} + +NAN_MODULE_INIT(Init) { + NAN_EXPORT(target, Foo); +} +``` + +[async_hooks]: https://nodejs.org/dist/latest-v9.x/docs/api/async_hooks.html +[napi]: https://nodejs.org/dist/latest-v9.x/docs/api/n-api.html#n_api_custom_asynchronous_operations diff --git a/node_modules/nan/doc/object_wrappers.md b/node_modules/nan/doc/object_wrappers.md new file mode 100644 index 0000000..07d8c05 --- /dev/null +++ b/node_modules/nan/doc/object_wrappers.md @@ -0,0 +1,263 @@ +## Object Wrappers + +The `ObjectWrap` class can be used to make wrapped C++ objects and a factory of wrapped objects. + + - <a href="#api_nan_object_wrap"><b><code>Nan::ObjectWrap</code></b></a> + + +<a name="api_nan_object_wrap"></a> +### Nan::ObjectWrap() + +A reimplementation of `node::ObjectWrap` that adds some API not present in older versions of Node. Should be preferred over `node::ObjectWrap` in all cases for consistency. + +Definition: + +```c++ +class ObjectWrap { + public: + ObjectWrap(); + + virtual ~ObjectWrap(); + + template <class T> + static inline T* Unwrap(v8::Local<v8::Object> handle); + + inline v8::Local<v8::Object> handle(); + + inline Nan::Persistent<v8::Object>& persistent(); + + protected: + inline void Wrap(v8::Local<v8::Object> handle); + + inline void MakeWeak(); + + /* Ref() marks the object as being attached to an event loop. + * Refed objects will not be garbage collected, even if + * all references are lost. + */ + virtual void Ref(); + + /* Unref() marks an object as detached from the event loop. This is its + * default state. When an object with a "weak" reference changes from + * attached to detached state it will be freed. Be careful not to access + * the object after making this call as it might be gone! + * (A "weak reference" means an object that only has a + * persistent handle.) + * + * DO NOT CALL THIS FROM DESTRUCTOR + */ + virtual void Unref(); + + int refs_; // ro +}; +``` + +See the Node documentation on [Wrapping C++ Objects](https://nodejs.org/api/addons.html#addons_wrapping_c_objects) for more details. + +### This vs. Holder + +When calling `Unwrap`, it is important that the argument is indeed some JavaScript object which got wrapped by a `Wrap` call for this class or any derived class. +The `Signature` installed by [`Nan::SetPrototypeMethod()`](methods.md#api_nan_set_prototype_method) does ensure that `info.Holder()` is just such an instance. +In Node 0.12 and later, `info.This()` will also be of such a type, since otherwise the invocation will get rejected. +However, in Node 0.10 and before it was possible to invoke a method on a JavaScript object which just had the extension type in its prototype chain. +In such a situation, calling `Unwrap` on `info.This()` will likely lead to a failed assertion causing a crash, but could lead to even more serious corruption. + +On the other hand, calling `Unwrap` in an [accessor](methods.md#api_nan_set_accessor) should not use `Holder()` if the accessor is defined on the prototype. +So either define your accessors on the instance template, +or use `This()` after verifying that it is indeed a valid object. + +### Examples + +#### Basic + +```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) +``` + +To use in Javascript: + +```Javascript +var objectwrapper = require('bindings')('objectwrapper'); + +var obj = new objectwrapper.MyObject(5); +console.log('Should be 5: ' + obj.getValue()); +``` + +#### Factory of wrapped objects + +```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) +``` + +To use in Javascript: + +```Javascript +var wrappedobjectfactory = require('bindings')('wrappedobjectfactory'); + +var obj = wrappedobjectfactory.newFactoryObjectInstance(10); +console.log('Should be 10: ' + obj.getValue()); +``` + +#### Passing wrapped objects around + +Use the `MyFactoryObject` class above along with the following: + +```c++ +static NAN_METHOD(Sum) { + Nan::MaybeLocal<v8::Object> maybe1 = Nan::To<v8::Object>(info[0]); + Nan::MaybeLocal<v8::Object> maybe2 = Nan::To<v8::Object>(info[1]); + + // Quick check: + if (maybe1.IsEmpty() || maybe2.IsEmpty()) { + // return value is undefined by default + return; + } + + MyFactoryObject* obj1 = + Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe1.ToLocalChecked()); + MyFactoryObject* obj2 = + Nan::ObjectWrap::Unwrap<MyFactoryObject>(maybe2.ToLocalChecked()); + + info.GetReturnValue().Set(Nan::New<v8::Number>(obj1->value() + obj2->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() + ); + Nan::Set(target, + Nan::New<v8::String>("sum").ToLocalChecked(), + Nan::GetFunction(Nan::New<v8::FunctionTemplate>(Sum)).ToLocalChecked() + ); +} + +NODE_MODULE(myaddon, Init) +``` + +To use in Javascript: + +```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)); +``` diff --git a/node_modules/nan/doc/persistent.md b/node_modules/nan/doc/persistent.md new file mode 100644 index 0000000..2e13f6b --- /dev/null +++ b/node_modules/nan/doc/persistent.md @@ -0,0 +1,296 @@ +## 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. + + - <a href="#api_nan_persistent_base"><b><code>Nan::PersistentBase & v8::PersistentBase</code></b></a> + - <a href="#api_nan_non_copyable_persistent_traits"><b><code>Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits</code></b></a> + - <a href="#api_nan_copyable_persistent_traits"><b><code>Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits</code></b></a> + - <a href="#api_nan_persistent"><b><code>Nan::Persistent</code></b></a> + - <a href="#api_nan_global"><b><code>Nan::Global</code></b></a> + - <a href="#api_nan_weak_callback_info"><b><code>Nan::WeakCallbackInfo</code></b></a> + - <a href="#api_nan_weak_callback_type"><b><code>Nan::WeakCallbackType</code></b></a> + +Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://developers.google.com/v8/embed#handles). + +<a name="api_nan_persistent_base"></a> +### Nan::PersistentBase & v8::PersistentBase + +A persistent handle contains a reference to a storage cell in V8 which holds an object value and which is updated by the garbage collector whenever the object is moved. A new storage cell can be created using the constructor or `Nan::PersistentBase::Reset()`. Existing handles can be disposed using an argument-less `Nan::PersistentBase::Reset()`. + +Definition: + +_(note: this is implemented as `Nan::PersistentBase` for older versions of V8 and the native `v8::PersistentBase` is used for newer versions of V8)_ + +```c++ +template<typename T> class PersistentBase { + public: + /** + * If non-empty, destroy the underlying storage cell + */ + void Reset(); + + /** + * If non-empty, destroy the underlying storage cell and create a new one with + * the contents of another if it is also non-empty + */ + template<typename S> void Reset(const v8::Local<S> &other); + + /** + * If non-empty, destroy the underlying storage cell and create a new one with + * the contents of another if it is also non-empty + */ + template<typename S> void Reset(const PersistentBase<S> &other); + + /** Returns true if the handle is empty. */ + bool IsEmpty() const; + + /** + * If non-empty, destroy the underlying storage cell + * IsEmpty() will return true after this call. + */ + void Empty(); + + template<typename S> bool operator==(const PersistentBase<S> &that); + + template<typename S> bool operator==(const v8::Local<S> &that); + + template<typename S> bool operator!=(const PersistentBase<S> &that); + + template<typename S> bool operator!=(const v8::Local<S> &that); + + /** + * Install a finalization callback on this object. + * NOTE: There is no guarantee as to *when* or even *if* the callback is + * invoked. The invocation is performed solely on a best effort basis. + * As always, GC-based finalization should *not* be relied upon for any + * critical form of resource management! At the moment you can either + * specify a parameter for the callback or the location of two internal + * fields in the dying object. + */ + template<typename P> + void SetWeak(P *parameter, + typename WeakCallbackInfo<P>::Callback callback, + WeakCallbackType type); + + void ClearWeak(); + + /** + * Marks the reference to this object independent. Garbage collector is free + * to ignore any object groups containing this object. Weak callback for an + * independent handle should not assume that it will be preceded by a global + * GC prologue callback or followed by a global GC epilogue callback. + */ + void MarkIndependent() const; + + bool IsIndependent() const; + + /** Checks if the handle holds the only reference to an object. */ + bool IsNearDeath() const; + + /** Returns true if the handle's reference is weak. */ + bool IsWeak() const +}; +``` + +See the V8 documentation for [`PersistentBase`](https://v8docs.nodesource.com/node-8.16/d4/dca/classv8_1_1_persistent_base.html) for further information. + +**Tip:** To get a `v8::Local` reference to the original object back from a `PersistentBase` or `Persistent` object: + +```c++ +v8::Local<v8::Object> object = Nan::New(persistent); +``` + +<a name="api_nan_non_copyable_persistent_traits"></a> +### Nan::NonCopyablePersistentTraits & v8::NonCopyablePersistentTraits + +Default traits for `Nan::Persistent`. This class does not allow use of the a copy constructor or assignment operator. At present `kResetInDestructor` is not set, but that will change in a future version. + +Definition: + +_(note: this is implemented as `Nan::NonCopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_ + +```c++ +template<typename T> class NonCopyablePersistentTraits { + public: + typedef Persistent<T, NonCopyablePersistentTraits<T> > NonCopyablePersistent; + + static const bool kResetInDestructor = false; + + template<typename S, typename M> + static void Copy(const Persistent<S, M> &source, + NonCopyablePersistent *dest); + + template<typename O> static void Uncompilable(); +}; +``` + +See the V8 documentation for [`NonCopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/de/d73/classv8_1_1_non_copyable_persistent_traits.html) for further information. + +<a name="api_nan_copyable_persistent_traits"></a> +### Nan::CopyablePersistentTraits & v8::CopyablePersistentTraits + +A helper class of traits to allow copying and assignment of `Persistent`. This will clone the contents of storage cell, but not any of the flags, etc.. + +Definition: + +_(note: this is implemented as `Nan::CopyablePersistentTraits` for older versions of V8 and the native `v8::NonCopyablePersistentTraits` is used for newer versions of V8)_ + +```c++ +template<typename T> +class CopyablePersistentTraits { + public: + typedef Persistent<T, CopyablePersistentTraits<T> > CopyablePersistent; + + static const bool kResetInDestructor = true; + + template<typename S, typename M> + static void Copy(const Persistent<S, M> &source, + CopyablePersistent *dest); +}; +``` + +See the V8 documentation for [`CopyablePersistentTraits`](https://v8docs.nodesource.com/node-8.16/da/d5c/structv8_1_1_copyable_persistent_traits.html) for further information. + +<a name="api_nan_persistent"></a> +### Nan::Persistent + +A type of `PersistentBase` which allows copy and assignment. Copy, assignment and destructor behavior is controlled by the traits class `M`. + +Definition: + +```c++ +template<typename T, typename M = NonCopyablePersistentTraits<T> > +class Persistent; + +template<typename T, typename M> class Persistent : public PersistentBase<T> { + public: + /** + * A Persistent with no storage cell. + */ + Persistent(); + + /** + * Construct a Persistent from a v8::Local. When the v8::Local is non-empty, a + * new storage cell is created pointing to the same object, and no flags are + * set. + */ + template<typename S> Persistent(v8::Local<S> that); + + /** + * Construct a Persistent from a Persistent. When the Persistent is non-empty, + * a new storage cell is created pointing to the same object, and no flags are + * set. + */ + Persistent(const Persistent &that); + + /** + * The copy constructors and assignment operator create a Persistent exactly + * as the Persistent constructor, but the Copy function from the traits class + * is called, allowing the setting of flags based on the copied Persistent. + */ + Persistent &operator=(const Persistent &that); + + template <typename S, typename M2> + Persistent &operator=(const Persistent<S, M2> &that); + + /** + * The destructor will dispose the Persistent based on the kResetInDestructor + * flags in the traits class. Since not calling dispose can result in a + * memory leak, it is recommended to always set this flag. + */ + ~Persistent(); +}; +``` + +See the V8 documentation for [`Persistent`](https://v8docs.nodesource.com/node-8.16/d2/d78/classv8_1_1_persistent.html) for further information. + +<a name="api_nan_global"></a> +### Nan::Global + +A type of `PersistentBase` which has move semantics. + +```c++ +template<typename T> class Global : public PersistentBase<T> { + public: + /** + * A Global with no storage cell. + */ + Global(); + + /** + * Construct a Global from a v8::Local. When the v8::Local is non-empty, a new + * storage cell is created pointing to the same object, and no flags are set. + */ + template<typename S> Global(v8::Local<S> that); + /** + * Construct a Global from a PersistentBase. When the Persistent is non-empty, + * a new storage cell is created pointing to the same object, and no flags are + * set. + */ + template<typename S> Global(const PersistentBase<S> &that); + + /** + * Pass allows returning globals from functions, etc. + */ + Global Pass(); +}; +``` + +See the V8 documentation for [`Global`](https://v8docs.nodesource.com/node-8.16/d5/d40/classv8_1_1_global.html) for further information. + +<a name="api_nan_weak_callback_info"></a> +### Nan::WeakCallbackInfo + +`Nan::WeakCallbackInfo` is used as an argument when setting a persistent reference as weak. You may need to free any external resources attached to the object. It is a mirror of `v8:WeakCallbackInfo` as found in newer versions of V8. + +Definition: + +```c++ +template<typename T> class WeakCallbackInfo { + public: + typedef void (*Callback)(const WeakCallbackInfo<T>& data); + + v8::Isolate *GetIsolate() const; + + /** + * Get the parameter that was associated with the weak handle. + */ + T *GetParameter() const; + + /** + * Get pointer from internal field, index can be 0 or 1. + */ + void *GetInternalField(int index) const; +}; +``` + +Example usage: + +```c++ +void weakCallback(const WeakCallbackInfo<int> &data) { + int *parameter = data.GetParameter(); + delete parameter; +} + +Persistent<v8::Object> obj; +int *data = new int(0); +obj.SetWeak(data, callback, WeakCallbackType::kParameter); +``` + +See the V8 documentation for [`WeakCallbackInfo`](https://v8docs.nodesource.com/node-8.16/d8/d06/classv8_1_1_weak_callback_info.html) for further information. + +<a name="api_nan_weak_callback_type"></a> +### Nan::WeakCallbackType + +Represents the type of a weak callback. +A weak callback of type `kParameter` makes the supplied parameter to `Nan::PersistentBase::SetWeak` available through `WeakCallbackInfo::GetParameter`. +A weak callback of type `kInternalFields` uses up to two internal fields at indices 0 and 1 on the `Nan::PersistentBase<v8::Object>` being made weak. +Note that only `v8::Object`s and derivatives can have internal fields. + +Definition: + +```c++ +enum class WeakCallbackType { kParameter, kInternalFields }; +``` diff --git a/node_modules/nan/doc/scopes.md b/node_modules/nan/doc/scopes.md new file mode 100644 index 0000000..84000ee --- /dev/null +++ b/node_modules/nan/doc/scopes.md @@ -0,0 +1,73 @@ +## 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. + + - <a href="#api_nan_handle_scope"><b><code>Nan::HandleScope</code></b></a> + - <a href="#api_nan_escapable_handle_scope"><b><code>Nan::EscapableHandleScope</code></b></a> + +Also see the V8 Embedders Guide section on [Handles and Garbage Collection](https://github.com/v8/v8/wiki/Embedder%27s%20Guide#handles-and-garbage-collection). + +<a name="api_nan_handle_scope"></a> +### Nan::HandleScope + +A simple wrapper around [`v8::HandleScope`](https://v8docs.nodesource.com/node-8.16/d3/d95/classv8_1_1_handle_scope.html). + +Definition: + +```c++ +class Nan::HandleScope { + public: + Nan::HandleScope(); + static int NumberOfHandles(); +}; +``` + +Allocate a new `Nan::HandleScope` whenever you are creating new V8 JavaScript objects. Note that an implicit `HandleScope` is created for you on JavaScript-accessible methods so you do not need to insert one yourself. + +Example: + +```c++ +// new object is created, it needs a new scope: +void Pointless() { + Nan::HandleScope scope; + v8::Local<v8::Object> obj = Nan::New<v8::Object>(); +} + +// JavaScript-accessible method already has a HandleScope +NAN_METHOD(Pointless2) { + v8::Local<v8::Object> obj = Nan::New<v8::Object>(); +} +``` + +<a name="api_nan_escapable_handle_scope"></a> +### Nan::EscapableHandleScope + +Similar to [`Nan::HandleScope`](#api_nan_handle_scope) but should be used in cases where a function needs to return a V8 JavaScript type that has been created within it. + +Definition: + +```c++ +class Nan::EscapableHandleScope { + public: + Nan::EscapableHandleScope(); + static int NumberOfHandles(); + template<typename T> v8::Local<T> Escape(v8::Local<T> value); +} +``` + +Use `Escape(value)` to return the object. + +Example: + +```c++ +v8::Local<v8::Object> EmptyObj() { + Nan::EscapableHandleScope scope; + v8::Local<v8::Object> obj = Nan::New<v8::Object>(); + return scope.Escape(obj); +} +``` + diff --git a/node_modules/nan/doc/script.md b/node_modules/nan/doc/script.md new file mode 100644 index 0000000..301c1b3 --- /dev/null +++ b/node_modules/nan/doc/script.md @@ -0,0 +1,58 @@ +## Script + +NAN provides `v8::Script` helpers as the API has changed over the supported versions of V8. + + - <a href="#api_nan_compile_script"><b><code>Nan::CompileScript()</code></b></a> + - <a href="#api_nan_run_script"><b><code>Nan::RunScript()</code></b></a> + - <a href="#api_nan_script_origin"><b><code>Nan::ScriptOrigin</code></b></a> + + +<a name="api_nan_compile_script"></a> +### Nan::CompileScript() + +A wrapper around [`v8::ScriptCompiler::Compile()`](https://v8docs.nodesource.com/node-8.16/da/da5/classv8_1_1_script_compiler.html#a93f5072a0db55d881b969e9fc98e564b). + +Note that `Nan::BoundScript` is an alias for `v8::Script`. + +Signature: + +```c++ +Nan::MaybeLocal<Nan::BoundScript> Nan::CompileScript( + v8::Local<v8::String> s, + const v8::ScriptOrigin& origin); +Nan::MaybeLocal<Nan::BoundScript> Nan::CompileScript(v8::Local<v8::String> s); +``` + + +<a name="api_nan_run_script"></a> +### Nan::RunScript() + +Calls `script->Run()` or `script->BindToCurrentContext()->Run(Nan::GetCurrentContext())`. + +Note that `Nan::BoundScript` is an alias for `v8::Script` and `Nan::UnboundScript` is an alias for `v8::UnboundScript` where available and `v8::Script` on older versions of V8. + +Signature: + +```c++ +Nan::MaybeLocal<v8::Value> Nan::RunScript(v8::Local<Nan::UnboundScript> script) +Nan::MaybeLocal<v8::Value> Nan::RunScript(v8::Local<Nan::BoundScript> script) +``` + +<a name="api_nan_script_origin"></a> +### Nan::ScriptOrigin + +A class transparently extending [`v8::ScriptOrigin`](https://v8docs.nodesource.com/node-16.0/db/d84/classv8_1_1_script_origin.html#pub-methods) +to provide backwards compatibility. Only the listed methods are guaranteed to +be available on all versions of Node. + +Declaration: + +```c++ +class Nan::ScriptOrigin : public v8::ScriptOrigin { + public: + ScriptOrigin(v8::Local<v8::Value> name, v8::Local<v8::Integer> line = v8::Local<v8::Integer>(), v8::Local<v8::Integer> column = v8::Local<v8::Integer>()) + v8::Local<v8::Value> ResourceName() const; + v8::Local<v8::Integer> ResourceLineOffset() const; + v8::Local<v8::Integer> ResourceColumnOffset() const; +} +``` diff --git a/node_modules/nan/doc/string_bytes.md b/node_modules/nan/doc/string_bytes.md new file mode 100644 index 0000000..7c1bd32 --- /dev/null +++ b/node_modules/nan/doc/string_bytes.md @@ -0,0 +1,62 @@ +## 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. + + - <a href="#api_nan_encoding"><b><code>Nan::Encoding</code></b></a> + - <a href="#api_nan_encode"><b><code>Nan::Encode()</code></b></a> + - <a href="#api_nan_decode_bytes"><b><code>Nan::DecodeBytes()</code></b></a> + - <a href="#api_nan_decode_write"><b><code>Nan::DecodeWrite()</code></b></a> + + +<a name="api_nan_encoding"></a> +### Nan::Encoding + +An enum representing the supported encoding types. A copy of `node::encoding` that is consistent across versions of Node. + +Definition: + +```c++ +enum Nan::Encoding { ASCII, UTF8, BASE64, UCS2, BINARY, HEX, BUFFER } +``` + + +<a name="api_nan_encode"></a> +### Nan::Encode() + +A wrapper around `node::Encode()` that provides a consistent implementation across supported versions of Node. + +Signature: + +```c++ +v8::Local<v8::Value> Nan::Encode(const void *buf, + size_t len, + enum Nan::Encoding encoding = BINARY); +``` + + +<a name="api_nan_decode_bytes"></a> +### Nan::DecodeBytes() + +A wrapper around `node::DecodeBytes()` that provides a consistent implementation across supported versions of Node. + +Signature: + +```c++ +ssize_t Nan::DecodeBytes(v8::Local<v8::Value> val, + enum Nan::Encoding encoding = BINARY); +``` + + +<a name="api_nan_decode_write"></a> +### Nan::DecodeWrite() + +A wrapper around `node::DecodeWrite()` that provides a consistent implementation across supported versions of Node. + +Signature: + +```c++ +ssize_t Nan::DecodeWrite(char *buf, + size_t len, + v8::Local<v8::Value> val, + enum Nan::Encoding encoding = BINARY); +``` diff --git a/node_modules/nan/doc/v8_internals.md b/node_modules/nan/doc/v8_internals.md new file mode 100644 index 0000000..08dd6d0 --- /dev/null +++ b/node_modules/nan/doc/v8_internals.md @@ -0,0 +1,199 @@ +## 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. + + - <a href="#api_nan_gc_callback"><b><code>NAN_GC_CALLBACK()</code></b></a> + - <a href="#api_nan_add_gc_epilogue_callback"><b><code>Nan::AddGCEpilogueCallback()</code></b></a> + - <a href="#api_nan_remove_gc_epilogue_callback"><b><code>Nan::RemoveGCEpilogueCallback()</code></b></a> + - <a href="#api_nan_add_gc_prologue_callback"><b><code>Nan::AddGCPrologueCallback()</code></b></a> + - <a href="#api_nan_remove_gc_prologue_callback"><b><code>Nan::RemoveGCPrologueCallback()</code></b></a> + - <a href="#api_nan_get_heap_statistics"><b><code>Nan::GetHeapStatistics()</code></b></a> + - <a href="#api_nan_set_counter_function"><b><code>Nan::SetCounterFunction()</code></b></a> + - <a href="#api_nan_set_create_histogram_function"><b><code>Nan::SetCreateHistogramFunction()</code></b></a> + - <a href="#api_nan_set_add_histogram_sample_function"><b><code>Nan::SetAddHistogramSampleFunction()</code></b></a> + - <a href="#api_nan_idle_notification"><b><code>Nan::IdleNotification()</code></b></a> + - <a href="#api_nan_low_memory_notification"><b><code>Nan::LowMemoryNotification()</code></b></a> + - <a href="#api_nan_context_disposed_notification"><b><code>Nan::ContextDisposedNotification()</code></b></a> + - <a href="#api_nan_get_internal_field_pointer"><b><code>Nan::GetInternalFieldPointer()</code></b></a> + - <a href="#api_nan_set_internal_field_pointer"><b><code>Nan::SetInternalFieldPointer()</code></b></a> + - <a href="#api_nan_adjust_external_memory"><b><code>Nan::AdjustExternalMemory()</code></b></a> + + +<a name="api_nan_gc_callback"></a> +### NAN_GC_CALLBACK(callbackname) + +Use `NAN_GC_CALLBACK` to declare your callbacks for `Nan::AddGCPrologueCallback()` and `Nan::AddGCEpilogueCallback()`. Your new method receives the arguments `v8::GCType type` and `v8::GCCallbackFlags flags`. + +```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()); +} +``` + +<a name="api_nan_add_gc_epilogue_callback"></a> +### Nan::AddGCEpilogueCallback() + +Signature: + +```c++ +void Nan::AddGCEpilogueCallback(v8::Isolate::GCEpilogueCallback callback, v8::GCType gc_type_filter = v8::kGCTypeAll) +``` + +Calls V8's [`AddGCEpilogueCallback()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a580f976e4290cead62c2fc4dd396be3e). + +<a name="api_nan_remove_gc_epilogue_callback"></a> +### Nan::RemoveGCEpilogueCallback() + +Signature: + +```c++ +void Nan::RemoveGCEpilogueCallback(v8::Isolate::GCEpilogueCallback callback) +``` + +Calls V8's [`RemoveGCEpilogueCallback()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#adca9294555a3908e9f23c7bb0f0f284c). + +<a name="api_nan_add_gc_prologue_callback"></a> +### Nan::AddGCPrologueCallback() + +Signature: + +```c++ +void Nan::AddGCPrologueCallback(v8::Isolate::GCPrologueCallback, v8::GCType gc_type_filter callback) +``` + +Calls V8's [`AddGCPrologueCallback()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a6dbef303603ebdb03da6998794ea05b8). + +<a name="api_nan_remove_gc_prologue_callback"></a> +### Nan::RemoveGCPrologueCallback() + +Signature: + +```c++ +void Nan::RemoveGCPrologueCallback(v8::Isolate::GCPrologueCallback callback) +``` + +Calls V8's [`RemoveGCPrologueCallback()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a5f72c7cda21415ce062bbe5c58abe09e). + +<a name="api_nan_get_heap_statistics"></a> +### Nan::GetHeapStatistics() + +Signature: + +```c++ +void Nan::GetHeapStatistics(v8::HeapStatistics *heap_statistics) +``` + +Calls V8's [`GetHeapStatistics()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a5593ac74687b713095c38987e5950b34). + +<a name="api_nan_set_counter_function"></a> +### Nan::SetCounterFunction() + +Signature: + +```c++ +void Nan::SetCounterFunction(v8::CounterLookupCallback cb) +``` + +Calls V8's [`SetCounterFunction()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a045d7754e62fa0ec72ae6c259b29af94). + +<a name="api_nan_set_create_histogram_function"></a> +### Nan::SetCreateHistogramFunction() + +Signature: + +```c++ +void Nan::SetCreateHistogramFunction(v8::CreateHistogramCallback cb) +``` + +Calls V8's [`SetCreateHistogramFunction()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a542d67e85089cb3f92aadf032f99e732). + +<a name="api_nan_set_add_histogram_sample_function"></a> +### Nan::SetAddHistogramSampleFunction() + +Signature: + +```c++ +void Nan::SetAddHistogramSampleFunction(v8::AddHistogramSampleCallback cb) +``` + +Calls V8's [`SetAddHistogramSampleFunction()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#aeb420b690bc2c216882d6fdd00ddd3ea). + +<a name="api_nan_idle_notification"></a> +### Nan::IdleNotification() + +Signature: + +```c++ +bool Nan::IdleNotification(int idle_time_in_ms) +``` + +Calls V8's [`IdleNotification()` or `IdleNotificationDeadline()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#ad6a2a02657f5425ad460060652a5a118) depending on V8 version. + +<a name="api_nan_low_memory_notification"></a> +### Nan::LowMemoryNotification() + +Signature: + +```c++ +void Nan::LowMemoryNotification() +``` + +Calls V8's [`LowMemoryNotification()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a24647f61d6b41f69668094bdcd6ea91f). + +<a name="api_nan_context_disposed_notification"></a> +### Nan::ContextDisposedNotification() + +Signature: + +```c++ +void Nan::ContextDisposedNotification() +``` + +Calls V8's [`ContextDisposedNotification()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#ad7f5dc559866343fe6cd8db1f134d48b). + +<a name="api_nan_get_internal_field_pointer"></a> +### Nan::GetInternalFieldPointer() + +Gets a pointer to the internal field with at `index` from a V8 `Object` handle. + +Signature: + +```c++ +void* Nan::GetInternalFieldPointer(v8::Local<v8::Object> object, int index) +``` + +Calls the Object's [`GetAlignedPointerFromInternalField()` or `GetPointerFromInternalField()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#a580ea84afb26c005d6762eeb9e3c308f) depending on the version of V8. + +<a name="api_nan_set_internal_field_pointer"></a> +### Nan::SetInternalFieldPointer() + +Sets the value of the internal field at `index` on a V8 `Object` handle. + +Signature: + +```c++ +void Nan::SetInternalFieldPointer(v8::Local<v8::Object> object, int index, void* value) +``` + +Calls the Object's [`SetAlignedPointerInInternalField()` or `SetPointerInInternalField()`](https://v8docs.nodesource.com/node-8.16/db/d85/classv8_1_1_object.html#ab3c57184263cf29963ef0017bec82281) depending on the version of V8. + +<a name="api_nan_adjust_external_memory"></a> +### Nan::AdjustExternalMemory() + +Signature: + +```c++ +int Nan::AdjustExternalMemory(int bytesChange) +``` + +Calls V8's [`AdjustAmountOfExternalAllocatedMemory()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#ae1a59cac60409d3922582c4af675473e). + diff --git a/node_modules/nan/doc/v8_misc.md b/node_modules/nan/doc/v8_misc.md new file mode 100644 index 0000000..1bd46d3 --- /dev/null +++ b/node_modules/nan/doc/v8_misc.md @@ -0,0 +1,85 @@ +## Miscellaneous V8 Helpers + + - <a href="#api_nan_utf8_string"><b><code>Nan::Utf8String</code></b></a> + - <a href="#api_nan_get_current_context"><b><code>Nan::GetCurrentContext()</code></b></a> + - <a href="#api_nan_set_isolate_data"><b><code>Nan::SetIsolateData()</code></b></a> + - <a href="#api_nan_get_isolate_data"><b><code>Nan::GetIsolateData()</code></b></a> + - <a href="#api_nan_typedarray_contents"><b><code>Nan::TypedArrayContents</code></b></a> + + +<a name="api_nan_utf8_string"></a> +### Nan::Utf8String + +Converts an object to a UTF-8-encoded character array. If conversion to a string fails (e.g. due to an exception in the toString() method of the object) then the length() method returns 0 and the * operator returns NULL. The underlying memory used for this object is managed by the object. + +An implementation of [`v8::String::Utf8Value`](https://v8docs.nodesource.com/node-8.16/d4/d1b/classv8_1_1_string_1_1_utf8_value.html) that is consistent across all supported versions of V8. + +Definition: + +```c++ +class Nan::Utf8String { + public: + Nan::Utf8String(v8::Local<v8::Value> from); + + int length() const; + + char* operator*(); + const char* operator*() const; +}; +``` + +<a name="api_nan_get_current_context"></a> +### Nan::GetCurrentContext() + +A call to [`v8::Isolate::GetCurrent()->GetCurrentContext()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a81c7a1ed7001ae2a65e89107f75fd053) that works across all supported versions of V8. + +Signature: + +```c++ +v8::Local<v8::Context> Nan::GetCurrentContext() +``` + +<a name="api_nan_set_isolate_data"></a> +### Nan::SetIsolateData() + +A helper to provide a consistent API to [`v8::Isolate#SetData()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#a7acadfe7965997e9c386a05f098fbe36). + +Signature: + +```c++ +void Nan::SetIsolateData(v8::Isolate *isolate, T *data) +``` + + +<a name="api_nan_get_isolate_data"></a> +### Nan::GetIsolateData() + +A helper to provide a consistent API to [`v8::Isolate#GetData()`](https://v8docs.nodesource.com/node-8.16/d5/dda/classv8_1_1_isolate.html#aabd223436bc1100a787dadaa024c6257). + +Signature: + +```c++ +T *Nan::GetIsolateData(v8::Isolate *isolate) +``` + +<a name="api_nan_typedarray_contents"></a> +### Nan::TypedArrayContents<T> + +A helper class for accessing the contents of an ArrayBufferView (aka a typedarray) from C++. If the input array is not a valid typedarray, then the data pointer of TypedArrayContents will default to `NULL` and the length will be 0. If the data pointer is not compatible with the alignment requirements of type, an assertion error will fail. + +Note that you must store a reference to the `array` object while you are accessing its contents. + +Definition: + +```c++ +template<typename T> +class Nan::TypedArrayContents { + public: + TypedArrayContents(v8::Local<Value> array); + + size_t length() const; + + T* const operator*(); + const T* const operator*() const; +}; +``` |