From f20e16993b07f2d62347197605015aef4d37cce3 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Thu, 30 Nov 2023 23:33:59 -0800 Subject: [PATCH] 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. --- doc/contributing/adding-new-napi-api.md | 4 ++++ doc/contributing/releases-node-api.md | 2 ++ src/js_native_api.h | 2 ++ 3 files changed, 8 insertions(+) diff --git a/doc/contributing/adding-new-napi-api.md b/doc/contributing/adding-new-napi-api.md index 8d2233bc30f690..e834a395b6206f 100644 --- 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_` **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 index f2277b228ec0d6..5f4e6df9a5c3bc 100644 --- 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_`. + 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 index d665052b947552..a3ee3a0e224262 100644 --- 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,