@echecs/pgn

PGN

PGN is a fast, lightweight TypeScript parser for Portable Game Notation — the standard format for recording chess games.

It parses PGN input into structured move objects with decomposed SAN, paired white/black moves, and full support for annotations and variations. Zero runtime dependencies. The smallest PGN parser on npm.

Package	Pack size	Unpacked
@echecs/pgn	42 KB	195 KB
pgn-parser	99 KB	606 KB
@mliebelt/pgn-parser	148 KB	595 KB
chess.js	150 KB	724 KB

Why this library?

Most PGN parsers on npm either give you raw strings with no structure, or fail on anything beyond a plain game record. If you're building a chess engine, opening book, or game viewer, you need more:

• Decomposed SAN — every move is parsed into piece, from, to, capture, promotion, check, and checkmate fields. No regex on your side.
• Paired move structure — moves are returned as [moveNumber, whiteMove, blackMove] tuples, ready to render or process without further work.
• RAV support — recursive annotation variations ((...) sub-lines) are parsed into a variants tree on each move. Essential for opening books and annotated games.
• NAG support — symbolic (!, ?, !!, ??, !?, ?!) and numeric ($1–$255) annotations are surfaced as an annotations array. Essential for Lichess and ChessBase exports.
• Multi-game files — parse entire PGN databases in one call. Tested on files with 3 500+ games.
• Fast — built on a Peggy PEG parser. Throughput is within 1.1–1.2x of the fastest parsers on npm, which do far less work per move (see BENCHMARK_RESULTS.md).

If you only need raw SAN strings and a flat move list, any PGN parser will do. If you need structured, engine-ready output with annotations and variations, this is the one.

Installation

npm install @echecs/pgn

Quick Start

import parse from '@echecs/pgn';

const games = parse(`
  [Event "Example"]
  [White "Player1"]
  [Black "Player2"]
  [Result "1-0"]

  1. e4 e5 2. Nf3 Nc6 3. Bb5 1-0
`);

console.log(games[0].moves[0]);
// [1, { piece: 'pawn', to: 'e4', capture: false, ... }, { piece: 'pawn', to: 'e5', capture: false, ... }]

Usage

parse()

Takes a PGN string and returns an array of game objects — one per game in the file.

parse(input: string, options?: ParseOptions): PGN[]

stream() (deprecated)

Deprecated. Use parse() instead — it already handles multi-game input. stream() will be removed in the next major version. It emits a console.warn on first call.

stringify()

Converts one or more parsed PGN objects back into a valid PGN string, providing semantic round-trip fidelity.

stringify(input: PGN | PGN[], options?: StringifyOptions): string

Reconstructs SAN from Notation fields, re-serializes annotation commands ([%cal], [%csl], [%clk], [%eval]) back into comment blocks, and preserves RAVs and NAGs. Pass onWarning to observe recoverable issues (e.g. invalid castling destination, negative clock). StringifyOptions is a subset of ParseOptions — onError is not accepted since stringify never fails hard.

import parse, { stringify } from '@echecs/pgn';

const games = parse(pgnString);
const output = stringify(games); // valid PGN string

Error handling

By default, parse() silently returns [] on parse failure. Pass an onError callback to observe failures:

import parse, { type ParseError } from '@echecs/pgn';

const games = parse(input, {
  onError(err: ParseError) {
    console.error(
      `Parse failed at line ${err.line}:${err.column} — ${err.message}`,
    );
  },
});

onError receives a ParseError with:

Field	Type	Description
message	string	Human-readable description from the parser
offset	number	Character offset in the input (0-based)
line	number	1-based line number
column	number	1-based column number

Warnings

Pass onWarning to observe spec-compliance issues that do not prevent parsing:

import parse, { type ParseWarning } from '@echecs/pgn';

const games = parse(input, {
  onWarning(warn: ParseWarning) {
    console.warn(warn.message);
  },
});

onWarning receives a ParseWarning with the same fields as ParseError: message, offset, line, column.

Currently fires for:

