nan - npm Package Compare versions

Comparing version 2.8.0 to 2.9.1

CHANGELOG.md

 # NAN ChangeLog
 
-**Version 2.8.0: current Node 9.2.0, Node 12: 0.12.18, Node 10: 0.10.48, iojs: 3.3.1**
+**Version 2.9.1: current Node 9.5.0, Node 0.12: 0.12.18, Node 0.10: 0.10.48, iojs: 3.3.1**
 
+### 2.9.1 Feb 22 2018
+
+  - Bugfix: Avoid deprecation warnings in deprecated `Nan::Callback::operator()` 372b14d91289df4604b0f81780709708c45a9aa4
+  - Bugfix: Avoid deprecation warnings in `Nan::JSON` 3bc294bce0b7d0a3ee4559926303e5ed4866fda2
+
+### 2.9.0 Feb 22 2018
+
+  - Deprecation: Deprecate legacy `Callback::Call` 6dd5fa690af61ca3523004b433304c581b3ea309
+  - Feature: introduce `AsyncResource` class 90c0a179c0d8cb5fd26f1a7d2b1d6231eb402d48o
+  - Feature: Add context aware `Nan::Callback::Call` functions 7169e09fb088418b6e388222e88b4c13f07ebaee
+  - Feature: Make `AsyncWorker` context aware 066ba21a6fb9e2b5230c9ed3a6fc51f1211736a4
+  - Feature: add `Callback` overload to `Nan::Call` 5328daf66e202658c1dc0d916c3aaba99b3cc606
+  - Bugfix: fix warning: suggest parentheses around `&&` within `||` b2bb63d68b8ae623a526b542764e1ac82319cb2c
+  - Bugfix: Fix compilation on io.js 3 d06114dba0a522fb436f0c5f47b994210968cd7b
+
 ### 2.8.0 Nov 15 2017
@@ -6,0 +21,0 @@

doc/asyncworker.md

@@ -15,2 +15,7 @@ ## Asynchronous work helpers
 
+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:
@@ -21,3 +26,3 @@
  public:
-  explicit AsyncWorker(Callback *callback_);
+  explicit AsyncWorker(Callback *callback_, const char* resource_name = "nan:AsyncWorker");
 
@@ -78,5 +83,5 @@ virtual ~AsyncWorker();
  public:
-  explicit AsyncProgressWorker(Callback *callback_);
+  explicit AsyncProgressWorkerBase(Callback *callback_, const char* resource_name = ...);
 
-  virtual ~AsyncProgressWorker();
+  virtual ~AsyncProgressWorkerBase();
 
@@ -114,3 +119,3 @@ void WorkProgress();
  public:
-  explicit AsyncProgressQueueWorker(Callback *callback_);
+  explicit AsyncProgressQueueWorker(Callback *callback_, const char* resource_name = "nan:AsyncProgressQueueWorker");
 
@@ -144,1 +149,3 @@ virtual ~AsyncProgressQueueWorker();
 ```
+
+[AsyncResource]: "node_misc.html#api_nan_asyncresource"

doc/callback.md

@@ -25,8 +25,10 @@ ## Nan::Callback
 
-  v8::Local<v8::Value> operator()(v8::Local<v8::Object> target,
-                                  int argc = 0,
-                                  v8::Local<v8::Value> argv[] = 0) const;
+  MaybeLocal<v8::Value> operator()(AsyncResource* async_resource,
+                                   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;
+  MaybeLocal<v8::Value> operator()(AsyncResource* async_resource,
+                                   int argc = 0,
+                                   v8::Local<v8::Value> argv[] = 0) const;
 
@@ -43,2 +45,20 @@ void SetFunction(const v8::Local<v8::Function> &fn);
 
+  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,
@@ -45,0 +65,0 @@ int argc,

doc/maybe_types.md

@@ -125,4 +125,6 @@ ## Maybe Types
 
-A helper method for calling [`v8::Function#Call()`](https://v8docs.nodesource.com/io.js-3.3/d5/d54/classv8_1_1_function.html#a468a89f737af0612db10132799c827c0) in a way compatible across supported versions of V8.
+A helper method for calling a synchronous [`v8::Function#Call()`](https://v8docs.nodesource.com/io.js-3.3/d5/d54/classv8_1_1_function.html#a468a89f737af0612db10132799c827c0) in a way compatible across supported versions of V8.
 
+For asynchronous callbacks, use Nan::Callback::Call along with an AsyncResource.
+
 Signature:
@@ -132,2 +134,4 @@
 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[]);
 ```
@@ -134,0 +138,0 @@

doc/node_misc.md

 ## 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>
@@ -7,9 +8,63 @@ - <a href="#api_nan_module_init"><b><code>NAN_MODULE_INIT()</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 asynchornously, 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,
+                                            Nan::async_context async_context);
+  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
+                                            v8::Local<v8::String> symbol,
+                                            int argc,
+                                            v8::Local<v8::Value>* argv,
+                                            Nan::async_context async_context);
+  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
+                                            const char* method,
+                                            int argc,
+                                            v8::Local<v8::Value>* argv,
+                                            Nan::async_context async_context);
+};
+```
+
+* `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()
 
-Wrappers around `node::MakeCallback()` providing a consistent API across all supported versions of Node.
+Wrappers around the legacy `node::MakeCallback()` APIs.
 
-Use `MakeCallback()` rather than using `v8::Function#Call()` directly in order to properly process internal Node functionality including domains, async hooks, the microtask queue, and other debugging functionality.
+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.
 
