isepic-chess.js

isepic-chess.js is a lightweight and flexible chess utility library for JavaScript, providing robust features like legal moves calculation, FEN validation, SAN parsing, and more. It emphasizes a UI-less and dependency-less design, making it a powerful backend for any chess application.

• :sparkles: Flexibility: Inspired by JavaScript's flexibility, it strives to make things work without easily giving up and throwing errors.


• :white_check_mark: Code Coverage: Despite its flexibility and complexity, it achieves an impressive 98~% code coverage ^{(as of v6.0.0)}, ensuring reliability.


• :chart_with_upwards_trend: Perft-Tested: Each release is rigorously tested against known Perft positions to guarantee accurate move generation.


• :no_entry_sign: UI-less: All user interface code is completely separated into the Isepic Chess UI project, keeping this library compact.


• :x: Dependency-less: It operates entirely without relying on any other external libraries.

:pushpin: Table of contents

- isepic-chess.js
- Table of contents
- Installation
- Node.js example
- Demo
- Features
- Documentation
- Copyright and license

:computer_mouse: Installation

``


NPM


npm install isepic-chess
`

Then: const {Ic} = require("isepic-chess");

---

`html


Web browser



`

The variable Ic will be added to window.

:green_heart: Node.js example

`js
const { Ic } = require('isepic-chess');

let example_pgn = [Event "m1 London"]
[Site "?"]
[Date "1861.07.??"]
[Round "9"]
[White "Kolisch, Ignatz"]
[Black "Anderssen, Adolf"]
[Result "0-1"]
[Annotator "JvR"]
[SetUp "1"]
[FEN "5r1k/pp4pp/3r3q/8/3PpP1P/1P2NbP1/PB1Q3K/R7 b - - 0 30"]
[PlyCount "13"]
[EventDate "1861.??.??"]

30... Rxf4 $1 {Anderssen starts fireworks.} 31. Qe1 (31.gxf4 $2 Qxh4+ 32.Kg1
Rg6+) 31... Rg6 (31...Rxh4+ $1 32.gxh4 Rg6 $1) 32. Bc1 (32.Ng2 $1) 32... Rxh4+
$1 33. gxh4 Qf4+ 34. Kh3 Bg2+ $1 35. Nxg2 Qf3+ 36. Kh2 Qxg2# { Anderssen won
the match by this mate (+4, =2, -3).} 0-1;

let board = Ic.initBoard({
pgn: example_pgn,
});

console.log(board.ascii());
// +------------------------+
// 8 | . . . . . . . k |
// 7 | p p . . . . p p |
// 6 | . . . . . . r . |
// 5 | . . . . . . . . |
// 4 | . . . P p . . P |
// 3 | . P . . . . . . |
// 2 | P . . . . . q K |
// 1 | R . B . Q . . . |
// +------------------------+
// a b c d e f g h

console.log(board.fen);
// "7k/pp4pp/6r1/8/3Pp2P/1P6/P5qK/R1B1Q3 w - - 0 37"

let fen_arr = [
'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1',
'r1bqk2r/pppp1pbp/2n2n2/4p3/5p2/2N3PN/PPPPP1BP/R1BQK2R w KQkq - 2 8',
'r2qkb1r/pbp1p1p1/1pnp1n1p/5p2/4P2P/5NP1/PPPPKPB1/RNBQR3 w kq - 0 8',
'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq - 0 1',
'r2qkbnr/ppp4p/2np1p2/4p3/3PP3/P2B1N2/1PP2PpP/RNBQ1RK1 b kq - 1 11',
];

/ transform each FEN into arrays with their legal SAN moves for the g2 square /
let mapped = fen_arr.map((fen) => Ic.fenApply(fen, 'legalSanMoves', ['g2']));

