Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

nan

Package Overview
Dependencies
Maintainers
1
Versions
89
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

nan - npm Package Compare versions

Comparing version 0.3.0-wip2 to 0.3.0

2

package.json
{
"name": "nan",
"version": "0.3.0-wip2",
"version": "0.3.0",
"description": "Native Abstractions for Node.js: C++ header for Node 0.8->0.12 compatibility",

@@ -5,0 +5,0 @@ "main": ".index.js",

195

README.md

@@ -6,3 +6,3 @@ Native Abstractions for Node.js

***Current version: 0.2.2*** *(See [nan.h](https://github.com/rvagg/nan/blob/master/nan.h) for changelog)*
***Current version: 0.3.0*** *(See [nan.h](https://github.com/rvagg/nan/blob/master/nan.h) for changelog)*

@@ -20,4 +20,24 @@ Thanks to the crazy changes in V8 (and some in Node core), keeping native addons compiling happily across versions, particularly 0.10 to 0.11/0.12, is a minor nightmare. The goal of this project is to store all logic necessary to develop native Node.js addons without having to inspect `NODE_MODULE_VERSION` and get yourself into a macro-tangle.

Simply copy **[nan.h](https://github.com/rvagg/nan/blob/master/nan.h)** from this repository into your project and load it in your source files with `#include "nan.h"`. The version is listed at the top of the file so be sure to check back here regularly for updates.
Simply add **NAN** as a dependency in the *package.json* of your Node addon:
```js
"dependencies": {
...
"nan" : "~0.3.0"
...
}
```
Pull in the path to **NAN** in your *binding.gyp* so that you can use `#include "nan.h"` in your *.cpp*:
```js
"include_dirs" : [
...
"<!(node -p -e \"require('path').dirname(require.resolve('nan'))\")"
...
]
```
This works like a `-I<path-to-NAN>` when compiling your addon.
<a name="example"></a>

@@ -28,3 +48,3 @@ ## Example

or a simpler example, see the **[async pi estimation example](https://github.com/rvagg/nan/tree/master/examples/async_pi_estimate)** in the examples directory for full code an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of **NAN**.
For a simpler example, see the **[async pi estimation example](https://github.com/rvagg/nan/tree/master/examples/async_pi_estimate)** in the examples directory for full code and an explanation of what this Monte Carlo Pi estimation example does. Below are just some parts of the full example that illustrate the use of **NAN**.

@@ -152,3 +172,7 @@ Compare to the current 0.10 version of this example, found in the [node-addon-examples](https://github.com/rvagg/node-addon-examples/tree/master/9_async_work) repository and also a 0.11 version of the same found [here](https://github.com/kkoopa/node-addon-examples/tree/5c01f58fc993377a567812597e54a83af69686d7/9_async_work).

* <a href="#api_nan_return_undefined"><b><code>NanReturnUndefined</code></b></a>
* <a href="#api_nan_return_null"><b><code>NanReturnNull</code></b></a>
* <a href="#api_nan_return_empty_string"><b><code>NanReturnEmptyString</code></b></a>
* <a href="#api_nan_scope"><b><code>NanScope</code></b></a>
* <a href="#api_nan_locker"><b><code>NanLocker</code></b></a>
* <a href="#api_nan_unlocker"><b><code>NanUnlocker</code></b></a>
* <a href="#api_nan_get_internal_field_pointer"><b><code>NanGetInternalFieldPointer</code></b></a>

@@ -164,3 +188,3 @@ * <a href="#api_nan_set_internal_field_pointer"><b><code>NanSetInternalFieldPointer</code></b></a>

* <a href="#api_nan_uint32_option_value"><b><code>NanUInt32OptionValue</code></b></a>
* <a href="#api_nan_throw_error"><b><code>NanThrowError</code></b>, <b><code>NanThrowTypeError</code></b>, <b><code>NanThrowRangeError</code></b>, <b><code>NanThrowError(Local<Value>)</code></b></a>
* <a href="#api_nan_throw_error"><b><code>NanThrowError</code></b>, <b><code>NanThrowTypeError</code></b>, <b><code>NanThrowRangeError</code></b>, <b><code>NanThrowError(Handle<Value>)</code></b>, <b><code>NanThrowError(Handle<Value>, int)</code></b></a>
* <a href="#api_nan_new_buffer_handle"><b><code>NanNewBufferHandle(char *, size_t, FreeCallback, void *)</code></b>, <b><code>NanNewBufferHandle(char *, uint32_t)</code></b>, <b><code>NanNewBufferHandle(uint32_t)</code></b></a>

@@ -173,2 +197,3 @@ * <a href="#api_nan_buffer_use"><b><code>NanBufferUse(char *, uint32_t)</code></b></a>

* <a href="#api_nan_assign_persistent"><b><code>NanAssignPersistent</code></b></a>
* <a href="#api_nan_init_persistent"><b><code>NanInitPersistent</code></b></a>
* <a href="#api_nan_callback"><b><code>NanCallback</code></b></a>

@@ -207,6 +232,6 @@ * <a href="#api_nan_async_worker"><b><code>NanAsyncWorker</code></b></a>

// 0.10 and below:
v8::Handle<v8::Value> name(const v8::Arguments& args)
Handle<Value> name(const Arguments& args)
// 0.11 and above
void name(const v8::FunctionCallbackInfo<v8::Value>& args)
void name(const FunctionCallbackInfo<Value>& args)
```

@@ -221,3 +246,3 @@

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_GETTER`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_GETTER`.

@@ -229,3 +254,3 @@ <a name="api_nan_setter"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_SETTER`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_SETTER`.

@@ -236,3 +261,3 @@ <a name="api_nan_property_getter"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_GETTER`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_GETTER`.

@@ -243,3 +268,3 @@ <a name="api_nan_property_setter"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_SETTER`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_SETTER`.

@@ -250,3 +275,3 @@ <a name="api_nan_property_enumerator"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_ENUMERATOR`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_ENUMERATOR`.

@@ -257,3 +282,3 @@ <a name="api_nan_property_deleter"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_ENUMERATOR`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_DELETER`.

@@ -264,3 +289,3 @@ <a name="api_nan_property_query"></a>

You can use `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_ENUMERATOR`.
You can use `NanReturnNull()`, `NanReturnEmptyString()`, `NanReturnUndefined()` and `NanReturnValue()` in a `NAN_PROPERTY_QUERY`.

@@ -284,3 +309,3 @@ <a name="api_nan_weak_callback"></a>

<a name="api_nan_return_value"></a>
### NanReturnValue(v8::Handle&lt;v8::Value&gt;)
### NanReturnValue(Handle&lt;Value&gt;)

@@ -293,3 +318,3 @@ Use `NanReturnValue` when you want to return a value from your V8 accessible method:

NanReturnValue(v8::String::New("FooBar!"));
NanReturnValue(String::New("FooBar!"));
}

@@ -313,6 +338,32 @@ ```

<a name="api_nan_return_null"></a>
### NanReturnNull()
Use `NanReturnNull` when you want to return `Null` from your V8 accessible method:
```c++
NAN_METHOD(Foo::Baz) {
...
NanReturnNull();
}
```
<a name="api_nan_return_empty_string"></a>
### NanReturnEmptyString()
Use `NanReturnEmptyString` when you want to return an empty `String` from your V8 accessible method:
```c++
NAN_METHOD(Foo::Baz) {
...
NanReturnEmptyString();
}
```
<a name="api_nan_scope"></a>
### NanScope()
The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanScope()` necessary, use it in place of `v8::HandleScope scope`:
The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanScope()` necessary, use it in place of `HandleScope scope`:

@@ -323,8 +374,34 @@ ```c++

NanReturnValue(v8::String::New("FooBar!"));
NanReturnValue(String::New("FooBar!"));
}
```
<a name="api_nan_locker"></a>
### NanLocker()
The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanLocker()` necessary, use it in place of `Locker locker`:
```c++
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
```
<a name="api_nan_unlocker"></a>
### NanUnlocker()
The introduction of `isolate` references for many V8 calls in Node 0.11 makes `NanUnlocker()` necessary, use it in place of `Unlocker unlocker`:
```c++
NAN_METHOD(Foo::Bar) {
NanLocker();
...
NanUnlocker();
}
```
<a name="api_nan_get_internal_field_pointer"></a>
### void * NanGetInternalFieldPointer(v8::Handle&lt;v8::Object&gt;, int)
### void * NanGetInternalFieldPointer(Handle&lt;Object&gt;, int)

@@ -339,3 +416,3 @@ Gets a pointer to the internal field with at `index` from a V8 `Object` handle.

<a name="api_nan_set_internal_field_pointer"></a>
### void NanSetInternalFieldPointer(v8::Handle&lt;v8::Object&gt;, int, void *)
### void NanSetInternalFieldPointer(Handle&lt;Object&gt;, int, void *)

@@ -352,3 +429,3 @@ Sets the value of the internal field at `index` on a V8 `Object` handle.

<a name="api_nan_object_wrap_handle"></a>
### v8::Local&lt;v8::Object&gt; NanObjectWrapHandle(Object)
### Local&lt;Object&gt; NanObjectWrapHandle(Object)

@@ -358,7 +435,7 @@ When you want to fetch the V8 object handle from a native object you've wrapped with Node's `ObjectWrap`, you should use `NanObjectWrapHandle`:

```c++
NanObjectWrapHandle(iterator)->Get(v8::String::NewSymbol("end"))
NanObjectWrapHandle(iterator)->Get(String::NewSymbol("end"))
```
<a name="api_nan_make_weak"></a>
### NanMakeWeak(v8::Persistent&lt;T&gt;, parameter, callback)
### NanMakeWeak(Persistent&lt;T&gt;, parameter, callback)

@@ -368,5 +445,5 @@ Make a persistent reference weak.

<a name="api_nan_symbol"></a>
### v8::String NanSymbol(char *)
### String NanSymbol(char *)
This isn't strictly about compatibility, it's just an easier way to create string symbol objects (i.e. `v8::String::NewSymbol(x)`), for getting and setting object properties, or names of objects.
This isn't strictly about compatibility, it's just an easier way to create string symbol objects (i.e. `String::NewSymbol(x)`), for getting and setting object properties, or names of objects.

@@ -412,5 +489,6 @@ ```c++

<a name="api_nan_from_v8_string"></a>
### char* NanFromV8String(v8::Handle&lt;v8::Value&gt;[, enum node::encoding, size_t *])
### char* NanFromV8String(Handle&lt;Value&gt;[, enum Nan::Encoding, size_t *, char *, size_t, int])
When you want to convert a V8 string to a `char*` use `NanFromV8String`. It is possible to define an encoding that defaults to `node::UTF8` as well as a pointer to a variable that will be assigned the number of bytes in the returned string. On versions prior to 0.11, the `node::BINARY` and `node::BUFFER` encodings currently may not work properly yet. do not Just remember that you'll end up with an object that you'll need to `delete[]` at some point:
When you want to convert a V8 `String` to a `char*` use `NanFromV8String`. It is possible to define an encoding that defaults to `Nan::UTF8` as well as a pointer to a variable that will be assigned the number of bytes in the returned string. It is also possible to supply a buffer and its length to the function in order not to have a new buffer allocated. The final argument allows optionally setting `String::WriteOptions`, which default to `String::HINT_MANY_WRITES_EXPECTED | String::NO_NULL_TERMINATION`.
Just remember that you'll end up with an object that you'll need to `delete[]` at some point unless you supply your own buffer:

@@ -420,3 +498,3 @@ ```c++

char* name = NanFromV8String(args[0]);
char* decoded = NanFromV8String(args[1], node::BASE64, &count);
char* decoded = NanFromV8String(args[1], Nan::BASE64, &count, NULL, 0, String::HINT_MANY_WRITES_EXPECTED);
char param_copy[count];

@@ -428,3 +506,3 @@ memcpy(param_copy, decoded, count);

<a name="api_nan_boolean_option_value"></a>
### bool NanBooleanOptionValue(v8::Handle&lt;v8::Value&gt;, v8::Handle&lt;v8::String&gt;[, bool])
### bool NanBooleanOptionValue(Handle&lt;Value&gt;, Handle&lt;String&gt;[, bool])

@@ -443,3 +521,3 @@ When you have an "options" object that you need to fetch properties from, boolean options can be fetched with this pair. They check first if the object exists (`IsEmpty`), then if the object has the given property (`Has`) then they get and convert/coerce the property to a `bool`.

<a name="api_nan_uint32_option_value"></a>
### uint32_t NanUInt32OptionValue(v8::Handle&lt;v8::Value&gt;, v8::Handle&lt;v8::String&gt;, uint32_t)
### uint32_t NanUInt32OptionValue(Handle&lt;Value&gt;, Handle&lt;String&gt;, uint32_t)

@@ -455,3 +533,3 @@ Similar to `NanBooleanOptionValue`, use `NanUInt32OptionValue` to fetch an integer option from your options object. Can be any kind of JavaScript `Number` and it will be coerced to an unsigned 32-bit integer.

<a name="api_nan_throw_error"></a>
### NanThrowError(message), NanThrowTypeError(message), NanThrowRangeError(message), NanThrowError(Local&lt;Value&gt;)
### NanThrowError(message), NanThrowTypeError(message), NanThrowRangeError(message), NanThrowError(Local&lt;Value&gt;), NanThrowError(Local&lt;Value&gt;, int)

@@ -464,6 +542,6 @@ For throwing `Error`, `TypeError` and `RangeError` objects. You should `return` this call:

Can also handle any custom object you may want to throw.
Can also handle any custom object you may want to throw. If used with the error code argument, it will add the supplied error code to the error object as a property called `code`.
<a name="api_nan_new_buffer_handle"></a>
### v8::Local&lt;v8::Object&gt; NanNewBufferHandle(char *, uint32_t), v8::Local&lt;v8::Object&gt; NanNewBufferHandle(uint32_t)
### Local&lt;Object&gt; NanNewBufferHandle(char *, uint32_t), Local&lt;Object&gt; NanNewBufferHandle(uint32_t)

@@ -481,3 +559,3 @@ The `Buffer` API has changed a little in Node 0.11, this helper provides consistent access to `Buffer` creation:

<a name="api_nan_buffer_use"></a>
### v8::Local&lt;v8::Object&gt; NanBufferUse(char*, uint32_t)
### Local&lt;Object&gt; NanBufferUse(char*, uint32_t)

@@ -499,3 +577,3 @@ `Buffer::New(char*, uint32_t)` prior to 0.11 would make a copy of the data.

<a name="api_nan_persistent_to_local"></a>
### v8::Local&lt;Type&gt; NanPersistentToLocal(v8::Persistent&lt;Type&gt;&)
### Local&lt;Type&gt; NanPersistentToLocal(Persistent&lt;Type&gt;&)

@@ -507,3 +585,3 @@ Aside from `FunctionCallbackInfo`, the biggest and most painful change to V8 in Node 0.11 is the many restrictions now placed on `Persistent` handles. They are difficult to assign and difficult to fetch the original value out of.

```c++
v8::Local<v8::Object> handle = NanPersistentToLocal(persistentHandle);
Local<Object> handle = NanPersistentToLocal(persistentHandle);
```

@@ -516,9 +594,9 @@

```c++
v8::Local<v8::FunctionTemplate> ftmpl = v8::FunctionTemplate::New();
v8::Local<v8::ObjectTemplate> otmpl = ftmpl->InstanceTemplate();
v8::Local<v8::Context> ctx = NanNewContextHandle(NULL, otmpl);
Local<FunctionTemplate> ftmpl = FunctionTemplate::New();
Local<ObjectTemplate> otmpl = ftmpl->InstanceTemplate();
Local<Context> ctx = NanNewContextHandle(NULL, otmpl);
```
<a name="api_nan_dispose"></a>
### template&lt;class T&gt; void NanDispose(v8::Persistent&lt;T&gt; &)
### void NanDispose(Persistent&lt;T&gt; &)

@@ -536,21 +614,32 @@ Use `NanDispose` to dispose a `Persistent` handle.

In general it is now better to place anything you want to protect from V8's garbage collector as properties of a generic `v8:Object` and then assign that to a `Persistent`. This works in older versions of Node also if you use `NanAssignPersistent`:
In general it is now better to place anything you want to protect from V8's garbage collector as properties of a generic `Object` and then assign that to a `Persistent`. This works in older versions of Node also if you use `NanAssignPersistent`:
```c++
v8::Persistent<v8::Object> persistentHandle;
Persistent<Object> persistentHandle;
...
v8::Local<v8::Object> obj = v8::Object::New();
obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a v8::Local<v8::String>
NanAssignPersistent(v8::Object, persistentHandle, obj)
Local<Object> obj = Object::New();
obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a Local<String>
NanAssignPersistent(Object, persistentHandle, obj)
```
<a name="api_nan_init_persistent"></a>
### NanInitPersistent(type, name, object)
User `NanInitPersistent` to declare and initialize a new `Persistent` with the supplied object. The assignment operator for `Persistent` is no longer public in Node 0.11, so this macro makes it easier to declare and initializing a new `Persistent`. See <a href="#api_nan_assign_persistent"><b><code>NanAssignPersistent</code></b></a> for more information.
```c++
Local<Object> obj = Object::New();
obj->Set(NanSymbol("key"), keyHandle); // where keyHandle might be a Local<String>
NanInitPersistent(Object, persistentHandle, obj);
```
<a name="api_nan_callback"></a>
### NanCallback
Because of the difficulties imposed by the changes to `Persistent` handles in V8 in Node 0.11, creating `Persistent` versions of your `v8::Local<v8::Function>` handles is annoyingly tricky. `NanCallback` makes it easier by taking your `Local` handle, making it persistent until the `NanCallback` is deleted and even providing a handy `Call()` method to fetch and execute the callback `Function`.
Because of the difficulties imposed by the changes to `Persistent` handles in V8 in Node 0.11, creating `Persistent` versions of your `Local<Function>` handles is annoyingly tricky. `NanCallback` makes it easier by taking your `Local` handle, making it persistent until the `NanCallback` is deleted and even providing a handy `Call()` method to fetch and execute the callback `Function`.
```c++
v8::Local<v8::Function> callbackHandle = callback = args[0].As<v8::Function>();
Local<Function> callbackHandle = callback = args[0].As<Function>();
NanCallback *callback = new NanCallback(callbackHandle);

@@ -568,4 +657,4 @@ // pass `callback` around and it's safe from GC until you:

// an error argument:
v8::Local<v8::Value> argv[] = {
v8::Exception::Error(v8::String::New("fail!"))
Local<Value> argv[] = {
Exception::Error(String::New("fail!"))
};

@@ -575,5 +664,5 @@ callback->Call(1, argv);

// a success argument:
v8::Local<v8::Value> argv[] = {
v8::Local<v8::Value>::New(v8::Null()),
v8::String::New("w00t!")
Local<Value> argv[] = {
Local<Value>::New(Null()),
String::New("w00t!")
};

@@ -614,6 +703,6 @@ callback->Call(2, argv);

// Save a V8 object in a Persistent handle to protect it from GC
void SavePersistent(const char *key, v8::Local<v8::Object> &obj);
void SavePersistent(const char *key, Local<Object> &obj);
// Fetch a stored V8 object (don't call from within `Execute()`)
v8::Local<v8::Object> GetFromPersistent(const char *key);
Local<Object> GetFromPersistent(const char *key);

@@ -620,0 +709,0 @@ // Default implementation calls the callback function with no arguments.

nan.h

Sorry, the diff of this file is not supported yet

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc