Guides
Migration (2.1 → 3.0)
Upgrade checklist for new variants, meta constraints, and API changes.
Migration guide
Upgrading to 3.0.0 (from 2.1.x)
3.0.0 is a major jump from 2.1.0: new variants (Killer, Thermo, Kropki, Samurai), architecture cleanup, and a few breaking renames. Classic 9×9 top-level helpers still work.
Breaking changes
| Removed / renamed | Replacement |
|---|---|
getClassicEngine() (public) | createEngine({ variant: "classic" }) |
validateRow / validateColumn / validateBox | validateBoard(board) or engine.validateBoard(board) |
SudokuEngine (batch class) | BatchEngine |
SudokuEngineOptions | BatchEngineOptions |
Also: SudokuVariant.id is typed as string so custom defineVariant definitions are first-class (preset ids remain the same string literals).
SudokuEngineError is unchanged (shared error type for batch, bounds, and registry).
Codemod-style replacements
// Before (2.1)
import { getClassicEngine, SudokuEngine, validateRow } from "@reetesh/sudoku-engine";
const e = getClassicEngine();
validateRow(board, 0);
new SudokuEngine({ seed: 1 }).generateBatch({ count: 10 });
// After (3.0)
import { createEngine, BatchEngine, validateBoard } from "@reetesh/sudoku-engine";
const e = createEngine({ variant: "classic" });
validateBoard(board);
new BatchEngine({ seed: 1 }).generateBatch({ count: 10 });What stays the same
import { generatePuzzle, solve, validateBoard, createEngine } from "@reetesh/sudoku-engine";
generatePuzzle("medium");
solve(puzzle);
createEngine({ variant: "jigsaw" }); // still worksNew in 3.0 (variants)
import { createEngine } from "@reetesh/sudoku-engine";
// Killer / Thermo / Kropki — persist and reattach meta
const killer = createEngine({ variant: "killer" });
const game = killer.generatePuzzle("easy")!;
killer.withMeta(game.metaConstraints!).solve(game.puzzle);
// Samurai — 21×21; inactive cells stay null
createEngine({ variant: "samurai" }).generatePuzzle("easy");Preferred APIs in 3.0
import {
createEngine,
defineVariant,
BatchEngine,
composeHouses,
} from "@reetesh/sudoku-engine";
const engine = createEngine({ variant: "samurai" });
createEngine({ definition: defineVariant({ /* … */ }) });
new BatchEngine({ variant: "6x6", seed: 42 }).generateBatch({ count: 8 });Upgrade checklist
- Bump to
@reetesh/sudoku-engine@3.0.0. - Replace
SudokuEngine→BatchEngineandSudokuEngineOptions→BatchEngineOptions. - Remove
getClassicEngine,validateRow,validateColumn,validateBox. - Prefer
createEnginefor anything non-classic (and for classic when you want one object for the whole session). - Re-run typecheck — removed exports will fail at compile time.
- If you add Killer / Thermo / Kropki, always save
metaConstraintswith the puzzle.
Behavioral notes
- Classic facades use a lazy singleton internally (no module-scope engine at import time).
- Technique heuristics are per-variant (tighter / jigsaw / meta / samurai profiles).
- Docs hub: start at docs/README.md.
2.1 / 2.0 (historical)
- 2.1: Windoku + Jigsaw
- 2.0: Variant framework (
createEngine), classic + 6×6 + diagonal + hyper
See Changelog for the full timeline.