node-rcheevos 0.5.0 → 1.0.0

package/README.md

@@ -1,77 +1,77 @@
 # 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.
+[![npm version](https://badge.fury.io/js/node-rcheevos.svg)](https://www.npmjs.com/package/node-rcheevos)
 
-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.
+Generate RetroAchievements hashes for ROMs in Node.js. Uses the same [rcheevos](https://github.com/RetroAchievements/rcheevos) C library that RetroArch uses, so your hashes will match exactly.
 
-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 not just reimplement the hashing in JavaScript?
 
-## Why this exists
+I tried that first. Each console has its own special hashing rules - NES strips the iNES header, SNES might have a 512-byte header to skip, PlayStation has to parse `SYSTEM.CNF` to find which executable to hash, N64 needs byte-order conversion depending on the ROM format. The [RetroAchievements docs](https://docs.retroachievements.org/developer-docs/game-identification.html) explain all this, but keeping JavaScript implementations updated for 40+ systems when RA changes their logic is a pain. Easier to just wrap their C library directly.
 
-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
+Built this for [ROMie](https://github.com/JZimz/romie) but figured it's useful standalone.
 
+## Installation
 ```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
+Includes pre-built binaries for macOS, Windows, and Linux (both x64 and ARM64). If you're on something else, it'll build from source automatically.
 
+## Quick Start
 ```javascript
-const { rhash } = require('node-rcheevos');
+const { rhash, ConsoleId } = require('node-rcheevos');
 
-const md5 = rhash(4, '/path/to/game.gb');  // Game Boy
-console.log(md5);  // "a1b2c3d4e5f6..."
+const md5 = rhash(ConsoleId.GAMEBOY, '/path/to/pokemon-red.gb');
+console.log(md5); // "bb7df04e1b0a2570657527a7e108ae23"
 ```
 
-TypeScript works too:
+## API
 
-```typescript
-import { rhash } from 'node-rcheevos';
+### `rhash(consoleId, path, buffer?)`
 
-const md5 = rhash(41, '/path/to/game.iso');  // PSP
-```
+**Parameters:**
+- `consoleId` (number): RetroAchievements console ID (use `ConsoleId` constants or numeric values)
+- `path` (string): Path to your ROM file
+- `buffer` (Buffer, optional): ROM data if you already have it in memory
 
-CLI if you want to test it quick:
+**Returns:** MD5 hash as a lowercase hex string
 
-```bash
-npx rhash -c 4 /path/to/game.gb
-```
+**Throws:** Error if the file doesn't exist, can't be read, or the console ID is invalid
 
-## API
+### `ConsoleId`
 
-Just one function: `rhash(consoleId, path, buffer?)`
+Exported constants for all console IDs if you prefer named constants over numbers.
 
-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.
+```javascript
+const { ConsoleId } = require('node-rcheevos');
 
-## Console IDs
+console.log(ConsoleId.GAMEBOY);      // 4
+console.log(ConsoleId.PLAYSTATION);  // 12
+console.log(ConsoleId.PSP);          // 41
+```
 
-Here are the common ones (full list at [docs.retroachievements.org](https://docs.retroachievements.org/Console-IDs/)):
+### Buffer limitations
 
-| 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 |
+**Works with buffers** (cartridge-based systems like GB, GBA, NES, SNES):
+```javascript
+const buffer = fs.readFileSync('/path/to/game.gb');
+const md5 = rhash(ConsoleId.GAMEBOY, '/path/to/game.gb', buffer);
+```
 
-## Building from source
+**Doesn't work with buffers** (disc-based like PlayStation, PSP, and arcade systems):
+```javascript
+// Passing a buffer will throw an error - must use file path
+const md5 = rhash(ConsoleId.PLAYSTATION, '/path/to/game.bin');
+```
 
-If you want to hack on it:
+Disc-based systems need to read specific sectors from the image file, and arcade systems hash the filename, so they can't work with in-memory buffers.
+
+## CLI Usage
+```bash
+npx rhash -c 4 /path/to/game.gb
+```
 
+## Building from Source
 ```bash
 git clone --recursive https://github.com/jzimz/node-rcheevos.git
 cd node-rcheevos
@@ -79,8 +79,8 @@ 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.
+The `--recursive` flag is important - it pulls in the rcheevos library. Without it, you won't have anything to build against.
 
 ## License
 
-MIT. The rcheevos library this wraps is also MIT.
+MIT. The rcheevos library is also MIT.

package/lib/index.d.ts

@@ -1,7 +1,112 @@
+/**
+ * RetroAchievements console identifiers.
+ * Use these constants instead of magic numbers for better readability.
+ *
+ * @example
+ * ```typescript
+ * import { rhash, ConsoleId } from 'node-rcheevos';
+ *
+ * const md5 = rhash(ConsoleId.GAMEBOY, '/path/to/game.gb');
+ * ```
+ */
+export const ConsoleId: {
+  readonly UNKNOWN: 0;
+  readonly MEGA_DRIVE: 1;
+  readonly NINTENDO_64: 2;
+  readonly SUPER_NINTENDO: 3;
+  readonly GAMEBOY: 4;
+  readonly GAMEBOY_ADVANCE: 5;
+  readonly GAMEBOY_COLOR: 6;
+  readonly NINTENDO: 7;
+  readonly PC_ENGINE: 8;
+  readonly SEGA_CD: 9;
+  readonly SEGA_32X: 10;
+  readonly MASTER_SYSTEM: 11;
+  readonly PLAYSTATION: 12;
+  readonly ATARI_LYNX: 13;
+  readonly NEOGEO_POCKET: 14;
+  readonly GAME_GEAR: 15;
+  readonly GAMECUBE: 16;
+  readonly ATARI_JAGUAR: 17;
+  readonly NINTENDO_DS: 18;
+  readonly WII: 19;
+  readonly WII_U: 20;
+  readonly PLAYSTATION_2: 21;
+  readonly XBOX: 22;
+  readonly MAGNAVOX_ODYSSEY2: 23;
+  readonly POKEMON_MINI: 24;
+  readonly ATARI_2600: 25;
+  readonly MS_DOS: 26;
+  readonly ARCADE: 27;
+  readonly VIRTUAL_BOY: 28;
+  readonly MSX: 29;
+  readonly COMMODORE_64: 30;
+  readonly ZX81: 31;
+  readonly ORIC: 32;
+  readonly SG1000: 33;
+  readonly VIC20: 34;
+  readonly AMIGA: 35;
+  readonly ATARI_ST: 36;
+  readonly AMSTRAD_PC: 37;
+  readonly APPLE_II: 38;
+  readonly SATURN: 39;
+  readonly DREAMCAST: 40;
+  readonly PSP: 41;
+  readonly CDI: 42;
+  readonly THREEDO: 43;
+  readonly COLECOVISION: 44;
+  readonly INTELLIVISION: 45;
+  readonly VECTREX: 46;
+  readonly PC8800: 47;
+  readonly PC9800: 48;
+  readonly PCFX: 49;
+  readonly ATARI_5200: 50;
+  readonly ATARI_7800: 51;
+  readonly X68K: 52;
+  readonly WONDERSWAN: 53;
+  readonly CASSETTEVISION: 54;
+  readonly SUPER_CASSETTEVISION: 55;
+  readonly NEO_GEO_CD: 56;
+  readonly FAIRCHILD_CHANNEL_F: 57;
+  readonly FM_TOWNS: 58;
+  readonly ZX_SPECTRUM: 59;
+  readonly GAME_AND_WATCH: 60;
+  readonly NOKIA_NGAGE: 61;
+  readonly NINTENDO_3DS: 62;
+  readonly SUPERVISION: 63;
+  readonly SHARPX1: 64;
+  readonly TIC80: 65;
+  readonly THOMSONTO8: 66;
+  readonly PC6000: 67;
+  readonly PICO: 68;
+  readonly MEGADUCK: 69;
+  readonly ZEEBO: 70;
+  readonly ARDUBOY: 71;
+  readonly WASM4: 72;
+  readonly ARCADIA_2001: 73;
+  readonly INTERTON_VC_4000: 74;
+  readonly ELEKTOR_TV_GAMES_COMPUTER: 75;
+  readonly PC_ENGINE_CD: 76;
+  readonly ATARI_JAGUAR_CD: 77;
+  readonly NINTENDO_DSI: 78;
+  readonly TI83: 79;
+  readonly UZEBOX: 80;
+  readonly FAMICOM_DISK_SYSTEM: 81;
+  readonly HUBS: 100;
+  readonly EVENTS: 101;
+  readonly STANDALONE: 102;
+};
+
+/**
+ * Valid console ID values for the rhash function.
+ * This is the union of all values in the ConsoleId object.
+ */
+export type ConsoleIdValue = typeof ConsoleId[keyof typeof ConsoleId];
+
 /**
  * Generate a hash for a ROM file using the RetroAchievements algorithm.
  *
- * @param consoleId - The RetroAchievements console ID (e.g., 41 for PSP)
+ * @param consoleId - The RetroAchievements console ID
  * @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
@@ -9,15 +114,15 @@
  *
  * @example
  * ```typescript
- * import { rhash } from 'node-rcheevos';
+ * import { rhash, ConsoleId } from 'node-rcheevos';
  * import { readFileSync } from 'fs';
  *
- * // Hash from file
- * const md5 = rhash(41, '/path/to/game.iso');
+ * // Hash from file using ConsoleId constant or use literal numbers
+ * const md5 = rhash(ConsoleId.PSP, '/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);
+ * const md5 = rhash(ConsoleId.PSP, '/path/to/game.iso', buffer);
  * ```
  */
-export function rhash(consoleId: number, path: string, buffer?: Buffer): string;
+export function rhash(consoleId: ConsoleIdValue, path: string, buffer?: Buffer): string;

package/lib/index.js

@@ -1,5 +1,94 @@
 const addon = require('node-gyp-build')(__dirname + '/..');
 
+const ConsoleId = {
+  UNKNOWN: 0,
+  MEGA_DRIVE: 1,
+  NINTENDO_64: 2,
+  SUPER_NINTENDO: 3,
+  GAMEBOY: 4,
+  GAMEBOY_ADVANCE: 5,
+  GAMEBOY_COLOR: 6,
+  NINTENDO: 7,
+  PC_ENGINE: 8,
+  SEGA_CD: 9,
+  SEGA_32X: 10,
+  MASTER_SYSTEM: 11,
+  PLAYSTATION: 12,
+  ATARI_LYNX: 13,
+  NEOGEO_POCKET: 14,
+  GAME_GEAR: 15,
+  GAMECUBE: 16,
+  ATARI_JAGUAR: 17,
+  NINTENDO_DS: 18,
+  WII: 19,
+  WII_U: 20,
+  PLAYSTATION_2: 21,
+  XBOX: 22,
+  MAGNAVOX_ODYSSEY2: 23,
+  POKEMON_MINI: 24,
+  ATARI_2600: 25,
+  MS_DOS: 26,
+  ARCADE: 27,
+  VIRTUAL_BOY: 28,
+  MSX: 29,
+  COMMODORE_64: 30,
+  ZX81: 31,
+  ORIC: 32,
+  SG1000: 33,
+  VIC20: 34,
+  AMIGA: 35,
+  ATARI_ST: 36,
+  AMSTRAD_PC: 37,
+  APPLE_II: 38,
+  SATURN: 39,
+  DREAMCAST: 40,
+  PSP: 41,
+  CDI: 42,
+  THREEDO: 43,
+  COLECOVISION: 44,
+  INTELLIVISION: 45,
+  VECTREX: 46,
+  PC8800: 47,
+  PC9800: 48,
+  PCFX: 49,
+  ATARI_5200: 50,
+  ATARI_7800: 51,
+  X68K: 52,
+  WONDERSWAN: 53,
+  CASSETTEVISION: 54,
+  SUPER_CASSETTEVISION: 55,
+  NEO_GEO_CD: 56,
+  FAIRCHILD_CHANNEL_F: 57,
+  FM_TOWNS: 58,
+  ZX_SPECTRUM: 59,
+  GAME_AND_WATCH: 60,
+  NOKIA_NGAGE: 61,
+  NINTENDO_3DS: 62,
+  SUPERVISION: 63,
+  SHARPX1: 64,
+  TIC80: 65,
+  THOMSONTO8: 66,
+  PC6000: 67,
+  PICO: 68,
+  MEGADUCK: 69,
+  ZEEBO: 70,
+  ARDUBOY: 71,
+  WASM4: 72,
+  ARCADIA_2001: 73,
+  INTERTON_VC_4000: 74,
+  ELEKTOR_TV_GAMES_COMPUTER: 75,
+  PC_ENGINE_CD: 76,
+  ATARI_JAGUAR_CD: 77,
+  NINTENDO_DSI: 78,
+  TI83: 79,
+  UZEBOX: 80,
+  FAMICOM_DISK_SYSTEM: 81,
+  HUBS: 100,
+  EVENTS: 101,
+  STANDALONE: 102
+};
+
 module.exports = {
-  rhash: addon.rhash
+  rhash: addon.rhash,
+  ConsoleId
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-rcheevos",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Node.js native bindings for RetroAchievements rcheevos library (hash generation)",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",