util: introduce `util.types.is[…]` type checks

Provide public APIs for native typechecking that is actually useful.
The motivation for this is providing alternatives to userland
modules that would currently rely on `process.binding('util')`.

PR-URL: https://github.com/nodejs/node/pull/18415
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

1 files changed, 582 insertions, 5 deletions

diff --git a/doc/api/util.md b/doc/api/util.md
index 03ef10ba1a..524372a6fe 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -891,6 +891,555 @@ encoded bytes.
 
 The encoding supported by the `TextEncoder` instance. Always set to `'utf-8'`.
 
+## util.types
+<!-- YAML
+added: REPLACEME
+-->
+
+`util.types` provides a number of type checks for different kinds of built-in
+objects. Unlike `instanceof` or `Object.prototype.toString.call(value)`,
+these checks do not inspect properties of the object that are accessible from
+JavaScript (like their prototype), and usually have the overhead of
+calling into C++.
+
+The result generally does not make any guarantees about what kinds of
+properties or behavior a value exposes in JavaScript. They are primarily
+useful for addon developers who prefer to do type checking in JavaScript.
+
+### util.types.isAnyArrayBuffer(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`ArrayBuffer`][] or
+[`SharedArrayBuffer`][] instance.
+
+See also [`util.types.isArrayBuffer()`][] and
+[`util.types.isSharedArrayBuffer()`][].
+
+For example:
+
+```js
+util.types.isAnyArrayBuffer(new ArrayBuffer());  // Returns true
+util.types.isAnyArrayBuffer(new SharedArrayBuffer());  // Returns true
+```
+
+### util.types.isArgumentsObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is an `arguments` object.
+
+For example:
+
+<!-- eslint-disable prefer-rest-params -->
+```js
+function foo() {
+  util.types.isArgumentsObject(arguments);  // Returns true
+}
+```
+
+### util.types.isArrayBuffer(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`ArrayBuffer`][] instance.
+This does *not* include [`SharedArrayBuffer`][] instances. Usually, it is
+desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that.
+
+For example:
+
+```js
+util.types.isArrayBuffer(new ArrayBuffer());  // Returns true
+util.types.isArrayBuffer(new SharedArrayBuffer());  // Returns false
+```
+
+### util.types.isAsyncFunction(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is an [async function][].
+Note that this only reports back what the JavaScript engine is seeing;
+in particular, the return value may not match the original source code if
+a transpilation tool was used.
+
+For example:
+
+```js
+util.types.isAsyncFunction(function foo() {});  // Returns false
+util.types.isAsyncFunction(async function foo() {});  // Returns true
+```
+
+### util.types.isBooleanObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a boolean object, e.g. created
+by `new Boolean()`.
+
+For example:
+
+```js
+util.types.isBooleanObject(false);  // Returns false
+util.types.isBooleanObject(true);   // Returns false
+util.types.isBooleanObject(new Boolean(false));   // Returns true
+util.types.isBooleanObject(new Boolean(true));    // Returns true
+util.types.isBooleanObject(Boolean(false)); // Returns false
+util.types.isBooleanObject(Boolean(true)); // Returns false
+```
+
+### util.types.isDataView(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`DataView`][] instance.
+
+For example:
+
+```js
+const ab = new ArrayBuffer(20);
+util.types.isDataView(new DataView(ab));  // Returns true
+util.types.isDataView(new Float64Array());  // Returns false
+```
+
+See also [`ArrayBuffer.isView()`][].
+
+### util.types.isDate(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Date`][] instance.
+
+For example:
+
+```js
+util.types.isDate(new Date());  // Returns true
+```
+
+### util.types.isExternal(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a native `External` value.
+
+### util.types.isFloat32Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Float32Array`][] instance.
+
+For example:
+
+```js
+util.types.isFloat32Array(new ArrayBuffer());  // Returns false
+util.types.isFloat32Array(new Float32Array());  // Returns true
+util.types.isFloat32Array(new Float64Array());  // Returns false
+```
+
+### util.types.isFloat64Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Float64Array`][] instance.
+
+For example:
+
+```js
+util.types.isFloat64Array(new ArrayBuffer());  // Returns false
+util.types.isFloat64Array(new Uint8Array());  // Returns false
+util.types.isFloat64Array(new Float64Array());  // Returns true
+```
+
+### util.types.isGeneratorFunction(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a generator function.
+Note that this only reports back what the JavaScript engine is seeing;
+in particular, the return value may not match the original source code if
+a transpilation tool was used.
+
+For example:
+
+```js
+util.types.isGeneratorFunction(function foo() {});  // Returns false
+util.types.isGeneratorFunction(function* foo() {});  // Returns true
+```
+
+### util.types.isGeneratorObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a generator object as returned from a
+built-in generator function.
+Note that this only reports back what the JavaScript engine is seeing;
+in particular, the return value may not match the original source code if
+a transpilation tool was used.
+
+For example:
+
+```js
+function* foo() {}
+const generator = foo();
+util.types.isGeneratorObject(generator);  // Returns true
+```
+
+### util.types.isInt8Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Int8Array`][] instance.
+
+For example:
+
+```js
+util.types.isInt8Array(new ArrayBuffer());  // Returns false
+util.types.isInt8Array(new Int8Array());  // Returns true
+util.types.isInt8Array(new Float64Array());  // Returns false
+```
+
+### util.types.isInt16Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Int16Array`][] instance.
+
+For example:
+
+```js
+util.types.isInt16Array(new ArrayBuffer());  // Returns false
+util.types.isInt16Array(new Int16Array());  // Returns true
+util.types.isInt16Array(new Float64Array());  // Returns false
+```
+
+### util.types.isInt32Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Int32Array`][] instance.
+
+For example:
+
+```js
+util.types.isInt32Array(new ArrayBuffer());  // Returns false
+util.types.isInt32Array(new Int32Array());  // Returns true
+util.types.isInt32Array(new Float64Array());  // Returns false
+```
+
+### util.types.isMap(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Map`][] instance.
+
+For example:
+
+```js
+util.types.isMap(new Map());  // Returns true
+```
+
+### util.types.isMapIterator(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is an iterator returned for a built-in
+[`Map`][] instance.
+
+For example:
+
+```js
+const map = new Map();
+util.types.isMapIterator(map.keys());  // Returns true
+util.types.isMapIterator(map.values());  // Returns true
+util.types.isMapIterator(map.entries());  // Returns true
+util.types.isMapIterator(map[Symbol.iterator]());  // Returns true
+```
+
+### util.types.isNativeError(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is an instance of a built-in [`Error`][] type.
+
+For example:
+
+```js
+util.types.isNativeError(new Error());  // Returns true
+util.types.isNativeError(new TypeError());  // Returns true
+util.types.isNativeError(new RangeError());  // Returns true
+```
+
+### util.types.isNumberObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a number object, e.g. created
+by `new Number()`.
+
+For example:
+
+```js
+util.types.isNumberObject(0);  // Returns false
+util.types.isNumberObject(new Number(0));   // Returns true
+```
+
+### util.types.isPromise(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Promise`][].
+
+For example:
+
+```js
+util.types.isPromise(Promise.resolve(42));  // Returns true
+```
+
+### util.types.isProxy(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a [`Proxy`][] instance.
+
+For example:
+
+```js
+const target = {};
+const proxy = new Proxy(target, {});
+util.types.isProxy(target);  // Returns false
+util.types.isProxy(proxy);  // Returns true
+```
+
+### util.types.isRegExp(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a regular expression object.
+
+For example:
+
+```js
+util.types.isRegExp(/abc/);  // Returns true
+util.types.isRegExp(new RegExp('abc'));  // Returns true
+```
+
+### util.types.isSet(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Set`][] instance.
+
+For example:
+
+```js
+util.types.isSet(new Set());  // Returns true
+```
+
+### util.types.isSetIterator(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is an iterator returned for a built-in
+[`Set`][] instance.
+
+For example:
+
+```js
+const set = new Set();
+util.types.isSetIterator(set.keys());  // Returns true
+util.types.isSetIterator(set.values());  // Returns true
+util.types.isSetIterator(set.entries());  // Returns true
+util.types.isSetIterator(set[Symbol.iterator]());  // Returns true
+```
+
+### util.types.isSharedArrayBuffer(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`SharedArrayBuffer`][] instance.
+This does *not* include [`ArrayBuffer`][] instances. Usually, it is
+desirable to test for both; See [`util.types.isAnyArrayBuffer()`][] for that.
+
+For example:
+
+```js
+util.types.isSharedArrayBuffer(new ArrayBuffer());  // Returns false
+util.types.isSharedArrayBuffer(new SharedArrayBuffer());  // Returns true
+```
+
+### util.types.isStringObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a string object, e.g. created
+by `new String()`.
+
+For example:
+
+```js
+util.types.isStringObject('foo');  // Returns false
+util.types.isStringObject(new String('foo'));   // Returns true
+```
+
+### util.types.isSymbolObject(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a symbol object, created
+by calling `Object()` on a `Symbol` primitive.
+
+For example:
+
+```js
+const symbol = Symbol('foo');
+util.types.isSymbolObject(symbol);  // Returns false
+util.types.isSymbolObject(Object(symbol));   // Returns true
+```
+
+### util.types.isTypedArray(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`TypedArray`][] instance.
+
+For example:
+
+```js
+util.types.isTypedArray(new ArrayBuffer());  // Returns false
+util.types.isTypedArray(new Uint8Array());  // Returns true
+util.types.isTypedArray(new Float64Array());  // Returns true
+```
+
+See also [`ArrayBuffer.isView()`][].
+
+### util.types.isUint8Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Uint8Array`][] instance.
+
+For example:
+
+```js
+util.types.isUint8Array(new ArrayBuffer());  // Returns false
+util.types.isUint8Array(new Uint8Array());  // Returns true
+util.types.isUint8Array(new Float64Array());  // Returns false
+```
+
+### util.types.isUint8ClampedArray(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Uint8ClampedArray`][] instance.
+
+For example:
+
+```js
+util.types.isUint8ClampedArray(new ArrayBuffer());  // Returns false
+util.types.isUint8ClampedArray(new Uint8ClampedArray());  // Returns true
+util.types.isUint8ClampedArray(new Float64Array());  // Returns false
+```
+
+### util.types.isUint16Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Uint16Array`][] instance.
+
+For example:
+
+```js
+util.types.isUint16Array(new ArrayBuffer());  // Returns false
+util.types.isUint16Array(new Uint16Array());  // Returns true
+util.types.isUint16Array(new Float64Array());  // Returns false
+```
+
+### util.types.isUint32Array(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`Uint32Array`][] instance.
+
+For example:
+
+```js
+util.types.isUint32Array(new ArrayBuffer());  // Returns false
+util.types.isUint32Array(new Uint32Array());  // Returns true
+util.types.isUint32Array(new Float64Array());  // Returns false
+```
+
+### util.types.isWeakMap(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`WeakMap`][] instance.
+
+For example:
+
+```js
+util.types.isWeakMap(new WeakMap());  // Returns true
+```
+
+### util.types.isWeakSet(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`WeakSet`][] instance.
+
+For example:
+
+```js
+util.types.isWeakSet(new WeakSet());  // Returns true
+```
+
+### util.types.isWebAssemblyCompiledModule(value)
+<!-- YAML
+added: REPLACEME
+-->
+
+Returns `true` if the value is a built-in [`WebAssembly.Module`][] instance.
+
+For example:
+
+```js
+const module = new WebAssembly.Module(wasmBuffer);
+util.types.isWebAssemblyCompiledModule(module);  // Returns true
+```
+
+
 ## Deprecated APIs
 
 The following APIs have been deprecated and should no longer be used. Existing
