fast-pgn-parser 0.0.1

package/scripts/install-libpgn.cjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Ensures vendor/libpgn exists (clones from GitHub if missing).
+ * Run before node-gyp so the native addon can build and link libpgn.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const vendorLibpgn = path.join(__dirname, '..', 'vendor', 'libpgn');
+const pgnC = path.join(vendorLibpgn, 'pgn.c');
+
+if (fs.existsSync(pgnC)) {
+  console.log('vendor/libpgn already present');
+  runNodeGyp();
+  process.exit(0);
+}
+
+const vendorDir = path.join(__dirname, '..', 'vendor');
+if (!fs.existsSync(vendorDir)) {
+  fs.mkdirSync(vendorDir, { recursive: true });
+}
+try {
+  console.log('Cloning libpgn into vendor/libpgn...');
+  execSync('git clone --depth 1 https://github.com/fwttnnn/libpgn.git libpgn', {
+    cwd: vendorDir,
+    stdio: 'inherit',
+  });
+  console.log('libpgn cloned successfully');
+} catch (err) {
+  console.warn('Could not clone libpgn (native addon will not be built):', err.message);
+  process.exit(0);
+}
+
+if (fs.existsSync(pgnC)) {
+  runNodeGyp();
+}
+
+function runNodeGyp() {
+  try {
+    execSync('node-gyp rebuild', { stdio: 'inherit', cwd: path.join(__dirname, '..') });
+  } catch (err) {
+    console.warn('node-gyp rebuild failed; using JS stub:', err.message);
+  }
+}

package/src/binding.cc

@@ -0,0 +1,130 @@
+/**
+ * N-API bindings for libpgn. Exposes Parser with nextGame() for streaming games.
+ */
+#include <napi.h>
+#include <string>
+#include <vector>
+#include <cstring>
+
+extern "C" {
+#include "pgn.h"
+}
+
+static napi_value pgn_metadata_to_object(napi_env env, pgn_metadata_t* meta) {
+  napi_value obj;
+  napi_create_object(env, &obj);
+  if (!meta || !meta->items) return obj;
+  for (size_t i = 0; i < meta->length; i++) {
+    __pgn_metadata_item_t* item = &meta->items[i];
+    if (!item->key || !item->key->buf || !item->value || !item->value->buf) continue;
+    napi_value key_val, value_val;
+    napi_create_string_utf8(env, item->key->buf, item->key->length, &key_val);
+    napi_create_string_utf8(env, item->value->buf, item->value->length, &value_val);
+    napi_set_property(env, obj, key_val, value_val);
+  }
+  return obj;
+}
+
+static napi_value pgn_to_game_object(napi_env env, pgn_t* pgn) {
+  napi_value game;
+  napi_create_object(env, &game);
+
+  napi_value tags = pgn_metadata_to_object(env, pgn->metadata);
+  napi_set_named_property(env, game, "tags", tags);
+
+  const char* result_str = pgn_score_to_string(pgn->score);
+  napi_value result;
+  napi_create_string_utf8(env, result_str ? result_str : "*", NAPI_AUTO_LENGTH, &result);
+  napi_set_named_property(env, game, "result", result);
+
+  napi_value moves_array;
+  napi_create_array_with_length(env, 0, &moves_array);
+  if (pgn->moves && pgn->moves->values) {
+    size_t idx = 0;
+    for (size_t i = 0; i < pgn->moves->length; i++) {
+      napi_value white_move;
+      napi_create_string_utf8(env, pgn->moves->values[i].white.notation, NAPI_AUTO_LENGTH, &white_move);
+      napi_set_element(env, moves_array, idx++, white_move);
+      if (pgn->moves->values[i].black.notation[0] != '\0') {
+        napi_value black_move;
+        napi_create_string_utf8(env, pgn->moves->values[i].black.notation, NAPI_AUTO_LENGTH, &black_move);
+        napi_set_element(env, moves_array, idx++, black_move);
+      }
+    }
+    napi_set_named_property(env, game, "moves", moves_array);
+  } else {
+    napi_set_named_property(env, game, "moves", moves_array);
+  }
+
+  return game;
+}
+
+class ParserWrapper : public Napi::ObjectWrap<ParserWrapper> {
+ public:
+  static Napi::Object Init(Napi::Env env, Napi::Object exports);
+  ParserWrapper(const Napi::CallbackInfo& info);
+
+ private:
+  Napi::Value NextGame(const Napi::CallbackInfo& info);
+  std::string text_;
+  size_t offset_{0};
+};
+
+Napi::Object ParserWrapper::Init(Napi::Env env, Napi::Object exports) {
+  Napi::Function func = DefineClass(env, "Parser", {
+    InstanceMethod("nextGame", &ParserWrapper::NextGame),
+  });
+  Napi::Object constructor = func.Get("constructor").As<Napi::Object>();
+  exports.Set("Parser", func);
+  return exports;
+}
+
+ParserWrapper::ParserWrapper(const Napi::CallbackInfo& info)
+  : Napi::ObjectWrap<ParserWrapper>(info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1 || !info[0].IsString()) {
+    Napi::TypeError::New(env, "Expected string (pgnText)").ThrowAsJavaScriptException();
+    return;
+  }
+  text_ = info[0].As<Napi::String>().Utf8Value();
+}
+
+Napi::Value ParserWrapper::NextGame(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (offset_ >= text_.size()) {
+    return env.Null();
+  }
+  // Skip leading whitespace between games
+  while (offset_ < text_.size() && (text_[offset_] == ' ' || text_[offset_] == '\n' || text_[offset_] == '\r' || text_[offset_] == '\t')) {
+    offset_++;
+  }
+  if (offset_ >= text_.size()) {
+    return env.Null();
+  }
+  std::vector<char> mutable_buf(text_.begin() + offset_, text_.end());
+  mutable_buf.push_back('\0');
+  pgn_t* pgn = pgn_init();
+  if (!pgn) {
+    return env.Null();
+  }
+  size_t consumed = pgn_parse(pgn, mutable_buf.data());
+  if (consumed == 0) {
+    pgn_cleanup(pgn);
+    return env.Null();
+  }
+  size_t start = offset_;
+  offset_ += consumed;
+  std::string pgntext = text_.substr(start, consumed);
+  napi_value gameVal = pgn_to_game_object(env, pgn);
+  pgn_cleanup(pgn);
+  napi_value pgntextVal;
+  napi_create_string_utf8(env, pgntext.c_str(), pgntext.size(), &pgntextVal);
+  napi_set_named_property(env, gameVal, "pgntext", pgntextVal);
+  return Napi::Value(env, gameVal);
+}
+
+static Napi::Object Init(Napi::Env env, napi_value exports_val) {
+  return ParserWrapper::Init(env, Napi::Object(env, exports_val));
+}
+
+NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)

