Professional Sudoku Engine

A production-grade, highly optimized Sudoku generator and solver for JavaScript and TypeScript.

Features

• Algorithmic Integrity:
  • Guaranteed unique solutions.
  • Rotational symmetry for professional-looking puzzles.
  • Difficulty scaling.
• Robust API:
  • Immutability guaranteed.
  • Zod-powered input validation.
  • Deterministic generation via Seed Support.
• Performance: Optimized backtracking solver.

Installation

npm install sudoku-engine

Usage

Basic Generation

import { SudokuEngine } from 'sudoku-engine';

// Generate a medium puzzle (default)
const { puzzle, solution } = SudokuEngine.generate('MEDIUM');
// puzzle: number[81] (0 = empty)
// solution: number[81] (filled)

Seeded Generation (Daily Challenge)

const result = SudokuEngine.generate({ 
  difficulty: 'HARD', 
  seed: '2025-12-25' 
});
// result.puzzle will be identical everywhere for this seed!

Solving

const { success, board } = SudokuEngine.solve(userBoard);
if (success) {
  console.log("Solved!", board);
}

API Reference

generate(options)

| Option | Type | Default | Description | |Obs | --- | --- | --- | | difficulty | number \| 'EASY' ... | 0.5 | 0.0 to 1.0 or named level | | seed | string | random | Seed for deterministic generation |

solve(board)

Returns { success: boolean, board: number[] }. Does not mutate the input.

isValid(board, index, value)

Checks if placing a value at the specific index is valid according to Sudoku rules. Returns boolean.

getHint(board)

Returns the best logical hint for the current board state. Returns Hint | null.

interface Hint {
  type: HintType; // 'NAKED_SINGLE', 'HIDDEN_SINGLE', etc.
  description: string;
  cells: number[]; // Indices involved
  values: number[]; // Values involved
}

grade(board)

Grades the difficulty of a board based on the techniques required to solve it. Returns { difficulty: string, score: number }.

getSolvePath(board)

Returns the step-by-step logical path to solve the puzzle. Returns { solved: boolean, steps: SolveStep[] }.

generateTechniquePuzzle(strategy, difficulty)

Generates a puzzle that requires a specific strategy (e.g., 'HIDDEN_PAIR') to solve. Useful for training or specific difficulty generation. Returns number[] | null.

License

ISC