ansi-stream-parser

A parser for ANSI escape sequence text (SGR) that works on streaming/partial input.

Why another library? I needed a parser that could handle both streaming and also 256-color codes.

Installation

1npm install ansi-stream-parser

Usage

1import { createParser } from "ansi-stream-parser";
2
3const parser = createParser();
4
5// Parse ANSI text
6const styled = parser.push("\x1b[32mHello\x1b[0m \x1b[1;31mWorld\x1b[0m!");
7
8console.log(styled);
9// [
10//   { text: 'Hello', fg: { type: '16', code: 2 } },
11//   { text: ' ' },
12//   { text: 'World', fg: { type: '16', code: 1 }, decorations: ['bold'] },
13//   { text: '!' }
14// ]

Streaming

The parser maintains state across multiple calls making it ideal for streaming:

Note: you must consume the return value of each push call or you will lose the parsed results.

1const parser = createParser();
2
3// Feed data chunk by chunk
4const a = parser.push("\x1b[38;5;");
5// a is [] (still buffering)
6
7const b = parser.push("123m");
8// b is [] (still buffering)
9
10const result = parser.push("Colored text\x1b[0m");
11// result is [ { text: 'Colored text', fg: { type: '256', code: 123 } } ]

Tokenizer

The library also exports a tokenizer that emits tokens.

1import { createTokenizer } from "ansi-stream-parser";
2
3const tokenizer = createTokenizer();
4
5// Tokenize ANSI text into individual tokens
6const tokens = tokenizer.push("\x1b[32mHello\x1b[0m World");
7
8console.log(tokens);
9// [
10//   { type: 'set-fg-color', color: { type: '16', code: 2 } },
11//   { type: 'text', text: 'Hello' },
12//   { type: 'reset-all' },
13//   { type: 'text', text: ' World' }
14// ]
15
16// The tokenizer also handles streaming
17const a = tokenizer.push("\x1b[38;5;"); // [] (buffering)
18const b = tokenizer.push("196m"); // [{ type: 'set-fg-color', color: { type: '256', code: 196 } }]
19const c = tokenizer.push("Red"); // [{ type: 'text', text: 'Red' }]
20
21// Reset the tokenizer state
22tokenizer.reset();

The tokenizer is useful when you need more control over token processing or want to implement your own styling logic.

Color Helpers

The library provides color utilities for working with the parsed color values.

This is useful for when you're mapping StyledText parser output to HTML or other formats.

1import { getColor16Name, getColorHexCode, Color16 } from "ansi-stream-parser";
2
3// Get color name for 16-color codes
4const colorName = getColorName({ type: "16", code: 1 }); // "red"
5
6// Convert any color to hex code
7const hex16 = getColorHexCode({ type: "16", code: Color16.red }); // "#aa0000"
8const hex256 = getColorHexCode({ type: "256", code: 196 }); // "#ff0000"
9const hexRgb = getColorHexCode({ type: "rgb", rgb: [255, 0, 0] }); // "#ff0000"
10
11// Use a custom palette for 16-color codes
12const customPalette = [
13  [0, 0, 0], // black
14  [255, 0, 0], // red (brighter)
15  [0, 255, 0], // green (brighter)
16  [255, 255, 0], // yellow (brighter)
17  // ... continue for all 16 colors
18] as const;
19
20const customHex = getColorHexCode({ type: "16", code: 1 }, customPalette); // "#ff0000"

ANSI to HTML

Convert ANSI escape sequences to HTML spans with proper escaping.

Like the parser and tokenizer, this is a streaming transformer that processes input incrementally.

• Decorations (bold, italic, etc.) are converted to classes: .ansi-bold, .ansi-italic, etc.
• Foreground and background colors are converted to inline color and background-color styles with hex color codes.

1import { createAnsiToHtmlTransformer } from "ansi-stream-parser";
2
3const transformer = createAnsiToHtmlTransformer();
4
5const html1 = transformer.push("\x1b[32mHello ");
6const html2 = transformer.push("World\x1b[0m \x1b[1;31mBold");
7const html3 = transformer.push(" Text\x1b[0m!");
8
9assert.deepEqual(
10  [...html1, ...html2, ...html3],
11  [
12    '<span style="color: #00aa00">Hello World</span>',
13    "<span> </span>",
14    '<span class="ansi-bold" style="color: #aa0000">Bold Text</span>',
15    "<span>!</span>",
16  ],
17);

1/* Example CSS to handle the default html decorations */
2
3.ansi-bold {
4  font-weight: bold;
5}
6.ansi-dim {
7  opacity: 0.75;
8}
9.ansi-italic {
10  font-style: italic;
11}
12.ansi-underline {
13  text-decoration: underline;
14}
15.ansi-strikethrough {
16  text-decoration: line-through;
17}
18.ansi-underline.ansi-strikethrough {
19  text-decoration: underline line-through;
20}
21
22/* Probably nothing to do for these */
23.ansi-hidden,
24.ansi-reverse,
25.ansi-blink {
26}