Package Exports
- colorix
- colorix/ansi.d.mts
- colorix/ansi.mjs
- colorix/color-sequence.d.mts
- colorix/color-sequence.mjs
- colorix/colors.d.mts
- colorix/colors.mjs
- colorix/index.d.mts
- colorix/index.mjs
- colorix/map-colors-to-codes.d.mts
- colorix/map-colors-to-codes.mjs
- colorix/modules
- colorix/modules/colorix-error.d.mts
- colorix/modules/colorix-error.mjs
- colorix/modules/colorix-safe.d.mts
- colorix/modules/colorix-safe.mjs
- colorix/modules/colorix.d.mts
- colorix/modules/colorix.mjs
- colorix/modules/index.d.mts
- colorix/modules/index.mjs
- colorix/modules/ink-presets.d.mts
- colorix/modules/ink-presets.mjs
- colorix/modules/pretty-error.d.mts
- colorix/modules/pretty-error.mjs
- colorix/modules/safe.d.mts
- colorix/modules/safe.mjs
- colorix/modules/supports-color.d.mts
- colorix/modules/supports-color.mjs
- colorix/package.json
- colorix/reset.d.mts
- colorix/reset.mjs
- colorix/types
- colorix/types/ansi.d.mts
- colorix/types/ansi.mjs
- colorix/types/apply-style.d.mts
- colorix/types/apply-style.mjs
- colorix/types/color-sequence.d.mts
- colorix/types/color-sequence.mjs
- colorix/types/colorix-error.d.mts
- colorix/types/colorix-error.mjs
- colorix/types/colorix.d.mts
- colorix/types/colorix.mjs
- colorix/types/colors.d.mts
- colorix/types/colors.mjs
- colorix/types/index.d.mts
- colorix/types/index.mjs
- colorix/types/map-colors-to-codes.d.mts
- colorix/types/map-colors-to-codes.mjs
- colorix/types/pretty-error.d.mts
- colorix/types/pretty-error.mjs
- colorix/utils
- colorix/utils/index.d.mts
- colorix/utils/index.mjs
- colorix/utils/is-string.d.mts
- colorix/utils/is-string.mjs
- colorix/utils/join.d.mts
- colorix/utils/join.mjs
Readme
Colorix
Colorix helps you recognize and track ansi escape sequences in your code, and provides a simple way to define and layer color presets.
import cx from 'colorix'
const goblinInk = cx('bgGreen', 'black', 'bold')
console.log(goblinInk('hello goblin', '!'))
With TypeScript, you'll see how the color sequences are applied to your strings.
declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], ['hello goblin', '!']>
// => `\u001B[42;30;1mhello goblin!\u001B[0m`This is useful with primitive strings as well.
declare const goblinMessage: Colorix<['bgGreen', 'black', 'bold'], [string, ...string[]]>
// => `\u001B[42;30;1m${string}\u001B[0m`How it works
// create a theme by passing colors to the first function.
declare const cx: <Colors extends Color[]>(
...colors: Colors
) => // then pass stringifiable values to the second function to colorize them.
<Strings extends Stringifiable[]>(
...strings: Strings
) => // the returned value is an ansified string.
Colorix<Colors, Strings>Installation
Add colorix to your project using your favorite package manager.
NPM
npm install colorixPNPM
pnpm add colorixYarn
yarn add colorixHow to support terminals without color
safe, colorixSafe, cxs
You can use safe to check if the terminal supports color before applying a preset.
import cx, { safe } from 'colorix'
const errorInk = cx('bold', 'red')
console.log(errorInk('That tasted purple...'))
// "\u001B[mThat tasted purple...\u001B[0m"
console.log(safe(errorInk)('That tasted purple...'))
// "That tasted purple..." | "\u001B[mThat tasted purple...\u001B[0m"Alternatively, use colorixSafe / cxs for an Ink preset that only applies colors if the terminal supports it.
import { cxs, colorixSafe } from 'colorix'
const safeErrorInk = cxs('bold', 'red') // or colorixSafe('bold', 'red')
console.log(safeErrorInk('That tasted purple...'))Bonus Features
ColorixError
ColorixError can be used to extend the Error class. This is useful for throwing consistent, legible, contextual errors.
import { ColorixError } from 'colorix'
const FileNotFoundError = ColorixError('FileNotFoundError', 'Critical file is missing!')
throw new FileNotFoundError(
'File at',
(style) => style.path('file.txt'),
'does not exist. Check the documentation for more information',
(style) => style.link('https://github.com/Cuppachino/colorix')
)PrettyError
For an "out-of-the-box" solution, use PrettyError. It provides the same naming and fallback message behavior as Colorix without an api for customizing the rest of the error.
import { PrettyError } from 'colorix'
const IOError = PrettyError('IOError', 'An unknown IO error occurred.')
try {
throw new IOError()
} catch (err) {
console.log(err)
}
try {
throw new IOError('Illegal write operation.', 'more info...')
} catch (err) {
console.log(err)
}Exports
default, colorix, cx
| Colorix | Description |
|---|---|
default / cx / colorix |
Create presets for colorizing Stringifiable values. |
cxs / colorixSafe |
Create presets for colorizing when the terminal supports it Stringifiable. |
safe |
Call a colorix preset safely safe(cx( ...colors )). |
ColorixError |
Create child Error classes with colorized messages. |
Constants
| Name | Description |
|---|---|
CSI |
control sequence introducer ("\x1b[") |
SGRT |
select graphic rendition terminator ("m") |
FOREGROUND |
readonly foreground lookup object |
BACKGROUND |
readonly background lookup object |
MODIFIER |
readonly modifier lookup object |
COLORS |
readonly color lookup object (foreground, background, and modifiers) |
hasBasicColors |
boolean indicating if the terminal supports basic colors |
has256Colors |
boolean indicating if the terminal supports 256 colors |
has16mColors |
boolean indicating if the terminal supports 16 million colors |
supportsColor |
boolean indicating if the terminal supports any color |
Types
| Generic | Description |
|---|---|
Colorix |
utility for creating literals wrapped in ANSI sequences |
ColorSequence |
utility for creating literal ANSI sequences |
| Alias | Description |
|---|---|
ResetSequence |
literal reset sequence that is always appended to the end of a color sequence |
ColorTable |
readonly record of color aliases and color codes |
Color |
a foreground, background, or modifier color (keyof ColorTable) |
ColorCode |
an SGR color code |
Foreground |
a foreground color |
Background |
a background color |
Modifier |
a modifier color |
Color Tables
| Foreground | Code | Foreground Bright | Code |
|---|---|---|---|
"black" |
30 | "gray" |
90 |
"red" |
31 | "redBright" |
91 |
"green" |
32 | "greenBright" |
92 |
"yellow" |
33 | "yellowBright" |
93 |
"blue" |
34 | "blueBright" |
94 |
"magenta" |
35 | "magentaBright" |
95 |
"cyan" |
36 | "cyanBright" |
96 |
"white" |
37 | "whiteBright" |
97 |
| Background | Code | Background Bright | Code |
|---|---|---|---|
"bgBlack" |
40 | "bgGray" |
100 |
"bgRed" |
41 | "bgRedBright" |
101 |
"bgGreen" |
42 | "bgGreenBright" |
102 |
"bgYellow" |
43 | "bgYellowBright" |
103 |
"bgBlue" |
44 | "bgBlueBright" |
104 |
"bgMagenta" |
45 | "bgMagentaBright" |
105 |
"bgCyan" |
46 | "bgCyanBright" |
106 |
"bgWhite" |
47 | "bgWhiteBright" |
107 |
| Modifier | Code |
|---|---|
"reset" |
0 |
"bold" |
1 |
"dim" |
2 |
"italic" |
3 |
"underline" |
4 |
"inverse" |
7 |
"hidden" |
8 |
"strikethrough" |
9 |