@kikuchan/binary-reader 0.1.0-alpha.3 → 0.1.0-alpha.4

package/README.md

@@ -0,0 +1,71 @@
+# @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]`.

package/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,`__esModule`,{value:!0});var e=class{#e;#t;#n;#r={};constructor(e,t){ArrayBuffer.isView(e)?this.#e=new DataView(e.buffer,e.byteOffset,e.byteLength):this.#e=new DataView(e),this.#t=0,this.#n=t?.littleEndian}get position(){return this.#t}get size(){return this.#e.byteLength}get remain(){return this.size-this.position}eof(){return this.remain<=0}seek(e){if(typeof e==`string`){let t=this.#r[e];if(t===void 0)throw Error(`seek: no such bookmark`);e=t}return typeof e==`number`&&(this.#t=Math.min(Math.max(e,0),this.size)),this}bookmark(e){return this.#r[e]=this.#t,this}rewind(){return this.seek(0)}skip(e){return this.seek(this.#t+(e??1))}align(e){if(!(e>0))throw RangeError(`align(n): n must be > 0`);return this.position%e?this.skip(e-this.position%e):this}peekBytes(e){e===void 0&&(e=this.remain);let t=this.#e.byteOffset+this.position;return new Uint8Array(this.#e.buffer.slice(t,t+e))}readUint8(){let e=this.#e.getUint8(this.position);return this.skip(1),e}readUint16(e){let t=this.#e.getUint16(this.position,e??this.#n);return this.skip(2),t}readUint16le(){return this.readUint16(!0)}readUint16be(){return this.readUint16(!1)}readUint32(e){let t=this.#e.getUint32(this.position,e??this.#n);return this.skip(4),t}readUint32le(){return this.readUint32(!0)}readUint32be(){return this.readUint32(!1)}readUint64(e){let t=this.#e.getBigUint64(this.position,e??this.#n);return this.skip(8),t}readUint64le(){return this.readUint64(!0)}readUint64be(){return this.readUint64(!1)}readInt8(){let e=this.#e.getInt8(this.position);return this.skip(1),e}readInt16(e){let t=this.#e.getInt16(this.position,e??this.#n);return this.skip(2),t}readInt16le(){return this.readInt16(!0)}readInt16be(){return this.readInt16(!1)}readInt32(e){let t=this.#e.getInt32(this.position,e??this.#n);return this.skip(4),t}readInt32le(){return this.readInt32(!0)}readInt32be(){return this.readInt32(!1)}readInt64(e){let t=this.#e.getBigInt64(this.position,e??this.#n);return this.skip(8),t}readInt64le(){return this.readInt64(!0)}readInt64be(){return this.readInt64(!1)}readFloat16(e){let t=this.#e.getFloat16(this.position,e??this.#n);return this.skip(2),t}readFloat16le(){return this.readFloat16(!0)}readFloat16be(){return this.readFloat16(!1)}readFloat32(e){let t=this.#e.getFloat32(this.position,e??this.#n);return this.skip(4),t}readFloat32le(){return this.readFloat32(!0)}readFloat32be(){return this.readFloat32(!1)}readFloat64(e){let t=this.#e.getFloat64(this.position,e??this.#n);return this.skip(8),t}readFloat64le(){return this.readFloat64(!0)}readFloat64be(){return this.readFloat64(!1)}#i(){let e=this.remain;for(let t=0;t<e;t++)if(this.#e.getUint8(this.position+t)===0)return t}readBytes(e){let t=this.peekBytes(e);return t&&this.skip(t.byteLength),t}readString(e,t){let n=this.remain,r=0;if(e===void 0&&(e=this.#i(),r=1),e===void 0||n<e)return;let i=this.peekBytes(e);try{if(typeof t==`function`){let n=t(i);return this.skip(e+r),n}else{let n=new TextDecoder(t??`utf-8`,{fatal:!0}).decode(i);return this.skip(e+r),n}}catch{return}}},t=e;exports.BinaryReader=e,exports.default=t;

package/index.d.cts

@@ -0,0 +1,55 @@
+//#region src/index.d.ts
+type BinaryLike = Uint8Array | Uint8ClampedArray | ArrayBufferLike | DataView;
+type Options = {
+  littleEndian?: boolean;
+};
+declare class BinaryReader {
+  #private;
+  constructor(u8: BinaryLike, opts?: Options);
+  get position(): number;
+  get size(): number;
+  get remain(): number;
+  eof(): boolean;
+  seek(n: number | string): this;
+  bookmark(s: string): this;
+  rewind(): this;
+  skip(n?: number): this;
+  align(n: number): this;
+  peekBytes(n?: number): Uint8Array<ArrayBuffer | SharedArrayBuffer>;
+  readUint8(): number;
+  readUint16(littleEndian?: boolean): number;
+  readUint16le(): number;
+  readUint16be(): number;
+  readUint32(littleEndian?: boolean): number;
+  readUint32le(): number;
+  readUint32be(): number;
+  readUint64(littleEndian?: boolean): bigint;
+  readUint64le(): bigint;
+  readUint64be(): bigint;
+  readInt8(): number;
+  readInt16(littleEndian?: boolean): number;
+  readInt16le(): number;
+  readInt16be(): number;
+  readInt32(littleEndian?: boolean): number;
+  readInt32le(): number;
+  readInt32be(): number;
+  readInt64(littleEndian?: boolean): bigint;
+  readInt64le(): bigint;
+  readInt64be(): bigint;
+  readFloat16(littleEndian?: boolean): number;
+  readFloat16le(): number;
+  readFloat16be(): number;
+  readFloat32(littleEndian?: boolean): number;
+  readFloat32le(): number;
+  readFloat32be(): number;
+  readFloat64(littleEndian?: boolean): number;
+  readFloat64le(): number;
+  readFloat64be(): number;
+  readBytes(n?: number): Uint8Array<ArrayBuffer | SharedArrayBuffer>;
+  /**
+   * @returns string. undefined on oversize or EOF.
+   */
+  readString(len?: number, encoding?: string | ((u8: Uint8Array) => string)): string | undefined;
+}
+//#endregion
+export { BinaryLike, BinaryReader, BinaryReader as default };

package/package.json

@@ -4,7 +4,7 @@
   "keywords": [
     "binary-reader"
   ],
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.4",
   "type": "module",
   "main": "./index.js",
   "author": "kikuchan <kikuchan98@gmail.com>",
@@ -14,7 +14,8 @@
   "exports": {
     ".": {
       "types": "./index.d.ts",
-      "import": "./index.js"
+      "import": "./index.js",
+      "require": "./index.cjs"
     }
   },
   "repository": {