@peteanderson/ansi 0.3.2 → 1.0.0

package/src/simplify/{types.d.ts → types.ts}

@@ -12,7 +12,7 @@ export type Attribute =
 	| "reset"
 	| number;
 
-type AttributeMap = Map<Attribute, number[]>;
+export type AttributeMap = Map<Attribute, number[]>;
 
 export interface Atom {
 	attribute : Attribute;
@@ -21,8 +21,8 @@ export interface Atom {
 }
 
 export type BuildAtom = (
-	attribute: Attribute,
-	codes    : number[],
-	index    : number,
-	state    : AttributeMap,
+	attribute : Attribute,
+	codes     : number[],
+	index     : number,
+	state     : AttributeMap,
 ) => Atom;

package/src/simplify/{utils.js → utils.ts}

@@ -1,7 +1,4 @@
-"use strict";
-
-/** @type {<T>(a: T[] | undefined, b: T[] | undefined) => boolean} */
-function arraysEqual(a, b) {
+export function arraysEqual<T>(a: T[] | undefined, b: T[] | undefined): boolean {
 	if (a === b)
 		return true;
 
@@ -16,8 +13,7 @@ function arraysEqual(a, b) {
 	return true;
 }
 
-/** @type {(previous: number[] | undefined, current: number[]) => number[]} */
-function transitionIntensity(previous, current) {
+export function transitionIntensity(previous: number[] | undefined, current: number[]): number[] {
 	if (!previous || previous[0] === 22 || current[0] === 22)
 		return current;
 
@@ -26,7 +22,7 @@ function transitionIntensity(previous, current) {
 	const oldDim  = previous[previous.length - 1] === 2;
 	const newDim  = current[current.length - 1] === 2;
 
-	const result = [];
+	const result: number[] = [];
 
 	if (oldBold && !newBold || oldDim && !newDim)
 		result.push(22);
@@ -36,6 +32,4 @@ function transitionIntensity(previous, current) {
 		result.push(2);
 
 	return result;
-}
-
-module.exports = {arraysEqual, transitionIntensity};
+}

package/src/{slice.js → slice.ts}

@@ -1,19 +1,12 @@
-"use strict";
+import {rxCSI, rxSGR}  from "./patterns";
+import {simplify}      from "./simplify";
+import {visibleLength} from "./strip";
 
-const {rxCSI, rxSGR}  = require("./patterns");
-const {simplify}      = require("./simplify");
-const {visibleLength} = require("./strip");
-
-/**
-@type {
-	(
-		text            : string,
-		fromStringIndex : number,
-		visibleCount    : number,
-	) => {index: number, length: number}
-}
-*/
-function scanCSI(text, fromStringIndex, visibleCount) {
+function scanCSI(
+	text            : string,
+	fromStringIndex : number,
+	visibleCount    : number,
+): {index: number; length: number} {
 	// We intentionally mutate `lastIndex` here, so we need a clone.
 	const rx = new RegExp(rxCSI);
 
@@ -37,8 +30,7 @@ function scanCSI(text, fromStringIndex, visibleCount) {
 	return {index, length};
 }
 
-/** @type {(text: string, start: number, end?: number) => string} */
-function skippedSequences(text, start, end) {
+function skippedSequences(text: string, start: number, end?: number): string {
 	const sequences = text.slice(start, end).match(new RegExp(rxSGR));
 	return sequences ? simplify(sequences.join("")) : "";
 }
@@ -61,12 +53,9 @@ function skippedSequences(text, start, end) {
  * length of the slice, and that the terminal state may not be exactly the same at the start and end
  * of the slice as it would be if the whole string were printed. This function is intended mostly
  * for text that contains SGR codes, but no other ANSI codes or control characters.
- *
- * @type {(text: string, start: number, end: number) => string}
  */
-function slice(text, start, end) {
-	/** @type {number | undefined} */
-	let textVisibleLength;
+export function slice(text: string, start: number, end: number): string {
+	let textVisibleLength: number | undefined;
 	const getVisibleLength = () => textVisibleLength ??= visibleLength(text);
 
 	if (start < 0 || end < 0) {
@@ -89,11 +78,8 @@ function slice(text, start, end) {
 			? scanCSI(text, startIndex, end - visibleSkipped).index
 			: text.length;
 
-	// Start and end the string in the same terminal state it would be in if the string weren't sliced.
 	const leadingSequences  = skippedSequences(text, 0, startIndex);
 	const trailingSequences = skippedSequences(text, endIndex);
 
 	return leadingSequences + text.slice(startIndex, endIndex) + trailingSequences;
-}
-
-module.exports = {slice};
+}

package/src/strip.ts

@@ -0,0 +1,5 @@
+import {rxCSI, rxUnsafe} from "./patterns";
+
+export const strip         = (text: string): string => text.replace(new RegExp(rxCSI), "");
+export const visibleLength = (text: string): number => strip(text).length;
+export const sanitize      = (text: string): string => text.replace(new RegExp(rxUnsafe), "");

package/src/{terminal.js → terminal.ts}

@@ -1,5 +1,3 @@
-"use strict";
-
 const terminal = {
 	focusReporting: {
 		enable  : "\x1b[?1004h",
@@ -26,8 +24,9 @@ const terminal = {
 	},
 };
 
-/** @type {typeof terminal} */
-const disabled = {
+export type Terminal = typeof terminal;
+
+const disabled: Terminal = {
 	focusReporting: {
 		enable  : "",
 		disable : "",
@@ -53,6 +52,4 @@ const disabled = {
 	},
 };
 
-const makeTerminal = (enabled = true) => enabled ? terminal : disabled;
-
-module.exports = {makeTerminal};
+export const makeTerminal = (enabled = true): Terminal => enabled ? terminal : disabled;

package/LICENSE

@@ -1,7 +0,0 @@
-Copyright 2026 Pete Anderson
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,174 +0,0 @@
-# @peteanderson/ansi
-
-ANSI escape sequence helpers for Node.js terminal output. Automatically detects terminal
-capabilities and adapts output accordingly.
-
-## Installation
-
-```sh
-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"));
-
-// 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});
-```
-
-## 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**: 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:
-
-- 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
-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
-
-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
-
-### `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.
-
-### `reset`
-
-The SGR reset sequence. Empty string if color is disabled.
-
-### `caret`
-
-Available if feature is enabled:
-
-- `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)
-
-### `terminal`
-
-Terminal control features (available if feature is enabled):
-
-- `terminal.focusReporting.enable` / `terminal.focusReporting.disable` - enable/disable focus
-  reporting
-- `terminal.alternateBuffer.on` / `terminal.alternateBuffer.off` - switch to/from alternate buffer
-- `terminal.alternateBuffer.legacy.on` / `terminal.alternateBuffer.legacy.off` - use legacy
-  alternate buffer sequences
-- `terminal.bracketedPasteMode.enable` / `terminal.bracketedPasteMode.disable` - enable/disable
-  bracketed paste mode
-
-### `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;
-    terminal   : boolean;
-}
-```
-
-## License
-
-MIT

package/src/ansi.js

@@ -1,70 +0,0 @@
-"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");
-const {makeTerminal}                    = require("./terminal");
-
-/**
-@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>;
-
-	terminal : ReturnType<typeof makeTerminal>;
-
-	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),
-
-		terminal: makeTerminal(features.terminal),
-
-		padEnd,
-		padStart,
-
-		strip,
-		visibleLength,
-		sanitize,
-		slice,
-		simplify,
-
-		features,
-	};
-}
-
-const ansi = Object.assign(makeAnsi, makeAnsi());
-
-module.exports = ansi;

package/src/features/build.js

@@ -1,68 +0,0 @@
-"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,
-		terminal?  : boolean,
-	) => Features
-}
-*/
-function build(isTTY, colorDepth, style, caret, erase, scroll, terminal) {
-	if (
-		style    !== undefined &&
-		caret    !== undefined &&
-		erase    !== undefined &&
-		scroll   !== undefined &&
-		terminal !== undefined
-	)
-		return {colorDepth: normalizeColorDepth(colorDepth), style, caret, erase, scroll, terminal};
-
-	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,
-		terminal   : terminal ?? support.terminal,
-	};
-}
-
-/** @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/src/features/detect.js

@@ -1,40 +0,0 @@
-"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,
-		terminal : enabled,
-	};
-}
-
-module.exports = {detectFeatureSupport, getColorDepth}

package/src/features/features.js

@@ -1,53 +0,0 @@
-"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, terminal} = features;
-
-	stream ??= process.stdout;
-
-	if (colorDepth)
-		build(stream.isTTY, colorDepth, style, caret, erase, scroll, terminal);
-
-	if (stream.isTTY)
-		return build(true, getColorDepth(stream), style, caret, erase, scroll, terminal);
-
-	return build(false, getColorDepth(), style, caret, erase, scroll, terminal);
-}
-
-module.exports = {getFeatures};

package/src/features/index.js

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

package/src/index.js

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

package/src/pad.js

@@ -1,21 +0,0 @@
-"use strict";
-
-const {visibleLength} = require("./strip");
-
-/**
- * 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}
- */
-const padEnd = (text, targetLength, fillString = " ") =>
-	text + fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length);
-
-/**
- * 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}
- */
-const padStart = (text, targetLength, fillString = " ") =>
-	fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length) + text;
-
-module.exports = {padEnd, padStart};

package/src/scroll.js

@@ -1,18 +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`,
-};
-
-/** @type {typeof scroll} */
-const disabled = {
-	up   : () => "",
-	down : () => "",
-};
-
-const makeScroll = (enabled = true) => enabled ? scroll : disabled;
-
-module.exports = {makeScroll};

package/src/sgr/color/index.js

@@ -1 +0,0 @@
-module.exports = require("./color");