Mirrors/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2025-12-28 07:50:41 +00:00
Code Issues Actions 17 Packages Projects Releases Wiki Activity

doc: improve documentation for util.types.isNativeError()

Browse Source 
Makes clear what a native error is by linking the spec. Explains that
`instanceof Error` and util.types.isNativeError() are not equivalent.
Give examples for objects that are `instance of Error` but not native
errors and vice versa. Recommends checking for both if one wants to find
out if something is an error.

PR-URL: https://github.com/nodejs/node/pull/46840
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This commit is contained in:
Julian Dax 2023-03-18 14:13:37 +01:00 committed by GitHub
parent 9ce2f4f5e1
commit 35dd93841b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/api/util.md
View File

@ -2515,12 +2515,43 @@ added: v10.0.0
* `value` {any}
* Returns: {boolean}
Returns `true` if the value is an instance of a built-in [`Error`][] type.
Returns `true` if the value was returned by the constructor of a
[built-in `Error` type][].
```js
util.types.isNativeError(new Error()); // Returns true
util.types.isNativeError(new TypeError()); // Returns true
util.types.isNativeError(new RangeError()); // Returns true
console.log(util.types.isNativeError(new Error())); // true
console.log(util.types.isNativeError(new TypeError())); // true
console.log(util.types.isNativeError(new RangeError())); // true
```
Subclasses of the native error types are also native errors:
```js
class MyError extends Error {}
console.log(util.types.isNativeError(new MyError())); // true
```
A value being `instanceof` a native error class is not equivalent to `isNativeError()`
returning `true` for that value. `isNativeError()` returns `true` for errors
which come from a different [realm][] while `instanceof Error` returns `false`
for these errors:
```js
const vm = require('node:vm');
const context = vm.createContext({});
const myError = vm.runInContext('new Error', context);
console.log(util.types.isNativeError(myError)); // true
console.log(myError instanceof Error); // false
```
Conversely, `isNativeError()` returns `false` for all objects which were not
returned by the constructor of a native error. That includes values
which are `instanceof` native errors:
```js
const myError = { __proto__: Error.prototype };
console.log(util.types.isNativeError(myError)); // false
console.log(myError instanceof Error); // true
```
### `util.types.isNumberObject(value)`
@ -3335,10 +3366,12 @@ util.log('Timestamped message.');
[`util.types.isNativeError()`]: #utiltypesisnativeerrorvalue
[`util.types.isSharedArrayBuffer()`]: #utiltypesissharedarraybuffervalue
[async function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
[built-in `Error` type]: https://tc39.es/ecma262/#sec-error-objects
[compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters
[constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor
[default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort
[global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for
[list of deprecated APIS]: deprecations.md#list-of-deprecated-apis
[realm]: https://tc39.es/ecma262/#realm
[semantically incompatible]: https://github.com/nodejs/node/issues/4179
[util.inspect.custom]: #utilinspectcustom