Commit 2dd3b02
doc: improve documentation for util.types.isNativeError()
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: #46840
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>1 parent 732a98e commit 2dd3b02
1 file changed
Lines changed: 37 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2504,12 +2504,43 @@ added: v10.0.0 | |||
| 2504 | 2504 | * `value` {any} | |
| 2505 | 2505 | * Returns: {boolean} | |
| 2506 | 2506 | ||
| 2507 | - Returns `true` if the value is an instance of a built-in [`Error`][] type. | ||
| 2507 | + Returns `true` if the value was returned by the constructor of a | ||
| 2508 | + [built-in `Error` type][]. | ||
| 2508 | 2509 | ||
| 2509 | 2510 | ```js | |
| 2510 | - util.types.isNativeError(new Error()); // Returns true | ||
| 2511 | - util.types.isNativeError(new TypeError()); // Returns true | ||
| 2512 | - util.types.isNativeError(new RangeError()); // Returns true | ||
| 2511 | + console.log(util.types.isNativeError(new Error())); // true | ||
| 2512 | + console.log(util.types.isNativeError(new TypeError())); // true | ||
| 2513 | + console.log(util.types.isNativeError(new RangeError())); // true | ||
| 2514 | + ``` | ||
| 2515 | + | ||
| 2516 | + Subclasses of the native error types are also native errors: | ||
| 2517 | + | ||
| 2518 | + ```js | ||
| 2519 | + class MyError extends Error {} | ||
| 2520 | + console.log(util.types.isNativeError(new MyError())); // true | ||
| 2521 | + ``` | ||
| 2522 | + | ||
| 2523 | + A value being `instanceof` a native error class is not equivalent to `isNativeError()` | ||
| 2524 | + returning `true` for that value. `isNativeError()` returns `true` for errors | ||
| 2525 | + which come from a different [realm][] while `instanceof Error` returns `false` | ||
| 2526 | + for these errors: | ||
| 2527 | + | ||
| 2528 | + ```js | ||
| 2529 | + const vm = require('node:vm'); | ||
| 2530 | + const context = vm.createContext({}); | ||
| 2531 | + const myError = vm.runInContext('new Error', context); | ||
| 2532 | + console.log(util.types.isNativeError(myError)); // true | ||
| 2533 | + console.log(myError instanceof Error); // false | ||
| 2534 | + ``` | ||
| 2535 | + | ||
| 2536 | + Conversely, `isNativeError()` returns `false` for all objects which were not | ||
| 2537 | + returned by the constructor of a native error. That includes values | ||
| 2538 | + which are `instanceof` native errors: | ||
| 2539 | + | ||
| 2540 | + ```js | ||
| 2541 | + const myError = { __proto__: Error.prototype }; | ||
| 2542 | + console.log(util.types.isNativeError(myError)); // false | ||
| 2543 | + console.log(myError instanceof Error); // true | ||
| 2513 | 2544 | ``` | |
| 2514 | 2545 | ||
| 2515 | 2546 | ### `util.types.isNumberObject(value)` | |
@@ -3324,11 +3355,13 @@ util.log('Timestamped message.'); | |||
| 3324 | 3355 | [`util.types.isNativeError()`]: #utiltypesisnativeerrorvalue | |
| 3325 | 3356 | [`util.types.isSharedArrayBuffer()`]: #utiltypesissharedarraybuffervalue | |
| 3326 | 3357 | [async function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | |
| 3358 | + [built-in `Error` type]: https://tc39.es/ecma262/#sec-error-objects | ||
| 3327 | 3359 | [compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters | |
| 3328 | 3360 | [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor | |
| 3329 | 3361 | [default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | |
| 3330 | 3362 | [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for | |
| 3331 | 3363 | [list of deprecated APIS]: deprecations.md#list-of-deprecated-apis | |
| 3332 | 3364 | [pkgjs/parseargs]: https://github.com/pkgjs/parseargs | |
| 3365 | + [realm]: https://tc39.es/ecma262/#realm | ||
| 3333 | 3366 | [semantically incompatible]: https://github.com/nodejs/node/issues/4179 | |
| 3334 | 3367 | [util.inspect.custom]: #utilinspectcustom | |
0 commit comments