# Eight Colors
> A tiny ANSI color helper for terminal output.

[![](https://img.shields.io/npm/v/eight-colors)](https://www.npmjs.com/package/eight-colors)
![](https://img.shields.io/github/license/cenfun/eight-colors)
[![](https://devimg.vercel.app/npm/downloads/eight-colors?label={total}%20downloads/month)](https://www.npmjs.com/package/eight-colors)

![](scripts/eight-colors.png)

## Install
```bash
npm i eight-colors
```

## Features
* Eight basic colors: `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`
* Background colors via `EC.bg.*`
* Bright colors via `EC.br.*`
* Bright background colors via `EC.br.bg.*`
* Text styles: `reset`, `bold`, `faint`, `italic`, `underline`, `inverse`, `hidden`, `strike`
* Remove ANSI escape sequences with `EC.remove()`
* Colored logging helpers such as `EC.logRed()`
* CJS, ESM, TypeScript types, and browser bundle
* Supports `NO_COLOR`, `FORCE_COLOR`, `--no-color`, and `--color`
* Zero dependencies

## Quick Start

### CommonJS
```js
const EC = require('eight-colors');

console.log(EC.red('red string'));
console.log(EC.bg.red('red background'));
console.log(EC.br.red('bright red string'));
console.log(EC.br.bg.red('bright red background'));
console.log(EC.italic('italic text'));
console.log(EC.underline('underline text'));
console.log(EC.green(EC.underline('green underline text')));
```

### ESM
```js
import EC from 'eight-colors';

console.log(EC.red('red string'));
console.log(EC.br.bg.red('bright red background'));
```

### More Examples
```js
// remove ANSI escape sequences
const redString = EC.red('red string');
const plainString = EC.remove(redString);
console.assert(plainString === 'red string');

// color log helpers: print and return the colored string
const logged = EC.logRed('string1', 'string2');
console.assert(EC.remove(logged) === 'string1 string2');

EC.logRed('log red');
EC.logGreen('log green');
EC.logYellow('log yellow');
EC.logCyan('log cyan');
EC.logWhite('log white');

// log with multiple arguments
EC.log('log 2 arguments', EC.red('2'));
EC.logGreen('logGreen 2 arguments', '2');
EC.logMagenta('logMagenta 3 arguments', EC.red('2'), '3');
```

![](scripts/screenshots.png)

## Color Control
`EC.disabled` controls whether ANSI escape sequences are added at runtime:

```js
EC.disabled = true;   // all color functions return plain strings
EC.disabled = false;  // back to normal
```

On module initialization, `eight-colors` also reads environment variables and CLI flags:

* `NO_COLOR` or `--no-color`: disable colors
* `FORCE_COLOR` or `--color`: enable colors
* If both disabled and forced options are present, disabled takes precedence

The environment check is based on key presence, not on a specific value.

## API
Text colors:
```js
EC.black(str)
EC.red(str)
EC.green(str)
EC.yellow(str)
EC.blue(str)
EC.magenta(str)
EC.cyan(str)
EC.white(str)
```

Background colors:
```js
EC.bg.black(str)
EC.bg.red(str)
EC.bg.green(str)
EC.bg.yellow(str)
EC.bg.blue(str)
EC.bg.magenta(str)
EC.bg.cyan(str)
EC.bg.white(str)
```

Bright colors:
```js
EC.br.black(str)
EC.br.red(str)
EC.br.green(str)
EC.br.yellow(str)
EC.br.blue(str)
EC.br.magenta(str)
EC.br.cyan(str)
EC.br.white(str)
```

Bright background colors:
```js
EC.br.bg.black(str)
EC.br.bg.red(str)
EC.br.bg.green(str)
EC.br.bg.yellow(str)
EC.br.bg.blue(str)
EC.br.bg.magenta(str)
EC.br.bg.cyan(str)
EC.br.bg.white(str)
```

Styles:
```js
EC.reset(str)
EC.bold(str)
EC.faint(str)
EC.italic(str)
EC.underline(str)
EC.inverse(str)
EC.hidden(str)
EC.strike(str)
```

Helpers:
```js
EC.remove(str)
EC.log(...args)

EC.logBlack(...args)
EC.logRed(...args)
EC.logGreen(...args)
EC.logYellow(...args)
EC.logBlue(...args)
EC.logMagenta(...args)
EC.logCyan(...args)
EC.logWhite(...args)
```

Property:
```js
EC.disabled  // boolean, default: false
```

Notes:
* `EC.log()` joins multiple arguments with spaces before printing (no return value)
* `EC.logRed(...args)` and other color log methods print the result and also return the colored string
* Color log methods remove existing ANSI sequences from arguments before applying the new color

## Browser
The package also provides a UMD bundle in `dist/eight-colors.js`.

```html
<script src="path-to/eight-colors/dist/eight-colors.js"></script>
<script>
    const EC = window['eight-colors'];
    console.log(EC.red('red string'));
</script>
```

Note: Most browser consoles do not render ANSI escape sequences as colors (Firefox DevTools ignores them entirely; Chrome has limited support). The browser bundle is mainly useful when you want the same API shape across environments or need `EC.remove()` to strip ANSI sequences.

![](scripts/browser.png)

## Links
* https://en.wikipedia.org/wiki/ANSI_escape_code
* https://handwiki.org/wiki/ANSI_escape_code