@braebo/ansi

ANSI code helpers for colorful logging in node.js and chrome.

• Hex -> True Color
• Dynamic colorization
• Gradients
• TypeScript / ESM
• Dependency-free
• Lightweight
• Tree shakable

Install

# npm
pnpm i -D @braebo/ansi

# jsr
pnpm dlx jsr add @braebo/ansi

Usage

Hex

Create colors from hex values:

import { ansiHex } from '@braebo/ansi'

const coral = ansiHex('#FF7F50')
console.log(coral('This text will be coral colored'))

Style

Create styles from the ansiStyle function:

import { ansiStyle } from '@braebo/ansi'

const bold = ansiStyle('bold')
console.log(bold('This text will be bold'))

Gradient

Interpolate gradients with any number of colors:

import { ansiGradient } from '@braebo/ansi'

// Create a gradient function.
const g = ansiGradient('#38b2db', '#5959b5', '#e84067')

Now that we have a gradient function, we can pass it a string:

console.log(g('Simple gradient text.'))

Or pass it a number to get a color stop:

const fade = `
${g(0.5)}■■■■■■■■■■■■
${g(0.0)}■■■■■■■■■■■■
${g(0.9)}■■■■■■■■■■■■
${CLEAR}`

console.log(fade)

Mini Methods

Colored logging can quickly become unweildy, so I like to use the mini methods for common colors and styles:

import { l } from '@braebo/ansi' // console.log

import { r, g, b } from '@braebo/ansi' // Colors
import { d, bd, em } from '@braebo/ansi' // Styles

// Colors
l(r('red'))
l(g('green'))
l(b('blue'))

// Styles
l(d('dimmed'))
l(bd('bold'))
l(em('italic'))

If no arguments are provided, the mini methods will return the ANSI code:

console.log(r() + 'red', y() + 'yellow', g() + 'green')

[!NOTE] When no string is provided to a mini method, it won't be wrapped in a corresponding reset code. Use the clear method (clr()) to reset the styles yourself.

logger

The logger function used by the mini methods is somewhat involved, so I decided to expose / document it. It can be used to create your own custom logging functions that colorize input dynamically.

const err = logger({
	prefix: r('| '),
	printWidth: 20,
	fn: (...args: any[]) => {
		console.log(r('>'), r(bd('ERROR')))
		console.log(...args)
	},
})

err('Something went wrong:', { ok: false, cause: '¯\\_(ツ)_/¯' })

LogOptions

The logger function accepts the following options:

printWidth

Controls the expansion of objects and arrays into multiline output.

@default 60

const l = logger({ printWidth: 50 })
l({ foo: true, bar: [1, 'two', { three: () => 3 }] })

[!NOTE] Internally, printWidth is calculated somewhat roughly, so this option is generally a ballpark estimate.

inline

Forces inputs into either inline or multiline output.

@default undefined

const l = logger({ inline: true })
l({ foo: true, bar: [1, 'two', { three: () => 3 }] })

Add __inline__ to an object for a granular overrides.

l({
	one: 1,
	two: 2,
	nested: { __inline__: true, one: 1, two: 2, three: 3 },
})

For array overrides, use the strings __inline__ and __multiline__ to force inline or multiline output.

l([true, 1, 'two', () => 3, '__multiline__'])

delimiter

The delimiter used between rest args.

@default ' '

const l = logger({ delimiter: c(' · ') })
l(true, 1, 'two', () => 3)

prefix

A prefix to prepend to each line (works with multiline output).

@default ''

const l = logger({ prefix: c('⌇ '), delimiter: '' })
l('# ', bd('Header'))
l()
l(d('<p>'), em('Hello, world!'), d('</p>'))

fn

A custom logger function.

@default console.log

const l = logger({ fn: console.warn })
l('E-gad!')

paint()

The paint function used by logger can be used directly to colorize arbitrary input:

console.log(
	paint(
		{
			num: 123,
			bool: true,
			str: 'foo',
			fn: () => 'bar',
		},
		{ inline: false },
	),
)

Why

NIH syndrome / copy-paste fatigue.

License

MIT © braebo