tessl/npm-chess-js

A TypeScript chess library used for chess move generation/validation, piece placement/movement, and check/checkmate/stalemate detection - basically everything but the AI.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Chess.js

Name: tessl/npm-chess-js
Author: tessl

Chess.js is a TypeScript chess library used for chess move generation/validation, piece placement/movement, and check/checkmate/stalemate detection - basically everything but the AI. It provides a complete chess engine with support for all standard chess rules, FEN and PGN formats, and comprehensive game analysis capabilities.

Package Information

Package Name: chess.js
Package Type: npm
Language: TypeScript
Installation: npm install chess.js

Core Imports

import { Chess, Move, validateFen } from "chess.js";
import { WHITE, BLACK, PAWN, KING, QUEEN, ROOK, BISHOP, KNIGHT } from "chess.js";
import { DEFAULT_POSITION, SQUARES, SEVEN_TAG_ROSTER } from "chess.js";

For CommonJS:

const { Chess, Move, validateFen } = require("chess.js");
const { WHITE, BLACK, PAWN, KING, QUEEN, ROOK, BISHOP, KNIGHT } = require("chess.js");

Basic Usage

import { Chess } from "chess.js";

// Create a new chess game
const chess = new Chess();

// Play a random game
while (!chess.isGameOver()) {
  const moves = chess.moves();
  const move = moves[Math.floor(Math.random() * moves.length)];
  chess.move(move);
}

// Get the game result
console.log(chess.pgn());
console.log(`Game over: ${chess.isCheckmate() ? 'Checkmate' : 'Draw'}`);

Architecture

Chess.js is built around several key components:

Chess Class: Core game engine managing board state, move generation, and rule enforcement
Move Class: Immutable move objects containing detailed move information and analysis methods
FEN Support: Complete Forsyth-Edwards Notation parsing and generation for position serialization
PGN Support: Portable Game Notation import/export with header and comment support
Move Generation: Efficient 0x88 board representation for fast legal move generation
Game Analysis: Built-in check/mate detection, draw conditions, and position evaluation

Capabilities

Game Management

Core chess game functionality for creating, managing, and analyzing chess positions and games.

class Chess {
  constructor(fen?: string, options?: { skipValidation?: boolean });
  reset(): void;
  clear(options?: { preserveHeaders?: boolean }): void;
  load(fen: string, options?: LoadOptions): void;
  fen(options?: { forceEnpassantSquare?: boolean }): string;
}

interface LoadOptions {
  skipValidation?: boolean;
  preserveHeaders?: boolean;
}

Game Management

Move Operations

Move generation, validation, and execution with support for standard and advanced chess notation.

class Chess {
  moves(options?: MovesOptions): string[] | Move[];
  move(move: string | MoveInput, options?: { strict?: boolean }): Move;
  undo(): Move | null;
}

interface MovesOptions {
  verbose?: boolean;
  square?: Square;
  piece?: PieceSymbol;
}

interface MoveInput {
  from: string;
  to: string;
  promotion?: string;
}

Move Operations

Board Representation

Board state access, piece manipulation, and visual representation methods.

class Chess {
  board(): (PieceInfo | null)[][];
  get(square: Square): Piece | undefined;
  put(piece: Piece, square: Square): boolean;
  remove(square: Square): Piece | undefined;
  findPiece(piece: Piece): Square[];
  ascii(): string;
}

interface PieceInfo {
  square: Square;
  type: PieceSymbol;
  color: Color;
}

interface Piece {
  type: PieceSymbol;
  color: Color;
}

Board Representation

Game Analysis

Position analysis including check/mate detection, draw conditions, and attack analysis.

class Chess {
  isCheck(): boolean;
  isCheckmate(): boolean;
  isStalemate(): boolean;
  isDraw(): boolean;
  isGameOver(): boolean;
  isAttacked(square: Square, attackedBy: Color): boolean;
  attackers(square: Square, attackedBy?: Color): Square[];
}

Game Analysis

FEN Support

Complete Forsyth-Edwards Notation support for position serialization and validation.

function validateFen(fen: string): FenValidationResult;

interface FenValidationResult {
  ok: boolean;
  error?: string;
}

FEN Support

Utility Functions

Random number generation utility for chess position hashing and analysis.

/**
 * Creates a xoroshiro128** pseudo-random number generator
 * @param state - Initial 128-bit state as bigint
 * @returns Generator function that returns bigint values
 */
function xoroshiro128(state: bigint): () => bigint;

PGN Support

Portable Game Notation import/export with headers, comments, and move annotation support.

class Chess {
  pgn(options?: PgnOptions): string;
  loadPgn(pgn: string, options?: LoadPgnOptions): void;
  setHeader(key: string, value: string): Record<string, string>;
  getHeaders(): Record<string, string>;
}

interface PgnOptions {
  newline?: string;
  maxWidth?: number;
}

interface LoadPgnOptions {
  strict?: boolean;
  newlineChar?: string;
}

PGN Support

Types

// Basic Types
type Color = 'w' | 'b';
type PieceSymbol = 'p' | 'n' | 'b' | 'r' | 'q' | 'k';
type Square = 'a8' | 'b8' | 'c8' | 'd8' | 'e8' | 'f8' | 'g8' | 'h8' |
              'a7' | 'b7' | 'c7' | 'd7' | 'e7' | 'f7' | 'g7' | 'h7' |
              'a6' | 'b6' | 'c6' | 'd6' | 'e6' | 'f6' | 'g6' | 'h6' |
              'a5' | 'b5' | 'c5' | 'd5' | 'e5' | 'f5' | 'g5' | 'h5' |
              'a4' | 'b4' | 'c4' | 'd4' | 'e4' | 'f4' | 'g4' | 'h4' |
              'a3' | 'b3' | 'c3' | 'd3' | 'e3' | 'f3' | 'g3' | 'h3' |
              'a2' | 'b2' | 'c2' | 'd2' | 'e2' | 'f2' | 'g2' | 'h2' |
              'a1' | 'b1' | 'c1' | 'd1' | 'e1' | 'f1' | 'g1' | 'h1';

// Constants
const WHITE = 'w';
const BLACK = 'b';
const PAWN = 'p';
const KNIGHT = 'n';
const BISHOP = 'b'; 
const ROOK = 'r';
const QUEEN = 'q';
const KING = 'k';
const DEFAULT_POSITION = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1';
const SQUARES: Square[] = [
  'a8', 'b8', 'c8', 'd8', 'e8', 'f8', 'g8', 'h8',
  'a7', 'b7', 'c7', 'd7', 'e7', 'f7', 'g7', 'h7',
  'a6', 'b6', 'c6', 'd6', 'e6', 'f6', 'g6', 'h6',
  'a5', 'b5', 'c5', 'd5', 'e5', 'f5', 'g5', 'h5',
  'a4', 'b4', 'c4', 'd4', 'e4', 'f4', 'g4', 'h4',
  'a3', 'b3', 'c3', 'd3', 'e3', 'f3', 'g3', 'h3',
  'a2', 'b2', 'c2', 'd2', 'e2', 'f2', 'g2', 'h2',
  'a1', 'b1', 'c1', 'd1', 'e1', 'f1', 'g1', 'h1'
];
const SEVEN_TAG_ROSTER: Record<string, string> = {
  Event: '?',
  Site: '?', 
  Date: '????.??.??',
  Round: '?',
  White: '?',
  Black: '?',
  Result: '*'
};