@peteanderson/ansi 0.2.4 → 0.3.1

package/README.md

@@ -1,6 +1,7 @@
 # @peteanderson/ansi
 
-ANSI escape sequence helpers for Node.js terminal output. Automatically disables color when stdout is not a TTY or when standard environment variables (`NO_COLOR`, `NODE_DISABLE_COLORS`, `FORCE_COLOR`, `TERM=dumb`) indicate it should be.
+ANSI escape sequence helpers for Node.js terminal output. Automatically detects terminal
+capabilities and adapts output accordingly.
 
 ## Installation
 
@@ -11,54 +12,149 @@ npm install @peteanderson/ansi
 ## Usage
 
 ```js
-const {fg, bg, style, reset, stripAnsiSequences} = require('@peteanderson/ansi');
-
-console.log(fg.red('error: something went wrong'));
-console.log(bg.blue(fg.white('highlighted')));
-console.log(style.bold('important'));
-console.log(fg.rgb(5, 2, 0)('custom color'));
-console.log('some styled text' + reset);
-console.log(stripAnsiSequences('\x1b[31mred\x1b[0m')); // => 'red'
+const ansi = require("@peteanderson/ansi");
+
+console.log(ansi.fg.red("error: something went wrong"));
+console.log(ansi.bg.blue.combine(ansi.fg.white)("highlighted"));
+console.log(ansi.style.bold("important"));
+console.log(ansi.fg.rgb(5, 2, 0)("custom color"));
+
+// Disable colors for a specific stream
+const ansiNoColor = ansi(1); // force 1-bit (no color)
+console.log(ansiNoColor.fg.red("this won't be colored"));
+
+// Override specific features
+const customAnsi = ansi({colorDepth: 8, caret: false});
 ```
 
-## API
+## Feature Detection
 
-All color and style functions accept a string and return a string. When color is disabled, the functions are identity — they return the input unchanged.
+The module automatically detects:
 
-### `fg` — foreground colors
+- **Color depth**: 1 (none), 4 (16 colors), 8 (256 colors), 24 (true color)
+- **Style support**: enabled if color depth > 1
+- **Other features**: caret, 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:
 
-`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
+- 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 module exports a callable function with detection-based properties:
 
 ```js
-fg.red('text')
-fg.rgb(r, g, b)('text')  // r, g, b in 0–5 for the 6×6×6 cube, or grayscale 232–255
+const ansi = require("@peteanderson/ansi");
+const customAnsi = ansi(options); // returns configured instance
 ```
 
+### `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.
+
 ### `bg` — background colors
 
-`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white`
+Functions that wrap text with color codes (or plain text if disabled):
 
-```js
-bg.green('text')
-bg.rgb(r, g, b)('text')
-```
+- 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
 
 ### `style`
 
-`bold` `dim` `italic` `underline` `inverse` `hidden` `strikethrough`
+Functions that wrap text with style codes (disabled if color depth = 1):
 
-```js
-style.bold('text')
-style.italic(style.bold('text'))
-```
+`bold` `dim` `italic` `underline` `inverse` `hidden` `strikethrough` `doubleUnderline` `framed`
+`encircled` `overline`
+
+All return functions with `open` and `close` properties for raw sequences.
 
 ### `reset`
 
-The SGR reset sequence (`\x1b[0m`). An empty string when color is disabled.
+The SGR reset sequence. Empty string if color is disabled.
+
+### `caret`
+
+Available if feature is enabled:
 
-### `stripAnsiSequences(text)`
+- `caret.show` / `caret.hide` - show or hide the cursor
+- `caret.position.get` - get the current cursor position (terminal sends position to stdin)
+- `caret.position.set(row, col)` - set cursor position (1-based indexing)
+- `caret.shape.block` / `caret.shape.underline` / `caret.shape.bar` - change cursor shape
+- `caret.up(n)` / `caret.down(n)` / `caret.forward(n)` / `caret.backward(n)` - move cursor
+- `caret.nextLine(n)` / `caret.prevLine(n)` - move cursor to next/previous line
+- `caret.x(col)` - move cursor to column (1-based)
+- `caret.save` / `caret.restore` - save/restore cursor position (VT100)
 
