console-toolkit 1.2.9 → 1.2.10

package/src/ansi/sgr-constants.d.ts

@@ -0,0 +1,173 @@
+/** Pre-built SGR escape sequences for common text styling commands.
+ * Each constant is a complete escape sequence string ready to write to the terminal.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Package:-ansi}
+ */
+
+/** SGR sequence: enable bold. */
+export const BOLD: string;
+/** SGR sequence: enable dim/faint. */
+export const DIM: string;
+/** SGR sequence: enable italic. */
+export const ITALIC: string;
+/** SGR sequence: enable underline. */
+export const UNDERLINE: string;
+/** SGR sequence: enable blink. */
+export const BLINK: string;
+/** SGR sequence: enable rapid blink. */
+export const RAPID_BLINK: string;
+/** SGR sequence: enable inverse/reverse video. */
+export const INVERSE: string;
+/** SGR sequence: enable hidden/invisible text. */
+export const HIDDEN: string;
+/** SGR sequence: enable strikethrough. */
+export const STRIKETHROUGH: string;
+/** SGR sequence: enable overline. */
+export const OVERLINE: string;
+
+/** SGR sequence: reset all attributes. */
+export const RESET_ALL: string;
+/** SGR sequence: reset all attributes (alias of RESET_ALL). */
+export const RESET: string;
+
+/** SGR sequence: reset bold (also resets dim). */
+export const RESET_BOLD: string;
+/** SGR sequence: reset dim (also resets bold). */
+export const RESET_DIM: string;
+/** SGR sequence: reset italic. */
+export const RESET_ITALIC: string;
+/** SGR sequence: reset underline. */
+export const RESET_UNDERLINE: string;
+/** SGR sequence: reset blink. */
+export const RESET_BLINK: string;
+/** SGR sequence: reset rapid blink. */
+export const RESET_RAPID_BLINK: string;
+/** SGR sequence: reset inverse. */
+export const RESET_INVERSE: string;
+/** SGR sequence: reset hidden. */
+export const RESET_HIDDEN: string;
+/** SGR sequence: reset strikethrough. */
+export const RESET_STRIKETHROUGH: string;
+/** SGR sequence: reset overline. */
+export const RESET_OVERLINE: string;
+
+/** SGR sequence: reset foreground color to default. */
+export const RESET_COLOR: string;
+/** SGR sequence: reset background color to default. */
+export const RESET_BG_COLOR: string;
+/** SGR sequence: reset font to default. */
+export const RESET_FONT: string;
+
+/** SGR sequence: set foreground to black. */
+export const BLACK: string;
+/** SGR sequence: set foreground to red. */
+export const RED: string;
+/** SGR sequence: set foreground to green. */
+export const GREEN: string;
+/** SGR sequence: set foreground to yellow. */
+export const YELLOW: string;
+/** SGR sequence: set foreground to blue. */
+export const BLUE: string;
+/** SGR sequence: set foreground to magenta. */
+export const MAGENTA: string;
+/** SGR sequence: set foreground to cyan. */
+export const CYAN: string;
+/** SGR sequence: set foreground to white. */
+export const WHITE: string;
+
+/** SGR sequence: set foreground to bright black. */
+export const BRIGHT_BLACK: string;
+/** SGR sequence: set foreground to bright red. */
+export const BRIGHT_RED: string;
+/** SGR sequence: set foreground to bright green. */
+export const BRIGHT_GREEN: string;
+/** SGR sequence: set foreground to bright yellow. */
+export const BRIGHT_YELLOW: string;
+/** SGR sequence: set foreground to bright blue. */
+export const BRIGHT_BLUE: string;
+/** SGR sequence: set foreground to bright magenta. */
+export const BRIGHT_MAGENTA: string;
+/** SGR sequence: set foreground to bright cyan. */
+export const BRIGHT_CYAN: string;
+/** SGR sequence: set foreground to bright white. */
+export const BRIGHT_WHITE: string;
+
+/** SGR sequence: set background to black. */
+export const BG_BLACK: string;
+/** SGR sequence: set background to red. */
+export const BG_RED: string;
+/** SGR sequence: set background to green. */
+export const BG_GREEN: string;
+/** SGR sequence: set background to yellow. */
+export const BG_YELLOW: string;
+/** SGR sequence: set background to blue. */
+export const BG_BLUE: string;
+/** SGR sequence: set background to magenta. */
+export const BG_MAGENTA: string;
+/** SGR sequence: set background to cyan. */
+export const BG_CYAN: string;
+/** SGR sequence: set background to white. */
+export const BG_WHITE: string;
+
+/** SGR sequence: set background to bright black. */
+export const BG_BRIGHT_BLACK: string;
+/** SGR sequence: set background to bright red. */
+export const BG_BRIGHT_RED: string;
+/** SGR sequence: set background to bright green. */
+export const BG_BRIGHT_GREEN: string;
+/** SGR sequence: set background to bright yellow. */
+export const BG_BRIGHT_YELLOW: string;
+/** SGR sequence: set background to bright blue. */
+export const BG_BRIGHT_BLUE: string;
+/** SGR sequence: set background to bright magenta. */
+export const BG_BRIGHT_MAGENTA: string;
+/** SGR sequence: set background to bright cyan. */
+export const BG_BRIGHT_CYAN: string;
+/** SGR sequence: set background to bright white. */
+export const BG_BRIGHT_WHITE: string;
+
+/** SGR sequence: set foreground to black (explicit FG_ prefix). */
+export const FG_BLACK: string;
+/** SGR sequence: set foreground to red (explicit FG_ prefix). */
+export const FG_RED: string;
+/** SGR sequence: set foreground to green (explicit FG_ prefix). */
+export const FG_GREEN: string;
+/** SGR sequence: set foreground to yellow (explicit FG_ prefix). */
+export const FG_YELLOW: string;
+/** SGR sequence: set foreground to blue (explicit FG_ prefix). */
+export const FG_BLUE: string;
+/** SGR sequence: set foreground to magenta (explicit FG_ prefix). */
+export const FG_MAGENTA: string;
+/** SGR sequence: set foreground to cyan (explicit FG_ prefix). */
+export const FG_CYAN: string;
+/** SGR sequence: set foreground to white (explicit FG_ prefix). */
+export const FG_WHITE: string;
+
+/** SGR sequence: set foreground to bright black (explicit FG_ prefix). */
+export const FG_BRIGHT_BLACK: string;
+/** SGR sequence: set foreground to bright red (explicit FG_ prefix). */
+export const FG_BRIGHT_RED: string;
+/** SGR sequence: set foreground to bright green (explicit FG_ prefix). */
+export const FG_BRIGHT_GREEN: string;
+/** SGR sequence: set foreground to bright yellow (explicit FG_ prefix). */
+export const FG_BRIGHT_YELLOW: string;
+/** SGR sequence: set foreground to bright blue (explicit FG_ prefix). */
+export const FG_BRIGHT_BLUE: string;
+/** SGR sequence: set foreground to bright magenta (explicit FG_ prefix). */
+export const FG_BRIGHT_MAGENTA: string;
+/** SGR sequence: set foreground to bright cyan (explicit FG_ prefix). */
+export const FG_BRIGHT_CYAN: string;
+/** SGR sequence: set foreground to bright white (explicit FG_ prefix). */
+export const FG_BRIGHT_WHITE: string;
+
+/** SGR sequence: set foreground to gray (alias of BRIGHT_BLACK). */
+export const GRAY: string;
+/** SGR sequence: set foreground to grey (alias of BRIGHT_BLACK). */
+export const GREY: string;
+/** SGR sequence: set background to gray (alias of BG_BRIGHT_BLACK). */
+export const BG_GRAY: string;
+/** SGR sequence: set background to grey (alias of BG_BRIGHT_BLACK). */
+export const BG_GREY: string;
+/** SGR sequence: set foreground to gray (alias of FG_BRIGHT_BLACK). */
+export const FG_GRAY: string;
+/** SGR sequence: set foreground to grey (alias of FG_BRIGHT_BLACK). */
+export const FG_GREY: string;

