@peteanderson/ansi 0.2.3 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # @peteanderson/ansi
 
-ANSI escape sequence helpers for Node.js terminal output.
+ANSI escape sequence helpers for Node.js terminal output. Automatically detects terminal
+capabilities and adapts output accordingly.
 
 ## Installation
 
@@ -17,47 +18,80 @@ 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.visibleLength(styledText)); // get display width
-console.log(ansi.slice("styled text", 0, 5)); // slice by visible length
-console.log(ansi.simplify(styledText)); // combine adjacent SGR sequences
+
+// 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:
+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 (r, g, b in 0–5 or grayscale 232–255)
-- `fg.x256(code)(text)` or `fg.x256(r, g, b)(text)` - 256-color palette
+- `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:
+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
-- `bg.x256(code)(text)` or `bg.x256(r, g, b)(text)` - 256-color palette
+- `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:
+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)
@@ -69,36 +103,53 @@ All return functions with `open` and `close` properties for raw sequences.
 
 ### `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.
+Removes all ANSI CSI sequences from a string (always available).
 
 ### `slice(text, start, end)`
 
-Slices a string by visible characters, ignoring ANSI sequences. Works like `String.prototype.slice`
-but counts only visible characters. Properly maintains terminal state at slice boundaries.
+Slices a string by visible characters, ignoring ANSI sequences (always available).
 
 ### `sanitize(text)`
 
-Removes "unsafe" CSI sequences (non-SGR), leaving only color and style codes.
+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. Useful
-for optimizing styled strings.
+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.
+Returns the visible length of a string with all ANSI sequences removed (always available).
+
+### `features`
+
+Object containing the detected feature configuration:
+
+```ts
+{
+    colorDepth : 1 | 3 | 4 | 8 | 24;
+    style      : boolean;
+    caret      : boolean;
+    erase      : boolean;
+    scroll     : boolean;
+}
+```
 
 ## License
 

package/dist/ansi.d.ts

@@ -1,13 +1,46 @@
-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";
+export = ansi;
+declare const ansi: typeof makeAnsi & {
+    fg: Channel;
+    bg: Channel;
+} & {
+    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>;
+};
+declare namespace ansi {
+    export { Args, Ansi };
+}
+declare function makeAnsi(...args: Args): Ansi;
+import { makeCaret } from "./caret";
+import { makeErase } from "./erase";
+import { makeScroll } from "./scroll";
+import { makeStyle } from "./sgr/style";
 import { strip } from "./strip";
 import { visibleLength } from "./strip";
 import { sanitize } from "./strip";
 import { slice } from "./slice";
 import { simplify } from "./simplify/simplify";
-export { caret, erase, scroll, reset, style, fg, bg, strip, visibleLength, sanitize, slice, simplify };
+import { getFeatures } from "./features/features";
+type Args = import("./features/features").Args;
+type Ansi = 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>;
+};
+import { makeColor } from "./sgr/color/color";

package/dist/ansi.js

@@ -1,23 +1,49 @@
 "use strict";
-const caret = require("./caret");
-const erase = require("./erase");
-const scroll = require("./scroll");
-const { bg, fg, reset, style } = require("./sgr");
+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");
-const ansi = {
-    caret,
-    erase,
-    scroll,
-    reset,
-    style,
-    fg,
-    bg,
-    strip,
-    visibleLength,
-    sanitize,
-    slice,
-    simplify,
-};
+/**
+@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/dist/caret.d.ts

@@ -1,25 +1,28 @@
-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 };
-}
+export function makeCaret(enabled?: boolean): {
+    up: (count?: number) => string;
+    down: (count?: number) => string;
+    forward: (count?: number) => string;
+    backward: (count?: number) => string;
+    nextLine: (count?: number) => string;
+    prevLine: (count?: number) => string;
+    /** @type {(x: number) => string} */
+    x: (x: number) => string;
+    save: string;
+    restore: string;
+    hide: string;
+    show: string;
+    position: {
+        get: string;
+        /** @type {(x: number, y: number) => string} */
+        set: (x: number, y: number) => string;
+    };
+    shape: {
+        steadyBlock: string;
+        steadyBar: string;
+        steadyUnderline: string;
+        blinkingBlock: string;
+        blinkingBar: string;
+        blinkingUnderline: string;
+        default: string;
+    };
+};

package/dist/caret.js

@@ -1,6 +1,8 @@
 "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"),
@@ -37,4 +39,32 @@ const caret = {
         default: "\x1b[0 q",
     },
 };
-module.exports = caret;
+/** @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/dist/erase.d.ts

@@ -1,14 +1,13 @@
-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;
-}
+export function makeErase(enabled?: boolean): {
+    line: {
+        toStart: string;
+        toEnd: string;
+        full: string;
+    };
+    screen: {
+        toStart: string;
+        toEnd: string;
+        full: string;
+        scrollback: string;
+    };
+};

package/dist/erase.js

@@ -12,4 +12,19 @@ const erase = {
         scrollback: "\x1b[3J",
     },
 };
-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/dist/features/build.d.ts

@@ -0,0 +1,11 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+export function build(isTTY: boolean, colorDepth: ColorDepth, style?: boolean, caret?: boolean, erase?: boolean, scroll?: boolean): Features;
+/** @type {(isTTY: boolean, enabled: boolean) => Features} */
+export const boolean: (isTTY: boolean, enabled: boolean) => Features;
+/** @type {(isTTY: boolean, colorDepth: ColorDepth) => Features} */
+export const number: (isTTY: boolean, colorDepth: ColorDepth) => Features;
+/** @type {(stream: NodeJS.WriteStream) => Features} */
+export const tty: (stream: NodeJS.WriteStream) => Features;
+/** @type {() => Features} */
+export const pipe: () => Features;

package/dist/features/build.js

@@ -0,0 +1,50 @@
+"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/dist/features/detect.d.ts

@@ -0,0 +1,4 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+export function detectFeatureSupport(isTTY: boolean, colorDepth: ColorDepth): Omit<Features, "colorDepth">;
+export function getColorDepth(stream?: NodeJS.WriteStream): ColorDepth;

package/dist/features/detect.js

@@ -0,0 +1,33 @@
+"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/dist/features/features.d.ts

@@ -0,0 +1,5 @@
+export type ColorDepth = import("./types").ColorDepth;
+export type Features = import("./types").Features;
+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;
+import { Socket } from "node:net";

package/dist/features/features.js

@@ -0,0 +1,39 @@
+"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/dist/features/index.d.ts

@@ -0,0 +1,2 @@
+declare const _exports: typeof import("./features");
+export = _exports;

package/dist/features/index.js

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