@echecs/pgn 3.1.3 → 3.5.1

package/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [3.5.1] - 2026-03-14
+
+### Changed
+
+- README: document `stream()` API with signature and Node.js usage example
+- README: update type names (`Moves` → `MoveList`) and clarify `Move.from`
+  disambiguation and move tuple slot semantics
+- Updated benchmark results for v3.5.0 SAN rule restructure
+
+## [3.5.0] - 2026-03-14
+
+### Added
+
+- `stream(input: AsyncIterable<string>): AsyncGenerator<PGN>` — new named export
+  for incremental, memory-efficient parsing of large PGN databases
+
+### Changed
+
+- `Move.from` widened from `File | Rank` to `Disambiguation`
+  (`Square | File | Rank`) to correctly type fully-disambiguated moves (e.g.
+  `Qd1xe4` → `from: "d1"`)
+- `type Moves` renamed to `MoveList`; new
+  `MovePair = [number, Move | undefined, Move?]` tuple
+- `type Variation` simplified to `MoveList[]`
+
+### Performance
+
+- Restructured `SAN` grammar rule to eliminate post-match regex on every move;
+  closes remaining ~1.1–1.2x gap vs `pgn-parser` on move-heavy fixtures
+
+## [3.4.0] - 2026-02-21
+
+### Changed
+
+- Rewrote README following `@echecs/elo` library style with badges, Why, Quick
+  Start, Usage, and Contributing sections
+- Updated AGENTS.md to reflect Peggy migration and remove stale nearley/moo
+  references
+
+### Added
+
+- Features section in README highlighting RAV and NAG support with a parser
+  comparison table
+- Performance section in README with benchmark results table
+- Codecov badge to README
+
+### Removed
+
+- `docs.yml` workflow (no hosted docs in this project)
+
+## [3.3.0] - 2026-02-21
+
+### Added
+
+- Peggy PEG parser replacing nearley/moo for O(n) linear-time parsing —
+  delivering up to 10× throughput improvement on large PGN files
+- Comparative benchmark (`comparison.bench.ts`) measuring `@echecs/pgn` against
+  `@mliebelt/pgn-parser` and `chess.js`
+
+### Performance
+
+- Replaced `pickBy` with direct property assignment in SAN action block,
+  reducing allocations per move
+- Added length-check guards before NAG and comment processing in MOVE action,
+  skipping unnecessary work for moves without annotations
+- Removed `delete` mutations and reduced allocations in `pairMoves`, avoiding V8
+  hidden-class transitions
+
+### Removed
+
+- Stale `tokenizer.ts` debug script
+
+## [3.2.1] - 2026-02-20
+
+### Fixed
+
+- Sort `multiGameFixtures` keys in comparison benchmark to satisfy the
+  `sort-keys` lint rule
+
+## [3.2.0] - 2026-02-20
+
+### Added
+
+- Comparative PGN parser benchmark (`comparison.bench.ts`) for cross-library
+  performance tracking
+
+### Performance
+
+- Reduced Earley parser overhead via grammar and caching optimizations
+
+## [3.1.3] - 2025-03-27
+
+### Fixed
+
+- Removed accidental production dependency introduced in 3.1.2
+
+## [3.1.2] - 2025-03-01
+
+### Fixed
+
+- Increased per-test timeout to accommodate `long.pgn` (~3 500 games) on slow CI
+  runners
+
+## [3.1.1] - 2025-03-01
+
+### Fixed
+
+- Corrected `.js` extension on relative imports in test files (NodeNext
+  resolution)
+
+## [3.1.0] - 2025-03-01
+
+### Added
+
+- moo tokenizer for faster lexing
+- New grammar supporting the full PGN specification including RAV (recursive
+  annotated variations) and NAG (numeric annotation glyphs)
+
+[unreleased]: https://github.com/mormubis/pgn/compare/v3.4.0...HEAD
+[3.4.0]: https://github.com/mormubis/pgn/compare/v3.3.0...v3.4.0
+[3.3.0]: https://github.com/mormubis/pgn/compare/v3.2.1...v3.3.0
+[3.2.1]: https://github.com/mormubis/pgn/compare/v3.2.0...v3.2.1
+[3.2.0]: https://github.com/mormubis/pgn/compare/v3.1.3...v3.2.0
+[3.1.3]: https://github.com/mormubis/pgn/compare/v3.1.2...v3.1.3
+[3.1.2]: https://github.com/mormubis/pgn/compare/v3.1.1...v3.1.2
+[3.1.1]: https://github.com/mormubis/pgn/compare/v3.1.0...v3.1.1
+[3.1.0]: https://github.com/mormubis/pgn/releases/tag/v3.1.0

