util: colorize text with hex colors

PR-URL: #61556
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Jordan Harband <ljharb@gmail.com>
Reviewed-By: René <contact.9a5d6388@renegade334.me.uk>
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Claudio Wunder <cwunder@gnome.org>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: araujogui

benchmark/util/style-text.js

@@ -7,7 +7,7 @@ const assert = require('node:assert');
 
 constbench=common.createBenchmark(main,{
 messageType: ['string','number','boolean','invalid'],
-format: ['red','italic','invalid'],
+format: ['red','italic','invalid','#ff0000'],
 validateStream: [1,0],
 n: [1e3],
 });

doc/api/util.md

@@ -2520,6 +2520,9 @@ added:
  - v21.7.0
  - v20.12.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/61556
+ description: Add support for hexadecimal colors.
  - version: v24.2.0
  pr-url: https://github.com/nodejs/node/pull/58437
  description: Added the `'none'` format as a non-op format.
@@ -2537,7 +2540,8 @@ changes:
 -->
 
 * `format` {string | Array} A text format or an Array
- of text formats defined in `util.inspect.colors`.
+ of text formats defined in `util.inspect.colors`, or a hex color in `#RGB`
+ or `#RRGGBB` form.
 * `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`.
@@ -2600,6 +2604,30 @@ console.log(
 
 The special format value `none` applies no additional styling to the text.
 
+In addition to predefined color names, `util.styleText()` supports hex color
+strings using ANSI TrueColor (24-bit) escape sequences. Hex colors can be
+specified in either 3-digit (`#RGB`) or 6-digit (`#RRGGBB`) format:
+
+```mjs
+import { styleText } from'node:util';
+
+// 6-digit hex color
+console.log(styleText('#ff5733', 'Orange text'));
+
+// 3-digit hex color (shorthand)
+console.log(styleText('#f00', 'Red text'));
+```
+
+```cjs
+const { styleText } =require('node:util');
+
+// 6-digit hex color
+console.log(styleText('#ff5733', 'Orange text'));
+
+// 3-digit hex color (shorthand)
+console.log(styleText('#f00', 'Red text'));
+```
+
 The full list of formats can be found in [modifiers][].
 
 ## Class: `util.TextDecoder`

lib/util.js

@@ -37,6 +37,8 @@ const {
  ObjectSetPrototypeOf,
  ObjectValues,
  ReflectApply,
+ RegExpPrototypeExec,
+ StringPrototypeSlice,
  StringPrototypeToWellFormed,
 }=primordials;
 
@@ -46,10 +48,12 @@ const {
 codes: {
 ERR_FALSY_VALUE_REJECTION,
 ERR_INVALID_ARG_TYPE,
+ERR_INVALID_ARG_VALUE,
 ERR_OUT_OF_RANGE,
 },
  isErrorStackTraceLimitWritable,
 }=require('internal/errors');
+const{ Buffer }=require('buffer');
 const{
  format,
  formatWithOptions,
@@ -156,6 +160,51 @@ function replaceCloseCode(str, closeSeq, openSeq, keepClose) {
 returnresult+str.slice(lastIndex);
 }
 
+// Matches #RGB or #RRGGBB
+consthexColorRegExp=/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+
+/**
+ * Validates whether a string is a valid hex color code.
+ * @param {string} hex The hex string to validate (e.g., '#fff' or '#ffffff')
+ * @returns {boolean} True if valid hex color, false otherwise
+ */
+functionisValidHexColor(hex){
+returntypeofhex==='string'&&RegExpPrototypeExec(hexColorRegExp,hex)!==null;
+}
+
+/**
+ * Parses a hex color string into RGB components.
+ * Supports both 3-digit (#RGB) and 6-digit (#RRGGBB) formats.
+ * @param {string} hex A valid hex color string
+ * @returns {Buffer} The RGB components
+ */
+functionhexToRgb(hex){
+// Normalize to 6 digits
+lethexStr;
+if(hex.length===4){
+// Expand #RGB to #RRGGBB
+hexStr=hex[1]+hex[1]+hex[2]+hex[2]+hex[3]+hex[3];
+}elseif(hex.length===7){
+hexStr=StringPrototypeSlice(hex,1);
+}else{
+thrownewERR_OUT_OF_RANGE('hex','#RGB or #RRGGBB',hex);
+}
+
+// TODO(araujogui): use Uint8Array.fromHex
+returnBuffer.from(hexStr,'hex');
+}
+
+/**
+ * Generates the ANSI TrueColor (24-bit) escape sequence for a foreground color.
+ * @param {number} r Red component (0-255)
+ * @param {number} g Green component (0-255)
+ * @param {number} b Blue component (0-255)
+ * @returns {string} The ANSI escape sequence
+ */
+functionrgbToAnsi24Bit(r,g,b){
+return`38;2;${r};${g};${b}`;
+}
+
 /**
  * @param {string | string[]} format
  * @param {string} text
@@ -205,8 +254,25 @@ function styleText(format, text, options) {
 
 for(constkeyofformatArray){
 if(key==='none')continue;
+
+if(isValidHexColor(key)){
+if(skipColorize)continue;
+const{0: r,1: g,2: b}=hexToRgb(key);
+constopenSeq=kEscape+rgbToAnsi24Bit(r,g,b)+kEscapeEnd;
+constcloseSeq=kEscape+'39'+kEscapeEnd;
+openCodes+=openSeq;
+closeCodes=closeSeq+closeCodes;
+processedText=replaceCloseCode(processedText,closeSeq,openSeq,false);
+continue;
+}
+
 conststyle=cache[key];
 if(style===undefined){
+// Check if it looks like an invalid hex color (starts with #)
+if(typeofkey==='string'&&key[0]==='#'){
+thrownewERR_INVALID_ARG_VALUE('format',key,
+'must be a valid hex color (#RGB or #RRGGBB)');
+}
 validateOneOf(key,'format',ObjectGetOwnPropertyNames(inspect.colors));
 }
 openCodes+=style.openSeq;