node-sudoku

README.md

SudokuJS: Advanced Sudoku Generator & Solver

SudokuJS is a robust and flexible JavaScript library designed for generating, manipulating, and solving Sudoku puzzles. Whether you're developing a game, a puzzle platform, or just need a powerful Sudoku engine, SudokuJS has got you covered.

🌟 Features

• Dynamic Sudoku Generation: Craft puzzles based on difficulty levels or specific empty cell counts.
• Powerful Solving Algorithm: Turn any Sudoku challenge into a walk in the park.
• Asynchronous Support: Seamlessly integrate with modern applications without blocking the main thread.
• Comprehensive Sudoku Class: Engage with your Sudoku board directly, with methods for solution retrieval, board validation, and debug insights.
• TypeScript Supported: For enhanced development experience with type safety.

🚀 Quick Start

Installation

pnpm install sudokujs

Generating a Puzzle

import sudokuJs from 'sudokujs'

async function demo() {
  const sudoku = await sudokuJs({ level: 3 })
  console.log(sudoku.getBoard('array'))
}

demo()

📚 Documentation

Main API: sudokuJs(options: SudokuJS)

Generate a fresh Sudoku puzzle. Options include:

• level: The desired difficulty (0-4, with 4 being the most challenging).
• emptyHoleCount: Directly set the number of empty cells. (Takes precedence over level if both are provided.)
• strict: Enforce a unique solution for the generated puzzle. Default is true.

Utility Functions

• generate(digHoleCount: number): Synchronously produce a puzzle with a set number of empty cells.
• generateAsync(digHoleCount: number): Async version of the above.
• generateByLevel(level: number): Craft a puzzle of a particular difficulty level.
• solve(board: BoardTypes, args: { strict?, emptyHoleChar, as? }): BoardTypes: Resolve any Sudoku board.

Class: Sudoku

An object-oriented interface to engage with Sudoku boards.

Methods:

• getBoard(as: AsTypes): Retrieve the current board state.
• getAnswer(as: AsTypes): Obtain the board's solution.
• validate(): Check if the current board state is valid.
• debug(): Gain insights into the board's internal state and potential solutions.

📦 Integration

SudokuJS is designed to be compatible with a myriad of JavaScript ecosystems:

• Web Applications: Integrate directly into React, Angular, Vue, or plain JS projects.
• Node.js: Suitable for backend applications, tools, or CLI applications.
• Game Development: Integrate with frameworks like Phaser, Three.js, or Babylon.js for game development.

🤝 Contribution & Community

We embrace open-source and encourage active participation. Whether it's bug fixes, feature enhancements, or documentation improvements, your contributions are welcome!

• Bug Reports: Use GitHub issues for bugs.
• Feature Requests: Open an issue to discuss new features or enhancements.
• Pull Requests: Keep them concise; one feature or bugfix per PR is best.

📄 License

SudokuJS is open-sourced under the MIT License. Feel free to use, modify, and distribute as you see fit, but please provide attribution.

🙏 Acknowledgements

Thanks to the open-source community for their continuous inspiration and support.