roomie 1.0.2 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nicolás Contreras
+
+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

@@ -1,15 +1,44 @@
 # roomie
 
-Roomie is a library for analyzing basic metadata of ROM files from various classic consoles. It allows extracting relevant information such as the game name, region, code, ROM and RAM size, version, and other console-specific data.
+![GitHub Sponsors](https://img.shields.io/github/sponsors/nikitacontreras?style=flat-square&label=sponsor%20me&link=https%3A%2F%2Fgithub.com%2Fsponsors%2Fnikitacontreras) ![NPM Version](https://img.shields.io/npm/v/roomie?style=flat-square)
+
+---
+
+## Introduction
+
+**roomie** is a lightweight library for extracting metadata from ROM files of classic gaming consoles. It supports multiple systems and provides detailed information such as game title, region, game code, ROM and RAM sizes, version, and other console-specific data. Designed for simplicity and accuracy, roomie aids developers and enthusiasts in analyzing ROM files programmatically.
+
+---
 
 ## Installation
 
+Install via npm:
+
 ```bash
 npm install roomie
 ```
 
+---
+
 ## Usage
 
+roomie supports both CommonJS (CJS) and ES Modules (ESM) import styles.
+
+### CommonJS (CJS)
+
+```js
+const Roomie = require("roomie");
+
+const romPath = "/path/to/game.sfc";
+const roomie = new Roomie(romPath);
+
+roomie.on("loaded", (info) => {
+  console.log("ROM Information:", info);
+});
+```
+
+### ES Modules (ESM)
+
 ```ts
 import Roomie from "roomie";
 
@@ -28,24 +57,72 @@ await roomie.load(romBuffer);
 console.log(roomie.info);
 ```
 
+---
+
 ## Supported Consoles
 
-Roomie supports metadata extraction from the following systems:
+| Console                     | Description                                                   |
+|-----------------------------|---------------------------------------------------------------|
+| **Nintendo DS (NDS)**        | Extracts game name, region, game code, ROM/RAM size, version, and other metadata. |
+| **Game Boy Advance (GBA)**   | Provides title, game code, region, ROM/RAM size, version, and related info.       |
+| **Game Boy (GB)**            | Retrieves title, cartridge type, ROM/RAM size, and additional metadata.          |
+| **Super Nintendo / Super Famicom (SNES/SFC)** | Detects ROM type (HiROM/LoROM), game name, region, code, ROM size, and console-specific fields. |
+
+---
+
+## API Reference
+
+### Constructor
+
+```ts
+new Roomie(pathOrBuffer: string | Buffer)
+```
+
+Creates a new Roomie instance and immediately loads the ROM from the given file path or Buffer. Emits the `'loaded'` event once metadata extraction is complete.
+
+### Methods
+
+```ts
+await roomie.load(pathOrBuffer: string | Buffer): Promise<void>
+```
+
+Loads or reloads a ROM from a file path or Buffer, emitting `'loaded'` on success.
+
+### Properties
+
+- `roomie.info: RomInfo` – Object containing extracted ROM metadata.
+- `roomie.rom: Buffer` – Raw bytes of the loaded ROM.
+- `roomie.system: "nds" | "gba" | "gb" | "sfc"` – Detected console system.
+
+### Events
+
+- `'loaded'` – Emitted when ROM metadata is successfully loaded and parsed. The listener receives the `info` object.
+
+### Example JSON Output
+
+```json
+{
+  "system": "gba",
+  "title": "METROID FUSION",
+  "gameCode": "AGB-AMME",
+  "region": "USA",
+  "romSize": 2097152,
+  "ramSize": 32768,
+  "version": 1,
+  "checksum": "0x1234"
+}
+```
+
+---
 
-- **Nintendo DS (NDS):** Retrieves data such as the game name, region, game code, ROM and RAM size, version, among others.
-- **Game Boy Advance (GBA):** Extracts information about the title, game code, region, ROM and RAM size, version, etc.
-- **Game Boy (GB):** Provides details about the title, cartridge type, ROM and RAM size, and other metadata.
-- **Super Nintendo / Super Famicom (SNES/SFC):** Detects the ROM type (HiROM/LoROM), game name, region, code, ROM size, and other specific fields.
+## Error Handling
 
-## API
+If the ROM cannot be identified, the library throws errors with codes:
 
-- `new Roomie(path: string | Buffer)` – Creates an instance and immediately loads the specified ROM file or buffer. Emits the `'loaded'` event when the information is available.
-- `await roomie.load(pathOrBuffer: string | Buffer)` – Loads or reloads a different ROM file from a file path or a Buffer.
-- `roomie.info: RomInfo` – Object with the analyzed ROM metadata, including system, size, game code, region, and other specific fields.
-- `roomie.rom: Buffer` – Contains the raw bytes of the loaded ROM file.
-- `roomie.system: "nds" | "gba" | "gb" | "sfc"` – Detected system based on the file extension and content.
+- `unknown_file` – When loading from a file path and the system is unrecognized.
+- `unknown_bytes` – When loading from a Buffer and the system is unrecognized.
 
-If the system cannot be identified, the library throws errors with codes `unknown_file` (when loading from a path) or `unknown_bytes` (when loading from a Buffer).
+---
 
 ## License
 

package/dist/index.cjs

@@ -1 +1,4 @@
-module.exports = require("./index.mjs");
+
+const mod = require("./index.mjs");
+module.exports = mod.default || mod;
+module.exports.default = mod.default || mod;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
-export { Roomie as default } from "./roomie";
-export * from "./roomie";
-export * from "./types";
+import Roomie from "./roomie.js";
+export default Roomie;
+export * from "./roomie.js";
+export * from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
-export { Roomie as default } from "./roomie";
-export * from "./roomie";
-export * from "./types";
+import Roomie from "./roomie.js";
+export default Roomie;
+export * from "./roomie.js";
+export * from "./types.js";

package/dist/index.mjs

@@ -1,3 +1,4 @@
-export { Roomie as default } from "./roomie";
-export * from "./roomie";
-export * from "./types";
+import Roomie from "./roomie.js";
+export default Roomie;
+export * from "./roomie.js";
+export * from "./types.js";

package/dist/roomie.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "node:events";
-import type { SupportedSystem } from "./types";
+import type { SupportedSystem } from "./types.js";
 export interface RomInfo {
     path: string;
     system: SupportedSystem;
@@ -19,17 +19,32 @@ export interface RomInfo {
         ram?: number;
         hardware?: Record<string, unknown>;
     };
+    n64?: {
+        name?: string;
+        country?: string;
+        version?: string;
+    };
 }
 export declare class Roomie extends EventEmitter {
     private _path;
     private _rom;
     private _system;
     private _info;
+    name?: string;
+    gameid?: string;
+    region?: string;
+    gamecode?: string;
+    cartridge?: Record<string, unknown>;
     constructor(path: string);
     private detectSystemFromPath;
     private readGameCode;
     private computeRegion;
     private computeSfcInfo;
+    private _name;
+    private _gameid;
+    private _gamecode;
+    private _cartridge;
+    private _region;
     load(pathOrBuffer: string | Buffer): Promise<void>;
     get info(): RomInfo;
     get system(): SupportedSystem;

package/dist/roomie.js

@@ -1,9 +1,9 @@
 import { EventEmitter } from "node:events";
 import { createHash } from "node:crypto";
 import { promises as fs } from "node:fs";
-import { regions } from "./tables/regions";
-import { specs } from "./tables/specs";
-import { isHiRomBuffer } from "./systems/snes";
+import { regions } from "./tables/regions.js";
+import { specs } from "./tables/specs.js";
+import { isHiRomBuffer } from "./systems/snes.js";
 export class Roomie extends EventEmitter {
     constructor(path) {
         super();
@@ -19,6 +19,8 @@ export class Roomie extends EventEmitter {
             return "gb";
         if (ext === "sfc" || ext === "smc")
             return "sfc";
+        if (ext === "z64" || ext === "n64")
+            return "n64";
         // Default to sfc to keep compatibility with original intent; could be improved.
         return "sfc";
     }
@@ -34,6 +36,9 @@ export class Roomie extends EventEmitter {
             if (system === "gb" && b.length >= 0x0143) {
                 return b.subarray(0x013F, 0x0143).toString("ascii");
             }
+            if (system === "n64" && b.length >= 0x2F) {
+                return b.subarray(0x20, 0x2F).toString("ascii").trim();
+            }
         }
         catch { }
         return undefined;
@@ -66,40 +71,224 @@ export class Roomie extends EventEmitter {
                     return regions.snes[key];
                 }
                 return undefined;
+            case "n64":
+                // N64 region code at offset 0x3E in some ROMs (common practice)
+                if (this._rom.length > 0x3E) {
+                    const regionByte = this._rom[0x3E];
+                    // Map region byte to region string (basic example)
+                    const regionMap = {
+                        0x44: "USA",
+                        0x45: "Europe",
+                        0x46: "France",
+                        0x4A: "Japan",
+                        0x50: "PAL",
+                        0x55: "Australia",
+                        0x58: "Germany",
+                        0x59: "Europe",
+                        0x5A: "Europe",
+                    };
+                    return regionMap[regionByte] || "Unknown";
+                }
+                return undefined;
         }
     }
     computeSfcInfo() {
         if (this._system !== "sfc")
             return undefined;
         const hi = isHiRomBuffer(this._rom);
-        const base = hi ? 0xFFD0 : 0x7FD0; // region/speed map nearby
-        const romspeedOff = base + 0x09; // D9
-        const romTypeOff = base + 0x05; // D5
-        const romSizeOff = base + 0x07; // D7
-        const ramSizeOff = base + 0x08; // D8
+        const base = hi ? 0xFFD0 : 0x7FD0;
+        const offD5 = base + 0x05; // map mode (for specs mapping)
+        const offD6 = base + 0x06; // hardware type
+        const offD7 = base + 0x07; // ROM size exponent
+        const offD8 = base + 0x08; // RAM size exponent
+        const offD9 = base + 0x09; // raw romSpeed byte
         const out = {};
-        if (this._rom.length > romspeedOff) {
-            const key = this._rom[romspeedOff].toString(16);
-            out.romSpeed = key;
+        // romSpeed: raw D9 byte as string, like original JS
+        if (this._rom.length > offD9) {
+            out.romSpeed = this._rom[offD9].toString().trim();
+        }
+        // specs: map D5 (2-digit hex) to specs.sfc.romspeed
+        if (this._rom.length > offD5) {
+            const key = this._rom[offD5].toString(16).padStart(2, "0");
             const spec = specs.sfc?.romspeed?.[key];
             if (spec)
                 out.rom = { ...(out.rom || {}), type: spec.type, speed: spec.speed };
         }
-        if (this._rom.length > romTypeOff) {
-            const hwKey = this._rom[romTypeOff].toString(16);
+        // rom size from D7 using original expression
+        if (this._rom.length > offD7) {
+            const exp = this._rom[offD7];
+            const size = 2 ** (2 ^ exp) * 1000;
+            out.rom = { ...(out.rom || {}), size };
+        }
+        // ram size from D8 using original expression
+        if (this._rom.length > offD8) {
+            const exp = this._rom[offD8];
+            out.ram = 2 ** (2 ^ exp) * 1000;
+        }
+        // hardware from D6 (2-digit hex)
+        if (this._rom.length > offD6) {
+            const hwKey = this._rom[offD6].toString(16).padStart(2, "0");
             const hw = specs.sfc?.hardware?.[hwKey];
             if (hw)
                 out.hardware = hw;
         }
-        if (this._rom.length > romSizeOff) {
-            const exp = this._rom[romSizeOff];
-            out.rom = { ...(out.rom || {}), size: Math.pow(2, exp) * 1024 };
+        return out;
+    }
+    _name() {
+        const b = this._rom;
+        try {
+            switch (this._system) {
+                case "nds":
+                    if (b.length >= 0x20) {
+                        return b.subarray(0x0, 0x20).toString("ascii").replace(/\0/g, "").trim();
+                    }
+                    break;
+                case "gba":
+                    if (b.length >= 0xAC) {
+                        return b.subarray(0xA0, 0xAC).toString("ascii").replace(/\0/g, "").trim();
+                    }
+                    break;
+                case "gb":
+                    if (b.length >= 0x134) {
+                        return b.subarray(0x134, 0x144).toString("ascii").replace(/\0/g, "").trim();
+                    }
+                    break;
+                case "sfc":
+                    // SNES title at 0x7FC0 or 0xFFC0 depending on LoROM/HiROM
+                    const hi = isHiRomBuffer(b);
+                    const base = hi ? 0xFFC0 : 0x7FC0;
+                    if (b.length > base + 21) {
+                        return b.subarray(base, base + 21).toString("ascii").replace(/\0/g, "").trim();
+                    }
+                    break;
+                case "n64":
+                    if (b.length >= 0x20) {
+                        return b.subarray(0x20, 0x34).toString("ascii").replace(/\0/g, "").trim();
+                    }
+                    break;
+            }
         }
-        if (this._rom.length > ramSizeOff) {
-            const exp = this._rom[ramSizeOff];
-            out.ram = Math.pow(2, exp) * 1024;
+        catch { }
+        return undefined;
+    }
+    _gameid() {
+        const code = this._gamecode();
+        if (!code)
+            return undefined;
+        switch (this._system) {
+            case "nds":
+                return "NTR-" + code;
+            case "gba":
+                return "AGB-" + code;
+            default:
+                return undefined;
         }
-        return out;
+    }
+    _gamecode() {
+        const b = this._rom;
+        try {
+            switch (this._system) {
+                case "nds":
+                    if (b.length >= 0x10) {
+                        return b.subarray(0x0C, 0x10).toString("ascii");
+                    }
+                    break;
+                case "gba":
+                    if (b.length >= 0xB0) {
+                        return b.subarray(0xAC, 0xB0).toString("ascii");
+                    }
+                    break;
+                case "gb":
+                    if (b.length >= 0x0143) {
+                        return b.subarray(0x013F, 0x0143).toString("ascii");
+                    }
+                    break;
+                case "n64":
+                    if (b.length >= 0x2F) {
+                        return b.subarray(0x20, 0x2F).toString("ascii").trim();
+                    }
+                    break;
+            }
+        }
+        catch { }
+        return undefined;
+    }
+    _cartridge() {
+        // Build cartridge metadata depending on system
+        const b = this._rom;
+        switch (this._system) {
+            case "nds": {
+                const code = this._gamecode();
+                const region = this._region();
+                return {
+                    system: "nds",
+                    gameCode: code,
+                    region,
+                    size: b.length,
+                };
+            }
+            case "gba": {
+                const code = this._gamecode();
+                const region = this._region();
+                return {
+                    system: "gba",
+                    gameCode: code,
+                    region,
+                    size: b.length,
+                };
+            }
+            case "gb": {
+                const region = this._region();
+                return {
+                    system: "gb",
+                    region,
+                    size: b.length,
+                };
+            }
+            case "sfc": {
+                const sfcInfo = this.computeSfcInfo();
+                return {
+                    system: "sfc",
+                    ...sfcInfo,
+                    size: b.length,
+                };
+            }
+            case "n64": {
+                // N64 cartridge info from header bytes
+                const countryByte = b.length > 0x3E ? b[0x3E] : undefined;
+                const versionByte = b.length > 0x3F ? b[0x3F] : undefined;
+                const countryMap = {
+                    0x00: "Japan",
+                    0x01: "USA",
+                    0x02: "Europe",
+                    0x03: "Germany",
+                    0x04: "France",
+                    0x05: "Spain",
+                    0x06: "Italy",
+                    0x07: "China",
+                    0x08: "Australia",
+                    0x09: "Unknown",
+                    0x0A: "Unknown",
+                    0x0B: "Unknown",
+                    0x0C: "Unknown",
+                    0x0D: "Unknown",
+                    0x0E: "Unknown",
+                    0x0F: "Unknown",
+                };
+                return {
+                    system: "n64",
+                    name: this._name(),
+                    country: countryByte !== undefined ? countryMap[countryByte] || "Unknown" : undefined,
+                    version: versionByte !== undefined ? versionByte.toString() : undefined,
+                    size: b.length,
+                };
+            }
+            default:
+                return undefined;
+        }
+    }
+    _region() {
+        return this.computeRegion(this._system, this._gamecode());
     }
     async load(pathOrBuffer) {
         if (typeof pathOrBuffer === "string") {
@@ -136,6 +325,13 @@ export class Roomie extends EventEmitter {
                     detected = "gb";
                 }
             }
+            // Check N64: ASCII text at 0x20-0x2E
+            if (!detected && b.length >= 0x2F) {
+                const code = b.subarray(0x20, 0x2F).toString("ascii");
+                if (/^[\x20-\x7E]+$/.test(code) && code.trim().length > 0) {
+                    detected = "n64";
+                }
+            }
             // Check SFC: use isHiRomBuffer heuristic
             if (!detected) {
                 if (b.length > 0x8000 && (isHiRomBuffer(b) || !isHiRomBuffer(b))) {
@@ -160,7 +356,19 @@ export class Roomie extends EventEmitter {
         if (this._system === "sfc") {
             info.sfc = this.computeSfcInfo();
         }
+        if (this._system === "n64") {
+            info.n64 = {
+                name: this._name(),
+                country: this._region(),
+                version: this._rom.length > 0x3F ? this._rom[0x3F].toString() : undefined,
+            };
+        }
         this._info = info;
+        this.name = this._name();
+        this.gameid = this._gameid();
+        this.region = this._region();
+        this.gamecode = this._gamecode();
+        this.cartridge = this._cartridge();
         this.emit("loaded", info);
     }
     get info() { return this._info; }

package/dist/types.d.ts

@@ -1 +1 @@
-export type SupportedSystem = "nds" | "gba" | "gb" | "sfc";
+export type SupportedSystem = "nds" | "gba" | "gb" | "sfc" | "n64";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roomie",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "ROM metadata helper",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,7 @@
     ".": {
       "require": "./dist/index.cjs",
       "import": "./dist/index.mjs",
-      "types": "./dist/index.d.ts"
+      "default": "./dist/index.mjs"
     }
   },
   "engines": {