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

package/lib/packlets/hints/puzzleSessionHints.js

@@ -0,0 +1,499 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PuzzleSessionHints = void 0;
+const ts_utils_1 = require("@fgv/ts-utils");
+const common_1 = require("../common");
+const hints_1 = require("./hints");
+/**
+ * Wrapper class that integrates hint functionality with PuzzleSession.
+ * Provides hint generation, application, and explanation capabilities while
+ * maintaining integration with existing state management and undo/redo functionality.
+ * @public
+ */
+class PuzzleSessionHints {
+    /**
+     * @internal
+     */
+    constructor(session, hintSystem, config) {
+        this._session = session;
+        this._hintSystem = hintSystem;
+        this._config = config;
+        this._hintCache = undefined;
+    }
+    /**
+     * Creates a new PuzzleSessionHints wrapper for an existing PuzzleSession.
+     * @param session - The PuzzleSession to wrap
+     * @param config - Optional configuration for the hint system
+     * @returns Result containing the new PuzzleSessionHints wrapper
+     */
+    static create(session, config) {
+        const finalConfig = Object.assign({ enableNakedSingles: true, enableHiddenSingles: true, defaultExplanationLevel: 'detailed', cacheTimeoutMs: 5000, maxCacheEntries: 1 }, config);
+        return hints_1.HintSystem.create(finalConfig).onSuccess((hintSystem) => {
+            return (0, ts_utils_1.succeed)(new PuzzleSessionHints(session, hintSystem, finalConfig));
+        });
+    }
+    /**
+     * Gets the wrapped PuzzleSession instance.
+     * @returns The underlying PuzzleSession
+     */
+    get session() {
+        return this._session;
+    }
+    /**
+     * Gets the HintSystem instance.
+     * @returns The hint system
+     */
+    get hintSystem() {
+        return this._hintSystem;
+    }
+    /**
+     * Gets the configuration.
+     * @returns The configuration
+     */
+    get config() {
+        return this._config;
+    }
+    // Delegate all PuzzleSession methods for transparent access
+    /**
+     * Gets the puzzle ID.
+     * @returns The puzzle ID
+     */
+    get id() {
+        return this._session.id;
+    }
+    /**
+     * Gets the puzzle description.
+     * @returns The puzzle description
+     */
+    get description() {
+        return this._session.description;
+    }
+    /**
+     * Gets the number of rows in the puzzle.
+     * @returns The number of rows
+     */
+    get numRows() {
+        return this._session.numRows;
+    }
+    /**
+     * Gets the number of columns in the puzzle.
+     * @returns The number of columns
+     */
+    get numColumns() {
+        return this._session.numColumns;
+    }
+    /**
+     * Gets the current puzzle state.
+     * @returns The current state
+     */
+    get state() {
+        return this._session.state;
+    }
+    /**
+     * Gets whether undo is possible.
+     * @returns true if undo is possible
+     */
+    get canUndo() {
+        return this._session.canUndo;
+    }
+    /**
+     * Gets whether redo is possible.
+     * @returns true if redo is possible
+     */
+    get canRedo() {
+        return this._session.canRedo;
+    }
+    /**
+     * Checks if the puzzle is solved.
+     * @returns true if the puzzle is solved
+     */
+    checkIsSolved() {
+        return this._session.checkIsSolved();
+    }
+    /**
+     * Checks if the puzzle is valid.
+     * @returns true if the puzzle is valid
+     */
+    checkIsValid() {
+        return this._session.checkIsValid();
+    }
+    /**
+     * Updates a cell value.
+     * @param spec - Cell specification
+     * @param value - New value
+     * @returns Result with this instance
+     */
+    updateCellValue(spec, value) {
+        return this._session.updateCellValue(spec, value).onSuccess(() => {
+            this._invalidateCache();
+            return (0, ts_utils_1.succeed)(this);
+        });
+    }
+    /**
+     * Updates cell notes.
+     * @param spec - Cell specification
+     * @param notes - New notes
+     * @returns Result with this instance
+     */
+    updateCellNotes(spec, notes) {
+        return this._session.updateCellNotes(spec, notes).onSuccess(() => {
+            this._invalidateCache();
+            return (0, ts_utils_1.succeed)(this);
+        });
+    }
+    /**
+     * Updates multiple cells.
+     * @param updates - Array of cell updates
+     * @returns Result with this instance
+     */
+    updateCells(updates) {
+        return this._session.updateCells(updates).onSuccess(() => {
+            this._invalidateCache();
+            return (0, ts_utils_1.succeed)(this);
+        });
+    }
+    /**
+     * Performs an undo operation.
+     * @returns Result with this instance
+     */
+    undo() {
+        return this._session.undo().onSuccess(() => {
+            this._invalidateCache();
+            return (0, ts_utils_1.succeed)(this);
+        });
+    }
+    /**
+     * Performs a redo operation.
+     * @returns Result with this instance
+     */
+    redo() {
+        return this._session.redo().onSuccess(() => {
+            this._invalidateCache();
+            return (0, ts_utils_1.succeed)(this);
+        });
+    }
+    // Hint-specific functionality
+    /**
+     * Gets the best available hint for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing the best hint
+     */
+    getHint(options) {
+        return this._hintSystem.getBestHint(this._session.puzzle, this._session.state, options);
+    }
+    /**
+     * Gets all available hints for the current puzzle state.
+     * @param options - Optional hint generation options
+     * @returns Result containing array of hints
+     */
+    getAllHints(options) {
+        // Check cache first
+        const cachedHints = this._getCachedHints(options);
+        if (cachedHints) {
+            return (0, ts_utils_1.succeed)(cachedHints);
+        }
+        // Generate new hints
+        return this._hintSystem
+            .generateHints(this._session.puzzle, this._session.state, options)
+            .onSuccess((hints) => {
+            this._updateCache(hints, options);
+            return (0, ts_utils_1.succeed)(hints);
+        });
+    }
+    /**
+     * Applies a hint to the puzzle, updating the state and adding to undo history.
+     * @param hint - The hint to apply
+     * @returns Result with this instance if successful
+     */
+    applyHint(hint) {
+        return this._hintSystem
+            .applyHint(hint, this._session.puzzle, this._session.state)
+            .onSuccess((updates) => {
+            // Convert readonly array to mutable array for PuzzleSession.updateCells
+            const mutableUpdates = [...updates];
+            return this._session.updateCells(mutableUpdates).onSuccess(() => {
+                this._invalidateCache();
+                return (0, ts_utils_1.succeed)(this);
+            });
+        });
+    }
+    /**
+     * Gets hints that specifically affect a given cell.
+     * @param spec - Cell specification (ID, row/column, or cell object)
+     * @param options - Optional hint generation options
+     * @returns Result containing hints affecting the specified cell
+     */
+    getHintsForCell(spec, options) {
+        const cellIdResult = common_1.Ids.cellId(spec);
+        return cellIdResult.onSuccess((cellId) => {
+            return this.getAllHints(options).onSuccess((allHints) => {
+                const relevantHints = allHints.filter((hint) => {
+                    // Check if the hint affects this specific cell
+                    return (hint.cellActions.some((action) => action.cellId === cellId) ||
+                        hint.relevantCells.primary.includes(cellId) ||
+                        hint.relevantCells.secondary.includes(cellId) ||
+                        hint.relevantCells.affected.includes(cellId));
+                });
+                return (0, ts_utils_1.succeed)(relevantHints);
+            });
+        });
+    }
+    /**
+     * Gets a formatted explanation for a hint.
+     * @param hint - The hint to explain
+     * @param level - The explanation level (defaults to configured default)
+     * @returns Formatted explanation string
+     */
+    getExplanation(hint, level) {
+        return this._hintSystem.formatHintExplanation(hint, level);
+    }
+    /**
+     * Validates that a hint can be applied to the current state.
+     * @param hint - The hint to validate
+     * @returns Result indicating validation success or failure
+     */
+    validateHint(hint) {
+        return this._hintSystem.validateHint(hint, this._session.puzzle, this._session.state);
+    }
+    /**
+     * Checks if hints are available for the current state.
+     * @param options - Optional hint generation options
+     * @returns Result containing boolean indicating availability
+     */
+    hasHints(options) {
+        return this._hintSystem.hasHints(this._session.puzzle, this._session.state);
+    }
+    /**
+     * Gets statistics about available hints.
+     * @param options - Optional hint generation options
+     * @returns Result containing hint statistics
+     */
+    getHintStatistics(options) {
+        return this._hintSystem.getHintStatistics(this._session.puzzle, this._session.state);
+    }
+    /**
+     * Gets a summary of the hint system capabilities.
+     * @returns System capabilities summary
+     */
+    getSystemSummary() {
+        return this._hintSystem.getSystemSummary();
+    }
+    // Delegate remaining PuzzleSession methods for complete transparency
+    /**
+     * Gets the rows.
+     * @returns Array of row cages
+     */
+    get rows() {
+        return this._session.rows;
+    }
+    /**
+     * Gets the columns.
+     * @returns Array of column cages
+     */
+    get cols() {
+        return this._session.cols;
+    }
+    /**
+     * Gets the sections.
+     * @returns Array of section cages
+     */
+    get sections() {
+        return this._session.sections;
+    }
+    /**
+     * Gets all cages.
+     * @returns Array of all cages
+     */
+    get cages() {
+        return this._session.cages;
+    }
+    /**
+     * Gets all cells.
+     * @returns Array of all cells
+     */
+    get cells() {
+        return this._session.cells;
+    }
+    /**
+     * Gets the next step index.
+     * @returns Next step index
+     */
+    get nextStep() {
+        return this._session.nextStep;
+    }
+    /**
+     * Gets the number of steps.
+     * @returns Number of steps
+     */
+    get numSteps() {
+        return this._session.numSteps;
+    }
+    /**
+     * Gets empty cells.
+     * @returns Array of empty cells
+     */
+    getEmptyCells() {
+        return this._session.getEmptyCells();
+    }
+    /**
+     * Gets invalid cells.
+     * @returns Array of invalid cells
+     */
+    getInvalidCells() {
+        return this._session.getInvalidCells();
+    }
+    /**
+     * Checks if a cell is valid.
+     * @param spec - Cell specification
+     * @returns true if valid
+     */
+    cellIsValid(spec) {
+        return this._session.cellIsValid(spec);
+    }
+    /**
+     * Checks if a cell has a value.
+     * @param spec - Cell specification
+     * @returns true if cell has value
+     */
+    cellHasValue(spec) {
+        return this._session.cellHasValue(spec);
+    }
+    /**
+     * Checks if a value is valid for a cell.
+     * @param spec - Cell specification
+     * @param value - Value to check
+     * @returns true if valid
+     */
+    isValidForCell(spec, value) {
+        return this._session.isValidForCell(spec, value);
+    }
+    /**
+     * Gets a cell neighbor.
+     * @param spec - Cell specification
+     * @param direction - Navigation direction
+     * @param wrap - Wrap behavior
+     * @returns Result containing neighbor cell
+     */
+    getCellNeighbor(spec, direction, wrap) {
+        return this._session.getCellNeighbor(spec, direction, wrap);
+    }
+    /**
+     * Gets cell contents.
+     * @param spec - Cell specification
+     * @returns Result containing cell and contents
+     */
+    getCellContents(spec) {
+        return this._session.getCellContents(spec);
+    }
+    /**
+     * Checks if a cage contains a value.
+     * @param spec - Cage specification
+     * @param value - Value to check
+     * @returns true if cage contains value
+     */
+    cageContainsValue(spec, value) {
+        return this._session.cageContainsValue(spec, value);
+    }
+    /**
+     * Gets contained values in a cage.
+     * @param spec - Cage specification
+     * @returns Set of contained values
+     */
+    cageContainedValues(spec) {
+        return this._session.cageContainedValues(spec);
+    }
+    /**
+     * Gets string representation of the puzzle.
+     * @returns Array of strings representing puzzle rows
+     */
+    toStrings() {
+        return this._session.toStrings();
+    }
+    // Private cache management methods
+    /**
+     * Generates a cache key for the current state and options.
+     * @param options - Hint generation options
+     * @returns Cache key
+     */
+    _generateCacheKey(options) {
+        // Simple state hash based on cell values and notes
+        const stateString = this._session.toStrings().join('|');
+        const notesString = this._session.cells
+            .map((cell) => {
+            const contents = this._session
+                .getCellContents(cell.id)
+                .orDefault({ cell, contents: { value: undefined, notes: [] } });
+            return `${cell.id}:${contents.contents.notes.join(',')}`;
+        })
+            .join('|');
+        const stateHash = `${stateString}#${notesString}`;
+        const optionsString = options ? JSON.stringify(options) : '';
+        return { stateHash, options: optionsString };
+    }
+    /**
+     * Gets cached hints if valid.
+     * @param options - Hint generation options
+     * @returns Cached hints or undefined
+     */
+    _getCachedHints(options) {
+        var _a;
+        if (!this._hintCache) {
+            return undefined;
+        }
+        const cacheKey = this._generateCacheKey(options);
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const timeoutMs = (_a = this._config.cacheTimeoutMs) !== null && _a !== void 0 ? _a : 5000;
+        const now = Date.now();
+        // Check if cache is still valid
+        if (this._hintCache.cacheKey.stateHash === cacheKey.stateHash &&
+            this._hintCache.cacheKey.options === cacheKey.options &&
+            now - this._hintCache.generatedAt < timeoutMs) {
+            return this._hintCache.hints;
+        }
+        return undefined;
+    }
+    /**
+     * Updates the cache with new hints.
+     * @param hints - Generated hints
+     * @param options - Generation options
+     */
+    _updateCache(hints, options) {
+        const cacheKey = this._generateCacheKey(options);
+        this._hintCache = {
+            hints,
+            generatedAt: Date.now(),
+            cacheKey
+        };
+    }
+    /**
+     * Invalidates the current hint cache.
+     */
+    _invalidateCache() {
+        this._hintCache = undefined;
+    }
+}
+exports.PuzzleSessionHints = PuzzleSessionHints;
+//# sourceMappingURL=puzzleSessionHints.js.map

