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.
PR-URL: #54389Fixes: #54365
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Claudio Wunder <cwunder@gnome.org>
Reviewed-By: Rich Trott <rtrott@gmail.com>

Author: RafaelGSS

doc/api/util.md

@@ -1798,30 +1798,61 @@ console.log(util.stripVTControlCharacters('\u001B[4mvalue\u001B[0m'));
 // Prints "value"
 ```
 
-## `util.styleText(format, text)`
+## `util.styleText(format, text[, options])`
 
 > Stability: 1.1 - Active development
 
 <!-- YAML
 added: v20.12.0
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/54389
+ description: Respect isTTY and 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';
-consterrorMessage=styleText('red', 'Error! Error!');
-console.log(errorMessage);
+import { stderr } from'node:process';
+
+constsuccessMessage=styleText('green', 'Success!');
+console.log(successMessage);
+
+consterrorMessage=styleText(
+'red',
+'Error! Error!',
+// Validate if process.stderr has TTY
+ { stream: stderr },
+);
+console.error(successMessage);
 ```
 
 ```cjs
 const { styleText } =require('node:util');
-consterrorMessage=styleText('red', 'Error! Error!');
-console.log(errorMessage);
+const { stderr } =require('node:process');
+
+constsuccessMessage=styleText('green', 'Success!');
+console.log(successMessage);
+
+consterrorMessage=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

@@ -65,13 +65,26 @@ const {
 }=require('internal/util/inspect');
 const{ debuglog }=require('internal/util/debuglog');
 const{
+ validateBoolean,
  validateFunction,
  validateNumber,
  validateString,
  validateOneOf,
 }=require('internal/validators');
 const{ isBuffer }=require('buffer').Buffer;
+const{
+ isReadableStream,
+ isWritableStream,
+ isNodeStream,
+}=require('internal/streams/utils');
 consttypes=require('internal/util/types');
+
+letutilColors;
+functionlazyUtilColors(){
+utilColors??=require('internal/util/colors');
+returnutilColors;
+}
+
 constbinding=internalBinding('util');
 
 const{
@@ -209,10 +222,25 @@ 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 stream used for validation.
  * @returns {string}
  */
-functionstyleText(format,text){
+functionstyleText(format,text,{ validateStream =true, stream =process.stdout}={}){
 validateString(text,'text');
+validateBoolean(validateStream,'options.validateStream');
+
+if(validateStream){
+if(
+!isReadableStream(stream)&&
+!isWritableStream(stream)&&
+!isNodeStream(stream)
+){
+thrownewERR_INVALID_ARG_TYPE('stream',['ReadableStream','WritableStream','Stream'],stream);
+}
+}
+
 if(ArrayIsArray(format)){
 letleft='';
 letright='';
@@ -232,6 +260,18 @@ function styleText(format, text) {
 if(formatCodes==null){
 validateOneOf(format,'format',ObjectKeys(inspect.colors));
 }
+
+// Check colorize only after validating arg type and value
+if(
+validateStream&&
+(
+!stream||
+!lazyUtilColors().shouldColorize(stream)
+)
+){
+returntext;
+}
+
 return`${escapeStyleCode(formatCodes[0])}${text}${escapeStyleCode(formatCodes[1])}`;
 }
 

test/parallel/test-bootstrap-modules.js

@@ -43,6 +43,7 @@ expected.beforePreExec = new Set([
 'NativeModule internal/assert',
 'NativeModule internal/util/inspect',
 'NativeModule internal/util/debuglog',
+'NativeModule internal/streams/utils',
 'NativeModule internal/timers',
 'NativeModule events',
 'Internal Binding buffer',

test/parallel/test-util-styletext.js

@@ -1,7 +1,12 @@
 'use strict';
-require('../common');
-constassert=require('assert');
-constutil=require('util');
+
+constcommon=require('../common');
+constassert=require('node:assert');
+constutil=require('node:util');
+const{ WriteStream }=require('node:tty');
+
+conststyled='\u001b[31mtest\u001b[39m';
+constnoChange='test';
 
 [
 undefined,
@@ -31,13 +36,69 @@ assert.throws(() => {
 code: 'ERR_INVALID_ARG_VALUE',
 });
 
-assert.strictEqual(util.styleText('red','test'),'\u001b[31mtest\u001b[39m');
+assert.strictEqual(
+util.styleText('red','test',{validateStream: false}),
+'\u001b[31mtest\u001b[39m',
+);
+
+assert.strictEqual(
+util.styleText(['bold','red'],'test',{validateStream: false}),
+'\u001b[1m\u001b[31mtest\u001b[39m\u001b[22m',
+);
 
-assert.strictEqual(util.styleText(['bold','red'],'test'),'\u001b[1m\u001b[31mtest\u001b[39m\u001b[22m');
-assert.strictEqual(util.styleText(['bold','red'],'test'),util.styleText('bold',util.styleText('red','test')));
+assert.strictEqual(
+util.styleText(['bold','red'],'test',{validateStream: false}),
+util.styleText(
+'bold',
+util.styleText('red','test',{validateStream: false}),
+{validateStream: false},
+),
+);
 
 assert.throws(()=>{
 util.styleText(['invalid'],'text');
 },{
 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',{validateStream: false}),
+styled,
+);
+
+constfd=common.getTTYfd();
+if(fd!==-1){
+constwriteStream=newWriteStream(fd);
+
+constoriginalEnv=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
+};
+constoutput=util.styleText('red','test',{stream: writeStream});
+assert.strictEqual(output,testCase.expected);
+process.env=originalEnv;
+});
+}else{
+common.skip('Could not create TTY fd');
+}