-Removes ANSI SGR escape sequences from a string.
+### `erase`
+
+Available if feature is enabled:
+
+- `erase.line.toStart` / `erase.line.toEnd` / `erase.line.full` - erase line
+- `erase.screen.toStart` / `erase.screen.toEnd` / `erase.screen.full` - erase screen
+- `erase.screen.scrollback` - erase screen and scrollback buffer
+
+### `scroll`
+
+Available if feature is enabled:
+
+- `scroll.up(lines)` - scroll up (default 1 line)
+- `scroll.down(lines)` - scroll down (default 1 line)
+
+### `strip(text)`
+
+Removes all ANSI CSI sequences from a string (always available).
+
+### `slice(text, start, end)`
+
+Slices a string by visible characters, ignoring ANSI sequences (always available).
+
+### `sanitize(text)`
+
+Removes "unsafe" CSI sequences, leaving only color and style codes (always available).
+
+### `simplify(text)`
+
+Simplifies ANSI SGR sequences by combining adjacent sequences and removing redundant codes (always
+available).
+
+### `visibleLength(text)`
+
+Returns the visible length of a string with all ANSI sequences removed (always available).
+
+### `padStart(text, targetLength)` and `padEnd(text, targetLength)`
+
+Pads a string to a target visible length using spaces. Accounts for ANSI sequences when calculating
+length.
+
+### `features`
+
+Object containing the detected feature configuration:
+
+```ts
+{
+    colorDepth : 1 | 3 | 4 | 8 | 24;
+    style      : boolean;
+    caret      : boolean;
+    erase      : boolean;
+    scroll     : boolean;
+}
+```
 
 ## License
 

package/dist/ansi.d.ts

@@ -0,0 +1,52 @@
+export = ansi;
+declare const ansi: typeof makeAnsi & {
+    fg: Channel;
+    bg: Channel;
+} & {
+    caret: ReturnType<typeof makeCaret>;
+    erase: ReturnType<typeof makeErase>;
+    scroll: ReturnType<typeof makeScroll>;
+    reset: string;
+    style: ReturnType<typeof makeStyle>;
+    padEnd: typeof padEnd;
+    padStart: typeof padStart;
+    strip: typeof strip;
+    visibleLength: typeof visibleLength;
+    sanitize: typeof sanitize;
+    slice: typeof slice;
+    simplify: typeof simplify;
+    features: ReturnType<typeof getFeatures>;
+};
+declare namespace ansi {
+    export { Args, Ansi };
+}
+declare function makeAnsi(...args: Args): Ansi;
+import { makeCaret } from "./caret";
+import { makeErase } from "./erase";
+import { makeScroll } from "./scroll";
+import { makeStyle } from "./sgr/style";
+import { padEnd } from "./pad";
+import { padStart } from "./pad";
+import { strip } from "./strip";
+import { visibleLength } from "./strip";
+import { sanitize } from "./strip";
+import { slice } from "./slice";
+import { simplify } from "./simplify/simplify";
+import { getFeatures } from "./features/features";
+type Args = import("./features/features").Args;
+type Ansi = ReturnType<typeof makeColor> & {
+    caret: ReturnType<typeof makeCaret>;
+    erase: ReturnType<typeof makeErase>;
+    scroll: ReturnType<typeof makeScroll>;
+    reset: string;
+    style: ReturnType<typeof makeStyle>;
+    padEnd: typeof padEnd;
+    padStart: typeof padStart;
+    strip: typeof strip;
+    visibleLength: typeof visibleLength;
+    sanitize: typeof sanitize;
+    slice: typeof slice;
+    simplify: typeof simplify;
+    features: ReturnType<typeof getFeatures>;
+};
+import { makeColor } from "./sgr/color/color";

