doc: deprecate utilsNativeError in favor of ErrorisError

[miguelmarcondesf]

Refs #57962

We now have Error.isError available and it can be an alternative for util.types.utilisNativeError

[miguelmarcondesf]

Also to keep in mind:

          > Independently, a doc-only deprecation PR for `util.types.isNativeError()` can be opened.

I'm seeing a >50% performance regression for Error.isError over util.types.isNativeError in the current RC.

custom/type-check-nativeerror.js n=1000000 handler="error-iserror" type="native-error": 55,167,312.528783545
custom/type-check-nativeerror.js n=1000000 handler="isnativeerror" type="native-error": 127,300,251.90173846
custom/type-check-nativeerror.js n=1000000 handler="error-iserror" type="native-error-crossrealm": 50,549,863.72514987
custom/type-check-nativeerror.js n=1000000 handler="isnativeerror" type="native-error-crossrealm": 123,061,852.73311144
custom/type-check-nativeerror.js n=1000000 handler="error-iserror" type="non-native-error": 53,863,525.66184942
custom/type-check-nativeerror.js n=1000000 handler="isnativeerror" type="non-native-error": 117,042,527.28524657

I don't think that deprecation should really be considered unless this gets addressed upstream.

As soon as Error.isError() becomes a thing, we can adjust the implementation of internalUtil.isError() by replacing isNativeError() with ErrorIsError().

As a side note, ErrorIsError will not be exposed as a primordial while it remains a flagged feature in V8.

Originally posted by @Renegade334 in #57962 (comment)

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @LiviaMedeiros.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[Renegade334]

I still find it a premature decision to deprecate this method in favour of one which offers the same functionality, but at present takes 2.5x as long to execute – this does not represent equivalence imho.

[jasnell]

LGTM with the link updated to point to MDN instead of the proposal

[panva]

I still find it a premature decision to deprecate this method in favour of one which offers the same functionality, but at present takes 2.5x as long to execute – this does not represent equivalence imho.

I tend to agree with this. Also there are unresolved issues¹ with Error.isError

Footnotes

1. https://github.com/nodejs/node/issues/56497 ↩

[LiviaMedeiros]

I still find it a premature decision to deprecate this method in favour of one which offers the same functionality, but at present takes 2.5x as long to execute – this does not represent equivalence imho.

Just for the record, the speed difference seems to depend on the value. I'm getting the following numbers from 1e8 runs:

value	isNativeError	isError
new Error()	1199.98ms	2618.24ms
new TypeError()	1902.15ms	2547.55ms
new DOMException()	1829.65ms	2942.06ms
new (class extends Error {})()	1900.60ms	2552.22ms
Object.create(Error.prototype)	1829.65ms	2941.48ms
{}	1829.62ms	2942.25ms
[]	1829.03ms	2942.11ms
42	1685.01ms	2439.98ms
'error'	1829.61ms	3274.12ms
null	1895.54ms	3316.59ms
undefined	1968.88ms	3187.24ms

The difference for new Error() is indeed high, there probably should be a fast path implemented on v8 side.

Nevertheless, I don't see it as blocker for the doc-only deprecation. It might be a blocker for next steps, assuming that the situation won't change. In the worst case scenario (if it would be impossible to optimize in v8), we can keep isNativeError() as legacy solely for performance reasons.
Also for performance reasons, we can keep isNativeError() for internal use in Node.js core as long as it's faster than ErrorIsError().
In the scope of this PR, it might be worth adding a note in the docs that Error.isError() is currently slower.

Also there are unresolved issues1 with Error.isError

This is not really an issue with Error.isError itself, it's more of an issue with DOMException implementation in Node.js. util.types.isNativeError(new DOMException(1)) also returns false, and fix to this issue is likely to be applicable to both functions.

[geeksilva97]

I still find it a premature decision to deprecate this method in favour of one which offers the same functionality, but at present takes 2.5x as long to execute – this does not represent equivalence imho.

I tend to agree with this. Also there are unresolved issues1 with Error.isError

Footnotes

1. DOMException should have [[ErrorData]] internal slot #56497 ↩

I can't speak for the prematurity of this yet, but the linked issue seems more like an issue with the DomException not Error.isError

Sorry, Livia already mentioned this.

I think this is premature and entirely unnecessary but not to a point where i would needlessly block this over a subjective opinion.