console-toolkit 1.2.9 → 1.2.11

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 = '',