package/dist/ansi.js

@@ -0,0 +1,55 @@
+"use strict";
+const { makeCaret } = require("./caret");
+const { makeErase } = require("./erase");
+const { getFeatures } = require("./features");
+const { padEnd, padStart } = require("./pad");
+const { makeScroll } = require("./scroll");
+const { makeColor, makeReset, makeStyle } = require("./sgr");
+const { simplify } = require("./simplify");
+const { slice } = require("./slice");
+const { sanitize, strip, visibleLength } = require("./strip");
+/**
+@typedef {import("./features/features").Args} Args
+
+@typedef {ReturnType<typeof makeColor> & {
+    caret  : ReturnType<typeof makeCaret>;
+    erase  : ReturnType<typeof makeErase>;
+    scroll : ReturnType<typeof makeScroll>;
+
+    reset : string;
+    style : ReturnType<typeof makeStyle>;
+
+    padEnd   : typeof padEnd;
+    padStart : typeof padStart;
+
+    strip         : typeof strip;
+    visibleLength : typeof visibleLength;
+    sanitize      : typeof sanitize;
+    slice         : typeof slice;
+    simplify      : typeof simplify;
+
+    features : ReturnType<typeof getFeatures>;
+}} Ansi
+*/
+/** @type {(...args: Args) => Ansi}*/
+function makeAnsi(...args) {
+    const features = getFeatures(...args);
+    return {
+        caret: makeCaret(features.caret),
+        erase: makeErase(features.erase),
+        scroll: makeScroll(features.scroll),
+        reset: makeReset(features.colorDepth > 1),
+        style: makeStyle(features.style),
+        ...makeColor(features.colorDepth),
+        padEnd,
+        padStart,
+        strip,
+        visibleLength,
+        sanitize,
+        slice,
+        simplify,
+        features,
+    };
+}
+const ansi = Object.assign(makeAnsi, makeAnsi());
+module.exports = ansi;

package/dist/caret.d.ts

@@ -0,0 +1,28 @@
+export function makeCaret(enabled?: boolean): {
+    up: (count?: number) => string;
+    down: (count?: number) => string;
+    forward: (count?: number) => string;
+    backward: (count?: number) => string;
+    nextLine: (count?: number) => string;
+    prevLine: (count?: number) => string;
+    /** @type {(x: number) => string} */
+    x: (x: number) => string;
+    save: string;
+    restore: string;
+    hide: string;
+    show: string;
+    position: {
+        get: string;
+        /** @type {(x: number, y: number) => string} */
+        set: (x: number, y: number) => string;
+    };
+    shape: {
+        steadyBlock: string;
+        steadyBar: string;
+        steadyUnderline: string;
+        blinkingBlock: string;
+        blinkingBar: string;
+        blinkingUnderline: string;
+        default: string;
+    };
+};

package/dist/caret.js

