@peteanderson/ansi 0.2.4 → 0.3.0

package/dist/simplify/utils.js

@@ -0,0 +1,31 @@
+"use strict";
+/** @type {<T>(a: T[] | undefined, b: T[] | undefined) => boolean} */
+function arraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+/** @type {(previous: number[] | undefined, current: number[]) => number[]} */
+function transitionIntensity(previous, current) {
+    if (!previous || previous[0] === 22 || current[0] === 22)
+        return current;
+    const oldBold = previous[0] === 1;
+    const newBold = current[0] === 1;
+    const oldDim = previous[previous.length - 1] === 2;
+    const newDim = current[current.length - 1] === 2;
+    const result = [];
+    if (oldBold && !newBold || oldDim && !newDim)
+        result.push(22);
+    if (newBold && (!oldBold || result[0] === 22))
+        result.push(1);
+    if (newDim && (!oldDim || result[0] === 22))
+        result.push(2);
+    return result;
+}
+module.exports = { arraysEqual, transitionIntensity };

package/dist/slice.d.ts

@@ -0,0 +1 @@
+export function slice(text: string, start: number, end: number): string;

package/dist/slice.js

@@ -0,0 +1,83 @@
+"use strict";
+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) {
+    // We intentionally mutate `lastIndex` here, so we need a clone.
+    const rx = new RegExp(rxCSI);
+    let length = 0;
+    let index = fromStringIndex;
+    while (index < text.length && length < visibleCount) {
+        if (text[index] === "\x1b") {
+            rx.lastIndex = index;
+            const match = rx.exec(text);
+            if (match?.index === index) {
+                index += match[0].length;
+                continue;
+            }
+        }
+        index++;
+        length++;
+    }
+    return { index, length };
+}
+/** @type {(text: string, start: number, end?: number) => string} */
+function skippedSequences(text, start, end) {
+    const sequences = text.slice(start, end).match(new RegExp(rxSGR));
+    return sequences ? simplify(sequences.join("")) : "";
+}
+/**
+ * Return a slice of the given text, counting only visible characters (i.e. ignoring ANSI escape
+ * codes). The returned slice will include any ANSI escape codes from within the slice. In addition,
+ * SGR codes (m) from before and after the slice will be combined, simplified, and included so that
+ * the terminal state before and after the slice will be the same as if the whole string were
+ * printed. If you compose two or more slices together, there may be redundant SGR sequences at the
+ * boundaries, but the result will be correct. You can use `simplify` to remove the redundancies.
+ *
+ * Note the following caveats:
+ *
+ *   * Any non-SGR ANSI codes prior to or after the slice will be ignored.
+ *   * Control characters (such as newlines and backspaces) both outside and inside the slice are
+ *     counted as visible characters.
+ *
+ * These caveats mean that text may not appear on screen to be the same number of characters as the
+ * 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;
+    const getVisibleLength = () => textVisibleLength ??= visibleLength(text);
+    if (start < 0 || end < 0) {
+        textVisibleLength = getVisibleLength();
+        if (start < 0)
+            start = Math.max(0, textVisibleLength + start);
+        if (end < 0)
+            end = Math.max(0, textVisibleLength + end);
+    }
+    if (start > end)
+        return "";
+    if (start === 0 && (end >= text.length || end >= getVisibleLength()))
+        return text;
+    const { index: startIndex, length: visibleSkipped } = scanCSI(text, 0, start);
+    const endIndex = startIndex < text.length && visibleSkipped < 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/dist/strip.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Remove all ANSI escape codes from the given text.
+ * @type {(text: string) => string}
+ */
+export const strip: (text: string) => string;
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+export const visibleLength: (text: string) => number;
+/**
+ * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
+ * @type {(text: string) => string}
+ */
+export const sanitize: (text: string) => string;

package/dist/strip.js

@@ -0,0 +1,18 @@
+"use strict";
+const { rxCSI, rxUnsafe } = require("./patterns");
+/**
+ * Remove all ANSI escape codes from the given text.
+ * @type {(text: string) => string}
+ */
+const strip = text => text.replace(new RegExp(rxCSI), "");
+/**
+ * Calculate the visible length of a string with ANSI escape codes stripped.
+ * @type {(text: string) => number}
+ */
+const visibleLength = text => strip(text).length;
+/**
+ * Remove all ANSI escape codes except SGR codes (m), which are used for color and styling.
+ * @type {(text: string) => string}
+ */
+const sanitize = text => text.replace(new RegExp(rxUnsafe), "");
+module.exports = { strip, visibleLength, sanitize };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name"            : "@peteanderson/ansi",
-	"version"         : "0.2.4",
+	"version"         : "0.3.0",
 	"description"     : "ANSI escape sequence generation with automatic feature detection",
 	"author"          : {
 		"name"  : "Pete Anderson",
@@ -8,32 +8,25 @@
 	},
 	"repository"      : {
 		"type" : "git",
-		"url"  : "https://github.com/anderson-pete/ansi"
+		"url"  : "git+https://github.com/anderson-pete/ansi.git"
 	},