package/src/index.js

@@ -0,0 +1,61 @@
+/**
+ * PGN parser — public API: parse(string) returns an array of game objects.
+ * Requires the native addon (C bindings to libpgn). Throws if the addon failed to build.
+ */
+
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+let nativeBinding = null;
+try {
+  nativeBinding = require('./build/Release/pgn_parser.node');
+} catch {
+  try {
+    nativeBinding = require('./build/Debug/pgn_parser.node');
+  } catch (err) {
+    throw new Error(
+      'fast-pgn-parser: native addon failed to load. Ensure the C bindings are built (npm install / npm run rebuild). ' +
+        'You need Git, a C/C++ toolchain, and Node.js ≥18. Original error: ' + err.message
+    );
+  }
+}
+
+if (!nativeBinding || typeof nativeBinding.Parser !== 'function') {
+  throw new Error('fast-pgn-parser: native addon did not expose Parser. Rebuild with: npm run rebuild');
+}
+
+/**
+ * Game object returned by parse().
+ * @typedef {{
+ *   tags: { [key: string]: string },
+ *   moves: string[],
+ *   pgntext?: string
+ * }} Game
+ */
+
+/**
+ * Parse PGN text and return an array of game objects.
+ * Each game has `tags` (key/value headers), `moves` (array of SAN strings), and when available `pgntext` (raw PGN for that game).
+ *
+ * @param {string} pgnText - Full PGN string (one or more games).
+ * @returns {Game[]}
+ */
+export function parse(pgnText) {
+  const games = [];
+  const parser = new nativeBinding.Parser(pgnText);
+  while (true) {
+    const g = parser.nextGame();
+    if (g === null) break;
+    games.push({
+      tags: g.tags,
+      moves: Array.isArray(g.moves) ? g.moves : [],
+      pgntext: g.pgntext,
+    });
+  }
+  return games;
+}
+
+/** @returns {boolean} True if the native libpgn addon is in use (always true when the module loads successfully). */
+export function isNative() {
+  return true;
+}

package/test/index.test.js

