@peteanderson/ansi 0.2.3 → 0.3.0

package/src/erase.js

@@ -14,4 +14,21 @@ const erase = {
 	},
 };
 
-module.exports = erase;
+/** @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/scroll.js

@@ -7,4 +7,12 @@ const scroll = {
 	down : lines => `\x1b[${lines ?? 1}T`,
 };
 
-module.exports = scroll;
+/** @type {typeof scroll} */
+const disabled = {
+	up   : () => "",
+	down : () => "",
+};
+
+const makeScroll = (enabled = true) => enabled ? scroll : disabled;
+
+module.exports = {makeScroll};

package/src/sgr/color/color.js

@@ -0,0 +1,104 @@
+const {makeSGR}                                       = require("../sgr");
+const {makeStyle}                                     = require("../style");
+const {clip, rgbToX256, rgbToX16, rgbToX8, x256ToRgb} = require("./utils");
+
+/** @typedef {import("../sgr").Code}                     Code */
+/** @typedef {import("../../features/types").ColorDepth} ColorDepth */
+/** @typedef {import("../sgr").SGR}                      SGR */
+/** @typedef {import("./types").Channel}                 Channel */
+
+const fgOpen = 30, fgClose = 39;
+const bgOpen = 40, bgClose = 49;
+
+/** @type {(colorDepth: ColorDepth, open: number, close: number) => Channel} */
+function makeChannel(colorDepth, open, close) {
+	const sgrBase = makeSGR(colorDepth > 1);
+	const style   = makeStyle(colorDepth > 1);
+
+	/** @type {(code: Code) => SGR} */
+	const sgr = code => sgrBase(code, close);
+
+	/** @type {(index: number) => SGR} */
+	const bright =
+		colorDepth >= 4 ? index => sgr(open + 60 + index) :
+		colorDepth === 3 ?
+			open === fgOpen ?
+				index => style.bold.combine(sgr(open + index)) :
+				index => sgr(open + index) :
+		() => sgr(0);
+
+	/** @type {(code: number) => SGR} */
+	const x16ToX8 =
+		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);
+
+	return {
+		black   : sgr(open + 0),
+		red     : sgr(open + 1),
+		green   : sgr(open + 2),
+		yellow  : sgr(open + 3),
+		blue    : sgr(open + 4),
+		magenta : sgr(open + 5),
+		cyan    : sgr(open + 6),
+		white   : sgr(open + 7),
+
+		brightBlack   : bright(0),
+		brightRed     : bright(1),
+		brightGreen   : bright(2),
+		brightYellow  : bright(3),
+		brightBlue    : bright(4),
+		brightMagenta : bright(5),
+		brightCyan    : bright(6),
+		brightWhite   : bright(7),
+
+		rgb:
+			colorDepth >= 24 ? (r, g, b) => sgr([open + 8, 2, ...clip(r, g, b)]) :
+			colorDepth >=  8 ? (r, g, b) => sgr([open + 8, 5, rgbToX256(...clip(r, g, b))]) :
+			colorDepth >=  4 ? (r, g, b) => sgr(open + rgbToX16(...clip(r, g, b))) :
+			colorDepth === 3 ?
+				open === fgOpen ?
+					(r, g, b) => x16ToX8(rgbToX16(...clip(r, g, b))) :
+					(r, g, b) => sgr(open + rgbToX8(...clip(r, g, b))) :
+			() => sgr(0),
+
+		/** @type {(...args: [number] | [number, number, number]) => SGR} */
+		x256:
+			colorDepth >= 8 ?
+				(...args) => sgr(
+					[open + 8, 5, args.length === 3 ? rgbToX256(...clip(...args)) : clip(args[0])],
+				) :
+			colorDepth >= 4 ?
+				(...args) => 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) => sgr(
+						open + rgbToX8(
+						...args.length === 3 ? clip(...args) : x256ToRgb(clip(args[0])),
+						),
+					) :
+			() => sgr(0),
+
+		default: colorDepth > 1 ? `\x1b[${close}m` : "",
+	};
+}
+
+/** @type {Partial<Record<ColorDepth, {fg: Channel, bg: Channel}>>} */
+const cache = {};
+
+/** @type {(colorDepth: ColorDepth) => {fg: Channel, bg: Channel}} */
+const makeColor = (colorDepth = 4) =>
+	cache[colorDepth] ?? (cache[colorDepth] = {
+		fg : makeChannel(colorDepth, fgOpen, fgClose),
+		bg : makeChannel(colorDepth, bgOpen, bgClose),
+	});
+
+module.exports = {makeColor};

package/src/sgr/color/index.js

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

package/src/sgr/color/types.d.ts

@@ -0,0 +1,28 @@
+export interface Channel {
+	black   : SGR;
+	red     : SGR;
+	green   : SGR;
+	yellow  : SGR;
+	blue    : SGR;
+	magenta : SGR;
+	cyan    : SGR;
+	white   : SGR;
+
+	brightBlack   : SGR;
+	brightRed     : SGR;
+	brightGreen   : SGR;
+	brightYellow  : SGR;
+	brightBlue    : SGR;
+	brightMagenta : SGR;
+	brightCyan    : SGR;
+	brightWhite   : SGR;
+
+	rgb: (r: number, g: number, b: number) => SGR;
+
+	x256: {
+		(code: number): SGR;
+		(r: number, g: number, b: number): SGR;
+	};
+
+	default: string,
+}

package/src/sgr/color/utils.js

