react-docs-game-lib

A TypeScript library for calculating optimal moves in Tic-Tac-Toe using the Minimax algorithm. This library provides an unbeatable AI that can play perfect Tic-Tac-Toe.

🎯 Features

• ✅ Optimal move calculation using Minimax algorithm
• ✅ TypeScript support with full type definitions
• ✅ Zero dependencies - pure algorithm implementation
• ✅ Comprehensive tests with 100% coverage
• ✅ Fast performance - optimized for quick decisions
• ✅ Easy to use - simple, clean API

📦 Installation

npm install react-docs-game-lib

🚀 Quick Start

import { getOptimalTurn, GameBoard } from 'react-docs-game-lib';

// Define the game board: -1 = empty, 0 = Player O, 1 = Player X
const board: GameBoard = [
  1,
  1,
  -1, // X | X | -
  -1,
  0,
  -1, // - | O | -
  -1,
  -1,
  -1, // - | - | -
];

// Get optimal move for Player O (0)
const optimalMove = getOptimalTurn(board, 0);
console.log(optimalMove); // => 2 (blocks X's winning move)

📖 API Documentation

Types

CellValue

type CellValue = -1 | 0 | 1;

• -1: Empty cell
• 0: Player O
• 1: Player X

GameBoard

type GameBoard = [
  CellValue,
  CellValue,
  CellValue,
  CellValue,
  CellValue,
  CellValue,
  CellValue,
  CellValue,
  CellValue
];

Array of 9 cells representing the board:

0 | 1 | 2
---------
3 | 4 | 5
---------
6 | 7 | 8

Player

type Player = 0 | 1;

• 0: Player O
• 1: Player X

Functions

getOptimalTurn(gameField, player)

Returns the optimal move position for the given player.

Parameters:

• gameField: GameBoard - Current state of the game board
• player: Player - Current player (0 or 1)

Returns: number - Index (0-8) of the optimal move, or -1 if no moves available

Example:

const board: GameBoard = [-1, -1, -1, -1, -1, -1, -1, -1, -1];
const move = getOptimalTurn(board, 0);
console.log(move); // => 0 (corner is optimal on empty board)

Throws:

• Error if board is not exactly 9 elements
• Error if player is not 0 or 1

getOptimalTurnWithScore(gameField, player)

Returns the optimal move with its evaluation score.

Parameters:

• gameField: GameBoard - Current state of the game board
• player: Player - Current player (0 or 1)

Returns: OptimalMoveResult

{
  position: number; // Index of optimal move (0-8), or -1 if none
  score: number; // Evaluation score (positive = winning, negative = losing, 0 = draw)
}

Example:

const board: GameBoard = [0, 0, -1, 1, 1, -1, -1, -1, -1];
const result = getOptimalTurnWithScore(board, 0);
console.log(result); // => { position: 2, score: 9 } (winning move)

checkGameOver(board)

Checks if the game is over and returns the result.

Parameters:

• board: GameBoard - Current state of the game board

Returns:

{
  isOver: boolean; // true if game is finished
  winner: Player | null; // winning player (0 or 1), or null
  isDraw: boolean; // true if game ended in draw
}

Example:

const board: GameBoard = [0, 0, 0, 1, 1, -1, -1, -1, -1];
const result = checkGameOver(board);
console.log(result); // => { isOver: true, winner: 0, isDraw: false }

💡 Usage Examples

Basic AI Opponent

import { getOptimalTurn, checkGameOver, GameBoard } from 'react-docs-game-lib';

function playGame() {
  let board: GameBoard = [-1, -1, -1, -1, -1, -1, -1, -1, -1];
  let currentPlayer = 0;

  while (true) {
    // Get AI move
    const move = getOptimalTurn(board, currentPlayer);

    if (move === -1) break; // No moves available

    // Make the move
    board[move] = currentPlayer;

    // Check if game is over
    const gameState = checkGameOver(board);
    if (gameState.isOver) {
      if (gameState.isDraw) {
        console.log("It's a draw!");
      } else {
        console.log(`Player ${gameState.winner} wins!`);
      }
      break;
    }

    // Switch players
    currentPlayer = currentPlayer === 0 ? 1 : 0;
  }
}

React Integration

import { useState } from 'react';
import { getOptimalTurn, checkGameOver, GameBoard } from 'react-docs-game-lib';

function TicTacToe() {
  const [board, setBoard] = useState<GameBoard>([
    -1, -1, -1, -1, -1, -1, -1, -1, -1,
  ]);

  const handlePlayerMove = (position: number) => {
    if (board[position] !== -1) return;

    // Player move
    const newBoard = [...board] as GameBoard;
    newBoard[position] = 0;
    setBoard(newBoard);

    // Check game over
    const gameState = checkGameOver(newBoard);
    if (gameState.isOver) return;

    // AI move
    const aiMove = getOptimalTurn(newBoard, 1);
    if (aiMove !== -1) {
      newBoard[aiMove] = 1;
      setBoard(newBoard);
    }
  };

  // ... render board
}

🔍 How It Works

This library uses the Minimax algorithm, a decision-making algorithm used in game theory. The algorithm:

1. Explores all possible future game states recursively
2. Evaluates each terminal state (win/loss/draw)
3. Assumes both players play optimally
4. Chooses the move that leads to the best guaranteed outcome

The algorithm ensures the AI never loses - it will always win or draw when playing optimally.

📝 License

MIT © UV