@@ -0,0 +1,70 @@
+"use strict";
+/** @type {(code: string) => (count?: number) => string} */
+const move = code => count => `\x1b[${count === undefined ? "" : count ? count : "?"}${code}`;
+/** @type {(count?: number) => string} */
+const noop = () => "";
+const caret = {
+    up: move("A"),
+    down: move("B"),
+    forward: move("C"),
+    backward: move("D"),
+    nextLine: move("E"),
+    prevLine: move("F"),
+    /** @type {(x: number) => string} */
+    x: x => `\x1b[${x}G`,
+    // These are the old VT100 codes, but they're widely supported by old and new terminals. The
+    // newer VT220 codes are standardized by ECMA and ISO, and are also widely supported, but might
+    // not work in some older terminals. The VT220 codes are:
+    //
+    // ```
+    // save    : "\x1b[s",
+    // restore : "\x1b[u",
+    // ```
+    save: "\x1b7",
+    restore: "\x1b8",
+    hide: "\x1b[?25l",
+    show: "\x1b[?25h",
+    position: {
+        get: "\x1b[6n",
+        /** @type {(x: number, y: number) => string} */
+        set: (x, y) => `\x1b[${y};${x}H`,
+    },
+    shape: {
+        steadyBlock: "\x1b[2 q",
+        steadyBar: "\x1b[6 q",
+        steadyUnderline: "\x1b[4 q",
+        blinkingBlock: "\x1b[1 q",
+        blinkingBar: "\x1b[5 q",
+        blinkingUnderline: "\x1b[3 q",
+        default: "\x1b[0 q",
+    },
+};
+/** @type {typeof caret} */
+const disabled = {
+    up: noop,
+    down: noop,
+    forward: noop,
+    backward: noop,
+    nextLine: noop,
+    prevLine: noop,
+    x: noop,
+    save: "",
+    restore: "",
+    hide: "",
+    show: "",
+    position: {
+        get: "",
+        set: noop,
+    },
+    shape: {
+        steadyBlock: "",
+        steadyBar: "",
+        steadyUnderline: "",
+        blinkingBlock: "",
+        blinkingBar: "",
+        blinkingUnderline: "",
+        default: "",
+    },
+};
+const makeCaret = (enabled = true) => enabled ? caret : disabled;
+module.exports = { makeCaret };

package/dist/erase.d.ts

@@ -0,0 +1,13 @@
+export function makeErase(enabled?: boolean): {
+    line: {
+        toStart: string;
+        toEnd: string;
+        full: string;
+    };
+    screen: {
+        toStart: string;
+        toEnd: string;
+        full: string;
+        scrollback: string;
+    };
+};

package/dist/erase.js

@@ -0,0 +1,30 @@
+"use strict";
+const erase = {
+    line: {
+        toStart: "\x1b[1K",
+        toEnd: "\x1b[0K",
+        full: "\x1b[2K",
+    },
+    screen: {
+        toStart: "\x1b[1J",
+        toEnd: "\x1b[0J",
+        full: "\x1b[2J",
+        scrollback: "\x1b[3J",
+    },
+};
+/** @type {typeof erase} */
+const disabled = {
+    line: {
+        toStart: "",
+        toEnd: "",
+        full: "",
+    },
+    screen: {
+        toStart: "",
+        toEnd: "",
+        full: "",
+        scrollback: "",
+    },
+};
+const makeErase = (enabled = true) => enabled ? erase : disabled;
+module.exports = { makeErase };

package/dist/features/build.d.ts

@@ -0,0 +1,11 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+export function build(isTTY: boolean, colorDepth: ColorDepth, style?: boolean, caret?: boolean, erase?: boolean, scroll?: boolean): Features;
+/** @type {(isTTY: boolean, enabled: boolean) => Features} */
+export const boolean: (isTTY: boolean, enabled: boolean) => Features;
+/** @type {(isTTY: boolean, colorDepth: ColorDepth) => Features} */
+export const number: (isTTY: boolean, colorDepth: ColorDepth) => Features;
+/** @type {(stream: NodeJS.WriteStream) => Features} */
+export const tty: (stream: NodeJS.WriteStream) => Features;
+/** @type {() => Features} */
+export const pipe: () => Features;

package/dist/features/build.js

