diff --git a/doc/api/util.md b/doc/api/util.md index 9add56bfaf40c9..8fe3870f693f67 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -2510,12 +2510,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)` @@ -3330,11 +3361,13 @@ 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 [pkgjs/parseargs]: https://github.com/pkgjs/parseargs +[realm]: https://tc39.es/ecma262/#realm [semantically incompatible]: https://github.com/nodejs/node/issues/4179 [util.inspect.custom]: #utilinspectcustom