The ansi package provides a set of ANSI codes for terminal output, helpers, and a state machine for SGR sequences (colors and text styles).

The definitive list of ANSI codes is available in the Wikipedia article. The most important module for users of the toolkit is ansi/sgr-state.js described below.

ansi/index.js AKA ansi

This is the main user-facing module: ansi/index.js. It exposes other modules in this directory: ansi/csi.js and ansi/sgr.js. Additionally it exports a few constants (see the file for details). The most important ones:

Name	Description
CURSOR_SAVE	Save the current cursor position.
CURSOR_RESTORE	Restore the previously saved cursor position.
CURSOR_GO_UP1	Move the cursor up one line.
CURSOR_DELETE	Delete the character under the cursor.
ESC	The escape character. Used to form other sequences.

ansi/csi.js

The module ansi/csi.js provides CSI sequences (including SGR defined in ansi/sgr.js). See CSI for more details.

The most important cursor-related ones:

Name	Description
CURSOR_UP1	Move the cursor up one line.
CURSOR_DOWN1	Move the cursor down one line.
CURSOR_FORWARD1	Move the cursor forward one character.
CURSOR_RIGHT1	Alias of CURSOR_FORWARD1.
CURSOR_BACK1	Move the cursor backward one character.
CURSOR_LEFT1	Alias of CURSOR_BACK1.
CURSOR_NEXT_LINE1	Move the cursor to the beginning of the next line.
CURSOR_PREV_LINE1	Move the cursor to the beginning of the previous line.
CURSOR_COLUMN1	Move the cursor to the specified column.
CURSOR_HOME	Move the cursor to the beginning of the screen.
CURSOR_SAVE_POS	Save the current cursor position.
CURSOR_RESTORE_POS	Restore the previously saved cursor position.
CURSOR_NORMAL	Show the cursor.
CURSOR_INVISIBLE	Hide the cursor.

Note that some of codes are similar to ones defined in ansi/index.js but actually different.

The most important clearing-related ones:

Name	Description
CLEAR_SCREEN	Clear the screen.
CLEAR_SCREEN_ALL	Clear the screen and scrollback buffer.
CLEAR_EOS	Clear from the cursor to the end of the screen.
CLEAR_BOS	Clear from the beginning of the screen to the cursor.
CLEAR_LINE	Clear from the current line.
CLEAR_EOL	Clear from the cursor to the end of the line.
CLEAR_BOL	Clear from the beginning of the line to the cursor.

The most important screen-related ones:

Name	Description
SCREEN_SAVE	Save the current screen.
SCREEN_RESTORE	Restore the previously saved screen.
SCREEN_ALT_ON	Enable the alternative screen buffer.
SCREEN_ALT_OFF	Disable the alternative screen buffer.

Again, some codes are similar to ones defined in ansi/index.js but actually different.

ansi/sgr.js

The module ansi/sgr.js provides SGR sequences and defined all supporting constants and functions. See SGR for more details and the file itself.

The most important constants:

// Standard colors
const Colors = {
  BLACK: 0,
  RED: 1,
  GREEN: 2,
  YELLOW: 3,
  BLUE: 4,
  MAGENTA: 5,
  CYAN: 6,
  WHITE: 7,
  DEFAULT: 9
};

// Supported SGR commands
const Commands = {
  RESET_ALL: '0',
  BOLD: '1',
  DIM: '2',
  ITALIC: '3',
  UNDERLINE: '4',
  BLINK: '5',
  RAPID_BLINK: '6',
  INVERSE: '7',
  HIDDEN: '8',
  STRIKETHROUGH: '9',
  DEFAULT_FONT: '10',
  RESET_FONT: '10',
  FONT_GOTHIC: '20',
  RESET_BOLD: '22',
  RESET_DIM: '22',
  RESET_ITALIC: '23',
  RESET_UNDERLINE: '24',
  RESET_BLINK: '25',
  RESET_RAPID_BLINK: '25',
  RESET_INVERSE: '27',
  RESET_HIDDEN: '28',
  RESET_STRIKETHROUGH: '29',
  CURLY_UNDERLINE: '4:3',
  RESET_CURLY_UNDERLINE: '24',
  DOUBLE_UNDERLINE: '21',
  RESET_DOUBLE_UNDERLINE: '24',
  EXTENDED_COLOR: '38',
  BG_EXTENDED_COLOR: '48',
  DEFAULT_COLOR: '39',
  BG_DEFAULT_COLOR: '49',
  RESET_COLOR: '39',
  RESET_BG_COLOR: '49',
  OVERLINE: '53',
  RESET_OVERLINE: '55',
  DECORATION_COLOR: '58',
  DECORATION_DEFAULT_COLOR: '59',
  RESET_DECORATION_COLOR: '59'
};

The most important helper functions:

Function	Return	Description
reset(command)	string or undefined	Return a command to reset the given command.
setCommands(commands)	string	Return a well-formed SGR sequence from the given array of commands.
colorNumber(color)	number	Return the number of the given color.

reset() takes a code (as a string or a number) or a name as a string (defined in Commands above) and returns a command to reset the given command or undefined if the command was not found.

setCommands() takes an array of commands or a string and returns a well-formed SGR sequence. Passing the empty string or an empty array will return a RESET_ALL command.

colorNumber() takes a color name or a number and returns the number of the given color suitable for forming a color command. It is used as a sanitizer for color inputs.

ansi/sgr-state.js

The module ansi/sgr-state.js is the most important user-facing module: it defines a state machine for SGR sequences. See the file to learn the implementation.

State

The state is defined as the following structure:

const RESET_STATE = {
  bold: null,
  dim: null,
  italic: null,
  underline: null,
  blink: null,
  inverse: null,
  hidden: null,
  strikethrough: null,
  overline: null,
  foreground: null,
  background: null,
  decoration: null,
  font: null
};

