node-api: add node_api_symbol_for()

Fixes: #41294 Signed-off-by: Darshan Sen <[email protected]> PR-URL: #41329 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Michael Dawson <[email protected]> Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: James M Snell <[email protected]>

Author: RaisinTen

doc/api/n-api.md

@@ -2492,6 +2492,38 @@ This API creates a JavaScript `symbol` value from a UTF8-encoded C string.
 The JavaScript `symbol` type is described in [Section 19.4][]
 of the ECMAScript Language Specification.
 
+#### `node_api_symbol_for`
+
+<!-- YAML
+added: REPLACEME
+napiVersion: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status node_api_symbol_for(napi_env env,
+ const char* utf8description,
+ size_t length,
+ napi_value* result)
+```
+
+* `[in] env`: The environment that the API is invoked under.
+* `[in] utf8description`: UTF-8 C string representing the text to be used as the
+ description for the symbol.
+* `[in] length`: The length of the description string in bytes, or
+ `NAPI_AUTO_LENGTH` if it is null-terminated.
+* `[out] result`: A `napi_value` representing a JavaScript `symbol`.
+
+Returns `napi_ok` if the API succeeded.
+
+This API searches in the global registry for an existing symbol with the given
+description. If the symbol already exists it will be returned, otherwise a new
+symbol will be created in the registry.
+
+The JavaScript `symbol` type is described in [Section 19.4][] of the ECMAScript
+Language Specification.
+
 #### `napi_create_typedarray`
 
 <!-- YAML

src/js_native_api.h

@@ -93,6 +93,12 @@ NAPI_EXTERN napi_status napi_create_string_utf16(napi_env env,
 NAPI_EXTERNnapi_statusnapi_create_symbol(napi_envenv,
 napi_valuedescription,
 napi_value*result);
+#ifdefNAPI_EXPERIMENTAL
+NAPI_EXTERNnapi_statusnode_api_symbol_for(napi_envenv,
+constchar*utf8description,
+size_tlength,
+napi_value*result);
+#endif// NAPI_EXPERIMENTAL
 NAPI_EXTERNnapi_statusnapi_create_function(napi_envenv,
 constchar*utf8name,
 size_tlength,

src/js_native_api_v8.cc

@@ -1662,6 +1662,27 @@ napi_status napi_create_symbol(napi_env env,
 returnnapi_clear_last_error(env);
 }
 
+napi_status node_api_symbol_for(napi_env env,
+constchar* utf8description,
+size_t length,
+ napi_value* result){
+CHECK_ENV(env);
+CHECK_ARG(env, result);
+
+ napi_value js_description_string;
+STATUS_CALL(napi_create_string_utf8(env,
+ utf8description,
+ length,
+ &js_description_string));
+ v8::Local<v8::String> description_string =
+v8impl::V8LocalValueFromJsValue(js_description_string).As<v8::String>();
+
+ *result = v8impl::JsValueFromV8LocalValue(
+v8::Symbol::For(env->isolate, description_string));
+
+returnnapi_clear_last_error(env);
+}
+
 staticinline napi_status set_error_code(napi_env env,
  v8::Local<v8::Value> error,
  napi_value code,

test/js-native-api/test_properties/test.js

@@ -35,12 +35,11 @@ assert.ok(!propertyNames.includes('readwriteAccessor2'));
 assert.ok(!propertyNames.includes('readonlyAccessor1'));
 assert.ok(!propertyNames.includes('readonlyAccessor2'));
 
-// Validate property created with symbol
-conststart='Symbol('.length;
-constend=start+'NameKeySymbol'.length;
-constsymbolDescription=
-String(Object.getOwnPropertySymbols(test_object)[0]).slice(start,end);
-assert.strictEqual(symbolDescription,'NameKeySymbol');
+// Validate properties created with symbol
+constpropertySymbols=Object.getOwnPropertySymbols(test_object);
+assert.strictEqual(propertySymbols[0].toString(),'Symbol(NameKeySymbol)');
+assert.strictEqual(propertySymbols[1].toString(),'Symbol()');
+assert.strictEqual(propertySymbols[2],Symbol.for('NameKeySymbolFor'));
 
 // The napi_writable attribute should be ignored for accessors.
 constreadwriteAccessor1Descriptor=

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

@@ -1,3 +1,4 @@
+#defineNAPI_EXPERIMENTAL
 #include<js_native_api.h>
 #include"../common.h"
 
@@ -77,13 +78,25 @@ napi_value Init(napi_env env, napi_value exports){
 NODE_API_CALL(env,
 napi_create_symbol(env, symbol_description, &name_symbol));
 
+napi_valuename_symbol_descriptionless;
+NODE_API_CALL(env,
+napi_create_symbol(env, NULL, &name_symbol_descriptionless));
+
+napi_valuename_symbol_for;
+NODE_API_CALL(env, node_api_symbol_for(env,
+"NameKeySymbolFor",
+NAPI_AUTO_LENGTH,
+&name_symbol_for));
+
 napi_property_descriptorproperties[] ={
 {"echo", 0, Echo, 0, 0, 0, napi_enumerable, 0 },
 {"readwriteValue", 0, 0, 0, 0, number, napi_enumerable | napi_writable, 0 },
 {"readonlyValue", 0, 0, 0, 0, number, napi_enumerable, 0},
 {"hiddenValue", 0, 0, 0, 0, number, napi_default, 0},
 {NULL, name_value, 0, 0, 0, number, napi_enumerable, 0},
 {NULL, name_symbol, 0, 0, 0, number, napi_enumerable, 0},
+{NULL, name_symbol_descriptionless, 0, 0, 0, number, napi_enumerable, 0},
+{NULL, name_symbol_for, 0, 0, 0, number, napi_enumerable, 0},
 {"readwriteAccessor1", 0, 0, GetValue, SetValue, 0, napi_default, 0},
 {"readwriteAccessor2", 0, 0, GetValue, SetValue, 0, napi_writable, 0},
 {"readonlyAccessor1", 0, 0, GetValue, NULL, 0, napi_default, 0},

test/js-native-api/test_reference/test.js

@@ -21,6 +21,25 @@ async function runTests(){
 })();
 test_reference.deleteReference();
 
+(()=>{
+constsymbol=test_reference.createSymbolFor('testSymFor');
+test_reference.createReference(symbol,0);
+assert.strictEqual(test_reference.referenceValue,symbol);
+assert.strictEqual(test_reference.referenceValue,Symbol.for('testSymFor'));
+})();
+test_reference.deleteReference();
+
+(()=>{
+constsymbol=test_reference.createSymbolForEmptyString();
+test_reference.createReference(symbol,0);
+assert.strictEqual(test_reference.referenceValue,symbol);
+assert.strictEqual(test_reference.referenceValue,Symbol.for(''));
+})();
+test_reference.deleteReference();
+
+assert.throws(()=>test_reference.createSymbolForIncorrectLength(),
+/Invalidargument/);
+
 (()=>{
 constvalue=test_reference.createExternal();
 assert.strictEqual(test_reference.finalizeCount,0);

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

@@ -1,3 +1,4 @@
+#defineNAPI_EXPERIMENTAL
 #include<stdlib.h>
 #include<assert.h>
 #include<js_native_api.h>
@@ -49,6 +50,41 @@ static napi_value CreateSymbol(napi_env env, napi_callback_info info){
 returnresult_symbol;
 }
 
+staticnapi_valueCreateSymbolFor(napi_envenv, napi_callback_infoinfo){
+
+size_targc=1;
+napi_valueargs[1];
+
+chardescription[256];
+size_tdescription_length;
+
+NODE_API_CALL(env, napi_get_cb_info(env, info, &argc, args, NULL,NULL));
+NODE_API_ASSERT(env, argc==1, "Expect one argument only (symbol description)");
+
+NODE_API_CALL(env, napi_get_value_string_utf8(env, args[0], description, sizeof(description), &description_length));
+NODE_API_ASSERT(env, description_length <= 255, "Cannot accommodate descriptions longer than 255 bytes");
+
+napi_valueresult_symbol;
+
+NODE_API_CALL(env, node_api_symbol_for(env,
+description,
+description_length,
+&result_symbol));
+returnresult_symbol;
+}
+
+staticnapi_valueCreateSymbolForEmptyString(napi_envenv, napi_callback_infoinfo){
+napi_valueresult_symbol;
+NODE_API_CALL(env, node_api_symbol_for(env, NULL, 0, &result_symbol));
+returnresult_symbol;
+}
+
+staticnapi_valueCreateSymbolForIncorrectLength(napi_envenv, napi_callback_infoinfo){
+napi_valueresult_symbol;
+NODE_API_CALL(env, node_api_symbol_for(env, NULL, 5, &result_symbol));
+returnresult_symbol;
+}
+
 staticnapi_value
 CreateExternalWithFinalize(napi_envenv, napi_callback_infoinfo){
 napi_valueresult;
@@ -190,6 +226,9 @@ napi_value Init(napi_env env, napi_value exports){
 DECLARE_NODE_API_PROPERTY("checkExternal", CheckExternal),
 DECLARE_NODE_API_PROPERTY("createReference", CreateReference),
 DECLARE_NODE_API_PROPERTY("createSymbol", CreateSymbol),
+DECLARE_NODE_API_PROPERTY("createSymbolFor", CreateSymbolFor),
+DECLARE_NODE_API_PROPERTY("createSymbolForEmptyString", CreateSymbolForEmptyString),
+DECLARE_NODE_API_PROPERTY("createSymbolForIncorrectLength", CreateSymbolForIncorrectLength),
 DECLARE_NODE_API_PROPERTY("deleteReference", DeleteReference),
 DECLARE_NODE_API_PROPERTY("incrementRefcount", IncrementRefcount),
 DECLARE_NODE_API_PROPERTY("decrementRefcount", DecrementRefcount),