Finished first set of symbol tests

JckXia · JckXia · commit 26e2930c26a5 · 2021-07-09T15:45:20.000-04:00
Add new static method to symbol and updated tests

Updated Symbol.md 's docs, added function overload for Symbol class and new tests

Remove extra space and comments

Remove un-necssary string initialization

Update PR based on comments received

Add test checking if it's possible to pass nullptr to Symbol::For method

Update Symbol::For implementations and added new tests

Remove default parameter

Update documentation for Symbol
diff --git a/doc/symbol.md b/doc/symbol.md
@@ -34,7 +34,7 @@ If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
 being used, callers should check the result of `Napi::Env::IsExceptionPending` before
 attempting to use the returned value.
 
-### Utf8Value
+### WellKnown
 ```cpp
 static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& name);
 ```
@@ -45,4 +45,17 @@ static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& nam
 Returns a `Napi::Symbol` representing a well-known `Symbol` from the
 `Symbol` registry.
 
-[`Napi::Name`]: ./name.md
+### For
+```cpp
+static Napi::Symbol Napi::Symbol::For(napi_env env, const std::string& description);
+static Napi::Symbol Napi::Symbol::For(napi_env env, const char* description);
+static Napi::Symbol Napi::Symbol::For(napi_env env, String description);
+static Napi::Symbol Napi::Symbol::For(napi_env env, napi_value description);
+```
+
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object.
+- `[in] description`: The C++ string representing the `Napi::Symbol` in the global registry to retrieve.
+
+Searches in the global registry for existing symbol with the given name. If the symbol already exist it will be returned, otherwise a new symbol will be created in the registry. It's equivalent to Symbol.for() called from JavaScript.
+
+[`Napi::Name`]: ./name.md
diff --git a/napi-inl.h b/napi-inl.h
@@ -998,6 +998,27 @@ inline Symbol Symbol::WellKnown(napi_env env, const std::string& name) {
   return Napi::Env(env).Global().Get("Symbol").As<Object>().Get(name).As<Symbol>();
 }
 
+inline Symbol Symbol::For(napi_env env, const std::string& description) {
+  napi_value descriptionValue = String::New(env, description);
+  return Symbol::For(env, descriptionValue);
+}
+
+inline Symbol Symbol::For(napi_env env, const char* description) {
+  napi_value descriptionValue = String::New(env, description);
+  return Symbol::For(env, descriptionValue);
+}
+
+inline Symbol Symbol::For(napi_env env, String description) {
+  return Symbol::For(env, static_cast<napi_value>(description));
+}
+
+inline Symbol Symbol::For(napi_env env, napi_value description) {
+  Object symbObject = Napi::Env(env).Global().Get("Symbol").As<Object>();
+  auto forSymb =
+      symbObject.Get("for").As<Function>().Call(symbObject, {description});
+  return forSymb.As<Symbol>();
+}
+
 inline Symbol::Symbol() : Name() {
 }
 
