chore: refactor code, update readme

Author: webdiscus

README.md

@@ -105,7 +105,7 @@ Both are [recommended](https://github.com/es-tooling/module-replacements/blob/ma
 The package size in `node_modules` directory:
 
 - `picocolors`: [6.37 kB][npm-picocolors] (not minimized) - A micro library with basic features.
-- `аnsis`: [5.76 kB][npm-ansis] (minimized) - A powerful library with a rich set of features.
+- `аnsis`: [5.71 kB][npm-ansis] (minimized) - A powerful library with a rich set of features.
 - `chalk`: [44.2 kB][npm-chalk] (not minimized) - Provides similar functionality to Ansis.
 
 ### ⚡ Performance
@@ -214,7 +214,7 @@ As of 2025, only **Ansis**, **Chalk**, and **Picocolors** are actively maintaine
   - ☑️ Picocolors: `CJS` only
   - ☑️ Chalk: `ESM` only
 - Does it matter the unpacked size?
-  - ✅ [Ansis - 5.76 kB][npm-ansis]
+  - ✅ [Ansis - 5.71 kB][npm-ansis]
   - ✅ [Picocolors - 6.37 kB][npm-picocolors]
   - ❌ [Chalk - 44.2 kB][npm-chalk]
 - Does it matter if a library performs [~60 million](#bench-simple) or [~100 million](#bench-simple) **ops/sec** when outputting to the terminal?
@@ -230,10 +230,6 @@ As of 2025, only **Ansis**, **Chalk**, and **Picocolors** are actively maintaine
   - ✅ Ansis
   - ☑️ Chalk
   - ❌ Picocolors
-- Does supporting a wide range of [environments](#color-support) matter?
-  - ✅ Ansis
-  - ✅ Chalk
-  - ❌ Picocolors
 - Does keeping your code clean and readable matter?
   - ✅ Ansis ([default and named import](#import), [chained syntax](#chained-syntax), [nested **template strings**](#nested-syntax))
   - ✅ Chalk (default import, chained syntax)
@@ -877,10 +873,20 @@ import ansis from 'ansis';
 console.log('Color output: ', ansis.isSupported());
 ```
 
-There is no standard way to detect which color level is supported.
-The most common way to detect color support is to check the `TERM` and `COLORTERM` environment variables.
-CI systems can be detected by checking for the existence of the `CI` and other specifically environment variables.
-Combine that with the knowledge about which operating system the program is running on, and we have a decent enough way to detect colors.
+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.
+
+> Ansis explicitly detects `GitHub Actions` as supporting `truecolor`, as most Ansis users rely on GitHub CI.
+
+Combined with information about the operating system, this approach provides a practical and lightweight method for detecting color support in most environments.
 
 | Terminal                         | ANSI 16<br>colors | ANSI 256<br>colors | True<br>Color |  env.<br>TERM   | env.<br>COLORTERM | Specifically ENV variables             |
 |:---------------------------------|-------------------|:-------------------|:--------------|:---------------:|:-----------------:|:---------------------------------------|
@@ -1158,7 +1164,7 @@ c.red(1/0)     // 'Infinity' in red
 
 | Package                      |          Dependencies          | Minified         |                                            Unpacked Size |                                                           Tarball size |
 |:-----------------------------|:------------------------------:|------------------|---------------------------------------------------------:|-----------------------------------------------------------------------:|
-| [`ansis`][ansis]             |         [0][npm-ansis]         | uglified & minified |                                     [5.76 kB][npm-ansis] |             [3.4 kB](https://arve0.github.io/npm-download-size/#ansis) |
+| [`ansis`][ansis]             |         [0][npm-ansis]         | uglified & minified |                                     [5.71 kB][npm-ansis] |             [3.4 kB](https://arve0.github.io/npm-download-size/#ansis) |
 | [`picocolors`][picocolors]   |      [0][npm-picocolors]       | no               |                                [6.37 kB][npm-picocolors] |        [2.6 kB](https://arve0.github.io/npm-download-size/#picocolors) |
 | [`tinyrainbow`][tinyrainbow] |   [0][npm-tinyrainbow]         | uglified         |                                [8.1 kB][npm-tinyrainbow] |       [3.2 kB](https://arve0.github.io/npm-download-size/#tinyrainbow) |
 | [`colorette`][colorette]     |       [0][npm-colorette]       | no               |                                 [17.0 kB][npm-colorette] |         [4.9 kB](https://arve0.github.io/npm-download-size/#colorette) |

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ansis",
-  "version": "4.0.0-rc.8",
-  "description": "A small and fast library for applying ANSI colors in terminal or browser console",
+  "version": "4.0.0",
+  "description": "A small and fast ANSI color library",
   "keywords": [
     "ansi",
     "color",
@@ -79,19 +79,19 @@
   "devDependencies": {
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
-    "@types/node": "^22.13.1",
+    "@types/node": "^22.15.17",
     "@vitest/coverage-v8": "^3.1.1",
     "ansis": "file:dist",
     "esbuild": "^0.25.2",
     "prettier": "^3.5.3",
     "rimraf": "^6.0.1",
-    "rollup": "^4.40.0",
+    "rollup": "^4.40.2",
     "rollup-plugin-copy": "^3.5.0",
     "swc": "^1.0.11",
     "terser": "^5.39.0",
     "tsup": "^8.3.6",
     "typescript": "5.4.5",
-    "vitest": "^3.1.1"
+    "vitest": "^3.1.3"
   },
   "overrides": {
     "rollup-plugin-copy": {

package.npm.json

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

src/color-support.js

@@ -130,15 +130,22 @@ export const getLevel = (mockThis) => {
     colorLevel = LEVEL_BW;
   }
 
+  // Optimisation: The Terser inlines a function at use place, so we can split the logic on small parts in source code.
+
   // PM2 does not set process.stdout.isTTY, but colors may be supported (depends on actual terminal)
   // PM2_HOME is always set by PM2, whether running in fork or cluster mode
-  let isPM2 = !!env.PM2_HOME;
+  let isPM2 = () => !!env.PM2_HOME;
 
-  // when Next.JS runtime is `edge`, process.stdout is undefined, but colors output is supported
+  // When Next.JS runtime is `edge`, process.stdout is undefined, but colors output is supported
   // runtime values supported colors: `nodejs`, `edge`, `experimental-edge`
+  let isNextJs = () => env.NEXT_RUNTIME?.includes('edge');
+
+  // Whether the output is supported
+  let isTTY = () => isPM2() || isNextJs() || !!proc.stdout?.isTTY;
+
+  let isWin = () => proc.platform === 'win32';
 
-  // whether the output is supported
-  let isTTY = isPM2 || env.NEXT_RUNTIME?.includes('edge') || !!proc.stdout?.isTTY;
+  let isBrowser = () => !!thisRef.window?.chrome;
 
   // enforce a specific color support:
   // FORCE_COLOR=false   // disables colors
@@ -171,7 +178,7 @@ export const getLevel = (mockThis) => {
   if (isForced) colorLevel = forcedLevel;
 
   // if colorLevel === LEVEL_UNDEFINED, attempt to detect color level, returns 0, 1, 2 or 3
-  if (!~colorLevel) colorLevel = autoDetectLevel(env, isTTY, proc.platform === 'win32');
+  if (!~colorLevel) colorLevel = autoDetectLevel(env, isTTY(), isWin());
 
   // if force disabled: FORCE_COLOR=0 or FORCE_COLOR=false
   if (!forcedLevel
@@ -180,15 +187,13 @@ export const getLevel = (mockThis) => {
     || hasFlag(/^--(no-color|color=(false|never))$/)) return LEVEL_BW;
 
   // Detect browser support
-  if (!!thisRef.window?.chrome) return LEVEL_TRUECOLOR;
+  if (isBrowser()) return LEVEL_TRUECOLOR;
 
   // API Rule: If color output is force enabled but the color level is detected as B&W (e.g., TERM is dumb),
   // enable truecolor since color depth support does not matter.
 
-  // Optimisation: `!colorLevel` is equivalent to `colorLevel === LEVEL_BW`
-  //return isForced && !colorLevel ? LEVEL_TRUECOLOR : colorLevel;
-
   // If color output is forced but the environment doesn't support it, allow truecolor anyway,
   // for example, when saving CLI output snapshots to a file.
+  // Optimisation: `!colorLevel` is equivalent to `colorLevel === LEVEL_BW`
   return isForced && !colorLevel ? LEVEL_TRUECOLOR : colorLevel;
 };

test/functional.test.js

@@ -201,7 +201,7 @@ describe('handling numbers', () => {
   });
 });
 
-describe('style tests', () => {
+describe('color tests', () => {
   test(`visible with template literal`, () => {
     const received = ansis.visible`foo ${green`bar ${red`baz`} bar`} foo`;
     const expected = 'foo \x1b[32mbar \x1b[31mbaz\x1b[32m bar\x1b[39m foo';
@@ -250,6 +250,13 @@ describe('style tests', () => {
     expect(esc(received)).toEqual(esc(expected));
   });
 
+  test(`hex() Truecolor samples`, () => {
+    const received = `${hex('#FF701F')`Orange`}, ${hex('#FF007F')`Rose`}, ${hex('#5C0120')`Bordeaux`}`;
+    const expected = '\x1b[38;2;255;112;31mOrange\x1b[39m, \x1b[38;2;255;0;127mRose\x1b[39m, \x1b[38;2;92;1;32mBordeaux\x1b[39m';
+    console.log('Truecolor: ', received);
+    expect(esc(received)).toEqual(esc(expected));
+  });
+
   test(`ansis.fg(97)`, () => {
     const received = ansis.fg(97)('foo');
     const expected = '\x1b[38;5;97mfoo\x1b[39m';