package/src/ansi/sgr-state.d.ts

@@ -0,0 +1,91 @@
+/** SGR (Select Graphics Rendition) state object. Properties are `null` for reset, a command string when set, or `undefined` when unspecified. */
+export interface SgrState {
+  /** Bold attribute command or `null` to reset. */
+  bold?: string | null;
+  /** Dim/faint attribute command or `null` to reset. */
+  dim?: string | null;
+  /** Italic attribute command or `null` to reset. */
+  italic?: string | null;
+  /** Underline attribute command or `null` to reset. */
+  underline?: string | null;
+  /** Blink attribute command or `null` to reset. */
+  blink?: string | null;
+  /** Inverse/reverse attribute command or `null` to reset. */
+  inverse?: string | null;
+  /** Hidden attribute command or `null` to reset. */
+  hidden?: string | null;
+  /** Strikethrough attribute command or `null` to reset. */
+  strikethrough?: string | null;
+  /** Overline attribute command or `null` to reset. */
+  overline?: string | null;
+  /** Foreground color command(s) or `null` to reset. */
+  foreground?: string | string[] | null;
+  /** Background color command(s) or `null` to reset. */
+  background?: string | string[] | null;
+  /** Decoration (underline) color command(s) or `null` to reset. */
+  decoration?: string | string[] | null;
+  /** Font command or `null` to reset. */
+  font?: string | null;
+}
+
+/** The fully reset SGR state with all properties set to `null`. */
+export const RESET_STATE: SgrState;
+
+/** Extracts the cumulative SGR state from a string by parsing all SGR sequences.
+ * @param s - The string to parse for SGR sequences.
+ * @param initState - Initial state to build upon.
+ * @returns The resulting SGR state.
+ */
+export function extractState(s: string, initState?: SgrState): SgrState;
+/** Converts a value to an SGR state object.
+ * @param value - An SgrState object, a string containing SGR sequences, an object with `getState()`, or `null` for reset.
+ * @returns The resulting SGR state.
+ */
+export function toState(value: SgrState | string | {getState(): SgrState} | null): SgrState;
+
+/** Combines multiple SGR states, with later states overriding earlier ones.
+ * @param states - States to combine (SgrState objects, strings, or nulls).
+ * @returns The combined state.
+ */
+export function combineStates(...states: (SgrState | string | {getState(): SgrState} | null)[]): SgrState;
+/** Converts an array of SGR command strings into an SGR state object.
+ * @param commands - Array of SGR command strings.
+ * @returns The resulting state.
+ */
+export function commandsToState(commands: string[]): SgrState;
+/** Adds SGR commands to an existing state.
+ * @param state - The base state.
+ * @param commands - SGR command strings to add.
+ * @returns The updated state.
+ */
+export function addCommandsToState(state: SgrState, commands: string[]): SgrState;
+
+/** Converts an SGR state to an array of SGR command strings.
+ * @param state - The SGR state to convert.
+ * @returns Array of SGR command strings.
+ */
+export function stateToCommands(state: SgrState): string[];
+/** Computes the minimal SGR commands needed to transition from one state to another.
+ * @param prev - The previous SGR state.
+ * @param next - The target SGR state.
+ * @returns Array of SGR command strings for the transition.
+ */
+export function stateTransition(prev: SgrState, next: SgrState): string[];
+/** Computes the minimal SGR commands to reverse a state transition.
+ * @param prev - The previous SGR state.
+ * @param next - The target SGR state.
+ * @returns Array of SGR command strings for the reverse transition.
+ */
+export function stateReverseTransition(prev: SgrState, next: SgrState): string[];
+
+/** Converts an array of SGR commands to an escape sequence string.
+ * @param commands - Array of SGR command strings, or null/undefined.
+ * @returns The SGR escape sequence string.
+ */
+export function stringifyCommands(commands: string[] | undefined | null): string;
+/** Optimizes SGR sequences in a string by computing minimal state transitions.
+ * @param s - The string containing SGR sequences.
+ * @param initState - Initial SGR state.
+ * @returns The optimized string.
+ */
+export function optimize(s: string, initState?: SgrState): string;

