lib: respect terminal capabilities on styleText

This PR changes styleText API to respect terminal capabilities and environment variables such as NO_COLOR, NODE_DISABLE_COLORS, and FORCE_COLOR.
nodejs-github-bot · Aug 28, 2024 · Aug 14, 2024 · Aug 14, 2024 · Aug 16, 2024 · Aug 20, 2024
commit 9e3ada17fcf2988f32525824bb496d39f0a398e1
diff --git a/doc/api/util.md b/doc/api/util.md
@@ -1810,13 +1810,24 @@ 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/54388
+    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}
 ## `util.styleText(format, text)` 
 ## `util.styleText(format, text)` 
+  * `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';

diff --git a/lib/util.js b/lib/util.js
@@ -62,6 +62,13 @@ const {
   validateOneOf,
 } = require('internal/validators');
 const types = require('internal/util/types');
+
+let utilColors;
+function lazyUtilColors() {
+  utilColors ??= require('internal/util/colors');
+  return utilColors;
+}
+
 const binding = internalBinding('util');
 
 const {
@@ -92,10 +99,23 @@ 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');
+
+  if (validateStream) {
+    if (
+      !stream ||
+      !lazyUtilColors().shouldColorize(stream)
+    ) {
+      return text;
+    }
+  }
+
   if (ArrayIsArray(format)) {
     let left = '';
     let right = '';

diff --git a/test/parallel/test-util-styletext.js b/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,26 @@ assert.throws(() => {
 }, {
   code: 'ERR_INVALID_ARG_VALUE',
 });
+
+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;
+});