node-api: add node_api_symbol_for()

Fixes: https://github.com/nodejs/node/issues/41294

Signed-off-by: Darshan Sen <raisinten@gmail.com>

PR-URL: https://github.com/nodejs/node/pull/41329
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 32 insertions, 0 deletions

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 7955d0442b5..e7b061cf079 100644
--- a/doc/api/n-api.md
+++ b/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