@peteanderson/ansi 0.3.2 → 1.0.0

package/src/features/build.ts

@@ -0,0 +1,52 @@
+import { getColorDepth, detectFeatureSupport } from "./detect";
+import type { ColorDepth, Features }           from "./types";
+
+function normalizeColorDepth(colorDepth: number): 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;
+}
+
+export function build(
+	isTTY      : boolean,
+	colorDepth : ColorDepth,
+	style?     : boolean,
+	caret?     : boolean,
+	erase?     : boolean,
+	scroll?    : boolean,
+	terminal?  : boolean,
+): Features {
+	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,
+	};
+}
+
+export const boolean = (isTTY: boolean, enabled: boolean): Features =>
+	build(isTTY, enabled ? 4 : 1);
+
+export const number = (isTTY: boolean, colorDepth: ColorDepth): Features =>
+	build(isTTY, colorDepth);
+
+export const tty = (stream: NodeJS.WriteStream): Features =>
+	build(true, getColorDepth(stream));
+
+export const pipe = (): Features =>
+	build(false, getColorDepth());

package/src/features/detect.ts

@@ -0,0 +1,33 @@
+import type { ColorDepth, Features } from "./types";
+
+export function getColorDepth(stream?: NodeJS.WriteStream): ColorDepth {
+	if (stream?.isTTY)
+		return stream.getColorDepth() as ColorDepth;
+
+	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;
+	}
+}
+
+export function detectFeatureSupport(isTTY: boolean, colorDepth: ColorDepth): Omit<Features, "colorDepth"> {
+	const enabled = process.env.TERM !== "dumb" && isTTY;
+	return {
+		style    : colorDepth > 1,
+		caret    : enabled,
+		erase    : enabled,
+		scroll   : enabled,
+		terminal : enabled,
+	};
+}

package/src/features/features.ts

@@ -0,0 +1,48 @@
+import { Socket }                            from "node:net";
+import { WriteStream }                       from "node:tty";
+import { build, boolean, number, tty, pipe } from "./build";
+import { getColorDepth }                     from "./detect";
+import type { ColorDepth, Features }         from "./types";
+
+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 {
+	const [first, second] = args as [
+		boolean | ColorDepth | Partial<Features> | Socket | NodeJS.WriteStream | undefined,
+		NodeJS.WriteStream | undefined,
+	];
+
+	if (typeof first === "boolean")
+		return boolean((second ?? process.stdout).isTTY, first);
+
+	if (typeof first === "number")
+		return number((second ?? process.stdout).isTTY, first);
+
+	let input: Partial<Features> | Socket | NodeJS.WriteStream =
+		!first || typeof first !== "object"
+			? second ?? process.stdout
+			: first;
+
+	if (input instanceof WriteStream)
+		return tty(input);
+
+	if (input instanceof Socket)
+		return pipe();
+
+	const {colorDepth, style, caret, erase, scroll, terminal} = input as Partial<Features>;
+
+	const stream = second ?? 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);
+}

package/src/features/index.ts

@@ -0,0 +1 @@
+export * from "./features";

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

@@ -7,4 +7,4 @@ export interface Features {
 	erase      : boolean;
 	scroll     : boolean;
 	terminal   : boolean;
-}
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export {default} from "./ansi";
+export *         from "./ansi";

package/src/pad.ts

@@ -0,0 +1,7 @@
+import {visibleLength} from "./strip";
+
+export const padEnd = (text: string, targetLength: number, fillString = " "): string =>
+	text + fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length);
+
+export const padStart = (text: string, targetLength: number, fillString = " "): string =>
+	fillString.repeat(Math.max(0, targetLength - visibleLength(text)) / fillString.length) + text;

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

