js-chess-engine 1.0.2 → 2.0.0

package/README.md

@@ -1,338 +1,719 @@
 # JS-CHESS-ENGINE
+
 ![GitHub package.json version](https://img.shields.io/github/package-json/v/josefjadrny/js-chess-engine)
-![Test](https://raw.githubusercontent.com/josefjadrny/js-chess-engine/master/test/badge.svg?sanitize=true)
-![CI](https://github.com/josefjadrny/js-chess-engine/actions/workflows/main.yml/badge.svg?branch=master)
-[![JavaScript Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://standardjs.com)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Simple JavaScript chess engine without dependencies written in NodeJs.
-It can be used on both, server or client (web browser) and do not need persistent storage - handy for serverless solutions like AWS Lambda.
-This engine also includes configurable basic [AI computer logic](#computer-ai).
+Complete TypeScript chess engine without dependencies for Node.js >=24 and browsers. Includes configurable AI with difficulty levels 1-5.
+
+**⚠️ Upgrading from v1?** See [Breaking Changes](#breaking-changes-from-v1) section at the end of this document
 
 ## Install
+
 **Install with npm**
 
-```npm i js-chess-engine --save```
+```bash
+npm i js-chess-engine --save
+```
 
 **or install with yarn**
 
-```yarn add js-chess-engine```
+```bash
+yarn add js-chess-engine
+```
 
-**Example**
+**Node.js Requirement:** Node.js >=24 is required for v2.
 
-```js
-const jsChessEngine = require('js-chess-engine')
-const game = new jsChessEngine.Game()
-game.printToConsole()
-```
-more about [importing](#import) this library.
-## Examples
-**js-chess-engine-app** - React application example with js-chess-engine REST API backend (without persistent storage) - [GitHub](https://github.com/josefjadrny/js-chess-engine-app) or [LIVE DEMO](http://chess.nadsenyvyvojar.cz/)
+## Import
 
-**More examples**<BR/>
-[Simple Fastify server](example/server.mjs) <BR/>
-[Console](example/console.mjs) <BR/>
-[PC vs PC match](example/aiMatch.mjs) <BR/>
+### TypeScript / ESM
 
-## Documentation
-### Import
-In this documentation I am using CommonJS require known from Node.js, but there are several ways how to import this library.
+```typescript
+// Import Game class and stateless functions
+import { Game, moves, status, move, aiMove, getFen } from 'js-chess-engine'
 
-**Node.js (ESM)**
-```js
-import jsChessEngine from 'js-chess-engine'
-const game = new jsChessEngine.Game()
+// Import types for TypeScript
+import type { BoardConfig, PieceSymbol, MovesMap, AILevel } from 'js-chess-engine'
+
+const game = new Game()
 ```
 
-**Node.js (CommonJS)**
-```js
-const jsChessEngine = require('js-chess-engine')
-const game = new jsChessEngine.Game()
+### CommonJS (Node.js)
+
+```javascript
+const { Game, moves, status, move, aiMove, getFen } = require('js-chess-engine')
+
+const game = new Game()
 ```
 
-**React**
-```js
-import { Game, move, status, moves, aiMove, getFen } from 'js-chess-engine'
+### React / Modern JavaScript
+
+```typescript
+import { Game } from 'js-chess-engine'
+import type { BoardConfig, MovesMap } from 'js-chess-engine'
+
 const game = new Game()
+const allMoves: MovesMap = game.moves()
 ```
 
-You can find more about UMD [here](https://github.com/umdjs/umd).
+## Examples
 
-**Basically, you have two options how to use this engine.** <BR/>
-- [With in-memory](#option-1---with-in-memory)
-- [Without in-memory (on-the-fly)](#option-2---without-in-memory)
+**js-chess-engine-app** - React application example with js-chess-engine REST API backend (without persistent storage) - [GitHub](https://github.com/josefjadrny/js-chess-engine-app) or [LIVE DEMO](http://chess.josefjadrny.info/)
 
-<BR/>
+**Note:** Additional examples for v2 (server, console, AI match) will be added in a future release.
+
+## Documentation
+
+You have two options for using this engine:
+
+- [Option 1 - With in-memory (Game class)](#option-1---with-in-memory)
+- [Option 2 - Without in-memory (Stateless functions)](#option-2---without-in-memory)
 
 ### Option 1 - With in-memory
-Use the Game class and create a new game.
-```js
-const jsChessEngine = require('js-chess-engine')
-const game = new jsChessEngine.Game()
+
+Use the Game class to create and manage a chess game. In this mode, the game state is cached in memory for better performance.
+
+```typescript
+import { Game } from 'js-chess-engine'
+import type { BoardConfig, MovesMap } from 'js-chess-engine'
+
+const game = new Game()
 ```
 
-You can control your game with game object.
-In this mode, many things on the chessboard are cached (in-memory), so it is faster.
-You can still export your game to JSON or FEN and you can use this JSON or FEN to continue your game later.
+You can export your game to JSON or FEN at any time and use these formats to restore your game later.
 
-#### API description
+#### API Description
 
 **constructor**
 
-`new Game(configuration)` - Create a new game, init players and in-game situation. 
+`new Game(configuration)` - Create a new game with optional initial configuration.
+
+Params:
+- `configuration` BoardConfig | string (_optional_) - Chess board [configuration](#board-configuration) (JSON object or FEN string). Default is standard starting position.
+
+```typescript
+import { Game } from 'js-chess-engine'
+import type { BoardConfig } from 'js-chess-engine'
+
+// New game with starting position
+const game1 = new Game()
 
-Params
- - `configuration` Object or String (_optional_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
+// From FEN string
+const game2 = new Game('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1')
+
+// From BoardConfig object
+const config: BoardConfig = { /* ... */ }
+const game3 = new Game(config)
+```
 
 **move**
 
-`game.move(from, to)` - Perform a move on a chessboard and recalculates in-game situation. Returns played move `{"H7":"H5"}`
+`game.move(from, to)` - Perform a move on the chessboard and recalculate game state. **Returns full BoardConfig object** (breaking change from v1).
+
+Params:
+- `from` string (_mandatory_) - Starting square (case-insensitive, e.g., 'E2' or 'e2')
+- `to` string (_mandatory_) - Destination square (case-insensitive, e.g., 'E4' or 'e4')
+
+Returns: `BoardConfig` - Full board configuration after the move
+
+```typescript
+import type { BoardConfig } from 'js-chess-engine'
 
-Params
- - `from` String (_mandatory_) - Location on a chessboard where move starts (like A1,B3,...)
- - `to` String (_mandatory_) - Location on a chessboard where move ends (like A1,B3,...)
+const newConfig: BoardConfig = game.move('E2', 'E4')
+console.log(newConfig.pieces)  // {"E4": "P", "E1": "K", ...}
+```
 
 **moves**
 
-`game.moves(from)` - Return possible moves for playing player.
+`game.moves(from?)` - Get all legal moves for the current player. Optionally filter by a specific square.
+
+Params:
+- `from` string (_optional_) - Square to filter moves from (case-insensitive, e.g., 'E2'). If omitted, returns moves for all pieces.
+
+Returns: `MovesMap` - Object mapping from-squares to arrays of to-squares
 
-Params
- - `from` String (_optional_) - Location on a chessboard (like A1,B3,...). When not provided, returns all possible moves.
+```typescript
+import type { MovesMap } from 'js-chess-engine'
+
+// Get all moves (no parameter)
+const allMoves: MovesMap = game.moves()
+// {"E2": ["E3", "E4"], "B1": ["A3", "C3"], ...}
+
+// Get moves for specific square
+const pawnMoves: MovesMap = game.moves('E2')
+// {"E2": ["E3", "E4"]}
+```
 
 **setPiece**
 
-`game.setPiece(location, piece)` - New chess piece is added to provided location. Piece on provided location is replaced.
+`game.setPiece(location, piece)` - Add or replace a chess piece at the specified location.
 
-Params
-- `location` String (_mandatory_) - Location on a chessboard (like A1,B3,...).
-- `piece` String (_mandatory_) - A chess piece you need add (pieces syntax is same as FEN notation).
+Params:
+- `location` string (_mandatory_) - Square location (case-insensitive, e.g., 'E2')
+- `piece` PieceSymbol (_mandatory_) - Piece symbol using FEN notation (K, Q, R, B, N, P for white; k, q, r, b, n, p for black)
+
+```typescript
+import type { PieceSymbol } from 'js-chess-engine'
+
+const piece: PieceSymbol = 'Q'
+game.setPiece('E5', piece)
+```
 
 **removePiece**
 
-`game.removePiece(location)` - Remove piece on provided location.
+`game.removePiece(location)` - Remove a piece from the specified location.
 
-Params
-- `location` String (_mandatory_) - Location on a chessboard (like A1,B3,...).
+Params:
+- `location` string (_mandatory_) - Square location (case-insensitive, e.g., 'E2')
+
+```typescript
+game.removePiece('E5')
+```
 
 **aiMove**
 
-`game.aiMove(level)` - Calculates and perform next move by computer player. `game.move(from, to)` is called internally. Returns played move `{"H7":"H5"}`
+`game.aiMove(level)` - Calculate and perform the best move for the current player using AI. **Returns only the move** (v1 API compatible).
 
-Params
- - `level` Integer (_optional_) - Computer player skill from 0 to 3. Read more about [computer AI](#computer-ai). Default 2.
+Params:
+- `level` AILevel (_optional_) - AI difficulty level (1-5). See [Computer AI](#computer-ai) section. Default: 3
+
+Returns: `HistoryEntry` - The played move (e.g., `{"E2": "E4"}`)
+
+```typescript
+import type { HistoryEntry, AILevel } from 'js-chess-engine'
+
+const level: AILevel = 4
+const move: HistoryEntry = game.aiMove(level)
+console.log(move) // {"E2": "E4"}
+
+// To get board state after move, use exportJson()
+const board = game.exportJson()
+```
+
+**ai**
+
+`game.ai(options?)` - Calculate the best move using AI. **Returns both the move and board state**.
+
+Params:
+- `options` object (_optional_) - Configuration options:
+  - `level` number (_optional_) - AI difficulty level (1-5). See [Computer AI](#computer-ai) section. Default: `3`
+  - `play` boolean (_optional_) - Whether to apply the move to the game. Default: `true`. If `false`, returns the move without modifying the game state, and `board` will contain the current state (before the move).
+  - `ttSizeMB` number (_optional_) - Transposition table size in MB (0 to disable, 0.25-256). Default: **auto-scaled by AI level**. See [Auto-Scaling Transposition Table](#transposition-table) for details.
+
+Returns: `{ move: HistoryEntry, board: BoardConfig }` - Object containing the move and board state (current state if `play=false`, updated state if `play=true`)
+
+```typescript
+import type { HistoryEntry, BoardConfig } from 'js-chess-engine'
+
+// Play the move (default behavior)
+const result1 = game.ai({ level: 4 })
+console.log(result1.move)       // {"E2": "E4"}
+console.log(result1.board.turn) // "black" (updated after move)
+
+// Analysis mode: get move without applying it
+const result2 = game.ai({ level: 4, play: false })
+console.log(result2.move)       // {"E2": "E4"}
+console.log(result2.board.turn) // "white" (current state, before move)
+
+// Use default level 3
+const result3 = game.ai()
+console.log(result3.move) // AI move with level 3
+
+// TT size auto-scales by level (see Auto-Scaling Transposition Table section)
+const result4 = game.ai({ level: 5 })
+console.log(result4.move) // Level 5: 64 MB Node.js / 32 MB browser (auto)
+
+// Override TT size manually if needed
+const result5 = game.ai({ level: 3, ttSizeMB: 128 })
+console.log(result5.move) // Force 128MB cache
+
+// Ultra-lightweight mode for low-end devices
+const result6 = game.ai({ level: 2, ttSizeMB: 0.5 })
+console.log(result6.move) // Force 512KB cache
+```
 
 **getHistory**
 
-`game.getHistory(reversed)` - Returns all played moves in array with chess board configuration like `[{from:'A2',to:'A3',configuration:{...}},{from:'A7',to:'A6',configuration:{...}}]`.
+`game.getHistory()` - Get all played moves with board states.
 
-`configuration` object is a previous chess board [configuration](#board-configuration) (before that move was played) and can be used to start new game with `new Game(configuration)`.
+Returns: Array of objects containing move and resulting board configuration
 
-Params
-- `reversed` Boolean (_optional_) - When false, last move is the last element in returned array. When true, last move is first. Default false.
+```typescript
+const history = game.getHistory()
+// [
+//   { move: {"E2": "E4"}, pieces: {...}, turn: "black", ... },
+//   { move: {"E7": "E5"}, pieces: {...}, turn: "white", ... }
+// ]
+```
 
 **printToConsole**
 
-`game.printToConsole()` - Print a chessboard to console standard output.
+`game.printToConsole()` - Print an ASCII representation of the chessboard to console.
+
+```typescript
+game.printToConsole()
+//   +---+---+---+---+---+---+---+---+
+// 8 | r | n | b | q | k | b | n | r |
+//   +---+---+---+---+---+---+---+---+
+// 7 | p | p | p | p | p | p | p | p |
+//   +---+---+---+---+---+---+---+---+
+// ...
+```
 
 **exportJson**
 
-`game.exportJson()` - Return in-game situation represented by JSON [configuration](#board-configuration).
+`game.exportJson()` - Export current game state as a JSON BoardConfig object.
+
+Returns: `BoardConfig` - Full board configuration
+
+```typescript
+import type { BoardConfig } from 'js-chess-engine'
+
+const config: BoardConfig = game.exportJson()
+```
 
 **exportFEN**
 
-`game.exportFEN()` - Return in-game situation represented by [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation).
+`game.exportFEN()` - Export current game state as a FEN string.
 
-<BR/>
+Returns: string - [FEN notation](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation)
+
+```typescript
+const fen: string = game.exportFEN()
+// "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1"
+```
 
 ### Option 2 - Without in-memory
-It is possible to avoid using a Game object and call stateless functions directly. Every function needs configuration of your chessboard to work properly.
-This approach needs little more computing time to create and calculate everything from scratch for every call. 
-But this can be handy in stateless environments.
 
-```js
-const jsChessEngine = require('js-chess-engine')
-const { move, status, moves, aiMove, getFen } = jsChessEngine
+Call stateless functions directly without creating a Game object. This is ideal for serverless environments or when you want to manage state externally.
+
+```typescript
+import { move, moves, status, aiMove, ai, getFen } from 'js-chess-engine'
+import type { BoardConfig, MovesMap } from 'js-chess-engine'
 ```
-#### API description
+
+These functions require a board configuration for each call (either a BoardConfig object or FEN string).
+
+#### API Description
 
 **moves**
 
-`moves(boardConfiguration)` - Returns an Object with possible moves for playing player `{"B1":["A3","C3"],"G1":["F3","H3"]}`.
+`moves(boardConfiguration)` - Get all legal moves for the current player.
+
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration) (JSON object or FEN string)
+
+Returns: `MovesMap` - Object mapping from-squares to arrays of to-squares
+
+```typescript
+import { moves } from 'js-chess-engine'
+import type { MovesMap, BoardConfig } from 'js-chess-engine'
 
-Params
- - `boardConfiguration` Object or String (_mandatory_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
+// From BoardConfig object
+const config: BoardConfig = { /* ... */ }
+const allMoves: MovesMap = moves(config)
+// {"E2": ["E3", "E4"], "B1": ["A3", "C3"], ...}
+
+// From FEN string
+const fenMoves: MovesMap = moves('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1')
+```
 
 **status**
 
-`status(boardConfiguration)` - Return calculated JSON board [configuration](#board-configuration). You can use this function to convert your FEN to JSON.
+`status(boardConfiguration)` - Get calculated board configuration with current game status. Useful for converting FEN to JSON.
+
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration)
+
+Returns: `BoardConfig` - Full board configuration with status
+
+```typescript
+import { status } from 'js-chess-engine'
+import type { BoardConfig } from 'js-chess-engine'
 
-Params
- - `boardConfiguration` Object or String (_mandatory_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
+// Convert FEN to JSON
+const config: BoardConfig = status('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1')
+console.log(config.turn)      // "black"
+console.log(config.check)     // false
+console.log(config.checkMate) // false
+```
+
+**getFen**
+
+`getFen(boardConfiguration)` - Convert board configuration to FEN string.
 
-**getFEN**
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration)
 
-`getFEN(boardConfiguration)` - Return [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) string, representation of your chessboard.
+Returns: string - [FEN notation](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation)
 
-Params
- - `boardConfiguration` Object or String (_mandatory_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
+```typescript
+import { getFen } from 'js-chess-engine'
+import type { BoardConfig } from 'js-chess-engine'
+
+const config: BoardConfig = { /* ... */ }
+const fen: string = getFen(config)
+```
 
 **move**
 
-`move(boardConfiguration, from, to)` - Perform a move on a chessboard and recalculates in-game situation. New configuration of your chessboard is returned.
+`move(boardConfiguration, from, to)` - Perform a move and get the new board state. **Returns full BoardConfig object** (breaking change from v1).
 
-Params
- - `boardConfiguration` Object or String (_mandatory_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
- - `from` String (_mandatory_) - Location on a chessboard where move starts (like A1,B3,...)
- - `to` String (_mandatory_) - Location on a chessboard where move ends (like A1,B3,...)
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration)
+- `from` string (_mandatory_) - Starting square (case-insensitive)
+- `to` string (_mandatory_) - Destination square (case-insensitive)
+
+Returns: `BoardConfig` - Full board configuration after the move
+
+```typescript
+import { move } from 'js-chess-engine'
+import type { BoardConfig } from 'js-chess-engine'
+
+// Move from FEN string
+const config1: BoardConfig = move('rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1', 'E2', 'E4')
+
+// Move on existing config
+const config2: BoardConfig = move(config1, 'E7', 'E5')
+```
 
 **aiMove**
 
-`aiMove(boardConfiguration, level)` - Return computed move as an object like `{"H7":"H5"}`. Use `move(yourBoardConfiguration, from, to)` to play this move.
+`aiMove(boardConfiguration, level)` - Calculate and return the best move using AI. **Returns only the move** (v1 API compatible).
+
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration)
+- `level` AILevel (_optional_) - AI difficulty level (1-5). Default: 3
+
+Returns: `HistoryEntry` - The played move (e.g., `{"E2": "E4"}`)
+
+```typescript
+import { aiMove } from 'js-chess-engine'
+import type { HistoryEntry, AILevel } from 'js-chess-engine'
+
+const fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
+const level: AILevel = 4
+const move: HistoryEntry = aiMove(fen, level)
+console.log(move) // {"E2": "E4"}
+```
+
+**ai**
 
-Params
- - `boardConfiguration` Object or String (_mandatory_) - Is a chess board [configuration](#board-configuration). Default value is a configuration for new game.
- - `level` Integer (_optional_) - Computer player skill from 0 to 3. Read more about [computer AI](#computer-ai). Default 2.
+`ai(boardConfiguration, options?)` - Calculate the best move using AI. **Returns both the move and board state**.
 
-<BR/>
+Params:
+- `boardConfiguration` BoardConfig | string (_mandatory_) - Board [configuration](#board-configuration)
+- `options` object (_optional_) - Configuration options:
+  - `level` number (_optional_) - AI difficulty level (1-5). Default: `3`
+  - `play` boolean (_optional_) - Whether to apply the move to the board. Default: `true`. If `false`, returns the move without modifying the board state, and `board` will contain the current state (before the move).
+  - `ttSizeMB` number (_optional_) - Transposition table size in MB (0 to disable, 0.25-256). Default: **auto-scaled by AI level**. See [Auto-Scaling Transposition Table](#transposition-table) for details.
+
+Returns: `{ move: HistoryEntry, board: BoardConfig }` - Object containing the move and board state (current state if `play=false`, updated state if `play=true`)
+
+```typescript
+import { ai } from 'js-chess-engine'
+import type { HistoryEntry, BoardConfig } from 'js-chess-engine'
+
+const fen = 'rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1'
+
+// Play the move (default behavior)
+const result1 = ai(fen, { level: 4 })
+console.log(result1.move)       // {"E2": "E4"}
+console.log(result1.board.turn) // "black" (updated after move)
+
+// Analysis mode: get move without applying it
+const result2 = ai(fen, { level: 4, play: false })
+console.log(result2.move)       // {"E2": "E4"}
+console.log(result2.board.turn) // "white" (current state, before move)
+
+// Use default level 3
+const result3 = ai(fen)
+console.log(result3.move) // AI move with level 3
+
+// TT size auto-scales by level (see Auto-Scaling Transposition Table section)
+const result4 = ai(fen, { level: 5 })
+console.log(result4.move) // Level 5: 64 MB Node.js / 32 MB browser (auto)
+
+// Override TT size manually if needed
+const result5 = ai(fen, { level: 3, ttSizeMB: 128 })
+console.log(result5.move) // Force 128MB cache
+
+// Ultra-lightweight mode for low-end devices
+const result6 = ai(fen, { level: 2, ttSizeMB: 0.5 })
+console.log(result6.move) // Force 512KB cache
+```
 
 ### Board Configuration
-Board configuration could be described by JSON Object or FEN.
-
-#### JSON
-This can be handy for modern application, where is a state represented by an Object (like in React, Redux,...).
-You can easily merge returned state with your app state and get a new updated chessboard.
-
-
-```json
-{
-    "turn": "black",
-    "pieces": {
-        "E1": "K",
-        "C1": "B",
-        "E8": "k"
-    },
-    "moves": {
-      "E8": ["E7", "F8", "F7", "D8", "D7"]
-    },
-    "isFinished": false,
-    "check": false,
-    "checkMate": false,
-    "castling": {
-        "whiteLong": true,
-        "whiteShort": true,
-        "blackLong": true,
-        "blackShort": true    
-    },
-    "enPassant": "E6",
-    "halfMove": 0,
-    "fullMove": 1
+
+Board configuration can be represented as either a JSON object (BoardConfig) or a FEN string.
+
+#### JSON Format
+
+The JSON format is convenient for modern applications where state is represented as objects (React, Redux, etc.).
+
+```typescript
+import type { BoardConfig } from 'js-chess-engine'
+
+const config: BoardConfig = {
+  "turn": "black",
+  "pieces": {
+    "E1": "K",
+    "C1": "B",
+    "E8": "k"
+  },
+  "isFinished": false,
+  "check": false,
+  "checkMate": false,
+  "castling": {
+    "whiteLong": true,
+    "whiteShort": true,
+    "blackLong": true,
+    "blackShort": true
+  },
+  "enPassant": "E6",
+  "halfMove": 0,
+  "fullMove": 1
 }
 ```
 
-**turn** - Player which plays next. Values `white` (default) or `black`.
+**turn** - Player to move next. Values: `"white"` (default) or `"black"`
 
-**isFinished** - `true` when playing player cannot move (checkmate or draw). Default `false`.
+**isFinished** - `true` when the game is over (checkmate or stalemate). Default: `false`
 
-**check** - `true` when playing player is in check. Default `false`.
+**check** - `true` when the current player is in check. Default: `false`
 
-**checkMate** - `true` when playing player has checkmate. Default `false`.
+**checkMate** - `true` when the current player is checkmated. Default: `false`
 
-**castling** - Indicators if castling is still possible. `true` means yes. Default `true`.
- - `whiteLong` (_queenside_) - White king moves from E1 to C1.
- - `whiteShort`(_kingside_) - White king moves from E1 to G1.
- - `blackLong` (_queenside_) - Black king moves from E8 to C8.
- - `blackShort` (_kingside_) - Black king moves from E8 to C8.
- 
-**enPassant** - If a pawn has just made a two-square move, this is the position "behind" the pawn.
-This is an indicator for [enPassant](https://en.wikipedia.org/wiki/En_passant) special pawn move. Default `null`.
+**castling** - Castling availability for each side. `true` means castling is still possible. Default: all `true`
+- `whiteLong` (queenside) - White king moves from E1 to C1
+- `whiteShort` (kingside) - White king moves from E1 to G1
+- `blackLong` (queenside) - Black king moves from E8 to C8
+- `blackShort` (kingside) - Black king moves from E8 to G8
 
-**halfMove** - This is the number of halfmoves since the last capture or pawn advance. This is used to determine if a draw can be claimed under the fifty-move rule. Default `0`.
+**enPassant** - If a pawn just made a two-square move, this is the square "behind" the pawn for [en passant](https://en.wikipedia.org/wiki/En_passant) capture. Default: `null`
 
-**fullMove** - The number of the full move. It starts at 1, and is incremented after Black's move. Default `1`.
- 
-**moves** - Is added to server response when `moves()` or `move()` was called.
-It indicates possible moves for playing player (turn).
-```json
-{
-    "A7": ["A6", "A5"],
-    "B7": ["B6", "B5"]
-}
+**halfMove** - Number of halfmoves since the last capture or pawn advance. Used for the [fifty-move rule](https://en.wikipedia.org/wiki/Fifty-move_rule). Default: `0`
+
+**fullMove** - Full move number. Starts at 1 and increments after Black's move. Default: `1`
+
+**pieces** - Pieces on the board using FEN notation:
+
+| Piece  | White | Black |
+| :----: | :---: | :---: |
+| Pawn   |   P   |   p   |
+| Knight |   N   |   n   |
+| Bishop |   B   |   b   |
+| Rook   |   R   |   r   |
+| Queen  |   Q   |   q   |
+| King   |   K   |   k   |
+
+#### FEN Format
+
+You can also use [Forsyth–Edwards Notation (FEN)](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation):
+
+```typescript
+import { move } from 'js-chess-engine'
+
+const fen = 'rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1'
+const newConfig = move(fen, 'H7', 'H5')
+console.log(newConfig)
+// BoardConfig object with updated position
 ```
-Means A7 can move to A6 and A5. B7 can move to B6 and B5.
 
-**pieces** - Pieces on your chessboard. Syntax is same as FEN notation.<BR/>
-| Piece|White|Black|
-| :-: | :-:| :-:|
-| Pawn |P|p|
-| Knight |N|n|
-| Bishop |B|b|
-| Rook |R|r|
-| Queen |Q|q|
-| King |K|k|
+### Computer AI
+
+The engine includes a sophisticated AI based on the Minimax algorithm with alpha-beta pruning, enhanced with advanced performance optimizations. There are five difficulty levels:
+
+| Level | Alias             | Description                          | Search Depth | Avg. Time |
+| :---: | :---------------- | :----------------------------------- | :----------: | :-------: |
+|   1   | Beginner          | Very weak play, minimal lookahead    | 1-2 ply      | <10ms     |
+|   2   | Easy              | Suitable for new chess players       | 2-3 ply      | ~50ms     |
+|   3   | Intermediate      | Balanced difficulty (default)        | 3-4 ply      | ~300ms    |
+|   4   | Advanced          | Strong play with deeper search       | 4-5 ply      | ~2s       |
+|   5   | Expert            | Maximum difficulty and search depth  | 5-6 ply      | ~7s       |
 
+**Note:** Performance varies based on hardware and position complexity. Times shown are approximate averages on modern hardware.
 
-#### FEN
-You can also use the Forsyth–Edwards Notation ([FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation)).
+```typescript
+import { Game } from 'js-chess-engine'
+import type { AILevel } from 'js-chess-engine'
 
-```js
-const jsChessEngine = require('js-chess-engine')
-const { move } = jsChessEngine    
-const newFen = move('rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3 0 1', 'H7', 'H5')
-console.log(newFen)
-// rnbqkbnr/ppppppp1/8/7p/4P3/8/PPPP1PPP/RNBQKBNR w KQkq h6 0 2
+const game = new Game()
+
+// Different difficulty levels
+game.aiMove(1)  // Beginner
+game.aiMove(2)  // Easy
+game.aiMove(3)  // Intermediate (default)
+game.aiMove(4)  // Advanced
+game.aiMove(5)  // Expert
 ```
 
-<BR/>
+**Implementation Highlights:**
+- Alpha-beta pruning with transposition table (auto-scales by AI level for optimal memory usage)
+- Advanced move ordering (PV moves, MVV-LVA captures, killer moves)
+- Iterative deepening for optimal move ordering
+- Position evaluation with material balance and piece-square tables
+- 65% performance improvement over baseline implementation
+- Smart environment detection and level-based memory scaling for optimal performance across platforms
 
-### Computer AI
+#### Auto-Scaling Transposition Table (Smart Memory Management) {#transposition-table}
+
+The engine automatically adjusts cache size based on AI level and environment:
+
+| AI Level | Node.js Cache | Browser Cache | Use Case                     |
+| :------: | :-----------: | :-----------: | :--------------------------- |
+|    1     |     2 MB      |     1 MB      | Lightweight, fast responses  |
+|    2     |     4 MB      |     2 MB      | Mobile-friendly performance  |
+|    3     |    16 MB      |     8 MB      | Balanced (default)           |
+|    4     |    32 MB      |    16 MB      | Strong tactical play         |
+|    5     |    64 MB      |    32 MB      | Maximum strength             |
+
+Lower levels use less memory for faster responses, higher levels use more for better move quality. Browser cache sizes are appropriate for modern devices (2024+). Override with `ttSizeMB` option if needed.
+
+📚 **[Complete AI Implementation Guide →](docs/AI_IMPLEMENTATION.md)**
+
+For comprehensive technical documentation including algorithms, data structures, optimization techniques, and developer guides, see the AI implementation documentation.
+
+## Hints
+
+- **Pawn Promotion:** When a pawn reaches the opposite end of the board, it is automatically promoted to a Queen. If you want the player to choose the promotion piece in your application, use the `setPiece()` method to replace the queen with the desired piece.
 
-This engine includes configurable AI computer logic based on Minimax algorithm. There are five possible levels at this time.
+- **Castling:** Castling moves are included in the moves returned by `moves()`. When a king moves two squares (castling), the rook automatically moves as well.
 
-|Level|Alias|Moves to the future|HW requirements|Approx. time to move (s)*|
-| :-: | :-:| :-:| :-:| :-:|
-| 0 |Well-trained monkey| 1-2 | None | <0.01 |
-| 1 |Beginner| 2-4 | Very low | <0.1 |
-| 2 |Intermediate| 2-4 | Low | 0.7 |
-| 3 |Advanced| 3-5 | Medium | 4.6 |
-| 4 |Experienced| 4-5 | High | 9.5 |
+- **Fifty-Move Rule:** The `halfMove` counter is calculated automatically, but the [fifty-move rule](https://en.wikipedia.org/wiki/Fifty-move_rule) is not enforced by the engine. You can implement this rule in your application if needed.
 
-***Approx. time to move (s)** - This number represent the average amount of seconds needed for one move during a chess game on t3.nano AWS instance.
-T3.nano is a low-cost machine with 0.5 GiB RAM and basic CPU performance. Please note, amount of time needed for calculations heavily depends on in-game situation (number of chess pieces still on a chessboard).
+## TypeScript Support
 
-<BR/>
+Version 2.0 is written entirely in TypeScript and exports all necessary types:
 
-## HINTS
+```typescript
+import { Game } from 'js-chess-engine'
+import type {
+  // Board types
+  BoardConfig,
+  PieceSymbol,
+  Square,
+  Color,
+  MovesMap,
+  CastlingRights,
+  HistoryEntry,
 
-- When a pawn reaches an end of a chessboard, he is automatically converted and calculated as a Queen.
-If you like, player can pick a new chess piece in your app, and you can send an updated chessboard.
-For in-memory approach please check **setPiece** function.
-- Castling can be played by a King. You can receive this special move with `moves` call.
-When a move is recognized as a castling - played with a king across two chess fields, rook moves automatically with a king.
-- Halfmoves are calculated on the server, but the [fifty-move rule](https://en.wikipedia.org/wiki/Fifty-move_rule) is not handled by a server. You can handle this situation in your app if you need to.
+  // AI types
+  AILevel,
 
-<BR/>
+  // Piece types
+  PieceType
+} from 'js-chess-engine'
+```
+
+See `/src/types/board.types.ts` and `/src/types/ai.types.ts` for complete type definitions.
 
 ## Collaboration
 
-**Collaborators are welcome.** Please do not forget to check ESLint and run tests before submitting a new pull request (`npm run test`). 
+**Collaborators are welcome.** Please ensure your code passes TypeScript type checking and all tests before submitting a pull request:
 
-If it is possible, also use commit message prefixes like `feat: ` or `fix: ` - changelog is generated from this.
+```bash
+npm run typecheck  # TypeScript type checking
+npm run test       # Run test suite
+```
 
-<BR/>
+If possible, use commit message prefixes like `feat:` or `fix:` - the changelog is generated from these.
 
 ## TODO
-- Calculation and result caching
-- Forsyth–Edwards Notation (FEN) validation
 
-<BR/>
+- FEN validation
+- Additional endgame tablebase support
 
 ## CHANGELOG
-Changelog can be found [HERE](CHANGELOG.md) .
 
-<BR/>
+Changelog can be found [HERE](CHANGELOG.md).
 
 ## In conclusion - why another chess engine?
+
 I am not a chess pro. My father is.
-When I was ten, I had an Atari (with Turbo Basic), and I was hoping for new PC.
-My father told me, make me a computer program, which beat me in chess, and I buy you a new PC.
-Obviously, it was a trap and I failed. It comes to my mind after twenty years, and I would like to finish what I started before.
+
+When I was ten, I had an Atari (with Turbo Basic), and I was hoping for a new PC. My father told me: "Make me a computer program which beats me in chess, and I'll buy you a new PC."
+
+Obviously, it was a trap and I failed. Twenty years later, it came back to my mind, and I decided to finish what I started. This is version 2.0 - a complete TypeScript rewrite with improved performance and architecture.
+
+## Breaking Changes from v1
+
+Version 2.0 is a complete TypeScript rewrite with significant API changes. While method names remain the same, **several return types have changed**:
+
+### 1. `moves(square)` Return Type Changed
+
+**v1 Behavior:**
+
+```javascript
+const game = new Game()
+game.moves('E2')  // Returns array: ["E3", "E4"]
+```
+
+**v2 Behavior:**
+
+```typescript
+const game = new Game()
+game.moves('E2')  // Returns object: {"E2": ["E3", "E4"]}
+```
+
+### 2. `move()` Return Type Changed
+
+**v1 Behavior:**
+
+```javascript
+game.move('E2', 'E4')  // Returns move object: {"E2": "E4"}
+```
+
+**v2 Behavior:**
+
+```typescript
+game.move('E2', 'E4')  // Returns full BoardConfig object
+```
+
+### 3. `aiMove()` API - Now v1 Compatible ✅
+
+The `aiMove()` function has been **restored to v1 API compatibility**.
+
+**v1 Behavior:**
+
+```javascript
+aiMove(config, 2)  // Returns move object: {"E2": "E4"}
+```
+
+**v2 Behavior (Current):**
+
+```typescript
+aiMove(config, 3)  // Returns move object: {"E2": "E4"} ✅ v1 compatible
+```
+
+**New `ai()` function** - For users who need both move and board state:
+
+```typescript
+ai(config, 3)  // Returns: { move: {"E2": "E4"}, board: {...} }
+```
+
+### 4. AI Difficulty Levels Changed
+
+- **v1:** Levels 0-4 (0=easiest, 4=hardest)
+- **v2:** Levels 1-5 (1=easiest, 5=hardest)
+
+**Migration:**
+- Level 0 → Level 1 (Beginner)
+- Level 1 → Level 2 (Easy)
+- Level 2 → Level 3 (Intermediate, default)
+- Level 3 → Level 4 (Advanced)
+- Level 4 → Level 5 (Expert)
+
+The default level has changed from `2` to `3` to maintain similar difficulty in the middle range.
+
+### 5. Node.js Version Requirement
+
+- **v1:** Node.js >=20 <21
+- **v2:** Node.js >=24
+
+### What Stayed the Same
+
+- ✅ Game class constructor signature
+- ✅ Method names (move, moves, aiMove, etc.)
+- ✅ Board formats (JSON and FEN)
+- ✅ Chess rules (castling, en passant, promotions)
+- ✅ Square notation (case-insensitive: 'E2' or 'e2')