Skip to content

Commit c2f4d8d

Browse files
gabrielschulhofaduh95
gabrielschulhof
authored and
aduh95
committed
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 <[email protected]> Reviewed-By: James M Snell <[email protected]>
1 parent 4f77920 commit c2f4d8d

File tree

14 files changed

+46
-65
lines changed

14 files changed

+46
-65
lines changed

‎doc/api/n-api.md

+8-14
Original file line numberDiff line numberDiff line change
@@ -1748,7 +1748,7 @@ will not be freed. This can be avoided by calling
17481748

17491749
**Change History:**
17501750

1751-
* Experimental (`NAPI_EXPERIMENTAL` is defined):
1751+
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
17521752

17531753
References can be created for all value types. The new supported value
17541754
types do not support weak reference semantic and the values of these types
@@ -2700,10 +2700,9 @@ JavaScript `TypedArray` objects are described in
27002700

27012701
<!-- YAML
27022702
added: v23.0.0
2703+
napiVersion: 10
27032704
-->
27042705

2705-
> Stability: 1 - Experimental
2706-
27072706
```c
27082707
napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,
27092708
napi_value arraybuffer,
@@ -2965,10 +2964,9 @@ The JavaScript `string` type is described in
29652964
added:
29662965
- v20.4.0
29672966
- v18.18.0
2967+
napiVersion: 10
29682968
-->
29692969

2970-
> Stability: 1 - Experimental
2971-
29722970
```c
29732971
napi_status
29742972
node_api_create_external_string_latin1(napi_env env,
@@ -3045,10 +3043,9 @@ The JavaScript `string` type is described in
30453043
added:
30463044
- v20.4.0
30473045
- v18.18.0
3046+
napiVersion: 10
30483047
-->
30493048

3050-
> Stability: 1 - Experimental
3051-
30523049
```c
30533050
napi_status
30543051
node_api_create_external_string_utf16(napi_env env,
@@ -3140,10 +3137,9 @@ creation methods.
31403137
added:
31413138
- v22.9.0
31423139
- v20.18.0
3140+
napiVersion: 10
31433141
-->
31443142

3145-
> Stability: 1 - Experimental
3146-
31473143
```c
31483144
napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,
31493145
const char* str,
@@ -3175,10 +3171,9 @@ The JavaScript `string` type is described in
31753171
added:
31763172
- v21.7.0
31773173
- v20.12.0
3174+
napiVersion: 10
31783175
-->
31793176

3180-
> Stability: 1 - Experimental
3181-
31823177
```c
31833178
napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,
31843179
const char16_t* str,
@@ -3208,10 +3203,9 @@ The JavaScript `string` type is described in
32083203
added:
32093204
- v22.9.0
32103205
- v20.18.0
3206+
napiVersion: 10
32113207
-->
32123208

3213-
> Stability: 1 - Experimental
3214-
32153209
```c
32163210
napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,
32173211
const char* str,
@@ -6531,7 +6525,7 @@ napi_create_threadsafe_function(napi_env env,
65316525

65326526
**Change History:**
65336527

6534-
* Experimental (`NAPI_EXPERIMENTAL` is defined):
6528+
* Version 10 (`NAPI_VERSION` is defined as `10` or higher):
65356529

65366530
Uncaught exceptions thrown in `call_js_cb` are handled with the
65376531
[`'uncaughtException'`][] event, instead of being ignored.

‎doc/contributing/releases-node-api.md

+9-9
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ with:
8585
8686
```bash
8787
grep \
88-
-E \
88+
-nHE \
8989
'N(ODE_)?API_EXPERIMENTAL' \
9090
src/js_native_api{_types,}.h \
9191
src/node_api{_types,}.h
@@ -95,13 +95,13 @@ and update the define version guards with the release version:
9595

9696
```diff
9797
- #ifdef NAPI_EXPERIMENTAL
98-
+ #if NAPI_VERSION >= 10
98+
+ #if NAPI_VERSION >= 11
9999

100100
NAPI_EXTERN napi_status NAPI_CDECL
101101
node_api_function(napi_env env);
102102

103103
- #endif // NAPI_EXPERIMENTAL
104-
+ #endif // NAPI_VERSION >= 10
104+
+ #endif // NAPI_VERSION >= 11
105105
```
106106
107107
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
121121
#### Step 2. Update runtime version guards
122122

123123
If this release includes runtime behavior version guards, the relevant commits
124-
should already include `NAPI_VERSION_EXPERIMENTAL` guard for the change. Check
125-
for these guards with:
124+
should already include the `NAPI_VERSION_EXPERIMENTAL` guard for the change.
125+
Check for these guards with:
126126

127127
```bash
128-
grep NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
128+
grep -nH NAPI_VERSION_EXPERIMENTAL src/js_native_api_v8* src/node_api.cc
129129
```
130130

131131
and substitute this guard version with the release version `x`.
@@ -138,7 +138,7 @@ Check for these definitions with:
138138

139139
```bash
140140
grep \
141-
-E \
141+
-nHE \
142142
'N(ODE_)?API_EXPERIMENTAL' \
143143
test/node-api/*/{*.{h,c},binding.gyp} \
144144
test/js-native-api/*/{*.{h,c},binding.gyp}
@@ -170,7 +170,7 @@ stability banner:
170170
<!-- YAML
171171
added:
172172
- v1.2.3
173-
+ napiVersion: 10
173+
+ napiVersion: 11
174174
-->
175175

176176
- > Stability: 1 - Experimental
@@ -186,7 +186,7 @@ For all runtime version guards updated in Step 2, check for these definitions
186186
with:
187187

188188
```bash
189-
grep NAPI_EXPERIMENTAL doc/api/n-api.md
189+
grep -nH NAPI_EXPERIMENTAL doc/api/n-api.md
190190
```
191191

192192
In `doc/api/n-api.md`, update the `experimental` change history item to be the

‎src/js_native_api.h

+2-6
Original file line numberDiff line numberDiff line change
@@ -92,8 +92,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
9292
const char16_t* str,
9393
size_t length,
9494
napi_value* result);
95-
#ifdef NAPI_EXPERIMENTAL
96-
#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
95+
#if NAPI_VERSION >= 10
9796
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
9897
napi_env env,
9998
char* str,
@@ -110,17 +109,14 @@ node_api_create_external_string_utf16(napi_env env,
110109
void* finalize_hint,
111110
napi_value* result,
112111
bool* copied);
113-
#endif // NAPI_EXPERIMENTAL
114112

115-
#ifdef NAPI_EXPERIMENTAL
116-
#define NODE_API_EXPERIMENTAL_HAS_PROPERTY_KEYS
117113
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_latin1(
118114
napi_env env, const char* str, size_t length, napi_value* result);
119115
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf8(
120116
napi_env env, const char* str, size_t length, napi_value* result);
121117
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf16(
122118
napi_env env, const char16_t* str, size_t length, napi_value* result);
123-
#endif // NAPI_EXPERIMENTAL
119+
#endif // NAPI_VERSION >= 10
124120

125121
NAPI_EXTERN napi_status NAPI_CDECL napi_create_symbol(napi_env env,
126122
napi_value description,

‎src/js_native_api_v8.cc

+1-1
Original file line numberDiff line numberDiff line change
@@ -2753,7 +2753,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
27532753
CHECK_ARG(env, result);
27542754

27552755
v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
2756-
if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
2756+
if (env->module_api_version < 10) {
27572757
if (!(v8_value->IsObject() || v8_value->IsFunction() ||
27582758
v8_value->IsSymbol())) {
27592759
return napi_set_last_error(env, napi_invalid_arg);

‎src/js_native_api_v8.h

+5-5
Original file line numberDiff line numberDiff line change
@@ -234,11 +234,11 @@ inline napi_status napi_set_last_error(node_api_basic_env basic_env,
234234
CHECK_ENV_NOT_IN_GC((env)); \
235235
RETURN_STATUS_IF_FALSE( \
236236
(env), (env)->last_exception.IsEmpty(), napi_pending_exception); \
237-
RETURN_STATUS_IF_FALSE((env), \
238-
(env)->can_call_into_js(), \
239-
(env->module_api_version == NAPI_VERSION_EXPERIMENTAL \
240-
? napi_cannot_run_js \
241-
: napi_pending_exception)); \
237+
RETURN_STATUS_IF_FALSE( \
238+
(env), \
239+
(env)->can_call_into_js(), \
240+
(env->module_api_version >= 10 ? napi_cannot_run_js \
241+
: napi_pending_exception)); \
242242
napi_clear_last_error((env)); \
243243
v8impl::TryCatch try_catch((env))
244244

‎src/node_api.cc

+8-6
Original file line numberDiff line numberDiff line change
@@ -93,11 +93,11 @@ void node_napi_env__::CallbackIntoModule(T&& call) {
9393
return;
9494
}
9595
node::Environment* node_env = env->node_env();
96-
// If the module api version is less than NAPI_VERSION_EXPERIMENTAL,
97-
// and the option --force-node-api-uncaught-exceptions-policy is not
98-
// specified, emit a warning about the uncaught exception instead of
99-
// triggering uncaught exception event.
100-
if (env->module_api_version < NAPI_VERSION_EXPERIMENTAL &&
96+
// If the module api version is less than 10, and the option
97+
// --force-node-api-uncaught-exceptions-policy is not specified, emit a
98+
// warning about the uncaught exception instead of triggering the uncaught
99+
// exception event.
100+
if (env->module_api_version < 10 &&
101101
!node_env->options()->force_node_api_uncaught_exceptions_policy &&
102102
!enforceUncaughtExceptionPolicy) {
103103
ProcessEmitDeprecationWarning(
@@ -678,11 +678,13 @@ node::addon_context_register_func get_node_api_context_register_func(
678678
const char* module_name,
679679
int32_t module_api_version) {
680680
static_assert(
681-
NODE_API_SUPPORTED_VERSION_MAX == 9,
681+
NODE_API_SUPPORTED_VERSION_MAX == 10,
682682
"New version of Node-API requires adding another else-if statement below "
683683
"for the new version and updating this assert condition.");
684684
if (module_api_version == 9) {
685685
return node_api_context_register_func<9>;
686+
} else if (module_api_version == 10) {
687+
return node_api_context_register_func<10>;
686688
} else if (module_api_version == NAPI_VERSION_EXPERIMENTAL) {
687689
return node_api_context_register_func<NAPI_VERSION_EXPERIMENTAL>;
688690
} else if (module_api_version >= NODE_API_SUPPORTED_VERSION_MIN &&

‎src/node_api.h

+2-3
Original file line numberDiff line numberDiff line change
@@ -133,16 +133,15 @@ napi_create_external_buffer(napi_env env,
133133
napi_value* result);
134134
#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
135135

136-
#ifdef NAPI_EXPERIMENTAL
137-
#define NODE_API_EXPERIMENTAL_HAS_CREATE_BUFFER_FROM_ARRAYBUFFER
136+
#if NAPI_VERSION >= 10
138137

139138
NAPI_EXTERN napi_status NAPI_CDECL
140139
node_api_create_buffer_from_arraybuffer(napi_env env,
141140
napi_value arraybuffer,
142141
size_t byte_offset,
143142
size_t byte_length,
144143
napi_value* result);
145-
#endif // NAPI_EXPERIMENTAL
144+
#endif // NAPI_VERSION >= 10
146145

147146
NAPI_EXTERN napi_status NAPI_CDECL napi_create_buffer_copy(napi_env env,
148147
size_t length,

‎src/node_version.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@
100100

101101
// The NAPI_VERSION supported by the runtime. This is the inclusive range of
102102
// versions which the Node.js binary being built supports.
103-
#define NODE_API_SUPPORTED_VERSION_MAX 9
103+
#define NODE_API_SUPPORTED_VERSION_MAX 10
104104
#define NODE_API_SUPPORTED_VERSION_MIN 1
105105

106106
// Node API modules use NAPI_VERSION 8 by default if it is not explicitly

‎test/js-native-api/test_cannot_run_js/binding.gyp

+2-2
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,14 @@
55
"sources": [
66
"test_cannot_run_js.c"
77
],
8-
"defines": [ "NAPI_EXPERIMENTAL" ],
8+
"defines": [ "NAPI_VERSION=10" ],
99
},
1010
{
1111
"target_name": "test_pending_exception",
1212
"sources": [
1313
"test_cannot_run_js.c"
1414
],
15-
"defines": [ "NAPI_VERSION=8" ],
15+
"defines": [ "NAPI_VERSION=9" ],
1616
}
1717
]
1818
}

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

+3-13
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ static void Finalize(napi_env env, void* data, void* hint) {
2222
// napi_pending_exception is returned). This is not deterministic from
2323
// the point of view of the addon.
2424

25-
#ifdef NAPI_EXPERIMENTAL
25+
#if NAPI_VERSION > 9
2626
NODE_API_BASIC_ASSERT_RETURN_VOID(
2727
result == napi_cannot_run_js || result == napi_ok,
2828
"getting named property from global in finalizer should succeed "
@@ -32,19 +32,10 @@ static void Finalize(napi_env env, void* data, void* hint) {
3232
result == napi_pending_exception || result == napi_ok,
3333
"getting named property from global in finalizer should succeed "
3434
"or return napi_pending_exception");
35-
#endif // NAPI_EXPERIMENTAL
35+
#endif // NAPI_VERSION > 9
3636
free(ref);
3737
}
3838

39-
static void BasicFinalize(node_api_basic_env env, void* data, void* hint) {
40-
#ifdef NAPI_EXPERIMENTAL
41-
NODE_API_BASIC_CALL_RETURN_VOID(
42-
env, node_api_post_finalizer(env, Finalize, data, hint));
43-
#else
44-
Finalize(env, data, hint);
45-
#endif
46-
}
47-
4839
static napi_value CreateRef(napi_env env, napi_callback_info info) {
4940
size_t argc = 1;
5041
napi_value cb;
@@ -55,8 +46,7 @@ static napi_value CreateRef(napi_env env, napi_callback_info info) {
5546
NODE_API_CALL(env, napi_typeof(env, cb, &value_type));
5647
NODE_API_ASSERT(
5748
env, value_type == napi_function, "argument must be function");
58-
NODE_API_CALL(env,
59-
napi_add_finalizer(env, cb, ref, BasicFinalize, NULL, ref));
49+
NODE_API_CALL(env, napi_add_finalizer(env, cb, ref, Finalize, NULL, ref));
6050
return cb;
6151
}
6252

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ assert.notStrictEqual(test_general.testGetPrototype(baseObject),
3434
test_general.testGetPrototype(extendedObject));
3535

3636
// Test version management functions
37-
assert.strictEqual(test_general.testGetVersion(), 9);
37+
assert.strictEqual(test_general.testGetVersion(), 10);
3838

3939
[
4040
123,

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

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
"test_null.c",
88
],
99
"defines": [
10-
"NAPI_EXPERIMENTAL",
10+
"NAPI_VERSION=10",
1111
],
1212
},
1313
],

‎test/node-api/test_buffer/binding.gyp

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
{
44
"target_name": "test_buffer",
55
"defines": [
6-
'NAPI_EXPERIMENTAL'
6+
'NAPI_VERSION=10'
77
],
88
"sources": [ "test_buffer.c" ]
99
},

‎test/node-api/test_reference_by_node_api_version/binding.gyp

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
{
44
"target_name": "test_reference_all_types",
55
"sources": [ "test_reference_by_node_api_version.c" ],
6-
"defines": [ "NAPI_EXPERIMENTAL" ],
6+
"defines": [ "NAPI_VERSION=10" ],
77
},
88
{
99
"target_name": "test_reference_obj_only",
1010
"sources": [ "test_reference_by_node_api_version.c" ],
11-
"defines": [ "NAPI_VERSION=8" ],
11+
"defines": [ "NAPI_VERSION=9" ],
1212
}
1313
]
1414
}

0 commit comments

Comments
 (0)