@@ -2397,6 +2418,7 @@ inline const std::string& Error::Message() const NAPI_NOEXCEPT {
 inline void Error::ThrowAsJavaScriptException() const {
   HandleScope scope(_env);
   if (!IsEmpty()) {
+<<<<<<< HEAD
 #ifdef NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS
     bool pendingException = false;
 
@@ -2423,6 +2445,8 @@ inline void Error::ThrowAsJavaScriptException() const {
       status = napi_pending_exception;
     }
 #else
+=======
+>>>>>>> 7bfbd3e... Update Symbol::For implementations and added new tests
     // We intentionally don't use `NAPI_THROW_*` macros here to ensure
     // that there is no possible recursion as `ThrowAsJavaScriptException`
     // is part of `NAPI_THROW_*` macro definition for noexcept.
@@ -2740,19 +2764,31 @@ inline bool ObjectReference::Set(const char* utf8name, double numberValue) {
   return Value().Set(utf8name, numberValue);
 }
 
+<<<<<<< HEAD
 inline bool ObjectReference::Set(const std::string& utf8name,
+=======
+inline void ObjectReference::Set(const std::string& utf8name,
+>>>>>>> 7bfbd3e... Update Symbol::For implementations and added new tests
                                  napi_value value) {
   HandleScope scope(_env);
   return Value().Set(utf8name, value);
 }
 
+<<<<<<< HEAD
 inline bool ObjectReference::Set(const std::string& utf8name,
+=======
+inline void ObjectReference::Set(const std::string& utf8name,
+>>>>>>> 7bfbd3e... Update Symbol::For implementations and added new tests
                                  Napi::Value value) {
   HandleScope scope(_env);
   return Value().Set(utf8name, value);
 }
 
+<<<<<<< HEAD
 inline bool ObjectReference::Set(const std::string& utf8name,
+=======
+inline void ObjectReference::Set(const std::string& utf8name,
+>>>>>>> 7bfbd3e... Update Symbol::For implementations and added new tests
                                  std::string& utf8value) {
   HandleScope scope(_env);
   return Value().Set(utf8name, utf8value);
@@ -2763,7 +2799,11 @@ inline bool ObjectReference::Set(const std::string& utf8name, bool boolValue) {
   return Value().Set(utf8name, boolValue);
 }
 
+<<<<<<< HEAD
 inline bool ObjectReference::Set(const std::string& utf8name,
+=======
+inline void ObjectReference::Set(const std::string& utf8name,
+>>>>>>> 7bfbd3e... Update Symbol::For implementations and added new tests
                                  double numberValue) {
   HandleScope scope(_env);
   return Value().Set(utf8name, numberValue);
diff --git a/napi.h b/napi.h
@@ -538,6 +538,18 @@ namespace Napi {
    /// Get a public Symbol (e.g. Symbol.iterator).
    static Symbol WellKnown(napi_env, const std::string& name);
 
+   // Create a symbol in the global registry, UTF-8 Encoded cpp string
+   static Symbol For(napi_env env, const std::string& description);
+
+   // Create a symbol in the global registry, C style string (null terminated)
+   static Symbol For(napi_env env, const char* description);
+
+   // Create a symbol in the global registry, String value describing the symbol
+   static Symbol For(napi_env env, String description);
+
+   // Create a symbol in the global registry, napi_value describing the symbol
+   static Symbol For(napi_env env, napi_value description);
+
    Symbol();  ///< Creates a new _empty_ Symbol instance.
    Symbol(napi_env env,
           napi_value value);  ///< Wraps a Node-API value primitive.
diff --git a/test/binding.cc b/test/binding.cc
@@ -58,6 +58,7 @@ Object InitTypedThreadSafeFunctionSum(Env env);
 Object InitTypedThreadSafeFunctionUnref(Env env);
 Object InitTypedThreadSafeFunction(Env env);
 #endif
+Object InitSymbol(Env env);
 Object InitTypedArray(Env env);
 Object InitGlobalObject(Env env);
 Object InitObjectWrap(Env env);
@@ -117,6 +118,7 @@ Object Init(Env env, Object exports) {
 #endif // !NODE_ADDON_API_DISABLE_DEPRECATED
   exports.Set("promise", InitPromise(env));
   exports.Set("run_script", InitRunScript(env));
+  exports.Set("symbol", InitSymbol(env));
 #if (NAPI_VERSION > 3)
   exports.Set("threadsafe_function_ctx", InitThreadSafeFunctionCtx(env));
   exports.Set("threadsafe_function_existing_tsfn", InitThreadSafeFunctionExistingTsfn(env));
diff --git a/test/binding.gyp b/test/binding.gyp
@@ -46,6 +46,7 @@
         'object/subscript_operator.cc',
         'promise.cc',
         'run_script.cc',
+        "symbol.cc",
         'threadsafe_function/threadsafe_function_ctx.cc',
         'threadsafe_function/threadsafe_function_existing_tsfn.cc',
         'threadsafe_function/threadsafe_function_ptr.cc',
diff --git a/test/symbol.cc b/test/symbol.cc
@@ -0,0 +1,77 @@
+#include <napi.h>
+using namespace Napi;
+
+Symbol CreateNewSymbolWithNoArgs(const Napi::CallbackInfo&) {
+  return Napi::Symbol();
+}
+
+Symbol CreateNewSymbolWithCppStrDesc(const Napi::CallbackInfo& info) {
+  String cppStrKey = info[0].As<String>();
+  return Napi::Symbol::New(info.Env(), cppStrKey.Utf8Value());
+}
+
+Symbol CreateNewSymbolWithCStrDesc(const Napi::CallbackInfo& info) {
+  String cStrKey = info[0].As<String>();
+  return Napi::Symbol::New(info.Env(), cStrKey.Utf8Value().c_str());
+}
+
+Symbol CreateNewSymbolWithNapiString(const Napi::CallbackInfo& info) {
+  String strKey = info[0].As<String>();
+  return Napi::Symbol::New(info.Env(), strKey);
+}
+
+Symbol GetWellknownSymbol(const Napi::CallbackInfo& info) {
+  String registrySymbol = info[0].As<String>();
+  return Napi::Symbol::WellKnown(info.Env(),
+                                 registrySymbol.Utf8Value().c_str());
+}
+
+Symbol FetchSymbolFromGlobalRegistry(const Napi::CallbackInfo& info) {
+  String registrySymbol = info[0].As<String>();
+  return Napi::Symbol::For(info.Env(), registrySymbol);
+}
+
+Symbol FetchSymbolFromGlobalRegistryWithCppKey(const Napi::CallbackInfo& info) {
+  String cppStringKey = info[0].As<String>();
+  return Napi::Symbol::For(info.Env(), cppStringKey.Utf8Value());
+}
+
+Symbol FetchSymbolFromGlobalRegistryWithCKey(const Napi::CallbackInfo& info) {
+  String cppStringKey = info[0].As<String>();
+  return Napi::Symbol::For(info.Env(), cppStringKey.Utf8Value().c_str());
+}
+
+Symbol TestUndefinedSymbolsCanBeCreated(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  return Napi::Symbol::For(env, env.Undefined());
+}
+
+Symbol TestNullSymbolsCanBeCreated(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  return Napi::Symbol::For(env, env.Null());
+}
+
+Object InitSymbol(Env env) {
+  Object exports = Object::New(env);
+
+  exports["createNewSymbolWithNoArgs"] =
+      Function::New(env, CreateNewSymbolWithNoArgs);
+  exports["createNewSymbolWithCppStr"] =
+      Function::New(env, CreateNewSymbolWithCppStrDesc);
+  exports["createNewSymbolWithCStr"] =
+      Function::New(env, CreateNewSymbolWithCStrDesc);
+  exports["createNewSymbolWithNapi"] =
+      Function::New(env, CreateNewSymbolWithNapiString);
+  exports["getWellKnownSymbol"] = Function::New(env, GetWellknownSymbol);
+  exports["getSymbolFromGlobalRegistry"] =
+      Function::New(env, FetchSymbolFromGlobalRegistry);
+  exports["getSymbolFromGlobalRegistryWithCKey"] =
+      Function::New(env, FetchSymbolFromGlobalRegistryWithCKey);
+  exports["getSymbolFromGlobalRegistryWithCppKey"] =
+      Function::New(env, FetchSymbolFromGlobalRegistryWithCppKey);
+  exports["testUndefinedSymbolCanBeCreated"] =
+      Function::New(env, TestUndefinedSymbolsCanBeCreated);
+  exports["testNullSymbolCanBeCreated"] =
+      Function::New(env, TestNullSymbolsCanBeCreated);
+  return exports;
+}
diff --git a/test/symbol.js b/test/symbol.js
@@ -0,0 +1,70 @@
+'use strict';
+
+const buildType = process.config.target_defaults.default_configuration;
+const assert = require('assert');
+
+test(require(`./build/${buildType}/binding.node`));
+test(require(`./build/${buildType}/binding_noexcept.node`));
+ 
+
+async function test(binding)
+{
+
+    const wellKnownSymbolFunctions = ['asyncIterator','hasInstance','isConcatSpreadable', 'iterator','match','matchAll','replace','search','split','species','toPrimitive','toStringTag','unscopables'];
+
+    function assertCanCreateSymbol(symbol)
+    {
+      assert(binding.symbol.createNewSymbolWithCppStr(symbol) !== null);
+      assert(binding.symbol.createNewSymbolWithCStr(symbol) !== null);
+      assert(binding.symbol.createNewSymbolWithNapi(symbol) !== null);
+    }
+
+    function assertSymbolAreUnique(symbol)
+    {
+        const symbolOne = binding.symbol.createNewSymbolWithCppStr(symbol);
+        const symbolTwo = binding.symbol.createNewSymbolWithCppStr(symbol);
+
+        assert(symbolOne !== symbolTwo);
+    }
+
+    function assertSymbolIsWellknown(symbol)
+    {
+      const symbOne = binding.symbol.getWellKnownSymbol(symbol);
+      const symbTwo = binding.symbol.getWellKnownSymbol(symbol);
+      assert(symbOne && symbTwo);
+      assert(symbOne === symbTwo);
+    }
+
+    function assertSymbolIsNotWellknown(symbol)
+    {
+      const symbolTest = binding.symbol.getWellKnownSymbol(symbol);
+      assert(symbolTest === undefined);
+    }
+
+    function assertCanCreateOrFetchGlobalSymbols(symbol, fetchFunction)
+    {
+      const symbOne = fetchFunction(symbol);
+      const symbTwo = fetchFunction(symbol);
+      assert(symbOne && symbTwo);
+      assert(symbOne === symbTwo);
+    }
+    
+    assertCanCreateSymbol("testing");
+    assertSymbolAreUnique("symbol"); 
+    assertSymbolIsNotWellknown("testing");
+
+     for(const wellknownProperty of wellKnownSymbolFunctions)
+     {
+       assertSymbolIsWellknown(wellknownProperty);
+     }
+   
+     assertCanCreateOrFetchGlobalSymbols("data", binding.symbol.getSymbolFromGlobalRegistry);
+     assertCanCreateOrFetchGlobalSymbols("CppKey", binding.symbol.getSymbolFromGlobalRegistryWithCppKey);
+     assertCanCreateOrFetchGlobalSymbols("CKey", binding.symbol.getSymbolFromGlobalRegistryWithCKey);
+
+    assert(binding.symbol.createNewSymbolWithNoArgs() === undefined);
+
+    assert(binding.symbol.testNullSymbolCanBeCreated() === binding.symbol.testNullSymbolCanBeCreated());
+    assert(binding.symbol.testUndefinedSymbolCanBeCreated() === binding.symbol.testUndefinedSymbolCanBeCreated());
+    assert(binding.symbol.testUndefinedSymbolCanBeCreated() !== binding.symbol.testNullSymbolCanBeCreated());
+}
