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

Overview

Eval results

Files

Game Management

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

Core chess game functionality for creating, managing, and analyzing chess positions and games. Handles board initialization, position loading, and game state management.

Capabilities

Chess Class Constructor

Creates a new chess game instance with optional starting position.

/**
 * Creates a new chess game instance
 * @param fen - Optional FEN string for starting position (defaults to standard starting position)
 * @param options - Constructor options
 */
constructor(fen?: string, options?: ConstructorOptions);

interface ConstructorOptions {
  /** Skip FEN validation during construction */
  skipValidation?: boolean;
}

Usage Examples:

import { Chess, DEFAULT_POSITION } from "chess.js";

// Start from initial position
const chess = new Chess();

// Start from specific position
const chess2 = new Chess("r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3");

// Skip validation (use with caution)
const chess3 = new Chess("invalid-fen", { skipValidation: true });

Reset Game

Resets the board to the initial starting position.

/**
 * Reset the board to the initial starting position
 */
reset(): void;

Usage Examples:

const chess = new Chess();
chess.move('e4');
chess.move('e5');
chess.reset(); // Back to starting position

Clear Board

Clears the board of all pieces.

/**
 * Clear the board of all pieces
 * @param options - Clear options
 */
clear(options?: ClearOptions): void;

interface ClearOptions {
  /** Preserve PGN headers when clearing */
  preserveHeaders?: boolean;
}

Usage Examples:

const chess = new Chess();
chess.clear(); // Empty board
chess.clear({ preserveHeaders: true }); // Keep headers

Load Position

Loads a position from FEN string.

/**
 * Load a position from FEN string
 * @param fen - FEN string representing the position
 * @param options - Load options
 * @throws Error if FEN is invalid and validation enabled
 */
load(fen: string, options?: LoadOptions): void;

interface LoadOptions {
  /** Skip FEN validation */
  skipValidation?: boolean;
  /** Preserve existing PGN headers */
  preserveHeaders?: boolean;
}

Usage Examples:

const chess = new Chess();

// Load valid position
chess.load("r1bqkbnr/pppp1ppp/2n5/4p3/4P3/5N2/PPPP1PPP/RNBQKB1R w KQkq - 2 3");

// Load with error handling
try {
  chess.load("invalid-fen-string");
} catch (error) {
  console.error("Invalid FEN:", error.message);
}

// Skip validation (dangerous)
chess.load("potentially-invalid-fen", { skipValidation: true });

Get FEN String

Returns the current position as a FEN string.

/**
 * Get the current position as a FEN string
 * @param options - FEN generation options
 * @returns FEN string representing current position
 */
fen(options?: FenOptions): string;

interface FenOptions {
  /** Always include en passant square even if no legal capture exists */
  forceEnpassantSquare?: boolean;
}

Usage Examples:

const chess = new Chess();
console.log(chess.fen()); 
// "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"

chess.move('e4');
chess.move('e5');
chess.move('f4');
console.log(chess.fen());
// "rnbqkbnr/pppp1ppp/8/4p3/4PP2/8/PPPP2PP/RNBQKBNR b KQkq - 0 2"

// Force en passant square inclusion
console.log(chess.fen({ forceEnpassantSquare: true }));

Get Current Turn

Returns the current side to move.

/**
 * Get the current side to move
 * @returns Current player color
 */
turn(): Color;

Usage Examples:

const chess = new Chess();
console.log(chess.turn()); // 'w' (white to move)

chess.move('e4');
console.log(chess.turn()); // 'b' (black to move)

Set Turn

Sets the side to move (uses null move internally).

/**
 * Set the side to move
 * @param color - Color to set as active player
 * @returns True if turn was changed, false if already that player's turn
 * @throws Error if player is in check (cannot change turn while in check)
 */
setTurn(color: Color): boolean;

Usage Examples:

const chess = new Chess();
console.log(chess.turn()); // 'w'

chess.setTurn('b'); // Switch to black
console.log(chess.turn()); // 'b'

chess.setTurn('b'); // No change, returns false

Get Move Number

Returns the current move number.

/**
 * Get the current move number
 * @returns Current move number (increments after black's move)
 */
moveNumber(): number;

Usage Examples:

const chess = new Chess();
console.log(chess.moveNumber()); // 1

chess.move('e4'); // White's first move
console.log(chess.moveNumber()); // 1

chess.move('e5'); // Black's first move  
console.log(chess.moveNumber()); // 2

Types

type Color = 'w' | 'b';

interface ConstructorOptions {
  skipValidation?: boolean;
}

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

interface ClearOptions {
  preserveHeaders?: boolean;
}

interface FenOptions {
  forceEnpassantSquare?: boolean;
}

Install with Tessl CLI