@echecs/pgn 3.4.0 → 3.5.2

package/CHANGELOG.md

@@ -7,3 +7,143 @@ and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+## [3.5.2] - 2026-03-14
+
+### Fixed
+
+- Benchmark: `benko.pgn` moved to multi-game group and compared with the correct
+  `parseGames` API — previously called `parseGame` (single-game), causing all
+  comparison parsers to error
+- Benchmark: `comments.pgn` BOM (`U+FEFF`) now stripped before parsing, enabling
+  comparison against `@mliebelt/pgn-parser` and `pgn-parser`
+- Benchmark: fixture exclusion reasons documented in `BENCHMARK_RESULTS.md` and
+  in bench source comments
+
+## [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

@@ -31,8 +31,9 @@ opening book, or game viewer, you need more:
 - **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. Tested on files
-  with 3 500+ games.
+- **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)).
@@ -67,19 +68,41 @@ console.log(games[0].moves[0]);
 
 ## Usage
 
-`parse()` takes a PGN string and returns an array of game objects — one per game
-in the file.
+### `parse()`
+
+Takes a PGN string and returns an array of game objects — one per game in the
+file.
 
 ```typescript
 parse(input: string): PGN[]
 ```
 
+### `stream()`
+
+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.
+
+```typescript
+stream(input: AsyncIterable<string>): AsyncGenerator<PGN>
+```
+
+```typescript
+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);
+}
+```
+
 ### PGN object
 
 ```typescript
 {
-  meta:   Meta,   // tag pairs (Event, Site, Date, White, Black, …)
-  moves:  Moves,  // paired move list
+  meta:   Meta,      // tag pairs (Event, Site, Date, White, Black, …)
+  moves:  MoveList,  // paired move list
   result: 1 | 0 | 0.5 | '?'
 }
 ```
@@ -90,7 +113,7 @@ parse(input: string): PGN[]
 {
   piece:       'P' | 'R' | 'N' | 'B' | 'Q' | 'K', // always present
   to:          string,       // destination square, e.g. "e4"
-  from?:       string,       // disambiguation, e.g. "e" or "e2"
+  from?:       string,       // disambiguation: file "e", rank "2", or square "e2"
   capture?:    true,
   castling?:   true,
   check?:      true,
@@ -98,12 +121,13 @@ parse(input: string): PGN[]
   promotion?:  'R' | 'N' | 'B' | 'Q',
   annotations?: string[],   // e.g. ["!", "$14"]
   comment?:    string,
-  variants?:   Moves[],     // recursive annotation variations
+  variants?:   MoveList[],  // recursive annotation variations
 }
 ```
 
-Moves are grouped into tuples: `[moveNumber, whiteMove, blackMove]`. If the last
-move of a game or variation was made by white, `blackMove` is `undefined`.
+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.
 
 ### Annotations and comments