@@ -37,8 +37,6 @@ timeit(() => long .replace(new RegExp(rxSGR.source, "g"), ""), {description: "lo
 ```
 */
 
-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};
+export const rxSGR    = Object.freeze(/\x1b\[[\d;]*m/g);
+export const rxCSI    = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-~]/g);
+export const rxUnsafe = Object.freeze(/\x1b\[[0-?]*[ -/]*[@-ln-~]/g); // Everything except SGR codes (m).

package/src/scroll.ts

@@ -0,0 +1,13 @@
+const scroll = {
+	up   : (lines?: number): string => `\x1b[${lines ?? 1}S`,
+	down : (lines?: number): string => `\x1b[${lines ?? 1}T`,
+};
+
+export type Scroll = typeof scroll;
+
+const disabled: Scroll = {
+	up   : () => "",
+	down : () => "",
+};
+
+export const makeScroll = (enabled = true): Scroll => enabled ? scroll : disabled;

package/src/sgr/color/{color.js → color.ts}

@@ -1,25 +1,23 @@
-const {makeSGR}                                       = require("../sgr");
-const {makeStyle}                                     = require("../style");
-const {clip, rgbToX256, rgbToX16, rgbToX8, x256ToRgb} = require("./utils");
+import {makeSGR}                                       from "../sgr";
+import {makeStyle}                                     from "../style";
+import {clip, rgbToX16, rgbToX256, rgbToX8, x256ToRgb} from "./utils";
 
-/** @typedef {import("../sgr").Code}                     Code */
-/** @typedef {import("../../features/types").ColorDepth} ColorDepth */
-/** @typedef {import("../sgr").SGR}                      SGR */
-/** @typedef {import("./types").Channel}                 Channel */
+import type {ColorDepth}     from "../../features/types";
+import type {SGR}            from "../sgr";
+import type {Channel, Color} from "./types";
+
+export type {Color} from "./types";
 
 const fgOpen = 30, fgClose = 39;
 const bgOpen = 40, bgClose = 49;
 
-/** @type {(colorDepth: ColorDepth, open: number, close: number) => Channel} */
-function makeChannel(colorDepth, open, close) {
+function makeChannel(colorDepth: ColorDepth, open: number, close: number): Channel {
 	const sgrBase = makeSGR(colorDepth > 1);
 	const style   = makeStyle(colorDepth > 1);
 
-	/** @type {(code: Code) => SGR} */
-	const sgr = code => sgrBase(code, close);
+	const sgr = (code: number | number[]): SGR => sgrBase(code, close);
 
-	/** @type {(index: number) => SGR} */
-	const bright =
+	const bright: (index: number) => SGR =
 		colorDepth >= 4 ? index => sgr(open + 60 + index) :
 		colorDepth === 3 ?
 			open === fgOpen ?
@@ -27,11 +25,10 @@ function makeChannel(colorDepth, open, close) {
 				index => sgr(open + index) :
 		() => sgr(0);
 
-	/** @type {(code: number) => SGR} */
-	const x16ToX8 =
+	const x16ToX8: (code: number) => SGR =
 		open === fgOpen ?
 			code => code >= 60 ? style.bold.combine(sgr(open + code - 60)) : sgr(open + code) :
-			code => code >= 60 ? sgr(open + code - 60) : sgr(open + code);
+			code => code >= 60 ? sgr(open + code - 60)                     : sgr(open + code);
 
 	return {
 		black   : sgr(open + 0),
@@ -62,43 +59,37 @@ function makeChannel(colorDepth, open, close) {
 					(r, g, b) => sgr(open + rgbToX8(...clip(r, g, b))) :
 			() => sgr(0),
 
-		/** @type {(...args: [number] | [number, number, number]) => SGR} */
 		x256:
 			colorDepth >= 8 ?
-				(...args) => sgr(
+				(...args: [number] | [number, number, number]): SGR => sgr(
 					[open + 8, 5, args.length === 3 ? rgbToX256(...clip(...args)) : clip(args[0])],
 				) :
 			colorDepth >= 4 ?
-				(...args) => sgr(
+				(...args: [number] | [number, number, number]): SGR => sgr(
 					open +
 					rgbToX16(...(args.length === 3 ? clip(...args) : x256ToRgb(clip(args[0])))),
 				) :
 			colorDepth === 3 ?
 				open === fgOpen ?
-					(...args) => x16ToX8(
-						args.length === 3 ?
-							rgbToX16(...clip(...args)) :
-							rgbToX16(...x256ToRgb(clip(args[0]))),
+					(...args: [number] | [number, number, number]): SGR => x16ToX8(
+						args.length === 3
+							? rgbToX16(...clip(...args))
+							: rgbToX16(...x256ToRgb(clip(args[0]))),
 					) :
-					(...args) => sgr(
-						open + rgbToX8(
-						...args.length === 3 ? clip(...args) : x256ToRgb(clip(args[0])),
-						),
+					(...args: [number] | [number, number, number]): SGR => sgr(
+						open +
+						rgbToX8(...args.length === 3 ? clip(...args) : x256ToRgb(clip(args[0]))),
 					) :
-			() => sgr(0),
+			(): SGR => sgr(0),
 
 		default: colorDepth > 1 ? `\x1b[${close}m` : "",
 	};
 }
 
-/** @type {Partial<Record<ColorDepth, {fg: Channel, bg: Channel}>>} */
-const cache = {};
+const cache: Partial<Record<ColorDepth, Color>> = {};
 
-/** @type {(colorDepth: ColorDepth) => {fg: Channel, bg: Channel}} */
-const makeColor = (colorDepth = 4) =>
+export const makeColor = (colorDepth: ColorDepth = 4): Color =>
 	cache[colorDepth] ?? (cache[colorDepth] = {
 		fg : makeChannel(colorDepth, fgOpen, fgClose),
 		bg : makeChannel(colorDepth, bgOpen, bgClose),
-	});
-
-module.exports = {makeColor};
+	});

package/src/sgr/color/index.ts

@@ -0,0 +1 @@
+export * from "./color";

package/src/sgr/color/{types.d.ts → types.ts}

@@ -1,3 +1,5 @@
+import type {SGR} from "../sgr";
+
 export interface Channel {
 	black   : SGR;
 	red     : SGR;
@@ -24,5 +26,7 @@ export interface Channel {
 		(r: number, g: number, b: number): SGR;
 	};
 
-	default: string,
-}
+	default: string;
+}
+
+export type Color = {fg: Channel; bg: Channel};

package/src/sgr/color/utils.ts

@@ -0,0 +1,58 @@
+export function rgbToX256(r: number, g: number, b: number): number {
+	if (r === g && g === b)
+		return 232 + Math.floor(r * 24 / 256);
+
+	return (
+		16 +
+		Math.floor(r * 6 / 256) * 36 +
+		Math.floor(g * 6 / 256) * 6 +
+		Math.floor(b * 6 / 256)
+	);
+}
+
+export function x256ToRgb(code: number): [number, number, number] {
+	if (code >= 232) {
+		const gray = Math.round((code - 232) * 255 / 24);
+		return [gray, gray, gray];
+	}
+
+	code -= 16;
+	const r = Math.floor(code / 36) * 51;
+	const g = Math.floor((code % 36) / 6) * 51;
+	const b = (code % 6) * 51;
+	return [r, g, b];
+}
+
+export function rgbToX16(r: number, g: number, b: number): number {
+	r = Math.min(2, Math.floor(r / 85));
+	g = Math.min(2, Math.floor(g / 85));
+	b = Math.min(2, Math.floor(b / 85));
+
+	const index = (r ? 1 : 0) | (g ? 2 : 0) | (b ? 4 : 0);
+
+	const twos   = (r === 2 ? 1 : 0) + (g === 2 ? 1 : 0) + (b === 2 ? 1 : 0);
+	const ones   = (r === 1 ? 1 : 0) + (g === 1 ? 1 : 0) + (b === 1 ? 1 : 0);
+	const bright = twos > 0 && twos >= ones;
+
+	return index + (bright ? 60 : 0);
+}
+
+export function rgbToX8(r: number, g: number, b: number): number {
+	r = r >= 128 ? 1 : 0;
+	g = g >= 128 ? 1 : 0;
+	b = b >= 128 ? 1 : 0;
+
+	return (r ? 1 : 0) | (g ? 2 : 0) | (b ? 4 : 0);
+}
+
+export function clip(x: number): number;
+export function clip(r: number, g: number, b: number): [number, number, number];
+export function clip(...args: [number] | [number, number, number]): number | [number, number, number] {
+	return args.length === 1
+		? Math.max(0, Math.min(255, Math.floor(args[0])))
+		: [
+			Math.max(0, Math.min(255, Math.floor(args[0]))),
+			Math.max(0, Math.min(255, Math.floor(args[1]))),
+			Math.max(0, Math.min(255, Math.floor(args[2]))),
+		];
+}

package/src/sgr/index.ts

@@ -0,0 +1,3 @@
+export * from "./reset";
+export * from "./style";
+export * from "./color";

package/src/sgr/reset.ts

@@ -0,0 +1 @@
+export const makeReset = (enabled = true): string => enabled ? "\x1b[0m" : "";

package/src/sgr/sgr.ts

@@ -0,0 +1,68 @@
+export type Code = number | number[];
+
+export interface SGR {
+	(text: string): string;
+	open    : string;
+	close   : string;
+	codes   : {open: Code; close: Code};
+	combine : (...styles: SGR[]) => SGR;
+}
+
+function combine(code: Code, codes: Code[]): Code {
+	if (!codes.length)
+		return code;
+
+	const rtn = Array.isArray(code) ? [...code] : [code];
+
+	for (const c of codes) {
+		if (Array.isArray(c))
+			rtn.push(...c);
+		else
+			rtn.push(c);
+	}
+
+	return rtn;
+}
+
+const codeSequence = (code: Code): string | number => Array.isArray(code) ? code.join(";") : code;
+
+function sgr(open: Code, close: Code, reset = false): SGR {
+	const openCode      = codeSequence(open);
+	const closeCode     = codeSequence(close);
+	const openSequence  = `\x1b[${openCode}m`;
+	const closeSequence = `\x1b[${closeCode}m`;
+	const reopenCode    = reset ? `${closeCode};${openCode}` : openCode;
+
+	const rxClose = new RegExp(
+		`(?<start>\\x1b\\[(?:\\d+;)*)${closeCode}(?<end>(?:;\\d+)*m)`,
+		"g"
+	);
+	const replace = `$<start>${reopenCode}$<end>`;
+
+	const func = (s: string) => s ? openSequence + s.replace(rxClose, replace) + closeSequence : s;
+
+	return Object.assign(func, {
+		codes   : {open, close},
+		open    : openSequence,
+		close   : closeSequence,
+		combine : (...styles: SGR[]) => sgr(
+			combine(open, styles.map(s => s.codes.open)),
+			combine(close, styles.map(s => s.codes.close)),
+		),
+	});
+}
+
+let disabledSGR = null as unknown as SGR;
+disabledSGR = Object.assign(
+	(s: string) => s,
+	{
+		codes   : {open: 0, close: 0},
+		open    : "",
+		close   : "",
+		combine : (): SGR => disabledSGR,
+	},
+);
+
+const disabled = (): SGR => disabledSGR;
+
+export const makeSGR = (enabled = true): typeof sgr => enabled ? sgr : disabled;

package/src/sgr/{style.js → style.ts}

@@ -1,8 +1,6 @@
-"use strict";
+import {makeSGR} from "./sgr";
 
-const {makeSGR} = require("./sgr");
-
-function makeStyle(enabled = true) {
+export function makeStyle(enabled = true) {
 	const sgr = makeSGR(enabled);
 
 	return {
@@ -20,4 +18,4 @@ function makeStyle(enabled = true) {
 	};
 }
 
-module.exports = {makeStyle};
+export type Style = ReturnType<typeof makeStyle>;

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

@@ -1,7 +1,6 @@
-/** @typedef {number | number[]} Code */
+import type {Code} from "./sgr";
 
-/** @type {(code: Code, codes: Code[]) => Code} */
-function combine(code, codes, ) {
+export function combine(code: Code, codes: Code[]): Code {
 	if (!codes.length)
 		return code;
 
@@ -15,6 +14,4 @@ function combine(code, codes, ) {
 	}
 
 	return rtn;
-}
-
-module.exports = {combine};
+}

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

@@ -1,9 +1,6 @@
-"use strict";
+import type {Attribute, BuildAtom} from "./types";
 
-/** @typedef {import("./types").BuildAtom} BuildAtom */
-
-/** @type {BuildAtom} */
-function buildExtendedColorAtom(attribute, codes, index) {
+export const buildExtendedColorAtom: BuildAtom = (attribute, codes, index) => {
 	switch (codes[index + 1]) {
 		case 2:
 			if (index + 5 >= codes.length)
@@ -16,19 +13,20 @@ function buildExtendedColorAtom(attribute, codes, index) {
 		default:
 			return {attribute, code: codes.slice(index, index + 2), skip: 1};
 	}
-}
+};
 
-/** @type {BuildAtom} */
-function buildIntensityAtom(attribute, codes, index, state) {
+export const buildIntensityAtom: BuildAtom = (attribute, codes, index, state) => {
 	const code = codes[index];
 	if (code === 22)
 		return {attribute, code: [code]};
 
-	const current = state.get("intensity");
-	if (!current || current.length == 1 && current[0] === code || current[0] === 22)
+	const current = state.get("intensity" as Attribute);
+	if (
+		!current ||
+		current[0] === 22 ||
+		current.length === 1 && current[0] === code
+	)
 		return {attribute, code: [code]};
 
 	return {attribute, code: [1, 2]};
-}
-
-module.exports = {buildExtendedColorAtom, buildIntensityAtom};
+};

package/src/simplify/index.ts

@@ -0,0 +1 @@
+export * from "./simplify";

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

@@ -1,14 +1,8 @@
-"use strict";
+import {buildExtendedColorAtom, buildIntensityAtom} from "./atom";
 
-const {buildExtendedColorAtom, buildIntensityAtom} = require("./atom");
+import type {Atom, Attribute, AttributeMap, BuildAtom} from "./types";
 
-/** @typedef {import("./types").Atom}         Atom */
-/** @typedef {import("./types").Attribute}    Attribute */
-/** @typedef {import("./types").AttributeMap} AttributeMap */
-/** @typedef {import("./types").BuildAtom}    BuildAtom */
-
-/** @type {Record<number, [attribute: Attribute, buildAtom?: BuildAtom]>} */
-const codeMap = {
+const codeMap: Record<number, [attribute: Attribute, buildAtom?: BuildAtom]> = {
 	0   : ["reset"],
 	1   : ["intensity", buildIntensityAtom],
 	2   : ["intensity", buildIntensityAtom],
@@ -67,8 +61,7 @@ const codeMap = {
 	107 : ["bg"],
 };
 
-/** @type {(codes: number[], index: number, state: AttributeMap) => Atom} */
-function lookUpAtom(codes, index, state) {
+export function lookUpAtom(codes: number[], index: number, state: AttributeMap): Atom {
 	const code  = codes[index];
 	const entry = codeMap[code];
 
@@ -81,6 +74,4 @@ function lookUpAtom(codes, index, state) {
 		return buildAtom(attribute, codes, index, state);
 
 	return {attribute, code: [code]};
-}
-
-module.exports = {lookUpAtom};
+}

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

@@ -1,10 +1,7 @@
-"use strict";
+import {rxSGR} from "../patterns";
+import {State} from "./state";
 
-const {rxSGR} = require("../patterns");
-const {State} = require("./state");
-
-/** @type {(text: string) => string} */
-function simplify(text) {
+export function simplify(text: string): string {
 	// `.split` doesn't modify `lastIndex`, so no clone is necessary here.
 	const parts = text.split(rxSGR);
 
@@ -16,7 +13,6 @@ function simplify(text) {
 		let chunk = parts[i++];
 
 		while (!chunk && i < parts.length) {
-			// Merge consecutive SGR sequences.
 			codes.push(...parts[i++].split(";").map(Number));
 			chunk = parts[i++];
 		}
@@ -28,6 +24,4 @@ function simplify(text) {
 	}
 
 	return result;
-}
-
-module.exports = {simplify};
+}

package/src/simplify/state.ts

@@ -0,0 +1,63 @@
+import {lookUpAtom}                       from "./lookup";
+import {arraysEqual, transitionIntensity} from "./utils";
+
+import type {Attribute, AttributeMap} from "./types";
+
+const defaultCodes: Map<Attribute, number[]> = new Map([
+	["intensity",     [22]],
+	["italic",        [23]],
+	["underline",     [24]],
+	["inverse",       [27]],
+	["hidden",        [28]],
+	["strikethrough", [29]],
+	["fg",            [39]],
+	["bg",            [49]],
+	["frame",         [54]],
+	["overline",      [55]],
+]);
+
+export class State extends Map<Attribute, number[]> implements AttributeMap {
+	update(codes: number[]): number[] {
+		let snapshot: AttributeMap = new Map(this);
+
+		const attributes = new Set<Attribute>();
+
+		for (let i = 0; i < codes.length; i++) {
+			const {attribute, code, skip} = lookUpAtom(codes, i, this);
+
+			if (attribute === "reset") {
+				attributes.clear();
+				this.clear();
+				attributes.add("reset");
+				for (const [attr, defaultCode] of defaultCodes)
+					this.set(attr, defaultCode);
+
+				snapshot = new Map(this);
+				continue;
+			}
+
+			attributes.add(attribute);
+			this.set(attribute, code);
+
+			if (skip)
+				i += skip;
+		}
+
+		return Array.from(attributes).flatMap(attribute => {
+			if (attribute === "reset")
+				return [0];
+
+			const code = this.get(attribute)!;
+
+			if (arraysEqual(code, snapshot.get(attribute)))
+				return [];
+
+			if (attribute === "intensity") {
+				const previous = snapshot.get(attribute);
+				return transitionIntensity(previous, code);
+			}
+
+			return code;
+		});
+	}
+}