JSPrismarine

API reference / @jsprismarine/binaryutils / BinaryStream

Class: BinaryStream ​

Defined in: BinaryStream.ts:34

A high-performance binary stream for reading and writing binary data.

Unlike Node.js native buffers which have fixed size, BinaryStream uses dynamic buffers that grow automatically during write operations. This eliminates the need for manual resizing or inefficient Buffer.concat() calls.

Examples ​

Reading data

typescript
const stream = new BinaryStream(buffer);
const value = stream.readInt();

Writing data

typescript
const stream = new BinaryStream();
stream.writeInt(42);
stream.write(Buffer.from('Hello'));  // Buffer grows automatically
const buffer = stream.getWriteBuffer();

Encoding many packets without allocating

typescript
const stream = new BinaryStream(undefined, 0, 4096);
for (const packet of queue) {
    stream.resetWrite();
    packet.encode(stream);
    offset = stream.copyInto(arena, offset);
}

Extended by ​

Constructors ​

Constructor ​

new BinaryStream(buffer?, offset?, initialCapacity?): BinaryStream

Defined in: BinaryStream.ts:49

Creates a new BinaryStream instance.

Parameters ​

buffer? ​

Buffer<ArrayBufferLike>

The array or Buffer containing binary data.

offset? ​

number = 0

The initial pointer position.

initialCapacity? ​

number = 0

Pre-allocates the write buffer to this size. Use it when the encoded size is known up front: it skips the 256 -> 512 -> 1024 ... growth ladder, and with resetWrite it lets a long-lived encoder run without allocating at all.

Returns ​

BinaryStream

Methods ​

clear() ​

clear(): void

Defined in: BinaryStream.ts:977

Clears the whole BinaryStream instance.

The write buffer and its capacity are kept, so any view previously returned by getWriteBuffer is invalidated. See resetWrite.

Returns ​

void

copyInto() ​

copyInto(target, offset?): number

Defined in: BinaryStream.ts:856

Copies the encoded bytes into a caller-owned buffer at offset and returns the offset just past them. Lets many packets be encoded into one arena with no per-packet allocation at all.

Parameters ​

target ​

Buffer

offset? ​

number = 0

Returns ​

number

the new offset

copyOut() ​

copyOut(): Buffer

Defined in: BinaryStream.ts:840

Returns the encoded bytes as an exactly-sized, standalone Buffer.

Unlike getWriteBuffer the result does not alias this stream, so it survives resetWrite, and it does not pin a pool chunk: because Buffer.allocUnsafe is pool-backed (Buffer.poolSize is 64 KB on current Node), holding on to a handful of small slices from getWriteBuffer can keep megabytes alive.

Returns ​

Buffer

feof() ​

feof(): boolean

Defined in: BinaryStream.ts:875

Returns whatever or not the read offset is at end of line.

Returns ​

boolean

getBuffer() ​

getBuffer(): Buffer

Defined in: BinaryStream.ts:912

Returns the encoded buffer.

Beware: when a read buffer is present this returns that, discarding everything written. On a stream used for both reading and writing it never returns your output.

Returns ​

Buffer

Deprecated ​

See getReadBuffer and getWriteBuffer.

getReadBuffer() ​

getReadBuffer(): Buffer<ArrayBufferLike> | null

Defined in: BinaryStream.ts:920

Returns the read buffer if available.

Returns ​

Buffer<ArrayBufferLike> | null

getReadIndex() ​

getReadIndex(): number

Defined in: BinaryStream.ts:1019

Retuns the read index.

Returns ​

number

getWriteBuffer() ​

getWriteBuffer(): Buffer

Defined in: BinaryStream.ts:936

Returns the encoded bytes as a view over this stream's internal buffer.

The view is only valid until the next write: resetWrite, clear and reuse all rewind the cursor without reallocating, so a previously returned buffer is silently overwritten by the next packet. If you queue the result - a send queue, a resend window - use copyOut or copyInto instead.

It also keeps the whole pooled 64 KB chunk it was carved from alive; retaining a scattered handful of small packets this way can pin megabytes.

Returns ​

Buffer

getWriteIndex() ​

getWriteIndex(): number

Defined in: BinaryStream.ts:1027

Returns the write index.

Returns ​

number

read() ​

read(len): Buffer

Defined in: BinaryStream.ts:62

Reads a slice of buffer by the given length.

Parameters ​

len ​

number

How many bytes to read: a nonnegative integer.

Returns ​

Buffer

Throws ​

AssertionError when len is negative or not an integer, or runs past the end.

readBoolean() ​

readBoolean(): boolean

Defined in: BinaryStream.ts:179

Reads a boolean (true or false).

Returns ​

boolean

readByte() ​

readByte(): number

Defined in: BinaryStream.ts:143

Reads an unsigned byte (0 to 255).