@@ -1014,7 +1563,7 @@ added: v0.6.0
 deprecated: v4.0.0
 -->
 
-> Stability: 0 - Deprecated
+> Stability: 0 - Deprecated: Use [`util.types.isDate()`][] instead.
 
 * `object` {any}
 * Returns: {boolean}
@@ -1038,7 +1587,7 @@ added: v0.6.0
 deprecated: v4.0.0
 -->
 
-> Stability: 0 - Deprecated
+> Stability: 0 - Deprecated: Use [`util.types.isNativeError()`][] instead.
 
 * `object` {any}
 * Returns: {boolean}
@@ -1385,14 +1934,42 @@ Deprecated predecessor of `console.log`.
 
 [`'uncaughtException'`]: process.html#process_event_uncaughtexception
 [`Array.isArray()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray
-[`Buffer.isBuffer()`]: buffer.html#buffer_class_method_buffer_isbuffer_obj
-[`Error`]: errors.html#errors_class_error
-[`Object.assign()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
+[`ArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer
+[`ArrayBuffer.isView()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer/isView
+[async function]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function
 [`assert.deepStrictEqual()`]: assert.html#assert_assert_deepstrictequal_actual_expected_message
+[`Buffer.isBuffer()`]: buffer.html#buffer_class_method_buffer_isbuffer_obj
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
+[`DataView`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView
+[`Date`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
+[`Error`]: errors.html#errors_class_error
+[`Float32Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float32Array
+[`Float64Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Float64Array
+[`Int8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int8Array
+[`Int16Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int16Array
+[`Int32Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
+[`Map`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
+[`Object.assign()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign
+[`Promise`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[`Proxy`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy
+[`Set`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set
+[`SharedArrayBuffer`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer
+[`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 [`util.inspect()`]: #util_util_inspect_object_options
 [`util.promisify()`]: #util_util_promisify_original
+[`util.types.isAnyArrayBuffer()`]: #util_util_types_isanyarraybuffer_value
+[`util.types.isArrayBuffer()`]: #util_util_types_isarraybuffer_value
+[`util.types.isDate()`]: #util_util_types_isdate_value
+[`util.types.isNativeError()`]: #util_util_types_isnativeerror_value
+[`util.types.isSharedArrayBuffer()`]: #util_util_types_issharedarraybuffer_value
+[`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
+[`Uint8ClampedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8ClampedArray
+[`Uint16Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint16Array
+[`Uint32Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint32Array
+[`WeakMap`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
+[`WeakSet`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakSet
+[`WebAssembly.Module`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Module
 [Custom inspection functions on Objects]: #util_custom_inspection_functions_on_objects
 [Custom promisified functions]: #util_custom_promisified_functions
 [Customizing `util.inspect` colors]: #util_customizing_util_inspect_colors