Generate data about Sudoku puzzles and upload it via POST requests
- Installation
- Usage
- hint Object Properties
- PuzzleData Object Properties
- Developer Tools
npm install sudokuru- 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
- solution: optional parameter specifying boards solution so that amend notes hints can correct users mistakes
- Return Value: hint
- 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
"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.
[[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.
[[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.
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[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.
"Amend notes are when you reset a cell's notes to contain every nonconflicting number"Info about the strategy being used by the hint.
"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.
"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).
[[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.
[[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.
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[1,0,8]]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 1st cell in the 2nd row. The rest of the numbers in the subarray are the notes to be removed which is just 8.
"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.
"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.
"NAKED_SINGLE"Name of strategy used by the hint. Naked 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.
[[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.
[]Group type and index of groups that "cause strategy". This does not apply to this strategy.
[[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).
[]Notes that can be removed from cells along with their row and columns. This does not apply to this strategy.
"Naked singles are when you only have one number left as a possibility in a cell"Info about the strategy being used by the hint.
"When you see a naked single you can fill it in with its last remaining possibility"Describes the action that the hint is suggesting.
"NAKED_PAIR"Name of strategy used by the hint. Naked 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.
[[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.
[[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.
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[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).
"Naked 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.
"When you see a naked 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.
"NAKED_TRIPLET""NAKED_QUADRUPLET"Name of strategy used by the hint. Naked triplets through octuplets are scaled up versions of naked pairs except instead of using two cells and notes they share 3-8. Note: while cells in say a naked 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
"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 naked single which in the only 8 note in the box with the green border. Therefore, the other notes highlighted in red can be removed.
[[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.
[[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.
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[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).
"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.
"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
"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 naked 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.
[[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.
[[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.
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[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).
"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.
"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
"HIDDEN_TRIPLET""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.
"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.
[[0,6],[0,8]]Coordinates of cells that "cause" strategy to be applicable.
[[0,0],[2,2]]Group type and index of groups that "cause strategy".
[]Row, column, and values for cells that have had values placed in them as result of strategy. This does not apply to this strategy.
[[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.
"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.
"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.
81 character string representing the solution to the puzzle (left to right top to bottom)
Number representing the difficulty of the puzzle (higher is harder)
Number representing the number of givens i.e. pre-filled cells in the puzzle
Boolean array representing which strategies were used to solve the puzzle in following order (subset of StrategyEnum):
- 0: NAKED_SINGLE,
- 1: HIDDEN_SINGLE,
- 2: NAKED_PAIR,
- 3: HIDDEN_PAIR,
- 4: POINTING_PAIR,
- 5: NAKED_TRIPLET,
- 6: HIDDEN_TRIPLET,
- 7: POINTING_TRIPLET,
- 8: NAKED_QUADRUPLET,
- 9: HIDDEN_QUADRUPLET,
- 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 naked pair is made up of two naked 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.
Clone Repository
git clone https://github.com/SudoKuru/Sudokuru.gitRun one of the below commands to setup pre-commit hooks:
bun install # or npm installnpm run preparePre-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-commitbun......................................................................Passed
Should appear in the git output logs after a commit.
# Install Developer Dependencies
bun installRun Tests
Coverage reports are automatically generated can can be viewed in jest-coverage folder
npm run testRun Tests without coverage (faster)
bun testBuild dist Folder
bun buildCreate Local TypeDoc Documentation
bun update-docsThe 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/
