lib: respect terminal capabilities on styleText

doc/api/util.md

@@ -1810,24 +1810,55 @@ console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
 added:
   - v21.7.0
   - v20.12.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/54389
+    description: Respect isTTY and colors environment variables
+      such as NO_COLORS, NODE_DISABLE_COLORS, and FORCE_COLOR.
 -->
 
 * `format` {string | Array} A text format or an Array
   of text formats defined in `util.inspect.colors`.
 * `text` {string} The text to to be formatted.
+* `options` {Object}
+  * `validateStream` {boolean} When true, `stream` is checked to see if it can handle colors. **Default:** `true`.
+  * `stream` {Stream} A stream that will be validated if it can be colored. **Default:** `process.stdout`.
 
-This function returns a formatted text considering the `format` passed.
+This function returns a formatted text considering the `format` passed
+for printing in a terminal, it is aware of the terminal's capabilities
+and act according to the configuration set via `NO_COLORS`,
+`NODE_DISABLE_COLORS` and `FORCE_COLOR` environment variables.
 
 ```mjs
 import { styleText } from 'node:util';
-const errorMessage = styleText('red', 'Error! Error!');
-console.log(errorMessage);
+import { stderr } from 'node:process';
+
+const successMessage = styleText('green', 'Success!');
+console.log(successMessage);
+
+const errorMessage = styleText(
+  'red',
+  'Error! Error!',
+  // Validate if process.stderr has TTY
+  { stream: stderr },
+);
+console.error(successMessage);
 ```
 
 ```cjs
 const { styleText } = require('node:util');
-const errorMessage = styleText('red', 'Error! Error!');
-console.log(errorMessage);
+const { stderr } = require('node:process');
+
+const successMessage = styleText('green', 'Success!');
+console.log(successMessage);
+
+const errorMessage = styleText(
+  'red',
+  'Error! Error!',
+  // Validate if process.stderr has TTY
+  { stream: stderr },
+);
+console.error(successMessage);
 ```
 
 `util.inspect.colors` also provides text formats such as `italic`, and

lib/util.js

@@ -56,12 +56,25 @@ const {
 } = require('internal/util/inspect');
 const { debuglog } = require('internal/util/debuglog');
 const {
+  validateBoolean,
   validateFunction,
   validateNumber,
   validateString,
   validateOneOf,
 } = require('internal/validators');
+const {
+  isReadableStream,
+  isWritableStream,
+  isNodeStream,
+} = require('internal/streams/utils');
 const types = require('internal/util/types');
+
+let utilColors;
+function lazyUtilColors() {
+  utilColors ??= require('internal/util/colors');
+  return utilColors;
+}
+
 const binding = internalBinding('util');
 
 const {
@@ -92,10 +105,32 @@ function escapeStyleCode(code) {
 /**
  * @param {string | string[]} format
  * @param {string} text
+ * @param {object} [options={}]
+ * @param {boolean} [options.validateStream=true] - Whether to validate the stream.
+ * @param {Stream} [options.stream=process.stdout] - The output stream to write the styled text to.
  * @returns {string}
  */
-function styleText(format, text) {
+function styleText(format, text, { validateStream = true, stream = process.stdout } = {}) {
   validateString(text, 'text');
+  validateBoolean(validateStream, 'options.validateStream');
+
+  if (validateStream) {
+    if (
+      !isReadableStream(stream) &&
+      !isWritableStream(stream) &&
+      !isNodeStream(stream)
+    ) {
+      throw new ERR_INVALID_ARG_TYPE('stream', ['ReadableStream', 'WritableStream', 'Stream'], stream);
+    }
+
+    if (
+      !stream ||
+      !lazyUtilColors().shouldColorize(stream)
+    ) {
+      return text;
+    }
+  }
+
   if (ArrayIsArray(format)) {
     let left = '';
     let right = '';

test/parallel/test-util-styletext.js

@@ -1,7 +1,15 @@
 'use strict';
-require('../common');
-const assert = require('assert');
-const util = require('util');
+
+const common = require('../common');
+const assert = require('node:assert');
+const util = require('node:util');
+const { WriteStream } = require('node:tty');
+
+const styled = '\u001b[31mtest\u001b[39m';
+const noChange = 'test';
+
+const fd = common.getTTYfd();
+const writeStream = new WriteStream(fd);
 
 [
   undefined,
@@ -41,3 +49,35 @@
 }, {
   code: 'ERR_INVALID_ARG_VALUE',
 });
+
+assert.throws(() => {
+  util.styleText('red', 'text', { stream: {} });
+}, {
+  code: 'ERR_INVALID_ARG_TYPE',
+});
+
+// does not throw
+util.styleText('red', 'text', { stream: {}, validateStream: false });
+
+assert.strictEqual(util.styleText('red', 'test'), styled);
+
+const originalEnv = process.env;
+[
+  { isTTY: true, env: {}, expected: styled },
+  { isTTY: false, env: {}, expected: noChange },
+  { isTTY: true, env: { NODE_DISABLE_COLORS: '1' }, expected: noChange },
+  { isTTY: true, env: { NO_COLOR: '1' }, expected: noChange },
+  { isTTY: true, env: { FORCE_COLOR: '1' }, expected: styled },
+  { isTTY: true, env: { FORCE_COLOR: '1', NODE_DISABLE_COLORS: '1' }, expected: styled },
+  { isTTY: false, env: { FORCE_COLOR: '1', NO_COLOR: '1', NODE_DISABLE_COLORS: '1' }, expected: styled },
+  { isTTY: true, env: { FORCE_COLOR: '1', NO_COLOR: '1', NODE_DISABLE_COLORS: '1' }, expected: styled },
+].forEach((testCase) => {
+  writeStream.isTTY = testCase.isTTY;
+  process.env = {
+    ...process.env,
+    ...testCase.env
+  };
+  const output = util.styleText('red', 'test', { stream: writeStream });
+  assert.strictEqual(output, testCase.expected);
+  process.env = originalEnv;
+});