@peteanderson/ansi

v3.8.0

Published

18 days ago

ANSI escape sequence generation with automatic feature detection

0High
0Medium
0Low

peteanderson

ansi nodejs color terminal cli

@peteanderson/ansi

ANSI escape sequence helpers for Node.js terminal output. Automatically detects terminal capabilities and adapts output accordingly.

Installation

npm install @peteanderson/ansi

Usage

The examples below use require(), but import works identically for ESM and TypeScript consumers — just substitute import ansi from for const ansi = require, and so on.

// Use directly as a namespace
const ansi = require("@peteanderson/ansi");
console.log(ansi.fg.red("error: something went wrong"));
console.log(ansi.bg.blue.and.fg.white.and.bold("highlighted"));

// Call it to build a custom instance
const ansiNoColor = ansi(24); // force 24-bit (true color)
console.log(ansiNoColor.fg.rgb(255, 128, 64)("light red-orange"));

// Destructure named exports
const {ansi: defaultInstance, makeAnsi, fg} = require("@peteanderson/ansi");
console.log(fg.red.and.bold("Hello, world!"));
const custom = makeAnsi({colorDepth: 8, cursor: false});

Feature Detection

The module automatically detects:

Color depth: 1 (none), 4 (16 colors), 8 (256 colors), 24 (true color)
Style support: enabled if color depth > 1
Other features: cursor, erase, scroll — enabled if output is a TTY and TERM is not dumb

When disabled, features output empty strings. Color outputs plain text. This can be overridden:

Pass a boolean to force color on/off
Pass a number to set specific color depth (1, 3, 4, 8, or 24)
Pass a stream to use for detection
Pass a partial features object to override individual features

API

Default Export

The default export is both the pre-built default instance and a callable factory. You can use it directly as a namespace, call it to build a custom instance, or destructure properties from it:

const ansi = require("@peteanderson/ansi");

console.log(ansi.fg.red("hello"));   // use as instance
const custom = ansi(true);           // call as factory
console.log(custom.fg.red("hello")); // forced color

`makeAnsi(options?)`

The factory function, exported as a named export. Returns a configured instance. Equivalent to calling the default export as a function, but exported separately for consumers who want a plain function reference:

import {makeAnsi} from "@peteanderson/ansi";
const custom = makeAnsi(true);

`ansi`

The pre-built default instance, exported as a named export. Unlike the default export, this is not callable — use makeAnsi if you need to build a custom instance:

import {ansi, makeAnsi} from "@peteanderson/ansi";
console.log(ansi.fg.red("hello"));

`fg` — foreground colors

Functions that wrap text with color codes (or plain text if disabled):

Basic colors: black red green yellow blue magenta cyan white default
Bright colors: brightBlack brightRed brightGreen brightYellow brightBlue brightMagenta brightCyan brightWhite
fg.rgb(r, g, b)(text) - 24-bit RGB color, downscaled for lower color depths
fg.x256(code)(text) or fg.x256(r, g, b)(text) - 256-color palette, downscaled as needed

All return functions with open and close properties for raw sequences and an and property for fluent chaining.

`bg` — background colors

Functions that wrap text with color codes (or plain text if disabled):

Basic colors: black red green yellow blue magenta cyan white default
Bright colors: brightBlack brightRed brightGreen brightYellow brightBlue brightMagenta brightCyan brightWhite
bg.rgb(r, g, b)(text) - 24-bit RGB color, downscaled for lower color depths
bg.x256(code)(text) or bg.x256(r, g, b)(text) - 256-color palette, downscaled as needed

All return functions with open and close properties for raw sequences and an and property for fluent chaining.

`style`

Functions that wrap text with style codes (disabled if color depth = 1):

bold dim italic underline inverse hidden strikethrough doubleUnderline framed encircled overline

All return functions with open and close properties for raw sequences and an and property for fluent chaining.

Fluent Chaining with `.and`

Styles can be chained using the .and property for a natural, fluent interface. The style namespace is unnested in chains:

// Top-level: use style namespace
ansi.style.bold("bold text");

// In a chain: no need for style namespace
console.log(ansi.fg.white.and.bg.blue.and.bold("white on blue, bold"));
console.log(ansi.fg.red.and.underline("red underlined"));

Arbitrary Style Combination with `.combine()`

Arbitrary styles can be combined using the .combine() method on any SGR function. This allows you to combine any styles into a single function, which can then be applied to text:

const dim = format => format.combine(ansi.style.dim);

console.log(dim(ansi.fg.red("dim red text")));

Arbitrary Chaining with `.chain()`

The fluent interface is usually more convenient than .combine(), but it has one limitation: once an attribute has been set, it cannot be overridden via .and. For example, ansi.fg.red.and.fg.blue("text") will error both at compile time and at runtime, because the fg property isn't available in the chain, since it was already used.

This can be inconvenient when you want to override default styles. Take this example:

import ansi from "@peteanderson/ansi";

function formatText(text: string, format?: (defaultStyle: Format) => Format): string {
    let style = ansi.fg.green;
    if (format)
        style = format(style);
    return style(text);
}

formatText("Some error message", style => style.and.fg.red);
// ❌ TypeError: Cannot read properties of undefined (reading 'red')

This will throw an error at runtime since fg won't be available in the chain. However, with chain(), you can create a new formatter that allows overriding styles that have already been used:

import ansi from "./src";

function formatText(text: string, format?: (defaultStyle: Format) => Format): string {
    let style = ansi.fg.green;
    if (format)
        style = format(ansi.chain(style));
    return style(text);
}

formatText("Some error message", style => style.and.fg.red);
// ✅ "Some error message" in red

`reset`

The SGR reset sequence. Empty string if color is disabled.

`plain`

An identity formatter that returns its input string unchanged. Useful for conditionally disabling formatting or for testing:

function formatText(text, useColor) {
    const format = useColor ? ansi.fg.green : ansi.plain;
    return format.and.bold(text);
}