console.log(mapped);
// [
// ["g3", "g4"],
// ["Bf1", "Bf3", "Be4", "Bd5", "Bxc6"],
// ["Bh3", "Bh1", "Bf1"],
// [],
// ["gxf1=N", "gxf1=B", "gxf1=R+", "gxf1=Q+"]
// ]

/ get only the positions where the white king is not in its original square /
let filtered = fen_arr.filter((fen) => {
let rtn = false;
let obj = Ic.fenGet(fen, 'w');

if (obj) {
rtn = obj.w.kingBos !== 'e1';
}

return rtn;
});

console.log(filtered);
// [
// "r2qkb1r/pbp1p1p1/1pnp1n1p/5p2/4P2P/5NP1/PPPPKPB1/RNBQR3 w kq - 0 8",
// "r2qkbnr/ppp4p/2np1p2/4p3/3PP3/P2B1N2/1PP2PpP/RNBQ1RK1 b kq - 1 11"
// ]

let method_chaining = Ic('otherBoard')
.playMoves(['f3', 'e5', 'g4'])
.getCheckmateMoves()
.undoMove()
.playMoves(['e4', 'Qh4'])
.uciExport()
.legalUciMoves('g2');

console.log(method_chaining.stack);
// [
// true,
// ["d8h4"],
// {
// "colorMoved": "w",
// "colorToPlay": "b",
// "fen": "rnbqkbnr/pppp1ppp/8/4p3/6P1/5P2/PPPPP2P/RNBQKBNR b KQkq - 0 2",
// "san": "g4",
// "uci": "g2g4",
// "piece": "p",
// ...
// },
// true,
// "f2f3 e7e5 e2e4 d8h4"
// ["g2g3"]
// ]

console.log(method_chaining.board.legalUci);
// ["g2g3", "e1e2"]
``

:eye: Demo ^{(from isepic-chess-ui)}

https://ajax333221.github.io/isepic-chess-ui/

:rocket: Features

Core Game Logic:

• Generates Legal Moves: Efficiently calculates all legal moves for any given board state.


• Detects Checks, Checkmates & Draws: Identifies when a king is in check and recognizes checkmate and various draw positions. It also includes functions to find moves that lead to checkmate or a draw.


• Handles Pawn Promotion: Offers options to specify the desired promotion piece (Queen, Rook, Bishop, Knight).


• Calculates Material Difference: Quickly determines the material advantage for each side.


• Analyzes Square Control: Provides functionality to determine the number of attackers/defenders on any given square.

Game State Management:

• Comprehensive FEN Support: Imports (loadFen), exports (toFen), and performs advanced validation of FEN strings. Features powerful one-liner operations via Ic.fenApply() and Ic.fenGet().


• PGN Import/Export: Supports importing and exporting games in Portable Game Notation (PGN).


• UCI Import/Export: Compatible with Universal Chess Interface (UCI) for moves.


• Parses SAN (Standard Algebraic Notation): Converts human-readable SAN move strings into a machine-interpretable format for board operations.


• Navigable Move History: Offers full control over game history with methods for navigating (navFirst, navLast, navPrevious, navNext, undoMove, redoMove, toMove, reset).


• Multiple Board Instances: Allows managing several independent chess boards concurrently.

Miscellaneous:

• Type-Safe (TypeScript): Rewritten in TypeScript for improved code quality, maintainability, and enhanced developer experience.


• Chainable Board Methods: Provides a fluent API for chaining multiple board operations together for concise code.


• Generates ASCII Board Diagrams: Creates visual ASCII representations of the board state, useful for debugging or console output.


• Puzzle Mode: (🚧 work in progress 🚧) An upcoming feature designed to facilitate the creation, analysis, and solving of chess puzzles directly within the library.

:book: Documentation

- Examples
- Ic methods
- Board methods
- Board properties
- Square properties
- Move properties

:page_facing_up: Copyright and license

Copyright © 2026 Ajax Isepic (ajax333221)

Licensed under MIT License: http://opensource.org/licenses/mit-license.php