node-api: define version 10

Notable runtime changes to existing APIs:
- returning `node_api_cannot_run_js` instead of `napi_pending_exception`.
- allow creating references to objects, functions, and symbols.

Author: gabrielschulhof

doc/contributing/releases-node-api.md

@@ -85,7 +85,7 @@ with:
 
 ```bash
 grep                           \
-  -E                           \
+  -nHE                         \
   'N(ODE_)?API_EXPERIMENTAL'   \
   src/js_native_api{_types,}.h \
   src/node_api{_types,}.h
@@ -95,13 +95,13 @@ and update the define version guards with the release version:
 
 ```diff
 - #ifdef NAPI_EXPERIMENTAL
-+ #if NAPI_VERSION >= 10
++ #if NAPI_VERSION >= 11
 
   NAPI_EXTERN napi_status NAPI_CDECL
   node_api_function(napi_env env);
 
 - #endif  // NAPI_EXPERIMENTAL
-+ #endif  // NAPI_VERSION >= 10
++ #endif  // NAPI_VERSION >= 11
 ```
 
 Remove any feature flags of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>`.
@@ -121,11 +121,11 @@ Also, update the Node-API version value of the `napi_get_version` test in
 #### Step 2. Update runtime version guards
 
 If this release includes runtime behavior version guards, the relevant commits
-should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
-for these guards with:
+should already include the `NAPI_VERSION_EXPERIMENTAL` guard for the change.
+Check for these guards with:
 
 ```bash
-grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
+grep -nH NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
 ```
 
 and substitute this guard version with the release version `x`.
@@ -138,7 +138,7 @@ Check for these definitions with:
 
 ```bash
 grep                                    \
-  -E                                    \
+  -nHE                                  \
   'N(ODE_)?API_EXPERIMENTAL'            \
   test/node-api/*/{*.{h,c},binding.gyp} \
   test/js-native-api/*/{*.{h,c},binding.gyp}
@@ -186,7 +186,7 @@ For all runtime version guards updated in Step 2, check for these definitions
 with:
 
 ```bash
-grep NAPI_EXPERIMENTAL doc/api/n-api.md
+grep -nH NAPI_EXPERIMENTAL doc/api/n-api.md
 ```
 
 In `doc/api/n-api.md`, update the `experimental` change history item to be the

src/js_native_api.h

@@ -92,8 +92,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
                                                             const char16_t* str,
                                                             size_t length,
                                                             napi_value* result);
-#ifdef NAPI_EXPERIMENTAL
-#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
+#if NAPI_VERSION >= 10
 NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
     napi_env env,
     char* str,
@@ -110,17 +109,14 @@ node_api_create_external_string_utf16(napi_env env,
                                       void* finalize_hint,
                                       napi_value* result,
                                       bool* copied);
-#endif  // NAPI_EXPERIMENTAL
 
-#ifdef NAPI_EXPERIMENTAL
-#define NODE_API_EXPERIMENTAL_HAS_PROPERTY_KEYS
 NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_latin1(
     napi_env env, const char* str, size_t length, napi_value* result);
 NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf8(
     napi_env env, const char* str, size_t length, napi_value* result);
 NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf16(
     napi_env env, const char16_t* str, size_t length, napi_value* result);
-#endif  // NAPI_EXPERIMENTAL
+#endif  // NAPI_VERSION >= 10
 
 NAPI_EXTERN napi_status NAPI_CDECL napi_create_symbol(napi_env env,
                                                       napi_value description,

src/js_native_api_v8.cc

@@ -2753,7 +2753,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
   CHECK_ARG(env, result);
 
   v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
-  if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
+  if (env->module_api_version < 10) {
     if (!(v8_value->IsObject() || v8_value->IsFunction() ||
           v8_value->IsSymbol())) {
       return napi_set_last_error(env, napi_invalid_arg);

src/js_native_api_v8.h

@@ -236,7 +236,7 @@ inline napi_status napi_set_last_error(node_api_basic_env basic_env,
       (env), (env)->last_exception.IsEmpty(), napi_pending_exception);         \
   RETURN_STATUS_IF_FALSE((env),                                                \
                          (env)->can_call_into_js(),                            \
-                         (env->module_api_version == NAPI_VERSION_EXPERIMENTAL \
+                         (env->module_api_version >= 10                        \
                               ? napi_cannot_run_js                             \
                               : napi_pending_exception));                      \
   napi_clear_last_error((env));                                                \

src/node_api.cc

@@ -678,11 +678,13 @@ node::addon_context_register_func get_node_api_context_register_func(
     const char* module_name,
     int32_t module_api_version) {
   static_assert(
-      NODE_API_SUPPORTED_VERSION_MAX == 9,
+      NODE_API_SUPPORTED_VERSION_MAX == 10,
       "New version of Node-API requires adding another else-if statement below "
       "for the new version and updating this assert condition.");
   if (module_api_version == 9) {
     return node_api_context_register_func<9>;
+  } else if (module_api_version == 10) {
+    return node_api_context_register_func<10>;
   } else if (module_api_version == NAPI_VERSION_EXPERIMENTAL) {
     return node_api_context_register_func<NAPI_VERSION_EXPERIMENTAL>;
   } else if (module_api_version >= NODE_API_SUPPORTED_VERSION_MIN &&

src/node_api.h

@@ -136,16 +136,15 @@ napi_create_external_buffer(napi_env env,
                             napi_value* result);
 #endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
 
-#ifdef NAPI_EXPERIMENTAL
-#define NODE_API_EXPERIMENTAL_HAS_CREATE_BUFFER_FROM_ARRAYBUFFER
+#if NAPI_VERSION >= 10
 
 NAPI_EXTERN napi_status NAPI_CDECL
 node_api_create_buffer_from_arraybuffer(napi_env env,
                                         napi_value arraybuffer,
                                         size_t byte_offset,
                                         size_t byte_length,
                                         napi_value* result);
-#endif  // NAPI_EXPERIMENTAL
+#endif  // NAPI_VERSION >= 10
 
 NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
                                                            size_t length,

src/node_version.h

@@ -100,7 +100,7 @@
 
 // The NAPI_VERSION supported by the runtime. This is the inclusive range of
 // versions which the Node.js binary being built supports.
-#define NODE_API_SUPPORTED_VERSION_MAX 9
+#define NODE_API_SUPPORTED_VERSION_MAX 10
 #define NODE_API_SUPPORTED_VERSION_MIN 1
 
 // Node API modules use NAPI_VERSION 8 by default if it is not explicitly

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

@@ -2,7 +2,6 @@
   "targets": [
     {
       "target_name": "test_finalizer",
-      "defines": [ "NAPI_EXPERIMENTAL" ],
       "sources": [
         "test_finalizer.c"
       ]

test/js-native-api/test_general/test.js

@@ -34,7 +34,7 @@ assert.notStrictEqual(test_general.testGetPrototype(baseObject),
                       test_general.testGetPrototype(extendedObject));
 
 // Test version management functions
-assert.strictEqual(test_general.testGetVersion(), 9);
+assert.strictEqual(test_general.testGetVersion(), 10);
 
 [
   123,

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

@@ -6,9 +6,6 @@
         "test_string.c",
         "test_null.c",
       ],
-      "defines": [
-        "NAPI_EXPERIMENTAL",
-      ],
     },
   ],
 }