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: https://github.com/nodejs/node/pull/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>

1 files changed, 30 insertions, 0 deletions

diff --git a/doc/api/tty.md b/doc/api/tty.md
index 26761442a50..12a34b14eb7 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