• Missing STR tags (Black, Date, Event, Result, Round, Site, White) — emitted in alphabetical key order; position fields are nominal placeholders
• Move number mismatch (declared move number in the PGN text doesn't match the move's actual position) — position fields are nominal placeholders
• Result tag mismatch ([Result "..."] tag value differs from the game termination marker) — position fields are nominal placeholders
• Duplicate tag names — line and column point to the opening [ of the duplicate tag

The same option is accepted by stringify().

PGN object

{
  meta:   Meta,      // tag pairs (Event, Site, Date, White, Black, …)
  moves:  NotationList,  // paired notation list
  result: 1 | 0 | 0.5 | '?'
}

meta is an index of all tag pairs from the PGN header. The Result key is optional — games with no tag pairs return meta: {}. Use game.result (always present) as the authoritative game outcome.

Notation object

Notation extends SAN from @echecs/san — all SAN fields are always present.

{
  // SAN fields (always present)
  piece:       Piece,        // 'pawn' | 'knight' | 'bishop' | 'rook' | 'queen' | 'king'
  to:          Square | undefined, // destination square, e.g. "e4"; undefined for castling
  from:        Disambiguation | undefined, // file "e", rank "2", or square "e2"
  capture:     boolean,
  castling:    boolean,
  check:       boolean,
  checkmate:   boolean,
  long:        boolean,      // queenside castling
  promotion:   PromotionPiece | undefined, // 'queen' | 'rook' | 'bishop' | 'knight'

  // PGN-specific fields (optional)
  annotations?: string[],   // e.g. ["!", "$14"]
  comment?:    string,
  arrows?:     Arrow[],              // from [%cal ...] command
  squares?:    SquareAnnotation[],   // from [%csl ...] command
  clock?:      number,               // from [%clk ...] — seconds remaining
  eval?:       Eval,                 // from [%eval ...] — engine evaluation
  variants?:   NotationList[],  // recursive annotation variations
}

Moves are grouped into tuples: [moveNumber, whiteMove, blackMove]. Both move slots can be undefined — whiteMove when a variation begins on black's turn, blackMove when the game or variation ends on white's move.

Annotations and comments

12. Nf3! $14 { White has a slight advantage }

{
  piece: 'knight', to: 'f3', capture: false, castling: false,
  check: false, checkmate: false, long: false,
  from: undefined, promotion: undefined,
  annotations: ['!', '14'],  // numeric NAGs stored without '
Comment annotations
PGN files produced by GUIs and engines embed structured commands inside move
comments using the [%cmd ...] syntax. This library parses the four most common
commands and exposes them as dedicated fields on Notation:



Field
Type
PGN command
Description



arrows
Arrow[]
[%cal ...]
Coloured arrows drawn on the board


squares
SquareAnnotation[]
[%csl ...]
Coloured square highlights


clock
number
[%clk ...]
Remaining time in seconds (sub-second preserved)


eval
Eval
[%eval ...]
Engine evaluation (centipawns or mate-in-N)


Command strings are stripped from move.comment. Unknown [%...] commands are
left in the comment string unchanged.
Types
type AnnotationColor = 'B' | 'C' | 'G' | 'O' | 'R' | 'Y'; // Blue, Cyan, Green, Orange, Red, Yellow

interface Arrow {
  color: AnnotationColor;
  from: Square; // e.g. "e2"
  to: Square; // e.g. "e4"
}

interface SquareAnnotation {
  color: AnnotationColor;
  square: Square; // e.g. "e4"
}

type Eval =
  | { type: 'cp'; value: number; depth?: number } // centipawn score
  | { type: 'mate'; value: number; depth?: number }; // mate in N
Example
1. e4 { [%cal Ge2e4,Re4e5] [%clk 0:05:00] } e5
{
  piece: 'pawn', to: 'e4', capture: false, castling: false,
  check: false, checkmate: false, long: false,
  from: undefined, promotion: undefined,
  // comment is absent — no free text remains after stripping commands
  arrows: [
    { color: 'G', from: 'e2', to: 'e4' },
    { color: 'R', from: 'e4', to: 'e5' },
  ],
  clock: 300,    // 5 minutes in seconds
}
Variations
5... Ba5 (5... Be7 6. d4) 6. Qb3
The alternative line appears as a variants array on the move where it
branches:
{
  piece: 'bishop', to: 'a5', capture: false, castling: false,
  check: false, checkmate: false, long: false,
  from: undefined, promotion: undefined,
  variants: [
    [ [5, undefined, { piece: 'bishop', to: 'e7', ... }], [6, { piece: 'pawn', to: 'd4', ... }] ]
  ]
}
Exported types
All public types are exported as named type exports:
import type {
  AnnotationColor, // 'B' | 'C' | 'G' | 'O' | 'R' | 'Y'
  Arrow, // { color, from, to }
  Disambiguation, // Square | File | Rank
  Eval, // { type: 'cp' | 'mate', value, depth? }
  File, // 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h'
  Meta, // { [key: string]: string | undefined }
  Notation, // single parsed notation object (extends SAN)
  NotationList, // NotationPair[]
  NotationPair, // [number, Notation | undefined, Notation?]
  ParseError, // { message, offset, line, column }
  ParseOptions, // { onError?, onWarning? }
  ParseWarning, // { message, offset, line, column }
  PGN, // { meta, moves, result }
  Piece, // 'pawn' | 'knight' | 'bishop' | 'rook' | 'queen' | 'king'
  PromotionPiece, // 'knight' | 'bishop' | 'rook' | 'queen'
  Rank, // '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8'
  Result, // '1-0' | '0-1' | '1/2-1/2' | '?'
  SAN, // base SAN interface from @echecs/san
  Square, // `${File}${Rank}`, e.g. "e4"
  SquareAnnotation, // { color, square }
  StringifyOptions, // { onWarning? }
  Variation, // NotationList[]
} from '@echecs/pgn';
Contributing
Contributions are welcome. Please read CONTRIBUTING.md for
guidelines on how to submit issues and pull requests.
 prefix
  comment: 'White has a slight advantage'
}

Comment annotations

PGN files produced by GUIs and engines embed structured commands inside move comments using the __INLINE_CODE_84__ syntax. This library parses the four most common commands and exposes them as dedicated fields on __INLINE_CODE_85__:

Field	Type	PGN command	Description
__INLINE_CODE_86__	__INLINE_CODE_87__	__INLINE_CODE_88__	Coloured arrows drawn on the board
__INLINE_CODE_89__	__INLINE_CODE_90__	__INLINE_CODE_91__	Coloured square highlights
__INLINE_CODE_92__	__INLINE_CODE_93__	__INLINE_CODE_94__	Remaining time in seconds (sub-second preserved)
__INLINE_CODE_95__	__INLINE_CODE_96__	__INLINE_CODE_97__	Engine evaluation (centipawns or mate-in-N)

Command strings are stripped from __INLINE_CODE_98__. Unknown __INLINE_CODE_99__ commands are left in the comment string unchanged.

Types

__CODE_BLOCK_11__

Example

__CODE_BLOCK_12__ __CODE_BLOCK_13__

Variations

__CODE_BLOCK_14__

The alternative line appears as a __INLINE_CODE_100__ array on the move where it branches:

__CODE_BLOCK_15__

Exported types

All public types are exported as named type exports:

__CODE_BLOCK_16__

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on how to submit issues and pull requests.