@@ -0,0 +1,50 @@
+"use strict";
+const { getColorDepth, detectFeatureSupport } = require("./detect");
+/** @typedef {import("./types").ColorDepth} ColorDepth */
+/** @typedef {import("./types").Features}   Features */
+/** @type {(colorDepth: number) => ColorDepth} */
+function normalizeColorDepth(colorDepth) {
+    colorDepth = Math.floor(colorDepth);
+    if (colorDepth >= 24)
+        return 24;
+    if (colorDepth >= 8)
+        return 8;
+    if (colorDepth >= 4)
+        return 4;
+    if (colorDepth === 3)
+        return 3;
+    return 1;
+}
+/**
+@type {
+    (
+        isTTY      : boolean,
+        colorDepth : ColorDepth,
+        style?     : boolean,
+        caret?     : boolean,
+        erase?     : boolean,
+        scroll?    : boolean,
+    ) => Features
+}
+*/
+function build(isTTY, colorDepth, style, caret, erase, scroll) {
+    if (style !== undefined && caret !== undefined && erase !== undefined && scroll !== undefined)
+        return { colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll };
+    const support = detectFeatureSupport(isTTY, colorDepth);
+    return {
+        colorDepth: normalizeColorDepth(colorDepth),
+        style: style ?? support.style,
+        caret: caret ?? support.caret,
+        erase: erase ?? support.erase,
+        scroll: scroll ?? support.scroll,
+    };
+}
+/** @type {(isTTY: boolean, enabled: boolean) => Features} */
+const boolean = (isTTY, enabled) => build(isTTY, enabled ? 4 : 1);
+/** @type {(isTTY: boolean, colorDepth: ColorDepth) => Features} */
+const number = (isTTY, colorDepth) => build(isTTY, colorDepth);
+/** @type {(stream: NodeJS.WriteStream) => Features} */
+const tty = stream => build(true, getColorDepth(stream));
+/** @type {() => Features} */
+const pipe = () => build(false, getColorDepth());
+module.exports = { build, boolean, number, tty, pipe };

package/dist/features/detect.d.ts

@@ -0,0 +1,4 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+export function detectFeatureSupport(isTTY: boolean, colorDepth: ColorDepth): Omit<Features, "colorDepth">;
+export function getColorDepth(stream?: NodeJS.WriteStream): ColorDepth;

package/dist/features/detect.js

@@ -0,0 +1,33 @@
+"use strict";
+/** @typedef {import("./types").ColorDepth} ColorDepth */
+/** @typedef {import("./types").Features}   Features */
+/** @type {(stream?: NodeJS.WriteStream) => ColorDepth} */
+function getColorDepth(stream) {
+    if (stream?.isTTY)
+        return /** @type {ColorDepth} */ (stream.getColorDepth());
+    if (process.env.NO_COLOR || process.env.NODE_DISABLE_COLORS)
+        return 1;
+    switch (process.env.FORCE_COLOR) {
+        case "":
+        case "true":
+        case "1":
+            return 4;
+        case "2":
+            return 8;
+        case "3":
+            return 24;
+        default:
+            return 1;
+    }
+}
+/** @type {(isTTY: boolean, colorDepth: ColorDepth) => Omit<Features, "colorDepth">} */
+function detectFeatureSupport(isTTY, colorDepth) {
+    const enabled = process.env.TERM !== "dumb" && isTTY;
+    return {
+        style: colorDepth > 1,
+        caret: enabled,
+        erase: enabled,
+        scroll: enabled,
+    };
+}
+module.exports = { detectFeatureSupport, getColorDepth };

package/dist/features/features.d.ts

@@ -0,0 +1,5 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+export type Args = [enabled: boolean, stream?: NodeJS.WriteStream] | [colorDepth: ColorDepth, stream?: NodeJS.WriteStream] | [features: Partial<Features>, stream?: NodeJS.WriteStream] | [socket: Socket] | [stream?: NodeJS.WriteStream];
+export function getFeatures(...args: Args): Features;
+import { Socket } from "node:net";

package/dist/features/features.js

