@haydenhigg/pastel

A small library for simplifying terminal coloring in NodeJS (but this one uses templating for succinct and powerful effects).

Usage

There are a few ways to use this package. You can use the escape characters directly:

const pastel = require("@haydenhigg/pastel");

console.log(pastel.meta.bold + pastel.meta.italic + pastel.bg.green + pastel.fg.red + "Hello world!" + pastel.meta.reset); // red, bold, and italic on green background

but that's not recommended (unless you want to create multi-line effects without a reset). Even easier is to use the convert function:

console.log(pastel.convert("Hello world!", { color: "red", background: "green", decoration: ["bold", "italic"] }));

Sometimes that might be a litte more than you need, though. In that case, just use some of the shortened helper functions:

console.log(pastel.red("Hello world!")); // of course these can be use within each-other...
console.log(pastel.bold(pastel.italic(pastel.greenBackground(pastel.red("Hello world!")))));

Are these not expressive enough for you? There is also a parse function:

console.log(pastel.parse("*$<gn>rdHello world^!$*")); // the same as all of the other examples!

The syntax for this is short and sweet, and the actual function is quite powerful, so the strings it takes in can look quite obscure. To break it down quickly:

// these characters go around the text to be altered, and they don't touch the rest of the string or interfere with other effects
'*some text*' // bold
'$some text$' // italic
'_some text_' // underline
'!some text!' // blink

// these characters are meant to be used alone, without a matching character
'>color' // sets color to 'color', where 'color' is a 2-letter code of the possible colors (the first and last letter, like 'rd' for red or "ma" for magenta)
'<color' // sets background color to 'color', see above for limits on what 'color' must be
'|' // a manual reset character (pastel.meta.reset), but it's almost never necessary (the other characters use their own reset characters internally)

// the escape character
'^' // used if you want to use a control character (*, $, _, !, >, <, |, ^) in the string. you have to escape this character to use it in a string as well

All of this means that we can get complex combinations with far less typing:

console.log(pastel.parse(">rd_!This! is red $and$ underlined *($and$ bold)*.>bk This is black $and$ underlined^!_"));

// is the same as

console.log(
    pastel.convert("This", { color: "red", decoration: ["blink", "underline"] }) +
    pastel.convert(" is red ", { color: "red", decoration: ["underline"] }) +
    pastel.convert("and", { color: "red", decoration: ["italic", "underline"] }) +
    pastel.convert(" underlined ", { color: "red", decoration: ["underline"] }) +
    pastel.convert("(", { color: "red", decoration: ["bold", "underline"] }) +
    pastel.convert("and", { color: "red", decoration: ["bold", "italic", "underline"] }) +
    pastel.convert(" bold)", { color: "red", decoration: ["bold", "underline"] }) +
    pastel.convert(".", { color: "red", decoration: ["underline"] }) +
    pastel.convert(" This is black ", { color: "black", decoration: ["underline"] }) +
    pastel.convert("and", { color: "black", decoration: ["italic", "underline"] }) +
    pastel.convert(" underlined!", { color: "black", decoration: ["underline"] }));

Other functions

• There are shorthand functions for rainbow and rainbowBackground -styled text, and those are valid options for convert too.
• There are shorthand functions for success, warning, and error that provide the expected functionality, and you can provide your own label if you want (success(message, label) = label: message, success(message) = success: message`).