Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

streambuf

Wiiseguy2.5kMIT2.0.0TypeScript support: included

Streamed Buffers - .NET's BinaryReader facsimile

stream, streams, streamed, streambuf, streambuffer, buffer, buffers, buffered, system.io, BinaryWriter, BinaryReader, binary, reader, writer, fstream, ifstream, ofstream, iostream, seek, tell

readme

streambuf - Stream Buffers Node.js CI codecov npm

Stream Buffers - .NET's BinaryReader facsimile for Node.js

This library wraps most of Buffer's methods. The difference with Buffer is that with streambuf you don't have to specify an offset each read/write operation, it uses an internal cursor.

streambuf offers a low-level API that similar to C++'s fstream/iostream/etc. or .NET's BinaryReader/BinaryWriter.

If you're looking for a library that is more high-level and built on top of streambuf, check out node-structor.

Install

$ npm install streambuf

Usage

const fs = require('fs');
const { StreamBuffer } = require('streambuf');

let buffer = StreamBuffer.from(fs.readFileSync('hiscore.dat'));

let nameLength = buffer.readUInt32LE();
let name = buffer.readString(nameLength);

buffer.skip(-nameLength); // go back to the beginning of the name
buffer.writeString(name.toUpperCase()); // overwrite the name in the buffer with something else

Refer to Buffer for a list of available read and write methods supported by StreamBuffer (omit the offset param).

API

StreamBuffer(Buffer)

Constructor: initialize with a Buffer object.

StreamBuffer(StreamBuffer)

Constructor: initialize with another StreamBuffer object's underlying Buffer.

StreamBuffer numeric methods

readInt8, readInt16LE, readInt16BE, readInt32LE, readInt32BE, readIntLE, readIntBE, readUInt8, readUInt16LE, readUInt16BE, readUInt32LE, readUInt32BE, readUIntLE, readUIntBE, readFloatLE, readFloatBE, readDoubleLE, readDoubleBE writeInt8, writeInt16LE, writeInt16BE, writeInt32LE, writeInt32BE, writeIntLE, writeIntBE, writeUInt8, writeUInt16LE, writeUInt16BE, writeUInt32LE, writeUInt32BE, writeFloatLE, writeFloatBE, writeDoubleLE, writeDoubleBE

StreamBuffer BigInt methods

readBigInt64LE, readBigInt64BE, readBigUInt64LE, readBigUInt64BE, writeBigInt64LE, writeBigInt64BE, writeBigUInt64LE, writeBigUInt64BE

.buffer

Provides raw access to the underlying Buffer object (read-only)

.read(numBytes)

Returns a new StreamBuffer that references the same Buffer as the original, but cropped by offset and offset + numBytes.

.write(buffer: Buffer)

Writes the contents of another Buffer.

.readByte()

Alias for .readUInt8()

.readSByte()

Alias for .readInt8()

.writeByte()

Alias for .writeUInt8()

.writeSByte()

Alias for .writeInt8()

.read7BitInt()

Reads a 7 bit encoded integer, like those used by .NET

.write7BitInt()

Writes a 7 bit encoded integer, like those used by .NET

.readChar([encoding])

Reads a single character from the buffer according to the specified character encoding. Multi-byte characters are not read - use readString for that instead. 'encoding' defaults to utf8.

.writeChar([encoding])

Writes a single character to the buffer according to the specified character encoding. Multi-byte characters are not written - use writeString for that instead. 'encoding' defaults to utf8.

.readString([length, [encoding]])

Decodes to a string according to the specified character encoding in encoding and length. 'encoding' defaults to utf8. 'length' is optional. If left undefined, it will use the first occurrence of a zero (0) byte as the end of the string.

.writeString(str, [encoding])

Writes a string to the underlying buffer with the specified encoding. 'encoding' defaults to utf8.

.peekString([length, [encoding]])

Functions the same way as .readString(), but does not update the offset.

.readString0([encoding])

Reads a string from the buffer according to the specified character encoding, stopping at the first zero (0) byte. Similar to calling .readString() without a length parameter, but more implicit. 'encoding' defaults to utf8.

