tty: add hasColors function

This adds a small wrapper around the `getColorDepth` function to check if the stream supports at least a specific amount of colors. This is convenient as the other API is not as straight forward and most use cases likely only want to know if a specific amount of colors is supported or not. PR-URL: #26247 Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Weijia Wang <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sakthipriyan Vairamani <[email protected]>

Author: BridgeAR

doc/api/tty.md

@@ -176,6 +176,35 @@ corresponding to this `WriteStream`. The array is of the type
 `[numColumns, numRows]` where `numColumns` and `numRows` represent the number
 of columns and rows in the corresponding [TTY](tty.html).
 
+### writeStream.hasColors([count][, env])
+<!-- YAML
+added: REPLACEME
+-->
+
+*`count`{integer} The number of colors that are requested (minimum 2).
+**Default:** 16.
+*`env`{Object} An object containing the environment variables to check. This
+ enables simulating the usage of a specific terminal. **Default:**
+`process.env`.
+* Returns:{boolean}
+
+Returns `true` if the `writeStream` supports at least as many colors as provided
+in `count`. Minimum support is 2 (black and white).
+
+This has the same false positives and negatives as described in
+[`writeStream.getColorDepth()`][].
+
+```js
+process.stdout.hasColors();
+// Returns true or false depending on if `stdout` supports at least 16 colors.
+process.stdout.hasColors(256);
+// Returns true or false depending on if `stdout` supports at least 256 colors.
+process.stdout.hasColors({TMUX:'1' });
+// Returns true.
+process.stdout.hasColors(2**24,{TMUX:'1' });
+// Returns false (the environment setting pretends to support 2 ** 8 colors).
+```
+
 ### writeStream.isTTY
 <!-- YAML
 added: v0.5.8
@@ -217,3 +246,4 @@ integer.
 [`process.stderr`]: process.html#process_process_stderr
 [`process.stdin`]: process.html#process_process_stdin
 [`process.stdout`]: process.html#process_process_stdout
+[`writeStream.getColorDepth()`]: #tty_writestream_getcolordepth_env

lib/internal/tty.js

@@ -22,6 +22,11 @@
 
 'use strict';
 
+const{
+ERR_INVALID_ARG_TYPE,
+ERR_OUT_OF_RANGE
+}=require('internal/errors').codes;
+
 letOSRelease;
 
 constCOLORS_2=1;
@@ -148,6 +153,23 @@ function getColorDepth(env = process.env){
 returnCOLORS_2;
 }
 
+functionhasColors(count,env){
+if(env===undefined&&
+(count===undefined||typeofcount==='object'&&count!==null)){
+env=count;
+count=16;
+}else{
+if(typeofcount!=='number'){
+thrownewERR_INVALID_ARG_TYPE('count','number',count);
+}
+if(count<2){
+thrownewERR_OUT_OF_RANGE('count','>= 2',count);
+}
+}
+returncount<=2**getColorDepth(env);
+}
+
 module.exports={
- getColorDepth
+ getColorDepth,
+ hasColors
 };

lib/tty.js

@@ -26,7 +26,10 @@ const net = require('net');
 const{TTY, isTTY }=internalBinding('tty_wrap');
 consterrors=require('internal/errors');
 const{ERR_INVALID_FD,ERR_TTY_INIT_FAILED}=errors.codes;
-const{ getColorDepth }=require('internal/tty');
+const{
+ getColorDepth,
+ hasColors
+}=require('internal/tty');
 
 // Lazy loaded for startup performance.
 letreadline;
@@ -110,6 +113,8 @@ WriteStream.prototype.isTTY = true;
 
 WriteStream.prototype.getColorDepth=getColorDepth;
 
+WriteStream.prototype.hasColors=hasColors;
+
 WriteStream.prototype._refreshSize=function(){
 constoldCols=this.columns;
 constoldRows=this.rows;

…t/pseudo-tty/test-tty-get-color-depth.js test/pseudo-tty/test-tty-color-support.jstest/pseudo-tty/test-tty-get-color-depth.js renamed to test/pseudo-tty/test-tty-color-support.js test/pseudo-tty/test-tty-get-color-depth.js renamed to test/pseudo-tty/test-tty-color-support.js

@@ -11,8 +11,26 @@ const writeStream = new WriteStream(fd);
 constdepth=writeStream.getColorDepth();
 assert.strictEqual(typeofdepth,'number');
 assert(depth>=1&&depth<=24);
+
+constsupport=writeStream.hasColors();
+assert.strictEqual(support,depth!==1);
 }
 
+// Validate invalid input.
+[true,null,()=>{},Symbol(),5n].forEach((input)=>{
+assert.throws(
+()=>writeStream.hasColors(input),
+{code: 'ERR_INVALID_ARG_TYPE'}
+);
+});
+
+[-1,1].forEach((input)=>{
+assert.throws(
+()=>writeStream.hasColors(input),
+{code: 'ERR_OUT_OF_RANGE'}
+);
+});
+
 // Check different environment variables.
 [
 [{COLORTERM: '1'},4],
@@ -48,6 +66,10 @@ const writeStream = new WriteStream(fd);
 depth,
 `i: ${i}, expected: ${depth}, actual: ${actual}, env: ${env}`
 );
+constcolors=2**actual;
+assert(writeStream.hasColors(colors,env));
+assert(!writeStream.hasColors(colors+1,env));
+assert(depth>=4 ? writeStream.hasColors(env) : !writeStream.hasColors(env));
 });
 
 // OS settings