Stain the pane without the pain of remembering if it's bgRed, redBg, or ordering for that matter
- Dyslectic friendly with any-fluent-chain API:
stain.white.bold.cyan.bg('No More Tears') - Supports: 4-bit (16 colors), 8-bit (256 colors),
bold,dim,underline,inverse, andNO_COLOR - Nest-able:
stain.red.bold('bold' + stain.normal.blue(' normal ') + 'bold') - Fast-ish: ~180,000,000/sec (
NO_COLOR), ~6,500,000/sec (simpleEscape), ~5,000,000/sec (default) - TypeScript'ed with zero dependencies
Code
import stain, { createStain } from 'stain'; // chain it & stain it console.log(stain.cyan('cyan fg')); console.log(stain.iblue('intense blue fg')); console.log(stain.bold.ired('bold intense red fg')); // apply a background color simply by adding '.bg' property after the color console.log(stain.icyan.bg.black('intense cyan bg with black fg')); // order of operations makes no difference console.log(stain.black.icyan.bg('intense cyan bg with black fg')); // last prop/chain always wins console.log(stain.blue.bg.red.black.icyan.bg('intense cyan bg with black fg')); // chain anything & everything till to your heart's content console.log(stain.blue.black.bg.yellow.underline('yellow fg with black bg and underlined')); console.log(stain.blue.black.bg.yellow.underline.inverse('yellow bg with black fg and underlined')); console.log(stain.even.this.works.yellow.bold('bold yellow fg')); // nesting works console.log(stain.purple.bold('bold-purple ' + stain.cyan.normal('normal-cyan') + ' bold-purple')); // xterm/256-color 'stain.x<number>' notation console.log(stain.x123('a lovely cornflower blue')); // create your own xterm/256-color palette with easy pasy to remember names const customStain = createStain({ xterm: true, colors: { warn: 226, // yellow error: 196, // red }, }); console.log(customStain.warn('yellow/xterm=226 fg')); console.log(customStain.error('red/xterm=196 fg')); console.log(customStain.warn.error.bg('yellow/xterm=226 fg with red/xterm=196 bg')); console.log(customStain.warn.bg.error('red/xterm=196 fg with yellow/xterm=226 bg'));
# pick your poison
npm install stain
bun add stain
pnpm add stain
yarn add stainimport stain from 'stain';
console.log(stain.cyan('The Main Stain'));Pre-initialized with
xtermenabled
import { createStain } from 'stain';
const myStain = createStain({
noColor: !!process.env['CI'],
xterm: true,
colors: {
peach: 216,
navy: 18,
},
format: (...args) => args.join(' | '),
});
process.stdout.write(`
${myStain.x216('peach fg')}
${myStain.peach('peach fg')}
${myStain.x18.bg('navy bg')}
${myStain.navy.bg('navy bg')}
`);
// styled format output: 'multiple | args | format'
process.stdout.write(myStain.green('multiple', 'args', 'format'));type StainOptions = {
/**
* Custom color mapping to 8-bit/256-color codes (0-255) (e.g: {error: 196})
* @default undefined
*/
colors?: Record<string, number>;
/**
* Custom format function
* @default simplified `util.format` with with `JSON.stringify` fallback
* @see {@link https://nodejs.org/api/util.html#utilformatformat-args}
*/
format?: (...args: any[]) => string;
/**
* Disable ANSI color/styling (~50-250x faster)
* @default false (unless the `NO_COLOR` environment/CLI variable is set)
*/
noColor?: boolean;
/**
* Use a simpler ANSI escape function without nesting support (~1.5-4x faster)
* @default false
*/
simpleEscape?: boolean;
/**
* Enable 8-bit/256-color support via `x<number>` notation
* @default false (for `createStain`)
* @default true (for default `stain` export)
* @see {@link https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit}
*/
xterm?: boolean;
};| Options | |
|---|---|
| Background | append .bg to any foreground (e.g: stain.white.bg, stain.iblue.bg) |
| 4-bit Color | black, red, green, yellow, blue, purple, cyan, white |
| 4-bit Color Intense | iblack, ired, igreen, iyellow, iblue, ipurple, icyan, iwhite |
| 8-bit Color | x0 through x255 (e.g: stain.x122, stain.x50, stain.x150.bg) |
| Font | bold, dim, normal, underline |
| Other | inverse, reset |
8-bit Color Grid
// bold - makes text bold
console.log(' ' + stain.bold('stain.bold'));
// dim - makes text dim
console.log(' ' + stain.dim('stain.dim'));
console.log(' ' + stain.dim.white('stain.dim.white (tends to work better than gray)'));
// underline - underlines text
console.log(' ' + stain.red.underline('stain.red.underline'));
// inverse - inverts the foreground and background colors
console.log(' ' + stain.red.black.bg('stain.red.black.bg'));
console.log(' ' + stain.red.black.bg.inverse('stain.red.black.bg.inverse'));
// normal - resets bold and dim styles
console.log(' ' + stain.cyan.bold(`stain.cyan.bold ${stain.normal(' stain.normal ')} stain.cyan.bold`));
console.log(' ' + stain.cyan.dim(`stain.cyan.dim ${stain.normal(' stain.normal ')} stain.cyan.dim`));
// reset - resets all active styles, returning to the terminal default
console.log(' ' + stain.underline.yellow.bold(`stain.underline.yellow.bold${stain.reset(' reset ')}stain.underline.yellow.bold`));- Clone repository
- Create and switch to a new branch for your work
- Make and commit changes
- Run
make releaseto clean, setup, build, lint, and test - If everything checks out, push branch to repository and submit pull request
# USAGE
make [flags...] <target>
# TARGET
-------------------
run executes entry-point (./src/index.ts) via 'bun run'
release clean, setup, build, lint, test, aok (everything but the kitchen sink)
-------------------
build builds the .{js,d.ts} (skips: lint, test, and .min.* build)
build_cjs builds the .cjs export
build_esm builds the .js (esm) export
build_declarations builds typescript .d.{ts,mts,cts} declarations
-------------------
install installs dependencies via bun
update updates dependencies
update_dry lists dependencies that would be updated via 'make update'
-------------------
lint lints via tsc & eslint
lint_eslint lints via eslint
lint_eslint_fix lints and auto-fixes via eslint --fix
lint_tsc lints via tsc
lint_watch lints via eslint & tsc with fs.watch to continuously lint on change
-------------------
test runs bun test(s)
test_watch runs bun test(s) in watch mode
test_update runs bun test --update-snapshots
-------------------
help displays (this) help screen
# FLAGS
-------------------
BUN [? ] bun build flag(s) (e.g: make BUN="--banner='// bake until golden brown'")
-------------------
CJS [?1] builds the cjs (common js) target on 'make release'
EXE [?js|mjs] default esm build extension
TAR [?0] build target env (-1=bun, 0=node, 1=dom, 2=dom+iife, 3=dom+iife+userscript)
MIN [?1] builds minified (*.min.{mjs,cjs,js}) targets on 'make release'
-------------------
BAIL [?1] fail fast (bail) on the first test or lint error
ENV [?DEV|PROD|TEST] sets the 'ENV' & 'IS_*' static build variables (else auto-set)
TEST [?0] sets the 'IS_TEST' static build variable (always 1 if test target)
WATCH [?0] sets the '--watch' flag for bun/tsc (e.g: WATCH=1 make test)
-------------------
DEBUG [?0] enables verbose logging and sets the 'IS_DEBUG' static build variable
QUIET [?0] disables pretty-printed/log target (INIT/DONE) info
NO_COLOR [?0] disables color logging/ANSI codes
MIT License
Copyright (c) 2025 te <[email protected]>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.