Class BytesIO

A versatile in-memory binary stream class utilizing Node.js Buffers. Mimics the behavior of Python's built-in io.BytesIO module, providing a stream-like interface for reading and writing binary data in memory.

Supports sequential and random-access operations using a seekable internal pointer, and provides convenient helper methods to read and write integers, floats, doubles, and raw buffers.

Remarks

This class is highly optimized for performance and is particularly useful in environments requiring low-level binary manipulation, such as network protocols, file parsers, and custom serializers.

Example

Writing and Reading Data:

import { BytesIO } from '@tgsnake/bytesio';

// Create a BytesIO instance from existing data
const stream = BytesIO.from([0x01, 0x02, 0x03, 0x04]);

// Read a 32-bit signed integer in little-endian format
const intVal = stream.readInt32LE(); // Reads 4 bytes and advances pointer
console.log(intVal); // Output: 67305985

Example

Seeking the Stream Pointer:

const stream = BytesIO.from('Hello, World!', 'utf-8');

// Seek to position 7 (from the beginning of the buffer)
stream.seek(7, 0);

// Read remaining bytes
const msg = stream.read().toString('utf-8');
console.log(msg); // Output: 'World!'

Index

Constructors

constructor

Accessors

buffer length post

Constructors

constructor

new BytesIO(buffer?: Buffer): BytesIO
Initializes a new instance of the BytesIO class.
Parameters
- buffer: Buffer = ...
  
  The initial binary buffer to populate the BytesIO instance with. Defaults to an empty buffer.
Returns BytesIO
- Defined in BytesIO.ts:68

Accessors

buffer

get buffer(): Buffer
Gets the raw, underlying Buffer instance managed by this BytesIO object.

Returns Buffer

The underlying Buffer instance.
- Defined in BytesIO.ts:398

length

get length(): number
Gets the total size of the underlying buffer in bytes.

Returns number

The byte length of the buffer.
- Defined in BytesIO.ts:389

post

get post(): number
Gets the current read/write pointer (offset index) within the buffer.

Returns number

The current pointer position.
- Defined in BytesIO.ts:407

Methods

read

read(length?: number): Buffer
Reads binary data from the current pointer position. Advances the internal pointer by the number of bytes successfully read.
Parameters
- Optionallength: number
  
  The number of bytes to read. - If undefined or not provided, reads all remaining bytes from the current pointer to the end of the buffer. - If provided, reads at most length bytes from the current pointer position.
Returns Buffer

A new Buffer containing the read bytes. If the pointer is out of bounds or length is less than 1, returns an empty buffer.
- Defined in BytesIO.ts:164

readBigInt64BE

