sudokuru

v3.3.0

Published

16 days ago

This is the Sudokuru package.

Downloads

415

0High
0Medium
0Low

sudokuru

Sudokuru Logo

Sudoku Puzzle Generator

NPM License

Generate data about Sudoku puzzles

[!NOTE]
This project uses BreakVer for project versioning.

Installation

npm install sudokuru

Usage

JavaScript

Hint File

getHint()

Setup:
```
import {getHint} from 'sudokuru';
```
Description: Returns a hint based on the puzzle and notes provided

Syntax

getHint(board, notes, strategies, solution);

Parameters:
- board: 2d board array (9 arrays, one for each row, each with 9 strings representing values or "0" if empty)
- notes: 2d notes array (81 arrays, one for each cell containing each note that is left in it)
- strategies: optional parameter specifying which strategies are allowed to be used in the hint given in order of precedence (allowed values are the strings in the StrategyEnum in Sudoku.ts)
- solution: optional parameter specifying boards solution so that amend notes hints can correct users mistakes
Return Value: hint

PuzzleData File

Setup:
```
import {getPuzzleData} from 'sudokuru';
```
Description: Returns data about a given puzzle
Syntax
```
getPuzzleData(board);
```
Parameters:
- board: puzzle board string (81 characters, one for each cell containing each value or "0" if empty, left to right top to bottom)
Return Value: puzzleData

hint Object Properties

Example 1: Amend Notes

Example 1

strategy

"AMEND_NOTES"

Name of strategy used by the hint. Amend notes works removing all notes from a cell then adding back in just the ones that don't conflict with placed values in the same row, column, and box as the cell. In the picture the cell with the red border was previously empty and amend notes was able to add in the 2 and 8 only as the others conflicted with the highlighted cells.

cause

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

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [7, 4] referring to the cell with the 9 highlighted in blue in the next to last row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 8th row and cause[0][1] refers to it being in the 5th column. Similarly the last cell cause[6] is the highlighted 3 that it shares a box with.

groups

[[0,7],[1,2],[2,6]]

Group type and index of groups that "cause strategy". This is a 2d array so group[0] is [0, 7] referring to the next to next to last row with green borders. group[0][0] refers to the group type (0 = row, 1 = column, 2 = box) and group[0][1] refers to it being the 8th row. Similarly the last group group[2] is the bottom left box whose cells also have green borders.

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

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

Notes that can be removed from cells along with their row and columns. The first two values represent the row and column respectively so removals[0][0] and removals[0][1] refer to the 3rd cell in the 8th row. The rest of the numbers in the subarray are the notes to be removed which is every number but 2 and 8. Amend notes is unique in that every note that shouldn't be removed should be added back in (2 and 8 in this example). In this example the cell had no notes in it before amend notes.

info

"Amend notes are when you reset a cell's notes to contain every nonconflicting number"

Info about the strategy being used by the hint.

action

"When you see an amend notes you can remove all notes then add all nonconflicting numbers to its notes"

Describes the action that the hint is suggesting.

Example 2: Simplify Notes

Example 2

strategy

"SIMPLIFY_NOTES"

Name of strategy used by the hint. Simplify notes works by using a cell with a placed value (the blue highlighted 8) to remove a note of the same value from a cell sharing a group (the red 8 note in a cell in the same column).

cause

[[7,0]]

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [7, 0] referring to the cell with the 8 highlighted in blue in the next to last row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 8th row and cause[0][1] refers to it being in the 1st column.

groups

[[1,0]]

Group type and index of groups that "cause strategy". This is a 2d array so group[0] is [1, 0] referring to the first column with green borders. group[0][0] refers to the group type (0 = row, 1 = column, 2 = box) and group[0][1] refers to it being the 1st column.

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

[[1,0,8]]

info

"You can simplify notes using values already placed in cells at the start of the game"

Info about the strategy being used by the hint.

action

"When there is a value already placed in a cell than it can be removed from all other cells notes in its row, column, and box"

Describes the action that the hint is suggesting.

Example 3: Obvious Single

