buffer-writer

What is buffer-writer?

The buffer-writer package is a Node.js module that provides a way to write values to a Buffer with automatic buffer management. It allows for writing various types of data, such as integers, strings, and floating-point numbers, in a binary format to a buffer. This can be particularly useful when dealing with binary protocols or when you need to serialize data for storage or network transmission.

What are buffer-writer's main functionalities?

Writing integers

This feature allows writing 8-bit, 16-bit, and 32-bit integers to a buffer. The 'BE' and 'LE' suffixes indicate whether the integer should be written in big-endian or little-endian format.

const BufferWriter = require('buffer-writer');
const writer = new BufferWriter();
writer.writeInt8(0x68);
writer.writeInt16BE(0x1234);
writer.writeInt32LE(0x12345678);
const buffer = writer.getBuffer();

Writing floating-point numbers

This feature allows writing 32-bit and 64-bit floating-point numbers to a buffer. Similar to integers, the 'BE' and 'LE' suffixes indicate the endianness.

const BufferWriter = require('buffer-writer');
const writer = new BufferWriter();
writer.writeFloatBE(3.14);
writer.writeDoubleLE(3.141592653589793);
const buffer = writer.getBuffer();

Writing strings

This feature allows writing strings to a buffer. It supports writing standard strings and null-terminated strings, which are commonly used in C-style string handling.

const BufferWriter = require('buffer-writer');
const writer = new BufferWriter();
writer.writeString('Hello, World!');
writer.writeStringZero('Null-terminated string.');
const buffer = writer.getBuffer();

Buffer management

This feature allows for managing the buffer by moving the write position. In this example, the 'rewind' method is used to move the write position back, allowing overwriting of previously written data.

const BufferWriter = require('buffer-writer');
const writer = new BufferWriter();
writer.writeUInt8(0xff);
writer.rewind(1);
writer.writeUInt8(0x7f);
const buffer = writer.getBuffer();

Other packages similar to buffer-writer

smart-buffer

Smart-buffer is an npm package that provides similar functionality to buffer-writer. It allows for reading and writing to Buffers in Node.js with automatic resizing. It has a more fluent API and additional features like inserting data at arbitrary positions and supports chaining of method calls.

buffer-builder

Buffer-builder is another npm package that offers functionality to write various types of data to a buffer. It is similar to buffer-writer but has a different API design and may have different performance characteristics.

bl

The 'bl' (Buffer List) package is a Node.js module that provides a storage mechanism for collections of Node Buffers. While it is not a direct alternative to buffer-writer, it can be used in conjunction with it to manage a list of buffers efficiently.

README

buffer-writer

Fast & efficient buffer writer used to keep memory usage low by internally recycling a single large buffer.

Used as the binary protocol writer in node-postgres

Since postgres requires big endian encoding, this only writes big endian numbers for now, but can & probably will easily be extended to write little endian as well.

I'll admit this has a few postgres specific things I might need to take out in the future, such as addHeader

api

var writer = new (require('buffer-writer')());

writer.addInt32(num)

Writes a 4-byte big endian binary encoded number to the end of the buffer.

writer.addInt16(num)

Writes a 2-byte big endian binary encoded number to the end of the buffer.

writer.addCString(string)

Writes a string to the buffer utf8 encoded and adds a null character (\0) at the end.

var buffer = writer.addHeader(char)

Writes the 5 byte PostgreSQL required header to the beginning of the buffer. (1 byte for character, 1 BE Int32 for length of the buffer)

var buffer = writer.join()

Collects all data in the writer and joins it into a single, new buffer.

var buffer = writer.flush(char)

Writes the 5 byte postgres required message header, collects all data in the writer and joins it into a single, new buffer, and then resets the writer.

thoughts

This is kind of node-postgres specific. If you're interested in using this for a more general purpose thing, lemme know. I would love to work with you on getting this more reusable for your needs.

license

MIT