Returns ​

number

readDouble() ​

readDouble(): number

Defined in: BinaryStream.ts:481

Returns a 64 bit (8 bytes) big-endian flating point number.

Returns ​

number

readDoubleLE() ​

readDoubleLE(): number

Defined in: BinaryStream.ts:501

Returns a 64 bit (8 bytes) little-endian flating point number.

Returns ​

number

readFloat() ​

readFloat(): number

Defined in: BinaryStream.ts:441

Returns a 32 bit (4 bytes) big-endian flating point number.

Returns ​

number

readFloatLE() ​

readFloatLE(): number

Defined in: BinaryStream.ts:461

Returns a 32 bit (4 bytes) big-endian flating point number.

Returns ​

number

readInt() ​

readInt(): number

Defined in: BinaryStream.ts:361

Reads a 32 bit (4 bytes) big-endian signed number.

Returns ​

number

readIntLE() ​

readIntLE(): number

Defined in: BinaryStream.ts:381

Reads a 32 bit (4 bytes) signed number.

Returns ​

number

readLengthPrefixed() ​

readLengthPrefixed(): Buffer

Defined in: BinaryStream.ts:107

Reads a varuint32 byte length, then that many bytes.

Returns ​

Buffer

The bytes, a view into the stream's buffer.

readLong() ​

readLong(): bigint

Defined in: BinaryStream.ts:521

Returns a 64 bit (8 bytes) signed big-endian number.

Returns ​

bigint

readLongLE() ​

readLongLE(): bigint

Defined in: BinaryStream.ts:540

Returns a 64 bit (8 bytes) signed little-endian number.

Returns ​

bigint

readRemaining() ​

readRemaining(): Buffer

Defined in: BinaryStream.ts:888

Reads the remaining bytes and returns the buffer slice.

Returns ​

Buffer

readShort() ​

readShort(): number

Defined in: BinaryStream.ts:197

Reads a 16 bit (2 bytes) signed big-endian number.

Returns ​

number

readShortLE() ​

readShortLE(): number

Defined in: BinaryStream.ts:217

Reads a 16 bit (2 bytes) signed little-endian number.

Returns ​

number

readSignedByte() ​

readSignedByte(): number

Defined in: BinaryStream.ts:161

Reads a signed byte (-128 to 127).

Returns ​

number

readTriad() ​

readTriad(): number

Defined in: BinaryStream.ts:277

Reads a 24 bit (3 bytes) signed big-endian number.

Returns ​

number

readTriadLE() ​

readTriadLE(): number

Defined in: BinaryStream.ts:298

Reads a 24 bit (3 bytes) little-endian number.

Returns ​

number

readUnsignedInt() ​

readUnsignedInt(): number

Defined in: BinaryStream.ts:401

Reads a 32 bit (4 bytes) big-endian unsigned number.

Returns ​

number

readUnsignedIntLE() ​

readUnsignedIntLE(): number

Defined in: BinaryStream.ts:421

Reads a 32 bit (4 bytes) little-endian unsigned number.

Returns ​

number

readUnsignedLong() ​

readUnsignedLong(): bigint

Defined in: BinaryStream.ts:559

Returns a 64 bit (8 bytes) unsigned big-endian number.

Returns ​

bigint

readUnsignedLongLE() ​

readUnsignedLongLE(): bigint

Defined in: BinaryStream.ts:578

Returns a 64 bit (8 bytes) unsigned little-endian number.

Returns ​

bigint

readUnsignedShort() ​

readUnsignedShort(): number

Defined in: BinaryStream.ts:237

Reads a 16 bit (2 bytes) unsigned big-endian number.

Returns ​

number

readUnsignedShortLE() ​

readUnsignedShortLE(): number

Defined in: BinaryStream.ts:257

Reads a 16 bit (2 bytes) unsigned little-endian number.

Returns ​

number

readUnsignedTriad() ​

readUnsignedTriad(): number

Defined in: BinaryStream.ts:319

Reads a 24 bit (3 bytes) unsigned big-endian number.

Returns ​

number

readUnsignedTriadLE() ​

readUnsignedTriadLE(): number

Defined in: BinaryStream.ts:340

Reads a 24 bit (3 bytes) unsigned little-endian number.

Returns ​

number

readUnsignedVarInt() ​

readUnsignedVarInt(): number

Defined in: BinaryStream.ts:619

Reads a 32 bit unsigned number.

Returns ​

number

readUnsignedVarLong() ​

readUnsignedVarLong(): bigint

Defined in: BinaryStream.ts:702

Reads a 64 bit unsigned variable-length number.

Returns ​

bigint

readVarInt() ​

readVarInt(): number

Defined in: BinaryStream.ts:597

Reads a 32 bit (4 bytes) zigzag-encoded number.

