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 <anna@addaleax.net> Reviewed-By: Weijia Wang <starkwang@126.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>

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;
+
 let OSRelease;
 
 const COLORS_2 = 1;
@@ -148,6 +153,23 @@ function getColorDepth(env = process.env) {
  return COLORS_2;
 }
 
+function hasColors(count, env) {
+ if (env === undefined &&
+ (count === undefined || typeof count === 'object' && count !== null)) {
+ env = count;
+ count = 16;
+ } else {
+ if (typeof count !== 'number') {
+ throw new ERR_INVALID_ARG_TYPE('count', 'number', count);
+ }
+ if (count < 2) {
+ throw new ERR_OUT_OF_RANGE('count', '>= 2', count);
+ }
+ }
+ return count <= 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');
 const errors = 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.
 let readline;
@@ -110,6 +113,8 @@ WriteStream.prototype.isTTY = true;
 
 WriteStream.prototype.getColorDepth = getColorDepth;
 
+WriteStream.prototype.hasColors = hasColors;
+
 WriteStream.prototype._refreshSize = function() {
  const oldCols = this.columns;
  const oldRows = this.rows;

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);
  const depth = writeStream.getColorDepth();
  assert.strictEqual(typeof depth, 'number');
  assert(depth >= 1 && depth <= 24);
+
+ const support = 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}`
  );
+ const colors = 2 ** actual;
+ assert(writeStream.hasColors(colors, env));
+ assert(!writeStream.hasColors(colors + 1, env));
+ assert(depth >= 4 ? writeStream.hasColors(env) : !writeStream.hasColors(env));
 });
 
 // OS settings