Node: Deprecate object.inspect for custom inspection

[jakearchibald]

https://nodejs.org/api/util.html#util_custom_inspection_functions_on_objects

The use of obj.inspect as part of inspecting (and therefore console.log) seems to catch people out https://twitter.com/wSokra/status/910070904666943489.

Given that there's a Symbol now, is there a plan to deprecate obj.inspect?

[BridgeAR]

I agree that it would be good to deprecate that. It is difficult to know how many people rely on this right now though.

@ChALkeR @refack would you be so kind and try finding out how often this might be used?

[MylesBorins]

/cc @nodejs/tsc

[TimothyGu]

I'm not TSC but I'm :+1: on this. Compatibility risks are always there, but util.inspect will still give an output for objects after this change, just a less helpful one.

[refack]

@ChALkeR @refack would you be so kind and try finding out how often this might be used?

It's a tricky query to run... preliminary results indicate "no very often".

Compatibility risks are always there, but util.inspect will still give an output for objects after this change, just a less helpful one.

Just a reminder, deprecation is still far from removal (a full cycle needs at least two major versions). And even after a "full deprecation" removal is not automatic. So IMHO if it's a "bad" API that already has a better implementation, deciding to deprecate should be easier.

[refack]

Found an interesting example - Q

> p = Q.Promise((r) => { r('a') })
{ state: 'fulfilled', value: 'a' }
> util.inspect.defaultOptions.customInspect = false
false
> p
{ [String: 'a']
  promiseDispatch: [Function],
  valueOf: [Function],
  inspect: [Function] }
>

It not exactly negative or positive, although IMHO it's more positive, since the inspection should show the full internal state.
/cc @kriskowal

[jakearchibald]

Is that done using .inspect or the symbol? Should be easy to get Q to switch to the symbol.

[refack]

Is that done using .inspect or the symbol? Should be easy to get Q to switch to the symbol.

Q promises have a semantic inspect method, so IMHO this is an example of bad interaction (pro deprecation).

[Fishrock123]

I agree that it should be moved to a Symbol (if it has not been already), but not that it should be removed entirely.

[addaleax]

@Fishrock123 Yeah, there’s util.inspect.custom for exactly that. :) Node 4.x doesn’t have it, unfortunately.

[BridgeAR]

@Fishrock123 the main point is to remove this and not about using the symbol version. The reason is that you can not inspect all objects properly with this and that is a bad API. You always have to think about not inspecting anything that has a "inspect" function on it that is not meant as a custom inspect function.

[kriskowal]

Folks do depend on inspect’s presence and shape of its return value, and while it deliberately interacts with util.inspect as-it-was for debug purposes, it seems relatively unlikely that any code depends on the interaction. We can claw back the current behavior with the symbol.

Aside, it seems to me like custom inspect methods should be receiving a Set of visited objects that they can pass back to util.inspect recursively, to break cyclic references.

[BridgeAR]

@kriskowal the customInspect function already receives the set of visited objects. It is on the second argument the seen property.
And as you can see due to this issue being opened including the mentioned tweet, people did run into issues because of the current behavior. We do not know how many but it seems like quite a few people are not happy with the current implementation and prefer a side effect free variant like the symbol one.

[kriskowal]

@BridgeAR Filed under https://github.com/kriskowal/q/issues/822

We’ll need to find a way to feature-detect the symbol. Q is old enough that it lives is in the realm of “you might not be using CommonJS”, and if you are using CommonJS, it doesn’t assume you’re using Node.js either. From time to time, folks remind me that they’re using Q in a script tag or with an old version of Browserify.

[Trott]

Runtime deprecation proposed in https://github.com/nodejs/node/pull/16393. We're past the deadline for this landing in 9.0.0 without extraordinary action. So if it lands, it won't be seen in a release at least until 10.0.0.

[Trott]

Runtime deprecation landed (https://github.com/nodejs/node/pull/16393) but won't be released until 10.0.0. This should probably stay open until the feature is removed, which I believe can't happen until 11.0.0.

[Yomguithereal]

I am sorry to ask the question here because it's probably not the good place but how do you think people should ensure cross-platform usage of custom inspection now? What I mean is that, for instance, I have libraries of data structures using custom inspect functions so that the log output is useful for the user. But now I have to require the util module to implement this feature and this breaks my code for the browser if I don't have some kind of building phase splitting code for node consumption and for the browser.

[Trott]

@Yomguithereal If you haven't already, you might try asking that question in these places:

• Node.js Help
• StackOverflow
• #node.js channel on chat.freenode.net. See http://nodeirc.info/ for more information.
• Node.js Slack Community: Visit nodeslackers.com to register.

[Trott]

Opened a pull request with a milestone for 11.0.0 to move this to End-of-Life. If that lands and is released in 11.0.0 (which is due out in October 2018), then the API can be removed at any time after that, although we'd probably target 12.0.0 (April 2019) at the earliest for full removal.

[Yomguithereal]

Thanks @Trott. Will definitely check this.

[chocolateboy]

@Yomguithereal I had the same problem and solved it with inspect-custom-symbol, which uses the browser field in its package.json to provide a (different) symbol in the browser without requiring util (and thereby forcing it to be pulled in by Browserify etc.).

Still, I wish this had been implemented as e.g. Symbol.for('util.inspect.custom') rather than a private symbol that requires this kind of workaround.

[Yomguithereal]

Thanks @chocolateboy. I guess for now this is the only decent workaround :(

[chocolateboy]

@Yomguithereal

I guess for now this is the only decent workaround :(

I've proposed a fix for this here.

[BridgeAR]

This got resolved with #16393 and #20722