readBigInt64BE(size?: number): bigint
Reads a signed 64-bit BigInt in big-endian format (BigInt64BE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns bigint

The read signed 64-bit BigInt (value ranges from -9,223,372,036,854,775,808n to 9,223,372,036,854,775,807n).
- Defined in BytesIO.ts:250

readBigInt64LE

readBigInt64LE(size?: number): bigint
Reads a signed 64-bit BigInt in little-endian format (BigInt64LE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns bigint

The read signed 64-bit BigInt (value ranges from -9,223,372,036,854,775,808n to 9,223,372,036,854,775,807n).
- Defined in BytesIO.ts:237

readBigUInt64BE

readBigUInt64BE(size?: number): bigint
Reads an unsigned 64-bit BigInt in big-endian format (BigUInt64BE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns bigint

The read unsigned 64-bit BigInt (value ranges from 0n to 18,446,744,073,709,551,615n).
- Defined in BytesIO.ts:276

readBigUInt64LE

readBigUInt64LE(size?: number): bigint
Reads an unsigned 64-bit BigInt in little-endian format (BigUInt64LE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns bigint

The read unsigned 64-bit BigInt (value ranges from 0n to 18,446,744,073,709,551,615n).
- Defined in BytesIO.ts:263

readDoubleBE

readDoubleBE(size?: number): number
Reads a 64-bit double-precision floating-point number in big-endian format (DoubleBE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns number

The read double-precision floating-point number.
- Defined in BytesIO.ts:302

readDoubleLE

readDoubleLE(size?: number): number
Reads a 64-bit double-precision floating-point number in little-endian format (DoubleLE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 8
  
  The number of bytes to advance the pointer after reading. Defaults to 8.
Returns number

The read double-precision floating-point number.
- Defined in BytesIO.ts:289

readFloatBE

readFloatBE(size?: number): number
Reads a 32-bit single-precision floating-point number in big-endian format (FloatBE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read single-precision floating-point number.
- Defined in BytesIO.ts:328

readFloatLE

readFloatLE(size?: number): number
Reads a 32-bit single-precision floating-point number in little-endian format (FloatLE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read single-precision floating-point number.
- Defined in BytesIO.ts:315

readInt32BE

readInt32BE(size?: number): number
Reads a signed 32-bit integer in big-endian format (Int32BE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read signed 32-bit integer (value ranges from -2,147,483,648 to 2,147,483,647).
- Defined in BytesIO.ts:198

readInt32LE

readInt32LE(size?: number): number
Reads a signed 32-bit integer in little-endian format (Int32LE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read signed 32-bit integer (value ranges from -2,147,483,648 to 2,147,483,647).
- Defined in BytesIO.ts:185

readUInt32BE

readUInt32BE(size?: number): number
Reads an unsigned 32-bit integer in big-endian format (UInt32BE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read unsigned 32-bit integer.
- Defined in BytesIO.ts:224

readUInt32LE

readUInt32LE(size?: number): number
Reads an unsigned 32-bit integer in little-endian format (UInt32LE) from the current pointer position. Automatically advances the pointer by the specified size of bytes.
Parameters
- size: number = 4
  
  The number of bytes to advance the pointer after reading. Defaults to 4.
Returns number

The read unsigned 32-bit integer (value ranges from 0 to 4,294,967,295).
- Defined in BytesIO.ts:211

seek

seek(offset: number, whence?: number): number
Adjusts the position of the internal read/write pointer (offset cursor).
Parameters
- offset: number
  
  The byte offset relative to the reference point defined by whence. - If whence is 0, must be 0 or positive. - If whence is 2, must be less than 0.
- whence: number = 0
  
  The reference point for the seek operation: - 0 (default): Absolute positioning from the start of the buffer. - 1: Relative positioning from the current pointer position. - 2: Relative positioning from the end of the buffer (expects a negative offset).
Returns number

The new pointer position (relative to the start of the buffer).

Throws

If whence is 0 and offset is negative.

Throws

If whence is 2 and offset is non-negative.

Throws

If whence is 2 and the absolute seek location would be less than 0.

Throws

If whence is not 0, 1, or 2.
- Defined in BytesIO.ts:90

slice

slice(...args: any[]): BytesIO
Returns a new BytesIO instance populated with a subarray/slice of the current buffer. The slice is created using the standard Buffer.subarray method, meaning it shares the same allocated memory as the original buffer.
Parameters
- ...args: any[]
  
  Arguments passed directly to the underlying Buffer.subarray method. Typically [start[, end]], where start is the starting index (default 0) and end is the ending index (exclusive, default buffer length).
Returns BytesIO

A new BytesIO instance containing the sliced view of the buffer.
- Defined in BytesIO.ts:126

toJSON

toJSON(): { data: number[]; type: "Buffer" }
Returns a JSON representation of the underlying buffer. This is useful for serializing the binary data, representing it as an object containing a type property (typically "Buffer") and a data array of byte values.

Returns { data: number[]; type: "Buffer" }

An object representing the buffer in JSON format.
- Defined in BytesIO.ts:137

toString

toString(...args: any[]): string
Decodes the underlying buffer to a string according to the specified encoding.
Parameters
- ...args: any[]
  
  Arguments passed directly to the underlying Buffer.toString method. Typically [encoding[, start[, end]]], where: - encoding is the character encoding to use (e.g., 'utf8', 'hex', 'base64'). - start is the byte offset to start decoding (default 0). - end is the byte offset to stop decoding (exclusive, default buffer length).
Returns string

The decoded string representation of the buffer.
- Defined in BytesIO.ts:151

write

write(data: Buffer): BytesIO
Appends the provided binary data to the absolute end of the underlying buffer.
Parameters
- data: Buffer
  
  The Buffer containing the binary data to append.
Returns BytesIO

The current BytesIO instance, enabling method chaining.

Remarks

This operation concatenates the new data to the existing buffer, increasing its total length. Note that this method does not modify or advance the current pointer position (post).
- Defined in BytesIO.ts:344

`Static`alloc

alloc(size: number): BytesIO
Allocates a new BytesIO instance populated with a zero-filled buffer of the specified size.
Parameters
- size: number
  
  The number of bytes to allocate for the initial buffer.
Returns BytesIO

A new BytesIO instance with the allocated buffer.
- Defined in BytesIO.ts:358

`Static`concat

concat(data: Buffer<ArrayBufferLike>[]): BytesIO
Concatenates an array of Buffer instances into a single BytesIO instance.
Parameters
- data: Buffer<ArrayBufferLike>[]
  
  An array of Buffer objects to be joined together in order.
Returns BytesIO

A new BytesIO instance containing the concatenated binary data.
- Defined in BytesIO.ts:380

`Static`from

from(input: any, encode?: any): BytesIO
Creates a new BytesIO instance from the given input data, delegating to Buffer.from.
Parameters
- input: any
  
  The input data. Can be a Buffer, Uint8Array, ArrayBuffer, SharedArrayBuffer, an Array of numbers, a string, or an object with a valueOf or Symbol.toPrimitive method.
- Optionalencode: any
  
  The character encoding to use if the input is a string (e.g., 'utf8', 'hex', 'base64').
Returns BytesIO

A new BytesIO instance initialized with the parsed input data.
- Defined in BytesIO.ts:370

Class BytesIO

Remarks

Example

Example

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns BytesIO

Accessors

buffer

Returns Buffer

length

Returns number

post

Returns number

Methods

read

Parameters

Returns Buffer

readBigInt64BE

Parameters

Returns bigint

readBigInt64LE

Parameters

Returns bigint

readBigUInt64BE

Parameters

Returns bigint

readBigUInt64LE

Parameters

Returns bigint

readDoubleBE

Parameters

Returns number

readDoubleLE

Parameters

Returns number

readFloatBE

Parameters

Returns number

readFloatLE

Parameters

Returns number

readInt32BE

Parameters

Returns number

readInt32LE

Parameters

Returns number

readUInt32BE

Parameters

Returns number

readUInt32LE

Parameters

Returns number

seek

Parameters

Returns number

Throws

Throws

Throws

Throws

slice

Parameters

Returns BytesIO

toJSON

Returns { data: number[]; type: "Buffer" }

toString

Parameters

Returns string

write

Parameters

Returns BytesIO

Remarks

Staticalloc

Parameters

`Static`alloc

`Static`concat

`Static`from