@peteanderson/ansi 0.2.2 → 0.2.4

package/README.md

@@ -1,6 +1,6 @@
 # @peteanderson/ansi
 
-ANSI escape sequence helpers for Node.js terminal output.
+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.
 
 ## Installation
 
@@ -11,89 +11,54 @@ npm install @peteanderson/ansi
 ## Usage
 
 ```js
-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"));
-console.log(ansi.strip("styled text")); // remove all ANSI codes
-console.log(ansi.slice("styled text", 0, 5)); // slice by visible length
-console.log(ansi.simplify(styledText)); // combine adjacent SGR sequences
+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'
 ```
 
 ## API
 
-### `fg` — foreground colors
+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.
 
-Functions that wrap text with color codes:
+### `fg` — foreground colors
 
-- 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 (r, g, b in 0–5 or grayscale 232–255)
-- `fg.x256(code)(text)` or `fg.x256(r, g, b)(text)` - 256-color palette
+`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white` `gray`
 
-All return functions with `open` and `close` properties for raw sequences.
+```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
+```
 
 ### `bg` — background colors
 
-Functions that wrap text with color codes:
+`black` `red` `green` `yellow` `blue` `magenta` `cyan` `white`
 
-- 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
-- `bg.x256(code)(text)` or `bg.x256(r, g, b)(text)` - 256-color palette
+```js
+bg.green('text')
+bg.rgb(r, g, b)('text')
+```
 
 ### `style`
 
-Functions that wrap text with style codes:
-
-`bold` `dim` `italic` `underline` `inverse` `hidden` `strikethrough` `doubleUnderline` `framed`
-`encircled` `overline`
-
-All return functions with `open` and `close` properties for raw sequences.
-
-### `caret`
-
-- `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)
+`bold` `dim` `italic` `underline` `inverse` `hidden` `strikethrough`
 
-### `erase`
-
-- `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`
-
-- `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.
-
-### `slice(text, start, end)`
-
-Slices a string by visible characters, ignoring ANSI sequences. Works like `String.prototype.slice`
-but counts only visible characters.
+```js
+style.bold('text')
+style.italic(style.bold('text'))
+```
 
-### `sanitize(text)`
+### `reset`
 
-Removes "unsafe" CSI sequences (non-SGR), leaving only color and style codes.
+The SGR reset sequence (`\x1b[0m`). An empty string when color is disabled.
 
-### `simplify(text)`
+### `stripAnsiSequences(text)`
 
-Simplifies ANSI SGR sequences by combining adjacent sequences and removing redundant codes. Useful
-for optimizing styled strings.
+Removes ANSI SGR escape sequences from a string.
 
 ## License
 

package/ansi.js

@@ -0,0 +1,28 @@
+"use strict";
+
+const caret                            = require("./caret");
+const erase                            = require("./erase");
+const scroll                           = require("./scroll");
+const {bg, fg, reset, style}           = require("./sgr");
+const {simplify}                       = require("./simplify");
+const {slice}                          = require("./slice");
+const {sanitize, strip, visibleLength} = require("./strip");
+
+const ansi = {
+	caret,
+	erase,
+	scroll,
+
+	reset,
+	style,
+	fg,
+	bg,
+
+	strip,
+	visibleLength,
+	sanitize,
+	slice,
+	simplify,
+};
+
+module.exports = ansi;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name"            : "@peteanderson/ansi",
-	"version"         : "0.2.2",
+	"version"         : "0.2.4",
 	"description"     : "ANSI escape sequence generation with automatic feature detection",
 	"author"          : {
 		"name"  : "Pete Anderson",
@@ -8,25 +8,32 @@
 	},
 	"repository"      : {
 		"type" : "git",
-		"url"  : "git+https://github.com/anderson-pete/ansi.git"
+		"url"  : "https://github.com/anderson-pete/ansi"
 	},