@@ -0,0 +1,39 @@
+"use strict";
+const { Socket } = require("node:net");
+const { WriteStream } = require("node:tty");
+const { build, boolean, number, tty, pipe } = require("./build");
+const { getColorDepth } = require("./detect");
+/**
+@typedef {import("./types").ColorDepth} ColorDepth
+@typedef {import("./types").Features}   Features
+
+@typedef {
+    | [enabled    : boolean,           stream?: NodeJS.WriteStream]
+    | [colorDepth : ColorDepth,        stream?: NodeJS.WriteStream]
+    | [features   : Partial<Features>, stream?: NodeJS.WriteStream]
+    | [socket     : Socket]
+    | [stream?    : NodeJS.WriteStream]
+} Args
+*/
+/** @type {(...args: Args) => Features} */
+function getFeatures(...args) {
+    let [features, stream] = args;
+    if (typeof features === "boolean")
+        return boolean((stream ?? process.stdout).isTTY, features);
+    if (typeof features === "number")
+        return number((stream ?? process.stdout).isTTY, features);
+    if (!features || typeof features !== "object")
+        features = (stream ?? process.stdout);
+    if (features instanceof WriteStream)
+        return tty(features);
+    if (features instanceof Socket)
+        return pipe();
+    const { colorDepth, style, caret, erase, scroll } = features;
+    stream ??= process.stdout;
+    if (colorDepth)
+        build(stream.isTTY, colorDepth, style, caret, erase, scroll);
+    if (stream.isTTY)
+        return build(true, getColorDepth(stream), style, caret, erase, scroll);
+    return build(false, getColorDepth(), style, caret, erase, scroll);
+}
+module.exports = { getFeatures };

package/dist/features/index.d.ts

@@ -0,0 +1,2 @@
+declare const _exports: typeof import("./features");
+export = _exports;

package/dist/features/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./features");

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+declare const _exports: ((...args: Args) => Ansi) & {
+    fg: Channel;
+    bg: Channel;
+} & {
+    caret: ReturnType<(enabled?: boolean) => {
+        up: (count?: number) => string;
+        down: (count?: number) => string;
+        forward: (count?: number) => string;
+        backward: (count?: number) => string;
+        nextLine: (count?: number) => string;
+        prevLine: (count?: number) => string;
+        x: (x: number) => string;
+        save: string;
+        restore: string;
+        hide: string;
+        show: string;
+        position: {
+            get: string;
+            set: (x: number, y: number) => string;
+        };
+        shape: {
+            steadyBlock: string;
+            steadyBar: string;
+            steadyUnderline: string;
+            blinkingBlock: string;
+            blinkingBar: string;
+            blinkingUnderline: string;
+            default: string;
+        };
+    }>;
+    erase: ReturnType<(enabled?: boolean) => {
+        line: {
+            toStart: string;
+            toEnd: string;
+            full: string;
+        };
+        screen: {
+            toStart: string;
+            toEnd: string;
+            full: string;
+            scrollback: string;
+        };
+    }>;
+    scroll: ReturnType<(enabled?: boolean) => {
+        up: (lines?: number) => string;
+        down: (lines?: number) => string;
+    }>;
+    reset: string;
+    style: ReturnType<typeof import("./sgr/style").makeStyle>;
+    padEnd: (text: string, targetLength: number, fillString?: string) => string;
+    padStart: (text: string, targetLength: number, fillString?: string) => string;
+    strip: (text: string) => string;
+    visibleLength: (text: string) => number;
+    sanitize: (text: string) => string;
+    slice: typeof import("./slice").slice;
+    simplify: typeof import("./simplify/simplify").simplify;
+    features: ReturnType<typeof import("./features/features").getFeatures>;
+};
+export = _exports;

package/dist/index.js

@@ -0,0 +1,2 @@
+"use strict";
+module.exports = require("./ansi");

package/dist/pad.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pad the given text at the end with the specified fill string to the target visible length without
+ * counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+export const padEnd: (text: string, targetLength: number, fillString?: string) => string;
+/**
+ * Pad the given text at the start with the specified fill string to the target visible length
+ * without counting ANSI escape codes.
+ * @type {(text: string, targetLength: number, fillString?: string) => string}
+ */
+export const padStart: (text: string, targetLength: number, fillString?: string) => string;