feat: add readonly level property to get the detected color support level

Author: webdiscus

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.1.0 (2025-05-28)
+
+- feat: add readonly `level` property to get the detected color support level:
+  - 0 - no colors,
+  - 1 - 16 colors,
+  - 2 - 256 colors,
+  - 3 - truecolor.
+
+## 4.0.0 (2025-05-08)
+
+Release v4.
+
 ## Pre release note: ✨ Ansis v4 - Smaller package, and cleaner API
 
 Ansis v4 drops legacy baggage and unused artifacts.

README.md

@@ -878,26 +878,34 @@ Execute the script in a terminal:
 
 Ansis automatically detects the supported color level:
 
-- Truecolor
-- ANSI 256 colors
-- ANSI 16 colors
-- black & white (no colors)
+- `0` – No color (black & white)
+- `1` – Basic ANSI (16 colors)
+- `2` – Extended ANSI (256 colors)
+- `3` – Truecolor (24-bit RGB)
 
-Ansis has the method `isSupported()` that returns a `boolean` value whether the output supports ANSI color and styles.
+You can access the detected color level via the readonly `level` property:
 
 ```js
 import ansis from 'ansis';
 
-console.log('Color output: ', ansis.isSupported());
+console.log('Detected color level: ', ansis.level);
 ```
 
-There is no standard way to detect terminal color support.
-The most common method is to check the `TERM` and `COLORTERM` environment variables, which often indicate the supported color level.
+To check if ANSI color output is supported, use the `isSupported()` method:
+
+```js
+import ansis from 'ansis';
+
+console.log('Color output supported:', ansis.isSupported());
+```
+
+> [!NOTE]
+> There is no standard way to detect terminal color support.
+> The most common method is to check the `TERM` and `COLORTERM` environment variables, which often indicate the supported color level.
 
 Most standard CI systems can be identified by the presence of the  `CI` environment variable.
 While some CI uses their own specific environment variables, they are inconsistent and not widely adopted.
 
