node-api: introduce experimental feature flags

Add a flag for each experimental feature to indicate its presence.
That way, if we compile with `NAPI_EXPERIMENTAL` turned on, we'll be
able to distinguish between what `NAPI_EXPERIMENTAL` used to mean on an
old version of the headers when compiling against such an old version,
and what it means on a new version of Node.js.

PR-URL: #50991
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Vladimir Morozov <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Backport-PR-URL: #51804
(cherry picked from commit 727dd28)

Author: gabrielschulhof

doc/contributing/adding-new-napi-api.md

@@ -34,6 +34,10 @@ Node-API.
   * Experimental APIs **must** be documented as such.
   * Experimental APIs **must** require an explicit compile-time flag
     (`#define`) to be set to opt-in.
+  * A feature flag of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>` **must**
+    be added with each experimental feature in order to allow code to
+    distinguish between experimental features as present in one version of
+    Node.js versus another.
   * Experimental APIs **must** be considered for backport.
   * Experimental status exit criteria **must** involve at least the
     following:

doc/contributing/releases-node-api.md

@@ -100,6 +100,8 @@ and update the define version guards with the release version:
 + #endif  // NAPI_VERSION >= 10
 ```
 
+Remove any feature flags of the form `NODE_API_EXPERIMENTAL_HAS_<FEATURE>`.
+
 Also, update the Node-API version value of the `napi_get_version` test in
 `test/js-native-api/test_general/test.js` with the release version `x`:
 

src/js_native_api.h

@@ -93,6 +93,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
                                                             size_t length,
                                                             napi_value* result);
 #ifdef NAPI_EXPERIMENTAL
+#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
 NAPI_EXTERN napi_status NAPI_CDECL
 node_api_create_external_string_latin1(napi_env env,
                                        char* str,
@@ -518,6 +519,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_add_finalizer(napi_env env,
 #endif  // NAPI_VERSION >= 5
 
 #ifdef NAPI_EXPERIMENTAL
+#define NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
 
 NAPI_EXTERN napi_status NAPI_CDECL
 node_api_post_finalizer(napi_env env,