@@ -0,0 +1,108 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parse } from '../src/index.js';
+
+const samplePgn = `[Event "Example"]
+[White "A"]
+[Black "B"]
+
+1. e4 e5 2. Nf3 Nc6 3. Bb5 *
+
+`;
+
+const twoGames = samplePgn + `
+[Event "Second"]
+[White "C"]
+[Black "D"]
+
+1. d4 d5 *
+`;
+
+const pgnWithResults = `[Event "W"]
+[White "W"]
+[Black "B"]
+[Result "1-0"]
+
+1. e4 *
+
+[Event "L"]
+[Result "0-1"]
+
+1. e4 e5 2. Ke2 *
+
+[Event "D"]
+[Result "1/2-1/2"]
+
+1. e4 e5 2. Nf3 Nc6 3. Nf3 *
+`;
+
+describe('parse', () => {
+  it('returns an array of game objects', () => {
+    const games = parse(samplePgn);
+    assert.strictEqual(games.length, 1);
+    assert.strictEqual(typeof games[0], 'object');
+    assert.ok('tags' in games[0]);
+    assert.ok('moves' in games[0]);
+  });
+
+  it('each game has tags (key/value) and moves (array of strings)', () => {
+    const games = parse(samplePgn);
+    assert.strictEqual(games[0].tags.Event, 'Example');
+    assert.strictEqual(games[0].tags.White, 'A');
+    assert.strictEqual(games[0].tags.Black, 'B');
+    assert.ok(Array.isArray(games[0].moves));
+    assert.ok(games[0].moves.length >= 4);
+    assert.strictEqual(games[0].moves[0], 'e4');
+    assert.strictEqual(games[0].moves[1], 'e5');
+  });
+
+  it('returns multiple games', () => {
+    const games = parse(twoGames);
+    assert.strictEqual(games.length, 2);
+    assert.strictEqual(games[0].tags.Event, 'Example');
+    assert.strictEqual(games[1].tags.Event, 'Second');
+    assert.strictEqual(games[1].tags.White, 'C');
+  });
+
+  it('returns empty array for empty string', () => {
+    const games = parse('');
+    assert.strictEqual(games.length, 0);
+  });
+
+  it('each game includes pgntext when available', () => {
+    const games = parse(samplePgn);
+    assert.ok('pgntext' in games[0]);
+    assert.strictEqual(typeof games[0].pgntext, 'string');
+    assert.ok(games[0].pgntext.includes('[Event "Example"]'));
+    assert.ok(games[0].pgntext.includes('1. e4 e5'));
+  });
+
+  it('pgntext is the raw PGN for that game only', () => {
+    const games = parse(twoGames);
+    assert.ok(!games[0].pgntext.includes('Second'));
+    assert.ok(games[1].pgntext.includes('[Event "Second"]'));
+  });
+
+  it('pgntext contains only that game\'s tags and moves, not other games', () => {
+    const games = parse(twoGames);
+    assert.ok(games.length >= 2, 'need multiple games');
+    assert.ok(games[0].pgntext != null && games[0].pgntext.length > 0);
+    assert.ok(games[1].pgntext != null && games[1].pgntext.length > 0);
+    assert.ok(games[0].pgntext.includes('[Event "Example"]'), 'game 0 pgntext should include its Event tag');
+    assert.ok(games[0].pgntext.includes('1. e4 e5'), 'game 0 pgntext should include its moves');
+    assert.ok(!games[0].pgntext.includes('Second'), 'game 0 pgntext must not contain the other game\'s Event');
+    assert.ok(!games[0].pgntext.includes('d4'), 'game 0 pgntext must not contain the other game\'s moves');
+    assert.ok(games[1].pgntext.includes('[Event "Second"]'), 'game 1 pgntext should include its Event tag');
+    assert.ok(games[1].pgntext.includes('1. d4 d5'), 'game 1 pgntext should include its moves');
+    assert.ok(!games[1].pgntext.includes('Example'), 'game 1 pgntext must not contain the other game\'s Event');
+    assert.ok(!games[1].pgntext.includes('Bb5'), 'game 1 pgntext must not contain the other game\'s moves');
+  });
+
+  it('parses games with Result tag', () => {
+    const games = parse(pgnWithResults);
+    assert.strictEqual(games.length, 3);
+    assert.strictEqual(games[0].tags.Result, '1-0');
+    assert.strictEqual(games[1].tags.Result, '0-1');
+    assert.strictEqual(games[2].tags.Result, '1/2-1/2');
+  });
+});

package/vendor/README.md

@@ -0,0 +1,17 @@
+# Vendor: libpgn
+
+The [libpgn](https://github.com/fwttnnn/libpgn) C library is used by the N-API addon and is **statically linked** into the native module.
+
+## Automatic setup
+
+Running `npm install` runs `scripts/install-libpgn.js`, which clones libpgn into **`vendor/libpgn`** if missing, then runs `node-gyp rebuild` to build the addon. If the clone or build fails, the package still installs and the JS stub parser is used.
+
+## Manual setup
+
+To clone libpgn yourself (e.g. for a submodule):
+
+```bash
+git clone https://github.com/fwttnnn/libpgn.git vendor/libpgn
+```
+
+Then run `npm run rebuild` to build the native addon.