-	"keywords"        : [
-		"ansi",
-		"nodejs",
-		"color",
-		"terminal",
-		"cli"
-	],
-	"engines"         : {
-		"node": ">=18"
-	},
-	"files"           : [
-		"."
-	],
-	"main"            : "ansi.js",
-	"types"           : "ansi.d.ts",
+	"keywords"        : ["ansi", "nodejs", "color", "terminal", "cli"],
+	"engines"         : {"node": ">=18"},
+	"files"           : ["dist", "src"],
+	"main"            : "dist/ansi.js",
+	"types"           : "dist/ansi.d.ts",
 	"exports"         : {
 		".": {
-			"require": "./ansi.js"
+			"types"   : "./dist/ansi.d.ts",
+			"require" : "./dist/ansi.js"
 		}
 	},
 	"license"         : "MIT",
 	"scripts"         : {
-		"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"
+		"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"
 	},
 	"devDependencies" : {
 		"@types/node" : "^26.0.0",

package/src/ansi.js

@@ -0,0 +1,58 @@
+"use strict";
+
+const {makeCaret}                       = require("./caret");
+const {makeErase}                       = require("./erase");
+const {getFeatures}                     = require("./features");
+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>;
+
+	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),
+
+		strip,
+		visibleLength,
+		sanitize,
+		slice,
+		simplify,
+
+		features,
+	};
+}
+
+const ansi = Object.assign(makeAnsi, makeAnsi());
+
+module.exports = ansi;

package/src/caret.js

@@ -0,0 +1,86 @@
+"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/src/erase.js

@@ -0,0 +1,34 @@
+"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/src/features/build.js

@@ -0,0 +1,60 @@
+"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/src/features/detect.js

@@ -0,0 +1,39 @@
+"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/src/features/features.js

@@ -0,0 +1,53 @@
+"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/src/features/index.js

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

package/src/features/types.d.ts

@@ -0,0 +1,9 @@
+export type ColorDepth = 1 | 3 | 4 | 8 | 24;
+
+export interface Features {
+	colorDepth : ColorDepth;
+	style      : boolean;
+	caret      : boolean;
+	erase      : boolean;
+	scroll     : boolean;
+}

package/src/index.js

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

package/src/patterns.js

@@ -0,0 +1,44 @@
+/*
+I'm freezing these to prevent accidental mutation of the `lastIndex` property, which could keep
+future calls from starting at the beginning of the string.
+
+Code using these objects will have to clone them (with `new RegExp(rx)`) before using functions
+that modify `lastIndex` (such as `exec`). But according to my benchmarks, cloning the regex takes
+mere nanoseconds, and it wasn't even measurable when operating on longer strings. V8 clearly uses a
+global cache of compiled regexes. I assume that SpiderMonkey does the same thing.
+
+Here are my `timeit` benchmark results:
+
+```js
+const {timeit} = require("$timeit");
+
+const rxSGR = /\x1b\[[\d;]*m/g;
+const short = "\x1b[31mred \x1b[32mgreen \x1b[34mblue \x1b[0m";
+const long  = short.repeat(1000);
+
+timeit(() => short.replace(rxSGR, ""),                         {description: "short - no clone     "});
+timeit(() => short.replace(new RegExp(rxSGR), ""),             {description: "short - clone object "});
+timeit(() => short.replace(new RegExp(rxSGR.source, "g"), ""), {description: "short - clone source "});
+
+console.log();
+
+timeit(() => long .replace(rxSGR, ""),                         {description: "long  - no clone     "});
+timeit(() => long .replace(new RegExp(rxSGR), ""),             {description: "long  - clone object "});
+timeit(() => long .replace(new RegExp(rxSGR.source, "g"), ""), {description: "long  - clone source "});
+
+// Output:
+// short - no clone     : 82.73 ns (12,087,731 in 1.000016982 s)
+// short - clone object : 142.132 ns (7,035,692 in 1.0000001770000002 s)
+// short - clone source : 127.872 ns (7,820,293 in 1.00000017 s)
+//
+// long  - no clone     : 47.953 ųs (20,854 in 1.0000098149999999 s)
+// long  - clone object : 46.713 ųs (21,408 in 1.0000285520000003 s)
+// long  - clone source : 46.491 ųs (21,510 in 1.000026492 s)
+```
+*/
+
+const rxSGR    = Object.freeze(/\x1b\[[\d;]*m/g);
+const rxCSI    = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-~]/g);
+const rxUnsafe = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-ln-~]/g); // Everything except SGR codes (m).
+
+module.exports = {rxSGR, rxCSI, rxUnsafe};

package/src/scroll.js

@@ -0,0 +1,18 @@
+"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};