@@ -0,0 +1,81 @@
+/** @typedef {import("../sgr").Code} Code */
+
+/** @type {(r: number, g: number, b: number) => number} */
+function rgbToX256(r, g, b) {
+	if (r === g && g === b) {
+		// grayscale
+		return 232 + Math.floor(r * 24 / 256);
+	}
+
+	// 6x6x6 color cube
+	return (
+		16 +
+		Math.floor(r * 6 / 256) * 36 +
+		Math.floor(g * 6 / 256) * 6 +
+		Math.floor(b * 6 / 256)
+	);
+}
+
+/** @type {(code: number) => [number, number, number]} */
+function x256ToRgb(code) {
+	if (code >= 232) {
+		// grayscale
+		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];
+}
+
+/** @type {(r: number, g: number, b: number) => number} */
+function rgbToX16(r, g, b) {
+	// First calculate it as a 4x4x4 cube.
+
+	r = Math.min(2, Math.floor(r / 85));
+	g = Math.min(2, Math.floor(g / 85));
+	b = Math.min(2, Math.floor(b / 85));
+
+	// Which channels are "on" determines the hue (ANSI color index 0–7).
+	const index = (r ? 1 : 0) | (g ? 2 : 0) | (b ? 4 : 0);
+
+	// The bright bit is derived from the max channel level across all three.
+	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 value uses the SGR offset scheme: 0–7 for normal, 60–67 for bright.
+	return index + (bright ? 60 : 0);
+}
+
+/** @type {(r: number, g: number, b: number) => number} */
+function rgbToX8(r, g, b) {
+	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);
+}
+
+/**
+ * @overload
+ * @param   {number} x
+ * @returns {number}
+ * @overload
+ * @param   {number} r
+ * @param   {number} g
+ * @param   {number} b
+ * @returns {[number, number, number]}
+ *//** @param {[number] | [number, number, number]} args */
+const clip = (...args) => 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]))),
+	];
+
+module.exports = {rgbToX256, x256ToRgb, rgbToX16, rgbToX8, clip};

package/src/sgr/reset.js

@@ -1,3 +1,3 @@
-const reset = "\x1b[0m";
+const makeReset = (enabled = true) => enabled ? "\x1b[0m" : "";
 
-module.exports = {reset};
+module.exports = {makeReset};

package/src/sgr/sgr.js

@@ -1,15 +1,13 @@
 "use strict";
 
-const $codes = Symbol();
-
 /**
 @typedef {number | number[]} Code
 @typedef {{
 	(text: string): string;
-	open     : string;
-	close    : string;
-	[$codes] : {open: Code, close: Code};
-	combine  : (...styles: SGR[]) => SGR;
+	open    : string;
+	close   : string;
+	codes   : {open: Code, close: Code};
+	combine : (...styles: SGR[]) => SGR;
 }} SGR
 */
 
@@ -48,19 +46,32 @@ function sgr(open, close, reset = false) {
 	const replace = `$<start>${reopenCode}$<end>`;
 
 	/** @type {(text: string) => string} */
-	const func = s => openSequence + s.replace(rxClose, replace) + closeSequence
+	const func = s => openSequence + s.replace(rxClose, replace) + closeSequence;
 
 	return Object.assign(func, {
-		[$codes] : {open, close},
-		open     : openSequence,
-		close    : closeSequence,
+		codes : {open, close},
+		open  : openSequence,
+		close : closeSequence,
 
 		/** @type {(...styles: SGR[]) => SGR} */
 		combine: (...styles) => sgr(
-			combine(open, styles.map(s => s[$codes].open)),
-			combine(close, styles.map(s => s[$codes].close)),
+			combine(open, styles.map(s => s.codes.open)),
+			combine(close, styles.map(s => s.codes.close)),
 		),
 	});
-}
+};
+
+/** @type {SGR} */
+const disabledSGR = Object.assign(/** @type {(text: string) => string} */ s => s, {
+	codes   : {open: 0, close: 0},
+	open    : "",
+	close   : "",
+	combine : () => disabledSGR,
+});
+
+/** @type {typeof sgr} */
+const disabled = () => disabledSGR;
+
+const makeSGR = (enabled = true) => enabled ? sgr : disabled;
 
-module.exports = {sgr};
+module.exports = {makeSGR};

package/src/sgr/style.js

@@ -1,19 +1,23 @@
 "use strict";
 
-const {sgr} = require("./sgr");
+const {makeSGR} = require("./sgr");
 
-const style = {
-	bold            : sgr(1, 22, true),
-	dim             : sgr(2, 22, true),
-	italic          : sgr(3, 23),
-	underline       : sgr(4, 24),
-	inverse         : sgr(7, 27),
-	hidden          : sgr(8, 28),
-	strikethrough   : sgr(9, 29),
-	doubleUnderline : sgr(21, 24),
-	frame           : sgr(51, 54),
-	encircle        : sgr(52, 54),
-	overline        : sgr(53, 55),
-};
+function makeStyle(enabled = true) {
+	const sgr = makeSGR(enabled);
 
-module.exports = {style};
+	return {
+		bold            : sgr(1, 22, true),
+		dim             : sgr(2, 22, true),
+		italic          : sgr(3, 23),
+		underline       : sgr(4, 24),
+		inverse         : sgr(7, 27),
+		hidden          : sgr(8, 28),
+		strikethrough   : sgr(9, 29),
+		doubleUnderline : sgr(21, 24),
+		frame           : sgr(51, 54),
+		encircle        : sgr(52, 54),
+		overline        : sgr(53, 55),
+	};
+}
+
+module.exports = {makeStyle};

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 };
-}