@echecs/san

Parse, resolve, and stringify SAN (Standard Algebraic Notation) chess moves. Strict TypeScript. Implements the notation defined in FIDE Laws of Chess, Appendix C.

Installation

npm install @echecs/san
Copy

Usage

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

// Parse SAN syntax only — returns a SanMove (no position needed)
const sanMove = parse('Nf3');

// Parse and resolve in one call — returns a Move with from/to squares
const move = parse('Nf3', position);

// Resolve a SanMove to a Move (find the from square)
const move = resolve(sanMove, position);

// Convert a Move back to a SAN string
const san = stringify(move, position);
Copy

API

parse(san: string): SanMove

Parses a SAN string and returns a SanMove describing the move's syntax. Does not require a position. Throws RangeError for empty or invalid input.

parse(san: string, position: Position): Move

Parses and resolves a SAN string against a position in one call. Equivalent to calling parse then resolve. Throws RangeError for empty, invalid, or illegal input.

resolve(move: SanMove, position: Position): Move

Finds the source square for a SanMove in the given position. Throws RangeError if no legal move matches or if the move is ambiguous.

stringify(move: Move, position: Position): string

Returns the SAN string for a Move in the given position, including disambiguation, capture marker, check, and checkmate symbols. Throws RangeError if no piece occupies the source square.

Types

interface SanMove {
  capture: boolean;
  castle: 'kingside' | 'queenside' | undefined;
  check: 'check' | 'checkmate' | undefined;
  file: File | undefined;
  piece: PieceType;
  promotion: PromotionPieceType | undefined;
  rank: Rank | undefined;
  to: Square | undefined;
}
Copy

file and rank are the disambiguation hints from the SAN string, not the destination square. to is undefined for castling moves.

Move is defined locally in @echecs/san:

interface Move {
  from: Square;
  promotion?: PromotionPieceType;
  to: Square;
}
Copy

Position is re-exported from @echecs/position for convenience. PromotionPieceType is the union of piece types a pawn can promote to:

import type { Move, Position, PromotionPieceType, SanMove } from '@echecs/san';
Copy

Errors

All functions throw RangeError for domain violations:

Situation	Message
Empty SAN string	Empty SAN string
Invalid SAN syntax	Invalid SAN: "<input>"
No legal move found	Describes the move
Ambiguous move	Lists the number of candidates
No piece on source square	Describes the square

License

MIT