diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index 607678ebbfba95..ce2872a3a9896e 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -964,6 +964,9 @@ The [`tls.SecurePair`][] class is deprecated. Please use -Type: Documentation-only +Type: Runtime The [`util.isArray()`][] API is deprecated. Please use `Array.isArray()` instead. @@ -985,6 +988,9 @@ instead. -Type: Documentation-only +Type: Runtime -The [`util.isBoolean()`][] API is deprecated. +The [`util.isBoolean()`][] API is deprecated. Please use +`typeof arg === 'boolean'` instead. ### DEP0046: `util.isBuffer()` -Type: Documentation-only +Type: Runtime The [`util.isBuffer()`][] API is deprecated. Please use [`Buffer.isBuffer()`][] instead. @@ -1026,6 +1036,9 @@ The [`util.isBuffer()`][] API is deprecated. Please use -Type: Documentation-only +Type: Runtime -The [`util.isDate()`][] API is deprecated. +The [`util.isDate()`][] API is deprecated. Please use +`arg instanceof Date` instead. ### DEP0048: `util.isError()` -Type: Documentation-only +Type: Runtime -The [`util.isError()`][] API is deprecated. +The [`util.isError()`][] API is deprecated. Please use +`Object.prototype.toString(arg) === '[object Error]' || arg instanceof Error` +instead. ### DEP0049: `util.isFunction()` -Type: Documentation-only +Type: Runtime -The [`util.isFunction()`][] API is deprecated. +The [`util.isFunction()`][] API is deprecated. Please use +`typeof arg === 'function'` instead. ### DEP0050: `util.isNull()` -Type: Documentation-only +Type: Runtime -The [`util.isNull()`][] API is deprecated. +The [`util.isNull()`][] API is deprecated. Please use +`arg === null` instead. ### DEP0051: `util.isNullOrUndefined()` -Type: Documentation-only +Type: Runtime -The [`util.isNullOrUndefined()`][] API is deprecated. +The [`util.isNullOrUndefined()`][] API is deprecated. Please use +`arg === null || arg === undefined` instead. ### DEP0052: `util.isNumber()` -Type: Documentation-only +Type: Runtime -The [`util.isNumber()`][] API is deprecated. +The [`util.isNumber()`][] API is deprecated. Please use +`typeof arg === 'number'` instead. ### DEP0053: `util.isObject()` -Type: Documentation-only +Type: Runtime -The [`util.isObject()`][] API is deprecated. +The [`util.isObject()`][] API is deprecated. Please use +`arg && typeof arg === 'object'` instead. ### DEP0054: `util.isPrimitive()` -Type: Documentation-only +Type: Runtime -The [`util.isPrimitive()`][] API is deprecated. +The [`util.isPrimitive()`][] API is deprecated. Please use +`arg === null || (typeof arg !=='object' && typeof arg !== 'function')` +instead. ### DEP0055: `util.isRegExp()` -Type: Documentation-only +Type: Runtime -The [`util.isRegExp()`][] API is deprecated. +The [`util.isRegExp()`][] API is deprecated. Please use +`arg instanceof RegExp` instead. ### DEP0056: `util.isString()` -Type: Documentation-only +Type: Runtime -The [`util.isString()`][] API is deprecated. +The [`util.isString()`][] API is deprecated. Please use +`typeof arg === 'string'` instead. ### DEP0057: `util.isSymbol()` -Type: Documentation-only +Type: Runtime -The [`util.isSymbol()`][] API is deprecated. +The [`util.isSymbol()`][] API is deprecated. Please use +`typeof arg === 'symbol'` instead. ### DEP0058: `util.isUndefined()` -Type: Documentation-only +Type: Runtime -The [`util.isUndefined()`][] API is deprecated. +The [`util.isUndefined()`][] API is deprecated. Please use +`arg === undefined` instead. ### DEP0059: `util.log()` -Type: Documentation-only +Type: Runtime + +The [`util.log()`][] API has been deprecated because it's an unmaintained +legacy API that was exposed to user land by accident. Instead, +consider the following alternatives based on your specific needs: + +* **Third-Party Logging Libraries** + +* **Use `console.log(new Date().toLocaleString(), message)`** -The [`util.log()`][] API is deprecated. +By adopting one of these alternatives, you can transition away from `util.log()` +and choose a logging strategy that aligns with the specific +requirements and complexity of your application. ### DEP0060: `util._extend()` -Type: Documentation-only +Type: Runtime -The [`util._extend()`][] API is deprecated. +The [`util._extend()`][] API is deprecated because it's an unmaintained +legacy API that was exposed to user land by accident. +Please use `target = Object.assign(target, source)` instead. ### DEP0061: `fs.SyncWriteStream` diff --git a/lib/util.js b/lib/util.js index 9ddb332f866355..b882ef304096a3 100644 --- a/lib/util.js +++ b/lib/util.js @@ -375,7 +375,9 @@ function _exceptionWithHostPort(...args) { module.exports = { _errnoException, _exceptionWithHostPort, - _extend, + _extend: deprecate(_extend, + 'The `util._extend` API is deprecated. Please use Object.assign() instead.', + 'DEP0060'), callbackify, debug: debuglog, debuglog, @@ -386,9 +388,15 @@ module.exports = { getSystemErrorName, inherits, inspect, - isArray: ArrayIsArray, - isBoolean, - isBuffer, + isArray: deprecate(ArrayIsArray, + 'The `util.isArray` API is deprecated. Please use `Array.isArray()` instead.', + 'DEP0044'), + isBoolean: deprecate(isBoolean, + 'The `util.isBoolean` API is deprecated. Please use `typeof arg === "boolean"` instead.', + 'DEP0045'), + isBuffer: deprecate(isBuffer, + 'The `util.isBuffer` API is deprecated. Please use `Buffer.isBuffer()` instead.', + 'DEP0046'), isDeepStrictEqual(a, b) { if (internalDeepEqual === undefined) { internalDeepEqual = require('internal/util/comparisons') @@ -396,19 +404,52 @@ module.exports = { } return internalDeepEqual(a, b); }, - isNull, - isNullOrUndefined, - isNumber, - isString, - isSymbol, - isUndefined, - isRegExp: types.isRegExp, - isObject, - isDate: types.isDate, - isError, - isFunction, - isPrimitive, - log, + isNull: deprecate(isNull, + 'The `util.isNull` API is deprecated. Please use `arg === null` instead.', + 'DEP0050'), + isNullOrUndefined: deprecate(isNullOrUndefined, + 'The `util.isNullOrUndefined` API is deprecated. ' + + 'Please use `arg === null || arg === undefined` instead.', + 'DEP0051'), + isNumber: deprecate(isNumber, + 'The `util.isNumber` API is deprecated. Please use `typeof arg === "number"` instead.', + 'DEP0052'), + isString: deprecate(isString, + 'The `util.isString` API is deprecated. Please use `typeof arg === "string"` instead.', + 'DEP0056'), + isSymbol: deprecate(isSymbol, + 'The `util.isSymbol` API is deprecated. Please use `arg === "symbol"` instead.', + 'DEP0057'), + isUndefined: deprecate(isUndefined, + 'The `util.isUndefined` API is deprecated. Please use `arg === undefined` instead.', + 'DEP0058'), + isRegExp: deprecate(types.isRegExp, + 'The `util.isRegExp` API is deprecated. Please use `arg instanceof RegExp` instead.', + 'DEP0055'), + isObject: deprecate(isObject, + 'The `util.isObject` API is deprecated. ' + + 'Please use `arg !== null && typeof arg === "object"` instead.', + 'DEP0053'), + isDate: deprecate(types.isDate, + 'The `util.isDate` API is deprecated. Please use `arg instanceof Date` instead.', + 'DEP0047'), + isError: deprecate(isError, + 'The `util.isError` API is deprecated. ' + + 'Please use `ObjectPrototypeToString(e) === "[object Error]" ' + + '|| e instanceof Error` instead.', + 'DEP0048'), + isFunction: deprecate(isFunction, + 'The `util.isFunction` API is deprecated. Please use `typeof arg === "function"` instead.', + 'DEP0049'), + isPrimitive: deprecate(isPrimitive, + 'The `util.isPrimitive` API is deprecated. ' + + 'Please use `arg === null || ' + + '(typeof arg !== "object" && typeof arg !== "function")` instead.', + 'DEP0054'), + log: deprecate(log, + 'The `util.log API is deprecated. ' + + 'Please use console.log() with a custom formatter or a third-party logger instead.', + 'DEP0059'), promisify, stripVTControlCharacters, toUSVString,