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.

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

util: use a shared symbol for util.inspect.custom #20857

Closed
wants to merge 12 commits into from
Closed

util: use a shared symbol for util.inspect.custom #20857

wants to merge 12 commits into from

Conversation

chocolateboy
Copy link
Contributor

@chocolateboy chocolateboy commented May 20, 2018

Define util.inspect.custom as:

Symbol.for("util.inspect.custom")

rather than:

Symbol("util.inspect.custom")

This allows util.inspect hooks to easily/safely be defined in non-Node.js environments.

The old symbol and the new symbol stringify to the same value, so much of the test code remains the same.

Fixes: #20821

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines

@nodejs-github-bot nodejs-github-bot added the util Issues and PRs related to the built-in util module. label May 20, 2018
doc/api/util.md Outdated
can be used to define custom inspection functions in any environment.

```js
const INSPECT = Symbol.for('util.inspect.custom');
Copy link
Member

Choose a reason for hiding this comment

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

Please use lower cased variable names. We do not use capital letters to indicate constants.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

doc/api/util.md Outdated
* {symbol} that can be used to declare custom inspect functions.

This is a shared symbol, `Symbol.for('util.inspect.custom')`, which
can be used to define custom inspection functions in any environment.
Copy link
Member

Choose a reason for hiding this comment

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

It might be good to also add a reference to mdn about Symbol.for() but that is not a must.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

@BridgeAR
Copy link
Member

@chocolateboy thanks a lot for working on this! 👍

@devsnek
Copy link
Member

devsnek commented May 20, 2018

i think we should namespace any global symbols we create with node, otherwise looks good

@chocolateboy
Copy link
Contributor Author

i think we should namespace any global symbols we create with node

I agree, but I think that should be addressed in a separate issue as there are other symbols which would also need to be updated e.g. util.promisify.custom.

doc/api/util.md Outdated
* {symbol} that can be used to declare custom inspect functions.

This is a shared symbol, [`Symbol.for('util.inspect.custom')`], which is registered
in the [global symbol registry](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for).
Copy link
Member

Choose a reason for hiding this comment

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

Would you be so kind and move the actual link to the bottom of the file? :-) That allows the text to still stay readable.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

@BridgeAR
Copy link
Member

@chocolateboy you mean because the name would change for the symbol?

@jasnell jasnell added the semver-major PRs that contain breaking changes and should be released in the next major version. label May 20, 2018
@jasnell
Copy link
Member

jasnell commented May 20, 2018

Marking semver-major because this impacts the global symbol namespace.

@BridgeAR
Copy link
Member

If we handle this as semver-major, we should be fine to change the symbol name to node:util.inspect.custom right away.

I think it would really be good if this could be backported though... so I wonder if we should really handle this as semver-major.

@mscdex
Copy link
Contributor

mscdex commented May 20, 2018

That last checkbox shouldn't be ticked, the commit messages don't follow the commit message guidelines.

Copy link
Member

@addaleax addaleax left a comment

Choose a reason for hiding this comment

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

Changes to lib/ and test/ look good :)

doc/api/util.md Outdated

class Password {
constructor(value) {
this.value = value || document.getElementById('password').value;
Copy link
Member

Choose a reason for hiding this comment

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

Not really a fan of non-Node.js examples in the Node.js documentation ;)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

doc/api/util.md Outdated

const password = new Password('r0sebud');
console.log(password);
// Prints xxxxxxxx
Copy link
Member

Choose a reason for hiding this comment

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

It might be obvious from context, but when only considering the example, it’s not all that obvious whether this prints xxxxxxxx because of .toString() or because of the [inspect]() method.

Maybe we could change the latter one to something like return `Password <${this.toString()}>`; ?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

@BridgeAR
Copy link
Member

@mscdex the first commit message does follow the commit guidlines. The others are not but it would be squashed anyway.

@chocolateboy
Copy link
Contributor Author

chocolateboy commented May 20, 2018

@mscdex

the commit messages don't follow the commit message guidelines.

Is this an issue with the follow-up commits or the first commit?

I can't see anything here about the format of commit messages for review/feedback fixes. I assumed they would be squashed:

Note that multiple commits often get squashed when they are landed

@jasnell
Copy link
Member

jasnell commented May 20, 2018

so I wonder if we should really handle this as semver-major

Yes, it should be semver-major.

Any uses of the new symbol would fail on LTS release lines. And if backported, there'd be a breaking difference between releases in the same LTS line

doc/api/util.md Outdated

This is a shared symbol, `Symbol.for('util.inspect.custom')`, which is
registered in the [global symbol registry][]. It can be used to define
custom inspection functions in any environment.
Copy link
Member

Choose a reason for hiding this comment

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

How about:

In addition to being accessible through `util.inspect`, this symbol is
[registered globally][global symbol registry], such that it may be obtained
through `Symbol.for('util.inspect.custom')`.

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've tweaked the wording here.

doc/api/util.md Outdated
@@ -2095,6 +2122,7 @@ Deprecated predecessor of `console.log`.
[`Error`]: errors.html#errors_class_error
[`Float32Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array
[`Float64Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
[global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for
Copy link
Member

Choose a reason for hiding this comment

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

This should get sorted after all other entries with first letter uppercase, i.e., ASCII-betically.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

doc/api/util.md Outdated
@@ -564,8 +564,8 @@ terminals.

<!-- type=misc -->

Objects may also define their own `[util.inspect.custom](depth, opts)` function
that `util.inspect()` will invoke and use the result of when inspecting the
Objects may also define their own `[util.inspect.custom](depth, opts)` function,
Copy link
Member

Choose a reason for hiding this comment

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

It would help if there is a link to util.inspect.custom:

Objects may also define their own <code>[[util.inspect.custom][]](depth,
opts)</code> function, which ...

...

[util.inspect.custom]: #util_util_inspect_custom

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Is this the right syntax?

Objects may also define their own <code>[[util.inspect.custom][]](depth,
opts)</code> function, which 

I can't see any other examples like this.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Done.

@addaleax
Copy link
Member

@jasnell Can you give an example of code that would that would be broken by backporting this to older release lines? I can’t seem to think of anything.

doc/api/util.md Outdated
@@ -620,8 +620,35 @@ util.inspect(obj);
added: v6.6.0
-->
Copy link
Member

Choose a reason for hiding this comment

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

Oh, almost forgot: Can you add a changes: block here that describes the change in a succinct fashion? (compare e.g. the metadata for crypto.createCipher in crypto.md)

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Like this?

Copy link
Member

Choose a reason for hiding this comment

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

Yup, looks good!

@jasnell
Copy link
Member

jasnell commented May 21, 2018

@jasnell Can you give an example of code that would that would be broken by backporting this to older release lines? I can’t seem to think of anything.

I should have said potentially breaking. Marking as major is defensive given that this consumes a symbol from the global namespace. Just need a demonstration that a backport wouldn't break. A good CITGM run should be enough if any of the modules there use the current exported symbol.

Keep in mind, however, that any code written to use the Symbol.for rather than the exported symbol won't work in current release lines. So a note should be added to that effect.


// util.inspect.custom is a shared symbol which can be accessed as
// Symbol.for("util.inspect.custom").
const inspect = Symbol.for('util.inspect.custom');
Copy link
Member

Choose a reason for hiding this comment

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

Maybe

assert.strictEqual(util.inspect.custom, inspect);

also?

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 could do that, but it feels rather like assert(true === true). If it fails, the other tests will fail. If it passes, the other tests are redundant.

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 this test over the other ones then.

Copy link
Member

Choose a reason for hiding this comment

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

@chocolateboy it is not like assert(true === true) because it verifies the reference equality and that is the most important part here. So yes, the other tests are redundant in that case but that should already highlight that this test is actually preferable over the others.

Copy link
Contributor Author

@chocolateboy chocolateboy May 21, 2018

Choose a reason for hiding this comment

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

@BridgeAR, @TimothyGu

it is not like assert(true === true) because it verifies the reference equality

I'm not clear how that differs from or improves on assert(true === true).

that is the most important part here

I disagree. I think this change violates a tenet of testing: Test behavior, not implementation.

It's possible for:

util.inspect.custom === Symbol.for("util.inspect.custom")

- to be true and for these tests to fail because inspect accidentally or maliciously ends up checking a different symbol (e.g. util.inspect.hook). At the moment, this mismatch would also be caught by the util.inspect.custom tests preceding these tests, but that's just an unintended consequence of the way the tests are (or aren't) organized.

The equality of the references is not the goal: it's a means to an end (using the hook outside of Node.js). If JavaScript supported operator overloading or custom hash codes, they could even be different references. It's the "Does this work outside of Node.js?" that matters, and that's what these tests test.

@TimothyGu
Copy link
Member

I also think we should namespace the symbol to node:.

Copy link
Member

@devsnek devsnek left a comment

Choose a reason for hiding this comment

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

the symbol needs to be namespaced to node somehow

@addaleax
Copy link
Member

@nodejs/tsc Can you take a look at this? I think namespacing with node is not a good idea. (i.e. I’m -1 on namespacing to node unless we have a good reason.)

It would be a different story if this was actually about a Node.js-specific concept, but as I understand it the whole point here is to enable libraries to have isomorphic support for this feature in browsers. It’s not like the idea of inspecting JS objects is tied to Node in any way.

(Also /cc @mafintosh whose https://github.com/mafintosh/inspect-custom-symbol package already uses Symbol.for('util.inspect.custom').)

@addaleax
Copy link
Member

@devsnek
Copy link
Member

devsnek commented May 21, 2018

@addaleax

It would be a different story if this was actually about a Node.js-specific concept

util.inspect is super duper node centric though. what browser mechanism matches it such that we shouldn't namespace this symbol?

@addaleax
Copy link
Member

It would be a different story if this was actually about a Node.js-specific concept

util.inspect is super duper node centric though.

I mean, yes, our implementation is, but the API conceptually isn’t; and this is modifying a part of the API, not the implementation.

what browser mechanism matches it such that we shouldn't namespace this symbol?

None (and I wouldn’t expect built-in support in browsers either) – what I was trying to say is that this is a missing puzzle piece for people who want to provide a matching library for browsers.

@mcollina
Copy link
Member

I'm +1 on this being semver-minor because:

> Symbol('util.custom.inspect').toString() === Symbol.for('util.custom.inspect').toString()
true

IMHO we should really discuss a policy for symbols. I might be ok if we want to namespace all of them, and maybe document them all in a single place. Namespacing only one does not resonate with me.

I think we should release it as a minor in 10, and see if there are actual breakages and bake it for LTS for a bit.

@devsnek
Copy link
Member

devsnek commented May 21, 2018

what I was trying to say is that this is a missing puzzle piece for people who want to provide a matching library for browsers.

perhaps thats where the miscommunication lies, i wouldn't encourage the community to standardise object inspection around this symbol, unless we name it something a lot more generic (Symbol.for('custom inspect') or something) and even then i wouldn't seek this out as a connection between the ecosystems.

@addaleax
Copy link
Member

@devsnek I am a bit torn between what you’re suggesting and @mcollina’s comment – being more generic seems fine to me, but I could see how that change might more realistically break somebody’s code than the current version of this patch.

targos pushed a commit to targos/node that referenced this pull request Sep 23, 2018
Define `util.inspect.custom` as
`Symbol.for("nodejs.util.inspect.custom")` rather than
`Symbol("util.inspect.custom")`. This allows `inspect` hooks to
easily/safely be defined in non-Node.js environments.

Fixes: nodejs#20821
Refs: nodejs#22684

PR-URL: nodejs#20857
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: John-David Dalton <john.david.dalton@gmail.com>
targos pushed a commit that referenced this pull request Sep 24, 2018
Define `util.inspect.custom` as
`Symbol.for("nodejs.util.inspect.custom")` rather than
`Symbol("util.inspect.custom")`. This allows `inspect` hooks to
easily/safely be defined in non-Node.js environments.

Fixes: #20821
Refs: #22684

Backport-PR-URL: #23039
PR-URL: #20857
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: John-David Dalton <john.david.dalton@gmail.com>
@targos targos added backported-to-v10.x and removed author ready PRs that have at least one approval, no pending requests for changes, and a CI started. backport-requested-v10.x labels Sep 24, 2018
@oyyd oyyd mentioned this pull request Sep 26, 2018
2 tasks
targos added a commit that referenced this pull request Oct 7, 2018
Notable changes:

* assert
  * The diff output is now a tiny bit improved by sorting object
    properties when inspecting the values that are compared with each
    other. #22788
* cli
  * The options parser now normalizes `_` to `-` in all multi-word
    command-line flags, e.g. `--no_warnings` has the same effect as
    `--no-warnings`. #23020
  * Added bash completion for the `node` binary. To generate a bash
    completion script, run `node --completion-bash`. The output can be
    saved to a file which can be sourced to enable completion.
    #20713
* crypto
  * Added support for PEM-level encryption.
    #23151
  * Added an API asymmetric key pair generation. The new methods
    `crypto.generateKeyPair` and `crypto.generateKeyPairSync` can be
    used to generate public and private key pairs. The API supports
    RSA, DSA and EC and a variety of key encodings (both PEM and DER).
    #22660
* fs
  * Added a `recursive` option to `fs.mkdir` and `fs.mkdirSync`. If
    this option is set to true, non-existing parent folders will be
    automatically created. #21875
* http2
  * Added a `'ping'` event to `Http2Session` that is emitted whenever a
    non-ack `PING` is received.
    #23009
  * Added support for the `ORIGIN` frame.
    #22956
* module
  * Added `module.createRequireFromPath(filename)`. This new method can
    be used to create a custom require function that will resolve
    modules relative to the filename path.
    #19360
* process
  * Added a `'multipleResolves'` process event that is emitted whenever
    a `Promise` is attempted to be resolved multiple times, e.g. if the
    `resolve` and `reject` functions are both called in a `Promise`
    executor. #22218
* **url**
  * Added `url.fileURLToPath(url)` and `url.pathToFileURL(path)`. These
    methods can be used to correctly convert between file: URLs and
    absolute paths. #22506
* **util**
  * Added the `sorted` option to `util.inspect()`. If set to `true`,
    all properties of an object and Set and Map entries will be sorted
    in the returned string. If set to a function, it is used as a
    compare function. #22788
  * The `util.instpect.custom` symbol is now defined in the global
    symbol registry as `Symbol.for('nodejs.util.inspect.custom')`.
    #20857
* **Windows**
  * The Windows msi installer now provides an option to automatically
    install the tools required to build native modules.
    #22645
* **Added new collaborators**:
  * digitalinfinity - Hitesh Kanwathirtha

PR-URL: #23313
targos added a commit that referenced this pull request Oct 10, 2018
Notable changes:

* assert
  * The diff output is now a tiny bit improved by sorting object
    properties when inspecting the values that are compared with each
    other. #22788
* cli
  * The options parser now normalizes `_` to `-` in all multi-word
    command-line flags, e.g. `--no_warnings` has the same effect as
    `--no-warnings`. #23020
  * Added bash completion for the `node` binary. To generate a bash
    completion script, run `node --completion-bash`. The output can be
    saved to a file which can be sourced to enable completion.
    #20713
* crypto
  * Added support for PEM-level encryption.
    #23151
  * Added an API asymmetric key pair generation. The new methods
    `crypto.generateKeyPair` and `crypto.generateKeyPairSync` can be
    used to generate public and private key pairs. The API supports
    RSA, DSA and EC and a variety of key encodings (both PEM and DER).
    #22660
* fs
  * Added a `recursive` option to `fs.mkdir` and `fs.mkdirSync`. If
    this option is set to true, non-existing parent folders will be
    automatically created. #21875
* http2
  * Added a `'ping'` event to `Http2Session` that is emitted whenever a
    non-ack `PING` is received.
    #23009
  * Added support for the `ORIGIN` frame.
    #22956
  * Updated nghttp2 to 1.34.0. This adds RFC 8441 extended connect
    protocol support to allow use of WebSockets over HTTP/2.
    #23284
* module
  * Added `module.createRequireFromPath(filename)`. This new method can
    be used to create a custom require function that will resolve
    modules relative to the filename path.
    #19360
* process
  * Added a `'multipleResolves'` process event that is emitted whenever
    a `Promise` is attempted to be resolved multiple times, e.g. if the
    `resolve` and `reject` functions are both called in a `Promise`
    executor. #22218
* url
  * Added `url.fileURLToPath(url)` and `url.pathToFileURL(path)`. These
    methods can be used to correctly convert between file: URLs and
    absolute paths. #22506
* util
  * Added the `sorted` option to `util.inspect()`. If set to `true`,
    all properties of an object and Set and Map entries will be sorted
    in the returned string. If set to a function, it is used as a
    compare function. #22788
  * The `util.instpect.custom` symbol is now defined in the global
    symbol registry as `Symbol.for('nodejs.util.inspect.custom')`.
    #20857
  * Added support for `BigInt` numbers in `util.format()`.
    #22097
* V8 API
  * A number of V8 C++ APIs have been marked as deprecated since they
    have been removed in the upstream repository. Replacement APIs
    are added where necessary. #23159
* Windows
  * The Windows msi installer now provides an option to automatically
    install the tools required to build native modules.
    #22645
* Workers
  * Debugging support for Workers using the DevTools protocol has been
    implemented. #21364
  * The public `inspector` module is now enabled in Workers.
    #22769
* Added new collaborators:
  * digitalinfinity - Hitesh Kanwathirtha

PR-URL: #23313
targos added a commit that referenced this pull request Oct 10, 2018
Notable changes:

* assert
  * The diff output is now a tiny bit improved by sorting object
    properties when inspecting the values that are compared with each
    other. #22788
* cli
  * The options parser now normalizes `_` to `-` in all multi-word
    command-line flags, e.g. `--no_warnings` has the same effect as
    `--no-warnings`. #23020
  * Added bash completion for the `node` binary. To generate a bash
    completion script, run `node --completion-bash`. The output can be
    saved to a file which can be sourced to enable completion.
    #20713
* crypto
  * Added support for PEM-level encryption.
    #23151
  * Added an API asymmetric key pair generation. The new methods
    `crypto.generateKeyPair` and `crypto.generateKeyPairSync` can be
    used to generate public and private key pairs. The API supports
    RSA, DSA and EC and a variety of key encodings (both PEM and DER).
    #22660
* fs
  * Added a `recursive` option to `fs.mkdir` and `fs.mkdirSync`. If
    this option is set to true, non-existing parent folders will be
    automatically created. #21875
* http2
  * Added a `'ping'` event to `Http2Session` that is emitted whenever a
    non-ack `PING` is received.
    #23009
  * Added support for the `ORIGIN` frame.
    #22956
  * Updated nghttp2 to 1.34.0. This adds RFC 8441 extended connect
    protocol support to allow use of WebSockets over HTTP/2.
    #23284
* module
  * Added `module.createRequireFromPath(filename)`. This new method can
    be used to create a custom require function that will resolve
    modules relative to the filename path.
    #19360
* process
  * Added a `'multipleResolves'` process event that is emitted whenever
    a `Promise` is attempted to be resolved multiple times, e.g. if the
    `resolve` and `reject` functions are both called in a `Promise`
    executor. #22218
* url
  * Added `url.fileURLToPath(url)` and `url.pathToFileURL(path)`. These
    methods can be used to correctly convert between file: URLs and
    absolute paths. #22506
* util
  * Added the `sorted` option to `util.inspect()`. If set to `true`,
    all properties of an object and Set and Map entries will be sorted
    in the returned string. If set to a function, it is used as a
    compare function. #22788
  * The `util.instpect.custom` symbol is now defined in the global
    symbol registry as `Symbol.for('nodejs.util.inspect.custom')`.
    #20857
  * Added support for `BigInt` numbers in `util.format()`.
    #22097
* V8 API
  * A number of V8 C++ APIs have been marked as deprecated since they
    have been removed in the upstream repository. Replacement APIs
    are added where necessary. #23159
* Windows
  * The Windows msi installer now provides an option to automatically
    install the tools required to build native modules.
    #22645
* Workers
  * Debugging support for Workers using the DevTools protocol has been
    implemented. #21364
  * The public `inspector` module is now enabled in Workers.
    #22769
* Added new collaborators:
  * digitalinfinity - Hitesh Kanwathirtha

PR-URL: #23313
targos added a commit that referenced this pull request Oct 10, 2018
Notable changes:

* assert
  * The diff output is now a tiny bit improved by sorting object
    properties when inspecting the values that are compared with each
    other. #22788
* cli
  * The options parser now normalizes `_` to `-` in all multi-word
    command-line flags, e.g. `--no_warnings` has the same effect as
    `--no-warnings`. #23020
  * Added bash completion for the `node` binary. To generate a bash
    completion script, run `node --completion-bash`. The output can be
    saved to a file which can be sourced to enable completion.
    #20713
* crypto
  * Added support for PEM-level encryption.
    #23151
  * Added an API asymmetric key pair generation. The new methods
    `crypto.generateKeyPair` and `crypto.generateKeyPairSync` can be
    used to generate public and private key pairs. The API supports
    RSA, DSA and EC and a variety of key encodings (both PEM and DER).
    #22660
* fs
  * Added a `recursive` option to `fs.mkdir` and `fs.mkdirSync`. If
    this option is set to true, non-existing parent folders will be
    automatically created. #21875
* http2
  * Added a `'ping'` event to `Http2Session` that is emitted whenever a
    non-ack `PING` is received.
    #23009
  * Added support for the `ORIGIN` frame.
    #22956
  * Updated nghttp2 to 1.34.0. This adds RFC 8441 extended connect
    protocol support to allow use of WebSockets over HTTP/2.
    #23284
* module
  * Added `module.createRequireFromPath(filename)`. This new method can
    be used to create a custom require function that will resolve
    modules relative to the filename path.
    #19360
* process
  * Added a `'multipleResolves'` process event that is emitted whenever
    a `Promise` is attempted to be resolved multiple times, e.g. if the
    `resolve` and `reject` functions are both called in a `Promise`
    executor. #22218
* url
  * Added `url.fileURLToPath(url)` and `url.pathToFileURL(path)`. These
    methods can be used to correctly convert between file: URLs and
    absolute paths. #22506
* util
  * Added the `sorted` option to `util.inspect()`. If set to `true`,
    all properties of an object and Set and Map entries will be sorted
    in the returned string. If set to a function, it is used as a
    compare function. #22788
  * The `util.instpect.custom` symbol is now defined in the global
    symbol registry as `Symbol.for('nodejs.util.inspect.custom')`.
    #20857
  * Added support for `BigInt` numbers in `util.format()`.
    #22097
* V8 API
  * A number of V8 C++ APIs have been marked as deprecated since they
    have been removed in the upstream repository. Replacement APIs
    are added where necessary. #23159
* Windows
  * The Windows msi installer now provides an option to automatically
    install the tools required to build native modules.
    #22645
* Workers
  * Debugging support for Workers using the DevTools protocol has been
    implemented. #21364
  * The public `inspector` module is now enabled in Workers.
    #22769
* Added new collaborators:
  * digitalinfinity - Hitesh Kanwathirtha

PR-URL: #23313
jasnell pushed a commit that referenced this pull request Oct 17, 2018
Notable changes:

* assert
  * The diff output is now a tiny bit improved by sorting object
    properties when inspecting the values that are compared with each
    other. #22788
* cli
  * The options parser now normalizes `_` to `-` in all multi-word
    command-line flags, e.g. `--no_warnings` has the same effect as
    `--no-warnings`. #23020
  * Added bash completion for the `node` binary. To generate a bash
    completion script, run `node --completion-bash`. The output can be
    saved to a file which can be sourced to enable completion.
    #20713
* crypto
  * Added support for PEM-level encryption.
    #23151
  * Added an API asymmetric key pair generation. The new methods
    `crypto.generateKeyPair` and `crypto.generateKeyPairSync` can be
    used to generate public and private key pairs. The API supports
    RSA, DSA and EC and a variety of key encodings (both PEM and DER).
    #22660
* fs
  * Added a `recursive` option to `fs.mkdir` and `fs.mkdirSync`. If
    this option is set to true, non-existing parent folders will be
    automatically created. #21875
* http2
  * Added a `'ping'` event to `Http2Session` that is emitted whenever a
    non-ack `PING` is received.
    #23009
  * Added support for the `ORIGIN` frame.
    #22956
  * Updated nghttp2 to 1.34.0. This adds RFC 8441 extended connect
    protocol support to allow use of WebSockets over HTTP/2.
    #23284
* module
  * Added `module.createRequireFromPath(filename)`. This new method can
    be used to create a custom require function that will resolve
    modules relative to the filename path.
    #19360
* process
  * Added a `'multipleResolves'` process event that is emitted whenever
    a `Promise` is attempted to be resolved multiple times, e.g. if the
    `resolve` and `reject` functions are both called in a `Promise`
    executor. #22218
* url
  * Added `url.fileURLToPath(url)` and `url.pathToFileURL(path)`. These
    methods can be used to correctly convert between file: URLs and
    absolute paths. #22506
* util
  * Added the `sorted` option to `util.inspect()`. If set to `true`,
    all properties of an object and Set and Map entries will be sorted
    in the returned string. If set to a function, it is used as a
    compare function. #22788
  * The `util.instpect.custom` symbol is now defined in the global
    symbol registry as `Symbol.for('nodejs.util.inspect.custom')`.
    #20857
  * Added support for `BigInt` numbers in `util.format()`.
    #22097
* V8 API
  * A number of V8 C++ APIs have been marked as deprecated since they
    have been removed in the upstream repository. Replacement APIs
    are added where necessary. #23159
* Windows
  * The Windows msi installer now provides an option to automatically
    install the tools required to build native modules.
    #22645
* Workers
  * Debugging support for Workers using the DevTools protocol has been
    implemented. #21364
  * The public `inspector` module is now enabled in Workers.
    #22769
* Added new collaborators:
  * digitalinfinity - Hitesh Kanwathirtha

PR-URL: #23313
itu2n1i8w added a commit to itu2n1i8w/buffer that referenced this pull request Aug 5, 2024
Ports the `buffer-inspect` test from Node core.
Adds a `Buffer.prototype[util.inspect.custom]` method, which is an alias
to `Buffer.prototype.inspect`. Node already doesn't have an `.inspect`
method on Buffers anymore, but since this module has to work in browsers
that do not have Symbols, it seems better to keep it around.

In Node, this will use the builtin `util.inspect.custom` symbol. In the
browser, it will use `Symbol.for('util.inspect.custom')`. The browser
version of `util` will also use the `inspect-custom-symbol` module in
the near future.

If nodejs/node#20857 gets merged,
`Symbol.for('util.inspect.custom')` will be used everywhere and the
dependency on `inspect-custom-symbol` could probably be dropped.

The motivation for this is API parity and the fact that Node is
removing support for the old `.inspect` method:
nodejs/node#20722
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
semver-minor PRs that contain new features and should be released in the next minor version. util Issues and PRs related to the built-in util module.
Projects
None yet
Development

Successfully merging this pull request may close these issues.