node-ansiparser

2.2.1 verified Sat Apr 25 auth: no javascript

A parser for ANSI escape code sequences implementing the state machine described at vt100.net/emu/dec_ansi_parser. Version 2.2.1 is the latest stable release, with no further updates expected. It provides callbacks for printable characters, OSC, execute, CSI, ESC, and DCS sequences. Unlike alternatives (e.g., ansi-parser), this library follows the DEC ANSI parser specification closely, supports unicode, and allows injection of error handling. It is designed for Node.js and requires only a terminal object with specific callback methods.

Common errors

error TypeError: inst_x is not a function ↓

cause Terminal object is missing the inst_x method.

fix

Add an inst_x method to your terminal object: inst_x(flag) { console.log('execute', flag.charCodeAt(0)); }

error SyntaxError: Unexpected token '?' ↓

cause Using CommonJS require in a project with ESM-only settings.

fix

Use import statement: import AnsiParser from 'node-ansiparser'

error ReferenceError: AnsiParser is not defined ↓

cause Import path or module resolution issue.

fix

Ensure you have installed the package and use correct import: 'node-ansiparser'.

Warnings

gotcha Unicode high characters (>0x9f) are only allowed in GROUND, OSC_STRING, and DCS_PASSTHROUGH states; elsewhere they cancel the escape sequence. ↓

fix Ensure unicode input is cleanly split; avoid sending partial multibyte characters across parse calls.

gotcha The inst_p callback may be called with an incomplete character if a multibyte character is split across parse calls. ↓

fix Buffer partial characters manually; the parser does not reassemble multibyte sequences across calls.

deprecated Node.js require() usage may be deprecated in future; prefer ESM import. ↓

fix Use import AnsiParser from 'node-ansiparser' instead of require.

gotcha If the terminal object does not implement all required methods, the parser injects dummy methods silently. ↓

fix Always implement all callbacks (inst_p, inst_o, inst_x, inst_c, inst_e, inst_H, inst_P, inst_U) to avoid unexpected behavior.

gotcha The inst_E error callback expects a specific return object to abort; returning nothing defaults to continue with GROUND state. ↓

fix Return { abort: true } from inst_E to abort parsing on error.

Install

npm install node-ansiparser

yarn add node-ansiparser

pnpm add node-ansiparser

Imports

default
wrong
```
const AnsiParser = require('node-ansiparser')
```
correct
```
import AnsiParser from 'node-ansiparser'
```
ESM import is the modern usage; CommonJS require still works but may trigger deprecation.

AnsiParser

wrong

const { AnsiParser } = require('node-ansiparser')

correct

import { AnsiParser } from 'node-ansiparser'

Named export is available; many users expect a default export.

type
wrong
```
import AnsiParser from 'node-ansiparser'
```
correct
```
import type { AnsiParser } from 'node-ansiparser'
```
For TypeScript, use type-only import if only using types; the package ships no TS declarations.

Quickstart

Demonstrates basic ANSI escape sequence parsing with a terminal object that logs all callbacks.

import AnsiParser from 'node-ansiparser';

const terminal = {
  inst_p: (s) => console.log('print', s),
  inst_o: (s) => console.log('osc', s),
  inst_x: (flag) => console.log('execute', flag.charCodeAt(0)),
  inst_c: (collected, params, flag) => console.log('csi', collected, params, flag),
  inst_e: (collected, flag) => console.log('esc', collected, flag),
  inst_H: (collected, params, flag) => console.log('dcs_hook', collected, params, flag),
  inst_P: (data) => console.log('dcs_put', data),
  inst_U: () => console.log('dcs_unhook'),
  inst_E: (e) => { console.warn('error', e); return { abort: false }; }
};

const parser = new AnsiParser(terminal);
parser.parse('\x1b[31mHello\x1b[0m\x1b]0;title\x07');
parser.reset();