chess-utils

TypeScript utilities for chess-related projects.

Install

pnpm add chess-utils

Data Types

| Type | Description | | --- | --- | | Square | 0–63 index (a1 = 0, h8 = 63). | | Piece | Pawn, Knight, Bishop, Rook, Queen, King enum. | | Color | White or Black enum. | | PieceOnBoard | { kind: Piece; color: Color }. | | MoveRaw | Minimal move: { from, to, piece?, capture?, promotion, flags? }. | | Move | Fully resolved move with piece, capture, promotion, and flags filled. | | Board64 | 64-length array of PieceOnBoard | null indexed by Square. | | GameState | { board, sideToMove, castling, enPassant, halfmoveClock, fullmoveNumber }. | | Notation | 'san' | 'lan' | 'uci'. | | PGNMetadata | { [tag: string]: string } key/value tags. | | PGNResult | '1-0' | '0-1' | '1/2-1/2' | '*'. |

Exports

| Export | Role | Example | | --- | --- | --- | | initialGameState | Standard chess starting state. | const state = initialGameState(); | | parseFEN / formatFEN | FEN <-> GameState. | formatFEN(parseFEN(fen)) | | parseSAN / formatSAN | SAN parsing/formatting (needs state for disambiguation). | formatSAN(state, parseSAN(state, 'Nf3')) | | parseUCI / formatUCI | UCI parsing/formatting. | formatUCI(parseUCI('e2e4')) | | parseLAN / formatLAN | LAN parsing/formatting. | formatLAN(parseLAN('e2-e4')) | | convertNotation | Convert a single move between SAN/LAN/UCI. | convertNotation(state, 'e4', 'san', 'uci') | | parseMoveList | Parse a move list into { start, moves, final, result? }. | parseMoveList('e4 e5 Nf3') | | formatMoveList | Format MoveRaw[] back into text with optional numbers. | formatMoveList(start, moves) | | buildMoveTuples | Expand MoveRaw[] into [GameState, MoveRaw][] for UI/trees. | buildMoveTuples(start, moves) | | normalizeMoveText | Strip PGN tags/comments/nums/results into SAN list. | normalizeMoveText(pgn) | | moveListToFEN | Move list -> final FEN. | moveListToFEN('e2e4 e7e5', { notation: 'uci' }) | | moveListToPGN | Move list -> PGN with metadata. | moveListToPGN('e4 e5', { outputNotation: 'uci' }) | | parsePGN | PGN -> { metadata, start, moves, final, result? }. | parsePGN(pgn) | | formatPGN | Metadata + moves -> PGN text. | formatPGN(meta, start, moves) | | extractMetadata / formatPGNMetadata | Read/write PGN tag pairs. | extractMetadata(pgn) | | stripVariations / extractResultToken | PGN text helpers (remove variations, pull result). | stripVariations(pgn) | | clamp | Number clamping helper. | clamp(12, 0, 8) |

Quick Recipes

Parse PGN and get final FEN

import { parsePGN, formatFEN } from 'chess-utils';

const parsed = parsePGN(pgnText);
const fen = formatFEN(parsed.final);

Convert SAN list to UCI list

import { parseMoveList, formatMoveList } from 'chess-utils';

const { start, moves } = parseMoveList('e4 e5 Nf3');
const uci = formatMoveList(start, moves, { notation: 'uci', includeMoveNumbers: false });

Convert move list to PGN with metadata

import { moveListToPGN } from 'chess-utils';

const pgn = moveListToPGN('e4 e5 Nf3', {
  metadata: { Event: 'Casual', Result: '1-0' },
});

Normalize PGN move text

import { normalizeMoveText } from 'chess-utils';

const moves = normalizeMoveText(pgnText);
// "e4 e5 Nf3 Nc6 ..."