util: mark deprecated objects with symbol

[avivkeller]

Fixes #22543

This PR marks deprecated objects with a custom symbol, to make it easier for developers to know what functions have been deprecated.

[benjamingr]

Is there a particular reason this is a global symbol in the registry? Cross version compat if we vendor deprecated stuff e.g. from strearms?

[avivkeller]

No, no specific reason. I noticed that other Symbols within the util object were formatted the same way, and I wanted to follow the trend, is there a better way?

[cola119]

Can you please add tests?

[avivkeller]

I've added
util.isDeprecated(object) (Function)
util.deprecate.isDeprecated (Symbol)

I'll add some tests later today

[marco-ippolito]

If we ship this, we then have it applied to every function, class constructor etc... we have deprecated, which seems a big change, but I dont see the return. Can you please describe more the use case?

[avivkeller]

If we ship this, we then have it applies to every function, class constructor etc... we have deprecated, which seems a big change, but I dont see the return. Can you please describe more the use case?

I believe that the comments on issue #22543 give some use cases, but I see it as a way for developers to anticipate deprecations. For example, they can use the punycode module when available, but otherwise use some other method.

[marco-ippolito]

If we ship this, we then have it applies to every function, class constructor etc... we have deprecated, which seems a big change, but I dont see the return. Can you please describe more the use case?

I believe that the comments on issue #22543 give some use cases, but I see it as a way for developers to anticipate deprecations. For example, they can use the punycode module when available, but otherwise use some other method.

punycode is deprecated 😄 but thats beside the point, if we want developers to know we runtime deprecate so they will see the warning.

[avivkeller]

I'm aware that puny_code is deprecated, that's why it was my example. The warnings are nice, but they aren't programmatic, an end user can't really use them in their code

[marco-ippolito]

But how do you know something is deprecated? Manually calling util.isDeprecated for every single api they use if they use are deprecated or am I missing something?

[avivkeller]

But how do you know something is deprecated? Manually calling util.isDeprecated for every single api they use if they use are deprecated or am I missing something?

Yes.
Any function deprecated with util.deprecate will have the new symbol. (This includes developer-deprecated functions)

[marco-ippolito]

I'm trying to immagine the use case:
If you dont know something is deprecated (you can always read the documentation) every time you use a function you add the check:

const { readFile } = require('node:fs');

if(util.isDeprecated(readFile)){
// do what? 😅
}

You will know with a warning anyways

[avivkeller]

True, maybe this PR isn't the best, I can always close it and focus on a different part of Node.

[avivkeller]

I just found a use case, I was just trying to print NodeJS internals, but only non-deprecated ones, as their was no way to do it

[tniessen]

Deprecations are fine-grained in many cases, e.g., a function's behavior might be deprecated under certain circumstances only.

I don't see what problem this is solving properly.

[avivkeller]

It was something that I figured would help in the experimental REPL, but I think your right