fixup! util: add formatText API to text formatting

doc/api/util.md

@@ -345,31 +345,6 @@ util.format('%% %s');
 Some input values can have a significant performance overhead that can block the
 event loop. Use this function with care and never in a hot code path.
 
-## `util.formatText(format, text)`
-
-> Stability: 1 - Experimental
-
-<!-- YAML
-added: REPLACEME
--->
-
-* `format` {string} A text format defined in `util.inspect.colors`.
-* `text` {string} The text to to be formatted.
-
-This function returns a formatted text considering the `format` passed
-
-```js
-const textRedCollor = util.formatText('red', 'My red message');
-console.log(textRedCollor);
-```
-
-`util.inspect.colors` also provides text formats such as `italic`, and
-`underline`:
-
-```js
-console.log(util.formatText('italic', 'My italic message'));
-```
-
 ## `util.formatWithOptions(inspectOptions, format[, ...args])`
 
 <!-- YAML
@@ -1817,6 +1792,31 @@ console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
 // Prints "value"
 ```
 
+## `util.styleText(format, text)`
+
+> Stability: 1.1 - Active development
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `format` {string} A text format defined in `util.inspect.colors`.
+* `text` {string} The text to to be formatted.
+
+This function returns a formatted text considering the `format` passed.
+
+```js
+const textRedCollr = util.styleText('red', 'My red message');
+console.log(textRedColor);
+```
+
+`util.inspect.colors` also provides text formats such as `italic`, and
+`underline` and you can combine both:
+
+```js
+console.log(util.styleText('underline', util.styleText('italic', 'My italic underlined message')));
+```
+
 ## Class: `util.TextDecoder`
 
 <!-- YAML

lib/util.js

@@ -51,7 +51,6 @@ const {
   codes: {
     ERR_FALSY_VALUE_REJECTION,
     ERR_INVALID_ARG_TYPE,
-    ERR_INVALID_ARG_VALUE,
     ERR_OUT_OF_RANGE,
   },
   isErrorStackTraceLimitWritable,
@@ -69,6 +68,7 @@ const {
   validateFunction,
   validateNumber,
   validateString,
+  validateOneOf,
 } = require('internal/validators');
 const { isBuffer } = require('buffer').Buffer;
 const types = require('internal/util/types');
@@ -203,17 +203,10 @@ function pad(n) {
  * @param {string} text
  * @returns {string}
  */
-function formatText(format, text) {
-  validateString(format, 'format');
+function styleText(format, text) {
+  validateOneOf(format, 'format', ObjectKeys(inspect.colors));
   validateString(text, 'text');
   const formatCodes = inspect.colors[format];
-  if (formatCodes === undefined) {
-    throw new ERR_INVALID_ARG_VALUE(
-      'format',
-      `${format}`,
-      `must be one of ${ObjectKeys(inspect.colors).join(',')}`,
-    );
-  }
   return `\u001b[${formatCodes[0]}m${text}\u001b[${formatCodes[1]}m`;
 }
 
@@ -415,7 +408,7 @@ module.exports = {
   debuglog,
   deprecate,
   format,
-  formatText,
+  styleText,
   formatWithOptions,
   getSystemErrorMap,
   getSystemErrorName,

test/parallel/test-util-styletext.js

@@ -0,0 +1,35 @@
+'use strict';
+require('../common');
+const assert = require('assert');
+const util = require('util');
+
+[
+  undefined,
+  null,
+  false,
+  5n,
+  5,
+  Symbol(),
+  () => {},
+  {},
+  [],
+].forEach((invalidOption) => {
+  assert.throws(() => {
+    util.styleText(invalidOption, 'test');
+  }, {
+    code: 'ERR_INVALID_ARG_VALUE',
+  });
+  assert.throws(() => {
+    util.styleText('red', invalidOption);
+  }, {
+    code: 'ERR_INVALID_ARG_TYPE'
+  });
+});
+
+assert.throws(() => {
+  util.styleText('invalid', 'text');
+}, {
+  code: 'ERR_INVALID_ARG_VALUE',
+});
+
+assert.strictEqual(util.styleText('red', 'test'), '\u001b[31mtest\u001b[39m');