Class BinaryReader

packages/core/src/binary/reader.ts:26–121

 * The buffer must remain valid and unmodified for the reader's lifetime.
 */
export class BinaryReader {
  private readonly bytes: Uint8Array;
  private readonly dv: DataView;
  private off = 0;

  constructor(bytes: Uint8Array) {
    this.bytes = bytes;
    this.dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
  }

  get offset(): number {
    return this.off;
  }

  get byteLength(): number {
    return this.bytes.byteLength;
  }

  get remaining(): number {
    return this.byteLength - this.off;
  }

  /** Validate that offset is 4-byte aligned; throws ZR_MISALIGNED on violation. */
  ensureAligned4(offset: number = this.off): void {
    if ((offset & 3) !== 0) {
      throw new ZrBinaryError({
        code: "ZR_MISALIGNED",
        offset,
        detail: "offset must be 4-byte aligned",
      });
    }
  }

  /** Advance cursor by len bytes without reading; validates bounds first. */
  skip(len: number): void {
    if (!Number.isInteger(len) || len < 0) {
      throw new Error(`BinaryReader.skip: len must be a non-negative integer (got ${String(len)})`);
    }
    this.ensureAvailable(len);
    this.off += len;
  }

  /** Read unsigned 8-bit integer, advancing cursor by 1 byte. */
  readU8(): number {
    this.ensureAvailable(1);
    const v = this.dv.getUint8(this.off);
    this.off += 1;
    return v;
  }

  /** Read unsigned 32-bit integer (little-endian), advancing cursor by 4 bytes. */
  readU32(): number {
    this.ensureAvailable(4);
    const v = this.dv.getUint32(this.off, true);
    this.off += 4;
    return v;
  }