Node: Feature request: util: isDeprecated()

[mscdex]

Prior discussion: #22524

It would be useful to have a public API for reliably detecting deprecated methods and properties upfront.

As I mentioned in the referenced issue, end users can currently check func.name === 'deprecated' or for properties, check for a getter and/or setter that has getset.name === 'deprecated', however this isn't necessarily something that is guaranteed to always work. I propose we have some API(s) for doing a more reliable check within core (possibly utilizing internal symbols on the deprecated function wrapper?).

Perhaps the API would be something like util.isDeprecated(objOrFunc[, propertyName]) so you could do:

util.isDeprecated(os.tmpDir);
// or alternatively
util.isDeprecated(os, 'tmpDir');
// or for non-function properties
util.isDeprecated(crypto, 'DEFAULT_ENCODING');

This won't work for all possible deprecation scenarios though (e.g. deprecated function parameters, options, etc.), but at least it'd be something useful for many other cases.

[AyushG3112]

Instead of an API, maybe we can add a isDeprecated flag to the function returned by util.deprecate?

[gireeshpunathil]

how would one consume this capability? if isDeprecated returns true, what is the next action for the program? Is it harder for manually checking the doc for the deprecation prior to coding than doing this runtime hack? In either case, this feature cannot be reliably implemented if it cannot provide an alternative recommended API when the result is positive.

[mscdex]

To me this is not a "runtime hack". I see it more as an alternative to node version checking when supporting multiple major node versions.

/cc @dougwilson as he originally inquired about the right way to do this, so he may have a use case to share

[mscdex]

@AyushG3112 That's not as foolproof (and my current suggested solution is not either), which is why I suggested some mechanism that is more unique to node core only (e.g. an internal symbol placed on the wrapper function). Also simply using a flag on functions still requires the end user to have to manually check for deprecated properties by looking for a 'deprecated' getter/setter on parent objects.

Having a single API that can work for both is much cleaner IMHO.

[jasnell]

Slightly different idea... expose a well-known symbol on the deprecated function that provides the deprecation code... e.g.

console.log(process.assert[util.deprecation])
// Prints: DEP0100

The key challenge with this API, of course, is that it would only be usable for a subset of our deprecations. Things that we deprecate without using the util.deprecate() wrapper would be entirely undetectable using this mechanism.

[Fishrock123]

How would this work for non-property deprecations?

[mscdex]

How would this work for non-property deprecations?

This won't work for all possible deprecation scenarios though (e.g. deprecated function parameters, options, etc.), but at least it'd be something useful for many other cases.

[jasnell]

Note that this does have a bit of logical overlap with the ongoing feature discovery discussion and a similar question could be asked about whether something is experimental.