-	"keywords"        : ["ansi", "nodejs", "color", "terminal", "cli"],
-	"engines"         : {"node": ">=18"},
-	"files"           : ["dist", "src"],
-	"main"            : "dist/ansi.js",
-	"types"           : "dist/ansi.d.ts",
+	"keywords"        : [
+		"ansi",
+		"nodejs",
+		"color",
+		"terminal",
+		"cli"
+	],
+	"engines"         : {
+		"node": ">=18"
+	},
+	"files"           : [
+		"."
+	],
+	"main"            : "ansi.js",
+	"types"           : "ansi.d.ts",
 	"exports"         : {
 		".": {
-			"types"   : "./dist/ansi.d.ts",
-			"require" : "./dist/ansi.js"
+			"require": "./ansi.js"
 		}
 	},
 	"license"         : "MIT",
 	"scripts"         : {
-		"prebuild" : "node -e \"require('node:fs').rmSync('dist', {force: true, recursive: true})\"",
-		"build"    : "tsc -p tsconfig.build.json",
-		"prepack"  : "npm run build",
-		"tag"      : "git tag -a v$npm_package_version -m v$npm_package_version"
+		"build" : "rm *.d.ts && tsc --allowJs --declaration --emitDeclarationOnly --moduleResolution node --ignoreDeprecations 6.0 ansi.js",
+		"tag"   : "git tag -a v$npm_package_version -m v$npm_package_version"
 	},
 	"devDependencies" : {
 		"@types/node" : "^26.0.0",

package/dist/ansi.d.ts

@@ -1,12 +0,0 @@
-import caret = require("./caret");
-import erase = require("./erase");
-import scroll = require("./scroll");
-import { reset } from "./sgr/reset";
-import { style } from "./sgr/style";
-import { fg } from "./sgr/color";
-import { bg } from "./sgr/color";
-import { strip } from "./strip";
-import { sanitize } from "./strip";
-import { slice } from "./strip";
-import { simplify } from "./simplify/simplify";
-export { caret, erase, scroll, reset, style, fg, bg, strip, sanitize, slice, simplify };

package/dist/ansi.js

@@ -1,21 +0,0 @@
-"use strict";
-const caret = require("./caret");
-const erase = require("./erase");
-const scroll = require("./scroll");
-const { bg, fg, reset, style } = require("./sgr");
-const { simplify } = require("./simplify");
-const { sanitize, slice, strip } = require("./strip");
-const ansi = {
-    caret,
-    erase,
-    scroll,
-    reset,
-    style,
-    fg,
-    bg,
-    strip,
-    sanitize,
-    slice,
-    simplify,
-};
-module.exports = ansi;

package/dist/caret.d.ts

@@ -1,25 +0,0 @@
-export let up: (count?: number) => string;
-export let down: (count?: number) => string;
-export let forward: (count?: number) => string;
-export let backward: (count?: number) => string;
-export let nextLine: (count?: number) => string;
-export let prevLine: (count?: number) => string;
-export let x: (x: number) => string;
-export let save: string;
-export let restore: string;
-export let hide: string;
-export let show: string;
-export namespace position {
-    let get: string;
-    let set: (x: number, y: number) => string;
-}
-export namespace shape {
-    export let steadyBlock: string;
-    export let steadyBar: string;
-    export let steadyUnderline: string;
-    export let blinkingBlock: string;
-    export let blinkingBar: string;
-    export let blinkingUnderline: string;
-    let _default: string;
-    export { _default as default };
-}

package/dist/caret.js

@@ -1,40 +0,0 @@
-"use strict";
-/** @type {(code: string) => (count?: number) => string} */
-const move = code => count => `\x1b[${count === undefined ? "" : count ? count : "?"}${code}`;
-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",
-    },
-};
-module.exports = caret;

package/dist/erase.d.ts

