Commit 82c7757
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 49981b9 commit 82c7757
1 file changed
Lines changed: 37 additions & 4 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -2510,12 +2510,43 @@ added: v10.0.0 | |||
| 2510 | 2510 | * `value` {any} | |
| 2511 | 2511 | * Returns: {boolean} | |
| 2512 | 2512 | ||
| 2513 | - Returns `true` if the value is an instance of a built-in [`Error`][] type. | ||
| 2513 | + Returns `true` if the value was returned by the constructor of a | ||
| 2514 | + [built-in `Error` type][]. | ||
| 2514 | 2515 | ||
| 2515 | 2516 | ```js | |
| 2516 | - util.types.isNativeError(new Error()); // Returns true | ||
| 2517 | - util.types.isNativeError(new TypeError()); // Returns true | ||
| 2518 | - util.types.isNativeError(new RangeError()); // Returns true | ||
| 2517 | + console.log(util.types.isNativeError(new Error())); // true | ||
| 2518 | + console.log(util.types.isNativeError(new TypeError())); // true | ||
| 2519 | + console.log(util.types.isNativeError(new RangeError())); // true | ||
| 2520 | + ``` | ||
| 2521 | + | ||
| 2522 | + Subclasses of the native error types are also native errors: | ||
| 2523 | + | ||
| 2524 | + ```js | ||
| 2525 | + class MyError extends Error {} | ||
| 2526 | + console.log(util.types.isNativeError(new MyError())); // true | ||
| 2527 | + ``` | ||
| 2528 | + | ||
| 2529 | + A value being `instanceof` a native error class is not equivalent to `isNativeError()` | ||
| 2530 | + returning `true` for that value. `isNativeError()` returns `true` for errors | ||
| 2531 | + which come from a different [realm][] while `instanceof Error` returns `false` | ||
| 2532 | + for these errors: | ||
| 2533 | + | ||
| 2534 | + ```js | ||
| 2535 | + const vm = require('node:vm'); | ||
| 2536 | + const context = vm.createContext({}); | ||
| 2537 | + const myError = vm.runInContext('new Error', context); | ||
| 2538 | + console.log(util.types.isNativeError(myError)); // true | ||
| 2539 | + console.log(myError instanceof Error); // false | ||
| 2540 | + ``` | ||
| 2541 | + | ||
| 2542 | + Conversely, `isNativeError()` returns `false` for all objects which were not | ||
| 2543 | + returned by the constructor of a native error. That includes values | ||
| 2544 | + which are `instanceof` native errors: | ||
| 2545 | + | ||
| 2546 | + ```js | ||
| 2547 | + const myError = { __proto__: Error.prototype }; | ||
| 2548 | + console.log(util.types.isNativeError(myError)); // false | ||
| 2549 | + console.log(myError instanceof Error); // true | ||
| 2519 | 2550 | ``` | |
| 2520 | 2551 | ||
| 2521 | 2552 | ### `util.types.isNumberObject(value)` | |
@@ -3330,11 +3361,13 @@ util.log('Timestamped message.'); | |||
| 3330 | 3361 | [`util.types.isNativeError()`]: #utiltypesisnativeerrorvalue | |
| 3331 | 3362 | [`util.types.isSharedArrayBuffer()`]: #utiltypesissharedarraybuffervalue | |
| 3332 | 3363 | [async function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function | |
| 3364 | + [built-in `Error` type]: https://tc39.es/ecma262/#sec-error-objects | ||
| 3333 | 3365 | [compare function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Parameters | |
| 3334 | 3366 | [constructor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/constructor | |
| 3335 | 3367 | [default sort]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | |
| 3336 | 3368 | [global symbol registry]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/for | |
| 3337 | 3369 | [list of deprecated APIS]: deprecations.md#list-of-deprecated-apis | |
| 3338 | 3370 | [pkgjs/parseargs]: https://github.com/pkgjs/parseargs | |
| 3371 | + [realm]: https://tc39.es/ecma262/#realm | ||
| 3339 | 3372 | [semantically incompatible]: https://github.com/nodejs/node/issues/4179 | |
| 3340 | 3373 | [util.inspect.custom]: #utilinspectcustom | |
0 commit comments