@marianmeres/chessboard

A dependency-light, pure-TS description of a chess board — its geometry, positions, rules, and notation. No rendering, no engine, no I/O.

Status: 0.x work in progress. API may change without ceremony until 1.0.

Four layered subpath exports — import only what you need (the root export re-exports everything):

| Subpath | Layer | Concern | | ---------------------------------- | ----- | -------------------------------------------------------------------- | | @marianmeres/chessboard/geometry | L0 | squares, files/ranks, piece vocabulary, distances, rays, orientation | | @marianmeres/chessboard/position | L1 | piece placement (Board), FEN | | @marianmeres/chessboard/rules | L2 | legal moves, make/unmake, SAN/UCI, perft | | @marianmeres/chessboard/game | L3 | PGN, variations, replay cursor |

Works in Deno, Node and browsers. The only runtime dependency is @marianmeres/clog (injectable logging). The rules layer is verified against the full published Chess Programming Wiki perft table.

Install

npm i @marianmeres/chessboard

deno add jsr:@marianmeres/chessboard

Basic Usage

Geometry — coordinates and orientation for a board UI

import {
	formatSquare,
	renderOrder,
	squareAtCell,
	squareColor,
} from "@marianmeres/chessboard/geometry";

// the 64 squares in display order (row-major from the screen's top-left),
// White at the bottom — everything a dumb grid renderer needs
for (const sq of renderOrder("white")) {
	console.log(formatSquare(sq), squareColor(sq)); // "a8 light", "b8 dark", ...
}

// hit-test a tap at grid cell col 4, row 4
squareAtCell(4, 4, "white"); // 28 — e4

Position — FEN in and out

import { formatFen, parseFen } from "@marianmeres/chessboard/position";

// parsing is permissive: never throws, collects diagnostics into `errors`
const { setup, errors } = parseFen(
	"r3k2r/p1ppqpb1/bn2pnp1/3PN3/1p2P3/2N2Q1p/PPPBBPPP/R3K2R w KQkq - 0 1",
);
errors; // [] — clean parse
setup.turn; // "w"
formatFen(setup); // round-trips

Rules — legal moves and SAN

import { createPosition } from "@marianmeres/chessboard/rules";

const pos = createPosition(); // standard initial position
pos.makeMove(pos.parseSan("e4")!);
pos.makeMove(pos.parseSan("c5")!);
pos.moves().length; // 30
pos.fen(); // "rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2"

Game — PGN and replay

import { parsePgn } from "@marianmeres/chessboard/game";

const pgn = `[Event "Casual"]

1. e4 e5 2. Nf3 Nc6 *`;

const { games, errors } = parsePgn(pgn); // never throws, whatever the input
const cursor = games[0].cursor();
while (cursor.next()) {
	console.log(cursor.node()!.san, cursor.fen());
}

API Reference

See API.md for the complete API documentation, and docs/DESIGN.md for the design rationale.

License

MIT