node-api: napi_ref on all types is experimental

PR-URL: nodejs#47975
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>

doc/api/n-api.md

@@ -1652,23 +1652,23 @@ managed by scopes and all scopes must be closed before the end of a native
 method.
 
 Node-API provides methods for creating persistent references to values.
+Currently Node-API only allows references to be created for a
+limited set of value types, including object, external, function, and symbol.
+
 Each reference has an associated count with a value of 0 or higher,
 which determines whether the reference will keep the corresponding value alive.
 References with a count of 0 do not prevent values from being collected.
 Values of object (object, function, external) and symbol types are becoming
 'weak' references and can still be accessed while they are not collected.
-Values of other types are released when the count becomes 0
-and cannot be accessed from the reference any more.
 Any count greater than 0 will prevent the values from being collected.
 
 Symbol values have different flavors. The true weak reference behavior is
-only supported by local symbols created with the `Symbol()` constructor call.
-Globally registered symbols created with the `Symbol.for()` call remain
-always strong references because the garbage collector does not collect them.
-The same is true for well-known symbols such as `Symbol.iterator`. They are
-also never collected by the garbage collector. JavaScript's `WeakRef` and
-`WeakMap` types return an error when registered symbols are used,
-but they succeed for local and well-known symbols.
+only supported by local symbols created with the `napi_create_symbol` function
+or the JavaScript `Symbol()` constructor calls. Globally registered symbols
+created with the `node_api_symbol_for` function or JavaScript `Symbol.for()`
+function calls remain always strong references because the garbage collector
+does not collect them. The same is true for well-known symbols such as
+`Symbol.iterator`. They are also never collected by the garbage collector.
 
 References can be created with an initial reference count. The count can
 then be modified through [`napi_reference_ref`][] and
@@ -1679,11 +1679,6 @@ will return `NULL` for the returned `napi_value`. An attempt to call
 [`napi_reference_ref`][] for a reference whose object has been collected
 results in an error.
 
-Node-API versions 8 and earlier only allow references to be created for a
-limited set of value types, including object, external, function, and symbol.
-However, in newer Node-API versions, references can be created for any
-value type.
-
 References must be deleted once they are no longer required by the addon. When
 a reference is deleted, it will no longer prevent the corresponding object from
 being collected. Failure to delete a persistent reference results in
@@ -1701,6 +1696,15 @@ run and the native memory pointed by the earlier persistent reference
 will not be freed. This can be avoided by calling
 `napi_delete_reference` in addition to `napi_reference_unref` when possible.
 
+**Change History:**
+
+* Experimental (`NAPI_EXPERIMENTAL` is defined):
+
+  References can be created for all value types. The new supported value
+  types do not support weak reference semantic and the values of these types
+  are released when the reference count becomes 0 and cannot be accessed from
+  the reference anymore.
+
 #### `napi_create_reference`
 
 <!-- YAML
@@ -1725,10 +1729,6 @@ Returns `napi_ok` if the API succeeded.
 This API creates a new reference with the specified reference count
 to the value passed in.
 
-In Node-API version 8 and earlier, a reference could only be created for
-object, function, external, and symbol value types. However, in newer Node-API
-versions, a reference can be created for any value type.
-
 #### `napi_delete_reference`
 
 <!-- YAML

src/js_native_api_v8.cc

@@ -2436,7 +2436,7 @@ napi_status NAPI_CDECL napi_create_reference(napi_env env,
   CHECK_ARG(env, result);
 
   v8::Local<v8::Value> v8_value = v8impl::V8LocalValueFromJsValue(value);
-  if (env->module_api_version <= 8) {
+  if (env->module_api_version != NAPI_VERSION_EXPERIMENTAL) {
     if (!(v8_value->IsObject() || v8_value->IsFunction() ||
           v8_value->IsSymbol())) {
       return napi_set_last_error(env, napi_invalid_arg);