Example 3

strategy

"OBVIOUS_SINGLE"

Name of strategy used by the hint. Obvious single works by placing a value in a cell where it is the only remaining possibility. In the example the green highlighted 2 is the last remaining possibility in the blue highlighted cell.

cause

[[7,2]]

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [7, 2] referring to the 3rd cell in the next to last row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 8th row and cause[0][1] refers to it being in the 3rd column.

groups

[]

Group type and index of groups that "cause strategy". This does not apply to this strategy.

placements

[[7,2,2]]

Row, column, and values for cells that have had values placed in them as result of strategy. This is a 2d array so placements[0] refers to the first value that needs to be placed. The first value in the subarray refers to the cells row, the next value is the column, and the final value is the value to be placed ("2" in this case).

removals

[]

Notes that can be removed from cells along with their row and columns. This does not apply to this strategy.

info

"Obvious singles are when you only have one number left as a possibility in a cell"

Info about the strategy being used by the hint.

action

"When you see a obvious single you can fill it in with its last remaining possibility"

Describes the action that the hint is suggesting.

Example 4: Obvious Pair

Example 4

strategy

"OBVIOUS_PAIR"

Name of strategy used by the hint. Obvious pair works using two cells that share a group and only have the same two notes left as possibilities to eliminate those notes from other cells in the group. In the example 7 and 8 are the last remaining possibilities in the blue highlighted cells which are used to remove all the other 7 and 8s in the column shown highlighted in red.

cause

[[1,8],[6,8]]

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [1, 8] referring to the 9th cell in the second row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 2nd row and cause[0][1] refers to it being in the 9th column.

groups

[[1,8]]

Group type and index of groups that "cause strategy". This is a 2d array so group[0] is [1, 8] referring to the last column with green borders. group[0][0] refers to the group type (0 = row, 1 = column, 2 = box) and group[0][1] refers to it being the 9th column.

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

[[3,8,7,8],[4,8,7,8]]

Notes that can be removed from cells along with their row and columns. The first two values in each subarray represent the row and column respectively so removals[0][0] and removals[0][1] refer to the 9th cell in the 4th row. The rest of the numbers in the subarray are the notes to be removed which is 7 and 8 (although only 8 is there to begin with and is highlighted in red).

info

"Obvious pairs are when you only have the same two numbers left as a possibility in two cells in the same row, column, or box"

Info about the strategy being used by the hint.

action

"When you see a obvious pair you can remove them from the notes of every other cell in the row, column, or box that they share"

Describes the action that the hint is suggesting.

Example 5: Other Obvious Sets

strategy

"OBVIOUS_TRIPLET"

strategy

"OBVIOUS_QUADRUPLET"

Name of strategy used by the hint. Obvious triplets through octuplets are scaled up versions of obvious pairs except instead of using two cells and notes they share 3-8. Note: while cells in say a obvious quadruplet must share the same 4 notes the 4 cells don't have to individually have all 4 notes they just can't have any other notes.

Example 6: Hidden Single

Example 6

strategy

"HIDDEN_SINGLE"

Name of strategy used by the hint. Hidden single works by having only one cell in a group that still has a number as a possibility in which case all other notes can be removed from it. This is shown by the 8 obvious single which in the only 8 note in the box with the green border. Therefore, the other notes highlighted in red can be removed.

cause

[[3,8],[4,8],[5,6],[5,8]]

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [3, 8] referring to the 9th cell in the 4th row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 4th row and cause[0][1] refers to it being in the 9th column.

groups

[[2,5]]

Group type and index of groups that "cause strategy". This is a 2d array so group[0] is [2, 5] referring to the 6th box with green borders (boxes are zero-indexed starting with the top left and going left to right top to bottom). group[0][0] refers to the group type (0 = row, 1 = column, 2 = box) and group[0][1] refers to it being the 6th box.

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

[[3,6,1,2,3,9]]

