Accept Uint8Array and ArrayBuffer in loadROM()

ROM.load() previously only accepted binary strings, requiring users to
do roundabout conversions from typed arrays. Now accepts Uint8Array,
ArrayBuffer, Node.js Buffer, and binary strings directly.

Fixes #454

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bfirsh

src/nes.d.ts

@@ -29,7 +29,7 @@ export class NES {
   zapperFireUp: () => void;
   getFPS: () => number;
   reloadROM: () => void;
-  loadROM: (data: string | Buffer) => void;
+  loadROM: (data: string | Buffer | Uint8Array | ArrayBuffer) => void;
   setFramerate: (rate: number) => void;
   toJSON: () => EmulatorData;
   fromJSON: (data: EmulatorData) => void;

src/rom.js

@@ -64,12 +64,31 @@ class ROM {
   load(data) {
     let i, j, v;
 
-    if (!data.startsWith("NES\x1a")) {
-      throw new Error("Not a valid NES ROM.");
+    // Accept Uint8Array, ArrayBuffer, Buffer, or binary string.
+    if (data instanceof ArrayBuffer) {
+      data = new Uint8Array(data);
     }
+    const isTypedArray = ArrayBuffer.isView(data);
+
+    if (isTypedArray) {
+      if (
+        data.length < 4 ||
+        data[0] !== 0x4e ||
+        data[1] !== 0x45 ||
+        data[2] !== 0x53 ||
+        data[3] !== 0x1a
+      ) {
+        throw new Error("Not a valid NES ROM.");
+      }
+    } else {
+      if (!data.startsWith("NES\x1a")) {
+        throw new Error("Not a valid NES ROM.");
+      }
+    }
+
     this.header = new Uint8Array(16);
     for (i = 0; i < 16; i++) {
-      this.header[i] = data.charCodeAt(i) & 0xff;
+      this.header[i] = isTypedArray ? data[i] : data.charCodeAt(i) & 0xff;
     }
     this.romCount = this.header[4];
     this.vromCount = this.header[5] * 2; // Get the number of 4kB banks, not 8kB
@@ -101,7 +120,9 @@ class ROM {
         if (offset + j >= data.length) {
           break;
         }
-        this.rom[i][j] = data.charCodeAt(offset + j) & 0xff;
+        this.rom[i][j] = isTypedArray
+          ? data[offset + j]
+          : data.charCodeAt(offset + j) & 0xff;
       }
       offset += 16384;
     }
@@ -113,7 +134,9 @@ class ROM {
         if (offset + j >= data.length) {
           break;
         }
-        this.vrom[i][j] = data.charCodeAt(offset + j) & 0xff;
+        this.vrom[i][j] = isTypedArray
+          ? data[offset + j]
+          : data.charCodeAt(offset + j) & 0xff;
       }
       offset += 4096;
     }

test/nes.spec.js

@@ -36,13 +36,49 @@ describe("NES", function() {
     }
   });
 
+  it("loads a ROM from a Uint8Array and runs a frame", function() {
+    let onFrame = mock.fn();
+    let nes = new NES({ onFrame: onFrame });
+    let data = fs.readFileSync("roms/croom/croom.nes");
+    nes.loadROM(new Uint8Array(data));
+    nes.frame();
+    assert.strictEqual(onFrame.mock.callCount(), 1);
+    assert.ok(onFrame.mock.calls[0].arguments[0] instanceof Uint32Array);
+    assert.strictEqual(onFrame.mock.calls[0].arguments[0].length, 256 * 240);
+  });
+
+  it("produces the same frame buffer from Uint8Array and string", function() {
+    let stringFrames = [];
+    let nes1 = new NES({ onFrame: (buf) => stringFrames.push(buf.slice()) });
+    let data = fs.readFileSync("roms/croom/croom.nes");
+    nes1.loadROM(data.toString("binary"));
+    for (let i = 0; i < 6; i++) nes1.frame();
+
+    let uint8Frames = [];
+    let nes2 = new NES({ onFrame: (buf) => uint8Frames.push(buf.slice()) });
+    nes2.loadROM(new Uint8Array(data));
+    for (let i = 0; i < 6; i++) nes2.frame();
+
+    assert.strictEqual(stringFrames.length, uint8Frames.length);
+    for (let i = 0; i < stringFrames.length; i++) {
+      assert.deepStrictEqual(stringFrames[i], uint8Frames[i]);
+    }
+  });
+
   describe("#loadROM()", function() {
-    it("throws an error given an invalid ROM", function() {
+    it("throws an error given an invalid ROM string", function() {
       let nes = new NES();
       assert.throws(function() {
         nes.loadROM("foo");
       }, { message: "Not a valid NES ROM." });
     });
+
+    it("throws an error given an invalid ROM Uint8Array", function() {
+      let nes = new NES();
+      assert.throws(function() {
+        nes.loadROM(new Uint8Array([0x66, 0x6f, 0x6f]));
+      }, { message: "Not a valid NES ROM." });
+    });
   });
 
   describe("#frame() with invalid opcode", function() {