util: use a global symbol for `util.promisify.custom`

Define `util.promisify.custom`
as `Symbol.for("nodejs.util.inspect.custom")`, rather than
as `Symbol("util.inspect.custom")`.

This allows custom `promisify` wrappers to easily/safely be defined
in non‑Node.js environments.

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

PR-URL: https://github.com/nodejs/node/pull/31672
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

1 files changed, 21 insertions, 0 deletions

diff --git a/doc/api/util.md b/doc/api/util.md
index 151e476993..2c0062eff7 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -995,11 +995,32 @@ throw an error.
 ### `util.promisify.custom`
 <!-- YAML
 added: v8.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/31672
+    description: This is now defined as a shared symbol.
 -->
 
 * {symbol} that can be used to declare custom promisified variants of functions,
 see [Custom promisified functions][].
 
+In addition to being accessible through `util.promisify.custom`, this
+symbol is [registered globally][global symbol registry] and can be
+accessed in any environment as `Symbol.for('nodejs.util.promisify.custom')`.
+
+For example, with a function that takes in
+`(foo, onSuccessCallback, onErrorCallback)`:
+
+```js
+const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');
+
+doSomething[kCustomPromisifiedSymbol] = (foo) => {
+  return new Promise((resolve, reject) => {
+    doSomething(foo, resolve, reject);
+  });
+};
+```
+
 ## Class: `util.TextDecoder`
 <!-- YAML
 added: v8.3.0