node-rcheevos 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JZimz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# node-rcheevos
+
+> **⚠️ Work in Progress** - This works and I'm using it in ROMie, but it's early. Only macOS ARM64 binaries are pre-built right now. Other platforms will compile from source (need build tools) until I set up CI for cross-platform builds.
+
+Generate RetroAchievements hashes for ROMs in Node.js. Uses the official [rcheevos](https://github.com/RetroAchievements/rcheevos) C library, so you get the same hashes as RetroArch and other emulators.
+
+Built this for better RetroAchievements support in [ROMie](https://github.com/JZimz/romie), but it works anywhere you need to hash ROMs in Node.
+
+## Why this exists
+
+If you've tried adding RetroAchievements to an Electron app, you've probably hit this: WASM libraries don't work in the main process. And reimplementing the hashing logic in JavaScript is a recipe for subtle bugs when the algorithm changes.
+
+This wraps the official C library as a native Node addon, so it just works. Same hashing logic as the source of truth, supports all the systems RetroAchievements does (Game Boy, NES, SNES, PlayStation, PSP, you name it).
+
+## Install
+
+```bash
+npm install node-rcheevos
+```
+
+Comes with pre-built binaries for macOS, Windows, and Linux (both x64 and ARM64). If you're on something else, it'll build from source—just need the usual build tools (node-gyp stuff).
+
+## How to use it
+
+```javascript
+const { rhash } = require('node-rcheevos');
+
+const md5 = rhash(4, '/path/to/game.gb');  // Game Boy
+console.log(md5);  // "a1b2c3d4e5f6..."
+```
+
+TypeScript works too:
+
+```typescript
+import { rhash } from 'node-rcheevos';
+
+const md5 = rhash(41, '/path/to/game.iso');  // PSP
+```
+
+CLI if you want to test it quick:
+
+```bash
+npx rhash -c 4 /path/to/game.gb
+```
+
+## API
+
+Just one function: `rhash(consoleId, path, buffer?)`
+
+Pass it a RetroAchievements console ID (see table below) and the path to your ROM. Returns the MD5 hash as a string. Throws an error if the file doesn't exist or can't be hashed.
+
+## Console IDs
+
+Here are the common ones (full list at [docs.retroachievements.org](https://docs.retroachievements.org/Console-IDs/)):
+
+| ID | System |
+|----|--------|
+| 1  | Genesis/Mega Drive |
+| 2  | Nintendo 64 |
+| 3  | Super Nintendo |
+| 4  | Game Boy |
+| 5  | Game Boy Advance |
+| 6  | Game Boy Color |
+| 7  | NES/Famicom |
+| 11 | Game Gear |
+| 12 | PlayStation |
+| 27 | PlayStation Portable |
+| 38 | Nintendo 3DS |
+| 39 | Dreamcast |
+
+## Building from source
+
+If you want to hack on it:
+
+```bash
+git clone --recursive https://github.com/jzimz/node-rcheevos.git
+cd node-rcheevos
+npm install
+npm run build
+```
+
+The `--recursive` flag pulls in the rcheevos submodule. Without it, you won't have the C library to build against.
+
+## License
+
+MIT. The rcheevos library this wraps is also MIT.

package/bin/rhash.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+const { rhash } = require('../lib/index.js');
+const path = require('path');
+
+function printUsage() {
+  console.log('Usage: rhash -c <consoleId> <path>');
+  console.log('');
+  console.log('Options:');
+  console.log('  -c, --console <id>    RetroAchievements console ID');
+  console.log('');
+  console.log('Examples:');
+  console.log('  rhash -c 4 game.gb              # Game Boy');
+  console.log('  rhash --console 12 game.bin     # PlayStation');
+  console.log('');
+  console.log('Common console IDs:');
+  console.log('  1  - Sega Genesis/Mega Drive');
+  console.log('  2  - Nintendo 64');
+  console.log('  3  - Super Nintendo');
+  console.log('  4  - Game Boy');
+  console.log('  5  - Game Boy Advance');
+  console.log('  7  - NES/Famicom');
+  console.log('  12 - PlayStation');
+  console.log('  27 - PlayStation Portable');
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+  printUsage();
+}
+
+let consoleId;
+let romPath;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '-c' || args[i] === '--console') {
+    consoleId = parseInt(args[i + 1], 10);
+    i++;
+  } else if (!romPath) {
+    romPath = args[i];
+  }
+}
+
+if (!consoleId || !romPath) {
+  console.error('Error: Both console ID and ROM path are required\n');
+  printUsage();
+}
+
+if (isNaN(consoleId)) {
+  console.error('Error: Console ID must be a number\n');
+  printUsage();
+}
+
+const absolutePath = path.resolve(romPath);
+
+try {
+  const result = rhash(consoleId, absolutePath);
+  console.log(result);
+  process.exit(0);
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}

package/binding.gyp

@@ -0,0 +1,39 @@
+{
+  "targets": [
+    {
+      "target_name": "rcheevos",
+      "sources": [
+        "src/addon.cpp",
+        "src/rcheevos/src/rhash/aes.c",
+        "src/rcheevos/src/rhash/cdreader.c",
+        "src/rcheevos/src/rhash/hash.c",
+        "src/rcheevos/src/rhash/hash_disc.c",
+        "src/rcheevos/src/rhash/hash_encrypted.c",
+        "src/rcheevos/src/rhash/hash_rom.c",
+        "src/rcheevos/src/rhash/hash_zip.c",
+        "src/rcheevos/src/rhash/md5.c",
+        "src/rcheevos/src/rc_util.c"
+      ],
+      "include_dirs": [
+        "<!@(node -p \"require('node-addon-api').include\")",
+        "src/rcheevos/include",
+        "src/rcheevos/src"
+      ],
+      "defines": [
+        "NAPI_DISABLE_CPP_EXCEPTIONS"
+      ],
+      "cflags!": [ "-fno-exceptions" ],
+      "cflags_cc!": [ "-fno-exceptions" ],
+      "xcode_settings": {
+        "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
+        "CLANG_CXX_LIBRARY": "libc++",
+        "MACOSX_DEPLOYMENT_TARGET": "10.15"
+      },
+      "msvs_settings": {
+        "VCCLCompilerTool": {
+          "ExceptionHandling": 1
+        }
+      }
+    }
+  ]
+}

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generate a hash for a ROM file using the RetroAchievements algorithm.
+ *
+ * @param consoleId - The RetroAchievements console ID (e.g., 41 for PSP)
+ * @param path - Path to the ROM file (required even when using buffer, for file extension detection)
+ * @param buffer - Optional buffer containing ROM data. If provided, hashes from memory instead of reading file
+ * @returns MD5 hash as a 32-character hex string
+ * @throws Error if the file/buffer cannot be hashed
+ *
+ * @example
+ * ```typescript
+ * import { rhash } from 'node-rcheevos';
+ * import { readFileSync } from 'fs';
+ *
+ * // Hash from file
+ * const md5 = rhash(41, '/path/to/game.iso');
+ *
+ * // Hash from buffer (useful if already in memory)
+ * const buffer = readFileSync('/path/to/game.iso');
+ * const md5 = rhash(41, '/path/to/game.iso', buffer);
+ * ```
+ */
+export function rhash(consoleId: number, path: string, buffer?: Buffer): string;

package/lib/index.js

@@ -0,0 +1,5 @@
+const addon = require('node-gyp-build')(__dirname + '/..');
+
+module.exports = {
+  rhash: addon.rhash
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "node-rcheevos",
+  "version": "0.1.0",
+  "description": "Node.js native bindings for RetroAchievements rcheevos library (hash generation)",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "rhash": "bin/rhash.js"
+  },
+  "files": [
+    "lib/**/*",
+    "bin/**/*",
+    "prebuilds/**/*",
+    "binding.gyp",
+    "!**/*.test.*"
+  ],
+  "scripts": {
+    "install": "node-gyp-build",
+    "build": "node-gyp rebuild",
+    "prebuild": "prebuildify --napi --strip",
+    "test": "node --test"
+  },
+  "keywords": [
+    "retroachievements",
+    "rcheevos",
+    "hash",
+    "rom",
+    "native",
+    "addon"
+  ],
+  "author": {
+    "name": "JZimz",
+    "email": "jzimz.tv@gmail.com"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "node-addon-api": "^8.0.0",
+    "node-gyp-build": "^4.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "node-gyp": "^10.0.0",
+    "prebuildify": "^6.0.0"
+  },
+  "gypfile": true,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jzimz/node-rcheevos.git"
+  }
+}