address review comments

doc/api/n-api.md

@@ -119,13 +119,21 @@ available to the module code.
 
 The N-APIs associated strictly with accessing ECMAScript features from native
 code can be found separately in `js_native_api.h` and `js_native_api_types.h`.
-The APIS defined in these headers are included in `node_api.h` and
-`node_api_types.h`. The separate headers exist to provide for the possibility of
-multiple implementations of N-API.
+The APIs defined in these headers are included in `node_api.h` and
+`node_api_types.h`. The headers are structured in this way in order to allow
+implementations of N-API outside of Node.js. For those implementations the
+Node.js specific APIs may not be applicable.
 
 The Node.js-specific parts of an addon can be separated from the code that
 exposes the actual functionality to the JavaScript environment so that the
-latter may be used with multiple implementations of N-API:
+latter may be used with multiple implementations of N-API. In the example below,
+`addon.c` and `addon.h` refer only to `js_native_api.h`. This ensures that
+`addon.c` can be reused to compile against either the Node.js implementation of
+N-API or any implementation of N-API outside of Node.js.
+
+`addon_node.c` is a separate file that contains the Node.js specific entry point
+to the addon and which instantiates the addon by calling into `addon.c` when the
+addon is loaded into a Node.js environment.
 
 ```C
 // addon.h
@@ -168,10 +176,6 @@ static napi_value Init(napi_env env, napi_value exports) {
 NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)
 ```
 
-With files arranged in this fashion it is possible to build the addon for
-Node.js, and also to reuse the code in `addon.c` and `addon.h` for a potential
-implementation of N-API outside of Node.js.
-
 ## Basic N-API Data Types
 
 N-API exposes the following fundamental datatypes as abstractions that are

src/js_native_api.h

@@ -441,6 +441,11 @@ NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                         napi_value script,
                                         napi_value* result);
 
+// Memory management
+NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env,
+                                                    int64_t change_in_bytes,
+                                                    int64_t* adjusted_value);
+
 #ifdef NAPI_EXPERIMENTAL
 
 NAPI_EXTERN napi_status napi_create_bigint_int64(napi_env env,

src/js_native_api_v8.cc

@@ -2893,3 +2893,15 @@ napi_status napi_add_finalizer(napi_env env,
                                          finalize_hint,
                                          result);
 }
+
+napi_status napi_adjust_external_memory(napi_env env,
+                                        int64_t change_in_bytes,
+                                        int64_t* adjusted_value) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, adjusted_value);
+
+  *adjusted_value = env->isolate->AdjustAmountOfExternalAllocatedMemory(
+      change_in_bytes);
+
+  return napi_clear_last_error(env);
+}

src/js_native_api_v8.h

@@ -2,6 +2,7 @@
 #define SRC_JS_NATIVE_API_V8_H_
 
 #include <string.h>
+#include "js_native_api_types.h"
 #include "js_native_api_v8_internals.h"
 
 struct napi_env__ {
@@ -149,9 +150,9 @@ inline v8::Local<v8::Value> V8LocalValueFromJsValue(napi_value v) {
 class Finalizer {
  protected:
   Finalizer(napi_env env,
-             napi_finalize finalize_callback,
-             void* finalize_data,
-             void* finalize_hint)
+            napi_finalize finalize_callback,
+            void* finalize_data,
+            void* finalize_hint)
     : _env(env),
       _finalize_callback(finalize_callback),
       _finalize_data(finalize_data),

src/js_native_api_v8_internals.h

@@ -1,6 +1,15 @@
 #ifndef SRC_JS_NATIVE_API_V8_INTERNALS_H_
 #define SRC_JS_NATIVE_API_V8_INTERNALS_H_
 
+// The V8 implementation of N-API, including `js_native_api_v8.h` uses certain
+// idioms which require definition here. For example, it uses a variant of
+// persistent references which need not be reset in the constructor. It is the
+// responsibility of this file to define these idioms.
+
+// In the case of the Node.js implementation of N-API some of the idioms are
+// imported directly from Node.js by including `node_internals.h` below. Others
+// are bridged to remove references to the `node` namespace.
+
 #include "node_version.h"
 #include "env.h"
 #include "node_internals.h"

src/node_api.cc

@@ -796,18 +796,6 @@ napi_status napi_get_node_version(napi_env env,
   return napi_clear_last_error(env);
 }
 
-napi_status napi_adjust_external_memory(napi_env env,
-                                        int64_t change_in_bytes,
-                                        int64_t* adjusted_value) {
-  CHECK_ENV(env);
-  CHECK_ARG(env, adjusted_value);
-
-  *adjusted_value = env->isolate->AdjustAmountOfExternalAllocatedMemory(
-      change_in_bytes);
-
-  return napi_clear_last_error(env);
-}
-
 namespace {
 namespace uvimpl {
 

src/node_api.h

@@ -162,11 +162,6 @@ NAPI_EXTERN
 napi_status napi_get_node_version(napi_env env,
                                   const napi_node_version** version);
 
-// Memory management
-NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env,
-                                                    int64_t change_in_bytes,
-                                                    int64_t* adjusted_value);
-
 #if NAPI_VERSION >= 2
 
 // Return the current libuv event loop for a given environment