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. PR-URL: #55676 Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com>

Author: gabrielschulhof

doc/api/n-api.md

@@ -1748,7 +1748,7 @@ will not be freed. This can be avoided by calling
 
 **Change History:**
 
-* Experimental (`NAPI_EXPERIMENTAL` is defined):
+* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
 
  References can be created for all value types. The new supported value
  types do not support weak reference semantic and the values of these types
@@ -2700,10 +2700,9 @@ JavaScript `TypedArray` objects are described in
 
 <!-- YAML
 added: v23.0.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
  napi_value arraybuffer,
@@ -2965,10 +2964,9 @@ The JavaScript `string` type is described in
 added:
  - v20.4.0
  - v18.18.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status
 node_api_create_external_string_latin1(napi_env env,
@@ -3045,10 +3043,9 @@ The JavaScript `string` type is described in
 added:
  - v20.4.0
  - v18.18.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status
 node_api_create_external_string_utf16(napi_env env,
@@ -3140,10 +3137,9 @@ creation methods.
 added:
  - v22.9.0
  - v20.18.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
  const char* str,
@@ -3175,10 +3171,9 @@ The JavaScript `string` type is described in
 added:
  - v21.7.0
  - v20.12.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
  const char16_t* str,
@@ -3208,10 +3203,9 @@ The JavaScript `string` type is described in
 added:
  - v22.9.0
  - v20.18.0
+napiVersion: 10
 -->
 
-> Stability: 1 - Experimental
-
 ```c
 napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
  const char* str,
@@ -6531,7 +6525,7 @@ napi_create_threadsafe_function(napi_env env,
 
 **Change History:**
 
-* Experimental (`NAPI_EXPERIMENTAL` is defined):
+* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
 
  Uncaught exceptions thrown in `call_js_cb` are handled with the
  [`'uncaughtException'`][] event, instead of being ignored.

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}
@@ -170,7 +170,7 @@ stability banner:
  <!-- YAML
  added:
  - v1.2.3
-+ napiVersion: 10
++ napiVersion: 11
  -->
 
 - > Stability: 1 - Experimental
@@ -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

@@ -234,11 +234,11 @@ inline napi_status napi_set_last_error(node_api_basic_env basic_env,
  CHECK_ENV_NOT_IN_GC((env)); \
  RETURN_STATUS_IF_FALSE( \
  (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 \
-  ? napi_cannot_run_js  \
- : napi_pending_exception));   \
+ RETURN_STATUS_IF_FALSE(  \
+ (env),   \
+ (env)->can_call_into_js(),   \
+ (env->module_api_version >= 10 ? napi_cannot_run_js \
+   : napi_pending_exception)); \
  napi_clear_last_error((env)); \
  v8impl::TryCatch try_catch((env))
 

src/node_api.cc

@@ -93,11 +93,11 @@ void node_napi_env__::CallbackIntoModule(T&& call) {
  return;
  }
  node::Environment* node_env = env->node_env();
- // If the module api version is less than NAPI_VERSION_EXPERIMENTAL,
- // and the option --force-node-api-uncaught-exceptions-policy is not
- // specified, emit a warning about the uncaught exception instead of
- // triggering uncaught exception event.
- if (env->module_api_version < NAPI_VERSION_EXPERIMENTAL &&
+ // If the module api version is less than 10, and the option
+ // --force-node-api-uncaught-exceptions-policy is not specified, emit a
+ // warning about the uncaught exception instead of triggering the uncaught
+ // exception event.
+ if (env->module_api_version < 10 &&
  !node_env->options()->force_node_api_uncaught_exceptions_policy &&
  !enforceUncaughtExceptionPolicy) {
  ProcessEmitDeprecationWarning(
@@ -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

@@ -133,16 +133,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_cannot_run_js/binding.gyp

@@ -5,14 +5,14 @@
  "sources": [
  "test_cannot_run_js.c"
  ],
- "defines": [ "NAPI_EXPERIMENTAL" ],
+ "defines": [ "NAPI_VERSION=10" ],
  },
  {
  "target_name": "test_pending_exception",
  "sources": [
  "test_cannot_run_js.c"
  ],
- "defines": [ "NAPI_VERSION=8" ],
+ "defines": [ "NAPI_VERSION=9" ],
  }
  ]
 }

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

@@ -22,7 +22,7 @@ static void Finalize(napi_env env, void* data, void* hint) {
  // napi_pending_exception is returned). This is not deterministic from
  // the point of view of the addon.
 
-#ifdef NAPI_EXPERIMENTAL
+#if NAPI_VERSION > 9
  NODE_API_BASIC_ASSERT_RETURN_VOID(
  result == napi_cannot_run_js || result == napi_ok,
  "getting named property from global in finalizer should succeed "
@@ -32,19 +32,10 @@ static void Finalize(napi_env env, void* data, void* hint) {
  result == napi_pending_exception || result == napi_ok,
  "getting named property from global in finalizer should succeed "
  "or return napi_pending_exception");
-#endif // NAPI_EXPERIMENTAL
+#endif // NAPI_VERSION > 9
  free(ref);
 }
 
-static void BasicFinalize(node_api_basic_env env, void* data, void* hint) {
-#ifdef NAPI_EXPERIMENTAL
- NODE_API_BASIC_CALL_RETURN_VOID(
- env, node_api_post_finalizer(env, Finalize, data, hint));
-#else
- Finalize(env, data, hint);
-#endif
-}
-
 static napi_value CreateRef(napi_env env, napi_callback_info info) {
  size_t argc = 1;
  napi_value cb;
@@ -55,8 +46,7 @@ static napi_value CreateRef(napi_env env, napi_callback_info info) {
  NODE_API_CALL(env, napi_typeof(env, cb, &value_type));
  NODE_API_ASSERT(
  env, value_type == napi_function, "argument must be function");
- NODE_API_CALL(env,
- napi_add_finalizer(env, cb, ref, BasicFinalize, NULL, ref));
+ NODE_API_CALL(env, napi_add_finalizer(env, cb, ref, Finalize, NULL, ref));
  return cb;
 }