Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

util: use a global symbol for util.promisify.custom #31672

Closed
wants to merge 3 commits into from
Closed

util: use a global symbol for util.promisify.custom #31672

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5a96702
util: Use a global symbol for `util.promisify.custom`
ExE-Boss Feb 7, 2020
1798266
docs(util): Use a global symbol for `util.promisify.custom`
ExE-Boss Feb 7, 2020
e7d919e
test(util): Use a global symbol for `util.promisify.custom`
ExE-Boss Feb 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions doc/api/util.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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')`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It should be noted that any code that uses Symbol.for('nodejs.util.promisify.custom') syntax rather than the util.promisify.custom accessor will not work properly on older versions of Node.js so if compatibility with older versions is important, use of the accessor is preferred.

Copy link
Contributor Author

@ExE-Boss ExE-Boss Feb 7, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That will be visible in the History drop‑down, same as with util.inspect.custom, which doesn’t mention this either.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer a more explicit comment on it.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I recommend doing that in its own PR, as it will affect the documentation of util.inspect.custom (and possibly other symbols) as well.


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
Expand Down
2 changes: 1 addition & 1 deletion lib/internal/util.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,7 @@ function getSystemErrorName(err) {
return entry ? entry[0] : `Unknown system error ${err}`;
}

const kCustomPromisifiedSymbol = Symbol('util.promisify.custom');
const kCustomPromisifiedSymbol = SymbolFor('nodejs.util.promisify.custom');
jasnell marked this conversation as resolved.
Show resolved Hide resolved
const kCustomPromisifyArgsSymbol = Symbol('customPromisifyArgs');

function promisify(original) {
Expand Down
15 changes: 15 additions & 0 deletions test/parallel/test-util-promisify.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,21 @@ const stat = promisify(fs.stat);
assert.strictEqual(promisify(promisify(fn)), promisifedFn);
}

{
function fn() {}

function promisifiedFn() {}

// util.promisify.custom is a shared symbol which can be accessed
// as `Symbol.for("nodejs.util.promisify.custom")`.
const kCustomPromisifiedSymbol = Symbol.for('nodejs.util.promisify.custom');
fn[kCustomPromisifiedSymbol] = promisifiedFn;

assert.strictEqual(kCustomPromisifiedSymbol, promisify.custom);
assert.strictEqual(promisify(fn), promisifiedFn);
assert.strictEqual(promisify(promisify(fn)), promisifiedFn);
}

{
function fn() {}
fn[promisify.custom] = 42;
Expand Down