node-api: enable napi_ref for all value types

doc/api/n-api.md

@@ -2046,6 +2046,49 @@ the `napi_value` in question is of the JavaScript type expected by the API.
 
 ### Enum types
 
+#### `node_api_features`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+typedef enum {
+  node_api_feature_none = 0,
+  node_api_feature_reference_all_types = 1 << 0,
+
+  node_api_default_experimental_features = node_api_feature_reference_all_types,
+
+   // version specific
+  node_api_default_features = node_api_default_experimental_features,
+} node_api_features;
+```
+
+The `node_api_features` allow changing internal behavior of existing Node-API
+functions.
+
+We pass a `node_api_features` pointer to the `napi_module` struct in the
+`NAPI_MODULE_X` macro. This macro is used for the module registration.
+If the module is initialized without using this macro, then there will be
+no features selected and the module will use the `node_api_feature_none`.
+
+Each Node-API version defines its own default set of features.
+For the current version it can be accessed using `node_api_default_features`.
+A module can override the set of its enabled features by adding
+`NODE_API_CUSTOM_FEATURES` definition to the `.gyp` file and then defining the
+value of the global `node_api_module_features` variable.
+To check enabled features use the `node_api_is_feature_enabled` function.
+
+For example, to disable `node_api_feature_reference_all_types` feature we can
+exclude its bit from the `node_api_default_features` set:
+
+```c
+node_api_features node_api_module_features =
+    node_api_default_features & ~node_api_feature_reference_all_types;
+```
+
 #### `napi_key_collection_mode`
 
 <!-- YAML
@@ -5700,6 +5743,32 @@ support it:
 * If the function is not available, provide an alternate implementation
   that does not use the function.
 
+#### `node_api_is_feature_enabled`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+NAPI_EXTERN napi_status node_api_is_feature_enabled(napi_env env,
+                                                    node_api_features feature,
+                                                    bool* result);
+```
+
+* `[in] env`: The environment that the API is invoked under.
+* `[in] feature`: The features that we want to test.
+* `[out] result`: Whether the feature or a set of features are enabled.
+
+Returns `napi_ok` if the API succeeded.
+
+The function checks enabled features for the module.
+If `feature` parameter has multiple `node_api_features` bit flags, then the
+function returns `true` only when all the requested fatures are enabled.
+
+See `node_api_features` for more details about Node-API features.
+
 ## Memory management
 
 ### `napi_adjust_external_memory`

src/js_native_api.h

@@ -566,6 +566,11 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_object_seal(napi_env env,
                                                     napi_value object);
 #endif  // NAPI_VERSION >= 8
 
+#ifdef NAPI_EXPERIMENTAL
+NAPI_EXTERN napi_status NAPI_CDECL node_api_is_feature_enabled(
+    napi_env env, node_api_features feature, bool* result);
+#endif  // NAPI_EXPERIMENTAL
+
 EXTERN_C_END
 
 #endif  // SRC_JS_NATIVE_API_H_

src/js_native_api_types.h