Returns ​

number

readVarLong() ​

readVarLong(): bigint

Defined in: BinaryStream.ts:675

Reads a 64 bit zigzag-encoded variable-length number.

Returns ​

bigint

readVarString() ​

readVarString(): string

Defined in: BinaryStream.ts:126

Reads a string: a varuint32 byte length, then UTF-8 bytes, the form Bedrock writes strings in. Named apart from readString because RakNet's packets read theirs with a u16 length. The docs' string primitive

Returns ​

string

The read string.

reserve() ​

reserve(capacity): this

Defined in: BinaryStream.ts:805

Grows the write buffer so that at least capacity bytes can be written without any further allocation, and returns this stream.

Pre-sizing skips the 256 -> 512 -> 1024 ... growth ladder, each step of which copies the whole payload; a 3 KB packet starting from the 256-byte floor performs five allocations and memcpy's 1.25x its own size before it is done.

Parameters ​

capacity ​

number

Returns ​

this

resetWrite() ​

resetWrite(): void

Defined in: BinaryStream.ts:827

Rewinds the write cursor while keeping the allocated capacity, so a long-lived encoder reaches a steady state where it never allocates again. This is the intended way to reuse a stream for many packets.

Note the aliasing contract, which it shares with clear and reuse: any buffer previously handed out by getWriteBuffer is a view over this stream's memory and is invalidated by this call. Use copyOut or copyInto for output you intend to keep.

Returns ​

void

reuse() ​

reuse(buf): void

Defined in: BinaryStream.ts:991

Conventional method to reuse the stream without having to create a new BinaryStream instance.

The write buffer and its capacity are kept, so any view previously returned by getWriteBuffer is invalidated. See resetWrite.

Parameters ​

buf ​

Buffer

The new buffer instance.

Returns ​

void

setBuffer() ​

setBuffer(buf): void

Defined in: BinaryStream.ts:946

Sets the buffer for reading. make sure to reset the reading index!

Parameters ​

buf ​

Buffer

The new Buffer.

Returns ​

void

Deprecated ​

See setReadBuffer and setWriteBuffer.

setReadBuffer() ​

setReadBuffer(buf, rIndex?): void

Defined in: BinaryStream.ts:955

Sets the buffer for reading.

Parameters ​

buf ​

Buffer

The new Buffer.

rIndex? ​

number = 0

The new read index (default: 0, pass -1 to keep current).

Returns ​

void

setReadIndex() ​

setReadIndex(index): void

Defined in: BinaryStream.ts:1001

Sets the reading index.

Parameters ​

index ​

number

The new read index.

Returns ​

void

setWriteBuffer() ​

setWriteBuffer(buf, wIndex?): void

Defined in: BinaryStream.ts:965

Sets the buffer for writing.

Parameters ​

buf ​

Buffer

The new Buffer.

wIndex? ​

number = 0

The new write index (default: 0, pass -1 to keep current).

Returns ​

void

setWriteIndex() ​

setWriteIndex(index): void

Defined in: BinaryStream.ts:1010

Sets the new writing index.

Parameters ​

index ​

number

The new write index.

Returns ​

void

skip() ​

skip(len): void

Defined in: BinaryStream.ts:899

Skips len bytes on the buffer.

Parameters ​

len ​

number

Returns ​

void

write() ​

write(buf): void

Defined in: BinaryStream.ts:76

Appends a buffer to the main buffer.

Parameters ​

buf ​

Uint8Array

Returns ​

void

writeBoolean() ​

writeBoolean(v): void

Defined in: BinaryStream.ts:188

Writes a boolean (true or false).

Parameters ​

v ​

boolean

Returns ​

void

writeByte() ​

writeByte(v): void

Defined in: BinaryStream.ts:152

Writes an unsigned byte (0 to 255).

Parameters ​

v ​

number

Returns ​

void

writeDouble() ​

writeDouble(v): void

Defined in: BinaryStream.ts:490

Writes a 64 bit (8 bytes) big-endian floating point number.

Parameters ​

v ​

number

Returns ​

void

writeDoubleLE() ​

writeDoubleLE(v): void

Defined in: BinaryStream.ts:510

Writes a 64 bit (8 bytes) little-endian floating point number.

Parameters ​

v ​

number

Returns ​

void

writeFloat() ​

writeFloat(v): void

Defined in: BinaryStream.ts:450

Writes a 32 bit (4 bytes) big-endian floating point number.

Parameters ​

v ​

number

Returns ​

void

writeFloatLE() ​

writeFloatLE(v): void

Defined in: BinaryStream.ts:470

Writes a 32 bit (4 bytes) little-endian floating point number.

Parameters ​

v ​

number

Returns ​

void

writeInt() ​

writeInt(v): void

Defined in: BinaryStream.ts:370

