@fgv/ts-sudoku-lib 5.0.1-9 → 5.0.2-0

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

package/dist/packlets/common/puzzleSession.js

@@ -0,0 +1,369 @@
+/*
+ * 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 { captureResult, fail, succeed } from '@fgv/ts-utils';
+import { Cage } from './cage';
+import { Cell } from './cell';
+import { Ids } from './ids';
+/**
+ * Represents a single puzzle session, including puzzle, current state and redo/undo.
+ * @public
+ */
+export class PuzzleSession {
+    /**
+     * @internal
+     */
+    constructor(puzzle) {
+        this._puzzle = puzzle;
+        this.state = puzzle.initialState;
+        this._nextStep = 0;
+        this._numSteps = 0;
+        this._steps = [];
+    }
+    /**
+     * ID of the puzzle being solved.
+     */
+    get id() {
+        return this._puzzle.id;
+    }
+    /**
+     * Description of the puzzle being solved.
+     */
+    get description() {
+        return this._puzzle.description;
+    }
+    /**
+     * Type of the puzzle being solved.
+     */
+    get type() {
+        return this._puzzle.type;
+    }
+    /**
+     * Number of rows in the puzzle being solved.
+     */
+    get numRows() {
+        return this._puzzle.numRows;
+    }
+    /**
+     * Number of columns in the puzzle being solved.
+     */
+    get numColumns() {
+        return this._puzzle.numColumns;
+    }
+    /**
+     * The row {@link ICage | cages} in the puzzle being solved.
+     */
+    get rows() {
+        return this._puzzle.rows;
+    }
+    /**
+     * The column {@link ICage | cages} in the puzzle being solved.
+     */
+    get cols() {
+        return this._puzzle.cols;
+    }
+    /**
+     * The section {@link ICage | cages} in the puzzle being solved.
+     */
+    get sections() {
+        return this._puzzle.sections;
+    }
+    /**
+     * All {@link ICage | cages} in the puzzle being solved.
+     */
+    get cages() {
+        return this._puzzle.cages;
+    }
+    /**
+     * The cells {@link ICell | cells} in the puzzle being solved.
+     */
+    get cells() {
+        return this._puzzle.cells;
+    }
+    /**
+     * The puzzle structure for this session.
+     */
+    get puzzle() {
+        return this._puzzle;
+    }
+    /**
+     * Index of the next step in this puzzle session.
+     */
+    get nextStep() {
+        return this._nextStep;
+    }
+    /**
+     * Number of steps currently elapsed in this puzzle session.  Note
+     * that after undo, `nextStep` will be less than `numSteps`.
+     */
+    get numSteps() {
+        return this._numSteps;
+    }
+    /***
+     * Indicates whether undo is currently possible.
+     */
+    get canUndo() {
+        return this._nextStep > 0;
+    }
+    /**
+     * Indicates whether redo is currently possible.
+     */
+    get canRedo() {
+        return this._nextStep < this._numSteps;
+    }
+    /**
+     * Creates a new {@link PuzzleSession | puzzle session} from a supplied
+     * {@link Puzzle | puzzle}.
+     * @param puzzle - The {@link Puzzle | puzzle} from which the session is to be
+     * initialized.
+     * @returns `Success` with the requested {@link PuzzleSession | puzzle session},
+     * or `Failure` with details if an error occurs.
+     */
+    static create(puzzle) {
+        return captureResult(() => new PuzzleSession(puzzle));
+    }
+    /**
+     * Determines if the puzzle is correctly solved.
+     * @returns `true` if the puzzle is solved, `false` if the puzzle has
+     * empty or invalid cells.
+     */
+    checkIsSolved() {
+        return this._puzzle.checkIsSolved(this.state);
+    }
+    /**
+     * Determines if the puzzle is valid in its current state.
+     * @returns `true` if all non-empty cells in the puzzle are valid,
+     * or `false` if any cells are invalid.
+     */
+    checkIsValid() {
+        return this._puzzle.checkIsValid(this.state);
+    }
+    /**
+     * Gets all of the currently empty {@link ICell | cells} in the puzzle.
+     * @returns An array of {@link ICell | ICell} with all empty cells.
+     */
+    getEmptyCells() {
+        return this._puzzle.getEmptyCells(this.state);
+    }
+    /**
+     * Gets all of the currently invalid {@link ICell | cells} in the puzzle.
+     * @returns An array of {@link ICell | ICell} with all invalid cells.
+     */
+    getInvalidCells() {
+        return this._puzzle.getInvalidCells(this.state);
+    }
+    /**
+     * Determines if a cell is valid.
+     * @param spec - A `string` ({@link CellId | CellId}), {@link IRowColumn | RowColumn} or {@link ICell | ICell}
+     * describing the cell to be tested.
+     * @returns `true` if the cell value is valid, `false` if the cell value or the cell itself is invalid.
+     */
+    cellIsValid(spec) {
+        var _a;
+        return ((_a = this._cell(spec)) === null || _a === void 0 ? void 0 : _a.isValid(this.state)) === true;
+    }
+    /**
+     * Determines if a cell has a value.
+     * @param spec - A `string` ({@link CellId | CellId}), {@link IRowColumn | RowColumn} or {@link ICell | ICell}
+     * describing the cell to be tested.
+     * @returns `true` if the cell has a value, `false` if the cell is empty or the cell itself is invalid.
+     */
+    cellHasValue(spec) {
+        var _a;
+        return ((_a = this._cell(spec)) === null || _a === void 0 ? void 0 : _a.hasValue(this.state)) === true;
+    }
+    /**
+     * Determines if supplied value is valid for a specific cell.
+     * @param spec - A `string` ({@link CellId | CellId}), {@link IRowColumn | RowColumn} or {@link ICell | ICell}
+     * describing the cell to be tested.
+     * @param value - The value to be tested.
+     * @returns `true` if `value` is valid for the requested cell, `false` if the value or the cell itself is invalid.
+     */
+    isValidForCell(spec, value) {
+        var _a;
+        return ((_a = this._cell(spec)) === null || _a === void 0 ? void 0 : _a.isValidValue(value, this.state)) === true;
+    }
+    /**
+     * Gets the neighbor for a cell in a given direction using specified wrapping rules.
+     * @param spec - A `string` ({@link CellId | CellId}), {@link IRowColumn | RowColumn} or {@link ICell | ICell}
+     * describing the cell to be tested.
+     * @param direction - The direction of the desired neighbor.
+     * @param wrap - Wrapping rules to be applied.
+     * @returns `Success` with the requested {@link ICell | cell}, or `Failure` with details if an error occurs.
+     */
+    getCellNeighbor(spec, direction, wrap) {
+        return this._puzzle.getCellNeighbor(spec, direction, wrap);
+    }
+    /**
+     * Gets the {@link ICellContents | contents} for a specified cell.
+     * @param spec - A `string` ({@link CellId | CellId}), {@link IRowColumn | RowColumn} or {@link ICell | ICell}
+     * describing the cell to be queried.
+     * @returns `Success` with the {@link ICell | cell description} and {@link ICellContents | cell contents}, or
+     * `Failure` with details if an error occurs.
+     */
+    getCellContents(spec) {
+        return this._puzzle.getCellContents(spec, this.state);
+    }
+    /**
+     * Updates the value of a cell.
+     * @param spec - A `string`, {@link IRowColumn | row and column}, or {@link ICell | cell} identifying
+     * the cell to be updated.
+     * @param value - A new value for the cell.
+     * @returns `Success` with `this` if the update is applied, `Failure` with details if an error occurs.
+     */
+    updateCellValue(spec, value) {
+        const idResult = Ids.cellId(spec);
+        return idResult.onSuccess((id) => {
+            const notes = [];
+            const update = { id, value, notes };
+            return this._puzzle.updateValues(update, this.state).onSuccess((update) => {
+                this._addMove(update.cells);
+                this.state = update.to;
+                return succeed(this);
+            });
+        });
+    }
+    /**
+     * Updates the notes on a cell.
+     * @param spec - A `string`, {@link IRowColumn | row and column}, or {@link ICell | cell} identifying
+     * the cell to be updated.
+     * @param notes - New notes for the cell.
+     * @returns `Success` with `this` if the update is applied, `Failure` with details if an error occurs.
+     */
+    updateCellNotes(spec, notes) {
+        const idResult = Ids.cellId(spec);
+        return idResult.onSuccess((id) => {
+            const value = undefined;
+            const update = { id, value, notes };
+            return this._puzzle.updateNotes(update, this.state).onSuccess((update) => {
+                this._addMove(update.cells);
+                this.state = update.to;
+                return succeed(this);
+            });
+        });
+    }
+    /**
+     * Updates value & notes for multiple cells.
+     * @param updates - An array of {@link ICellState | cell state} objects, each describing
+     * one cell to be updated.
+     * @returns `Success` with `this` if the updates are applied, `Failure` with details if
+     * an error occurs.
+     */
+    updateCells(updates) {
+        return this._puzzle.updateContents(updates, this.state).onSuccess((update) => {
+            this._addMove(update.cells);
+            this.state = update.to;
+            return succeed(this);
+        });
+    }
+    /**
+     * Determines if some {@link ICage | cage} contains a specific value.
+     * @param spec - A `string` ({@link CageId | CageId}) or {@link ICage | ICage}
+     * indicating the cage to be tested.
+     * @param value - The value to be tested.
+     * @returns `true` if the cage exists and contains the specified value,
+     * `false` otherwise.
+     */
+    cageContainsValue(spec, value) {
+        var _a;
+        return ((_a = this._cage(spec)) === null || _a === void 0 ? void 0 : _a.containsValue(value, this.state)) === true;
+    }
+    /**
+     * Determines the numbers currently present in some cage.
+     * @param spec - A `string` ({@link CageId | CageId}) or {@link ICage | ICage}
+     * indicating the cage to be tested.
+     * @returns A `Set<number>` containing all numbers present in the cage.
+     */
+    cageContainedValues(spec) {
+        var _a, _b;
+        return (_b = (_a = this._cage(spec)) === null || _a === void 0 ? void 0 : _a.containedValues(this.state)) !== null && _b !== void 0 ? _b : new Set();
+    }
+    /**
+     * Undo a single move in this puzzle session.
+     * @returns `Success` with `this` if the undo is applied, or `Failure`
+     * with details if an error occurs.
+     */
+    undo() {
+        if (!this.canUndo) {
+            return fail(`nothing to undo`);
+        }
+        return this._puzzle
+            .updateContents(this._steps[this._nextStep - 1].updates.map((u) => u.from), this.state)
+            .onSuccess((update) => {
+            this._nextStep--;
+            this.state = update.to;
+            return succeed(this);
+        });
+    }
+    /**
+     * Redo a single move in this puzzle session.
+     * @returns `Success` with `this` if the redo is applied, or `Failure`
+     * with details if an error occurs.
+     */
+    redo() {
+        if (!this.canRedo) {
+            return fail('nothing to redo');
+        }
+        return this._puzzle
+            .updateContents(this._steps[this._nextStep].updates.map((u) => u.to), this.state)
+            .onSuccess((update) => {
+            this._nextStep++;
+            this.state = update.to;
+            return succeed(this);
+        });
+    }
+    /**
+     * Gets a string representation of this puzzle, one string
+     * per row.
+     */
+    toStrings() {
+        return this._puzzle.toStrings(this.state);
+    }
+    _addMove(updates) {
+        if (this._nextStep < this._steps.length) {
+            this._steps[this._nextStep++] = { updates };
+        }
+        else {
+            this._steps.push({ updates });
+            this._nextStep = this._steps.length;
+        }
+        this._numSteps = this._nextStep;
+    }
+    _cage(spec) {
+        if (spec instanceof Cage) {
+            return spec;
+        }
+        return Ids.cageId(spec)
+            .onSuccess((id) => {
+            return this._puzzle.getCage(id);
+        })
+            .orDefault();
+    }
+    _cell(spec) {
+        if (spec instanceof Cell) {
+            return spec;
+        }
+        return this._puzzle.getCell(spec).orDefault();
+    }
+}
+//# sourceMappingURL=puzzleSession.js.map