Style Escape Codes (sec)

Yet another ansi escape code sequence styler (#insert-mouthful-emoji-here). Supports stacking, nested and global styles; rgb, hex and hsl color spaces out of the box, no dependencies. Keep in mind that each terminal has slightly different color translation for the predefined color values like fgRed. Bundle includes both ESM and CJS files.

Installation

Install the package

npm install style-escape-codes
# or
yarn add style-escape-codes

Load as module

import { sec } from 'style-escape-codes';
// or
import { sec } from 'style-escape-codes/esm/';

Load as commonjs

const sec = require('style-escape-codes').sec;
// or
const sec = require('style-escape-codes/cjs/').sec;
// or
const { sec } = require('style-escape-codes');
// or
const { sec } = require('style-escape-codes/cjs/');

Changelog

v1.1.0

• Expose internal constants to enable custom string manipulations.
• Changelog added. Brief feature information and bug fixes will be added from now on.
• Documentation fixes.

v1.0.3

• Added enable and disable functionality (sec.enable(), sec.disable() and environment SEC_ENABLED=false). Was suppose to be 1.1.0, but, you know - life. To crack the ice I was going to tell a sodium joke, then I thought, Na.

v1.0.2

• Minor changes.

v1.0.1

• Minor Changes.

v1.0.0

• Initial release.

API

Usage:

sec. <style|set-color>[.<style|set-color>...][(<message>)|.set()|.unset()|.toString()]

sec. enable()|disable()

examples:

• sec.b.fg.rgb(255,0,0)('red bold message');
• sec.b.fgRed.set();
• sec.b.fgRed.unset();
• sec.b;
• sec.disable()
• sec.enable()

.disable():

Disable StyleEscapeCodes. Input text will become output without any escape codes. Cached root styles are deleted from the chain and all branches will be marked for garbage collection. Do not keep any references to a style if you plan to dynamically disable and enable this tool as this will prevent the garbage collection process.

const myStyle = sec.b.u.fgRed;
// prints with styles
console.log(sec.b.u.fgRed('Important message'));
// prints with styles
console.log(myStyle('Important message'));
sec.disable();
// prints without styles
console.log(sec.b.u.fgRed('Important message'));
// prints with styles!!!
console.log(myStyle('Important message'));
sec.enable();

You can also set the environment variable SEC_ENABLED=false before module initialization to stop any output from having escape codes. Setting the variable later on has no effect on the output.

.enable():

Enable StyleEscapeCodes.

<style> parameter:

• reset - reset all styles to their defaults.
• bold - text appears with increased intensity.
• dim - text appears with decreased intensity.
• italic - text slants slightly to the right, and guess what it was first used in Italy.
• underline - line under the text.
• invert - swap foreground and background colors.
• hide - text becomes invisible.
• strike - text is crossed-out.
• underlineDouble - double underline.
• overline - like underline, but completely opposite.
• foregroundColor - set foreground color sequence. Use .rgb(), .hex() or .hsl() methods next.
• fgBlack - set foreground color to Black.
• fgRed - set foreground color to Red.
• fgGreen - set foreground color to Green.
• fgYellow - set foreground color to Yellow.
• fgBlue - set foreground color to Blue.
• fgMagenta - set foreground color to Magenta.
• fgCyan - set foreground color to Cyan.
• fgWhite - set foreground color to White.
• fgBrightBlack - set foreground color to Bright Black.
• fgBrightRed - set foreground color to Bright Red.
• fgBrightGreen - set foreground color to Bright Green.
• fgBrightYellow - set foreground color to Bright Yellow.
• fgBrightBlue - set foreground color to Bright Blue.
• fgBrightMagenta - set foreground color to Bright Magenta.
• fgBrightCyan - set foreground color to Bright Cyan.
• fgBrightWhite - set foreground color to Bright White.
• backgroundColor - set background color sequence. Use .rgb(), .hex() or .hsl() methods next.
• bgBlack - set background color to Black.
• bgRed - set background color to Red.
• bgGreen - set background color to Green.
• bgYellow - set background color to Yellow.
• bgBlue - set background color to Blue.
• bgMagenta - set background color to Magenta.
• bgCyan - set background color to Cyan.
• bgWhite - set background color to White.
• bgBrightBlack - set background color to BrightBlack.
• bgBrightRed - set background color to BrightRed.
• bgBrightGreen - set background color to BrightGreen.
• bgBrightYellow - set background color to BrightYellow.
• bgBrightBlue - set background color to BrightBlue.
• bgBrightMagenta - set background color to BrightMagenta.
• bgBrightCyan - set background color to BrightCyan.
• bgBrightWhite - set background color to BrightWhite.

shorts:

• r (reset)
• b (bold)
• d (dim)
• i (italic)
• u (underline)
• inv (invert)
• h (hide)
• s (strike)
• ud (underlineDouble)
• o (overline)
• fg (foregroundColor)
• bg (backgroundColor)
• black (fgBlack)
• red (fgRed)
• green (fgGreen)
• yellow (fgYellow)
• blue (fgBlue)
• magenta (fgMagenta)
• cyan (fgCyan)
• white (fgWhite)
• brightBlack (fgBrightBlack)
• brightRed (fgBrightRed)
• brightGreen (fgBrightGreen)
• brightYellow (fgBrightYellow)
• brightBlue (fgBrightBlue)
• brightMagenta (fgBrightMagenta)
• brightCyan (fgBrightCyan)
• brightWhite (fgBrightWhite)

set-color parameter:

.{fg|foregroundColor|bg|backgroundColor}.{rgb(<r>,<g>,<b>)|hex(<hexvalue>)|hsl(<h>,<s>,<l>)}

examples:

• sec.fg.hsl(0, 100, 50);
• sec.bg.hex('f00');
• sec.backgroundColor.rgb(255, 0, 0);

parameters:

• r, g, b - number [0, 255]
• hexvalue - number [0, 16777215] or string of length 6, 3 or 1 characters
• h - number [0, 360)
• s, l - number [0, 100]

Examples

Difference between call, set, unset and toString

Calling the last property of the sec object as function is the same as surrounding a text with .set() and .unset() methods. .toString() internally calls .set() and implicit coercion to string calls .toString().

console.log(sec.b('bold message'));
console.log(sec.b.set() + 'bold message' + sec.b.unset());
console.log(sec.b.toString() + 'bold message' + sec.b.unset());
console.log(sec.b + 'bold message' + sec.b.unset());

Stacked styles

You can chain styles by calling them as a property of the previous style.

console.log(sec.u.i.b.red('underline, italic, bold red message'));

Nested styles

You can set styles inside styles.

console.log(
  sec.u.i.b.red(
    `underline, italic, bold red ${sec.blue('with blue inside')} message`
  )
);

Same-same, but different

All of the examples below do the same thing.

console.log(sec.bold.underline.red('bold underline red message'));
console.log(sec.b.u.fgRed('bold underline red message'));
console.log(sec.b.u.fg.rgb(255, 0, 0)('bold underline red message'));
console.log(sec.b.u.fg.hex('ff0000')('bold underline red message'));
console.log(sec.b.u.fg.hex('f00')('bold underline red message'));
console.log(sec.b.u.fg.hex(0xff0000)('bold underline red message'));
console.log(sec.b.u.fg.hsl(0, 100, 50)('bold underline red message'));
console.log(sec.b.u.fgRed + 'bold underline red message' + sec.b.u.fg.unset());

Real world examples

Simple real world example.

console.log(
  '\n',
  `🛑 ${sec.u.o.fg.hex('f00').bg.hsl(0, 60, 20)(' Error: Something went wrong! ')}`,
  '\n\n',
  `⚠️  ${sec.u.o.fg.hex('ff0').bg.hsl(60, 60, 20)(' Warning: Proceed with caution! ')}`,
  '\n\n',
  `✅ ${sec.u.o.fg.hex('0f0').bg.hsl(120, 60, 20)(' Success: It worked! ')}`,
  '\n'
);

Global styles (for terminals only)

You can leave the style 'open' by using .set() or .toString() methods and your terminal will continue to use that style until there is a different escape code sequence or a 'reset' code was used.

console.log('This is a regular output');
// set global style by calling the .set() method or by using .toString()
console.log(sec.i.fg.hex('9').bg.hex('3') + '');
// using exec for the sake of the example
exec(
  `echo This is an output from a different command, but it's styled as you can see. && \
  echo And this is another row. && \
  echo This is the third output from an echo command. `,
  (err, stdout) => {
    console.log(stdout);
    // don't forget to .unset() your global styles, or they will overflow
    // .b.fgRed will actually unset b and fg styles after the message
    console.log(sec.b.fgRed('Oops we have serious leak under the sink!'));
    console.log('Is it red or bold? Nope.');
    console.log(sec.i.fg.bg.unset());
    console.log('All ok now.');
  }
);

License

This project is licensed under the MIT License.