Tic-Tac-Toe Minimax Library

This library implements game logic and an AI (Minimax algorithm) for the classic Tic-Tac-Toe game (3×3).

📦 Library Purpose

The library allows you to:

• store and update the game board state;
• check for a win and game over conditions;
• get a list of available moves;
• find the optimal AI move for player X or O.

Suitable for:

• educational projects;
• browser and console games;
• demonstrating the Minimax algorithm.

🧩 Installation (npm package)

After publishing the package:

npm install tic-tac-toe-minimax-lib

Or locally (for development):

npm install ../tic-tac-toe-minimax-lib

🚀 Quick Start

import {
  findBestMove,
  getNewState,
  checkWin,
  type Board,
  type Player,
} from "tic-tac-toe-ai";

const board: Board = ["X", "O", "X", "O", "X", "O", null, null, null];

const aiPlayer: Player = "X";

const move = findBestMove(board, aiPlayer);
const newBoard = getNewState(board, move, aiPlayer);

if (checkWin(newBoard, aiPlayer)) {
  console.log("AI wins!");
}

🧱 Data Types

Player

export type Player = "X" | "O";

Cell

export type Cell = Player | null;

null represents an empty cell.

Board

export type Board = Cell[];

An array of 9 elements representing a 3×3 board.

Indexes:

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

🔧 Library API

checkWin(board, player)

Checks whether the specified player has won.

checkWin(board: Board, player: Player): boolean

Returns:

• true — the player has won
• false — no win

getAvailableMoves(board)

Returns a list of available (empty) cells.

getAvailableMoves(board: Board): number[]

Example result:

[6, 7, 8];

isGameOver(board)

Checks whether the game is over.

isGameOver(board: Board): boolean

The game is considered finished if:

• one of the players has won;
• there are no available moves (draw).

getNewState(board, moveIndex, player)

Creates a new board state after a move.

getNewState(
  board: Board,
  moveIndex: number,
  player: Player
): Board

❗ The original board is not mutated.

findBestMove(board, aiPlayer)

Finds the optimal move for the AI using the Minimax algorithm.

findBestMove(board: Board, aiPlayer: Player): number

Features:

• guarantees the optimal move;
• takes depth into account (faster wins are better);
• if the board is empty, selects the center cell (4).

Error:

• throws an Error if no moves are available.

🧠 Minimax Algorithm (Briefly)

• X — maximizing player (AI);
• O — minimizing player;
• AI win: +10 − depth;
• AI loss: depth − 10;
• draw: 0.

The algorithm recursively evaluates all possible moves until the end of the game.

🗂 Project Structure

src/
├── gameLogic.ts   // Win and game state checks
├── minimax.ts     // Minimax implementation
├── types.ts       // Shared types
├── index.ts       // Public API
└── main.ts        // Usage example

📦 Building the npm Package

1. package.json

{
  "name": "tic-tac-toe-ai",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "scripts": {
    "build": "tsc"
  }
}

2. tsconfig.json

{
  "compilerOptions": {
    "outDir": "dist",
    "declaration": true,
    "module": "nodenext",
    "target": "es2022",
    "moduleResolution": "Node"
  },
  "include": ["src"]
}

3. Build

npm run build

4. Publish

npm login
npm publish

✅ Summary

The library provides:

• a clean and fully typed API;
• an optimal AI for Tic-Tac-Toe;
• readiness for use as an npm package.

It can be easily integrated into any TypeScript or JavaScript project.