@@ -65,1 +120,4 @@ Signatures:
 ```
+
+[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

LICENSE.md

 The MIT License (MIT)
 =====================
 
-Copyright (c) 2017 NAN contributors
+Copyright (c) 2018 NAN contributors
 -----------------------------------
@@ -6,0 +6,0 @@

package.json

 {
   "name": "nan",
-  "version": "2.8.0",
+  "version": "2.9.1",
   "description": "Native Abstractions for Node.js: C++ header for Node 0.8 -> 9 compatibility",
@@ -5,0 +5,0 @@ "main": "include_dirs.js",

README.md

@@ -6,3 +6,3 @@ Native Abstractions for Node.js
 
-***Current version: 2.8.0***
+***Current version: 2.9.1***
 
@@ -25,2 +25,3 @@ *(See [CHANGELOG.md](https://github.com/nodejs/nan/blob/master/CHANGELOG.md) for complete ChangeLog)*
  * **[Tests](#tests)**
+ * **[Knowns issues](#issues)**
  * **[Governance & Contributing](#governance)**
@@ -320,2 +321,3 @@
 
+ - <a href="doc/node_misc.md#api_nan_asyncresource"><b><code>Nan::AsyncResource</code></b></a>
  - <a href="doc/node_misc.md#api_nan_make_callback"><b><code>Nan::MakeCallback()</code></b></a>
@@ -347,2 +349,29 @@ - <a href="doc/node_misc.md#api_nan_module_init"><b><code>NAN_MODULE_INIT()</code></b></a>
 
+<a name="issues"></a>
+
+## Known issues
+
+### Compiling against Node.js 0.12 on OSX
+
+With new enough compilers available on OSX, the versions of V8 headers corresponding to Node.js 0.12
+do not compile anymore. The error looks something like:
+
+```
+❯   CXX(target) Release/obj.target/accessors/cpp/accessors.o
+In file included from ../cpp/accessors.cpp:9:
+In file included from ../../nan.h:51:
+In file included from /Users/ofrobots/.node-gyp/0.12.18/include/node/node.h:61:
+/Users/ofrobots/.node-gyp/0.12.18/include/node/v8.h:5800:54: error: 'CreateHandle' is a protected member of 'v8::HandleScope'
+  return Handle<T>(reinterpret_cast<T*>(HandleScope::CreateHandle(
+                                        ~~~~~~~~~~~~~^~~~~~~~~~~~
+```
+
+This can be worked around by patching your local versions of v8.h corresponding to Node 0.12 to make
+`v8::Handle` a friend of `v8::HandleScope`. Since neither Node.js not V8 support this release line anymore
+this patch cannot be released by either project in an official release.
+
+For this reason, we do not test against Node.js 0.12 on OSX in this project's CI. If you need to support
+that configuration, you will need to either get an older compiler, or apply a source patch to the version
+of V8 headers as a workaround.
+
 <a name="governance"></a>
@@ -429,4 +458,4 @@
 
-Copyright (c) 2017 NAN WG Members / Collaborators (listed above).
+Copyright (c) 2018 NAN WG Members / Collaborators (listed above).
 
 Native Abstractions for Node.js is licensed under an MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.

tools/1to2.js

@@ -5,3 +5,3 @@ #!/usr/bin/env node
  *
- * Copyright (c) 2017 NAN contributors
+ * Copyright (c) 2018 NAN contributors
  *
@@ -8,0 +8,0 @@ * MIT License <https://github.com/nodejs/nan/blob/master/LICENSE.md>

No alert changes

Improved metrics

Total package byte prevSize

404355

increased by4%

Number of lines in readme file

457

increased by6.78%

No dependency changes