kokopu
Version:
A JavaScript/TypeScript library implementing the chess game rules and providing tools to read/write the standard chess file formats.
340 lines (339 loc) • 13.9 kB
TypeScript
/*!
* -------------------------------------------------------------------------- *
* *
* Kokopu - A JavaScript/TypeScript chess library. *
* <https://www.npmjs.com/package/kokopu> *
* Copyright (C) 2018-2025 Yoann Le Montagner <yo35 -at- melix.net> *
* *
* Kokopu is free software: you can redistribute it and/or *
* modify it under the terms of the GNU Lesser General Public License *
* as published by the Free Software Foundation, either version 3 of *
* the License, or (at your option) any later version. *
* *
* Kokopu is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU Lesser General Public License for more details. *
* *
* You should have received a copy of the GNU Lesser General *
* Public License along with this program. If not, see *
* <http://www.gnu.org/licenses/>. *
* *
* -------------------------------------------------------------------------- */
import { Color, GameResult, GameVariant } from './base_types';
import { DateValue } from './date_value';
import { GamePOJO } from './game_pojo';
import { Node, Variation } from './node_variation';
import { Position } from './position';
/**
* Chess game, with the move history, the position at each step of the game, the comments and annotations (if any),
* the result of the game, and some meta-data such as the name of the players, the date of the game, the name of the tournament, etc...
*/
export declare class Game {
private _playerName;
private _playerElo;
private _playerTitle;
private _event?;
private _round;
private _date?;
private _site?;
private _annotator?;
private _eco?;
private _opening?;
private _openingVariation?;
private _openingSubVariation?;
private _termination?;
private _result;
private _moveTreeRoot;
constructor();
/**
* Clear all the headers (player names, elos, titles, event name, date, etc...).
*
* The {@link Game.result} header is reseted to its default value.
* The initial position and moves are not modified.
*/
clearHeaders(): void;
/**
* Get the name of the player corresponding to the given color.
*/
playerName(color: Color): string | undefined;
/**
* Set the name of the player corresponding to the given color.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
playerName(color: Color, value: string | undefined): void;
/**
* Get the elo of the player corresponding to the given color.
*
* If defined, the returned value is guaranteed to be an integer >= 0.
*/
playerElo(color: Color): number | undefined;
/**
* Set the elo of the player corresponding to the given color.
*
* @param value - If `undefined`, the existing value (if any) is erased. Must be an integer >= 0.
*/
playerElo(color: Color, value: number | undefined): void;
/**
* Get the title of the player corresponding to the given color.
*/
playerTitle(color: Color): string | undefined;
/**
* Set the title of the player corresponding to the given color.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
playerTitle(color: Color, value: string | undefined): void;
/**
* Get the event.
*/
event(): string | undefined;
/**
* Set the event.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
event(value: string | undefined): void;
/**
* Get the round.
*/
round(): number | undefined;
/**
* Set the round.
*
* @param value - If `undefined`, the existing value (if any) is erased. Must be an integer >= 0.
*/
round(value: number | undefined): void;
/**
* Get the sub-round.
*/
subRound(): number | undefined;
/**
* Set the sub-round.
*
* @param value - If `undefined`, the existing value (if any) is erased. Must be an integer >= 0.
*/
subRound(value: number | undefined): void;
/**
* Get the sub-sub-round.
*/
subSubRound(): number | undefined;
/**
* Set the sub-sub-round.
*
* @param value - If `undefined`, the existing value (if any) is erased. Must be an integer >= 0.
*/
subSubRound(value: number | undefined): void;
private _setRoundPart;
/**
* Get the round, sub-round and sub-sub-round as a human-readable string, the 3 components being separated by dot characters.
*/
fullRound(): string | undefined;
/**
* Get the date of the game.
*/
date(): DateValue | undefined;
/**
* Set the date of the game.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
date(value: DateValue | Date | undefined): void;
/**
* Set the date of the game.
*
* If the month and/or the day of month are missing, the date of the game will be partially defined
* (see {@link DateValue} for more details regarding partially defined dates).
*/
date(year: number, month?: number, day?: number): void;
/**
* Get the date of the game as a standard JavaScript `Date` object.
*
* If the day of month is undefined for the current game, the returned `Date` object points at the first day of the corresponding month.
* If neither the day of month nor the month are undefined for the current game, the returned `Date` object points at the first day of the corresponding year.
*/
dateAsDate(): Date | undefined;
/**
* Get the date of the game as a human-readable string (e.g. `'November 1955'`, `'September 4, 2021'`).
*
* @param locales - Locales to use to generate the result. If undefined, the default locale of the execution environment is used.
* See [Intl documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locale_identification_and_negotiation)
* for more details.
*/
dateAsString(locales?: string | string[] | undefined): string | undefined;
/**
* Get where the game takes place.
*/
site(): string | undefined;
/**
* Set where the game takes place.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
site(value: string | undefined): void;
/**
* Get the name of the annotator.
*/
annotator(): string | undefined;
/**
* Set the name of the annotator.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
annotator(value: string | undefined): void;
/**
* Get the [ECO code](https://en.wikipedia.org/wiki/List_of_chess_openings).
*/
eco(): string | undefined;
/**
* Set the [ECO code](https://en.wikipedia.org/wiki/List_of_chess_openings).
*
* @param value - If `undefined`, the existing value (if any) is erased. Must be a valid ECO code (from `'A00'` to `'E99'`).
*/
eco(value: string | undefined): void;
/**
* Get the name of the opening.
*/
opening(): string | undefined;
/**
* Set the name of the opening.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
opening(value: string | undefined): void;
/**
* Get the name of the opening variation.
*/
openingVariation(): string | undefined;
/**
* Set the name of the opening variation.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
openingVariation(value: string | undefined): void;
/**
* Get the name of the opening sub-variation.
*/
openingSubVariation(): string | undefined;
/**
* Set the name of the opening sub-variation.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
openingSubVariation(value: string | undefined): void;
/**
* Get the reason of the conclusion of the game. Examples of possible values:
*
* - `'normal'`: game terminated in a normal fashion,
* - `'time forfeit'`: loss due to losing player's failure to meet time control requirements,
* - `'adjudication'`: result due to third party adjudication process,
* - `'death'`: losing player called to greater things, one hopes,
* - `'emergency'`: game concluded due to unforeseen circumstances,
* - etc...
*
* This list is not exhaustive and any string is valid value for this field.
*/
termination(): string | undefined;
/**
* Set the name of the opening sub-variation.
*
* @param value - If `undefined`, the existing value (if any) is erased.
*/
termination(value: string | undefined): void;
/**
* Get the result of the game.
*/
result(): GameResult;
/**
* Set the result of the game.
*/
result(value: GameResult): void;
/**
* Get the chess game variant of the game.
*/
variant(): GameVariant;
/**
* Get the initial position of the game.
*/
initialPosition(): Position;
/**
* Set the initial position of the game.
*
* @param fullMoveNumber - 1 by default
*/
initialPosition(initialPosition: Position, fullMoveNumber?: number): void;
/**
* [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) representation of the chess position at the beginning of the game.
*
* The fifty-move clock and full-move number are set according to the move history in the string returned by this method.
*/
initialFEN(): string;
/**
* Full-move number at which the game starts.
*/
initialFullMoveNumber(): number;
/**
* Chess position at the end of the game.
*/
finalPosition(): Position;
/**
* [FEN](https://en.wikipedia.org/wiki/Forsyth%E2%80%93Edwards_Notation) representation of the chess position at the end of the game.
*
* The fifty-move clock and full-move number are set according to the move history in the string returned by this method.
*/
finalFEN(): string;
/**
* The main variation of the game.
*/
mainVariation(): Variation;
/**
* Return the nodes corresponding to the moves of the main variation.
*
* @param withSubVariations - If `true`, the nodes of the sub-variations are also included in the result.
*/
nodes(withSubVariations?: boolean): Node[];
/**
* Number of half-moves in the main variation.
*
* For instance, after `1.e4 e5 2.Nf3`, the number of half-moves if 3 (2 white moves + 1 black move).
*/
plyCount(): number;
/**
* Return the node or variation corresponding to the given ID (see {@link Node.id | Node.id} and {@link Variation.id | Variation.id}
* to retrieve the ID of a node or variation).
*
* For the main variation, IDs are built as follows:
* - `'start'` is the ID of the main variation,
* - `'3w'` is for instance the ID of the node whose {@link Node.fullMoveNumber} is 3 and {@link Node.moveColor} is white
* (i.e. the 3rd white move if the game starts from the usual initial position),
* - `'end'` is an alias corresponding to the last node in the main variation (or the main variation itself if it is empty).
*
* For sub-variations, IDs are built as in the following examples:
* - `'2b-v0-start'` is the ID of the sub-variation at index 0 on node `'2b'` (in the main variation),
* - `'5w-v3-11b'` is the ID of the node whose {@link Node.fullMoveNumber} is 11 and {@link Node.moveColor} is black within
* the sub-variation at index 3 on node `'5w'` (in the main variation),
* - `'5w-v3-end'` is an alias corresponding to the last node in this sub-variation (or the sub-variation itself if it is empty).
*
* @param allowAliases - If `true`, search `id` among both IDs and ID aliases. If `false`, search among IDs only.
* @returns `undefined` if the given ID does not correspond to an existing {@link Node} and {@link Variation}.
*/
findById(id: string, allowAliases?: boolean): Node | Variation | undefined;
/**
* Return the [POJO](https://en.wikipedia.org/wiki/Plain_old_Java_object) representation of the current {@link Game}.
* To be used for JSON serialization, deep cloning, etc...
*/
pojo(): GamePOJO;
/**
* Decode the [POJO](https://en.wikipedia.org/wiki/Plain_old_Java_object) passed in argument, assuming it follows the schema defined by {@link GamePOJO}.
*
* @throws {@link exception.InvalidPOJO} if the given object cannot be decoded, either because it does not follow the schema defined by {@link GamePOJO},
* or because it would result in an inconsistent game (e.g. if it contains some invalid moves).
*/
static fromPOJO(pojo: unknown): Game;
/**
* Return a human-readable string representing the game. This string is multi-line,
* and is intended to be displayed in a fixed-width font (similarly to an ASCII-art picture).
*/
ascii(): string;
}