colourant v1.1.0
Node 8+ is required. Only LTS versions of Node are tested.
A Node.js library for formatting terminal text using ANSI
features
- No dependencies
- Super performant
- Supports nested & chained colours
- No
String.prototype
modifications - Conditional colour support
- Familiar API
- Fully written in TypeScript
install
$ npm install --save colourant
usage
const { blue, bold, red, white } = require( "colourant" );
// basic usage
red( "red text" );
// chained methods
blue().bold().underline( "howdy partner" );
// nested methods
bold(`${ white().bgRed( "[ERROR]" ) } ${ red().italic( "Something happened" ) }`);
Chained Methods
const { bold, green } = require( "colourant" );
console.log( bold().red( "this is a bold red message" ) );
console.log( bold().italic( "this is a bold italicized message" ) );
console.log( bold().yellow().bgRed().italic( "this is a bold yellow italicized message" ) );
console.log( green().bold().underline( "this is a bold green underlined message" ) );
Nested Methods
const { cyan, red, yellow } = require( "colourant" );
console.log( yellow( `foo ${ red().bold( "red" ) } bar ${ cyan( "cyan" ) } baz` ) );
console.log( yellow( "foo " + red().bold( "red" ) + " bar " + cyan( "cyan" ) + " baz" ) );
Conditional Support
Toggle colour support as needed; colourant
includes auto-detection, but may not cover all cases.
const colourant = require( "colourant" );
// manually enable
colourant.enable();
// manually disable
colourant.disable();
// or use another library to detect support
colourant.enabled = require( "color-support" ).level;
console.log( colourant.red( "I will only be coloured red if `colourant.enabled` is true" ) );
api
Built-in Styles
Built-in colourant
styles return a String
when invoked with input; otherwise chaining is expected.
It's up to the developer to pass the output to destinations like
console.log
,process.stdout.write
, etc.
The methods below are grouped by type for legibility purposes only. They each can be chained or nested with one another.
Colours:
black — red — green — yellow — blue — magenta — cyan — white — gray — grey
Backgrounds:
bgBlack — bgRed — bgGreen — bgYellow — bgBlue — bgMagenta — bgCyan — bgWhite
Modifiers:
reset — bold — dim — italic — underline — inverse — hidden — strikethrough
* Not widely supported
Utility Methods
As well as supporting the kleur 3 API, colourant also provides:
/*
`codegroup` refer's to an array containing the start and end codes
`codemap` refer's to a map of codegroups
*/
const colourant = require( "colourant" );
// Build a custom styled string transformer (stacked, alternative to chain)
colourant( ...codegroups )
// Build a non-chainable string transformer
colourant.from( number, number )
colourant.from( codegroup )
// Build a chainable string transformer
colourant.chain( codemap )
// Build and assign chainable string transformers
colourant.assign( target, codemap )
// Map of default styles
colourant.codes
// Build ANSI string for the given number
colourant.ANSI( number )
// Returns a grey string
colourant.time( string )
// Returns a white string
colourant.info( string )
// Returns a yellow string
colourant.warning( string )
// Returns a red string
colourant.error( string )
// Returns `true` if your env supports colouring by default (checked on library load)
colourant.supportsColour()
TypeScript
This library is written in TypeScript, but I wanted to export the colourant
function as a CommonJS default export (assigning it to Node's module.exports
) so that it's usable via just calling require( "colourant" )
instead of require( "colourant" ).colourant
or require( "colourant" ).default
; To import an exported interface or type, juse import the generated modules directly from colourant/out
benchmarks
Using Node v12.13.0 on a laptop powered by an AMD A10-4600M APU & 6GB RAM
Load time
chalk :: 23.930ms
kleur :: 11.131ms
ansi-colors :: 8.997ms
colorette :: 3.244ms
colourant :: 8.633ms
Performance
# All Colors
ansi-colors x 63,296 ops/sec ±1.93% (75 runs sampled)
chalk x 227,988 ops/sec ±1.32% (79 runs sampled)
kleur x 229,516 ops/sec ±1.67% (81 runs sampled)
colorette x 247,387 ops/sec ±3.44% (81 runs sampled)
colourant x 294,237 ops/sec ±1.50% (79 runs sampled)
# Stacked colors
ansi-colors x 7,408 ops/sec ±1.07% (80 runs sampled)
chalk x 174,681 ops/sec ±0.74% (83 runs sampled)
kleur x 26,174 ops/sec ±0.79% (82 runs sampled)
colourant x 90,674 ops/sec ±1.04% (81 runs sampled)
# Nested colors
ansi-colors x 18,684 ops/sec ±1.06% (81 runs sampled)
chalk x 42,756 ops/sec ±0.81% (83 runs sampled)
kleur x 62,920 ops/sec ±2.09% (84 runs sampled)
colorette x 87,270 ops/sec ±0.82% (82 runs sampled)
colourant x 61,707 ops/sec ±1.09% (77 runs sampled)
credits
This project is based on kleur 3, and contains content originally from it:
- Some source code, like
colourant/out/codes
- The screenshots used in this README
- This README is a rewrite of kleur's readme.md
license
Copyright (c) 2019 Futago-za Ryuu The MIT License, http://opensource.org/licenses/MIT