Overview
The util module provides utility functions for converting between different representations of chess concepts, manipulating coordinates, parsing and formatting moves, and performing common chess-related operations.
Type Utilities
defined
function defined<A>(v: A | undefined): v is A
true if the value is not undefined, false otherwise.
Example:
const square = parseSquare('e4');
if (defined(square)) {
console.log(`Square index: ${square}`);
}
opposite
function opposite(color: Color): Color
'black' if color is 'white', otherwise 'white'.
Example:
const turn: Color = 'white';
const nextTurn = opposite(turn); // 'black'
Square Utilities
squareRank
function squareRank(square: Square): number
const e4 = 28;
const rank = squareRank(e4); // 3 (rank 4)
squareFile
function squareFile(square: Square): number
const e4 = 28;
const file = squareFile(e4); // 4 (file e)
squareFromCoords
function squareFromCoords(file: number, rank: number): Square | undefined
The file as a number from 0 (a) to 7 (h).
The rank as a number from 0 (1) to 7 (8).
undefined if coordinates are out of bounds.
Example:
const e4 = squareFromCoords(4, 3); // 28
const invalid = squareFromCoords(8, 0); // undefined
parseSquare
function parseSquare(str: SquareName): Square
function parseSquare(str: string): Square | undefined
The square name (e.g., ‘e4’, ‘a1’).
undefined if the string is not a valid square name.
Example:
const e4 = parseSquare('e4'); // 28
const a1 = parseSquare('a1'); // 0
const invalid = parseSquare('z9'); // undefined
makeSquare
function makeSquare(square: Square): SquareName
const name = makeSquare(28); // 'e4'
const corner = makeSquare(0); // 'a1'
Role Conversion
roleToChar
function roleToChar(role: Role): RoleChar
const char = roleToChar('knight'); // 'n'
const queenChar = roleToChar('queen'); // 'q'
charToRole
function charToRole(ch: RoleChar | Uppercase<RoleChar>): Role
function charToRole(ch: string): Role | undefined
The character to convert (e.g., ‘n’, ‘N’, ‘q’).
undefined if the character is not a valid role character.
Example:
const role = charToRole('n'); // 'knight'
const upper = charToRole('Q'); // 'queen'
const invalid = charToRole('x'); // undefined
Move Utilities
parseUci
function parseUci(str: string): Move | undefined
undefined if the string is not valid UCI notation.
Formats supported:
- Normal move:
'e2e4'
- Promotion:
'e7e8q'
- Drop move:
'N@f3'
Example:
const move = parseUci('e2e4'); // { from: 12, to: 28 }
const promotion = parseUci('e7e8q'); // { from: 52, to: 60, promotion: 'queen' }
const drop = parseUci('N@f3'); // { role: 'knight', to: 21 }
const invalid = parseUci('xyz'); // undefined
makeUci
function makeUci(move: Move): string
- Normal move:
'e2e4'
- Promotion:
'e7e8q'
- Drop move:
'N@f3' (uppercase piece letter)
Example:
const uci = makeUci({ from: 12, to: 28 }); // 'e2e4'
const withPromo = makeUci({ from: 52, to: 60, promotion: 'queen' }); // 'e7e8q'
const drop = makeUci({ role: 'knight', to: 21 }); // 'N@f3'
moveEquals
function moveEquals(left: Move, right: Move): boolean
true if the moves are equal, false otherwise.
Example:
const move1 = { from: 12, to: 28 };
const move2 = { from: 12, to: 28 };
const move3 = { from: 12, to: 29 };
moveEquals(move1, move2); // true
moveEquals(move1, move3); // false
Castling Utilities
kingCastlesTo
function kingCastlesTo(color: Color, side: CastlingSide): Square
The color of the castling player.
The castling side (‘a’ for queenside, ‘h’ for kingside).
const whiteKingside = kingCastlesTo('white', 'h'); // 6 (g1)
const whiteQueenside = kingCastlesTo('white', 'a'); // 2 (c1)
const blackKingside = kingCastlesTo('black', 'h'); // 62 (g8)
const blackQueenside = kingCastlesTo('black', 'a'); // 58 (c8)
rookCastlesTo
function rookCastlesTo(color: Color, side: CastlingSide): Square
The color of the castling player.
The castling side (‘a’ for queenside, ‘h’ for kingside).
const whiteKingside = rookCastlesTo('white', 'h'); // 5 (f1)
const whiteQueenside = rookCastlesTo('white', 'a'); // 3 (d1)
const blackKingside = rookCastlesTo('black', 'h'); // 61 (f8)
const blackQueenside = rookCastlesTo('black', 'a'); // 59 (d8)