util: deprecate obj.inspect for custom inspection

[Trott]

The existence of obj.inspect() for custom inspection can cause people
to unintentionally break console.log() and friends. This is a
documentation-only deprecation that can hopefully land in 8.x.

Refs: #15549

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

util

[vsemozhetbyt]

not sure, but maybe "equivalent but deprecated"?

[Trott]

Yes, you're correct. Even better might be or the equivalent but deprecated which is what I'll switch it to in a minute.

[addaleax]

This is a documentation-only deprecation that can hopefully land in 8.x.

Just to give context, the alternative was only introduced a little more than a year ago in 6.4.0. I am perfectly fine with landing this in 8.x but I’d like to wait a little longer until we consider a runtime-deprecation.

[Trott]

Labeling semver-minor as our docs indicate that is the minimum for a doc-only deprecation.

[evanlucas]

can we check ecosystem usage of this before we land this?

[Trott]

can we check ecosystem usage of this before we land this?

@evanlucas The same question was asked in #15549 and @refack answered (in #15549 (comment)) like this:

@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.

[jasnell]

+1 as a docs-only deprecation

[refack]

can we check ecosystem usage of this before we land this?

querying for /\binspect\b/ results in more than 50KLOCs. In a partial manual review, I only picked up Q - #15549 (comment)

[ljharb]

Can someone confirm; will util.inspect fall back to the string "inspect" if util.inspect.custom is not available? Is there a plan in the future to change this behavior?

[jasnell]

Yes, the string inspect will still work. This is a docs only deprecation for now. Which means no runtime changes at all

[addaleax]

It might be helpful to note that, if compatibility is desired, having the method present under both names is always going to work?

[Trott]

I like the idea but I'm struggling with how to word it in a way that doesn't encourage people to use both if they're only using the Symbol. We don't want to create more messages if/when we move to a runtime deprecation. Suggestions welcome.

[addaleax]

@Trott The thing is, even if we move to a runtime deprecation, the symbol property will be the first one that’s detected, and the string property ignored – so if both are present, the runtime deprecation won’t be emitted… or am I misunderstanding what you’re saying?

[Trott]

@addaleax Good point. I've added some text in a separate commit.

[refack]

Can someone confirm; will util.inspect fall back to the string "inspect" if util.inspect.custom is not available? Is there a plan in the future to change this behavior?

AFAICT the long term "plan" is to runtime deprecate then remove, but that cycle requires at least two major versions, and future consensus.

[BridgeAR]

instead (For backwards compatibility with Node.js prior to version 6.4.0, both may be specified). ?

[refack]

I think since it's a whole sentence (not just a clause) inside the parentheses the period should be inside.

http://www.thepunctuationguide.com/parentheses.html

[Trott]

Perhaps the parentheses are unnecessary anyway?

[BridgeAR]

Landed in c09c04f

I removed the braces while landing.

[MylesBorins]

This does not land cleanly on 8.x. Could you please manually backport.

[MylesBorins]

nvm I figured it out ☺️

[vitaly-t]

I saw the change, read documentation and played with the Node and the code, and still cannot quite get it...

In order to provide custom console output for each of my custom types I used to do this:

MyType.prototype.inspect = function(){
    return 'CUSTOM VALUE';
}

How am I to change this code for the latest Node.js?

[addaleax]

@vitaly-t basically, whenever you want your custom inspect function and care about older Node versions, also do:

MyType.prototype.inspect = function(){
    return 'CUSTOM VALUE';
};
if (util.inspect.custom) {
  MyType.prototype[util.inspect.custom] = MyType.prototype.inspect;
}

If you do not care about Node < 6.4.0, you can (and probably should) just use

MyType.prototype[util.inspect.custom] = function(){
    return 'CUSTOM VALUE';
};

The reason for this is that it’s hard to tell for Node whether inspect was meant to be a custom inspection function for util.inspect, or somebody accidentally called it that way. With a symbol, that problem goes away.

[vitaly-t]

@addaleax Thank you! But if this is the case, then why the first code below works fine, while the one after doesn't?

Works:

const obj = {
    inspect: () => {
        return 'INSPECT';
    }
};
console.log(obj);
//=> INSPECT

Doesn't work:

const obj = {
    util: {
        inspect: {
            custom: () => {
                return 'INSPECT';
            }
        }
    }
};
console.log(obj);
//=> { util: { inspect: { custom: [Function: custom] } } }

Node.js v8.7.0

[ljharb]

@vitaly-t it's require('util').inspect.custom, eg:

const obj = {
  [require('util').inspect.custom]() {
    return 'INSPECT';
  }
};
console.log(obj);

[vitaly-t]

@ljharb Ouch,... tricky! I think documentation needs to get better on this one 😄 Thank you!

Also, I'd like to figure out what that require('util').inspect.custom really returns. I can only see in the console for it saying Symbol(util.inspect.custom). Inspecting the inspection 😄

[addaleax]

I think documentation needs to get better on this one 😄

PRs are definitely very welcome!

Also, I'd like to figure out what that require('util').inspect.custom really returns. I can only see in the console for it saying Symbol(util.inspect.custom)

I am not sure if this is helpful or not, but: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol (i.e. there isn’t really much more information contained in the value of util.inspect.custom than what Symbol(util.inspect.custom) says)

[gibfahn]

Release team were -1 on landing on v6.x, if you disagree let us know.

[ljharb]

@gibfahn on landing the deprecation, the new symbol, or either?

[gibfahn]

@gibfahn on landing the deprecation, the new symbol, or either?

On landing the deprecation, though it wasn't a heavy -1, as with all backports we'd like to hear others' thoughts (we have a week to decide).

Which is the new symbol? I don't see it in this PR.

[ljharb]

ah, you're right, it was added in #8174 (and backported to 4.x in #9688) and this is just the deprecation.