pgn-manager 1.0.0 → 1.1.0

package/README.md

@@ -1 +1,101 @@
-# pgn-manager
+# PGN Manager 📦♟️
+
+A powerful TypeScript/JavaScript library for managing chess PGN (Portable Game Notation) files with support for variations and game traversal.
+
+[![NPM Package](https://img.shields.io/npm/v/pgn-manager.svg)](https://www.npmjs.com/package/pgn-manager)
+[![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)
+
+
+## Features ✨
+- Parse PGN strings into manageable objects
+- Navigate through main lines and variations
+- Access FEN positions for any move
+- Handle game headers
+- Traverse moves forward and backward
+- Full TypeScript support
+
+## Installation 🚀
+
+```console
+npm install pgn-manager
+```
+
+## Usage 💻
+
+```typescript
+import PGNManager from 'pgn-manager';
+
+// Initialize with a PGN string
+const pgn = `1. e4 e5 2. Nf3 Nc6 (2... d6 3. d4) 3. Bb5 *`;
+const manager = new PGNManager(pgn);
+
+// Get the first move
+const firstMove = manager.getFirstMove();
+
+// Navigate through moves
+const nextMove = manager.nextMove(firstMove);
+const prevMove = manager.previousMove(nextMove);
+
+// Get FEN position for a move
+const fen = manager.getMoveFen(firstMove);
+
+// Access game headers
+const headers = manager.headers;
+```
+
+## API Reference 📚
+
+### Constructor
+- `new PGNManager(pgn: string)`: Creates a new PGN manager instance
+
+### Properties
+- `pgn`: Get the raw PGN string
+- `parsedPGN`: Get the parsed PGN object
+- `headers`: Get game headers array
+
+### Methods
+- `getMove(moveNumber: number)`: Get move by number
+- `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(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 🎯
+
+### Traversing Main Line
+
+```typescript
+const manager = new PGNManager("1. e4 e5 2. Nf3 Nc6 3. Bb5 *");
+let move = manager.getFirstMove();
+
+while (manager.hasNextMove(move)) {
+  console.log(move.move);
+  move = manager.nextMove(move);
+}
+```
+
+### Working with Variations
+
+```typescript
+const manager = new PGNManager("1. e4 e5 2. Nf3 Nc6 (2... d6 3. d4) 3. Bb5 *");
+const move = manager.getMove(2); // Get second move
+const variation = manager.getParentRav(move);
+
+if (variation) {
+  console.log("Move is part of a variation!");
+}
+```
+
+## Contributing 🤝
+Contributions are welcome! Feel free to submit issues and pull requests.
+
+## License 📄
+MIT License - feel free to use this in your projects!

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.0",
+  "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",
@@ -18,9 +18,7 @@
   "keywords": [
     "Chess",
     "PGN",
-    "Portal",
-    "Game",
-    "Notation"
+    "Portal Game Notation"
   ],
   "author": "Harsh Kumar <hadron43@yahoo.com>",
   "license": "MIT",
@@ -28,9 +26,12 @@
     "url": "https://github.com/hadron43/pgn-manager/issues"
   },
   "homepage": "https://github.com/hadron43/pgn-manager#readme",
-  "devDependencies": {
+  "dependencies": {
     "chess.js": "0.12.0",
-    "pgn-parser": "2.1.0",
+    "pgn-parser": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/chess.js": "^0.11.2",
     "typescript": "4.5.2"
   },
   "files": [