Notes that can be removed from cells along with their row and columns. The first two values in each subarray represent the row and column respectively so removals[0][0] and removals[0][1] refer to the 7th cell in the 4th row. The rest of the numbers in the subarray are the notes to be removed which is 1, 2, 3, and 9 (although only 1 and 3 are present and are highlighted in red).

info

"Hidden singles are when you only have one cell left still containing a specific value in a row, column, or box"

Info about the strategy being used by the hint.

action

"When you see a hidden single you can remove all notes other than the single from the cell"

Describes the action that the hint is suggesting.

Example 7: Hidden Pair

Example 7

strategy

"HIDDEN_PAIR"

Name of strategy used by the hint. Hidden pair works by having only two cells in a group that still have two specific numbers as possibilities in which case all other notes can be removed from the pair of cells. This is shown by the obvious pair in the top right in which they have the only 2 and 3's in the box with the green border. Therefore, the other notes highlighted in red can be removed.

cause

[[0,7],[1,7],[1,8]]

Coordinates of cells that "cause" strategy to be applicable. This is a 2d array so cause[0] is [0, 7] referring to the 8th cell in the 1st row (rows and columns are zero-indexed). cause[0][0] refers to it being in the 1st row and cause[0][1] refers to it being in the 8th column.

groups

[[2,2]]

Group type and index of groups that "cause strategy". This is a 2d array so group[0] is [2, 2] referring to the 3rd box with green borders (boxes are zero-indexed starting with the top left and going left to right top to bottom). group[0][0] refers to the group type (0 = row, 1 = column, 2 = box) and group[0][1] refers to it being the 3rd box.

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

[[0,6,1,7,8],[2,6,1,7,8]]

Notes that can be removed from cells along with their row and columns. The first two values in each subarray represent the row and column respectively so removals[0][0] and removals[0][1] refer to the 7th cell in the 1st row. The rest of the numbers in the subarray are the notes to be removed which is 1, 7, and 8 (although only 1 and 8 are present and are highlighted in red in the cell in the first row).

info

"Hidden pairs are when you only have two cells left still containing two specific values in a shared row, column, or box"

Info about the strategy being used by the hint.

action

"When you see a hidden pair you can remove all notes other than the pair from the cells"

Describes the action that the hint is suggesting.

Example 8: Other Hidden Sets

strategy

"HIDDEN_TRIPLET"

strategy

"HIDDEN_QUADRUPLET"

Name of strategy used by the hint. Hidden triplets through octuplets are scaled up versions of hidden pairs except instead of using two cells and notes they share 3-8. Note: while cells in say a hidden quadruplet must share the same 4 notes the 4 cells don't have to individually have all 4 notes they just have to be the only cells in the group that have those notes.

Example 9: Pointing Pair

Example 8

strategy

"POINTING_PAIR"

Name of strategy used by the hint. Pointing pair works by having only two cells in a box that still have a specific numbers as a possibility and also share a row or column in which case all other notes can be removed from any other cells in the shared row or column except for the pointing pair themself. This is shown by the pointing pair in the top right in which they have the only 6's in the box are in the two cells highlighted in blue on the same row. Therefore, the other notes highlighted in red can be removed.

cause

[[0,6],[0,8]]

Coordinates of cells that "cause" strategy to be applicable.

groups

[[0,0],[2,2]]

Group type and index of groups that "cause strategy".

placements

[]

Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.

removals

[[0,1,6],[0,2,6]]

Notes that can be removed from cells along with their row and columns. The first two values in each subarray represent the row and column respectively.

info

"Pointing pairs are when you only have two cells in a row or column left still containing a specific value and the cells also share a box"

Info about the strategy being used by the hint.

action

"When you see a pointing pair you can remove all other instances of the shared note from the box (except for those in the pair themself)"

Describes the action that the hint is suggesting.

PuzzleData Object Properties

solution

81 character string representing the solution to the puzzle (left to right top to bottom)

difficulty

Number representing the difficulty of the puzzle (higher is harder)

givensCount

Number representing the number of givens i.e. pre-filled cells in the puzzle

puzzleStrategies

Boolean array representing which strategies were used to solve the puzzle in following order (subset of StrategyEnum):