Writes a 32 bit (4 bytes) big-endian signed number.

Parameters ​

v ​

number

Returns ​

void

writeIntLE() ​

writeIntLE(v): void

Defined in: BinaryStream.ts:390

Writes a 32 bit (4 bytes) little-endian signed number.

Parameters ​

v ​

number

Returns ​

void

writeLengthPrefixed() ​

writeLengthPrefixed(buf): void

Defined in: BinaryStream.ts:115

Writes a varuint32 byte length, then the bytes.

Parameters ​

buf ​

Uint8Array

The bytes to append.

Returns ​

void

writeLong() ​

writeLong(v): void

Defined in: BinaryStream.ts:530

Writes a 64 bit (8 bytes) signed big-endian number.

Parameters ​

v ​

bigint

Returns ​

void

writeLongLE() ​

writeLongLE(v): void

Defined in: BinaryStream.ts:549

Writes a 64 bit (8 bytes) signed little-endian number.

Parameters ​

v ​

bigint

Returns ​

void

writeShort() ​

writeShort(v): void

Defined in: BinaryStream.ts:206

Writes a 16 bit (2 bytes) signed big-endian number.

Parameters ​

v ​

number

Returns ​

void

writeShortLE() ​

writeShortLE(v): void

Defined in: BinaryStream.ts:226

Writes a 16 bit (2 bytes) signed little-endian number.

Parameters ​

v ​

number

Returns ​

void

writeSignedByte() ​

writeSignedByte(v): void

Defined in: BinaryStream.ts:170

Writes a signed byte (-128 to 127).

Parameters ​

v ​

number

Returns ​

void

writeTriad() ​

writeTriad(v): void

Defined in: BinaryStream.ts:286

Writes a 24 bit (3 bytes) signed big-endian number.

Parameters ​

v ​

number

Returns ​

void

writeTriadLE() ​

writeTriadLE(v): void

Defined in: BinaryStream.ts:307

Writes a 24 bit (3 bytes) signed little-endian number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedInt() ​

writeUnsignedInt(v): void

Defined in: BinaryStream.ts:410

Writes a 32 bit (4 bytes) big-endian unsigned number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedIntLE() ​

writeUnsignedIntLE(v): void

Defined in: BinaryStream.ts:430

Writes a 32 bit (4 bytes) little-endian unsigned number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedLong() ​

writeUnsignedLong(v): void

Defined in: BinaryStream.ts:568

Writes a 64 bit (8 bytes) unsigned big-endian number.

Parameters ​

v ​

bigint

Returns ​

void

writeUnsignedLongLE() ​

writeUnsignedLongLE(v): void

Defined in: BinaryStream.ts:587

Writes a 64 bit (8 bytes) unsigned little-endian number.

Parameters ​

v ​

bigint

Returns ​

void

writeUnsignedShort() ​

writeUnsignedShort(v): void

Defined in: BinaryStream.ts:246

Writes a 16 bit (2 bytes) unsigned big-endian number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedShortLE() ​

writeUnsignedShortLE(v): void

Defined in: BinaryStream.ts:266

Writes a 16 bit (2 bytes) unsigned little-endian number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedTriad() ​

writeUnsignedTriad(v): void

Defined in: BinaryStream.ts:328

Writes a 24 bit (3 bytes) unsigned big-endian number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedTriadLE() ​

writeUnsignedTriadLE(v): void

Defined in: BinaryStream.ts:349

Writes a 24 bit (3 bytes) unsigned little-endian number.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedVarInt() ​

writeUnsignedVarInt(v): void

Defined in: BinaryStream.ts:657

Writes a 32 bit unsigned number with variable-length.

Parameters ​

v ​

number

Returns ​

void

writeUnsignedVarLong() ​

writeUnsignedVarLong(v): void

Defined in: BinaryStream.ts:742

Writes a 64 bit unsigned variable-length number.

Parameters ​

v ​

bigint

Returns ​

void

writeUTF8String() ​

writeUTF8String(value): void

Defined in: BinaryStream.ts:91

Writes a UTF-8 string directly into the stream's backing buffer.

Parameters ​

value ​

string

The string to encode.

Returns ​

void

writeVarInt() ​

writeVarInt(v): void

Defined in: BinaryStream.ts:609

Writes a 32 bit (4 bytes) zigzag-encoded number.

Parameters ​

v ​

number

Returns ​

void

writeVarLong() ​

writeVarLong(v): void

Defined in: BinaryStream.ts:688

Writes a 64 bit unsigned zigzag-encoded number.

Parameters ​

v ​

bigint

Returns ​

void

writeVarString() ​

writeVarString(str): void

Defined in: BinaryStream.ts:134

Writes a string as a varuint32 byte length, then UTF-8 bytes.

Parameters ​

str ​

string

The string to write.

Returns ​

void