.writeString0(str, [encoding])

Writes a string to the underlying buffer with the specified encoding, followed by a zero (0) byte. 'encoding' defaults to utf8.

.readString7([encoding])

A specialized version of readString(), it first reads a 7 bit encoded integer and uses that as the length of the to be read string. Can be used to read strings written by .NET's BinaryWriter.

.writeString7([encoding])

A specialized version of writeString(), it first writes a 7 bit encoded integer representing the length of the string, followed by the string.

.skip(numBytes)

Skips the specified number of bytes. A negative number can be used to rewind.

.setPos(pos) / .seek(pos)

Moves the offset to the specified pos.

.getPos() / .tell()

Returns the current offset.

.rewind()

Moves the offset back to 0.

.isEOF()

Returns true if the end of the buffer is reached. (offset >= buffer.length)

changelog

streambuf Changelog

[1.3.0] (29-jun-2024)

  • Added readString0 and writeString0 methods
  • Added readIntLE, readIntBE, readUIntLE, readUIntBE, writeIntLE, writeIntBE, writeUIntLE, writeUIntBE methods
  • Added length property to the StreamBuffer class
  • Added extra TS param typings
  • Added more tests
    • test for checking every numeric and write method is tested for length
    • test for checking if every Buffer read/write method is implemented in StreamBuffer
  • Added .prettierrc
  • Refactored deprecated Buffer method slice to subarray

[1.2.3] (20-aug-2022)

  • Code test coverage increased to 100%
  • Boundary checks for setPos/seek and skip

[1.2.0 - 1.2.2] (16-aug-2022)

  • TypeScript rewrite
  • Major performance improvements for numeric read and write methods
  • Added CHANGELOG

[1.1.4] (01-jan-2022)

  • Added BigInt support

[1.1.3] (31-dec-2021)

  • Removed Travis CI integration
  • Added GitHub Actions integration
  • Added readChar and writeChar
  • Added writeString7
  • Fix: prevent skip/seek/setPos from going out of bounds

[1.1.2] (19-feb-2021)

  • Minor changes to README and package.json keywords

[1.1.1] (18-feb-2021)

  • Minor changes to README

[1.1.0] (18-feb-2021)

  • Replaced ava with aqa because of the constant dependabot security issues with ava's numerous dependencies

[merge] (16-feb-2021)

  • dependabot ini bump due to security issue in ini (through ava)

[merge] (10-dec-2020)

  • dependabot ini bump due to security issue in lodash (through ava)

[1.0.13] (06-apr-2020)

  • Updated ava from 1.1.0 to 3.6.0 following npm audit issues
  • Added keywords to package.json

[1.0.12] (05-apr-2020)

  • Updated package-lock.json due to a security issue in lodash (through ava)

[1.0.11] (17-jul-2019)

  • Updated package-lock.json due to a security issue in lodash (through ava)

[1.0.10] (28-jun-2019)

  • Updated package-lock.json due to a security issue in js-yaml (through ava)

[1.0.9] (25-jan-2019)

  • Updated ava from 0.24.0 to 1.1.0 following npm audit issues

[1.0.8] (30-dec-2017)

  • Added Travis CI integration and fancy build status badge

[1.0.7] (29-dec-2017)

  • Added 7-bit integer methods and tests
  • Added the API to the README

[1.0.6] (29-dec-2017)

  • Added xFloat and xDouble Buffer methods support

[1.0.5] (29-dec-2017)

  • Added write methods, so streambuf is no longer a read-only library

[1.0.4] (28-dec-2017)

  • Minor README change

[1.0.3] (28-dec-2017)

  • Added many tests
  • Rewrote integer methods
  • Added LICENSE

[1.0.2] (27-dec-2017)

  • Added usage and examples to README

[1.0.1] (27-dec-2017)

  • Added README

[1.0.0] (27-dec-2017)

  • Initial release
  • Created git repository
  • Published NPM package

[local] (06-jan-2015)

  • Very first version! Originally used StreamBuffer to read and walk through old game data files and extract images and sounds