@fgv/ts-sudoku-lib 5.0.1-0 → 5.0.1-10

package/dist/packlets/common/puzzle.js

@@ -0,0 +1,411 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * 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.
+ */
+import { fail, mapResults, succeed } from '@fgv/ts-utils';
+import { Cage } from './cage';
+import { Cell } from './cell';
+import { Ids } from './ids';
+import { PuzzleState } from './puzzleState';
+/**
+ * Abstract base class for all puzzles.
+ * @public
+ */
+export class Puzzle {
+    /**
+     * Constructs a new puzzle state.
+     * @param puzzle - {@Link IPuzzleDefinition | Puzzle definition} from which this puzzle state
+     * is to be initialized.
+     */
+    constructor(puzzle, extraCages) {
+        /* c8 ignore next - ?? is defense in depth */
+        extraCages = extraCages !== null && extraCages !== void 0 ? extraCages : [];
+        // Validate cell count matches grid size
+        /* c8 ignore next 7 - defensive test - not reachable in practice */
+        if (puzzle.cells.length !== puzzle.totalRows * puzzle.totalColumns) {
+            throw new Error(`Puzzle '${puzzle.description}" expected ${puzzle.totalRows * puzzle.totalColumns} cells, found ${puzzle.cells.length}`);
+        }
+        this.id = puzzle.id;
+        this.description = puzzle.description;
+        this.type = puzzle.type;
+        this.dimensions = puzzle;
+        const rows = Puzzle._createRowCages(puzzle.totalRows, puzzle.totalColumns, puzzle.basicCageTotal).orThrow();
+        const columns = Puzzle._createColumnCages(puzzle.totalRows, puzzle.totalColumns, puzzle.basicCageTotal).orThrow();
+        const sections = Puzzle._createSectionCages(puzzle).orThrow();
+        const cages = [...rows, ...columns, ...sections, ...extraCages];
+        this._rows = new Map(rows);
+        this._columns = new Map(columns);
+        this._sections = new Map(sections);
+        this._cages = new Map(cages);
+        this._cells = new Map();
+        const cellInit = [...puzzle.cells];
+        for (let row = 0; row < this._rows.size; row++) {
+            const rowCage = this.getRow(row).orThrow();
+            for (let col = 0; col < this._columns.size; col++) {
+                const id = Ids.cellId({ row, col }).orThrow();
+                const colCage = this.getColumn(col).orThrow();
+                const sectionCage = this.getSection({ row, col }).orThrow();
+                const otherCages = extraCages.filter(([__key, cage]) => cage.containsCell(id));
+                const init = cellInit.shift();
+                /* c8 ignore next - defense in depth/make type check happy. undefined init should never happen */
+                const immutableValue = init === '.' ? undefined : this._parseAlphanumericValue(init !== null && init !== void 0 ? init : '0');
+                if (immutableValue !== undefined &&
+                    (Number.isNaN(immutableValue) || immutableValue < 1 || immutableValue > puzzle.maxValue)) {
+                    throw new Error(`Puzzle ${puzzle.description} illegal value "${init}" for cell ${id}`);
+                }
+                const cages = [rowCage, colCage, sectionCage, ...otherCages.map(([__key, state]) => state)];
+                const cell = new Cell({ id, immutableValue, row, col }, cages);
+                this._cells.set(id, cell);
+            }
+        }
+        this.initialState = PuzzleState.create(Array.from(this._cells.entries()).map(([id, state]) => {
+            return { id, value: state.immutableValue, notes: [] };
+        })).orThrow();
+    }
+    get numRows() {
+        return this._rows.size;
+    }
+    get numColumns() {
+        return this._columns.size;
+    }
+    get rows() {
+        return Array.from(this._rows.values());
+    }
+    get cols() {
+        return Array.from(this._columns.values());
+    }
+    get sections() {
+        return Array.from(this._sections.values());
+    }
+    get cages() {
+        return Array.from(this._cages.values());
+    }
+    get cells() {
+        return Array.from(this._cells.values());
+    }
+    /**
+     * @internal
+     */
+    static _createRowCages(numRows, numCols, basicCageTotal) {
+        const cages = [];
+        for (let r = 0; r < numRows; r++) {
+            const id = Ids.rowCageId(r);
+            const cellIds = Ids.cellIds(r, 1, 0, numCols);
+            /* c8 ignore next 3 - defense in depth should never happen */
+            if (cellIds.isFailure()) {
+                return fail(cellIds.message);
+            }
+            const result = Cage.create(id, 'row', basicCageTotal, cellIds.value).onSuccess((cage) => {
+                cages.push([id, cage]);
+                return succeed(cage);
+            });
+            /* c8 ignore next 3 - defense in depth should never happen */
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+        }
+        return succeed(cages);
+    }
+    /**
+     * @internal
+     */
+    static _createColumnCages(numRows, numCols, basicCageTotal) {
+        const cages = [];
+        for (let c = 0; c < numCols; c++) {
+            const id = Ids.columnCageId(c);
+            const cellIds = Ids.cellIds(0, numRows, c, 1);
+            /* c8 ignore next 3 - defense in depth should never happen */
+            if (cellIds.isFailure()) {
+                return fail(cellIds.message);
+            }
+            const result = Cage.create(id, 'column', basicCageTotal, cellIds.value).onSuccess((cage) => {
+                cages.push([id, cage]);
+                return succeed(cage);
+            });
+            /* c8 ignore next 3 - defense in depth should never happen */
+            if (result.isFailure()) {
+                return fail(result.message);
+            }
+        }
+        return succeed(cages);
+    }
+    /**
+     * Parse alphanumeric cell value (1-9, A-Z for values 10-35)
+     * @internal
+     */
+    _parseAlphanumericValue(char) {
+        // Handle digits 1-9
+        if (char >= '1' && char <= '9') {
+            return Number.parseInt(char, 10);
+        }
+        // Handle uppercase A-Z for values 10-35
+        if (char >= 'A' && char <= 'Z') {
+            return char.charCodeAt(0) - 'A'.charCodeAt(0) + 10;
+        }
+        // Handle lowercase a-z for values 10-35
+        if (char >= 'a' && char <= 'z') {
+            return char.charCodeAt(0) - 'a'.charCodeAt(0) + 10;
+        }
+        // Invalid character, return NaN to trigger error handling
+        return Number.NaN;
+    }
+    /**
+     * @internal
+     */
+    static _createSectionCages(puzzle) {
+        const cages = [];
+        const cageWidth = puzzle.cageWidthInCells;
+        const cageHeight = puzzle.cageHeightInCells;
+        const boardWidth = puzzle.boardWidthInCages;
+        const boardHeight = puzzle.boardHeightInCages;
+        for (let boardRow = 0; boardRow < boardHeight; boardRow++) {
+            for (let boardCol = 0; boardCol < boardWidth; boardCol++) {
+                const startRow = boardRow * cageHeight;
+                const startCol = boardCol * cageWidth;
+                const id = Ids.sectionCageId(startRow, startCol, cageHeight, cageWidth);
+                const cellIds = Ids.cellIds(startRow, cageHeight, startCol, cageWidth);
+                /* c8 ignore next 3 - defense in depth should never happen */
+                if (cellIds.isFailure()) {
+                    return fail(cellIds.message);
+                }
+                const result = Cage.create(id, 'section', puzzle.basicCageTotal, cellIds.value).onSuccess((cage) => {
+                    cages.push([id, cage]);
+                    return succeed(cage);
+                });
+                /* c8 ignore next 3 - defense in depth should never happen */
+                if (result.isFailure()) {
+                    return fail(result.message);
+                }
+            }
+        }
+        return succeed(cages);
+    }
+    checkIsSolved(state) {
+        for (const id of this._cells.keys()) {
+            if (!state.hasValue(id)) {
+                return false;
+            }
+        }
+        for (const cell of this._cells.values()) {
+            if (!cell.isValid(state)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    checkIsValid(state) {
+        for (const cell of this._cells.values()) {
+            if (!cell.isValid(state)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    getEmptyCells(state) {
+        return Array.from(this._cells.values()).filter((c) => !state.hasValue(c.id));
+    }
+    getInvalidCells(state) {
+        return Array.from(this._cells.values()).filter((c) => !c.isValid(state));
+    }
+    getCellContents(spec, state) {
+        return this.getCell(spec).onSuccess((cell) => {
+            if (cell.immutable) {
+                const contents = { value: cell.immutableValue, notes: [] };
+                return succeed({ cell, contents });
+            }
+            return state.getCellContents(cell.id).onSuccess((contents) => {
+                return succeed({ cell, contents });
+            });
+        });
+    }
+    getCell(spec) {
+        const want = Ids.cellId(spec);
+        if (want.isFailure()) {
+            return fail(want.message);
+        }
+        const cell = this._cells.get(want.value);
+        return cell ? succeed(cell) : fail(`Cell ${want.value} not found`);
+    }
+    getCellNeighbor(spec, direction, wrap) {
+        return this.getCell(spec).onSuccess((cell) => {
+            const move = direction === 'left' || direction === 'right'
+                ? this._moveColumn(cell, direction, wrap)
+                : this._moveRow(cell, direction, wrap);
+            return move.onSuccess((next) => this.getCell(next));
+        });
+    }
+    updateContents(wantUpdates, state) {
+        wantUpdates = Array.isArray(wantUpdates) ? wantUpdates : [wantUpdates];
+        return mapResults(wantUpdates.map((u) => this.getCellContents(u.id, state).onSuccess((existing) => existing.cell.update(u.value, u.notes).onSuccess((to) => {
+            const from = Object.assign({ id: u.id }, existing.contents);
+            return succeed({ from, to });
+        })))).onSuccess((cellUpdates) => {
+            return state.update(cellUpdates.map(({ to }) => to)).onSuccess((updatedState) => {
+                return succeed({
+                    from: state,
+                    to: updatedState,
+                    cells: cellUpdates
+                });
+            });
+        });
+    }
+    updateValues(wantUpdates, state) {
+        wantUpdates = Array.isArray(wantUpdates) ? wantUpdates : [wantUpdates];
+        return mapResults(wantUpdates.map((u) => this.getCellContents(u.id, state).onSuccess((existing) => existing.cell.update(u.value, existing.contents.notes).onSuccess((to) => {
+            const from = Object.assign({ id: u.id }, existing.contents);
+            return succeed({ from, to });
+        })))).onSuccess((cellUpdates) => {
+            return state.update(cellUpdates.map(({ to }) => to)).onSuccess((updatedState) => {
+                return succeed({
+                    from: state,
+                    to: updatedState,
+                    cells: cellUpdates
+                });
+            });
+        });
+    }
+    updateNotes(wantUpdates, state) {
+        wantUpdates = Array.isArray(wantUpdates) ? wantUpdates : [wantUpdates];
+        return mapResults(wantUpdates.map((u) => this.getCellContents(u.id, state).onSuccess((existing) => existing.cell.update(existing.contents.value, u.notes).onSuccess((to) => {
+            const from = Object.assign({ id: u.id }, existing.contents);
+            return succeed({ from, to });
+        })))).onSuccess((cellUpdates) => {
+            return state.update(cellUpdates.map(({ to }) => to)).onSuccess((updatedState) => {
+                return succeed({
+                    from: state,
+                    to: updatedState,
+                    cells: cellUpdates
+                });
+            });
+        });
+    }
+    updateCellValue(want, value, state) {
+        const idResult = Ids.cellId(want);
+        const notes = [];
+        return idResult.onSuccess((id) => {
+            const update = { id, value, notes };
+            return this.updateValues([update], state);
+        });
+    }
+    updateCellNotes(want, notes, state) {
+        const idResult = Ids.cellId(want);
+        const value = undefined;
+        return idResult.onSuccess((id) => {
+            const update = { id, value, notes };
+            return this.updateNotes([update], state);
+        });
+    }
+    getRow(row) {
+        const id = typeof row === 'number' ? Ids.rowCageId(row) : row;
+        const cage = this._rows.get(id);
+        return cage ? succeed(cage) : fail(`Row ${id} not found`);
+    }
+    getColumn(col) {
+        const id = typeof col === 'number' ? Ids.columnCageId(col) : col;
+        const cage = this._columns.get(id);
+        return cage ? succeed(cage) : fail(`Column ${id} not found`);
+    }
+    getSection(spec) {
+        const id = typeof spec === 'object'
+            ? Ids.sectionCageId(spec.row, spec.col, this.dimensions.cageHeightInCells, this.dimensions.cageWidthInCells)
+            : spec;
+        const cage = this._sections.get(id);
+        return cage ? succeed(cage) : fail(`Section ${id} not found`);
+    }
+    getCage(id) {
+        const cage = this._cages.get(id);
+        return cage ? succeed(cage) : fail(`Cage ${id} not found`);
+    }
+    toStrings(state) {
+        return Array.from(this._rows.values()).map((row) => row.toString(state));
+    }
+    toString(state) {
+        return this.toStrings(state).join('\n');
+    }
+    _moveColumn(current, direction, wrap) {
+        const row = current.row;
+        let col = current.col;
+        if (direction === 'left') {
+            if (col > 0) {
+                col = col - 1;
+            }
+            else if (wrap !== 'none') {
+                col = this.numColumns - 1;
+                if (wrap === 'wrap-next') {
+                    return this._moveRow({ row, col }, 'up', 'wrap-around');
+                }
+            }
+            else {
+                return fail(`cannot move left from column ${current.col}`);
+            }
+        }
+        else if (direction === 'right') {
+            if (col < this.numColumns - 1) {
+                col = col + 1;
+            }
+            else if (wrap !== 'none') {
+                col = 0;
+                if (wrap === 'wrap-next') {
+                    return this._moveRow({ row, col }, 'down', 'wrap-around');
+                }
+            }
+            else {
+                return fail(`cannot move right from column ${current.col}`);
+            }
+        }
+        return succeed({ row, col });
+    }
+    _moveRow(current, direction, wrap) {
+        let row = current.row;
+        const col = current.col;
+        if (direction === 'up') {
+            if (row > 0) {
+                row = row - 1;
+            }
+            else if (wrap !== 'none') {
+                row = this.numRows - 1;
+                if (wrap === 'wrap-next') {
+                    return this._moveColumn({ row, col }, 'left', 'wrap-around');
+                }
+            }
+            else {
+                return fail(`cannot move up from row ${current.row}`);
+            }
+        }
+        else if (direction === 'down') {
+            if (row < this.numRows - 1) {
+                row = row + 1;
+            }
+            else if (wrap !== 'none') {
+                row = 0;
+                if (wrap === 'wrap-next') {
+                    return this._moveColumn({ row, col }, 'right', 'wrap-around');
+                }
+            }
+            else {
+                return fail(`cannot move down from row ${current.row}`);
+            }
+        }
+        return succeed({ row, col });
+    }
+}
+//# sourceMappingURL=puzzle.js.map

package/dist/packlets/common/puzzleDefinitions.js

@@ -0,0 +1,247 @@
+/*
+ * MIT License
+ *
+ * Copyright (c) 2023 Erik Fortune
+ *
+ * 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.
+ */
+import { succeed, fail, captureResult } from '@fgv/ts-utils';
+/**
+ * Default validator for standard Sudoku puzzles
+ */
+class StandardSudokuValidator {
+    validateCells(cells, dimensions) {
+        const expectedLength = dimensions.cageHeightInCells *
+            dimensions.boardHeightInCages *
+            dimensions.cageWidthInCells *
+            dimensions.boardWidthInCages;
+        if (cells.length !== expectedLength) {
+            return fail(`Expected ${expectedLength} cells, got ${cells.length}`);
+        }
+        return succeed(true);
+    }
+}
+/**
+ * Validator for Killer Sudoku puzzles - understands extended format with cage definitions
+ */
+class KillerSudokuValidator {
+    validateCells(cells, dimensions) {
+        const expectedBasicLength = dimensions.cageHeightInCells *
+            dimensions.boardHeightInCages *
+            dimensions.cageWidthInCells *
+            dimensions.boardWidthInCages;
+        // Killer sudoku cells format includes cage definitions, so it will be longer than basic format
+        // The basic grid should be at the beginning of the string
+        if (cells.length < expectedBasicLength) {
+            return fail(`Killer sudoku cells must contain at least ${expectedBasicLength} grid cells, got ${cells.length}`);
+        }
+        // Find the separator between grid and cage definitions
+        const separatorIndex = cells.indexOf('|');
+        if (separatorIndex === -1) {
+            return fail('Killer sudoku cells must contain cage definitions after "|" separator');
+        }
+        if (separatorIndex !== expectedBasicLength) {
+            return fail(`Killer sudoku grid portion must be exactly ${expectedBasicLength} characters, got ${separatorIndex}`);
+        }
+        // Extract the basic grid portion (before the | separator)
+        const gridPortion = cells.substring(0, separatorIndex);
+        // For killer sudoku, the grid portion contains:
+        // - Digits 1-9 for prefilled values
+        // - '.' for empty cells
+        // - Letters A-Z, a-z for cage identifiers
+        const maxDigit = dimensions.cageWidthInCells * dimensions.cageHeightInCells;
+        const validDigits = new Set(['.', ...Array.from({ length: maxDigit }, (__val, i) => String(i + 1))]);
+        const validCageLetters = new Set([...'ABCDEFGHIJKLMNOPQRSTUVWXYZ', ...'abcdefghijklmnopqrstuvwxyz']);
+        for (let i = 0; i < gridPortion.length; i++) {
+            const char = gridPortion[i];
+            if (!validDigits.has(char) && !validCageLetters.has(char)) {
+                return fail(`Invalid character '${char}' at position ${i} in killer sudoku grid portion`);
+            }
+        }
+        return succeed(true);
+    }
+}
+/**
+ * Validator for Sudoku X puzzles - same as standard but with diagonal constraints
+ */
+class SudokuXValidator {
+    validateCells(cells, dimensions) {
+        // Sudoku X uses the same cell format as standard sudoku
+        return new StandardSudokuValidator().validateCells(cells, dimensions);
+    }
+}
+/**
+ * Registry of validators for different puzzle types
+ */
+const PUZZLE_TYPE_VALIDATORS = {
+    sudoku: new StandardSudokuValidator(),
+    'killer-sudoku': new KillerSudokuValidator(),
+    'sudoku-x': new SudokuXValidator()
+};
+/**
+ * Standard puzzle configurations
+ * @public
+ */
+export const STANDARD_CONFIGS = {
+    puzzle4x4: { cageWidthInCells: 2, cageHeightInCells: 2, boardWidthInCages: 2, boardHeightInCages: 2 },
+    puzzle6x6: { cageWidthInCells: 3, cageHeightInCells: 2, boardWidthInCages: 2, boardHeightInCages: 3 },
+    puzzle9x9: { cageWidthInCells: 3, cageHeightInCells: 3, boardWidthInCages: 3, boardHeightInCages: 3 },
+    puzzle12x12: { cageWidthInCells: 4, cageHeightInCells: 3, boardWidthInCages: 3, boardHeightInCages: 4 }
+};
+/**
+ * Factory for creating and validating puzzle definitions
+ * @public
+ */
+export class PuzzleDefinitionFactory {
+    /**
+     * Create a puzzle definition from dimensions and options
+     */
+    static create(dimensions, options = {}) {
+        var _a, _b, _c, _d, _e;
+        const dimensionValidation = this.validate(dimensions);
+        if (dimensionValidation.isFailure()) {
+            return fail(dimensionValidation.message);
+        }
+        const totalRows = dimensions.cageHeightInCells * dimensions.boardHeightInCages;
+        const totalColumns = dimensions.cageWidthInCells * dimensions.boardWidthInCages;
+        const maxValue = dimensions.cageWidthInCells * dimensions.cageHeightInCells;
+        const totalCages = dimensions.boardWidthInCages * dimensions.boardHeightInCages;
+        const basicCageTotal = this._calculateBasicCageTotal(maxValue);
+        // Validate cell data using type-specific validator
+        if (options.cells) {
+            const puzzleType = (_a = options.type) !== null && _a !== void 0 ? _a : 'sudoku';
+            const validator = PUZZLE_TYPE_VALIDATORS[puzzleType];
+            if (!validator) {
+                return fail(`Unknown puzzle type: ${puzzleType}`);
+            }
+            const cellValidation = validator.validateCells(options.cells, dimensions);
+            if (cellValidation.isFailure()) {
+                return fail(cellValidation.message);
+            }
+        }
+        const puzzleDefinition = {
+            // Dimensions
+            cageWidthInCells: dimensions.cageWidthInCells,
+            cageHeightInCells: dimensions.cageHeightInCells,
+            boardWidthInCages: dimensions.boardWidthInCages,
+            boardHeightInCages: dimensions.boardHeightInCages,
+            // Derived properties
+            totalRows,
+            totalColumns,
+            maxValue,
+            totalCages,
+            basicCageTotal,
+            // Default values
+            id: options.id,
+            description: (_b = options.description) !== null && _b !== void 0 ? _b : `${totalRows}x${totalColumns} puzzle`,
+            type: (_c = options.type) !== null && _c !== void 0 ? _c : 'sudoku',
+            level: (_d = options.level) !== null && _d !== void 0 ? _d : 1,
+            cells: (_e = options.cells) !== null && _e !== void 0 ? _e : '.'.repeat(totalRows * totalColumns),
+            cages: options.cages
+        };
+        return succeed(puzzleDefinition);
+    }
+    /**
+     * Create killer sudoku puzzle definition with cage constraints
+     */
+    static createKiller(dimensions, description) {
+        return captureResult(() => {
+            // Import needed here to avoid circular dependencies
+            const { Ids } = require('./ids');
+            // Convert killer cage format to standard cage format - creating minimal cage objects
+            const cages = description.killerCages.map((killerCage) => {
+                const cellIds = killerCage.cellPositions.map((pos) => Ids.cellId(pos).orThrow());
+                return {
+                    id: `K${killerCage.id}`,
+                    cellIds,
+                    cageType: 'killer',
+                    total: killerCage.sum,
+                    numCells: cellIds.length,
+                    /* c8 ignore next 1 - coverage fails when run as part of full suite */
+                    containsCell: (cellId) => cellIds.includes(cellId)
+                };
+            });
+            // Return the result directly, not wrapped in another Result
+            const result = this.create(dimensions, Object.assign(Object.assign({}, description), { cages, type: 'killer-sudoku' }));
+            if (result.isFailure()) {
+                throw new Error(result.message);
+            }
+            return result.value;
+        }).onFailure((error) => fail(`Failed to create killer sudoku: ${error}`));
+    }
+    /**
+     * Validate puzzle dimensions
+     */
+    static validate(dimensions) {
+        // Structural validation
+        if (dimensions.cageWidthInCells < 1 || dimensions.cageHeightInCells < 1) {
+            return fail('Cage dimensions must be positive integers');
+        }
+        // Sudoku cages must be multi-cell (both dimensions > 1)
+        if (dimensions.cageWidthInCells < 2 || dimensions.cageHeightInCells < 2) {
+            return fail('Cage dimensions must be at least 2x2 for valid Sudoku puzzles');
+        }
+        if (dimensions.boardWidthInCages < 1 || dimensions.boardHeightInCages < 1) {
+            return fail('Board dimensions must be positive integers');
+        }
+        // Size constraints (reasonable limits)
+        const totalRows = dimensions.cageHeightInCells * dimensions.boardHeightInCages;
+        const totalColumns = dimensions.cageWidthInCells * dimensions.boardWidthInCages;
+        if (totalRows > 25 || totalColumns > 25) {
+            return fail('Total grid size must not exceed 25x25');
+        }
+        // Mathematical validity - ensure cage size makes sense for Sudoku constraints
+        const maxValue = dimensions.cageWidthInCells * dimensions.cageHeightInCells;
+        if (maxValue < 2 || maxValue > 25) {
+            return fail('Cage size must result in values between 2 and 25');
+        }
+        return succeed(true);
+    }
+    /**
+     * Get a standard configuration by name
+     */
+    static getStandardConfig(name) {
+        return STANDARD_CONFIGS[name];
+    }
+    /**
+     * Get all available standard configurations
+     */
+    static getStandardConfigs() {
+        return STANDARD_CONFIGS;
+    }
+    /**
+     * Get validator for a specific puzzle type
+     */
+    static getValidator(puzzleType) {
+        return PUZZLE_TYPE_VALIDATORS[puzzleType];
+    }
+    /**
+     * Register a custom validator for a puzzle type
+     */
+    static registerValidator(puzzleType, validator) {
+        PUZZLE_TYPE_VALIDATORS[puzzleType] = validator;
+    }
+    /**
+     * Calculate the basic cage total (sum of 1 to maxValue)
+     */
+    static _calculateBasicCageTotal(maxValue) {
+        return (maxValue * (maxValue + 1)) / 2;
+    }
+}
+//# sourceMappingURL=puzzleDefinitions.js.map