pgn-manager 1.0.1 → 2.0.0

package/README.md

@@ -6,7 +6,6 @@ A powerful TypeScript/JavaScript library for managing chess PGN (Portable Game N
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![npm downloads](https://img.shields.io/npm/dm/pgn-manager.svg)](https://www.npmjs.com/package/pgn-manager)
-[![Coverage Status](https://coveralls.io/repos/github/username/pgn-manager/badge.svg?branch=main)](https://coveralls.io/github/username/pgn-manager?branch=main)
 
 
 ## Features ✨
@@ -58,14 +57,15 @@ const headers = manager.headers;
 
 ### Methods
 - `getMove(moveNumber: number)`: Get move by number
-- `getMoveNumber(move: Move)`: Get number for a move
-- `nextMove(move: Move)`: Get next move in the sequence
-- `previousMove(move: Move)`: Get previous move
-- `hasNextMove(move: Move)`: Check if move has a next move
+- `getMoveNumber(moveOrMoveId: Move | number)`: Get number for a move
+- `nextMove(moveOrMoveId: Move | number)`: Get next move in the sequence
+- `previousMove(moveOrMoveId: Move | number)`: Get previous move
+- `hasNextMove(moveOrMoveId: Move | number)`: Check if move has a next move
 - `getFirstMove()`: Get the first move of the game
 - `getLastMove()`: Get the last move of the game
-- `getMoveFen(move: Move)`: Get FEN position after move
-- `getParentRav(move: Move)`: Get parent variation for move
+- `getMoveFen(moveOrMoveId: Move | number)`: Get FEN position after move
+- `getParentRav(moveOrMoveId: Move | number)`: Get parent variation for move
+- `getMoveColor(moveOrMoveId: Move | number)`: Gets the color of the player who made the move ("w" for white or "b" for black)
 
 ## Examples 🎯
 

package/dist/index.d.ts

@@ -1,27 +1,134 @@
-import { ParsedPGN, Move, Rav, Header } from "pgn-parser";
+import { ShortMove } from "chess.js";
+import * as pgnParser from "pgn-parser";
+import type { ParsedPGN, Move, Rav, Header, Result } from "pgn-parser";
 export declare const FEN_START_POSITION = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
 export declare const FEN_EMPTY_POSITION = "8/8/8/8/8/8/8/8";
 declare class PGNManager {
+    /** The raw PGN string input */
     private rawPGN;
+    /** The parsed PGN game object */
     private game;
+    /** Array of moves in traversal order */
     private sortedMoves;
+    /** Map of moves to their FEN position strings */
     private moveFen;
+    /** Map of moves to their parent variations (or null for mainline) */
     private moveParent;
+    /** Map of variations to their parent moves */
     private ravParent;
+    /** Map of moves to the color of the player who made the move */
+    private moveColor;
+    /**
+     * Creates a new PGNManager instance
+     * @param pgn - The PGN string to parse and manage
+     */
     constructor(pgn: string);
+    /**
+     * Initializes the game traversal starting from the initial position
+     * @param game - The parsed PGN game object
+     */
     private dfOnGame;
+    /**
+     * Performs depth-first traversal of the game moves and variations
+     * @param move - The current move being processed
+     * @param parent - The parent RAV (variation) containing the move
+     * @param chessGame - The chess instance for the current position
+     */
     private dfsOnGame;
+    /**
+     * Gets the raw PGN string
+     * @returns The original PGN string
+     */
     get pgn(): string;
+    /**
+     * Gets the parsed PGN object
+     * @returns The parsed PGN game object
+     */
     get parsedPGN(): ParsedPGN;
+    /**
+     * Gets the game headers
+     * @returns Array of game headers
+     */
     get headers(): Array<Header>;
-    getMove: (moveNumber: number) => Move;
+    /**
+     * Gets a move by its number in the sequence
+     * @param moveNumber - The 1-based index of the move
+     * @returns The move object at the specified position
+     */
+    getMove: (moveNumber: number) => pgnParser.Move;
+    /**
+     * Gets the number of a move in the sequence
+     * @param move - The move object
+     * @returns The 1-based index of the move
+     */
     getMoveNumber: (move: Move) => number;
-    nextMove: (move: Move | undefined) => Move;
-    hasNextMove: (move: Move) => boolean;
-    previousMove: (move: Move) => Move | undefined;
-    getFirstMove: () => Move;
-    getLastMove: () => any;
-    getMoveFen: (move: Move) => string;
-    getParentRav: (move: Move) => Rav | null;
+    /**
+     * Gets the next move in the sequence
+     * @param moveOrId - The current move object or move number
+     * @returns The next move in the sequence
+     * @throws Error if there are no moves in the game
+     */
+    nextMove: (moveOrId: Move | number | undefined) => Move;
+    /**
+     * Checks if there is a next move available
+     * @param moveOrId - The current move object or move number
+     * @returns True if there is a next move, false otherwise
+     */
+    hasNextMove: (moveOrId: Move | number) => boolean;
+    /**
+     * Gets the previous move in the sequence
+     * @param moveOrId - The current move object or move number
+     * @returns The previous move or undefined if at the start
+     * @throws Error if there are no moves or if the move parameter is invalid
+     */
+    previousMove: (moveOrId: Move | number) => Move | undefined;
+    /**
+     * Gets the first move in the game
+     * @returns The first move
+     * @throws Error if there are no moves in the game
+     */
+    getFirstMove: () => pgnParser.Move;
+    /**
+     * Gets the last move in the game
+     * @returns The last move
+     * @throws Error if there are no moves in the game
+     */
+    getLastMove: () => pgnParser.Move;
+    /**
+     * Gets the FEN string for a specific move
+     * @param moveOrId - The move object or move number
+     * @returns The FEN string representing the position after the move
+     * @throws Error if the move parameter is invalid
+     */
+    getMoveFen: (moveOrId: Move | number) => string;
+    /**
+     * Gets the parent RAV (variation) for a move
+     * @param moveOrId - The move object or move number
+     * @returns The parent RAV or null if the move is in the main line
+     * @throws Error if the move parameter is invalid
+     */
+    getParentRav: (moveOrId: Move | number) => Rav | null;
+    /**
+     * Gets the color of the player who made the move
+     * @param moveOrId - The move object or move ID number
+     * @returns "w" for white or "b" for black
+     * @throws Error if the move parameter is invalid
+     */
+    getMoveColor: (moveOrId: Move | number) => "w" | "b";
+    /***
+     * Pushes a new move into the game
+     * @param moveId - The ID of the move to push
+     * @param newMove - The move object to add
+     * @param result - The result of the game after this move (default is "*")
+     * @returns The newly created move object
+     * @throws Error if the move parameter is invalid
+     */
+    pushMove: (moveId: number, newMove: ShortMove, result?: Result) => Move;
+    /**
+     * Delete a move and all subsequent moves in its variation from the game
+     * @param moveId - The ID of the move to delete from
+     * @throws Error if the move parameter is invalid
+     */
+    deleteMove: (moveId: number) => void;
 }
 export default PGNManager;

package/dist/index.js

@@ -3,25 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FEN_EMPTY_POSITION = exports.FEN_START_POSITION = void 0;
 const ChessJS = require("chess.js");
 const Chess = typeof ChessJS === "function" ? ChessJS : ChessJS.Chess;
-const pgn_parser_1 = require("pgn-parser");
+const pgnParser = require("pgn-parser");
+const utils_1 = require("./utils");
 exports.FEN_START_POSITION = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1";
 exports.FEN_EMPTY_POSITION = "8/8/8/8/8/8/8/8";
 class PGNManager {
+    /** The raw PGN string input */
     rawPGN;
+    /** The parsed PGN game object */
     game;
+    /** Array of moves in traversal order */
     sortedMoves;
+    /** Map of moves to their FEN position strings */
     moveFen;
+    /** Map of moves to their parent variations (or null for mainline) */
     moveParent;
+    /** Map of variations to their parent moves */
     ravParent;
+    /** Map of moves to the color of the player who made the move */
+    moveColor;
+    /**
+     * Creates a new PGNManager instance
+     * @param pgn - The PGN string to parse and manage
+     */
     constructor(pgn) {
         this.rawPGN = pgn;
-        this.game = pgn_parser_1.default.parse(pgn + " *")[0];
+        this.game = pgnParser.parse(pgn + " *")[0];
         this.sortedMoves = [];
         this.moveParent = new Map();
         this.ravParent = new Map();
         this.moveFen = new Map();
+        this.moveColor = new Map();
         this.dfOnGame(this.game);
     }
+    /**
+     * Initializes the game traversal starting from the initial position
+     * @param game - The parsed PGN game object
+     */
     dfOnGame = (game) => {
         this.sortedMoves = [];
         var chessGame = new Chess(exports.FEN_START_POSITION);
@@ -29,6 +47,12 @@ class PGNManager {
             this.dfsOnGame(move, game, chessGame);
         }
     };
+    /**
+     * Performs depth-first traversal of the game moves and variations
+     * @param move - The current move being processed
+     * @param parent - The parent RAV (variation) containing the move
+     * @param chessGame - The chess instance for the current position
+     */
     dfsOnGame = (move, parent, chessGame) => {
         this.sortedMoves.push(move);
         this.moveParent.set(move, parent);
@@ -46,26 +70,62 @@ class PGNManager {
             !chessGame.move(move.move, { sloppy: true }))
             console.log("Invalid move: " + move.move);
         this.moveFen.set(move, chessGame.fen());
+        this.moveColor.set(move, chessGame.turn() === "w" ? "b" : "w");
     };
+    /**
+     * Gets the raw PGN string
+     * @returns The original PGN string
+     */
     get pgn() {
         return this.rawPGN;
     }
+    /**
+     * Gets the parsed PGN object
+     * @returns The parsed PGN game object
+     */
     get parsedPGN() {
         return this.game;
     }
+    /**
+     * Gets the game headers
+     * @returns Array of game headers
+     */
     get headers() {
         if (!this.game || !this.game.headers)
             return [];
         return this.game.headers;
     }
+    /**
+     * Gets a move by its number in the sequence
+     * @param moveNumber - The 1-based index of the move
+     * @returns The move object at the specified position
+     */
     getMove = (moveNumber) => {
         let move = this.sortedMoves[moveNumber - 1];
         return move;
     };
+    /**
+     * Gets the number of a move in the sequence
+     * @param move - The move object
+     * @returns The 1-based index of the move
+     */
     getMoveNumber = (move) => {
         return this.sortedMoves.indexOf(move) + 1;
     };
-    nextMove = (move) => {
+    /**
+     * Gets the next move in the sequence
+     * @param moveOrId - The current move object or move number
+     * @returns The next move in the sequence
+     * @throws Error if there are no moves in the game
+     */
+    nextMove = (moveOrId) => {
+        let move;
+        if (typeof moveOrId === "number") {
+            move = this.getMove(moveOrId);
+        }
+        else {
+            move = moveOrId;
+        }
         if (!move) {
             if (this.sortedMoves.length == 0) {
                 throw Error("No moves in game");
@@ -92,10 +152,23 @@ class PGNManager {
         }
         return tempNextMove;
     };
-    hasNextMove = (move) => {
+    /**
+     * Checks if there is a next move available
+     * @param moveOrId - The current move object or move number
+     * @returns True if there is a next move, false otherwise
+     */
+    hasNextMove = (moveOrId) => {
+        const move = typeof moveOrId === "number" ? this.getMove(moveOrId) : moveOrId;
         return !move || this.nextMove(move) !== move;
     };
-    previousMove = (move) => {
+    /**
+     * Gets the previous move in the sequence
+     * @param moveOrId - The current move object or move number
+     * @returns The previous move or undefined if at the start
+     * @throws Error if there are no moves or if the move parameter is invalid
+     */
+    previousMove = (moveOrId) => {
+        const move = typeof moveOrId === "number" ? this.getMove(moveOrId) : moveOrId;
         if (!move) {
             if (this.sortedMoves.length == 0) {
                 throw Error("No moves in game");
@@ -122,31 +195,168 @@ class PGNManager {
         }
         return tempPrevMove;
     };
+    /**
+     * Gets the first move in the game
+     * @returns The first move
+     * @throws Error if there are no moves in the game
+     */
     getFirstMove = () => {
         if (this.sortedMoves.length == 0) {
             throw Error("No moves in game");
         }
         return this.sortedMoves[0];
     };
+    /**
+     * Gets the last move in the game
+     * @returns The last move
+     * @throws Error if there are no moves in the game
+     */
     getLastMove = () => {
         if (this.sortedMoves.length == 0) {
             throw Error("No moves in game");
         }
         return this.game.moves[this.game.moves.length - 1];
     };
-    getMoveFen = (move) => {
-        if (!move) {
+    /**
+     * Gets the FEN string for a specific move
+     * @param moveOrId - The move object or move number
+     * @returns The FEN string representing the position after the move
+     * @throws Error if the move parameter is invalid
+     */
+    getMoveFen = (moveOrId) => {
+        const move = typeof moveOrId === "number" ? this.getMove(moveOrId) : moveOrId;
+        if (!move || !this.moveFen.has(move)) {
             throw Error("Invalid 'move' parameter while getting fen");
         }
         let moveFen = this.moveFen.get(move);
         return moveFen ? moveFen : exports.FEN_EMPTY_POSITION;
     };
-    getParentRav = (move) => {
-        if (!move) {
+    /**
+     * Gets the parent RAV (variation) for a move
+     * @param moveOrId - The move object or move number
+     * @returns The parent RAV or null if the move is in the main line
+     * @throws Error if the move parameter is invalid
+     */
+    getParentRav = (moveOrId) => {
+        const move = typeof moveOrId === "number" ? this.getMove(moveOrId) : moveOrId;
+        if (!move || !this.moveParent.has(move)) {
             throw Error("Invalid 'move' parameter while getting parent rav");
         }
         let parentRav = this.moveParent.get(move);
         return parentRav ? parentRav : null;
     };
+    /**
+     * Gets the color of the player who made the move
+     * @param moveOrId - The move object or move ID number
+     * @returns "w" for white or "b" for black
+     * @throws Error if the move parameter is invalid
+     */
+    getMoveColor = (moveOrId) => {
+        const move = typeof moveOrId === "number" ? this.getMove(moveOrId) : moveOrId;
+        if (!move || !this.moveColor.has(move)) {
+            throw Error("Invalid 'move' parameter while getting move color");
+        }
+        return this.moveColor.get(move);
+    };
+    /***
+     * Pushes a new move into the game
+     * @param moveId - The ID of the move to push
+     * @param newMove - The move object to add
+     * @param result - The result of the game after this move (default is "*")
+     * @returns The newly created move object
+     * @throws Error if the move parameter is invalid
+     */
+    pushMove = (moveId, newMove, result = "*") => {
+        const currentMove = this.getMove(moveId);
+        // check if it's a valid move
+        const chess = new Chess(this.getMoveFen(currentMove));
+        if (!chess.move(newMove)) {
+            throw Error("Invalid move");
+        }
+        // check if this is a new variation
+        let isNewVariation = false;
+        const parentRav = this.getParentRav(currentMove);
+        if (parentRav.moves[parentRav.moves.length - 1] != currentMove) {
+            isNewVariation = true;
+        }
+        // add the move to the game
+        let move = undefined;
+        if (isNewVariation) {
+            move = {
+                move: chess.history().slice(-1)[0],
+                ravs: undefined,
+                move_number: currentMove.move_number,
+                comments: [],
+            };
+            const newVar = {
+                moves: [move],
+                result,
+            };
+            currentMove.ravs.push(newVar);
+            // update class variables
+            this.moveParent.set(move, newVar);
+            this.ravParent.set(newVar, currentMove);
+            this.moveFen.set(move, chess.fen());
+            this.moveColor.set(move, this.getMoveColor(currentMove));
+        }
+        else {
+            move = {
+                move: chess.history().slice(-1)[0],
+                ravs: undefined,
+                move_number: this.getMoveColor(currentMove) === "w"
+                    ? undefined
+                    : currentMove.move_number + 1,
+                comments: [],
+            };
+            parentRav.moves.push(move);
+            // update class variables
+            this.moveParent.set(move, parentRav);
+            this.moveFen.set(move, chess.fen());
+            this.moveColor.set(move, this.getMoveColor(currentMove) === "w" ? "b" : "w");
+        }
+        this.rawPGN = (0, utils_1.regeneratePGN)(this.game, this.moveColor);
+        this.dfOnGame(this.game);
+        return move;
+    };
+    /**
+     * Delete a move and all subsequent moves in its variation from the game
+     * @param moveId - The ID of the move to delete from
+     * @throws Error if the move parameter is invalid
+     */
+    deleteMove = (moveId) => {
+        const move = this.getMove(moveId);
+        if (!move) {
+            throw Error("Invalid move");
+        }
+        // delete the move and subsequent moves from the game
+        const parentRav = this.getParentRav(move);
+        const index = parentRav.moves.indexOf(move);
+        const deletedMoves = parentRav.moves.splice(index);
+        // collect all moves and variations that need cleanup
+        const movsToClean = [];
+        const ravsToClean = [];
+        for (const deletedMove of deletedMoves) {
+            movsToClean.push(deletedMove);
+            if (deletedMove.ravs) {
+                for (const rav of deletedMove.ravs) {
+                    ravsToClean.push(rav);
+                }
+            }
+        }
+        // Sort moves by their moveId in decreasing order
+        movsToClean.sort((a, b) => this.getMoveNumber(b) - this.getMoveNumber(a));
+        // clean up all maps at once
+        movsToClean.forEach((move) => {
+            this.moveParent.delete(move);
+            this.moveFen.delete(move);
+            this.moveColor.delete(move);
+        });
+        ravsToClean.forEach((rav) => {
+            this.ravParent.delete(rav);
+        });
+        // update the PGN and rebuild internal state
+        this.rawPGN = (0, utils_1.regeneratePGN)(this.game, this.moveColor);
+        this.dfOnGame(this.game);
+    };
 }
 exports.default = PGNManager;

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "pgn-manager",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "Libraray built on top of chess.js and pgn-parser to load and process PGN files in typescript.",
   "main": "dist/index",
   "typings": "dist/index",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
     "prepublishOnly": "npm run compile",
     "compile": "npm run clean && tsc -p .",
     "watch": "tsc -w -p .",
@@ -31,7 +33,12 @@
     "pgn-parser": "2.1.0"
   },
   "devDependencies": {
-    "typescript": "4.5.2"
+    "@types/chess.js": "^0.11.2",
+    "@types/jest": "^30.0.0",
+    "@types/pgn-parser": "^2.1.0",
+    "jest": "^30.0.4",
+    "ts-jest": "^29.4.0",
+    "typescript": "^5.8.3"
   },
   "files": [
     "dist/index.js",