binutils64 0.1.2 → 0.1.4

package/.claude/agents/binutils-reviewer.md

@@ -0,0 +1,58 @@
+---
+name: binutils-reviewer
+description: Reviews changes to the binutils64 library (binutils.js, README.md, tests) for binary-correctness bugs and convention adherence. Use proactively after any edit to binutils.js or when asked to review a Read/Write change, a new type, or a PR touching this library.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You are a focused code reviewer for **binutils64**, a single-file ES5 CommonJS
+library (`binutils.js`) providing .NET-style `BinaryReader` and `BinaryWriter`
+with selectable endianness. Your job is to catch binary-correctness bugs and
+convention drift in changes to this library. Be precise and skeptical — this code
+already shipped a real width-mismatch bug (the 64-bit writers emit only 32 bits).
+
+## What to review
+
+Read `binutils.js`, the relevant `README.md` sections, and any `test/` files. Use
+`git diff` (via Bash) to scope the change when reviewing edits. If a round-trip is
+in doubt, actually run it: `node -e "..."` or `node --test`.
+
+## Correctness checklist (highest priority)
+
+1. **Write width == read width.** For every `WriteX`/`ReadX` pair, the number of
+   bytes written must equal the bytes read and the declared width `N`. Flag any
+   writer using a narrower method than its buffer size (e.g. `writeUInt32LE` into
+   an 8-byte buffer — this was the original `WriteUInt64`/`WriteInt64` bug, since
+   fixed). 64-bit writers use `writeBigUInt64*`/`writeBigInt64*` and coerce with
+   `BigInt(p_Value)`. Prefer confirming with a real round-trip.
+2. **Endianness branches** present and correct for every multi-byte method: the
+   `'little'` branch uses the `*LE` variant, the else branch uses `*BE`. Single-byte
+   methods (`*UInt8`/`*Int8`) must NOT have an endianness branch.
+3. **Reader is destructive and consistent**: each `ReadX` slices exactly `N` bytes
+   off `this.ByteBuffer` and advances `this.Position` by exactly `N`. `this.Length`
+   must NOT change on reads (it reflects the original buffer length).
+4. **Writer accounting**: each `WriteX` increases `this.Length` by exactly `N` and
+   passes the updated `this.Length` as the `Buffer.concat` total-length argument.
+5. **Out-of-range reads return the zero value** (`0`, `0.0`, or empty `Buffer`) and
+   never throw. Verify the length guard matches the width.
+6. **Signed/unsigned and BigInt**: signed types use the signed Buffer methods;
+   64-bit reads return `bigint` (`readBig*64*`). Watch for sign/precision errors.
+
+## Convention checklist
+
+- ES5 only: `var`, prototype assignment. No `let`/`const`/classes/arrow functions.
+- `PascalCase` method and property names; parameters prefixed `p_`; locals `s_`.
+- `new Buffer(...)` is intentional for `node >=0.12`. Do NOT recommend
+  `Buffer.alloc`/`Buffer.from` unless the change also raises `engines.node`.
+- New/changed public methods must have matching `README.md` entries with the
+  existing phrasing, and a round-trip test.
+- Methods placed beside their family in the file, ordered consistently.
+
+## Output format
+
+Report findings grouped by severity. For each: a one-line title, the
+`binutils.js:line` reference, why it is wrong, and the concrete fix. Lead with
+**Correctness** issues, then **Conventions**, then **Docs/Tests**. State a
+confidence level and only raise convention nits if no correctness issue is
+outstanding. If you ran a round-trip to confirm, show the command and result. If
+nothing is wrong, say so plainly — do not invent issues.

package/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git checkout *)",
+      "Bash(node *)",
+      "Bash(echo \"exit code: $?\")",
+      "Read(//tmp/**)",
+      "Bash(echo \"exit: $?\")",
+      "mcp__claude_ai_Context7__resolve-library-id",
+      "mcp__claude_ai_Context7__query-docs",
+      "Bash(python3 -c \"import yaml,sys; yaml.safe_load\\(open\\('.github/workflows/test.yml'\\)\\); print\\('YAML OK'\\)\")",
+      "Bash(git add *)",
+      "Bash(git commit -m 'fix 64-bit writers and WriteBytes type guard *)",
+      "Bash(git commit -m 'add test suite using node:test *)",
+      "Bash(git commit -m 'add github actions workflow to run tests *)",
+      "Bash(git commit -m 'add project docs and claude tooling *)",
+      "Bash(git push *)",
+      "Bash(git commit -m 'rewrite readme with full api reference and examples *)"
+    ]
+  }
+}

