@fgv/ts-sudoku-lib 5.0.0-24 → 5.0.0-25

package/dist/ts-sudoku-lib.d.ts

@@ -0,0 +1,763 @@
+import { Brand } from '@fgv/ts-utils';
+import { Converter } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * All supported public types.
+ * @public
+ */
+export declare const allPuzzleTypes: PuzzleType[];
+
+/**
+ * Static class to instantiate any puzzle from a {@link PuzzleDescription | puzzle description}.
+ * @internal
+ */
+declare class AnyPuzzle {
+    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+}
+
+/**
+ * @internal
+ */
+export declare class Cage implements ICage {
+    readonly id: CageId;
+    readonly cageType: CageType;
+    readonly total: number;
+    protected readonly _cellIds: CellId[];
+    private _values;
+    private constructor();
+    get cellIds(): CellId[];
+    get numCells(): number;
+    static create(id: CageId, type: CageType, total: number, cells: CellId[]): Result<Cage>;
+    containsCell(id: CellId): boolean;
+    containsValue(value: number, state: PuzzleState, ignore?: CellId[]): boolean;
+    containedValues(state: PuzzleState): Set<number>;
+    toString(state?: PuzzleState): string;
+}
+
+/**
+ * Nominal identifier for a single {@Link ICage | cage} in a {@link PuzzleSession | puzzle}.
+ * @public
+ */
+export declare type CageId = Brand<string, 'CageId'>;
+
+/**
+ * Converts an arbitrary value to a {@link CageId | CageId}.
+ * @public
+ */
+declare const cageId: Converter<CageId>;
+
+/**
+ * Identifies the type of a {@Link ICage | cage}.
+ * @public
+ */
+export declare type CageType = 'row' | 'column' | 'section' | 'x' | 'killer';
+
+/**
+ * @internal
+ */
+export declare class Cell implements ICellInit, ICell {
+    readonly id: CellId;
+    readonly row: number;
+    readonly col: number;
+    readonly cages: readonly Cage[];
+    readonly immutable: boolean;
+    readonly immutableValue?: number;
+    constructor(init: ICellInit, cages: readonly Cage[]);
+    isValid(state: PuzzleState): boolean;
+    hasValue(state: PuzzleState): boolean;
+    isValidValue(value: number | undefined, state: PuzzleState): boolean;
+    update(value: number | undefined, notes: number[]): Result<ICellState>;
+    updateValue(value: number | undefined, state: PuzzleState): Result<ICellState>;
+    updateNotes(notes: number[], state: PuzzleState): Result<ICellState>;
+    toString(state?: PuzzleState): string;
+}
+
+/**
+ * Nominal identifier for a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
+ * @public
+ */
+export declare type CellId = Brand<string, 'CellId'>;
+
+/**
+ * Converts an arbitrary value to a {@link CellId | CellId}.
+ * @public
+ */
+declare const cellId: Converter<CellId>;
+
+declare namespace Converters {
+    export {
+        cageId,
+        cellId,
+        puzzleType,
+        puzzleDescription
+    }
+}
+export { Converters }
+
+declare namespace Converters_2 {
+    export {
+        loadJsonPuzzlesFileSync,
+        puzzlesFile
+    }
+}
+
+declare namespace File_2 {
+    export {
+        Converters_2 as Converters,
+        Model
+    }
+}
+export { File_2 as File }
+
+/**
+ * Describes the structure of a single cage in a {@link PuzzleSession | puzzle}.
+ * Does not describe state.
+ * @public
+ */
+export declare interface ICage {
+    /**
+     * Unique identifier for the cage.
+     */
+    readonly id: CageId;
+    /**
+     * The {@link CageType | type} of the cage.
+     */
+    readonly cageType: CageType;
+    /**
+     * The expected sum of all cells in the cage.
+     */
+    readonly total: number;
+    /**
+     * The number of cells in the cage.
+     */
+    readonly numCells: number;
+    /**
+     * The identity of each cell in the cage.
+     */
+    readonly cellIds: CellId[];
+    /**
+     * Determines if a supplied cell is present in the cage.
+     * @param id - the identifier to be searched.
+     */
+    containsCell(id: CellId): boolean;
+}
+
+/**
+ * Describes the structure of a single cell in a {@link PuzzleSession | puzzle}.
+ * Does not describe state.
+ * @public
+ */
+export declare interface ICell {
+    /**
+     * Unique identifier for the cell.
+     */
+    readonly id: CellId;
+    /**
+     * Row number of the cell.
+     */
+    readonly row: number;
+    /**
+     * Column number of the cell.
+     */
+    readonly col: number;
+    /**
+     * All of the {@Link ICage | cages} to which this cell belongs.
+     */
+    readonly cages: readonly ICage[];
+    /**
+     * Indicates whether this cell is a given value (immutable).
+     */
+    readonly immutable: boolean;
+    /**
+     * Given value of this cell, or `undefined` if the cell is not immutable.
+     */
+    readonly immutableValue?: number;
+}
+
+/**
+ * The contents of a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
+ * @public
+ */
+export declare interface ICellContents {
+    /**
+     * The value of the {@link ICell | cell}, or `undefined` if no value has been assigned.
+     */
+    readonly value?: number;
+    /**
+     * Any notes associated with the {@link ICell | cell}.
+     */
+    readonly notes: number[];
+}
+
+/**
+ * @internal
+ */
+export declare interface ICellInit {
+    readonly id: CellId;
+    readonly row: number;
+    readonly col: number;
+    readonly immutableValue?: number;
+}
+
+/**
+ * Describes the state of or a state update for a single {@link ICell |cell} in a
+ * {@link PuzzleSession | puzzle}.
+ * @public
+ */
+export declare interface ICellState extends ICellContents {
+    readonly id: CellId;
+}
+
+/**
+ * @internal
+ */
+export declare interface ICellUpdate {
+    from: ICellState;
+    to: ICellState;
+}
+
+/**
+ * @public
+ */
+export declare class Ids {
+    static cageId(from: string | ICage): Result<CageId>;
+    static cellId(spec: string | IRowColumn | ICell): Result<CellId>;
+    static rowCageId(row: number): CageId;
+    static columnCageId(col: number): CageId;
+    static sectionCageId(row: number, col: number): CageId;
+    static cellIds(firstRow: number, numRows: number, firstCol: number, numCols: number): Result<CellId[]>;
+}
+
+/**
+ * Description of a single puzzle.
+ * @public
+ */
+export declare interface IPuzzleDescription {
+    id?: string;
+    description: string;
+    type: PuzzleType;
+    level: number;
+    rows: number;
+    cols: number;
+    cells: string;
+}
+
+/**
+ * Parsed file containing a collection of puzzles.
+ * @public
+ */
+declare interface IPuzzlesFile {
+    puzzles: IPuzzleDescription[];
+}
+
+declare interface IPuzzleStep {
+    updates: ICellUpdate[];
+}
+
+/**
+ * @internal
+ */
+export declare interface IPuzzleUpdate {
+    from: PuzzleState;
+    to: PuzzleState;
+    cells: ICellUpdate[];
+}
+
+/**
+ * The row/column coordinate of a single {@Link ICell | cell} in a {@link PuzzleSession | puzzle}.
+ * @public
+ */
+export declare interface IRowColumn {
+    row: number;
+    col: number;
+}
+
+/**
+ * @public
+ */
+declare class KillerSudokuPuzzle extends Puzzle {
+    private constructor();
+    static create(desc: IPuzzleDescription): Result<Puzzle>;
+    private static _getKillerCages;
+    private static _getCageCells;
+    private static _getCages;
+    private static _getKillerCells;
+}
+
+/**
+ * Loads an arbitrary JSON file and parses it to return a validated
+ * {@link File.Model.IPuzzlesFile | IPuzzlesFile}.
+ * @param path - String path to the file
+ * @returns `Success` with the resulting file, or `Failure` with details if an
+ * error occurs.
+ * @public
+ */
+declare function loadJsonPuzzlesFileSync(path: string): Result<IPuzzlesFile>;
+
+declare namespace Model {
+    export {
+        IPuzzlesFile
+    }
+}
+
+/**
+ * Navigation direction within a puzzle.
+ * @public
+ *
+ */
+export declare type NavigationDirection = 'down' | 'left' | 'right' | 'up';
+
+/**
+ * Wrapping rules when navigating within a puzzle.
+ * @public
+ */
+export declare type NavigationWrap = 'none' | 'wrap-around' | 'wrap-next';
+
+/**
+ * @internal
+ */
+export declare class Puzzle {
+    readonly id?: string;
+    readonly description: string;
+    readonly initialState: PuzzleState;
+    /**
+     * @internal
+     */
+    protected readonly _rows: Map<CageId, Cage>;
+    /**
+     * @internal
+     */
+    protected readonly _columns: Map<CageId, Cage>;
+    /**
+     * @internal
+     */
+    protected readonly _sections: Map<CageId, Cage>;
+    /**
+     * @internal
+     */
+    protected readonly _cages: Map<CageId, Cage>;
+    /**
+     * @internal
+     */
+    protected readonly _cells: Map<CellId, Cell>;
+    /**
+     * Constructs a new puzzle state.
+     * @param puzzle - {@Link IPuzzleDescription | Puzzle description} from which this puzzle state
+     * is to be initialized.
+     */
+    protected constructor(puzzle: IPuzzleDescription, extraCages?: [CageId, Cage][]);
+    get numRows(): number;
+    get numColumns(): number;
+    get rows(): Cage[];
+    get cols(): Cage[];
+    get sections(): Cage[];
+    get cages(): Cage[];
+    get cells(): Cell[];
+    /**
+     * @internal
+     */
+    protected static _createRowCages(numRows: number, numCols: number): Result<[CageId, Cage][]>;
+    /**
+     * @internal
+     */
+    protected static _createColumnCages(numRows: number, numCols: number): Result<[CageId, Cage][]>;
+    /**
+     * @internal
+     */
+    private static _createSectionCages;
+    checkIsSolved(state: PuzzleState): boolean;
+    checkIsValid(state: PuzzleState): boolean;
+    getEmptyCells(state: PuzzleState): Cell[];
+    getInvalidCells(state: PuzzleState): Cell[];
+    getCellContents(spec: string | IRowColumn, state: PuzzleState): Result<{
+        cell: Cell;
+        contents: ICellContents;
+    }>;
+    getCell(spec: string | IRowColumn | ICell): Result<Cell>;
+    getCellNeighbor(spec: string | IRowColumn | ICell, direction: NavigationDirection, wrap: NavigationWrap): Result<ICell>;
+    updateContents(wantUpdates: ICellState[] | ICellState, state: PuzzleState): Result<IPuzzleUpdate>;
+    updateValues(wantUpdates: ICellState[] | ICellState, state: PuzzleState): Result<IPuzzleUpdate>;
+    updateNotes(wantUpdates: ICellState[] | ICellState, state: PuzzleState): Result<IPuzzleUpdate>;
+    updateCellValue(want: string | IRowColumn, value: number | undefined, state: PuzzleState): Result<IPuzzleUpdate>;
+    updateCellNotes(want: string | IRowColumn, notes: number[], state: PuzzleState): Result<IPuzzleUpdate>;
+    getRow(row: CageId | number): Result<Cage>;
+    getColumn(col: CageId | number): Result<Cage>;
+    getSection(spec: CageId | IRowColumn): Result<Cage>;
+    getCage(id: CageId): Result<Cage>;
+    toStrings(state: PuzzleState): string[];
+    toString(state: PuzzleState): string;
+    private _moveColumn;
+    private _moveRow;
+}
+
+/**
+ * A collection of puzzles of various types.
+ * @public
+ */
+export declare class PuzzleCollection {
+    /**
+     * All puzzles in the collection.
+     */
+    readonly puzzles: readonly IPuzzleDescription[];
+    private readonly _byId;
+    private constructor();
+    /**
+     * Creates a new puzzle from a loaded {@link File.Model.IPuzzlesFile | PuzzlesFile}
+     * @param from - The {@link File.Model.IPuzzlesFile | puzzles file} to be loaded.
+     * @returns `Success` with the resulting {@link PuzzleCollection | PuzzleCollection}
+     * or `Failure` with details if an error occurs.
+     */
+    static create(from: File_2.Model.IPuzzlesFile): Result<PuzzleCollection>;
+    /**
+     * Creates a new puzzle from a JSON file.
+     * @param path - path to the JSON file to be loaded.
+     * @returns `Success` with the resulting {@link PuzzleCollection | PuzzleCollection}
+     * or `Failure` with details if an error occurs.
+     */
+    static load(path: string): Result<PuzzleCollection>;
+    /**
+     * Gets a puzzle by id from this collection.
+     * @param id - The string ID of the puzzle to be returned.
+     * @returns `Success` with the requested {@link PuzzleSession | puzzle}, or
+     * `Failure` with details if an error occurs.
+     */
+    getPuzzle(id: string): Result<PuzzleSession>;
+    /**
+     * Gets a puzzle by id from this collection.
+     * @param id - The string ID of the puzzle to be returned.
+     * @returns `Success` with the requested {@link PuzzleSession | puzzle}, or
+     * `Failure` with details if an error occurs.
+     */
+    getDescription(id: string): Result<IPuzzleDescription>;
+}
+
+/**
+ * Get well-known {@link PuzzleCollection | puzzle collections}.
+ * @public
+ */
+export declare class PuzzleCollections {
+    private static _default;
+    /**
+     * The default {@link PuzzleCollection | puzzle collection}.
+     */
+    static get default(): PuzzleCollection;
+}
+
+/**
+ * Converts an arbitrary object to a {@link IPuzzleDescription | IPuzzleDescription}.
+ * @public
+ */
+declare const puzzleDescription: Converter<IPuzzleDescription>;
+
+declare namespace Puzzles {
+    export {
+        AnyPuzzle as Any,
+        KillerSudokuPuzzle as Killer,
+        SudokuPuzzle as Sudoku,
+        SudokuXPuzzle as SudokuX
+    }
+}
+export { Puzzles }
+
+/**
+ * Represents a single puzzle session, including puzzle, current state and redo/undo.
+ * @public
+ */
+export declare class PuzzleSession {
+    /**
+     * The current {@link PuzzleState | state} of this puzzle session.
+     */
+    state: PuzzleState;
+    protected readonly _puzzle: Puzzle;
+    protected _nextStep: number;
+    protected _numSteps: number;
+    protected _steps: IPuzzleStep[];
+    /**
+     * @internal
+     */
+    protected constructor(puzzle: Puzzle);
+    /**
+     * ID of the puzzle being solved.
+     */
+    get id(): string | undefined;
+    /**
+     * Description of the puzzle being solved.
+     */
+    get description(): string;
+    /**
+     * Number of rows in the puzzle being solved.
+     */
+    get numRows(): number;
+    /**
+     * Number of columns in the puzzle being solved.
+     */
+    get numColumns(): number;
+    /**
+     * The row {@link ICage | cages} in the puzzle being solved.
+     */
+    get rows(): ICage[];
+    /**
+     * The column {@link ICage | cages} in the puzzle being solved.
+     */
+    get cols(): ICage[];
+    /**
+     * The section {@link ICage | cages} in the puzzle being solved.
+     */
+    get sections(): ICage[];
+    /**
+     * All {@link ICage | cages} in the puzzle being solved.
+     */
+    get cages(): ICage[];
+    /**
+     * The cells {@link ICell | cells} in the puzzle being solved.
+     */
+    get cells(): ICell[];
+    /**
+     * Index of the next step in this puzzle session.
+     */
+    get nextStep(): number;
+    /**
+     * Number of steps currently elapsed in this puzzle session.  Note
+     * that after undo, `nextStep` will be less than `numSteps`.
+     */
+    get numSteps(): number;
+    /***
+     * Indicates whether undo is currently possible.
+     */
+    get canUndo(): boolean;
+    /**
+     * Indicates whether redo is currently possible.
+     */
+    get canRedo(): boolean;
+    /**
+     * 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: Puzzle): Result<PuzzleSession>;
+    /**
+     * Determines if the puzzle is correctly solved.
+     * @returns `true` if the puzzle is solved, `false` if the puzzle has
+     * empty or invalid cells.
+     */
+    checkIsSolved(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * Gets all of the currently empty {@link ICell | cells} in the puzzle.
+     * @returns An array of {@link ICell | ICell} with all empty cells.
+     */
+    getEmptyCells(): ICell[];
+    /**
+     * Gets all of the currently invalid {@link ICell | cells} in the puzzle.
+     * @returns An array of {@link ICell | ICell} with all invalid cells.
+     */
+    getInvalidCells(): ICell[];
+    /**
+     * 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: string | IRowColumn | ICell): boolean;
+    /**
+     * 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: string | IRowColumn | ICell): boolean;
+    /**
+     * 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: string | IRowColumn | ICell, value: number): boolean;
+    /**
+     * 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: string | IRowColumn | ICell, direction: NavigationDirection, wrap: NavigationWrap): Result<ICell>;
+    /**
+     * 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: string | IRowColumn): Result<{
+        cell: ICell;
+        contents: ICellContents;
+    }>;
+    /**
+     * 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: string | IRowColumn | ICell, value: number | undefined): Result<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: string | IRowColumn | ICell, notes: number[]): Result<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: ICellState[]): Result<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: string | ICage, value: number): boolean;
+    /**
+     * 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: string | ICage): Set<number>;
+    /**
+     * 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(): Result<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(): Result<this>;
+    /**
+     * Gets a string representation of this puzzle, one string
+     * per row.
+     */
+    toStrings(): string[];
+    private _addMove;
+    private _cage;
+    private _cell;
+}
+
+/**
+ * Converts an arbitrary object to a {@link File.Model.IPuzzlesFile | IPuzzlesFile}.
+ * @public
+ */
+declare const puzzlesFile: Converter<IPuzzlesFile>;
+
+/**
+ * @public
+ */
+export declare class PuzzleState {
+    /**
+     * @internal
+     */
+    protected readonly _cells: Map<CellId, ICellContents>;
+    /**
+     * @internal
+     */
+    protected constructor(from: Map<CellId, ICellContents>, updates?: ICellState[]);
+    /**
+     * Constructs a new {@link PuzzleState | PuzzleState}.
+     * @param cells - An array of {@link ICellState | CellState} used to initialize the state.
+     * @returns The new {@link PuzzleState | PuzzleState}.
+     */
+    static create(cells: ICellState[]): Result<PuzzleState>;
+    /**
+     * Convert {@link ICellContents | CellContents} to `[`{@link CellId | CellId}`,` {@link ICellContents | CellContents}`]`
+     * tuple for `Map` construction.
+     * @param states - An array of {@link ICellContents | CellContents} to be converted.
+     * @returns The corresponding array of `[`{@link CellId | CellId}`,` {@link ICellContents | CellContents}`]`
+     * @internal
+     */
+    protected static _toEntries(states?: ICellState[]): [CellId, ICellContents][];
+    /**
+     * Gets the contents of a cell specified by {@link CellId | id}.
+     * @param id - The {@link CellId | id} of the cell to be retrieved.
+     * @returns A {@link ICellContents | CellContents} with the contents of
+     * the requested cell.
+     */
+    getCellContents(id: CellId): Result<ICellContents>;
+    /**
+     * Determines if some cell has an assigned value.
+     * @param id - The {@link CellId | id} of the cell to be tested.
+     * @returns `true` if the cell has a value, `false` if the cell
+     * is empty or invalid.
+     */
+    hasValue(id: CellId): boolean;
+    /**
+     * Creates a new {@link PuzzleState | PuzzleState} which corresponds
+     * to this state with updates applied.
+     * @param updates - An array of {@link ICellState | CellState} to be
+     * applied.
+     * @returns A new {@link PuzzleState} with updates applied.
+     */
+    update(updates: ICellState[]): Result<PuzzleState>;
+}
+
+/**
+ * Describes the rules that apply to the puzzle.
+ * @public
+ */
+export declare type PuzzleType = 'killer-sudoku' | 'sudoku' | 'sudoku-x';
+
+/**
+ * Converts an arbitrary value to a {@link PuzzleType | PuzzleType}.
+ * @public
+ */
+declare const puzzleType: Converter<PuzzleType, ReadonlyArray<PuzzleType>>;
+
+/**
+ * @public
+ */
+declare class SudokuPuzzle extends Puzzle {
+    private constructor();
+    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+}
+
+/**
+ * @public
+ */
+declare class SudokuXPuzzle extends Puzzle {
+    private constructor();
+    static create(puzzle: IPuzzleDescription): Result<Puzzle>;
+    private static _getXCages;
+}
+
+/**
+ * The minimum and maximum possible values for a {@link ICage | cage}, by cage size in
+ * {@link ICell | cells}.
+ * @public
+ */
+export declare const totalsByCageSize: readonly {
+    min: number;
+    max: number;
+}[];
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.52.10"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-sudoku-lib",
-  "version": "5.0.0-24",
+  "version": "5.0.0-25",
   "description": "Sudoku rules library",
   "main": "lib/index.js",
   "types": "dist/ts-sudoku-lib.d.ts",
@@ -43,12 +43,12 @@
     "@rushstack/eslint-config": "4.4.0",
     "@rushstack/heft-jest-plugin": "0.16.12",
     "eslint-plugin-tsdoc": "~0.4.0",
-    "@fgv/ts-utils": "5.0.0-24",
-    "@fgv/ts-json-base": "5.0.0-24",
-    "@fgv/ts-utils-jest": "5.0.0-24"
+    "@fgv/ts-utils-jest": "5.0.0-25",
+    "@fgv/ts-utils": "5.0.0-25",
+    "@fgv/ts-json-base": "5.0.0-25"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.0.0-24"
+    "@fgv/ts-utils": "5.0.0-25"
   },
   "scripts": {
     "build": "heft build --clean",

package/config/api-extractor.json

@@ -1,343 +0,0 @@
-/**
- * Config file for API Extractor.  For more info, please visit: https://api-extractor.com
- */
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
-  /**
-   * Optionally specifies another JSON config file that this file extends from.  This provides a way for
-   * standard settings to be shared across multiple projects.
-   *
-   * If the path starts with "./" or "../", the path is resolved relative to the folder of the file that contains
-   * the "extends" field.  Otherwise, the first path segment is interpreted as an NPM package name, and will be
-   * resolved using NodeJS require().
-   *
-   * SUPPORTED TOKENS: none
-   * DEFAULT VALUE: ""
-   */
-  // "extends": "./shared/api-extractor-base.json"
-  // "extends": "my-package/include/api-extractor-base.json"
-  /**
-   * Determines the "<projectFolder>" token that can be used with other config file settings.  The project folder
-   * typically contains the tsconfig.json and package.json config files, but the path is user-defined.
-   *
-   * The path is resolved relative to the folder of the config file that contains the setting.
-   *
-   * The default value for "projectFolder" is the token "<lookup>", which means the folder is determined by traversing
-   * parent folders, starting from the folder containing api-extractor.json, and stopping at the first folder
-   * that contains a tsconfig.json file.  If a tsconfig.json file cannot be found in this way, then an error
-   * will be reported.
-   *
-   * SUPPORTED TOKENS: <lookup>
-   * DEFAULT VALUE: "<lookup>"
-   */
-  "projectFolder": "..",
-  /**
-   * (REQUIRED) Specifies the .d.ts file to be used as the starting point for analysis.  API Extractor
-   * analyzes the symbols exported by this module.
-   *
-   * The file extension must be ".d.ts" and not ".ts".
-   *
-   * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-   * prepend a folder token such as "<projectFolder>".
-   *
-   * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-   */
-  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
-  /**
-   * A list of NPM package names whose exports should be treated as part of this package.
-   *
-   * For example, suppose that Webpack is used to generate a distributed bundle for the project "library1",
-   * and another NPM package "library2" is embedded in this bundle.  Some types from library2 may become part
-   * of the exported API for library1, but by default API Extractor would generate a .d.ts rollup that explicitly
-   * imports library2.  To avoid this, we can specify:
-   *
-   *   "bundledPackages": [ "library2" ],
-   *
-   * This would direct API Extractor to embed those types directly in the .d.ts rollup, as if they had been
-   * local files for library1.
-   */
-  "bundledPackages": [],
-  /**
-   * Determines how the TypeScript compiler engine will be invoked by API Extractor.
-   */
-  "compiler": {
-    /**
-     * Specifies the path to the tsconfig.json file to be used by API Extractor when analyzing the project.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * Note: This setting will be ignored if "overrideTsconfig" is used.
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/tsconfig.json"
-     */
-    // "tsconfigFilePath": "<projectFolder>/tsconfig.json",
-    /**
-     * Provides a compiler configuration that will be used instead of reading the tsconfig.json file from disk.
-     * The object must conform to the TypeScript tsconfig schema:
-     *
-     * http://json.schemastore.org/tsconfig
-     *
-     * If omitted, then the tsconfig.json file will be read from the "projectFolder".
-     *
-     * DEFAULT VALUE: no overrideTsconfig section
-     */
-    // "overrideTsconfig": {
-    //   . . .
-    // }
-    /**
-     * This option causes the compiler to be invoked with the --skipLibCheck option. This option is not recommended
-     * and may cause API Extractor to produce incomplete or incorrect declarations, but it may be required when
-     * dependencies contain declarations that are incompatible with the TypeScript engine that API Extractor uses
-     * for its analysis.  Where possible, the underlying issue should be fixed rather than relying on skipLibCheck.
-     *
-     * DEFAULT VALUE: false
-     */
-    // "skipLibCheck": true,
-  },
-  /**
-   * Configures how the API report file (*.api.md) will be generated.
-   */
-  "apiReport": {
-    /**
-     * (REQUIRED) Whether to generate an API report.
-     */
-    "enabled": true
-    /**
-     * The filename for the API report files.  It will be combined with "reportFolder" or "reportTempFolder" to produce
-     * a full file path.
-     *
-     * The file extension should be ".api.md", and the string should not contain a path separator such as "\" or "/".
-     *
-     * SUPPORTED TOKENS: <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<unscopedPackageName>.api.md"
-     */
-    // "reportFileName": "<unscopedPackageName>.api.md",
-    /**
-     * Specifies the folder where the API report file is written.  The file name portion is determined by
-     * the "reportFileName" setting.
-     *
-     * The API report file is normally tracked by Git.  Changes to it can be used to trigger a branch policy,
-     * e.g. for an API review.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/etc/"
-     */
-    // "reportFolder": "<projectFolder>/etc/",
-    /**
-     * Specifies the folder where the temporary report file is written.  The file name portion is determined by
-     * the "reportFileName" setting.
-     *
-     * After the temporary file is written to disk, it is compared with the file in the "reportFolder".
-     * If they are different, a production build will fail.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/temp/"
-     */
-    // "reportTempFolder": "<projectFolder>/temp/"
-  },
-  /**
-   * Configures how the doc model file (*.api.json) will be generated.
-   */
-  "docModel": {
-    /**
-     * (REQUIRED) Whether to generate a doc model file.
-     */
-    "enabled": true
-    /**
-     * The output path for the doc model file.  The file extension should be ".api.json".
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/temp/<unscopedPackageName>.api.json"
-     */
-    // "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
-  },
-  /**
-   * Configures how the .d.ts rollup file will be generated.
-   */
-  "dtsRollup": {
-    /**
-     * (REQUIRED) Whether to generate the .d.ts rollup file.
-     */
-    "enabled": true
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated without any trimming.
-     * This file will include all declarations that are exported by the main entry point.
-     *
-     * If the path is an empty string, then this file will not be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<projectFolder>/dist/<unscopedPackageName>.d.ts"
-     */
-    // "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts",
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "beta" release.
-     * This file will include only declarations that are marked as "@public" or "@beta".
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: ""
-     */
-    // "betaTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-beta.d.ts",
-    /**
-     * Specifies the output path for a .d.ts rollup file to be generated with trimming for a "public" release.
-     * This file will include only declarations that are marked as "@public".
-     *
-     * If the path is an empty string, then this file will not be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: ""
-     */
-    // "publicTrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>-public.d.ts",
-    /**
-     * When a declaration is trimmed, by default it will be replaced by a code comment such as
-     * "Excluded from this release type: exampleMember".  Set "omitTrimmingComments" to true to remove the
-     * declaration completely.
-     *
-     * DEFAULT VALUE: false
-     */
-    // "omitTrimmingComments": true
-  },
-  /**
-   * Configures how the tsdoc-metadata.json file will be generated.
-   */
-  "tsdocMetadata": {
-    /**
-     * Whether to generate the tsdoc-metadata.json file.
-     *
-     * DEFAULT VALUE: true
-     */
-    // "enabled": true,
-    /**
-     * Specifies where the TSDoc metadata file should be written.
-     *
-     * The path is resolved relative to the folder of the config file that contains the setting; to change this,
-     * prepend a folder token such as "<projectFolder>".
-     *
-     * The default value is "<lookup>", which causes the path to be automatically inferred from the "tsdocMetadata",
-     * "typings" or "main" fields of the project's package.json.  If none of these fields are set, the lookup
-     * falls back to "tsdoc-metadata.json" in the package folder.
-     *
-     * SUPPORTED TOKENS: <projectFolder>, <packageName>, <unscopedPackageName>
-     * DEFAULT VALUE: "<lookup>"
-     */
-    // "tsdocMetadataFilePath": "<projectFolder>/dist/tsdoc-metadata.json"
-  },
-  /**
-   * Specifies what type of newlines API Extractor should use when writing output files.  By default, the output files
-   * will be written with Windows-style newlines.  To use POSIX-style newlines, specify "lf" instead.
-   * To use the OS's default newline kind, specify "os".
-   *
-   * DEFAULT VALUE: "crlf"
-   */
-  // "newlineKind": "crlf",
-  /**
-   * Configures how API Extractor reports error and warning messages produced during analysis.
-   *
-   * There are three sources of messages:  compiler messages, API Extractor messages, and TSDoc messages.
-   */
-  "messages": {
-    /**
-     * Configures handling of diagnostic messages reported by the TypeScript compiler engine while analyzing
-     * the input .d.ts files.
-     *
-     * TypeScript message identifiers start with "TS" followed by an integer.  For example: "TS2551"
-     *
-     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
-     */
-    "compilerMessageReporting": {
-      /**
-       * Configures the default routing for messages that don't match an explicit rule in this table.
-       */
-      "default": {
-        /**
-         * Specifies whether the message should be written to the the tool's output log.  Note that
-         * the "addToApiReportFile" property may supersede this option.
-         *
-         * Possible values: "error", "warning", "none"
-         *
-         * Errors cause the build to fail and return a nonzero exit code.  Warnings cause a production build fail
-         * and return a nonzero exit code.  For a non-production build (e.g. when "api-extractor run" includes
-         * the "--local" option), the warning is displayed but the build will not fail.
-         *
-         * DEFAULT VALUE: "warning"
-         */
-        "logLevel": "warning"
-        /**
-         * When addToApiReportFile is true:  If API Extractor is configured to write an API report file (.api.md),
-         * then the message will be written inside that file; otherwise, the message is instead logged according to
-         * the "logLevel" option.
-         *
-         * DEFAULT VALUE: false
-         */
-        // "addToApiReportFile": false
-      }
-      // "TS2551": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    },
-    /**
-     * Configures handling of messages reported by API Extractor during its analysis.
-     *
-     * API Extractor message identifiers start with "ae-".  For example: "ae-extra-release-tag"
-     *
-     * DEFAULT VALUE: See api-extractor-defaults.json for the complete table of extractorMessageReporting mappings
-     */
-    "extractorMessageReporting": {
-      "default": {
-        "logLevel": "warning"
-        // "addToApiReportFile": false
-      },
-      "ae-unresolved-link": {
-        "logLevel": "none",
-        "addToApiReportFile": true
-      }
-      // "ae-extra-release-tag": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    },
-    /**
-     * Configures handling of messages reported by the TSDoc parser when analyzing code comments.
-     *
-     * TSDoc message identifiers start with "tsdoc-".  For example: "tsdoc-link-tag-unescaped-text"
-     *
-     * DEFAULT VALUE:  A single "default" entry with logLevel=warning.
-     */
-    "tsdocMessageReporting": {
-      "default": {
-        "logLevel": "warning"
-        // "addToApiReportFile": false
-      }
-      // "tsdoc-link-tag-unescaped-text": {
-      //   "logLevel": "warning",
-      //   "addToApiReportFile": true
-      // },
-      //
-      // . . .
-    }
-  }
-}

package/config/rig.json

@@ -1,16 +0,0 @@
-// The "rig.json" file directs tools to look for their config files in an external package.
-// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
-{
-  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
-  /**
-   * (Required) The name of the rig package to inherit from.
-   * It should be an NPM package name with the "-rig" suffix.
-   */
-  "rigPackageName": "@rushstack/heft-node-rig"
-  /**
-   * (Optional) Selects a config profile from the rig package.  The name must consist of
-   * lowercase alphanumeric words separated by hyphens, for example "sample-profile".
-   * If omitted, then the "default" profile will be used."
-   */
-  // "rigProfile": "your-profile-name"
-}