fast-pgn-parser 0.0.1

package/README.md

@@ -0,0 +1,53 @@
+# fast-pgn-parser
+
+Basic but fast PGN (Portable Game Notation) parser for Node.js, backed by C bindings to [libpgn](https://github.com/fwttnnn/libpgn).
+
+The core parsing is implemented in C via libpgn and exposed to Node.js through native bindings.
+
+## Status
+
+In development. N-API bindings to libpgn are in place: libpgn is built and **statically linked** into the native addon. If the addon fails to build (no git, no C++ toolchain), the module throws at load time.
+
+## API
+
+- **`parse(pgnText)`** — Parses PGN text and returns an **array of game objects**. Each game has:
+  - **`tags`** — Object of key/value PGN headers (e.g. `Event`, `White`, `Black`, `Result`).
+  - **`moves`** — Array of move strings (SAN notation).
+  - **`pgntext`** — the raw PGN text for that game only.
+
+Example:
+
+```js
+import { parse } from 'fast-pgn-parser';
+
+const games = parse(pgnText);
+for (const game of games) {
+  console.log(game.tags.Event, game.tags.White, 'vs', game.tags.Black);
+  console.log(game.moves);  // ['e4', 'e5', 'Nf3', ...]
+  console.log(game.pgntext); // is the unparsed PGN for this game
+}
+```
+
+## Project layout
+
+- **`src/`** — Node.js API and N-API addon (`binding.cc`)
+- **`test/`** — Tests (`node --test`)
+- **`vendor/`** — [libpgn](https://github.com/fwttnnn/libpgn) is cloned into `vendor/libpgn` on install (see `vendor/README.md`)
+
+## Scripts
+
+- `npm install` — install deps, clone libpgn if needed, build native addon (fails if addon cannot be built)
+- `npm run rebuild` — rebuild the native addon (node-gyp)
+- `npm test` — run tests
+- `npm run test:coverage` — run tests with coverage (c8)
+- `npm run benchmark` — benchmark `parse()` vs [pgn-parser](https://www.npmjs.com/package/pgn-parser) using `scripts/games.pgn` (default 100 runs; `node scripts/benchmark-parse.mjs [path] [N]`)
+
+## Building the native addon
+
+- **Node.js** ≥ 18
+- **Git** — to clone libpgn (or add `vendor/libpgn` manually)
+- **C/C++ toolchain** — [node-gyp](https://github.com/nodejs/node-gyp#installation) (e.g. Visual Studio Build Tools on Windows, Xcode CLI on macOS, build-essential on Linux)
+
+On Windows, **Visual Studio 18** (version 18 in the install path) is supported via a postinstall script (`scripts/fix-node-gyp-vs18.cjs`) that applies the same approach as projects like bitboard-chess: node-gyp is adjusted so version 18 is treated as 2022 and the v145 toolset is used when the path contains `\18\`. No patch file is used.
+
+After `npm install`, the addon is in `build/Release/pgn_parser.node`. If the addon did not build, importing the module throws.

package/binding.gyp

@@ -0,0 +1,43 @@
+{
+  "targets": [{
+    "target_name": "pgn_parser",
+    "sources": [
+      "src/binding.cc",
+      "vendor/libpgn/annotation.c",
+      "vendor/libpgn/check.c",
+      "vendor/libpgn/comments.c",
+      "vendor/libpgn/coordinate.c",
+      "vendor/libpgn/metadata.c",
+      "vendor/libpgn/moves.c",
+      "vendor/libpgn/pgn.c",
+      "vendor/libpgn/piece.c",
+      "vendor/libpgn/score.c",
+      "vendor/libpgn/utils/buffer.c",
+      "vendor/libpgn/utils/cursor.c",
+      "vendor/libpgn/utils/export.c"
+    ],
+    "include_dirs": [
+      "<!@(node -p \"require('node-addon-api').include\")",
+      "vendor/libpgn",
+      "vendor/libpgn/utils"
+    ],
+    "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"],
+    "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"],
+    "cflags!": ["-fno-exceptions"],
+    "cflags_cc!": ["-fno-exceptions"],
+    "conditions": [
+      ["OS=='win'", {
+        "defines": ["PGN_STATIC_BUILD"],
+        "msvs_settings": {
+          "VCCLCompilerTool": {
+            "ExceptionHandling": 1
+          }
+        }
+      }],
+      ["OS!='win'", {
+        "cflags": ["-std=c99"],
+        "cflags_cc": ["-std=c++17"]
+      }]
+    ]
+  }]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "fast-pgn-parser",
+  "version": "0.0.1",
+  "description": "Basic but fast PGN parser",
+  "type": "module",
+  "main": "src/index.js",
+  "scripts": {
+    "install": "node scripts/install-libpgn.cjs",
+    "postinstall": "node scripts/fix-node-gyp-vs18.cjs",
+    "rebuild": "node-gyp rebuild",
+    "test": "node --test",
+    "test:coverage": "c8 node --test",
+    "coverage": "c8 node --test",
+    "benchmark": "node scripts/benchmark-parse.mjs"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "c8": "^10.1.2",
+    "node-gyp": "^10.0.0",
+    "pgn-parser": "^2.2.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "gypfile": true
+}

package/scripts/benchmark-parse.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Benchmark: fast-pgn-parser parse() vs pgn-parser parse()
+ * Usage: node scripts/benchmark-parse.mjs [path-to.pgn] [N]
+ * Defaults: scripts/games.pgn, N=100
+ */
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { parse as ourParse, isNative } from '../src/index.js';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const pgnParser = require('pgn-parser');
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const rootDir = join(__dirname, '..');
+
+const pgnPath = process.argv[2] || join(rootDir, 'scripts', 'games.pgn');
+const N = parseInt(process.argv[3] || '100', 10);
+
+let pgnText;
+try {
+  pgnText = readFileSync(pgnPath, 'utf8');
+  pgnText = pgnText.replace(/^\uFEFF/, '').replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+} catch (err) {
+  console.error('Failed to read:', pgnPath, err.message);
+  process.exit(1);
+}
+
+const bytes = Buffer.byteLength(pgnText, 'utf8');
+const gameCount = ourParse(pgnText).length;
+console.log('Input:', pgnPath);
+console.log('Size:', (bytes / 1024).toFixed(2), 'KB, games:', gameCount);
+console.log('Runs:', N);
+console.log('fast-pgn-parser (native):', isNative());
+console.log('');
+
+function timeIt(name, fn) {
+  const start = performance.now();
+  for (let i = 0; i < N; i++) fn();
+  const elapsed = performance.now() - start;
+  const perRun = elapsed / N;
+  const opsPerSec = (N / elapsed) * 1000;
+  console.log(name);
+  console.log('  total:', elapsed.toFixed(2), 'ms');
+  console.log('  per parse:', perRun.toFixed(4), 'ms');
+  console.log('  ops/sec:', opsPerSec.toFixed(1));
+  console.log('');
+  return elapsed;
+}
+
+const ourMs = timeIt('fast-pgn-parser', () => ourParse(pgnText));
+const theirMs = timeIt('pgn-parser', () => pgnParser.parse(pgnText));
+
+const ratio = theirMs / ourMs;
+console.log('Ratio (pgn-parser / fast-pgn-parser):', ratio.toFixed(2) + 'x');

package/scripts/fix-node-gyp-vs18.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Apply the same VS 18 fix as bitboard-chess (no patch file):
+ * - Map version 18 to versionYear 2022 so node-gyp accepts it via [2019, 2022]
+ * - In getToolset, use v145 when install path contains \18\, else v143 for 2022
+ * Idempotent: safe to run on vanilla or already-patched node-gyp.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const findVs = path.join(
+  __dirname,
+  '..',
+  'node_modules',
+  'node-gyp',
+  'lib',
+  'find-visualstudio.js'
+);
+
+if (!fs.existsSync(findVs)) {
+  process.exit(0);
+}
+
+let code = fs.readFileSync(findVs, 'utf8');
+
+// 1) getVersionInfo: versionMajor 18 -> versionYear 2022 (so [2019, 2022] accepts it)
+code = code.replace(
+  /(if \(ret\.versionMajor === 18\) \{\s*)ret\.versionYear = 2026/,
+  '$1ret.versionYear = 2022'
+);
+if (!code.includes('if (ret.versionMajor === 18)')) {
+  code = code.replace(
+    /(if \(ret\.versionMajor === 17\) \{\s*ret\.versionYear = 2022\s*return ret\s*\})\s*(this\.log\.silly\('- unsupported version:', ret\.versionMajor\))/,
+    "$1\n    if (ret.versionMajor === 18) {\n      ret.versionYear = 2022\n      return ret\n    }\n    $2"
+  );
+}
+
+// 2) supportedYears: use [2019, 2022] only
+code = code.replace(/\[2019, 2022, 2026\]/g, '[2019, 2022]');
+
+// 3) getToolset: for 2022 use v145 when path has \18\, else v143; remove 2026 branch if present
+if (!code.includes("includes('\\\\18\\\\')")) {
+  code = code.replace(
+    /(versionYear === 2022\) \{\s*)return 'v143'/,
+    "$1return (info.path && info.path.includes('\\\\18\\\\')) ? 'v145' : 'v143'"
+  );
+  code = code.replace(
+    /\s*\} else if \(versionYear === 2026\) \{\s*return 'v145'\s*\}/m,
+    '\n    }'
+  );
+}
+
+fs.writeFileSync(findVs, code, 'utf8');