ihex

Parse Intel HEX files and load them into a Buffer.

• Zero runtime dependencies (drops the abandoned line-reader).
• ESM, with full TypeScript declarations.
• Handles all standard record types (data, EOF, ESA, ELA, start-segment, start-linear).
• Throws on malformed lines, checksum failures, and bounds violations (configurable).

Install

npm install ihex

Quick start

import { parseFile, applyRecordsToBuffer, loadFileIntoBuffer } from 'ihex';

// One-liner: parse a .hex and write it into a Buffer.
const buf = Buffer.alloc(64 * 1024);
const highWaterMark = await loadFileIntoBuffer('firmware.hex', buf);
console.log(`Wrote ${highWaterMark} bytes`);

// Or operate on records directly.
const records = await parseFile('firmware.hex');
for (const r of records) {
  // r.byteCount, r.address, r.type, r.data
}
applyRecordsToBuffer(records, buf);

API

parseFile(filename): Promise<IHexRecord[]>

Read a HEX file from disk and parse its records.

parseString(content): IHexRecord[]

Parse HEX content from a string or Buffer. Blank lines are skipped.

parseLine(line, lineNumber?): IHexRecord

Parse a single trimmed HEX line. Throws an IHexParseError on bad input.

applyRecordsToBuffer(records, buffer, opts?): number

Apply parsed records to a Buffer, honoring ExtendedLinearAddress and ExtendedSegmentAddress records. Stops at the first EndOfFile record by default. Returns the highest byte offset written.

Options:

• stopAtEOF (default true): stop processing at the EOF record.
• strictBounds (default true): throw if a data record would write past the buffer; when false, the offending bytes are silently truncated.

loadFileIntoBuffer(filename, buffer, opts?): Promise<number>

Convenience: parseFile + applyRecordsToBuffer in one call.

IHexRecordType

Enum-like object: Data, EndOfFile, ExtendedSegmentAddress, StartSegmentAddress, ExtendedLinearAddress, StartLinearAddress.

IHexParseError

Subclass of Error carrying lineNumber and line fields.

Migrating from 0.x

The 0.x API was a single callback-style function:

const ihex = require('ihex');
ihex('firmware.hex', buf, () => { /* done */ });

In 1.0:

import { loadFileIntoBuffer } from 'ihex';
await loadFileIntoBuffer('firmware.hex', buf);

Beyond the surface change, 1.0 also fixes several bugs in the original:

• Uses Buffer.from() instead of the deprecated and unsafe new Buffer().
• Honors ExtendedLinearAddress records, so files larger than 64 KB load to the correct addresses (the 0.x code silently ignored them).
• Throws on malformed lines and checksum failures instead of console.log-ing and continuing.
• Stops at the EndOfFile record instead of silently mishandling it.

Requirements

• Node.js >= 22.

License

ISC.