package/README.md

@@ -1,140 +1,167 @@
 # PGN
 
-`PGN` is a parser that is part of the **ECHECS** project, designed to interpret
-the
-[PGN (Portable Game Notation) specification](http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm).
+[![npm](https://img.shields.io/npm/v/@echecs/pgn)](https://www.npmjs.com/package/@echecs/pgn)
+[![Test](https://github.com/mormubis/pgn/actions/workflows/test.yml/badge.svg)](https://github.com/mormubis/pgn/actions/workflows/test.yml)
+[![Coverage](https://codecov.io/gh/mormubis/pgn/branch/main/graph/badge.svg)](https://codecov.io/gh/mormubis/pgn)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**PGN** is a fast TypeScript parser for
+[Portable Game Notation](http://www.saremba.de/chessgml/standards/pgn/pgn-complete.htm)
+— the standard format for recording chess games.
+
+It parses PGN input into structured move objects with decomposed SAN, paired
+white/black moves, and full support for annotations and variations. Zero runtime
+dependencies.
+
+## Why this library?
+
+Most PGN parsers on npm either give you raw strings with no structure, or fail
+on anything beyond a plain game record. If you're building a chess engine,
+opening book, or game viewer, you need more:
+
+- **Decomposed SAN** — every move is parsed into `piece`, `from`, `to`,
+  `capture`, `promotion`, `check`, and `checkmate` fields. No regex on your
+  side.
+- **Paired move structure** — moves are returned as
+  `[moveNumber, whiteMove, blackMove]` tuples, ready to render or process
+  without further work.
+- **RAV support** — recursive annotation variations (`(...)` sub-lines) are
+  parsed into a `variants` tree on each move. Essential for opening books and
+  annotated games.
+- **NAG support** — symbolic (`!`, `?`, `!!`, `??`, `!?`, `?!`) and numeric
+  (`$1`–`$255`) annotations are surfaced as an `annotations` array. Essential
+  for Lichess and ChessBase exports.
+- **Multi-game files** — parse entire PGN databases in one call, or stream them
+  game-by-game with `stream()` for memory-efficient processing of large files.
+  Tested on files with 3 500+ games.
+- **Fast** — built on a [Peggy](https://peggyjs.org/) PEG parser. Throughput is
+  within 1.1–1.2x of the fastest parsers on npm, which do far less work per move
+  (see [BENCHMARK_RESULTS.md](./BENCHMARK_RESULTS.md)).
+
+If you only need raw SAN strings and a flat move list, any PGN parser will do.
+If you need structured, engine-ready output with annotations and variations,
+this is the one.
 
 ## Installation
 
 ```bash
-npm install --save-dev @echecs/pgn
+npm install @echecs/pgn
+```
+
+## Quick Start
+
+```typescript
+import parse from '@echecs/pgn';
+
+const games = parse(`
+  [Event "Example"]
+  [White "Player1"]
+  [Black "Player2"]
+  [Result "1-0"]
+
+  1. e4 e5 2. Nf3 Nc6 3. Bb5 1-0
+`);
+
+console.log(games[0].moves[0]);
+// [1, { piece: 'P', to: 'e4' }, { piece: 'P', to: 'e5' }]
 ```
 
 ## Usage
 
-The `parse` function takes a PGN formatted string as input and returns an array
-of parsed PGN objects.
+### `parse()`
+
+Takes a PGN string and returns an array of game objects — one per game in the
+file.
 
 ```typescript
 parse(input: string): PGN[]
 ```
 
-### PGN Object Format
+### `stream()`
 
-Here’s the structure of the `PGN` object:
+Takes any `AsyncIterable<string>` and yields one `PGN` object per game. Memory
+usage stays proportional to one game at a time, making it suitable for large
+databases read from disk or a network stream.
 
-#### PGN Object
+```typescript
+stream(input: AsyncIterable<string>): AsyncGenerator<PGN>
+```
 
 ```typescript
-{
-    "meta": Meta,
-    "moves": Moves,
-    "result": "1-0" // possible values: "1-0", "0-1", "1/2-1/2", "?"
+import { createReadStream } from 'node:fs';
+import { stream } from '@echecs/pgn';
+
+const chunks = createReadStream('database.pgn', { encoding: 'utf8' });
+for await (const game of stream(chunks)) {
+  console.log(game.meta.White, 'vs', game.meta.Black);
 }
 ```
 
-#### Meta Object
-
-The `meta` object contains metadata about the chess game.
+### PGN object
 
 ```typescript
 {
-    "Event": "name of the tournament or match event",
-    "Site": "location of the event",
-    "Date": "starting date of the game",
-    "Round": "playing round ordinal of the game",
-    "White": "player of the white pieces",
-    "Black": "player of the black pieces",
-    "Result": "result of the game",
-    // Any other additional tags
-    [key]: "string"
+  meta:   Meta,      // tag pairs (Event, Site, Date, White, Black, …)
+  moves:  MoveList,  // paired move list
+  result: 1 | 0 | 0.5 | '?'
 }
 ```
 
-#### Moves Array
-
-`Moves` is an array representing the sequence of moves in the game. Each element
-is an array containing the move number, the white move, and the black move.
+### Move object
 
 ```typescript
-[moveNumber, Move, Move];
+{
+  piece:       'P' | 'R' | 'N' | 'B' | 'Q' | 'K', // always present
+  to:          string,       // destination square, e.g. "e4"
+  from?:       string,       // disambiguation: file "e", rank "2", or square "e2"
+  capture?:    true,
+  castling?:   true,
+  check?:      true,
+  checkmate?:  true,
+  promotion?:  'R' | 'N' | 'B' | 'Q',
+  annotations?: string[],   // e.g. ["!", "$14"]
+  comment?:    string,
+  variants?:   MoveList[],  // recursive annotation variations
+}
 ```
 
-Note: Half moves are included for variations or in cases where the last move was
-made by white.
+Moves are grouped into tuples: `[moveNumber, whiteMove, blackMove]`. Both move
+slots can be `undefined` — `whiteMove` when a variation begins on black's turn,
+`blackMove` when the game or variation ends on white's move.
 
-#### Move Object
+### Annotations and comments
 
-Each move is represented by the following structure:
+```pgn
+12. Nf3! $14 { White has a slight advantage }
+```
 
 ```typescript
 {
-  "annotations": ["!", "$126"], // optional, annotations for the move
-  "capture": false, // optional, indicates if any piece was captured
-  "castling": true, // optional, indicates if the move was castling
-  "check": false, // optional, indicates if the move put the rival king in check
-  "checkmate": false, // optional, indicates if it is a checkmate
-  "comment": "Some comment", // optional, comment about the move
-  "from": "e", // optional, disambiguation of the move
-  "piece": "K", // required, type of piece (P, R, N, B, Q, K)
-  "promotion": "Piece", // optional, promotion piece (R, N, B, Q)
-  "to": "g1", // required, ending square of the move
-  "variants": [...] // optional, array of moves for variations following Moves format
+  piece: 'N', to: 'f3',
+  annotations: ['!', '$14'],
+  comment: 'White has a slight advantage'
 }
 ```
 
-### Example
+### Variations
 
-Here's a sample usage of the `PGN` parser:
+```pgn
+5... Ba5 (5... Be7 6. d4) 6. Qb3
+```
 
-```typescript
-import { readFileSync } from 'fs';
-import parse from '@echecs/pgn';
+The alternative line appears as a `variants` array on the move where it
+branches:
 
-function readFile(path) {
-  const filename = require.resolve(path);
-  return readFileSync(filename, 'utf8');
+```typescript
+{
+  piece: 'B', to: 'a5',
+  variants: [
+    [ [5, undefined, { piece: 'B', to: 'e7' }], [6, { piece: 'P', to: 'd4' }] ]
+  ]
 }
-
-const pgn = parse(readFile('./games/file.pgn'));
-
-// Output example of parsed `PGN`
-console.log(pgn);
-/*
-[
-   {
-     "meta": {
-       "Event": "Some Tournament",
-       "Site": "Some Location",
-       "Date": "2023.10.04",
-       "Round": "1",
-       "White": "Player1",
-       "Black": "Player2",
-       "Result": "1-0",
-       // additional tags...
-     },
-     "moves": [
-       [
-         1,
-         { "piece": "P", "to": "e4" },
-         { "piece": "P", "to": "e5" }
-       ],
-       [
-         2,
-         { "piece": "N", "to": "f3" },
-         { "piece": "N", "to": "c6" }
-       ],
-       // more moves...
-     ],
-     "result": "1-0"
-   }
-];
-*/
 ```
 
-## Important Notes
+## Contributing
 
-- `PGN` is a parser and does not verify the validity of the PGN games. It only
-  parses the provided content.
-- For game validation, use **@echecs/game** as it is responsible for verifying
-  game correctness as part of the **ECHECS** project.
+Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for
+guidelines on how to submit issues and pull requests.