@kikuchan/binary-reader/README.md

binary-reader

# @kikuchan/binary-reader

Small binary buffer reader for streaming-style, cursor-based parsing in Node.js and browsers.

## Install

```bash
npm install -D @kikuchan/binary-reader
```

## Quick Start

```ts
import { BinaryReader } from '@kikuchan/binary-reader';

const u8 = new Uint8Array([0x12, 0x34, 0x89, 0xab, 0xcd, 0xef]);
const r = new BinaryReader(u8); // default: big-endian

r.readUint16();     // 0x1234 (BE)
r.readUint32();     // 0x89ABCDEF (BE)

// Force endian per read
r.seek(0);
r.readUint16le();   // 0x3412

// Strings
const s = new BinaryReader(new TextEncoder().encode('Hi\0A'));
s.readString();     // 'Hi' (C-string, consumes trailing NUL)
s.readUint8();      // 0x41 ('A')

// Raw bytes
const r2 = new BinaryReader(new Uint8Array([1,2,3,4]));
const bytes = r2.peekBytes(2); // Uint8Array [1,2], does not advance
const next  = r2.readBytes(3); // Uint8Array [1,2,3], advances by 3
```

## API

- Position/state:
  - `position`, `size`, `remain`, `eof()`
  - `seek(n | label)`, `bookmark(label)`, `rewind()`, `skip(n?)`, `align(n)`

- Unsigned integers:
  - Base: `readUint8()`, `readUint16(le?)`, `readUint32(le?)`, `readUint64(le?)`
  - Suffix aliases: `readUint16le/be()`, `readUint32le/be()`, `readUint64le/be()`

- Signed integers:
  - Base: `readInt8()`, `readInt16(le?)`, `readInt32(le?)`, `readInt64(le?)`
  - Suffix aliases: `readInt16le/be()`, `readInt32le/be()`, `readInt64le/be()`

- Floating-point:
  - Base: `readFloat16(le?)`, `readFloat32(le?)`, `readFloat64(le?)`
  - Suffix aliases: `readFloat16le/be()`, `readFloat32le/be()`, `readFloat64le/be()`

- Bytes and strings:
  - `peekBytes(n?) -> Uint8Array` — peek without advancing (default: all remaining)
  - `readBytes(n?) -> Uint8Array` — read bytes and advance (default: all remaining)
  - `readString(len?, encoding?) -> string | undefined`
    - `len` omitted: C-string (null-terminated). Missing terminator returns `undefined` and does not advance.
    - `len` provided: reads exactly `len` bytes; decode failure returns `undefined` and does not advance.

## Endianness

- Default endianness is big-endian.
- You can set a default via constructor: `new BinaryReader(u8, { littleEndian: true })`.
- Per-call overrides use either the second param (e.g. `readUint16(true)`) or the `le/be` suffix methods.

## Notes

- Streaming-focused: the API models a moving cursor over a buffer. Methods read at the cursor and advance.
- `seek()` and `skip()` clamp positions to `[0, size]`.