From 42af1e0a2e2203bec6b6180d81be9ee3246dcb7c Mon Sep 17 00:00:00 2001
From: Ruben Bridgewater <ruben@bridgewater.de>
Date: Sat, 19 Jan 2019 15:37:38 +0100
Subject: [PATCH] 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.
---
 doc/api/tty.md                                | 30 +++++++++++++++++++
 lib/internal/tty.js                           | 24 ++++++++++++++-
 lib/tty.js                                    |  7 ++++-
 ...lor-depth.js => test-tty-color-support.js} | 22 ++++++++++++++
 ...r-depth.out => test-tty-color-support.out} |  0
 5 files changed, 81 insertions(+), 2 deletions(-)
 rename test/pseudo-tty/{test-tty-get-color-depth.js => test-tty-color-support.js} (77%)
 rename test/pseudo-tty/{test-tty-get-color-depth.out => test-tty-color-support.out} (100%)

diff --git a/doc/api/tty.md b/doc/api/tty.md
index 26761442a50865..12a34b14eb7cc0 100644
--- a/doc/api/tty.md
+++ b/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
diff --git a/lib/internal/tty.js b/lib/internal/tty.js
index 45f278d542c107..486dbbeaa508d3 100644
--- a/lib/internal/tty.js
+++ b/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;
@@ -151,6 +156,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
 };
diff --git a/lib/tty.js b/lib/tty.js
index 6efaac6e43215f..bc568146fd2acb 100644
--- a/lib/tty.js
+++ b/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;
@@ -109,6 +112,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;
diff --git a/test/pseudo-tty/test-tty-get-color-depth.js b/test/pseudo-tty/test-tty-color-support.js
similarity index 77%
rename from test/pseudo-tty/test-tty-get-color-depth.js
rename to test/pseudo-tty/test-tty-color-support.js
index 14151ec3fb2f01..b5bc3aca247417 100644
--- a/test/pseudo-tty/test-tty-get-color-depth.js
+++ b/test/pseudo-tty/test-tty-color-support.js
@@ -12,8 +12,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],
@@ -54,6 +72,10 @@ const writeStream = new WriteStream(fd);
     `i: ${i}, expected: ${depth}, ` +
       `actual: ${actual}, env: ${inspect(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
diff --git a/test/pseudo-tty/test-tty-get-color-depth.out b/test/pseudo-tty/test-tty-color-support.out
similarity index 100%
rename from test/pseudo-tty/test-tty-get-color-depth.out
rename to test/pseudo-tty/test-tty-color-support.out