From 900d79caf2e2afc7d47cb09da4f1f397fd3d31d2 Mon Sep 17 00:00:00 2001 From: Marco Ippolito Date: Tue, 31 Oct 2023 15:37:19 +0200 Subject: [PATCH] doc: add migration paths for deprecated utils PR-URL: https://github.com/nodejs/node/pull/50488 Reviewed-By: Rafael Gonzaga Reviewed-By: Yagiz Nizipli Reviewed-By: Robert Nagy Reviewed-By: James M Snell Reviewed-By: Ruben Bridgewater Reviewed-By: Joyee Cheung --- doc/api/deprecations.md | 53 ++++++++++++++++++++++++++++++----------- lib/util.js | 2 +- 2 files changed, 40 insertions(+), 15 deletions(-) diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index a39728b6e5b9a8..67f74ba4cb0b59 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -1005,7 +1005,8 @@ changes: Type: Runtime -The [`util.isBoolean()`][] API is deprecated. +The [`util.isBoolean()`][] API is deprecated. Please use +`typeof arg === 'boolean'` instead. ### DEP0046: `util.isBuffer()` @@ -1052,7 +1053,8 @@ changes: Type: Runtime -The [`util.isDate()`][] API is deprecated. +The [`util.isDate()`][] API is deprecated. Please use +`arg instanceof Date` instead. ### DEP0048: `util.isError()` @@ -1100,7 +1102,8 @@ changes: Type: Runtime -The [`util.isFunction()`][] API is deprecated. +The [`util.isFunction()`][] API is deprecated. Please use +`typeof arg === 'function'` instead. ### DEP0050: `util.isNull()` @@ -1123,7 +1126,8 @@ changes: Type: Runtime -The [`util.isNull()`][] API is deprecated. +The [`util.isNull()`][] API is deprecated. Please use +`arg === null` instead. ### DEP0051: `util.isNullOrUndefined()` @@ -1146,7 +1150,8 @@ changes: Type: Runtime -The [`util.isNullOrUndefined()`][] API is deprecated. +The [`util.isNullOrUndefined()`][] API is deprecated. Please use +`arg === null || arg === undefined` instead. ### DEP0052: `util.isNumber()` @@ -1169,7 +1174,8 @@ changes: Type: Runtime -The [`util.isNumber()`][] API is deprecated. +The [`util.isNumber()`][] API is deprecated. Please use +`typeof arg === 'number'` instead. ### DEP0053: `util.isObject()` @@ -1192,7 +1198,8 @@ changes: Type: Runtime -The [`util.isObject()`][] API is deprecated. +The [`util.isObject()`][] API is deprecated. Please use +`arg && typeof arg === 'object'` instead. ### DEP0054: `util.isPrimitive()` @@ -1215,7 +1222,9 @@ changes: 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()` @@ -1238,7 +1247,8 @@ changes: Type: Runtime -The [`util.isRegExp()`][] API is deprecated. +The [`util.isRegExp()`][] API is deprecated. Please use +`arg instanceof RegExp` instead. ### DEP0056: `util.isString()` @@ -1261,7 +1271,8 @@ changes: Type: Runtime -The [`util.isString()`][] API is deprecated. +The [`util.isString()`][] API is deprecated. Please use +`typeof arg === 'string'` instead. ### DEP0057: `util.isSymbol()` @@ -1284,7 +1295,8 @@ changes: Type: Runtime -The [`util.isSymbol()`][] API is deprecated. +The [`util.isSymbol()`][] API is deprecated. Please use +`typeof arg === 'symbol'` instead. ### DEP0058: `util.isUndefined()` @@ -1307,7 +1319,8 @@ changes: Type: Runtime -The [`util.isUndefined()`][] API is deprecated. +The [`util.isUndefined()`][] API is deprecated. Please use +`arg === undefined` instead. ### DEP0059: `util.log()` @@ -1326,7 +1339,17 @@ changes: Type: Runtime -The [`util.log()`][] API is deprecated. +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)`** + +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()` @@ -1345,7 +1368,9 @@ changes: 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 0e8a79d2b35eae..b882ef304096a3 100644 --- a/lib/util.js +++ b/lib/util.js @@ -431,7 +431,7 @@ module.exports = { 'Please use `arg !== null && typeof arg === "object"` instead.', 'DEP0053'), isDate: deprecate(types.isDate, - 'The `util.isDate API is deprecated. Please use `arg instanceof Error` instead.', + 'The `util.isDate` API is deprecated. Please use `arg instanceof Date` instead.', 'DEP0047'), isError: deprecate(isError, 'The `util.isError` API is deprecated. ' +