0: OBVIOUS_SINGLE,
1: HIDDEN_SINGLE,
2: OBVIOUS_PAIR,
3: HIDDEN_PAIR,
4: POINTING_PAIR,
5: OBVIOUS_TRIPLET,
6: HIDDEN_TRIPLET,
7: POINTING_TRIPLET,
8: OBVIOUS_QUADRUPLET,
9: HIDDEN_QUADRUPLET,

drills

1D number array representing last time strategy can be reasonably used as drill or -1 if it can't be used as a drill
Each index is defined as the puzzle when it has a certain number of cells filled in (so index 30 has 30 cells filled in including givens).
Reasonably is defined as to mean removing strategies if they overlap with their prereqs (i.e. if a obvious pair is made up of two obvious singles the pair will be excluded) and not counting a strategy if multiple instances of it are present so their is only one correct answer.
The same number index to strategy mapping as puzzleStrategies is used.

Developer Tools

Clone Repository

git clone https://github.com/SudoKuru/Sudokuru.git

bun install # or npm install

Install pre-commit hooks

Run the below command to setup pre-commit hooks:

pre-commit install

Pre-commit hooks can be run manually with below command, but will always run before git commit and git push if setup correctly.

npm run pre-commit

bun......................................................................Passed

Should appear in the git output logs after a commit.

# Install Developer Dependencies
bun install

Run Tests

Coverage reports are automatically generated can can be viewed in jest-coverage folder

npm run test

Run Tests without coverage (faster)

bun test

Build dist Folder

bun build

Create Local TypeDoc Documentation

bun update-docs

The following can also be done after installing the npm package by navigating to node_modules/sudokuru

Run Demo Server on http://localhost:3100/

bun start

# Can open interactive Solver Demo in browser while Demo Server is running (Generator/Demo/demo.html)

# Demo Server provides the following fakes for Puzzle Class (use http://localhost:3100/ as url)
# Puzzles.startGame(): Will overwrite text file with activeGame constant and return it to user
# Puzzles.getGame(): Will return the activeGame from text file or return 404 error if the text file doesn't exist
# Puzzles.saveGame(): Attempts to save changes to activeGame stored locally in a text file and returns true if successful
# Puzzles.finishGame(): Attempts to delete activeGame stored locally in a text file and returns true if successful
# Drills.getGame(): Will return a puzzle string constant

# Can modify a lessons by doing the following:
1. Log into AWS Console using team IAM user
2. Navigate to S3
3. Navigate to sudokuru bucket
4. Navigate to Lessons folder
5. Download the lessons json file e.g. AMEND_NOTES.json
6. Make changes locally to the json file
7. Upload the json file (it will overwrite the old version)

# Can add a lesson by doing the following:
1. Navigate to S3 sudokuru bucket Lessons folder same as in modifying lesson instructions above
2. Upload the new lesson json file using the same format as the existing ones
3. Download strategies.json
4. Add the new strategies name (same as uploaded file name) to strategies.json locally
5. Upload the json file (it will overwrite the old version)

Official TypeDoc Documentation is Hosted Here: https://sudokuru.github.io/SudokuPuzzleGenerator/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Sudoku Puzzle Generator

Table of Contents

Installation

Usage

JavaScript

Hint File

getHint()

PuzzleData File

hint Object Properties

Example 1: Amend Notes

strategy

cause

groups

placements

removals

info

action

Example 2: Simplify Notes

strategy

cause

groups

placements

removals

info

action

Example 3: Obvious Single

strategy

cause

groups

placements

removals

info

action

Example 4: Obvious Pair

strategy

cause

groups

placements

removals

info

action

Example 5: Other Obvious Sets

strategy

strategy

Example 6: Hidden Single

strategy

cause

groups

placements

removals

info

action

Example 7: Hidden Pair

strategy

cause

groups

placements

removals

info

action

Example 8: Other Hidden Sets

strategy

strategy

Example 9: Pointing Pair

strategy

cause

groups

placements

removals

info

action

PuzzleData Object Properties

solution

difficulty