node-api: introduce experimental feature flags

gabrielschulhof · richardlau · commit 3d0b233f527a · 2024-03-22T16:04:36.000Z
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 <midawson@redhat.com> Reviewed-By: Vladimir Morozov <vmorozov@microsoft.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Backport-PR-URL: #51804 (cherry picked from commit 727dd28)
diff --git a/doc/contributing/adding-new-napi-api.md b/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:
diff --git a/doc/contributing/releases-node-api.md b/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`:
 
diff --git a/src/js_native_api.h b/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,
