pgn-manager 1.0.1 → 1.1.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,16 @@ 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
+- `getChessJSInstance(moveOrMoveId: Move | number)`: Get or create a ChessJS instance for the position after the specified 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

@@ -2,26 +2,116 @@ import { ParsedPGN, Move, Rav, Header } 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>;
+    /**
+     * 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) => 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;
+    /**
+     * 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: () => Move;
+    /**
+     * Gets the last move in the game
+     * @returns The last move
+     * @throws Error if there are no moves in the game
+     */
     getLastMove: () => any;
-    getMoveFen: (move: Move) => string;
-    getParentRav: (move: Move) => Rav | null;
+    /**
+     * 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";
 }
 export default PGNManager;

package/dist/index.js

@@ -7,12 +7,24 @@ const pgn_parser_1 = require("pgn-parser");
 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];
@@ -20,8 +32,13 @@ class PGNManager {
         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 +46,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 +69,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 +151,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 +194,68 @@ 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) => {
+    /**
+     * 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) {
             throw Error("Invalid 'move' parameter while getting fen");
         }
         let moveFen = this.moveFen.get(move);
         return moveFen ? moveFen : exports.FEN_EMPTY_POSITION;
     };
-    getParentRav = (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) {
             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) {
+            throw Error("Invalid 'move' parameter while getting move color");
+        }
+        return this.moveColor.get(move);
+    };
 }
 exports.default = PGNManager;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgn-manager",
-  "version": "1.0.1",
+  "version": "1.1.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",
@@ -31,6 +31,7 @@
     "pgn-parser": "2.1.0"
   },
   "devDependencies": {
+    "@types/chess.js": "^0.11.2",
     "typescript": "4.5.2"
   },
   "files": [