@tgsnake/bytesio 1.0.0 → 2.0.0-browser.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 tgsnake
+Copyright (c) 2026 tgsnake
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,28 +1,213 @@
-# BytesIO 🚀
+# `@tgsnake/bytesio` 🚀
 
-A simple Buffer implementation inspired by Python's `BytesIO`.  
-This project was originally based on the source code from [`@tgsnake/core`](https://github.com/tgsnake/core). 🐍
+A high-performance, lightweight, seekable in-memory binary stream library for JavaScript and TypeScript, heavily inspired by Python's `io.BytesIO`.
 
-## Features ✨
+Originally decoupled from [`@tgsnake/core`](https://github.com/tgsnake/core) to serve as a high-performance standalone module for Node.js, Deno, Bun, and browser environments.
 
-- In-memory byte stream operations 💾
-- Read and write bytes efficiently ⚡
-- Python-like API for ease of use 🐍
+[![JSR Badge](https://jsr.io/badges/@tgsnake/bytesio)](https://jsr.io/@tgsnake/bytesio) [![NPM Version](https://img.shields.io/npm/v/@tgsnake/bytesio.svg)](https://www.npmjs.com/package/@tgsnake/bytesio) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-## Installation 📦
+---
+
+## ⚡ Key Features
+
+- 💾 **Seekable In-Memory Streams**: Track pointer position automatically with sequential or random-access seek operations (`0` absolute, `1` relative, `2` from-end).
+- ⚙️ **Direct Node.js Buffer API**: Provides highly optimized operations to read and write integers, floats, doubles, bigints, and subarrays directly from/to memory.
+- ⚡ **Cross-Platform**: Fully compatible with Node.js, Deno, Bun, and browsers with a centralized polyfill layer.
+- 🚀 **Zero Dependencies**: Lightweight and fast footprint designed for modern high-performance networking, protocol parsing, and binary serialization.
+- 📦 **Modern ESM & Typescript**: Written in TypeScript with first-class JSR support, full type safety, and clean ESM packaging.
+
+---
+
+## ⚠️ Requirements & Compatibility in v2.0.0
+
+Version `2.0.0` introduces modern packaging improvements to align with the current JS/TS ecosystem:
+
+- **Pure ESM (EcmaScript Modules)**: The package is now fully ESM. Since Node 20+ has support `require(ESM)`, this package now has fully writen to ESM. Minimum Node.js version is now **>= 22.0.0**. Formal support has been added for **Deno (>= 1.0.0)** and **Bun (>= 1.0.0)**.
+- **First-class JSR & Deno Support**: Native Deno integration and standard JSR publishing.
+
+---
+
+## 📦 Installation
+
+Install `@tgsnake/bytesio` using your favorite package manager:
+
+### Node.js / Bun (via NPM, Yarn, PNPM, Bun)
 
 ```bash
-# Example installation command
+# Using npm
 npm install @tgsnake/bytesio
+
+# Using yarn
+yarn add @tgsnake/bytesio
+
+# Using pnpm
+pnpm add @tgsnake/bytesio
+
+# Using bun
+bun add @tgsnake/bytesio
+```
+
+### Deno / JSR (Native Deno Import)
+
+```bash
+# Add the dependency via JSR
+deno add jsr:@tgsnake/bytesio
 ```
 
-## Usage 🛠️
+---
+
+## 🛠️ Detailed Usage & Examples
+
+### 1. In-Memory Write & Read Operations
 
-```ts
+```typescript
 import { BytesIO } from '@tgsnake/bytesio';
+import { Buffer } from 'node:buffer'; // or standard global Buffer in modern environments
 
+// 1. Create a stream and write binary data
 const stream = new BytesIO();
-stream.write(Buffer.from([1, 2, 3]));
+stream.write(Buffer.from([0x10, 0x20]));
+stream.write(Buffer.from([0x30, 0x40]));
+
+// Check pointer and stream length
+console.log('Stream length:', stream.length); // Output: 4 bytes
+console.log('Current pointer:', stream.post); // Output: 0 (write does not advance the seek pointer)
+
+// 2. Seek and read sequentially
 stream.seek(0);
-console.log(stream.read(3)); // Output: <Buffer 01 02 03>
+const allBytes = stream.read();
+console.log(allBytes); // Output: <Buffer 10 20 30 40>
+
+// 3. Read specific slice size
+stream.seek(1); // Seek to offset 1
+const chunk = stream.read(2);
+console.log(chunk); // Output: <Buffer 20 30>
+console.log('Pointer position:', stream.post); // Output: 3 (advanced by 2)
 ```
+
+### 2. Reading Binary Data Types (Integers, BigInts, Floats)
+
+`BytesIO` provides built-in wrapper methods for Node.js `Buffer` integer, bigint, and float parsing. They automatically advance the stream pointer by the number of read bytes (or a customized step size).
+
+```typescript
+import { BytesIO } from '@tgsnake/bytesio';
+
+// Setup buffer containing mixed data: [Int32LE, BigInt64BE, FloatLE]
+const dataStream = BytesIO.alloc(20);
+
+// Allocate and write manually or instantiate from array
+const stream = BytesIO.from([
+  0x78,
+  0x56,
+  0x34,
+  0x12, // 305419896 (Int32LE)
+  0x00,
+  0x00,
+  0x00,
+  0x00,
+  0x00,
+  0x00,
+  0x00,
+  0x0a, // 10n (BigInt64BE)
+  0x00,
+  0x00,
+  0xa0,
+  0x40, // 5.0 (FloatLE)
+]);
+
+// Read 32-bit signed integer (little-endian)
+const val1 = stream.readInt32LE(); // Reads 4 bytes and advances pointer by 4
+console.log(val1); // Output: 305419896
+console.log(stream.post); // Output: 4
+
+// Read 64-bit signed BigInt (big-endian)
+const val2 = stream.readBigInt64BE(); // Reads 8 bytes and advances pointer by 8
+console.log(val2); // Output: 10n
+console.log(stream.post); // Output: 12
+
+// Read 32-bit float (little-endian)
+const val3 = stream.readFloatLE(); // Reads 4 bytes and advances pointer by 4
+console.log(val3); // Output: 5.0
+console.log(stream.post); // Output: 16
+```
+
+### 3. Seeking Modes
+
+You can control stream tracking with standard file-seek positioning (`whence` options):
+
+```typescript
+import { BytesIO } from '@tgsnake/bytesio';
+
+const stream = BytesIO.from('Hello, Advanced BytesIO!', 'utf-8');
+
+// whence = 0 (Absolute seek relative to the beginning of the stream)
+stream.seek(7, 0);
+console.log(stream.read(8).toString('utf-8')); // Output: 'Advanced'
+
+// whence = 1 (Relative seek from the current pointer location)
+stream.seek(-8, 1); // Move backward 8 bytes
+console.log(stream.read(8).toString('utf-8')); // Output: 'Advanced'
+
+// whence = 2 (Seek relative to the end of the stream - expects a negative offset)
+stream.seek(-1, 2); // Move to the last byte
+console.log(stream.read().toString('utf-8')); // Output: '!'
+```
+
+---
+
+## 📖 API Documentation
+
+### Constructor
+
+- `new BytesIO(buffer?: Buffer)`: Creates an in-memory stream wrapper around an optional initial Node.js `Buffer`.
+
+### Instance Properties
+
+- `length`: `number` (Read-only) — The total size of the underlying buffer in bytes.
+- `buffer`: `Buffer` (Read-only) — Access the underlying raw `Buffer` object.
+- `post`: `number` (Read-only) — The current read/write pointer (byte index) of the stream.
+
+### Instance Methods
+
+- `seek(offset: number, whence?: number): number` — Moves the internal pointer. `whence` supports:
+  - `0`: Seek from start (absolute).
+  - `1`: Seek relative to current position.
+  - `2`: Seek relative to the end (requires negative offset).
+- `read(length?: number): Buffer` — Reads up to `length` bytes from the current pointer position and advances the pointer. If `length` is omitted, reads to the end.
+- `slice(start?: number, end?: number): BytesIO` — Returns a new `BytesIO` instance referencing a subarray slice of the original buffer (shared memory).
+- `write(data: Buffer): this` — Appends binary data to the absolute end of the buffer (increases length, doesn't change `post`).
+- `toJSON(): { type: 'Buffer'; data: number[] }` — Serializes the underlying buffer data to JSON format.
+- `toString(encoding?: string, start?: number, end?: number): string` — Decodes the buffer to a string.
+
+#### Custom Decoders (Integer/Float/BigInt)
+
+Every decoder reads the specified data type at the current pointer position and advances the pointer by `size` bytes (defaults to the type size):
+
+- `readInt32LE(size?: number): number`
+- `readInt32BE(size?: number): number`
+- `readUInt32LE(size?: number): number`
+- `readUInt32BE(size?: number): number`
+- `readBigInt64LE(size?: number): bigint`
+- `readBigInt64BE(size?: number): bigint`
+- `readBigUInt64LE(size?: number): bigint`
+- `readBigUInt64BE(size?: number): bigint`
+- `readDoubleLE(size?: number): number`
+- `readDoubleBE(size?: number): number`
+- `readFloatLE(size?: number): number`
+- `readFloatBE(size?: number): number`
+
+### Static Methods
+
+- `BytesIO.alloc(size: number): BytesIO` — Creates a new instance with a zero-filled buffer of the specified size.
+- `BytesIO.from(input: any, encoding?: string): BytesIO` — Creates a new instance from an array, string, buffer, or ArrayBuffer.
+- `BytesIO.concat(list: Buffer[]): BytesIO` — Joins an array of buffers into a single `BytesIO` instance.
+
+---
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE).
+
+---
+
+Built with ♥️ by the **tgsnake** team. Contributions and issues are welcome!

package/package.json

@@ -1,35 +1,48 @@
-{
-  "name": "@tgsnake/bytesio",
-  "packageManager": "yarn@4.9.2",
-  "version": "1.0.0",
-  "description": "A simple BytesIO implementation for Typescript",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "clean": "rm -rf dist",
-    "prepare": "yarn build",
-    "prettier": "NODE_OPTIONS=--max_old_space_size=4096 prettier -w .",
-    "docs": "typedoc --out docs src/BytesIO.ts --excludePrivate --excludeProtected --excludeInternal --theme default --readme none"
-  },
-  "homepage": "https://tgsnake.js.org",
-  "keywords": [
-    "tgsnake",
-    "BytesIO",
-    "Buffer"
-  ],
-  "bugs": "https://github.com/tgsnake/bytesio/issues",
-  "repository": "https://github.com/tgsnake/bytesio",
-  "author": "butthx",
-  "files": [
-    "dist/**/**"
-  ],
-  "license": "MIT",
-  "devDependencies": {
-    "@types/bun": "^1.2.18",
-    "@types/node": "^24.0.13",
-    "prettier": "^3.6.2",
-    "typedoc": "^0.28.7",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "@tgsnake/bytesio",
+  "packageManager": "yarn@4.9.2",
+  "version": "2.0.0-browser.0",
+  "description": "A simple BytesIO implementation for Typescript",
+  "main": "./browser/mod.js",
+  "types": "./browser/mod.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "build:jsr": "node ./generator/jsr_version/index.js",
+    "clean": "rm -rf dist",
+    "prepare": "yarn build",
+    "prettier": "NODE_OPTIONS=--max_old_space_size=4096 prettier -w .",
+    "docs": "typedoc --out docs src/BytesIO.ts --excludePrivate --excludeProtected --excludeInternal --theme default --readme none"
+  },
+  "homepage": "https://tgsnake.js.org",
+  "keywords": [
+    "tgsnake",
+    "BytesIO",
+    "Buffer"
+  ],
+  "bugs": "https://github.com/tgsnake/bytesio/issues",
+  "repository": "https://github.com/tgsnake/bytesio",
+  "author": "butthx",
+  "files": [
+    "browser/**/**"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "@types/node": "^25.9.1",
+    "prettier": "^3.8.3",
+    "typedoc": "^0.28.19",
+    "typescript": "^6.0.3"
+  },
+  "engineStrict": true,
+  "engines": {
+    "node": ">=22.0.0",
+    "npm": ">=6.0.0",
+    "yarn": ">=1.0.0",
+    "deno": ">=1.0.0",
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "buffer": "^6.0.3"
+  }
+}

package/dist/BytesIO.d.ts

@@ -1,33 +0,0 @@
-import { Buffer } from 'node:buffer';
-export declare class BytesIO {
-    private _buffer;
-    private _post;
-    constructor(buffer?: Buffer);
-    seek(offset: number, whence?: number): number;
-    slice(...args: Array<any>): BytesIO;
-    toJSON(): {
-        type: "Buffer";
-        data: number[];
-    };
-    toString(...args: Array<any>): string;
-    read(length?: number): Buffer;
-    readInt32LE(size?: number): number;
-    readInt32BE(size?: number): number;
-    readUInt32LE(size?: number): number;
-    readUInt32BE(size?: number): number;
-    readBigInt64LE(size?: number): bigint;
-    readBigInt64BE(size?: number): bigint;
-    readBigUInt64LE(size?: number): bigint;
-    readBigUInt64BE(size?: number): bigint;
-    readDoubleLE(size?: number): number;
-    readDoubleBE(size?: number): number;
-    readFloatLE(size?: number): number;
-    readFloatBE(size?: number): number;
-    write(data: Buffer): BytesIO;
-    static alloc(size: number): BytesIO;
-    static from(input: any, encode?: any): BytesIO;
-    static concat(data: Array<Buffer>): BytesIO;
-    get length(): number;
-    get buffer(): Buffer;
-    get post(): number;
-}

package/dist/BytesIO.js

@@ -1,145 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.BytesIO = void 0;
-const node_buffer_1 = require("node:buffer");
-class BytesIO {
-    _buffer;
-    _post;
-    constructor(buffer = node_buffer_1.Buffer.alloc(0)) {
-        this._post = 0;
-        this._buffer = buffer;
-        return this;
-    }
-    seek(offset, whence = 0) {
-        if (whence === 0) {
-            if (offset < 0) {
-                throw new Error(`offset of BytesIO.seek must be zero or positive value when whence is 0`);
-            }
-            this._post = whence;
-        }
-        else if (whence === 1) {
-            this._post += offset;
-        }
-        else if (whence === 2) {
-            if (offset >= 0) {
-                throw new Error(`offset of BytesIO.seek must be less than zero or negative value when whence is 2`);
-            }
-            if (node_buffer_1.Buffer.byteLength(this._buffer) + offset < 0) {
-                throw new Error(`offset out of range, offset ${offset} is less than the available buffer length.`);
-            }
-            this._post = node_buffer_1.Buffer.byteLength(this._buffer) + offset;
-        }
-        else {
-            throw new Error(`whence must be 0 or 1 or 2, but receive ${whence}`);
-        }
-        return this._post;
-    }
-    slice(...args) {
-        return new BytesIO(this._buffer.subarray(...args));
-    }
-    toJSON() {
-        return this._buffer.toJSON();
-    }
-    toString(...args) {
-        return this._buffer.toString(...args);
-    }
-    read(length) {
-        if (length === undefined) {
-            const results = this._buffer.subarray(this._post);
-            this.seek(node_buffer_1.Buffer.byteLength(results), 1);
-            return results;
-        }
-        if (length >= 1 && this._post <= node_buffer_1.Buffer.byteLength(this._buffer)) {
-            const results = this._buffer.subarray(this._post, this._post + length);
-            this.seek(length, 1);
-            return results;
-        }
-        return node_buffer_1.Buffer.alloc(0);
-    }
-    readInt32LE(size = 4) {
-        const results = this._buffer.readInt32LE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readInt32BE(size = 4) {
-        const results = this._buffer.readInt32BE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readUInt32LE(size = 4) {
-        const results = this._buffer.readUInt32LE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readUInt32BE(size = 4) {
-        const results = this._buffer.readInt32BE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readBigInt64LE(size = 8) {
-        const results = this._buffer.readBigInt64LE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readBigInt64BE(size = 8) {
-        const results = this._buffer.readBigInt64BE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readBigUInt64LE(size = 8) {
-        const results = this._buffer.readBigUInt64LE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readBigUInt64BE(size = 8) {
-        const results = this._buffer.readBigUInt64BE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readDoubleLE(size = 8) {
-        const results = this._buffer.readDoubleLE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readDoubleBE(size = 8) {
-        const results = this._buffer.readDoubleBE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readFloatLE(size = 4) {
-        const results = this._buffer.readFloatLE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    readFloatBE(size = 4) {
-        const results = this._buffer.readFloatBE(this._post);
-        this.seek(size, 1);
-        return results;
-    }
-    write(data) {
-        this._buffer = node_buffer_1.Buffer.concat([
-            this._buffer,
-            data,
-        ]);
-        return this;
-    }
-    static alloc(size) {
-        return new BytesIO(node_buffer_1.Buffer.alloc(size));
-    }
-    static from(input, encode) {
-        return new BytesIO(node_buffer_1.Buffer.from(input, encode));
-    }
-    static concat(data) {
-        return new BytesIO(node_buffer_1.Buffer.concat(data));
-    }
-    get length() {
-        return node_buffer_1.Buffer.byteLength(this._buffer);
-    }
-    get buffer() {
-        return this._buffer;
-    }
-    get post() {
-        return this._post;
-    }
-}
-exports.BytesIO = BytesIO;

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export { BytesIO } from './BytesIO.js';
-export { BytesIO as default } from './BytesIO.js';

package/dist/index.js

@@ -1,7 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = exports.BytesIO = void 0;
-var BytesIO_js_1 = require("./BytesIO.js");
-Object.defineProperty(exports, "BytesIO", { enumerable: true, get: function () { return BytesIO_js_1.BytesIO; } });
-var BytesIO_js_2 = require("./BytesIO.js");
-Object.defineProperty(exports, "default", { enumerable: true, get: function () { return BytesIO_js_2.BytesIO; } });