sudokubox

SudokuBox is an open source project that solves and generates 9x9 sudoku puzzle.

Table of content

• Getting started
  • Install
  • Require
  • Solve
  • Config
    • logger
    • verbose
    • logPerformance
  • Is valid input
  • Is valid board
  • Generate
• Sudoku board
• Input
• Output
• Older version
• License

Getting started

Install

To install this run the following command in the terminal.

npm i sudokubox

Require

Require sudokubox.

// ESM
import SudokuBox from 'sudokubox';

// CommonJs
const { SudokuBox } = require('sudokubox');

Solve

Create object and pass input.

const sudokuBox = new SudokuBox();

const input = [ /* this has 81 elements */ ];

const result = sudokuBox.solve({ input });

The result will have value like the following:

{ 
  "isPuzzleSolved": true,
  "isBoardValid": true,
  "output": [ /* this is a one dimensional array having 81 elements */ ], 
  "board": [ /* this is a two dimensional 9x9 array */ ]
}

If isPuzzleSolved is false then the puzzle was not solved.

If isBoardValid is false then the board is not valid and can't be solved.

Error

For error case the response will be like the following:

{
  "isPuzzleSolved": false,
  "error": {
    "message": "Some error message"
  }
}

Config

To pass config to SudokuBox pass the config option.

const config = { someConfigField: 'someConfigValue' };
const sudokuBox = new SudokuBox(config);

logger

Config custom logger like Pino.

import pino from 'pino';
const pinoLogger = pino({ level: 'debug' });
const config = { logger: pinoLogger };
const sudokuBox = new SudokuBox(config);

Default: No logger is used.

verbose

To print the logs pass the following config.

const config = { verbose: true };
const sudokuBox = new SudokuBox(config);

Default: verbose: false

Note! Must also set logger.

logPerformance

To print the performance pass the following config.

const config = { logPerformance: true };
const sudokuBox = new SudokuBox(config);

When logPerformance is true then result will look like the following.

{ 
  "isPuzzleSolved": true,
  "isBoardValid": true,
  "output": [ /* this is a one dimensional array having 81 elements */ ], 
  "board": [ /* this is a two dimensional 9x9 array */ ],
  "performance": {
    "duration": {
      "nano": 24453670,
      "micro": 24453.67,
      "milli": 24.45367,
      "second": 0.02445367
    }
  }
}

Default: logPerformance: false

Is valid input

This is to check the validity of the one dimensional input array (having 81 elements).

const sudokuBox = new SudokuBox();

const input = [ /* this has 81 elements */ ];

const result = sudokuBox.isValidInput({ input });

It will return true if input is valid.

{
  "isValidInput": boolean
}

Error

For error case the response will be like the following:

{
  "isValidInput": false,
  "error": {
    "message": "Some error message"
  }
}

Note!

• Input array can have empty cells (denoted by 0).

Valid means if a number N appears in a given cell C(r,c) then that number does not reappear in the

• row (r)
• column (c)
• sub board SB(r,c)

Is valid board

This is same as isValidInput but it checks the validity of the two dimensional array (9x9) representing the board.

const sudokuBox = new SudokuBox();

const board = [
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
  [/* 9 elements */],
];

const result = sudokuBox.isValidBoard({ board });

It will return true if board is valid.

{
  "isValidBoard": boolean
}

Error

For error case the response will be like the following:

{
  "isValidBoard": false,
  "error": {
    "message": "Some error message"
  }
}

Generate

Call generate with level to get a new puzzle.

const sudokuBox = new SudokuBox();

const puzzleConfig = { /* some config */ };

const { puzzle, board, totalCellsFilled, performance } = sudokuBox.generate(puzzleConfig);

Note!

• puzzle is a one dimensional array of size 81.
• board is a two-dimensional array having 9 rows and 9 columns.
• totalCellsFilled denotes the total number of cells filled in the puzzle.
• performance denotes the time taken. Check logPerformance.

Also, puzzleConfig is optional. If it is not set then default level=EASY.

Puzzle Config

Following are the configurations to generate puzzles.

{
  level: 'string'
}

For level set the following values.

EASY
MEDIUM
HARD
EXTREME
DIABOLICAL

Error

In case of error we will get the following response.

{
  "error": {
    "message": "Some error message"
  }
}

Sudoku board

The board size is 9x9.

Input

The input is a one dimensional array having 81 elements.

Use number 0 to denote empty cell.

Use number 1 to 9 to denote filled cell.

Following is a sample sudoku board.

Note! The array is formatted into lines for readability.

[
  1, 3, 0, 2, 0, 0, 7, 4, 0,
  0, 2, 5, 0, 1, 0, 0, 0, 0,
  4, 8, 0, 0, 6, 0, 0, 5, 0,
  0, 0, 0, 7, 8, 0, 2, 1, 0,
  5, 0, 0, 0, 9, 0, 3, 7, 0,
  9, 0, 0, 0, 3, 0, 0, 0, 5,
  0, 4, 0, 0, 0, 6, 8, 9, 0,
  0, 5, 3, 0, 0, 1, 4, 0, 0,
  6, 0, 0, 0, 0, 0, 0, 0, 0
]

Output

The output will be a one dimensional array having 81 elements.

For the above input array we will get the following output array.

Note! The array is formatted into lines for readability.

[
  1, 3, 6, 2, 5, 9, 7, 4, 8,
  7, 2, 5, 4, 1, 8, 9, 3, 6,
  4, 8, 9, 3, 6, 7, 1, 5, 2,
  3, 6, 4, 7, 8, 5, 2, 1, 9,
  5, 1, 8, 6, 9, 2, 3, 7, 4,
  9, 7, 2, 1, 3, 4, 6, 8, 5,
  2, 4, 1, 5, 7, 6, 8, 9, 3,
  8, 5, 3, 9, 2, 1, 4, 6, 7,
  6, 9, 7, 8, 4, 3, 5, 2, 1
]

Older version

CommonJS version - check v0.32.0

License

It's free :smiley:

MIT License Copyright (c) 2021 Yusuf Shakeel

Donate

Feeling generous :smiley: Donate via PayPal