@@ -108,6 +108,37 @@ typedef enum {
 //   * the definition of `napi_status` in doc/api/n-api.md to reflect the newly
 //     added value(s).
 
+#ifdef NAPI_EXPERIMENTAL
+// Features allow changing internal behavior of existing Node-API functions.
+//
+// We pass a node_api_features pointer to the napi_module struct
+// in the NAPI_MODULE_X macro. This macro is used for the module registration.
+// If the module is initialized without using this macro, then there will be
+// no features selected and the module will use the node_api_feature_none.
+//
+// Each Node-API version defines its own default set of features.
+// For the current version it can be accessed using node_api_default_features.
+// A module can override the set of its enabled features by adding
+// NODE_API_CUSTOM_FEATURES definition to the .gyp file and then defining the
+// value of the global node_api_module_features variable.
+// To check enabled features use the `node_api_is_feature_enabled` function.
+//
+// For example, to disables node_api_feature_reference_all_types:
+// node_api_features node_api_module_features =
+//   node_api_default_features & ~node_api_feature_reference_all_types;
+typedef enum {
+  // To be used when no features needs to be set.
+  node_api_feature_none = 0,
+  // Use napi_ref for all value types.
+  // Not only objects, external objects, functions, and symbols as before.
+  node_api_feature_reference_all_types = 1 << 0,
+  // Each version of Node-API is going to have its own default set of features.
+  node_api_default_experimental_features = node_api_feature_reference_all_types,
+  // This variable must be conditionally set depending on the Node-API version.
+  node_api_default_features = node_api_default_experimental_features,
+} node_api_features;
+#endif
+
 typedef napi_value(NAPI_CDECL* napi_callback)(napi_env env,
                                               napi_callback_info info);
 typedef void(NAPI_CDECL* napi_finalize)(napi_env env,

src/js_native_api_v8.cc

@@ -2495,9 +2495,11 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
   CHECK_ARG(env, result);
 
   v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
-  if (!(v8_value->IsObject() || v8_value->IsFunction() ||
-        v8_value->IsSymbol())) {
-    return napi_set_last_error(env, napi_invalid_arg);
+  if (!env->IsFeatureEnabled(node_api_feature_reference_all_types)) {
+    if (!(v8_value->IsObject() || v8_value->IsFunction() ||
+          v8_value->IsSymbol())) {
+      return napi_set_last_error(env, napi_invalid_arg);
+    }
   }
 
   v8impl::Reference* reference =
@@ -3257,3 +3259,12 @@ napi_status NAPI_CDECL napi_is_detached_arraybuffer(napi_env env,
 
   return napi_clear_last_error(env);
 }
+
+napi_status NAPI_CDECL node_api_is_feature_enabled(napi_env env,
+                                                   node_api_features feature,
+                                                   bool* result) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, result);
+  *result = env->IsFeatureEnabled(feature);
+  return napi_clear_last_error(env);
+}

src/js_native_api_v8.h

@@ -50,8 +50,11 @@ class RefTracker {
 }  // end of namespace v8impl
 
 struct napi_env__ {
-  explicit napi_env__(v8::Local<v8::Context> context)
-      : isolate(context->GetIsolate()), context_persistent(isolate, context) {
+  explicit napi_env__(v8::Local<v8::Context> context,
+                      node_api_features* features)
+      : isolate(context->GetIsolate()),
+        context_persistent(isolate, context),
+        features(features == nullptr ? node_api_feature_none : *features) {
     CHECK_EQ(isolate, context->GetIsolate());
     napi_clear_last_error(this);
   }
@@ -89,13 +92,19 @@ struct napi_env__ {
     }
   }
 
-  // This should be overridden to schedule the finalization to a properiate
+  // This should be overridden to schedule the finalization to appropriate
   // timing, like next tick of the event loop.
   virtual void CallFinalizer(napi_finalize cb, void* data, void* hint) {
     v8::HandleScope handle_scope(isolate);
     CallIntoModule([&](napi_env env) { cb(env, data, hint); });
   }
 
+  bool IsFeatureEnabled(node_api_features feature) {
+    // By comparing results of `&` operation to the feature parameter
+    // we allow to test for multiple feature flags.
+    return (features & feature) == feature;
+  }
+
   virtual void DeleteMe() {
     // First we must finalize those references that have `napi_finalizer`
     // callbacks. The reason is that addons might store other references which
@@ -122,6 +131,7 @@ struct napi_env__ {
   int open_callback_scopes = 0;
   int refs = 1;
   void* instance_data = nullptr;
+  node_api_features features = node_api_feature_none;
 
  protected:
   // Should not be deleted directly. Delete with `napi_env__::DeleteMe()`

src/node_api.cc

@@ -20,8 +20,9 @@
 #include <memory>
 
 node_napi_env__::node_napi_env__(v8::Local<v8::Context> context,
-                                 const std::string& module_filename)
-    : napi_env__(context), filename(module_filename) {
+                                 const std::string& module_filename,
+                                 node_api_features* features)
+    : napi_env__(context, features), filename(module_filename) {
   CHECK_NOT_NULL(node_env());
 }
 
@@ -126,10 +127,11 @@ class BufferFinalizer : private Finalizer {
 };
 
 inline napi_env NewEnv(v8::Local<v8::Context> context,
-                       const std::string& module_filename) {
+                       const std::string& module_filename,
+                       node_api_features* features) {
   node_napi_env result;
 
-  result = new node_napi_env__(context, module_filename);
+  result = new node_napi_env__(context, module_filename, features);
   // TODO(addaleax): There was previously code that tried to delete the
   // napi_env when its v8::Context was garbage collected;
   // However, as long as N-API addons using this napi_env are in place,
@@ -586,24 +588,42 @@ class AsyncContext {
 
 }  // end of namespace v8impl
 
+void napi_module_register_by_symbol_with_features(
+    v8::Local<v8::Object> exports,
+    v8::Local<v8::Value> module,
+    v8::Local<v8::Context> context,
+    napi_addon_register_func init,
+    node_api_features* features);
+
 // Intercepts the Node-V8 module registration callback. Converts parameters
 // to NAPI equivalents and then calls the registration callback specified
 // by the NAPI module.
 static void napi_module_register_cb(v8::Local<v8::Object> exports,
                                     v8::Local<v8::Value> module,
                                     v8::Local<v8::Context> context,
                                     void* priv) {
-  napi_module_register_by_symbol(
+  napi_module_register_by_symbol_with_features(
       exports,
       module,
       context,
-      static_cast<const napi_module*>(priv)->nm_register_func);
+      static_cast<const napi_module*>(priv)->nm_register_func,
+      static_cast<const napi_module*>(priv)->nm_features);
 }
 
 void napi_module_register_by_symbol(v8::Local<v8::Object> exports,
                                     v8::Local<v8::Value> module,
                                     v8::Local<v8::Context> context,
                                     napi_addon_register_func init) {
+  napi_module_register_by_symbol_with_features(
+      exports, module, context, init, nullptr);
+}
+
+void napi_module_register_by_symbol_with_features(
+    v8::Local<v8::Object> exports,
+    v8::Local<v8::Value> module,
+    v8::Local<v8::Context> context,
+    napi_addon_register_func init,
+    node_api_features* features) {
   node::Environment* node_env = node::Environment::GetCurrent(context);
   std::string module_filename = "";
   if (init == nullptr) {
@@ -631,7 +651,7 @@ void napi_module_register_by_symbol(v8::Local<v8::Object> exports,
   }
 
   // Create a new napi_env for this specific module.
-  napi_env env = v8impl::NewEnv(context, module_filename);
+  napi_env env = v8impl::NewEnv(context, module_filename, features);
 
   napi_value _exports;
   env->CallIntoModule([&](napi_env env) {

src/node_api.h

@@ -38,7 +38,12 @@ typedef struct napi_module {
   napi_addon_register_func nm_register_func;
   const char* nm_modname;
   void* nm_priv;
+#ifdef NAPI_EXPERIMENTAL
+  node_api_features* nm_features;
+  void* reserved[3];
+#else
   void* reserved[4];
+#endif
 } napi_module;
 
 #define NAPI_MODULE_VERSION 1
@@ -73,16 +78,39 @@ typedef struct napi_module {
   static void fn(void)
 #endif
 
+#ifdef NAPI_EXPERIMENTAL
+#ifdef NODE_API_CUSTOM_FEATURES
+
+// Define value of node_api_module_features variable in your module when
+// NODE_API_CUSTOM_FEATURES is set in gyp file.
+extern node_api_features node_api_module_features;
+#define NODE_API_DEFINE_DEFAULT_FEATURES
+
+#else  // NODE_API_CUSTOM_FEATURES
+
+#define NODE_API_DEFINE_DEFAULT_FEATURES                                       \
+  static node_api_features node_api_module_features = node_api_default_features;
+
+#endif  // NODE_API_CUSTOM_FEATURES
+
+#define NODE_API_FEATURES_PTR /* NOLINT */ &node_api_module_features,
+
+#else  // NAPI_EXPERIMENTAL
+#define NODE_API_DEFINE_DEFAULT_FEATURES
+#define NODE_API_FEATURES_PTR
+#endif  // NAPI_EXPERIMENTAL
+
 #define NAPI_MODULE_X(modname, regfunc, priv, flags)                           \
   EXTERN_C_START                                                               \
+  NODE_API_DEFINE_DEFAULT_FEATURES                                             \
   static napi_module _module = {                                               \
       NAPI_MODULE_VERSION,                                                     \
       flags,                                                                   \
       __FILE__,                                                                \
       regfunc,                                                                 \
       #modname,                                                                \
       priv,                                                                    \
-      {0},                                                                     \
+      NODE_API_FEATURES_PTR{0},                                                \
   };                                                                           \
   NAPI_C_CTOR(_register_##modname) { napi_module_register(&_module); }         \
   EXTERN_C_END

src/node_api_internals.h

@@ -10,7 +10,8 @@
 
 struct node_napi_env__ : public napi_env__ {
   node_napi_env__(v8::Local<v8::Context> context,
-                  const std::string& module_filename);
+                  const std::string& module_filename,
+                  node_api_features* features);
 
   bool can_call_into_js() const override;
   v8::Maybe<bool> mark_arraybuffer_as_untransferable(

test/js-native-api/common.h

@@ -1,3 +1,4 @@
+#define NAPI_EXPERIMENTAL
 #include <js_native_api.h>
 
 // Empty value so that macros here are able to return NULL or void

test/js-native-api/entry_point.c

@@ -1,3 +1,4 @@
+#define NAPI_EXPERIMENTAL
 #include <node_api.h>
 
 EXTERN_C_START

test/js-native-api/test_reference/binding.gyp

@@ -5,7 +5,8 @@
       "sources": [
         "../entry_point.c",
         "test_reference.c"
-      ]
+      ],
+      'defines': [ 'NODE_API_CUSTOM_FEATURES' ]
     }
   ]
 }

test/js-native-api/test_reference/test_reference.c

@@ -283,4 +283,9 @@ napi_value Init(napi_env env, napi_value exports) {
 
   return exports;
 }
+
+// Make sure that this test uses the old napi_ref behavior.
+node_api_features node_api_module_features =
+  node_api_default_features & ~node_api_feature_reference_all_types;
+
 EXTERN_C_END

test/js-native-api/test_reference_all_types/binding.gyp

@@ -0,0 +1,11 @@
+{
+  "targets": [
+    {
+      "target_name": "test_reference_all_types",
+      "sources": [
+        "../entry_point.c",
+        "test_reference_all_types.c"
+      ]
+    }
+  ]
+}