package/.claude/skills/add-binary-type/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: add-binary-type
+description: Add a new matched Read/Write method pair to binutils.js following the library's exact ES5 conventions, then update README.md and add a round-trip test. Use when asked to support a new numeric/binary type (e.g. a new width, a string type, a boolean) in the BinaryReader/BinaryWriter classes.
+---
+
+# Adding a binary type to binutils64
+
+This library exposes mirrored methods on `BinaryReader` and `BinaryWriter` in the
+single file `binutils.js`. Every supported type has a `ReadX` and a matching
+`WriteX`. Adding a type means editing both prototypes, updating `README.md`, and
+adding a round-trip test. Follow the templates below **exactly** — style
+deviations and width mismatches are the main source of bugs here (this library
+previously shipped a low-32-bit width bug in the 64-bit writers — don't repeat it).
+
+## Hard rules (match existing code)
+
+- ES5 only: `var`, prototype assignment. No `let`/`const`/classes/arrow functions.
+- Method names are `PascalCase`: `ReadUInt24`, `WriteBool`, etc.
+- Parameters are prefixed `p_` (`p_Value`); locals are prefixed `s_` (`s_Val`,
+  `s_TempBuffer`).
+- Keep `new Buffer(...)` — the package targets `node >=0.12`. Do not switch to
+  `Buffer.alloc`/`Buffer.from` unless `package.json` `engines.node` is also raised.
+- **The write width MUST equal the read width.** When the type is wider than 32
+  bits, use the correct wide Buffer method (`writeBigUInt64LE`, etc.), NOT
+  `writeUInt32LE` — using a 32-bit write into an 8-byte buffer was the original
+  64-bit writer bug (now fixed). 64-bit values are `BigInt`; coerce with
+  `BigInt(p_Value)` so both `Number` and `BigInt` arguments work.
+
+## Reader method template
+
+Out-of-range reads return `0` (or `0.0` / empty `Buffer`) — they do not throw.
+Reads are destructive: slice the consumed bytes off `this.ByteBuffer` and advance
+`this.Position` by the byte width `N`.
+
+```javascript
+ReadTYPE: function() {
+    if (this.ByteBuffer.length < N) {
+        return 0;
+    }
+
+    var s_Val = (this.Endianness == 'little') ? this.ByteBuffer.readTYPELE(0) : this.ByteBuffer.readTYPEBE(0);
+    this.ByteBuffer = this.ByteBuffer.slice(N);
+    this.Position += N;
+    return s_Val;
+},
+```
+
+For a single-byte type there is no endianness branch (see `ReadUInt8`/`ReadInt8`),
+and use `++this.Position;`.
+
+## Writer method template
+
+Allocate an `N`-byte temp buffer, write with the correct-width method honoring
+endianness, grow `this.Length` by `N`, and concat.
+
+```javascript
+WriteTYPE: function(p_Value) {
+    var s_TempBuffer = new Buffer(N);
+    if (this.Endianness == 'little') {
+        s_TempBuffer.writeTYPELE(p_Value, 0);
+    } else {
+        s_TempBuffer.writeTYPEBE(p_Value, 0);
+    }
+    this.Length += N;
+    this.ByteBuffer = Buffer.concat([this.ByteBuffer, s_TempBuffer], this.Length);
+},
+```
+
+For a single-byte type, drop the endianness branch (see `WriteUInt8`/`WriteInt8`).
+
+## Placement
+
+Keep the read/write methods grouped by family and ordered as in the existing file
+(unsigned ascending width, then signed ascending width, then float/double, then
+bytes). Add the new method next to its siblings, not at the end.
+
+## After editing binutils.js
+
+1. **README.md** — add a `### ReadX(...)` and `### WriteX(value)` entry in the
+   matching BinaryReader / BinaryWriter sections, mirroring the existing phrasing
+   ("Reads/Writes a … and advances the current position by N bytes").
+2. **Test** — add a round-trip test (see the `test-binutils` skill): write a value
+   in both `'big'` and `'little'`, read it back, assert equality. Include a min/max
+   or negative boundary value for signed/wide types. For 64-bit values assert the
+   returned type is `bigint`.
+3. Run the tests: `node --test`.
+
+## Verify before finishing
+
+- Write width == read width (round-trip test passes for both endiannesses).
+- `Position`/`Length` advance by exactly `N`.
+- Out-of-range read returns the documented zero value, not a throw.
+- README entries added; method placed beside its family.

package/.claude/skills/test-binutils/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: test-binutils
+description: Author and run tests for the binutils64 library using node:test and node:assert. Use when asked to add test coverage, write tests for a Read/Write method, verify a change, or set up the test suite for this project.
+---
+
+# Testing binutils64
+
+The library ships with no test framework today. Use the built-in `node:test`
+runner + `node:assert/strict` — zero dependencies. (The library's runtime floor
+stays `node >=0.12`; `node:test` only affects the dev/test environment, which
+needs Node >= 18.)
+
+## Layout & running
+
+- Put tests in `test/`, named `*.test.js`.
+- Run the whole suite: `node --test`.
+- Add to `package.json` if missing:
+  ```json
+  "scripts": { "test": "node --test" }
+  ```
+
+## Test file skeleton
+
+```javascript
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+
+test('UInt32 round-trips both endiannesses', function() {
+    ['big', 'little'].forEach(function(endian) {
+        var w = new binutils.BinaryWriter(endian);
+        w.WriteUInt32(0xDEADBEEF);
+        var r = new binutils.BinaryReader(w.ByteBuffer, endian);
+        assert.equal(r.ReadUInt32(), 0xDEADBEEF);
+    });
+});
+```
+
+Keep test code ES5-compatible in spirit (`var`, `function`) to match repo style,
+though the test runner itself requires modern Node.
+
+## Coverage priorities (highest value first)
+
+### 1. Round-trips — write then read back
+For every type, both `'big'` and `'little'`: write a value, feed `writer.ByteBuffer`
+into a reader, assert the read value equals the written one.
+- `UInt8/16/32`, `Int8/16/32`, `Float`, `Double`, `Bytes`.
+- `UInt64/Int64`: assert against the correct BigInt value. The writers accept a
+  `Number` or a `BigInt` and emit all 8 bytes; the reader returns a `BigInt`, so
+  compare against a `BigInt` literal (`123n`), not a `Number` (`123n !== 123` under
+  strict equality).
+- Signed boundaries: `Int32` min `-2147483648` and max `2147483647`, negatives for
+  `Int8/16`.
+- `Float`: compare with tolerance (`assert.ok(Math.abs(got - want) < 1e-6)`) due to
+  precision loss. `Double` is exact for representable values.
+
+### 2. BinaryReader behavior
+- **Endianness**: identical bytes read as `'big'` vs `'little'` produce the expected
+  swapped values; default (no arg) is `'big'`.
+- **Invariants**: after reads, `Position` advanced by the right byte count, `Length`
+  unchanged at the original size, `ByteBuffer` shrank by the consumed bytes.
+- **Out-of-range** reads return `0` / `0.0` / empty `Buffer` (never throw) — read
+  past the end for each method.
+- **Constructor inputs**: `Buffer`, `Array`, and `string` (+ encoding) all build;
+  an invalid input (e.g. a number) throws.
+- **Constructor copies input**: mutate the caller's original buffer after
+  constructing and confirm reader output is unaffected.
+- `ReadUInt64`/`ReadInt64` return a `bigint` (`assert.equal(typeof v, 'bigint')`).
+- README reader example: bytes `[1,0,2,0,0,0,3,1,2,3,4,5,6]` yield `1`, `2`, `3`,
+  a 6-byte buffer, then `Position` and `Length` both `13`.
+
+### 3. BinaryWriter behavior
+- Defaults: endianness `'big'`, encoding `'ascii'`.
+- `Length` increments by the correct width per write; emitted bytes match expected
+  hex for both endiannesses.
+- `WriteBytes` accepts `string`, `Array`, and `Buffer`, producing identical bytes,
+  and throws on any other input type.
+- README writer example yields `<Buffer ff ff 00 00 00 00 ff ff ff ff 05 04 03 02 01>`,
+  `Length` 15.
+
+### 4. Maintaining bug-documentation tests
+There are no open known bugs at the moment. When you discover one, pin its current
+behavior with a clearly-commented test so regressions are noticed. When a bug is
+fixed, delete its pinned test and convert any matching TODO round-trip into a normal
+assertion — this is how the former 64-bit writer bug (low-32-bit truncation) and the
+`WriteBytes` guard bug (`!p_Value instanceof Buffer` mis-parsing, which let invalid
+input through) were retired.
+
+## Verify before finishing
+- `node --test` passes (except intentionally-`todo` bug tests).
+- New types added via the `add-binary-type` skill have a matching round-trip test.

package/.github/workflows/test.yml

@@ -0,0 +1,22 @@
+name: Tests
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [20, 22, 24]
+    name: Node ${{ matrix.node }}
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+      # No install step: the package has zero dependencies and no lockfile.
+      - run: npm test

package/CLAUDE.md

@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+Guidance for working in this repository.
+
+## What this is
+
+`binutils64` — a small npm package providing .NET-style `BinaryReader` and
+`BinaryWriter` classes for Node.js, with selectable endianness (`'big'` default
+or `'little'`). All logic lives in a single file: `binutils.js`. Published to npm
+as `binutils64`.
+
+## Layout
+
+- `binutils.js` — the entire library. Two ES5 prototype-based "classes"
+  (`BinaryReader`, `BinaryWriter`) exported via `module.exports`.
+- `README.md` — the public API reference (keep in sync when adding/changing methods).
+- No `src/`, no build step, no dependencies, no test suite.
+
+## Running / testing
+
+There is no test framework, lint config, or build. To verify a change, write an
+ad-hoc script and run it with node, e.g.:
+
+```bash
+node -e "var b=require('./binutils.js'); var w=new b.BinaryWriter('little'); w.WriteUInt32(3); console.log(w.ByteBuffer);"
+```
+
+When you add or change a public method, update the matching section in `README.md`.
+
+## Code conventions (match the existing style exactly)
+
+- ES5 only: `var`, prototype assignment, no classes/arrow functions/`let`/`const`.
+- Method and property names are `PascalCase` (`ReadUInt32`, `ByteBuffer`, `Position`).
+- Function parameters are prefixed `p_` (`p_InputBuffer`, `p_Value`).
+- Local variables are prefixed `s_` (`s_Val`, `s_TempBuffer`).
+- Targets `node >=0.12`, so `new Buffer(...)` is used deliberately despite being
+  deprecated in modern Node. Don't "fix" it to `Buffer.alloc`/`Buffer.from` unless
+  the engines floor is also raised.
+- Commit messages are short, lowercase, imperative (e.g. `add read/write 64 bit values`,
+  `fix read int64`). No AI/Claude attribution.
+
+## Behavior to preserve
+
+- **Reads are destructive.** Each `Read*` slices the consumed bytes off
+  `this.ByteBuffer` and advances `this.Position`. `Length` stays at the original
+  buffer length; `ByteBuffer` shrinks as you read.
+- **Out-of-range reads return `0` (or `0.0`/empty Buffer), they do not throw.**
+- `ReadUInt64`/`ReadInt64` return a `BigInt` (via `readBigUInt64*`/`readBigInt64*`).
+- The constructor copies the input buffer (`new Buffer(p_InputBuffer)`) so the
+  caller's buffer is not mutated — preserve this.
+- `WriteUInt64`/`WriteInt64` accept a `Number` or `BigInt` (coerced via
+  `BigInt(p_Value)`) and emit all 8 bytes via `writeBigUInt64*`/`writeBigInt64*`.
+- `WriteBytes` accepts a `Buffer`, `Array`, or `string`, and throws on any other
+  input type.

package/README.md

@@ -1,163 +1,256 @@
-binutils - .NET like BinaryReader and BinaryWriter for node.js
-==============================================================
-
-These utilities provide you with a BinaryReader and BinaryWriter class with functions similar to the corresponding .NET classes.
-They also allow you to define a specific endianness!
-
-Basic installation and usage
-----------------------------
-
-You can install this package either by using npm or by downloading the source from GitHub and requiring it directly.
-
-To install using npm open your terminal (or command line), make sure you're in your application directory and execute the following command:
-
-    npm install binutils64
-    
-You can then start using the package by requiring it from your application as such:
-
-    var binutils = require('binutils64');
-    
-BinaryReader Class
-------------------
-
-### BinaryReader(inputBuffer, endianness, encoding)
-
-* Initializes a BinaryReader with the specified settings
-* inputBuffer can be a `Buffer`, a `string` or an `array`
-
-### ReadUInt8()
-
-* Reads a 8 bit unsigned integer from the buffer and advances the current position by 1 byte
-
-### ReadUInt16()
-
-* Reads a 16 bit unsigned integer from the buffer and advances the current position by 2 bytes
-
-### ReadUInt32()
-
-* Reads a 32 bit unsigned integer from the buffer and advances the current position by 4 bytes
-
-### ReadInt8()
-
-* Reads a 8 bit signed integer from the buffer and advances the current position by 1 byte
-
-### ReadInt16()
-
-* Reads a 16 bit signed integer from the buffer and advances the current position by 2 bytes
-
-### ReadInt32()
-
-* Reads a 32 bit signed integer from the buffer and advances the current position by 4 bytes
-
-### ReadFloat()
-
-* Reads a float from the buffer and advances the current position by 4 bytes
-
-### ReadDouble()
-
-* Reads a double from the buffer and advances the current position by 8 bytes
-
-### ReadBytes(count)
-
-* Reads the specified number of bytes into a new buffer and advances the current position by that number of bytes 
-
-### Length [Number]
-
-* The length of the initially provided data
-
-### Position [Number]
-
-* The current position (index) of the reader
-
-### ByteBuffer [Buffer]
-
-* A buffer containing the remaining data from the original buffer
-
-BinaryWriter Class
-------------------
-
-### BinaryWriter(endianness, encoding)
-
-* Initializes a BinaryWriter with the specified settings
-
-### WriteUInt8(value)
-
-* Writes a 8 bit unsigned integer to the buffer and advances the current position by 1 byte
-
-### WriteUInt16(value)
-
-* Writes a 16 bit unsigned integer to the buffer and advances the current position by 2 bytes
-
-### WriteUInt32(value)
-
-* Writes a 32 bit unsigned integer to the buffer and advances the current position by 4 bytes
-
-### WriteInt8(value)
-
-* Writes a 8 bit signed integer to the buffer and advances the current position by 1 byte
-
-### WriteInt16(value)
-
-* Writes a 16 bit signed integer to the buffer and advances the current position by 2 bytes
-
-### WriteInt32(value)
-
-* Writes a 32 bit signed integer to the buffer and advances the current position by 4 bytes
-
-### WriteFloat(value)
-
-* Writes a float to the buffer and advances the current position by 4 bytes
-
-### WriteDouble(value)
-
-* Writes a double to the buffer and advances the current position by 8 bytes
-
-### WriteBytes(value)
-
-* Reads the specified number of bytes into a new buffer and advances the current position by that number of bytes
-* value can be a `Buffer`, a `string` or an `array`
-
-### Length [Number]
-
-* The length of the current data buffer
-
-### ByteBuffer [Buffer]
-
-* A buffer containing the data written using the class functions
-
-Example
--------
-
-```javascript
-var binutils = require('./binutils.js');
-
-var buffer = new Buffer([1,  0, 2,  0, 0, 0, 3,  1, 2, 3, 4, 5, 6]);
-
-var reader = new binutils.BinaryReader(buffer);
-
-console.log(reader.ReadUInt8()); // Will print '1'
-console.log(reader.ReadUInt16()); // Will print '2'
-console.log(reader.ReadUInt32()); // Will print '3'
-console.log(reader.ReadBytes(6)); // Will print '<Buffer 01 02 03 04 05 06>'
-console.log(reader.Position); // Will print '13'
-console.log(reader.Length); // Will print '13'
-
-//
-
-var writer = new binutils.BinaryWriter();
-
-writer.WriteUInt16(65535);
-writer.WriteUInt32(0);
-writer.WriteInt32(-1);
-writer.WriteBytes([5, 4, 3, 2, 1]);
-
-console.log(writer.ByteBuffer); // Will print '<Buffer ff ff 00 00 00 00 ff ff ff ff 05 04 03 02 01>'
-console.log(writer.Length); // Will print '15'
-```
-
-TODO
-----
-
-* Add support for 64-bit integers
-* Add support for strings
-* Add support for booleans
+# binutils64
+
+> A .NET-style `BinaryReader` and `BinaryWriter` for Node.js, with selectable endianness.
+
+[![npm version](https://img.shields.io/npm/v/binutils64.svg)](https://www.npmjs.com/package/binutils64)
+[![Tests](https://github.com/mihailShumilov/node-binutils/actions/workflows/test.yml/badge.svg)](https://github.com/mihailShumilov/node-binutils/actions/workflows/test.yml)
+
+`binutils64` provides two small classes — `BinaryReader` and `BinaryWriter` — that
+make it easy to parse and produce binary data sequentially, with an API modelled on
+the corresponding .NET classes. Both classes let you choose the byte order
+(`big`- or `little`-endian) and support 8-, 16-, 32- and 64-bit integers, floats,
+doubles, and raw byte runs.
+
+## Table of contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+  - [BinaryReader](#binaryreader)
+  - [BinaryWriter](#binarywriter)
+- [Behavior and best practices](#behavior-and-best-practices)
+- [Examples](#examples)
+- [Requirements and compatibility](#requirements-and-compatibility)
+- [Testing](#testing)
+- [Contributing](#contributing)
+
+## Features
+
+- Sequential `Read*` / `Write*` methods for every common fixed-width type.
+- Per-instance endianness (`big` by default, or `little`).
+- 64-bit integers via JavaScript `BigInt`.
+- Signed and unsigned integers, IEEE-754 `float` and `double`, and raw byte runs.
+- Zero runtime dependencies.
+
+## Installation
+
+```bash
+npm install binutils64
+```
+
+Then require it:
+
+```javascript
+const binutils = require('binutils64');
+// const { BinaryReader, BinaryWriter } = require('binutils64');
+```
+
+## Quick start
+
+```javascript
+const { BinaryReader, BinaryWriter } = require('binutils64');
+
+// --- Writing ---
+const writer = new BinaryWriter();      // big-endian by default
+writer.WriteUInt16(65535);
+writer.WriteUInt32(0);
+writer.WriteInt32(-1);
+writer.WriteBytes([5, 4, 3, 2, 1]);
+
+console.log(writer.ByteBuffer);
+// <Buffer ff ff 00 00 00 00 ff ff ff ff 05 04 03 02 01>
+console.log(writer.Length); // 15
+
+// --- Reading ---
+const reader = new BinaryReader(writer.ByteBuffer);
+console.log(reader.ReadUInt16()); // 65535
+console.log(reader.ReadUInt32()); // 0
+console.log(reader.ReadInt32());  // -1
+console.log(reader.ReadBytes(5)); // <Buffer 05 04 03 02 01>
+```
+
+## API reference
+
+### BinaryReader
+
+A reader wraps an immutable copy of the input data and consumes it from the front as
+you read.
+
+#### `new BinaryReader(input, [endianness], [encoding])`
+
+| Parameter    | Type                          | Default | Description                                                        |
+| ------------ | ----------------------------- | ------- | ------------------------------------------------------------------ |
+| `input`      | `Buffer` \| `number[]` \| `string` | —  | The data to read. A `Buffer` is **copied** so the source is never mutated. |
+| `endianness` | `'big'` \| `'little'`         | `'big'` | Byte order used by all multi-byte reads.                           |
+| `encoding`   | `string`                      | `'ascii'` | Used only when `input` is a `string`, to turn it into bytes.     |
+
+Throws `Error` if `input` is not a `Buffer`, array, or string.
+
+#### Read methods
+
+| Method            | Bytes | Returns   | Notes                                          |
+| ----------------- | ----- | --------- | ---------------------------------------------- |
+| `ReadUInt8()`     | 1     | `number`  | Unsigned.                                      |
+| `ReadInt8()`      | 1     | `number`  | Signed.                                        |
+| `ReadUInt16()`    | 2     | `number`  | Honors endianness.                             |
+| `ReadInt16()`     | 2     | `number`  | Honors endianness.                             |
+| `ReadUInt32()`    | 4     | `number`  | Honors endianness.                             |
+| `ReadInt32()`     | 4     | `number`  | Honors endianness.                             |
+| `ReadUInt64()`    | 8     | `BigInt`  | Honors endianness. Returns a `BigInt`.         |
+| `ReadInt64()`     | 8     | `BigInt`  | Honors endianness. Returns a `BigInt`.         |
+| `ReadFloat()`     | 4     | `number`  | IEEE-754 single precision.                     |
+| `ReadDouble()`    | 8     | `number`  | IEEE-754 double precision.                     |
+| `ReadBytes(count)`| `count` | `Buffer`| Copies `count` bytes into a new `Buffer`.      |
+
+If fewer than the required number of bytes remain, integer/float reads return `0`
+(or `0.0`), and `ReadBytes` returns an empty `Buffer` — **without** throwing or
+advancing the position. See [Behavior and best practices](#behavior-and-best-practices).
+
+#### Reader properties
+
+| Property     | Type     | Description                                                         |
+| ------------ | -------- | ------------------------------------------------------------------- |
+| `ByteBuffer` | `Buffer` | The **remaining** unread data. Shrinks as you read.                 |
+| `Position`   | `number` | Number of bytes consumed so far (starts at `0`).                    |
+| `Length`     | `number` | The length of the original input. Does **not** change as you read.  |
+| `Endianness` | `string` | `'big'` or `'little'`.                                               |
+| `Encoding`   | `string` | The encoding passed to the constructor.                             |
+
+### BinaryWriter
+
+A writer accumulates bytes in an internal buffer that grows with every write.
+
+#### `new BinaryWriter([endianness], [encoding])`
+
+| Parameter    | Type                  | Default   | Description                              |
+| ------------ | --------------------- | --------- | ---------------------------------------- |
+| `endianness` | `'big'` \| `'little'` | `'big'`   | Byte order used by all multi-byte writes.|
+| `encoding`   | `string`              | `'ascii'` | Stored on the instance; reserved.        |
+
+#### Write methods
+
+| Method                | Bytes | Accepts             | Notes                                              |
+| --------------------- | ----- | ------------------- | -------------------------------------------------- |
+| `WriteUInt8(value)`   | 1     | `number`            | Unsigned.                                          |
+| `WriteInt8(value)`    | 1     | `number`            | Signed.                                            |
+| `WriteUInt16(value)`  | 2     | `number`            | Honors endianness.                                 |
+| `WriteInt16(value)`   | 2     | `number`            | Honors endianness.                                 |
+| `WriteUInt32(value)`  | 4     | `number`            | Honors endianness.                                 |
+| `WriteInt32(value)`   | 4     | `number`            | Honors endianness.                                 |
+| `WriteUInt64(value)`  | 8     | `number` \| `BigInt`| Coerced with `BigInt(value)`; honors endianness.   |
+| `WriteInt64(value)`   | 8     | `number` \| `BigInt`| Coerced with `BigInt(value)`; honors endianness.   |
+| `WriteFloat(value)`   | 4     | `number`            | IEEE-754 single precision.                         |
+| `WriteDouble(value)`  | 8     | `number`            | IEEE-754 double precision.                         |
+| `WriteBytes(value)`   | varies| `Buffer` \| `number[]` \| `string` | Strings are written as one byte per character code. Throws on any other type. |
+
+Writing a value outside the target type's range throws a `RangeError` (the standard
+Node.js `Buffer` write behavior) — e.g. `WriteUInt8(256)`.
+
+#### Writer properties
+
+| Property     | Type     | Description                                  |
+| ------------ | -------- | -------------------------------------------- |
+| `ByteBuffer` | `Buffer` | All bytes written so far.                    |
+| `Length`     | `number` | The current length of `ByteBuffer`.          |
+| `Endianness` | `string` | `'big'` or `'little'`.                        |
+| `Encoding`   | `string` | The encoding passed to the constructor.      |
+
+## Behavior and best practices
+
+- **Reads are destructive.** Each `Read*` call consumes bytes from the front of
+  `ByteBuffer` and advances `Position`. If you need the original bytes again, keep
+  your own copy before reading. Create a fresh `BinaryReader` to start over.
+- **`Length` vs. `Position`.** On a reader, `Length` is the original size and never
+  changes; `Position` tracks how much you have consumed. The bytes left to read are
+  `Length - Position` (also `ByteBuffer.length`).
+- **Out-of-range reads do not throw.** Reading past the end returns `0` / `0.0` /
+  an empty `Buffer` and leaves `Position` unchanged. Check the remaining length
+  yourself if a short buffer should be treated as an error:
+
+  ```javascript
+  if (reader.ByteBuffer.length < 4) {
+    throw new Error('truncated record');
+  }
+  const value = reader.ReadUInt32();
+  ```
+
+- **64-bit values are `BigInt`s.** `ReadUInt64`/`ReadInt64` always return a `BigInt`.
+  When writing, pass a `BigInt` for any value above `Number.MAX_SAFE_INTEGER`
+  (`2^53 - 1`) to avoid silent precision loss; smaller `number`s are accepted and
+  coerced automatically.
+- **Set endianness once, at construction.** All multi-byte methods follow the
+  instance's `Endianness`; reader and writer must agree to round-trip correctly.
+- **Constructing a reader from a string?** Pass the encoding explicitly
+  (e.g. `new BinaryReader(text, 'big', 'utf8')`) so the bytes are interpreted the
+  way you expect.
+
+## Examples
+
+### Round-tripping a 64-bit integer
+
+```javascript
+const { BinaryReader, BinaryWriter } = require('binutils64');
+
+const writer = new BinaryWriter();             // big-endian
+writer.WriteUInt64(0x1234567890ABCDEFn);       // pass a BigInt for large values
+console.log(writer.ByteBuffer);                // <Buffer 12 34 56 78 90 ab cd ef>
+
+const reader = new BinaryReader(writer.ByteBuffer);
+console.log(reader.ReadUInt64());              // 1311768467294899695n
+```
+
+### Little-endian
+
+```javascript
+const { BinaryReader, BinaryWriter } = require('binutils64');
+
+const writer = new BinaryWriter('little');
+writer.WriteUInt32(0x01020304);
+console.log(writer.ByteBuffer);                // <Buffer 04 03 02 01>
+
+const reader = new BinaryReader(writer.ByteBuffer, 'little');
+console.log(reader.ReadUInt32().toString(16)); // "1020304"
+```
+
+### Parsing a structured record
+
+```javascript
+const { BinaryReader } = require('binutils64');
+
+// type (u8), id (u32, big-endian), payload (6 bytes)
+const reader = new BinaryReader(Buffer.from([1, 0, 0, 0, 3, 1, 2, 3, 4, 5, 6]));
+
+const record = {
+  type:    reader.ReadUInt8(),   // 1
+  id:      reader.ReadUInt32(),  // 3
+  payload: reader.ReadBytes(6),  // <Buffer 01 02 03 04 05 06>
+};
+
+console.log(record, 'read', reader.Position, 'of', reader.Length, 'bytes');
+```
+
+## Requirements and compatibility
+
+- **Node.js.** The 8-, 16- and 32-bit methods run on very old Node.js versions, but
+  the 64-bit methods (`ReadUInt64`, `ReadInt64`, `WriteUInt64`, `WriteInt64`) rely on
+  `BigInt` and the `Buffer` big-integer methods, which require **Node.js 12 or newer**.
+- The library uses the legacy `Buffer` constructor internally; on modern Node.js you
+  may see a one-time `DEP0005` deprecation warning. This does not affect behavior.
+- Running the test suite uses the built-in `node:test` runner, which requires
+  **Node.js 18 or newer**.
+
+## Testing
+
+```bash
+npm test     # runs `node --test`
+```
+
+The suite covers every reader/writer method, round-trips across both endiannesses,
+edge cases (out-of-range reads, constructor input types, buffer-copy isolation), and
+the documented examples. Continuous integration runs it on Node.js 20, 22 and 24.
+
+## Contributing
+
+Issues and pull requests are welcome. Please add or update tests for any behavioral
+change and make sure `npm test` passes before opening a pull request.

package/binutils.js

@@ -60,7 +60,7 @@ BinaryReader.prototype = {
             return 0;
         }
 
-        var s_Val = (this.Endianness == 'little') ? this.ByteBuffer.readUInt32LE(0) : this.ByteBuffer.readUInt32BE(0);
+        var s_Val = (this.Endianness == 'little') ? this.ByteBuffer.readBigUInt64LE(0) : this.ByteBuffer.readBigUInt64BE(0);
         this.ByteBuffer = this.ByteBuffer.slice(8);
         this.Position += 8;
         return s_Val;
@@ -104,7 +104,7 @@ BinaryReader.prototype = {
             return 0;
         }
 
-        var s_Val = (this.Endianness == 'little') ? this.ByteBuffer.readInt32LE(0) : this.ByteBuffer.readInt32BE(0);
+        var s_Val = (this.Endianness == 'little') ? this.ByteBuffer.readBigInt64LE(0) : this.ByteBuffer.readBigInt64BE(0);
         this.ByteBuffer = this.ByteBuffer.slice(8);
         this.Position += 8;
         return s_Val;
@@ -195,10 +195,11 @@ BinaryWriter.prototype = {
 
     WriteUInt64: function(p_Value) {
         var s_TempBuffer = new Buffer(8);
+        var s_Value = BigInt(p_Value);
         if (this.Endianness == 'little') {
-            s_TempBuffer.writeUInt32LE(p_Value, 0);
+            s_TempBuffer.writeBigUInt64LE(s_Value, 0);
         } else {
-            s_TempBuffer.writeUInt32BE(p_Value, 0);
+            s_TempBuffer.writeBigUInt64BE(s_Value, 0);
         }
         this.Length += 8;
         this.ByteBuffer = Buffer.concat([this.ByteBuffer, s_TempBuffer], this.Length);
@@ -235,10 +236,11 @@ BinaryWriter.prototype = {
 
     WriteInt64: function(p_Value) {
         var s_TempBuffer = new Buffer(8);
+        var s_Value = BigInt(p_Value);
         if (this.Endianness == 'little') {
-            s_TempBuffer.writeInt32LE(p_Value, 0);
+            s_TempBuffer.writeBigInt64LE(s_Value, 0);
         } else {
-            s_TempBuffer.writeInt32BE(p_Value, 0);
+            s_TempBuffer.writeBigInt64BE(s_Value, 0);
         }
         this.Length += 8;
         this.ByteBuffer = Buffer.concat([this.ByteBuffer, s_TempBuffer], this.Length);
@@ -279,7 +281,7 @@ BinaryWriter.prototype = {
             p_Value = s_BytesArray;
         }
 
-        if (!p_Value instanceof Buffer && !p_Value instanceof Array) {
+        if (!(p_Value instanceof Buffer) && !(p_Value instanceof Array)) {
             throw new Error("Invalid Buffer object provided.");
         }
 

package/package.json

@@ -1,11 +1,14 @@
 {
     "name": "binutils64",
-    "version": "0.1.2",
+    "version": "0.1.4",
     "author": "Mihail Shumilov <mschumilow@gmail.com>",
     "description": "A .NET-like BinaryReader and BinaryWriter with endianness support.",
     "main": "./binutils.js",
+    "scripts": {
+        "test": "node --test"
+    },
     "engines": {
-        "node": ">=0.10"
+        "node": ">=0.12"
     },
     "repository": {
         "type" : "git",

package/test/edge-cases.test.js

@@ -0,0 +1,76 @@
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+var BinaryReader = binutils.BinaryReader;
+
+test('constructor accepts a Buffer', function() {
+    var r = new BinaryReader(Buffer.from([1, 2, 3]));
+    assert.equal(r.Length, 3);
+    assert.equal(r.ReadUInt8(), 1);
+});
+
+test('constructor accepts an Array', function() {
+    var r = new BinaryReader([1, 2, 3]);
+    assert.equal(r.Length, 3);
+    assert.equal(r.ReadUInt8(), 1);
+});
+
+test('constructor accepts a string with encoding', function() {
+    var r = new BinaryReader('ABC', 'big', 'ascii');
+    assert.equal(r.Length, 3);
+    assert.equal(r.ReadUInt8(), 65);
+});
+
+test('constructor rejects invalid input types', function() {
+    assert.throws(function() { new BinaryReader(42); }, /Invalid buffer input/);
+    assert.throws(function() { new BinaryReader({}); }, /Invalid buffer input/);
+    assert.throws(function() { new BinaryReader(null); }, /Invalid buffer input/);
+});
+
+test('constructor copies the input buffer (no aliasing)', function() {
+    var src = Buffer.from([1, 2, 3]);
+    var r = new BinaryReader(src);
+    src[0] = 99; // mutate the caller's buffer after construction
+    assert.equal(r.ReadUInt8(), 1, 'reader is unaffected by later mutation of the source');
+});
+
+test('out-of-range integer reads return 0 without advancing Position', function() {
+    var r = new BinaryReader([0x01], 'big'); // only 1 byte available
+    assert.equal(r.ReadUInt16(), 0);
+    assert.equal(r.ReadUInt32(), 0);
+    assert.equal(r.ReadUInt64(), 0);
+    assert.equal(r.ReadInt16(), 0);
+    assert.equal(r.ReadInt32(), 0);
+    assert.equal(r.ReadInt64(), 0);
+    assert.equal(r.Position, 0, 'failed reads do not advance Position');
+    assert.equal(r.ByteBuffer.length, 1, 'failed reads do not consume bytes');
+});
+
+test('out-of-range float/double reads return 0', function() {
+    var r = new BinaryReader([0x01], 'big');
+    assert.equal(r.ReadFloat(), 0);
+    assert.equal(r.ReadDouble(), 0);
+});
+
+test('ReadUInt8 on an empty buffer returns 0', function() {
+    var r = new BinaryReader([], 'big');
+    assert.equal(r.Length, 0);
+    assert.equal(r.ReadUInt8(), 0);
+    assert.equal(r.ReadInt8(), 0);
+});
+
+test('ReadBytes returns an empty Buffer when count exceeds remaining', function() {
+    var r = new BinaryReader([1, 2, 3], 'big');
+    var out = r.ReadBytes(5);
+    assert.ok(Buffer.isBuffer(out));
+    assert.equal(out.length, 0);
+    assert.equal(r.Position, 0, 'over-long ReadBytes does not advance');
+    assert.equal(r.ByteBuffer.length, 3);
+});
+
+test('ReadBytes reading exactly the remaining length succeeds', function() {
+    var r = new BinaryReader([1, 2, 3], 'big');
+    assert.deepEqual(Array.from(r.ReadBytes(3)), [1, 2, 3]);
+    assert.equal(r.Position, 3);
+    assert.equal(r.ByteBuffer.length, 0);
+});

package/test/reader.test.js

@@ -0,0 +1,106 @@
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+var BinaryReader = binutils.BinaryReader;
+
+function reader(arr, endian) {
+    return new BinaryReader(Buffer.from(arr), endian);
+}
+
+test('BinaryReader: constructor defaults', function() {
+    var r = reader([1, 2, 3]);
+    assert.equal(r.Endianness, 'big', 'defaults to big-endian');
+    assert.equal(r.Encoding, 'ascii', 'defaults to ascii encoding');
+    assert.equal(r.Length, 3, 'Length is the original buffer length');
+    assert.equal(r.Position, 0, 'Position starts at 0');
+    assert.equal(r.ByteBuffer.length, 3);
+});
+
+test('BinaryReader: ReadUInt8', function() {
+    var r = reader([200, 5]);
+    assert.equal(r.ReadUInt8(), 200);
+    assert.equal(r.ReadUInt8(), 5);
+});
+
+test('BinaryReader: ReadInt8 (signed)', function() {
+    var r = reader([0xFF, 0x80, 0x7F]);
+    assert.equal(r.ReadInt8(), -1);
+    assert.equal(r.ReadInt8(), -128);
+    assert.equal(r.ReadInt8(), 127);
+});
+
+test('BinaryReader: ReadUInt16 honors endianness', function() {
+    assert.equal(reader([0x12, 0x34], 'big').ReadUInt16(), 0x1234);
+    assert.equal(reader([0x12, 0x34], 'little').ReadUInt16(), 0x3412);
+});
+
+test('BinaryReader: ReadInt16 (signed)', function() {
+    assert.equal(reader([0xFF, 0xFF], 'big').ReadInt16(), -1);
+    assert.equal(reader([0x80, 0x00], 'big').ReadInt16(), -32768);
+    assert.equal(reader([0x00, 0x80], 'little').ReadInt16(), -32768);
+});
+
+test('BinaryReader: ReadUInt32 honors endianness', function() {
+    assert.equal(reader([0x12, 0x34, 0x56, 0x78], 'big').ReadUInt32(), 0x12345678);
+    assert.equal(reader([0x78, 0x56, 0x34, 0x12], 'little').ReadUInt32(), 0x12345678);
+});
+
+test('BinaryReader: ReadInt32 (signed)', function() {
+    assert.equal(reader([0xFF, 0xFF, 0xFF, 0xFF], 'big').ReadInt32(), -1);
+    assert.equal(reader([0x80, 0x00, 0x00, 0x00], 'big').ReadInt32(), -2147483648);
+});
+
+test('BinaryReader: ReadUInt64 returns a BigInt', function() {
+    var r = reader([0, 0, 0, 0, 0, 0, 0, 5], 'big');
+    var v = r.ReadUInt64();
+    assert.equal(typeof v, 'bigint');
+    assert.equal(v, 5n);
+    assert.equal(reader([5, 0, 0, 0, 0, 0, 0, 0], 'little').ReadUInt64(), 5n);
+});
+
+test('BinaryReader: ReadInt64 returns a signed BigInt', function() {
+    assert.equal(reader([0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], 'big').ReadInt64(), -1n);
+});
+
+test('BinaryReader: ReadFloat', function() {
+    // 1.5 as IEEE-754 single precision = 0x3FC00000
+    assert.equal(reader([0x3F, 0xC0, 0x00, 0x00], 'big').ReadFloat(), 1.5);
+    assert.equal(reader([0x00, 0x00, 0xC0, 0x3F], 'little').ReadFloat(), 1.5);
+});
+
+test('BinaryReader: ReadDouble', function() {
+    // 1.5 as IEEE-754 double precision = 0x3FF8000000000000
+    assert.equal(reader([0x3F, 0xF8, 0, 0, 0, 0, 0, 0], 'big').ReadDouble(), 1.5);
+});
+
+test('BinaryReader: ReadBytes returns a Buffer of the requested length', function() {
+    var r = reader([1, 2, 3, 4, 5, 6]);
+    var out = r.ReadBytes(4);
+    assert.ok(Buffer.isBuffer(out));
+    assert.deepEqual(Array.from(out), [1, 2, 3, 4]);
+    assert.equal(r.Position, 4);
+    assert.equal(r.ByteBuffer.length, 2);
+});
+
+test('BinaryReader: Position advances and Length stays constant; ByteBuffer shrinks', function() {
+    var r = reader([1, 2, 3, 4, 5, 6, 7, 8], 'big');
+
+    assert.equal(r.ReadUInt8(), 1);
+    assert.equal(r.Position, 1);
+    assert.equal(r.Length, 8, 'Length never changes on reads');
+    assert.equal(r.ByteBuffer.length, 7, 'ByteBuffer shrinks by consumed bytes');
+
+    assert.equal(r.ReadUInt16(), 0x0203);
+    assert.equal(r.Position, 3);
+    assert.equal(r.ByteBuffer.length, 5);
+
+    assert.equal(r.ReadUInt32(), 0x04050607);
+    assert.equal(r.Position, 7);
+    assert.equal(r.ByteBuffer.length, 1);
+});
+
+test('BinaryReader: same bytes decode differently per endianness', function() {
+    var b = [0x00, 0x00, 0x00, 0x01];
+    assert.equal(reader(b, 'big').ReadUInt32(), 1);
+    assert.equal(reader(b, 'little').ReadUInt32(), 0x01000000);
+});

package/test/readme-examples.test.js

@@ -0,0 +1,33 @@
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+
+// These mirror the worked examples in README.md. If the documented output ever
+// changes, the docs and these tests must change together.
+
+test('README reader example', function() {
+    var buffer = Buffer.from([1, 0, 2, 0, 0, 0, 3, 1, 2, 3, 4, 5, 6]);
+    var reader = new binutils.BinaryReader(buffer);
+
+    assert.equal(reader.ReadUInt8(), 1);
+    assert.equal(reader.ReadUInt16(), 2);
+    assert.equal(reader.ReadUInt32(), 3);
+    assert.deepEqual(Array.from(reader.ReadBytes(6)), [1, 2, 3, 4, 5, 6]);
+    assert.equal(reader.Position, 13);
+    assert.equal(reader.Length, 13);
+});
+
+test('README writer example', function() {
+    var writer = new binutils.BinaryWriter();
+
+    writer.WriteUInt16(65535);
+    writer.WriteUInt32(0);
+    writer.WriteInt32(-1);
+    writer.WriteBytes([5, 4, 3, 2, 1]);
+
+    assert.deepEqual(
+        Array.from(writer.ByteBuffer),
+        [0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF, 5, 4, 3, 2, 1]
+    );
+    assert.equal(writer.Length, 15);
+});

package/test/roundtrip.test.js

@@ -0,0 +1,120 @@
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+var BinaryReader = binutils.BinaryReader;
+var BinaryWriter = binutils.BinaryWriter;
+
+// Write a value with WriteMethod, then read it back with ReadMethod, asserting
+// equality across both endiannesses.
+function roundTrip(writeMethod, readMethod, value, compare) {
+    ['big', 'little'].forEach(function(endian) {
+        var w = new BinaryWriter(endian);
+        w[writeMethod](value);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        var got = r[readMethod]();
+        if (compare) {
+            compare(got, value, endian);
+        } else {
+            assert.equal(got, value, writeMethod + '/' + readMethod + ' (' + endian + ')');
+        }
+    });
+}
+
+test('round-trip: UInt8', function() {
+    roundTrip('WriteUInt8', 'ReadUInt8', 0);
+    roundTrip('WriteUInt8', 'ReadUInt8', 200);
+    roundTrip('WriteUInt8', 'ReadUInt8', 255);
+});
+
+test('round-trip: Int8', function() {
+    roundTrip('WriteInt8', 'ReadInt8', -128);
+    roundTrip('WriteInt8', 'ReadInt8', -1);
+    roundTrip('WriteInt8', 'ReadInt8', 127);
+});
+
+test('round-trip: UInt16', function() {
+    roundTrip('WriteUInt16', 'ReadUInt16', 0);
+    roundTrip('WriteUInt16', 'ReadUInt16', 0xBEEF);
+    roundTrip('WriteUInt16', 'ReadUInt16', 0xFFFF);
+});
+
+test('round-trip: Int16', function() {
+    roundTrip('WriteInt16', 'ReadInt16', -32768);
+    roundTrip('WriteInt16', 'ReadInt16', -1);
+    roundTrip('WriteInt16', 'ReadInt16', 32767);
+});
+
+test('round-trip: UInt32', function() {
+    roundTrip('WriteUInt32', 'ReadUInt32', 0);
+    roundTrip('WriteUInt32', 'ReadUInt32', 0xDEADBEEF);
+    roundTrip('WriteUInt32', 'ReadUInt32', 0xFFFFFFFF);
+});
+
+test('round-trip: Int32', function() {
+    roundTrip('WriteInt32', 'ReadInt32', -2147483648);
+    roundTrip('WriteInt32', 'ReadInt32', -1);
+    roundTrip('WriteInt32', 'ReadInt32', 2147483647);
+});
+
+test('round-trip: Float (within single-precision tolerance)', function() {
+    roundTrip('WriteFloat', 'ReadFloat', 1.5);
+    roundTrip('WriteFloat', 'ReadFloat', 3.14, function(got, want, endian) {
+        assert.ok(Math.abs(got - want) < 1e-5, 'Float ~3.14 (' + endian + '), got ' + got);
+    });
+});
+
+test('round-trip: Double (exact)', function() {
+    roundTrip('WriteDouble', 'ReadDouble', Math.PI);
+    roundTrip('WriteDouble', 'ReadDouble', -123456.789);
+});
+
+test('round-trip: Bytes', function() {
+    ['big', 'little'].forEach(function(endian) {
+        var payload = [1, 2, 3, 4, 5];
+        var w = new BinaryWriter(endian);
+        w.WriteBytes(payload);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        assert.deepEqual(Array.from(r.ReadBytes(payload.length)), payload);
+    });
+});
+
+// 64-bit round-trips. The writers accept a Number or a BigInt and emit all 8
+// bytes; the reader always returns a BigInt.
+
+test('round-trip: UInt64 (BigInt argument)', function() {
+    var value = 0x1234567890ABCDEFn;
+    ['big', 'little'].forEach(function(endian) {
+        var w = new BinaryWriter(endian);
+        w.WriteUInt64(value);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        assert.equal(r.ReadUInt64(), value);
+    });
+});
+
+test('round-trip: UInt64 (Number argument is coerced)', function() {
+    ['big', 'little'].forEach(function(endian) {
+        var w = new BinaryWriter(endian);
+        w.WriteUInt64(123);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        assert.equal(r.ReadUInt64(), 123n);
+    });
+});
+
+test('round-trip: Int64 (BigInt argument)', function() {
+    var value = -81985529216486896n;
+    ['big', 'little'].forEach(function(endian) {
+        var w = new BinaryWriter(endian);
+        w.WriteInt64(value);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        assert.equal(r.ReadInt64(), value);
+    });
+});
+
+test('round-trip: Int64 (negative Number argument is coerced)', function() {
+    ['big', 'little'].forEach(function(endian) {
+        var w = new BinaryWriter(endian);
+        w.WriteInt64(-123);
+        var r = new BinaryReader(w.ByteBuffer, endian);
+        assert.equal(r.ReadInt64(), -123n);
+    });
+});

package/test/writer.test.js

@@ -0,0 +1,115 @@
+var test = require('node:test');
+var assert = require('node:assert/strict');
+var binutils = require('../binutils.js');
+var BinaryWriter = binutils.BinaryWriter;
+
+function bytes(writer) {
+    return Array.from(writer.ByteBuffer);
+}
+
+test('BinaryWriter: constructor defaults', function() {
+    var w = new BinaryWriter();
+    assert.equal(w.Endianness, 'big');
+    assert.equal(w.Encoding, 'ascii');
+    assert.equal(w.Length, 0);
+    assert.equal(w.ByteBuffer.length, 0);
+});
+
+test('BinaryWriter: WriteUInt8', function() {
+    var w = new BinaryWriter();
+    w.WriteUInt8(200);
+    assert.deepEqual(bytes(w), [200]);
+    assert.equal(w.Length, 1);
+});
+
+test('BinaryWriter: WriteInt8 (signed)', function() {
+    var w = new BinaryWriter();
+    w.WriteInt8(-1);
+    assert.deepEqual(bytes(w), [0xFF]);
+    assert.equal(w.Length, 1);
+});
+
+test('BinaryWriter: WriteUInt16 honors endianness', function() {
+    var big = new BinaryWriter('big');
+    big.WriteUInt16(0x1234);
+    assert.deepEqual(bytes(big), [0x12, 0x34]);
+    assert.equal(big.Length, 2);
+
+    var little = new BinaryWriter('little');
+    little.WriteUInt16(0x1234);
+    assert.deepEqual(bytes(little), [0x34, 0x12]);
+});
+
+test('BinaryWriter: WriteUInt32 honors endianness', function() {
+    var big = new BinaryWriter('big');
+    big.WriteUInt32(0x12345678);
+    assert.deepEqual(bytes(big), [0x12, 0x34, 0x56, 0x78]);
+    assert.equal(big.Length, 4);
+
+    var little = new BinaryWriter('little');
+    little.WriteUInt32(0x12345678);
+    assert.deepEqual(bytes(little), [0x78, 0x56, 0x34, 0x12]);
+});
+
+test('BinaryWriter: WriteInt16 / WriteInt32 (signed)', function() {
+    var w16 = new BinaryWriter('big');
+    w16.WriteInt16(-2);
+    assert.deepEqual(bytes(w16), [0xFF, 0xFE]);
+
+    var w32 = new BinaryWriter('little');
+    w32.WriteInt32(-1);
+    assert.deepEqual(bytes(w32), [0xFF, 0xFF, 0xFF, 0xFF]);
+});
+
+test('BinaryWriter: WriteFloat', function() {
+    var big = new BinaryWriter('big');
+    big.WriteFloat(1.5);
+    assert.deepEqual(bytes(big), [0x3F, 0xC0, 0x00, 0x00]);
+    assert.equal(big.Length, 4);
+
+    var little = new BinaryWriter('little');
+    little.WriteFloat(1.5);
+    assert.deepEqual(bytes(little), [0x00, 0x00, 0xC0, 0x3F]);
+});
+
+test('BinaryWriter: WriteDouble', function() {
+    var w = new BinaryWriter('big');
+    w.WriteDouble(1.5);
+    assert.deepEqual(bytes(w), [0x3F, 0xF8, 0, 0, 0, 0, 0, 0]);
+    assert.equal(w.Length, 8);
+});
+
+test('BinaryWriter: WriteBytes accepts an array', function() {
+    var w = new BinaryWriter();
+    w.WriteBytes([1, 2, 3]);
+    assert.deepEqual(bytes(w), [1, 2, 3]);
+    assert.equal(w.Length, 3);
+});
+
+test('BinaryWriter: WriteBytes accepts a Buffer', function() {
+    var w = new BinaryWriter();
+    w.WriteBytes(Buffer.from([9, 8, 7]));
+    assert.deepEqual(bytes(w), [9, 8, 7]);
+    assert.equal(w.Length, 3);
+});
+
+test('BinaryWriter: WriteBytes accepts a string (per-char codes)', function() {
+    var w = new BinaryWriter();
+    w.WriteBytes('ABC');
+    assert.deepEqual(bytes(w), [65, 66, 67]);
+    assert.equal(w.Length, 3);
+});
+
+test('BinaryWriter: WriteBytes rejects non-Buffer/non-Array input', function() {
+    assert.throws(function() { new BinaryWriter().WriteBytes(4); }, /Invalid Buffer object/);
+    assert.throws(function() { new BinaryWriter().WriteBytes({}); }, /Invalid Buffer object/);
+});
+
+test('BinaryWriter: multiple writes accumulate and track Length', function() {
+    var w = new BinaryWriter('big');
+    w.WriteUInt8(1);
+    w.WriteUInt16(0x0203);
+    w.WriteUInt32(0x04050607);
+    assert.deepEqual(bytes(w), [1, 2, 3, 4, 5, 6, 7]);
+    assert.equal(w.Length, 7);
+});