util: create hex style cache and fast path

Signed-off-by: Guilherme Araújo <arauujogui@gmail.com>
PR-URL: #62999
Reviewed-By: Gürgün Dayıoğlu <hey@gurgun.day>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Ethan Arrowood <ethan@arrowood.dev>

Author: araujogui

benchmark/util/style-text.js

@@ -5,9 +5,22 @@ const common = require('../common.js');
 const{ styleText }=require('node:util');
 constassert=require('node:assert');
 
+// 1000 distinct hex colors to exercise the cache under high-miss conditions.
+// Spread evenly across hue space so colors are valid and maximally varied.
+constkHexColorCount=1000;
+consttoHex=(n)=>n.toString(16).padStart(2,'0');
+consthexColors=Array.from({length: kHexColorCount},(_,i)=>{
+constr=(i*37)&0xff;
+constg=(i*73)&0xff;
+constb=(i*137)&0xff;
+return`#${toHex(r)}${toHex(g)}${toHex(b)}`;
+});
+
 constbench=common.createBenchmark(main,{
 messageType: ['string','number','boolean','invalid'],
-format: ['red','italic','invalid','#ff0000'],
+// '#rotating' cycles through kHexColorCount distinct colors to simulate
+// the high-miss-rate / large-cache scenario (e.g. user-randomised colors).
+format: ['red','italic','invalid','#ff0000','#rotating'],
 validateStream: [1,0],
 n: [1e3],
 });
@@ -31,9 +44,10 @@ function main({ messageType, format, validateStream, n }) {
 
 bench.start();
 for(leti=0;i<n;i++){
+constfmt=format==='#rotating' ? hexColors[i%kHexColorCount] : format;
 letcolored='';
 try{
-colored=styleText(format,str,{ validateStream });
+colored=styleText(fmt,str,{ validateStream });
 assert.ok(colored);// Attempt to avoid dead-code elimination
 }catch{
 // eslint-disable no-empty

lib/util.js

@@ -38,6 +38,7 @@ const {
  ObjectValues,
  ReflectApply,
  RegExpPrototypeExec,
+ SafeMap,
  StringPrototypeSlice,
  StringPrototypeToWellFormed,
 }=primordials;
@@ -114,8 +115,20 @@ const kEscapeEnd = 'm';
 constkDimCode=2;
 constkBoldCode=1;
 
+// Close sequence for 24-bit foreground colors (reset to default foreground)
+constkHexCloseSeq=kEscape+'39'+kEscapeEnd;
+
 letstyleCache;
 
+constkHexStyleCacheMax=256;
+
+lethexStyleCache;
+
+functiongetHexStyleCache(){
+hexStyleCache??=newSafeMap();
+returnhexStyleCache;
+}
+
 functiongetStyleCache(){
 if(styleCache===undefined){
 styleCache={__proto__: null};
@@ -137,6 +150,28 @@ function getStyleCache() {
 returnstyleCache;
 }
 
+/**
+ * Returns the cached ANSI escape sequences for a hex color.
+ * Computes and caches on first use to avoid repeated Buffer allocations.
+ * @param {string} hex A valid hex color string (#RGB or #RRGGBB)
+ * @returns {{openSeq: string, closeSeq: string}}
+ */
+functiongetHexStyle(hex){
+constcache=getHexStyleCache();
+constcached=cache.get(hex);
+if(cached!==undefined)returncached;
+const{0: r,1: g,2: b}=hexToRgb(hex);
+conststyle={
+__proto__: null,
+openSeq: kEscape+rgbToAnsi24Bit(r,g,b)+kEscapeEnd,
+closeSeq: kHexCloseSeq,
+};
+if(cache.size>=kHexStyleCacheMax)
+cache.delete(cache.keys().next().value);
+cache.set(hex,style);
+returnstyle;
+}
+
 functionreplaceCloseCode(str,closeSeq,openSeq,keepClose){
 constcloseLen=closeSeq.length;
 letindex=str.indexOf(closeSeq);
@@ -163,15 +198,6 @@ function replaceCloseCode(str, closeSeq, openSeq, keepClose) {
 // 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.
@@ -225,6 +251,17 @@ function styleText(format, text, options) {
 constprocessed=replaceCloseCode(text,style.closeSeq,style.openSeq,style.keepClose);
 returnstyle.openSeq+processed+style.closeSeq;
 }
+
+if(format[0]==='#'){
+lethexStyle=getHexStyleCache().get(format);
+if(hexStyle===undefined&&RegExpPrototypeExec(hexColorRegExp,format)!==null){
+hexStyle=getHexStyle(format);
+}
+if(hexStyle!==undefined){
+constprocessed=replaceCloseCode(text,hexStyle.closeSeq,hexStyle.openSeq,false);
+returnhexStyle.openSeq+processed+hexStyle.closeSeq;
+}
+}
 }
 
 validateString(text,'text');
@@ -255,24 +292,26 @@ 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);
+if(typeofkey==='string'&&key[0]==='#'){
+lethexStyle=getHexStyleCache().get(key);
+if(hexStyle===undefined){
+if(RegExpPrototypeExec(hexColorRegExp,key)===null){
+thrownewERR_INVALID_ARG_VALUE('format',key,
+'must be a valid hex color (#RGB or #RRGGBB)');
+}
+if(skipColorize)continue;
+hexStyle=getHexStyle(key);
+}elseif(skipColorize){
+continue;
+}
+openCodes+=hexStyle.openSeq;
+closeCodes=hexStyle.closeSeq+closeCodes;
+processedText=replaceCloseCode(processedText,hexStyle.closeSeq,hexStyle.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;