-
 Ansis provides basic support for standard CI environments by checking the commonly used `CI` environment variable.
 In such cases, Ansis assumes support for at least 16 colors.
 If your code uses 256-color or truecolor, Ansis automatically [fallback](#fallback) to 16 colors, or to black and white if no color support is detected.

README.npm-node10.md

@@ -1,6 +1,6 @@
 # Ansis
 
-ANSI color library – special version for Node.js 10+.
+ANSI color library – special build for Node.js 10+.
 
 [Documentation](../../)
 

bench/index.js

@@ -40,21 +40,20 @@ import picocolors from 'picocolors';
 import { Ansis, cyan, green, red, yellow, hex, rgb } from 'ansis';
 
 import spectrum from '../examples/fixtures/spectrum.js';
-import { getLevel } from '../src/color-support.js';
 import { colorLevels, LEVEL_TRUECOLOR } from '../src/color-levels.js';
 
 import packages from './packages.js';
 
 // create a new instance of Ansis for correct measure in benchmark
 const ansis = new Ansis();
-const colorSpace = getLevel();
+const colorLevel = ansis.level;
 
 const log = console.log;
 
 log();
-log(cyan.inverse` Colors `, `Your terminal supports ${cyan(colorLevels[colorSpace])}.`);
+log(cyan.inverse` Colors `, `Your terminal supports ${cyan(colorLevels[colorLevel])}.`);
 
-if (colorSpace < LEVEL_TRUECOLOR) {
+if (colorLevel < LEVEL_TRUECOLOR) {
   log(red.inverse` WARNING `, yellow`Your terminal doesn't support Truecolor!`);
   log('The result of some tests can be NOT correct!\nChoose a modern terminal, e.g. iTerm.\n');
 }

bench/lib/bench.js

@@ -1,5 +1,5 @@
 import Benchmark from 'benchmark';
-import { Ansis } from '../../src/index.js';
+import { Ansis } from 'ansis';
 
 const benchStyle = new Ansis();
 

bench/package.json

@@ -11,7 +11,7 @@
   "dependencies": {
     "@colors/colors": "1.6.0",
     "ansi-colors": "4.1.3",
-    "ansis": "file:../dist",
+    "ansis": "file:../dist/node14",
     "benchmark": "2.1.4",
     "chalk": "5.4.1",
     "cli-color": "2.0.4",
@@ -21,6 +21,6 @@
     "kleur": "4.1.5",
     "kolorist": "1.8.0",
     "picocolors": "1.1.1",
-    "vitest": "^3.0.8"
+    "vitest": "^3.1.4"
   }
 }

bench/truecolor.bench.js

@@ -5,19 +5,18 @@ import Bench from './lib/bench.js';
 import chalk from 'chalk';
 import { Ansis, cyan, green, red, yellow, hex } from 'ansis';
 
-import { getLevel } from '../src/color-support.js';
 import { colorLevels, LEVEL_TRUECOLOR } from '../src/color-levels.js';
 
 const log = console.log;
 
 // create a new instance of Ansis for correct measure in benchmark
-const truecolorBench = new Ansis();
-const colorSpace = getLevel();
+const ansis = new Ansis();
+const colorLevel = ansis.level;
 
 log();
-log(cyan.inverse` Colors `, `Your terminal supports ${cyan(colorLevels[colorSpace])}.`);
+log(cyan.inverse` Colors `, `Your terminal supports ${cyan(colorLevels[colorLevel])}.`);
 
-if (colorSpace < LEVEL_TRUECOLOR) {
+if (colorLevel < LEVEL_TRUECOLOR) {
   log(red.inverse` WARNING `, yellow`Your terminal doesn't support Truecolor!`);
   log('The result of some tests can be NOT correct!\nChoose a modern terminal, e.g. iTerm.\n');
 }
@@ -38,12 +37,12 @@ log(hex('#F88').inverse.bold` -= Benchmark =- `);
 
 bench('RGB colors').
   add('chalk', () => chalk.rgb(99, 150, 200)('foo')).
-  add('ansis', () => truecolorBench.rgb(99, 150, 200)('foo')).
+  add('ansis', () => ansis.rgb(99, 150, 200)('foo')).
   run();
 
 bench('HEX colors').
   add('chalk #FBA', () => chalk.hex('#FBA')('foo')).
-  add('ansis #FBA', () => truecolorBench.hex('#FBA')('foo')).
+  add('ansis #FBA', () => ansis.hex('#FBA')('foo')).
   add('chalk #FBA123', () => chalk.hex('#FBA123')('foo')).
-  add('ansis #FBA123', () => truecolorBench.hex('#FBA123')('foo')).
+  add('ansis #FBA123', () => ansis.hex('#FBA123')('foo')).
   run();

compare/package.json

@@ -9,7 +9,7 @@
   "dependencies": {
     "@colors/colors": "1.6.0",
     "ansi-colors": "4.1.3",
-    "ansis": "file:../dist",
+    "ansis": "file:../dist/node14",
     "chalk": "5.3.0",
     "cli-color": "2.0.4",
     "colors": "1.4.0",
@@ -23,4 +23,4 @@
     "webpack": "^5.98.0",
     "webpack-cli": "^6.0.1"
   }
-}
+}

examples/package.json

@@ -7,4 +7,4 @@
     "spectrum": "node ./spectrum.js",
     "stylex": "node ./StyleX.js"
   }
-}
+}

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ansis",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "A small and fast ANSI color library",
   "keywords": [
     "ansi",

package.npm-node10.json

@@ -1,6 +1,6 @@
 {
 "name":"ansis",
-"version":"4.0.0-node10",
+"version":"4.1.0-node10",
 "description":"ANSI color lib",
 "keywords":["ansi","colors","cli"],
 "license":"ISC",

package.npm-node14.json

@@ -1,6 +1,6 @@
 {
 "name":"ansis",
-"version":"4.0.0",
+"version":"4.1.0",
 "description":"ANSI color lib",
 "keywords":["ansi","colors","cli"],
 "license":"ISC",