package/src/ansi/sgr-state.js

@@ -10,6 +10,9 @@ import {
   matchSgr
 } from './sgr.js';
 
+/** The fully reset SGR state with all properties set to `null`.
+ * @type {object}
+ */
 export const RESET_STATE = {
   bold: null,
   dim: null,
@@ -30,6 +33,11 @@ const defaultState = Symbol('defaultState');
 
 let toState;
 
+/** Extracts the cumulative SGR state from a string by parsing all SGR sequences.
+ * @param {string} s - The string to parse.
+ * @param {object} [initState] - Initial state to build upon.
+ * @returns {object} The resulting SGR state.
+ */
 export const extractState = (s, initState = defaultState) => {
   let state = toState(initState);
   matchSgr.lastIndex = 0;
@@ -63,6 +71,10 @@ const getStateResets = state => {
   return resetCount;
 };
 
+/** Combines multiple SGR states, with later states overriding earlier ones.
+ * @param {...(object|string)} states - States to combine.
+ * @returns {object} The combined state.
+ */
 export const combineStates = (...states) => {
   let state = {};
   for (const s of states) {
@@ -74,6 +86,10 @@ export const combineStates = (...states) => {
   return state;
 };
 
+/** Converts an array of SGR command strings into an SGR state object.
+ * @param {string[]} commands - Array of SGR command strings.
+ * @returns {object} The resulting state.
+ */
 export const commandsToState = commands => {
   let state = {};
   for (let i = 0; i < commands.length; ++i) {
@@ -191,6 +207,11 @@ export const commandsToState = commands => {
   return state;
 };
 
+/** Adds SGR commands to an existing state.
+ * @param {object} state - The current state.
+ * @param {string[]} commands - Commands to add.
+ * @returns {object} The updated state.
+ */
 export const addCommandsToState = (state, commands) => combineStates(state, commandsToState(commands));
 
 const equalColors = (a, b) => {
@@ -217,6 +238,10 @@ const resetColorProperties = {
 
 const chainedStates = {bold: 1, dim: 1};
 
+/** Converts an SGR state to an array of SGR command strings.
+ * @param {object|string} state - The state to convert.
+ * @returns {string[]} The command strings.
+ */
 export const stateToCommands = state => {
   state = toState(state);
   const commands = [];
@@ -257,6 +282,11 @@ export const stateToCommands = state => {
   return resetCount === TOTAL_RESETS ? [''] : commands;
 };
 
+/** Computes the minimal SGR commands needed to transition from one state to another.
+ * @param {object|string} prev - The previous state.
+ * @param {object|string} next - The next state.
+ * @returns {string[]} The transition commands.
+ */
 export const stateTransition = (prev, next) => {
   prev = toState(prev);
   next = toState(next);
@@ -318,6 +348,11 @@ export const stateTransition = (prev, next) => {
   return commands;
 };
 
+/** Computes the minimal SGR commands to reverse a state transition (from next back to prev).
+ * @param {object|string} prev - The state to restore.
+ * @param {object|string} next - The current state.
+ * @returns {string[]} The reverse transition commands.
+ */
 export const stateReverseTransition = (prev, next) => {
   prev = toState(prev);
   next = toState(next);
@@ -347,6 +382,7 @@ export const stateReverseTransition = (prev, next) => {
   if (prev.dim === null) ++resetCount;
 
   for (const name of Object.keys(RESET_STATE)) {
+    if (chainedStates[name] === 1) continue; // skip chained states
     const value = prev[name];
     if (resetColorProperties.hasOwnProperty(name)) {
       // color
@@ -374,8 +410,17 @@ export const stateReverseTransition = (prev, next) => {
   return commands;
 };
 
+/** Converts an array of SGR commands to an escape sequence string, or empty string if no commands.
+ * @param {string[]} commands
+ * @returns {string}
+ */
 export const stringifyCommands = commands => (commands?.length ? setCommands(commands) : '');
 
+/** Optimizes SGR sequences in a string by computing minimal state transitions.
+ * @param {string} s - The string to optimize.
+ * @param {object} [initState] - Initial state.
+ * @returns {string} The optimized string.
+ */
 export const optimize = (s, initState = defaultState) => {
   let state = toState(initState),
     result = '',