@@ -1,14 +0,0 @@
-export namespace line {
-    let toStart: string;
-    let toEnd: string;
-    let full: string;
-}
-export namespace screen {
-    let toStart_1: string;
-    export { toStart_1 as toStart };
-    let toEnd_1: string;
-    export { toEnd_1 as toEnd };
-    let full_1: string;
-    export { full_1 as full };
-    export let scrollback: string;
-}

package/dist/erase.js

@@ -1,15 +0,0 @@
-"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",
-    },
-};
-module.exports = erase;

package/dist/index.d.ts

@@ -1,106 +0,0 @@
-declare const _exports: {
-    caret: {
-        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: {
-        line: {
-            toStart: string;
-            toEnd: string;
-            full: string;
-        };
-        screen: {
-            toStart: string;
-            toEnd: string;
-            full: string;
-            scrollback: string;
-        };
-    };
-    scroll: {
-        up: (lines?: number) => string;
-        down: (lines?: number) => string;
-    };
-    reset: string;
-    style: {
-        bold: import("./sgr/sgr").SGR;
-        dim: import("./sgr/sgr").SGR;
-        italic: import("./sgr/sgr").SGR;
-        underline: import("./sgr/sgr").SGR;
-        inverse: import("./sgr/sgr").SGR;
-        hidden: import("./sgr/sgr").SGR;
-        strikethrough: import("./sgr/sgr").SGR;
-        doubleUnderline: import("./sgr/sgr").SGR;
-        frame: import("./sgr/sgr").SGR;
-        encircle: import("./sgr/sgr").SGR;
-        overline: import("./sgr/sgr").SGR;
-    };
-    fg: {
-        black: import("./sgr/sgr").SGR;
-        red: import("./sgr/sgr").SGR;
-        green: import("./sgr/sgr").SGR;
-        yellow: import("./sgr/sgr").SGR;
-        blue: import("./sgr/sgr").SGR;
-        magenta: import("./sgr/sgr").SGR;
-        cyan: import("./sgr/sgr").SGR;
-        white: import("./sgr/sgr").SGR;
-        brightBlack: import("./sgr/sgr").SGR;
-        brightRed: import("./sgr/sgr").SGR;
-        brightGreen: import("./sgr/sgr").SGR;
-        brightYellow: import("./sgr/sgr").SGR;
-        brightBlue: import("./sgr/sgr").SGR;
-        brightMagenta: import("./sgr/sgr").SGR;
-        brightCyan: import("./sgr/sgr").SGR;
-        brightWhite: import("./sgr/sgr").SGR;
-        default: string;
-        rgb: (r: number, g: number, b: number) => (text: string) => string;
-        x256: (arg0: number, arg1?: number, arg2?: number) => (text: string) => string;
-    };
-    bg: {
-        black: import("./sgr/sgr").SGR;
-        red: import("./sgr/sgr").SGR;
-        green: import("./sgr/sgr").SGR;
-        yellow: import("./sgr/sgr").SGR;
-        blue: import("./sgr/sgr").SGR;
-        magenta: import("./sgr/sgr").SGR;
-        cyan: import("./sgr/sgr").SGR;
-        white: import("./sgr/sgr").SGR;
-        brightBlack: import("./sgr/sgr").SGR;
-        brightRed: import("./sgr/sgr").SGR;
-        brightGreen: import("./sgr/sgr").SGR;
-        brightYellow: import("./sgr/sgr").SGR;
-        brightBlue: import("./sgr/sgr").SGR;
-        brightMagenta: import("./sgr/sgr").SGR;
-        brightCyan: import("./sgr/sgr").SGR;
-        brightWhite: import("./sgr/sgr").SGR;
-        default: string;
-        rgb: (r: number, g: number, b: number) => (text: string) => string;
-        x256: (arg0: number, arg1?: number, arg2?: number) => (text: string) => string;
-    };
-    strip: (text: string) => string;
-    sanitize: (text: string) => string;
-    slice: typeof import("./strip").slice;
-    simplify: typeof import("./simplify/simplify").simplify;
-};
-export = _exports;

package/dist/index.js

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

package/dist/scroll.d.ts

@@ -1,2 +0,0 @@
-export let up: (lines?: number) => string;
-export let down: (lines?: number) => string;

package/dist/scroll.js

@@ -1,8 +0,0 @@
-"use strict";
-const scroll = {
-    /** @type {(lines?: number) => string} */
-    up: lines => `\x1b[${lines ?? 1}S`,
-    /** @type {(lines?: number) => string} */
-    down: lines => `\x1b[${lines ?? 1}T`,
-};
-module.exports = scroll;

package/dist/sgr/color.d.ts

@@ -1,62 +0,0 @@
-export namespace fg {
-    export let black: import("./sgr").SGR;
-    export let red: import("./sgr").SGR;
-    export let green: import("./sgr").SGR;
-    export let yellow: import("./sgr").SGR;
-    export let blue: import("./sgr").SGR;
-    export let magenta: import("./sgr").SGR;
-    export let cyan: import("./sgr").SGR;
-    export let white: import("./sgr").SGR;
-    export let brightBlack: import("./sgr").SGR;
-    export let brightRed: import("./sgr").SGR;
-    export let brightGreen: import("./sgr").SGR;
-    export let brightYellow: import("./sgr").SGR;
-    export let brightBlue: import("./sgr").SGR;
-    export let brightMagenta: import("./sgr").SGR;
-    export let brightCyan: import("./sgr").SGR;
-    export let brightWhite: import("./sgr").SGR;
-    let _default: string;
-    export { _default as default };
-    export let rgb: (r: number, g: number, b: number) => (text: string) => string;
-    export let x256: (arg0: number, arg1?: number, arg2?: number) => (text: string) => string;
-}
-export namespace bg {
-    let black_1: import("./sgr").SGR;
-    export { black_1 as black };
-    let red_1: import("./sgr").SGR;
-    export { red_1 as red };
-    let green_1: import("./sgr").SGR;
-    export { green_1 as green };
-    let yellow_1: import("./sgr").SGR;
-    export { yellow_1 as yellow };
-    let blue_1: import("./sgr").SGR;
-    export { blue_1 as blue };
-    let magenta_1: import("./sgr").SGR;
-    export { magenta_1 as magenta };
-    let cyan_1: import("./sgr").SGR;
-    export { cyan_1 as cyan };
-    let white_1: import("./sgr").SGR;
-    export { white_1 as white };
-    let brightBlack_1: import("./sgr").SGR;
-    export { brightBlack_1 as brightBlack };
-    let brightRed_1: import("./sgr").SGR;
-    export { brightRed_1 as brightRed };
-    let brightGreen_1: import("./sgr").SGR;
-    export { brightGreen_1 as brightGreen };
-    let brightYellow_1: import("./sgr").SGR;
-    export { brightYellow_1 as brightYellow };
-    let brightBlue_1: import("./sgr").SGR;
-    export { brightBlue_1 as brightBlue };
-    let brightMagenta_1: import("./sgr").SGR;
-    export { brightMagenta_1 as brightMagenta };
-    let brightCyan_1: import("./sgr").SGR;
-    export { brightCyan_1 as brightCyan };
-    let brightWhite_1: import("./sgr").SGR;
-    export { brightWhite_1 as brightWhite };
-    let _default_1: string;
-    export { _default_1 as default };
-    let rgb_1: (r: number, g: number, b: number) => (text: string) => string;
-    export { rgb_1 as rgb };
-    let x256_1: (arg0: number, arg1?: number, arg2?: number) => (text: string) => string;
-    export { x256_1 as x256 };
-}

package/dist/sgr/color.js

@@ -1,111 +0,0 @@
-"use strict";
-const { sgr } = require("./sgr");
-/** @type {(r: number, g: number, b: number, open: number, close: number) => (text: string) => string} */
-const rgb = (r, g, b, open, close) => sgr([open, 2, r, g, b], close);
-/**
- * @overload
- * @param {number} code
- * @param {number} open
- * @param {number} close
- * @returns {(text: string) => string}
- */ /**
-* @overload
-* @param {number} r
-* @param {number} g
-* @param {number} b
-* @param {number} open
-* @param {number} close
-* @returns {(text: string) => string}
-*/ /**
-@type {
-   (
-       ...args: [number, number, number] | [number, number, number, number, number]
-   ) => (text: string) => string}
-*/
-function x256(...args) {
-    if (args.length === 3)
-        return sgr([args[1], 5, args[0]], args[2]);
-    const [r, g, b, open, close] = args;
-    if (r === g && g === b) {
-        // grayscale
-        return sgr([open, 5, 232 + Math.floor(r * 24 / 256)], close);
-    }
-    // 6x6x6 color cube
-    return sgr([
-        open,
-        5,
-        16 +
-            Math.floor(r * 6 / 256) * 36 +
-            Math.floor(g * 6 / 256) * 6 +
-            Math.floor(b * 6 / 256)
-    ], close);
-}
-const fg = {
-    black: sgr(30, 39),
-    red: sgr(31, 39),
-    green: sgr(32, 39),
-    yellow: sgr(33, 39),
-    blue: sgr(34, 39),
-    magenta: sgr(35, 39),
-    cyan: sgr(36, 39),
-    white: sgr(37, 39),
-    brightBlack: sgr(90, 39),
-    brightRed: sgr(91, 39),
-    brightGreen: sgr(92, 39),
-    brightYellow: sgr(93, 39),
-    brightBlue: sgr(94, 39),
-    brightMagenta: sgr(95, 39),
-    brightCyan: sgr(96, 39),
-    brightWhite: sgr(97, 39),
-    default: "\x1b[39m",
-    /** @type {(r: number, g: number, b: number) => (text: string) => string} */
-    rgb: (r, g, b) => rgb(r, g, b, 38, 39),
-    /**
-     * @overload
-     * @param {number} code
-     * @returns {(text: string) => string}
-     */ /**
-    * @param {number} r
-    * @param {number} g
-    * @param {number} b
-    * @returns {(text: string) => string}
-    */ /** @type {(arg0: number, arg1?: number, arg2?: number) => (text: string) => string} */
-    x256: (arg0, arg1, arg2) => arg1 === undefined || arg2 === undefined
-        ? x256(arg0, 38, 39)
-        : x256(arg0, arg1, arg2, 38, 39),
-};
-const bg = {
-    black: sgr(40, 49),
-    red: sgr(41, 49),
-    green: sgr(42, 49),
-    yellow: sgr(43, 49),
-    blue: sgr(44, 49),
-    magenta: sgr(45, 49),
-    cyan: sgr(46, 49),
-    white: sgr(47, 49),
-    brightBlack: sgr(100, 49),
-    brightRed: sgr(101, 49),
-    brightGreen: sgr(102, 49),
-    brightYellow: sgr(103, 49),
-    brightBlue: sgr(104, 49),
-    brightMagenta: sgr(105, 49),
-    brightCyan: sgr(106, 49),
-    brightWhite: sgr(107, 49),
-    default: "\x1b[49m",
-    /** @type {(r: number, g: number, b: number) => (text: string) => string} */
-    rgb: (r, g, b) => rgb(r, g, b, 48, 49),
-    /**
-     * @overload
-     * @param {number} code
-     * @returns {(text: string) => string}
-     */ /**
-    * @param {number} r
-    * @param {number} g
-    * @param {number} b
-    * @returns {(text: string) => string}
-    */ /** @type {(arg0: number, arg1?: number, arg2?: number) => (text: string) => string} */
-    x256: (arg0, arg1, arg2) => arg1 === undefined || arg2 === undefined
-        ? x256(arg0, 48, 49)
-        : x256(arg0, arg1, arg2, 48, 49),
-};
-module.exports = { fg, bg };