nmx.sudokugen.library 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 New Media XP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# Sudoku Gen Library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`sudoku` `javascript` `typescript` `library` `npm`
+
+© 2024-2026 New Media XP. Licensed under the [MIT License](https://github.com/newmediaxp/sudokugen/blob/main/LICENSE).  
+|
+[website](https://www.newmediaxp.com)
+|
+[email](mailto:contact@newmediaxp.com)
+|
+
+---
+
+## Description
+
+A library written in TypeScript to generate and solve sudoku puzzles, from rank 2 (4×4) up to rank 5 (25×25).
+
+* Every created puzzle has exactly one solution.
+* A seed reproduces the same puzzle, and gives the same puzzle as the
+  [C# library](https://www.nuget.org/packages/NMX.SudokuGen.Library) does for that seed.
+* It can also check a board for conflicts and shuffle a puzzle into an equivalent one.
+
+It ships as plain ES modules with type declarations and has no dependencies,
+so it runs in browsers, Node.js, Deno and Bun.
+
+---
+
+## Install
+
+```
+npm install nmx.sudokugen.library
+```
+
+In a browser without a bundler, import it from a CDN:
+
+```js
+import { Sudoku } from "https://cdn.jsdelivr.net/npm/nmx.sudokugen.library@1/+esm";
+```
+
+---
+
+## API
+
+```js
+import { Sudoku, Conflict, getPuzzleCode } from "nmx.sudokugen.library";
+
+const a_sudoku = Sudoku.create(3, 40);                // rank 3 (9×9), up to 40 blanks
+const a_seeded = Sudoku.create(3, 40, { seed: 777 }); // the same seed gives the same puzzle
+const a_solved = Sudoku.solve(a_sudoku.puzzle);       // throws unless the puzzle has exactly one solution
+const a_code   = getPuzzleCode(a_sudoku.puzzle);      // e.g. "390560027.001809405...."
+
+const a_board = [...a_sudoku.puzzle];                 // the board being played
+a_board[0] = 5;
+if (a_sudoku.findConflicts(a_board, 0) & Conflict.Row) console.log("5 is already in the row");
+```
+
+### `Sudoku`
+
+Immutable puzzle/solution pair. Grids are flat, row-by-row arrays of `squares` values, `0` = blank.
+Get one from `Sudoku.create`, `Sudoku.solve` or `shuffle`; the constructor is private.
+
+#### Methods
+
+| Member          | Signature                                                                 | Description |
+|-----------------|---------------------------------------------------------------------------|-------------|
+| `create`        | `static create(rank, blanks, { seed?, exhaustive? } = {}): Sudoku`         | New random puzzle with a unique solution. `blanks = Sudoku.maxBlanks` (-1) requests as many as possible. `seed` (any 32-bit integer) reproduces the puzzle. `exhaustive` skips the search budget for an exact blank count (can run very long at high ranks). |
+| `solve`         | `static solve(puzzle: ArrayLike<number>): Sudoku`                          | Solves a puzzle, rank inferred from its length. Takes arrays and typed arrays. Throws if the input is invalid, conflicting, or has no unique solution. |
+| `shuffle`       | `shuffle(seed?: number): Sudoku`                                           | Returns an equivalent variant (same rank, difficulty and blank count, different look). The original is untouched. The same seed gives the same variant. |
+| `findConflicts` | `findConflicts(board, index, input = board[index], excludeIndex = true): number` | Which of `index`'s units already hold `input`, as `Conflict` flags. Leave out `input` to check the value placed at `index`, or pass one to test a candidate before placing it. `excludeIndex = true` ignores the square's current value; `false` searches it too. A blank `input` (`0`) never conflicts. |
+
+#### Properties
+
+| Member                | Type                | Description                                                              |
+|-----------------------|---------------------|--------------------------------------------------------------------------|
+| `puzzle`              | `readonly number[]` | The puzzle grid, `0` = blank. Frozen: copy it (`[...puzzle]`) to edit.   |
+| `solution`            | `readonly number[]` | The unique completed solution. Frozen.                                   |
+| `removed`             | `number`            | Actual blank count (can be less than `blanks` when more would break uniqueness). |
+| `rank`                | `number`            | Segment size, 2 (4×4) to 5 (25×25).                                      |
+| `rows`                | `number`            | Squares per row, column and segment (`rank²`).                           |
+| `squares`             | `number`            | Total squares (`rows²`).                                                 |
+| `remove`              | `number`            | Requested blank count (the `blanks` argument to `create`, or `squares` for `maxBlanks`). |
+| `minRank` / `maxRank` | `static number`     | Allowed rank bounds, `2` and `5`.                                        |
+| `maxBlanks`           | `static number`     | Sentinel for `create`'s `blanks`: `-1` means "as many as possible".      |
+
+### `Conflict`
+
+Frozen bit flags, returned by `findConflicts`. Test them with `&`.
+
+| Value     | Meaning                                  |
+|-----------|------------------------------------------|
+| `None`    | No conflict (`0`).                       |
+| `Row`     | Value repeats in the row (`1`).          |
+| `Column`  | Value repeats in the column (`2`).       |
+| `Segment` | Value repeats in the segment, or box (`4`). |
+
+A square that is rule-clean but still wrong (`board[i] !== solution[i]`) returns `None`, so compare against `solution` to catch those.
+
+### Puzzle codes
+
+| Function        | Signature                                         | Description                                                                                             |
+|-----------------|---------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `getPuzzleCode` | `getPuzzleCode(grid: ArrayLike<number>): string`  | Encodes a grid as a puzzle code: one char per square (`0` blank, `1`-`9`, `A` = 10…), `.` between rows. |
+| `getPuzzleArr`  | `getPuzzleArr(code: string): number[]`            | Parses a puzzle code back into a grid array; unrecognised characters are ignored.                       |
+
+### Notes
+
+* **Errors** — `create`, `shuffle` and `findConflicts` throw a `RangeError` for an argument outside its range,
+  such as a rank of 6 or a seed that isn't a 32-bit integer. `solve` throws an `Error` for any puzzle it can't solve
+  uniquely, with the reason in the message.
+* **Speed** — every call is synchronous. On a desktop machine a rank 3 create takes about a millisecond,
+  a rank 4 create with `maxBlanks` around a tenth of a second, and a rank 5 create several seconds.
+  In a browser, run rank 4 and 5 creates in a [Web Worker](https://developer.mozilla.org/docs/Web/API/Web_Workers_API)
+  so the page stays responsive:
+
+  ```js
+  // sudoku-worker.js, started with new Worker("sudoku-worker.js", { type: "module" })
+  import { Sudoku } from "nmx.sudokugen.library";
+
+  self.onmessage = (p_event) => {
+      const a_sudoku = Sudoku.create(p_event.data.rank, p_event.data.blanks);
+      self.postMessage({ puzzle: a_sudoku.puzzle, solution: a_sudoku.solution });
+  };
+  ```
+
+* **State** — instances share no state, so any number of them can be created and used independently.
+
+---
+
+## Details
+
+* Dependencies
+
+    * None. Needs an ES2022 runtime: current browsers, Node.js 20 or later, Deno, Bun.
+
+* Other languages
+
+    * C# library: [NMX.SudokuGen.Library](https://www.nuget.org/packages/NMX.SudokuGen.Library)
+
+* Downloads
+
+    * [npm](https://www.npmjs.com/package/nmx.sudokugen.library)
+
+* Source
+
+    * [GitHub](https://github.com/newmediaxp/sudokugen/tree/main/js/nmx.sudokugen.library)
+
+---
+
+## Contact
+
+* Link: <https://www.newmediaxp.com/contact>
+* Email-1: <contact@newmediaxp.com>
+* Email-2: <animaxneil@gmail.com>
+
+---

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { Conflict, Sudoku } from "./sudoku.ts";
+export type { CreateOptions } from "./sudoku.ts";
+export { getPuzzleArr, getPuzzleCode } from "./utility.ts";

package/dist/index.js

@@ -0,0 +1,3 @@
+// Copyright (c) 2024-2026 New Media XP. Licensed under the MIT License.
+export { Conflict, Sudoku } from "./sudoku.js";
+export { getPuzzleArr, getPuzzleCode } from "./utility.js";

package/dist/random.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Knuth's subtractive generator, step for step as .NET's seeded System.Random runs it,
+ * so a seed gives the same puzzle here as in the C# library.
+ * The Int32Array stores wrap like C#'s unchecked int arithmetic, which large seeds rely on.
+ */
+export declare class Random {
+    private readonly seedArray;
+    private iNext;
+    private iNextP;
+    /**
+     * @param p_seed Any 32-bit integer; like .NET, a seed and its negation give the same sequence.
+     */
+    constructor(p_seed: number);
+    /**
+     * An integer within p_min..p_max - 1, as .NET's Random.Next(min, max) returns it.
+     * Only ranges up to 2^31 - 1 wide; .NET draws wider ones differently.
+     */
+    next(p_min: number, p_max: number): number;
+}
+/**
+ * A seed for the unseeded calls; their results only need to differ, not to be unpredictable.
+ */
+export declare function randomSeed(): number;

package/dist/random.js

@@ -0,0 +1,67 @@
+// Copyright (c) 2024-2026 New Media XP. Licensed under the MIT License.
+const mBig = 2147483647, mSeed = 161803398, sampleScale = 1 / mBig;
+/**
+ * Knuth's subtractive generator, step for step as .NET's seeded System.Random runs it,
+ * so a seed gives the same puzzle here as in the C# library.
+ * The Int32Array stores wrap like C#'s unchecked int arithmetic, which large seeds rely on.
+ */
+export class Random {
+    seedArray = new Int32Array(56);
+    iNext = 0;
+    iNextP = 21;
+    /**
+     * @param p_seed Any 32-bit integer; like .NET, a seed and its negation give the same sequence.
+     */
+    constructor(p_seed) {
+        const a_seedArray = this.seedArray;
+        let a_mj = mSeed - (p_seed === -2147483648 ? mBig : Math.abs(p_seed)), a_mk = 1;
+        a_seedArray[55] = a_mj;
+        for (let a_ii = 0, i = 1; i < 55; ++i) {
+            // the range [1..55] is special (Knuth), so position 0 stays unused
+            a_ii += 21;
+            if (a_ii >= 55)
+                a_ii -= 55;
+            a_seedArray[a_ii] = a_mk;
+            a_mk = (a_mj - a_mk) | 0;
+            if (a_mk < 0)
+                a_mk = (a_mk + mBig) | 0;
+            a_mj = a_seedArray[a_ii];
+        }
+        for (let k = 1; k < 5; ++k)
+            for (let i = 1; i < 56; ++i) {
+                let a_n = i + 30;
+                if (a_n >= 55)
+                    a_n -= 55;
+                a_seedArray[i] -= a_seedArray[1 + a_n];
+                if (a_seedArray[i] < 0)
+                    a_seedArray[i] += mBig;
+            }
+    }
+    /**
+     * An integer within p_min..p_max - 1, as .NET's Random.Next(min, max) returns it.
+     * Only ranges up to 2^31 - 1 wide; .NET draws wider ones differently.
+     */
+    next(p_min, p_max) {
+        const a_seedArray = this.seedArray;
+        let a_iNext = this.iNext + 1, a_iNextP = this.iNextP + 1;
+        if (a_iNext >= 56)
+            a_iNext = 1;
+        if (a_iNextP >= 56)
+            a_iNextP = 1;
+        let a_sample = (a_seedArray[a_iNext] - a_seedArray[a_iNextP]) | 0;
+        if (a_sample === mBig)
+            --a_sample;
+        if (a_sample < 0)
+            a_sample += mBig;
+        a_seedArray[a_iNext] = a_sample;
+        this.iNext = a_iNext;
+        this.iNextP = a_iNextP;
+        return Math.trunc(a_sample * sampleScale * (p_max - p_min)) + p_min;
+    }
+}
+/**
+ * A seed for the unseeded calls; their results only need to differ, not to be unpredictable.
+ */
+export function randomSeed() {
+    return (Math.random() * 4294967296) | 0;
+}

package/dist/solver.d.ts

@@ -0,0 +1,194 @@
+import type { Random } from "./random.ts";
+/**
+ * The search engine behind Sudoku.create and Sudoku.solve: a port of the C# Sudoku class's
+ * private state and methods, with the same names (lower camel case) so changes port line by line.
+ * Each instance serves one create or solve call; the Sudoku it yields keeps only the grids.
+ * Grids are flat row-by-row arrays of squares values, 0 = blank; masks hold bit v for value v.
+ */
+export declare class Solver {
+    readonly rank: number;
+    readonly rows: number;
+    readonly squares: number;
+    readonly remove: number;
+    removed: number;
+    readonly puzzle: Int32Array;
+    readonly solution: Int32Array;
+    private readonly squaresInSegmentRow;
+    private readonly trialBudget;
+    private readonly altSolution;
+    private readonly randomRows;
+    private readonly rowMask;
+    private readonly colMask;
+    private readonly segMask;
+    private readonly rowOnceMask;
+    private readonly colOnceMask;
+    private readonly segOnceMask;
+    private readonly rowTwiceMask;
+    private readonly colTwiceMask;
+    private readonly segTwiceMask;
+    private readonly rowThriceMask;
+    private readonly colThriceMask;
+    private readonly segThriceMask;
+    private readonly candMask;
+    private readonly rowBlockMask;
+    private readonly colBlockMask;
+    private readonly rowBlockElim;
+    private readonly colBlockElim;
+    private readonly rowConfMask;
+    private readonly colConfMask;
+    private readonly nakedSquares;
+    private readonly nakedMasks;
+    private readonly fullMask;
+    private readonly rowOf;
+    private readonly colOf;
+    private readonly segOf;
+    private readonly rowBlockOf;
+    private readonly colBlockOf;
+    private readonly unitSquares;
+    private fillNodesLeft;
+    private bestIdx;
+    private bestCount;
+    private bestMask;
+    private eliminated;
+    /**
+     * @param p_rank Segment size, already validated.
+     * @param p_remove Blank squares to aim for, already resolved and validated.
+     * @param p_exhaustive Skips the per-trial node budget (see trialBudgetPerSquare).
+     */
+    constructor(p_rank: number, p_remove: number, p_exhaustive: boolean);
+    /**
+     * Seeds the diagonal segments with random permutations. They never share a row or column,
+     * so they can be filled independently without backtracking.
+     */
+    private set_DiagonalSegments;
+    /**
+     * True when puzzle stays uniquely solvable after blanking p_idx.
+     * The puzzle was unique before the removal, so a second solution would have to place another
+     * conflict-free candidate there; each is trialled for solvability under trialBudget.
+     * An exhausted trial counts as solvable, rejecting the removal — safe, but may undershoot max blanks.
+     * @param p_idx Index of the square just blanked in puzzle.
+     * @param p_removed The solution value the square held before blanking.
+     * @returns True when no alternative value at p_idx completes the puzzle.
+     */
+    private uniqueWithout;
+    /**
+     * Blanks random squares one at a time, keeping only removals that preserve uniqueness (via uniqueWithout),
+     * until remove blanks are reached or no square can be removed.
+     */
+    prune(p_random: Random): void;
+    /**
+     * Rebuilds rowMask, colMask and segMask from p_arr:
+     * bit v of a unit's mask is set when value v is placed in that unit.
+     * @param p_arr The grid the masks should describe.
+     */
+    private loadMasks;
+    /**
+     * Recursive backtracker over the blank squares of p_arr, always working on the most constrained blank first,
+     * forced squares (one candidate left, or a hidden single) are placed without branching,
+     * and a grid is abandoned the moment any blank or needed unit value runs out of options.
+     * Deductions escalate lazily: only when nothing is forced are locked candidates derived
+     * (see derive_BlockEliminations) and the scan repeated on the narrowed candidates,
+     * then naked pairs (see search_NakedPairs) as the last rung before guessing,
+     * so easy grids never pay for the expensive deductions. All deductions keep every completion.
+     * When guessing is unavoidable, a two-homes value (see fillValuePair) is preferred
+     * over a square with 3+ candidates.
+     * p_mode decides the candidate order per square.
+     * The masks must describe p_arr on entry and are stale after a completed fill — enter via fillRemaining.
+     * @param p_arr The grid to fill, solution or altSolution.
+     * @param p_mode Candidate order per square.
+     * @returns True when the grid was completed, or the node budget ran out (leaving p_arr
+     * partially filled — see fillRemaining); a failed fill leaves it and the masks unchanged.
+     */
+    private fillConstrained;
+    /**
+     * One deduction pass over the blanks of p_arr: refreshes candMask,
+     * rebuilds the once/twice/thrice unit masks and picks the most constrained square.
+     * Stops early on a naked single, leaving the unit masks incomplete — the callers' count guards cover that.
+     * Sets bestIdx (the most constrained blank square; -1 when the grid is full), bestCount
+     * (that square's candidate count) and bestMask (that square's candidate mask).
+     * @param p_arr The grid being filled.
+     * @param p_refine False derives candidates from the unit masks; true narrows the stored ones
+     * by rowBlockElim/colBlockElim (see derive_BlockEliminations).
+     * @returns False when some blank has no candidate left.
+     */
+    private scan_Candidates;
+    /**
+     * Unit-level deductions over the masks of a completed scan_Candidates pass: fails the
+     * fill when a unit can no longer host a value it still needs, and redirects the fill to a hidden
+     * single (a value with one possible square left in a unit) when one exists, updating
+     * bestIdx, bestCount (to 1) and bestMask (to the value's bit).
+     * @param p_arr The grid being filled.
+     * @returns False when a needed value has no square left in some unit.
+     */
+    private search_UnitForced;
+    /**
+     * Locked candidates: summarises candMask per block (line∩segment intersection) and
+     * collects into rowBlockElim/colBlockElim the values each block cannot host:
+     * a value confined to one block of a segment stays out of the block's line elsewhere (pointing),
+     * one confined to one block of a line stays out of the block's segment elsewhere (claiming).
+     * @param p_arr The grid being filled; candMask must describe its blanks.
+     */
+    private derive_BlockEliminations;
+    /**
+     * Naked pairs: two blanks of a unit sharing the same two candidates lock those values between them,
+     * so both can be removed from every other square of the unit. Eliminations are applied directly to
+     * candMask; the caller rescans when any were made (eliminated is set true).
+     * @param p_arr The grid being filled; candMask must describe its blanks.
+     * @returns False when an elimination leaves a square without candidates
+     * (e.g. a third square of the unit held the same bare pair).
+     */
+    private search_NakedPairs;
+    /**
+     * Locates the one blank square of a unit that can still take the value of p_valueBit.
+     * Only called after the unit scan in fillConstrained proved exactly one such square exists.
+     * @param p_arr The grid being filled.
+     * @param p_unitOf Square→unit lookup of the unit's type: rowOf, colOf or segOf.
+     * @param p_unit Index of the unit within its type.
+     * @param p_valueBit Bit of the hidden single's value.
+     * @returns Index of the found square.
+     */
+    private search_HiddenSingle;
+    /**
+     * Binary branch of fillConstrained: places the value of p_valueBit in each of its two possible
+     * squares of a unit in turn and recurses — every completion must use one of them.
+     * In Uniqueness mode the square matching solution is tried last, preserving the steer-away order.
+     * @param p_arr The grid being filled.
+     * @param p_mode Candidate order per square, passed through to the recursion.
+     * @param p_unitOf Square→unit lookup of the unit's type: rowOf, colOf or segOf.
+     * @param p_unit Index of the unit within its type.
+     * @param p_valueBit Bit of the value with exactly two possible squares in the unit.
+     * @returns True when the grid was completed; see fillConstrained for the budget caveat.
+     */
+    private fillValuePair;
+    /**
+     * Syncs the masks to p_arr via loadMasks, then runs fillConstrained over the whole grid.
+     * @param p_arr The grid to fill, solution or altSolution.
+     * @param p_mode Candidate order per square.
+     * @param p_nodeBudget Search nodes the fill may spend; exhaustive when omitted. An exhausted fill
+     * returns true but leaves p_arr partially filled — only safe on scratch grids (see uniqueWithout).
+     * @returns True when the grid was completed (or the budget ran out); a failed fill leaves p_arr unchanged.
+     */
+    private fillRemaining;
+    /**
+     * Generates a complete random solution grid: seeds the diagonal segments,
+     * then backtrack-fills the rest in randomised order.
+     * @throws {Error} The grid could not be completed. Impossible for an empty grid,
+     * so this signals a bug in the fill logic itself.
+     */
+    fillAll(p_random: Random): void;
+    /**
+     * Completes solution from the already-validated puzzle inputs by deterministic backtracking.
+     * @returns False when the puzzle has no solution, e.g. inputs that are conflict-free but still unsatisfiable.
+     */
+    fillRest(): boolean;
+    /**
+     * True when every non-blank square of p_arr is within 1..rows and conflict-free.
+     * Repurposes the unit masks as scratch; every fill resyncs them anyway (see fillRemaining).
+     */
+    valid(p_arr: Int32Array): boolean;
+    /**
+     * True when solution is the only completion of puzzle: the Uniqueness fill steers away from the known solution,
+     * so ending up identical proves uniqueness.
+     */
+    unique(): boolean;
+}