The structure above defines a state for all supported SGR commands.

As you can see the names of individual properties correspond to command names defined in the Commands constant above.

Each property can have the following values:

• null - the property is reset. It corresponds to a RESET_XXX command, e.g., RESET_BOLD.
• undefined - the property is not set and we don't know its current value.
• a string - the property is set to the given value.
  • In most cases it is a corresponding command, e.g., Commands.BOLD.
  • Some properties are overloaded and the value would be the current command in effect. For example, underline is overloaded to be Commands.UNDERLINE, Commands.DOUBLE_UNDERLINE, or Commands.CURLY_UNDERLINE.
  • Color properties (foreground, background, decoration) can be command strings for standard colors, or arrays of commands for extended colors (3 elements for the 256 color mode, 5 elements for the true color mode).

Note: bold and dim are documented as intensities and share the same reset command. But actual implementations treat them as independent states. It is possible to combine them. The toolkit keep them separate, but when interpreting SGR sequences they are treated as the same state and will be reset together.

Given all that we can say that RESET_STATE (defined above) is a state with all properties reset to the initial values. An empty naked object {} is also a valid state. It defines a state when we have no idea what the current state is. An object {bold: '1'} defines a state with bold text on but no other properties are changed (we don't care about their states).

The module exposes the following functions:

Function	Return	Description
toState(state)	state	Sanitizes a state.
extractState(string, initState)	state	Extracts a state from the given string and adds it to the initial state.
combineStates(...states)	state	Combines multiple states into one in the given order.
commandToState(command)	state	Takes an array of commands and returns a state.
addCommandsToState(state, commands)	state	Takes an array of commands and adds them to the state.
stateToCommands(state)	array	Takes a state and returns an array of commands.
stateTransition(prevState, nextState)	array	Takes two states and returns an array of commands corresponding to the transition from the previous state to the next state.
stateReverseTransition(prevState, nextState)	array	Takes two states and returns an array of commands corresponding to the reverse transition from the next state to the previous state.
stringifyCommands(commands)	string	Takes an array of commands and returns a string representation of them as an SGR sequence.
optimize(string, initState = {})	string	Takes an SGR sequence and an initial state and returns an optimized version of it.

toState() is a sanitizer for states. When it takes null it returns RESET_STATE. If the input is an object with a method getState() it calls it and returns the result. Otherwise, it returns the object itself. If the input is a string it calls extractState() and returns the result. Otherwise, it return {} — an empty state with no known properties.

extractState() takes a string, extracts SGR sequences from it and adds them to the initial state. All other text is ignored.

stateTransition() produces a array of commands, which will transition from the previous state to the next one. stateReverseTransition() does the opposite. It is used to generate cleanup sequences. It is not an exact inverse of stateTransition() because it should handle the case when the previous state is undefined.

optimize() is used throughout the toolkit to optimize generated sequences. It takes a string and replaces all SGR sequences with their optimized versions preserving other text.

ansi/sgr-constants.js

The ansi/sgr-constants.js module exports most commonly used SGR commands as string constants. See the file for more details.

The provided commands:

• Common SGR commands:
  • BOLD, DIM, ITALIC, UNDERLINE, BLINK, RAPID_BLINK, INVERSE, HIDDEN, STRIKETHROUGH, OVERLINE.
• Reset commands:
  • Reset all: RESET_ALL, RESET (an alias of RESET_ALL).
  • Reset individual commands with prefixing them with RESET_: RESET_BOLD, RESET_DIM, RESET_ITALIC, RESET_UNDERLINE, RESET_BLINK, RESET_RAPID_BLINK, RESET_INVERSE, RESET_HIDDEN, RESET_STRIKETHROUGH, RESET_OVERLINE.
  • Reset colors and fonts: RESET_COLOR, RESET_BG_COLOR, RESET_FONT.
• Color commands:
  • Foreground color names: BLACK, RED, GREEN, YELLOW, BLUE, MAGENTA, CYAN, WHITE.
  • Bright foreground color names prefixed with BRIGHT_: BRIGHT_BLACK, BRIGHT_RED, BRIGHT_GREEN, BRIGHT_YELLOW, BRIGHT_BLUE, BRIGHT_MAGENTA, BRIGHT_CYAN, BRIGHT_WHITE.
  • Background color names prefixed with BG_: BG_BLACK, BG_RED, BG_GREEN, BG_YELLOW, BG_BLUE, BG_MAGENTA, BG_CYAN, BG_WHITE.
  • Bright background color names prefixed with BG_BRIGHT_: BG_BRIGHT_BLACK, BG_BRIGHT_RED, BG_BRIGHT_GREEN, BG_BRIGHT_YELLOW, BG_BRIGHT_BLUE, BG_BRIGHT_MAGENTA, BG_BRIGHT_CYAN, BG_BRIGHT_WHITE.
  • Explicit foreground color names prefixed with FG_: FG_BLACK, FG_RED, FG_GREEN, FG_YELLOW, FG_BLUE, FG_MAGENTA, FG_CYAN, FG_WHITE.
  • Explicit bright foreground color names prefixed with FG_BRIGHT_: FG_BRIGHT_BLACK, FG_BRIGHT_RED, FG_BRIGHT_GREEN, FG_BRIGHT_YELLOW, FG_BRIGHT_BLUE, FG_BRIGHT_MAGENTA, FG_BRIGHT_CYAN, FG_BRIGHT_WHITE.
  • Gray aliases: GRAY and GREY as aliases of BRIGHT_BLACK, BG_GRAY and BG_GREY as aliases of BG_BRIGHT_BLACK, FG_GRAY and FG_GREY as aliases of FG_BRIGHT_BLACK.

Exports

There is no default export.