package/lib/packlets/hints/types.d.ts

@@ -0,0 +1,102 @@
+import { Brand } from '@fgv/ts-utils';
+import { CellId } from '../common';
+/**
+ * Nominal identifier for a hint generation technique.
+ * @public
+ */
+export type TechniqueId = Brand<string, 'TechniqueId'>;
+/**
+ * Confidence level for a generated hint, ranging from 1 (low) to 5 (high).
+ * @public
+ */
+export type ConfidenceLevel = Brand<1 | 2 | 3 | 4 | 5, 'ConfidenceLevel'>;
+/**
+ * The type of action that should be taken on a cell as part of a hint.
+ * @public
+ */
+export type CellAction = 'set-value' | 'eliminate-candidate' | 'add-candidate' | 'highlight';
+/**
+ * The level of detail for hint explanations.
+ * @public
+ */
+export type ExplanationLevel = 'brief' | 'detailed' | 'educational';
+/**
+ * Standard difficulty classifications for Sudoku techniques.
+ * @public
+ */
+export type DifficultyLevel = 'beginner' | 'intermediate' | 'advanced' | 'expert';
+/**
+ * Describes an action to be taken on a specific cell as part of a hint.
+ * @public
+ */
+export interface ICellAction {
+    readonly cellId: CellId;
+    readonly action: CellAction;
+    readonly value?: number;
+    readonly reason?: string;
+}
+/**
+ * Information about the cells that are relevant to understanding a hint.
+ * @public
+ */
+export interface IRelevantCells {
+    readonly primary: readonly CellId[];
+    readonly secondary: readonly CellId[];
+    readonly affected: readonly CellId[];
+}
+/**
+ * A hint explanation at a specific level of detail.
+ * @public
+ */
+export interface IHintExplanation {
+    readonly level: ExplanationLevel;
+    readonly title: string;
+    readonly description: string;
+    readonly steps?: readonly string[];
+    readonly tips?: readonly string[];
+}
+/**
+ * A complete hint with all necessary information for display and application.
+ * @public
+ */
+export interface IHint {
+    readonly techniqueId: TechniqueId;
+    readonly techniqueName: string;
+    readonly difficulty: DifficultyLevel;
+    readonly confidence: ConfidenceLevel;
+    readonly cellActions: readonly ICellAction[];
+    readonly relevantCells: IRelevantCells;
+    readonly explanations: readonly IHintExplanation[];
+    readonly priority: number;
+}
+/**
+ * Configuration options for hint generation.
+ * @public
+ */
+export interface IHintGenerationOptions {
+    readonly maxHints?: number;
+    readonly minConfidence?: ConfidenceLevel;
+    readonly preferredDifficulty?: DifficultyLevel;
+    readonly enabledTechniques?: readonly TechniqueId[];
+    readonly explanationLevel?: ExplanationLevel;
+}
+/**
+ * Standard technique identifiers for built-in solving techniques.
+ * @public
+ */
+export declare const TechniqueIds: {
+    readonly NAKED_SINGLES: TechniqueId;
+    readonly HIDDEN_SINGLES: TechniqueId;
+};
+/**
+ * Standard confidence levels as branded types.
+ * @public
+ */
+export declare const ConfidenceLevels: {
+    readonly LOW: ConfidenceLevel;
+    readonly MEDIUM_LOW: ConfidenceLevel;
+    readonly MEDIUM: ConfidenceLevel;
+    readonly MEDIUM_HIGH: ConfidenceLevel;
+    readonly HIGH: ConfidenceLevel;
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/packlets/hints/types.js

@@ -0,0 +1,46 @@
+"use strict";
+/*
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfidenceLevels = exports.TechniqueIds = void 0;
+/**
+ * Standard technique identifiers for built-in solving techniques.
+ * @public
+ */
+exports.TechniqueIds = {
+    NAKED_SINGLES: 'naked-singles',
+    HIDDEN_SINGLES: 'hidden-singles'
+};
+/**
+ * Standard confidence levels as branded types.
+ * @public
+ */
+exports.ConfidenceLevels = {
+    LOW: 1,
+    MEDIUM_LOW: 2,
+    MEDIUM: 3,
+    MEDIUM_HIGH: 4,
+    HIGH: 5
+};
+//# sourceMappingURL=types.js.map

package/lib/packlets/puzzles/anyPuzzle.d.ts

@@ -1,10 +1,10 @@
 import { Result } from '@fgv/ts-utils';
-import { IPuzzleDescription, Puzzle } from '../common';
+import { IPuzzleDefinition, Puzzle } from '../common';
 /**
- * Static class to instantiate any puzzle from a {@link PuzzleDescription | puzzle description}.
+ * Static class to instantiate any puzzle from a {@link IPuzzleDefinition | puzzle definition}.
  * @internal
  */
 export declare class AnyPuzzle {
-    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    static create(puzzle: IPuzzleDefinition): Result<Puzzle>;
 }
 //# sourceMappingURL=anyPuzzle.d.ts.map

package/lib/packlets/puzzles/anyPuzzle.js

@@ -29,7 +29,7 @@ const killerSudokuPuzzle_1 = require("./killerSudokuPuzzle");
 const sudokuPuzzle_1 = require("./sudokuPuzzle");
 const sudokuXPuzzle_1 = require("./sudokuXPuzzle");
 /**
- * Static class to instantiate any puzzle from a {@link PuzzleDescription | puzzle description}.
+ * Static class to instantiate any puzzle from a {@link IPuzzleDefinition | puzzle definition}.
  * @internal
  */
 class AnyPuzzle {

package/lib/packlets/puzzles/index.d.ts

@@ -1,6 +1,8 @@
-import { AnyPuzzle as Any } from './anyPuzzle';
 import { KillerSudokuPuzzle as Killer } from './killerSudokuPuzzle';
 import { SudokuPuzzle as Sudoku } from './sudokuPuzzle';
 import { SudokuXPuzzle as SudokuX } from './sudokuXPuzzle';
-export { Any, Killer, Sudoku, SudokuX };
+import { KillerCombinations } from './killerCombinations';
+import { AnyPuzzle as Any } from './anyPuzzle';
+export * from './killerCombinationsTypes';
+export { Any, Killer, KillerCombinations, Sudoku, SudokuX };
 //# sourceMappingURL=index.d.ts.map