tty: add getColorDepth function

Right now it is very difficult to determine if a terminal supports
colors or not. This function adds this functionality by detecting
environment variables and checking process.

PR-URL: https://github.com/nodejs/node/pull/17615
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

1 files changed, 26 insertions, 0 deletions

diff --git a/doc/api/tty.md b/doc/api/tty.md
index 8b757c0f02..ce6dbae8fa 100644
--- a/doc/api/tty.md
+++ b/doc/api/tty.md
@@ -121,6 +121,32 @@ added: v0.7.7
 A `number` specifying the number of rows the TTY currently has. This property
 is updated whenever the `'resize'` event is emitted.
 
+### writeStream.getColorDepth([env])
+<!-- YAML
+added: REPLACEME
+-->
+
+* `env` {object} A object containing the environment variables to check.
+  Defaults to `process.env`.
+* Returns: {number}
+
+Returns:
+* 1 for 2,
+* 4 for 16,
+* 8 for 256,
+* 24 for 16,777,216
+colors supported.
+
+Use this to determine what colors the terminal supports. Due to the nature of
+colors in terminals it is possible to either have false positives or false
+negatives. It depends on process information and the environment variables that
+may lie about what terminal is used.
+To enforce a specific behavior without relying on `process.env` it is possible
+to pass in an object with different settings.
+
+Use the `NODE_DISABLE_COLORS` environment variable to enforce this function to
+always return 1.
+
 ## tty.isatty(fd)
 <!-- YAML
 added: v0.5.8