smart-buffer
Advanced tools
smart-buffer is a Buffer wrapper that adds automatic read & write offset tracking, string operations, data insertions, and more.
The smart-buffer npm package is a Node.js Buffer management library that provides a more convenient way to work with Node.js Buffers. It allows for automatic Buffer resizing, chainable method calls, and simplified Buffer read/write operations.
Reading and Writing Data
This feature allows for reading and writing various types of data to and from a buffer. The example shows how to read an 8-bit integer from a SmartBuffer instance.
const SmartBuffer = require('smart-buffer').SmartBuffer;
const buff = SmartBuffer.fromBuffer(Buffer.from([0x01, 0x02, 0x03, 0x04]));
const val = buff.readInt8();Automatic Buffer Resizing
SmartBuffer automatically resizes the internal Buffer as needed when writing data. The example demonstrates writing a null-terminated string to a SmartBuffer instance without worrying about the Buffer size.
const SmartBuffer = require('smart-buffer').SmartBuffer;
const buff = new SmartBuffer();
buff.writeStringNT('Hello, World!');Chainable Method Calls
SmartBuffer methods can be chained together for more concise code. The example shows multiple write operations being chained together.
const SmartBuffer = require('smart-buffer').SmartBuffer;
const buff = new SmartBuffer();
buff.writeInt32LE(123).writeStringNT('Hello').writeFloatBE(1.23);The 'buffer' package provides a Buffer class that is used to represent a fixed-length sequence of bytes. It is similar to smart-buffer but does not offer automatic resizing or chainable methods.
The 'bl' (Buffer List) package is a storage object for collections of Node.js Buffers. It offers a similar feature set to smart-buffer but focuses more on managing a list of Buffers rather than providing an enhanced Buffer API.
smart-buffer is a Buffer wrapper that adds automatic read & write offset tracking, string operations, data insertions, and more.
Key Features:
Requirements:
Legacy documentation for version 3 and prior can be found here.
yarn add smart-buffer
or
npm install smart-buffer
Note: The published NPM package includes the built javascript library. If you cloned this repo and wish to build the library manually use:
npm run build
// Javascript
const SmartBuffer = require('smart-buffer').SmartBuffer;
// Typescript
import { SmartBuffer, SmartBufferOptions} from 'smart-buffer';
Building a packet that uses the following protocol specification:
[PacketType:2][PacketLength:2][Data:XX]
To build this packet using the vanilla Buffer class, you would have to count up the length of the data payload beforehand. You would also need to keep track of the current "cursor" position in your Buffer so you write everything in the right places. With smart-buffer you don't have to do either of those things.
function createLoginPacket(username, password, age, country) {
const packet = new SmartBuffer();
packet.writeUInt16LE(0x0060); // Some packet type
packet.writeStringNT(username);
packet.writeStringNT(password);
packet.writeUInt8(age);
packet.writeStringNT(country);
packet.insertUInt16LE(packet.length - 2, 2);
return packet.toBuffer();
}
With the above function, you now can do this:
const login = createLoginPacket("Josh", "secret123", 22, "United States");
// <Buffer 60 00 1e 00 4a 6f 73 68 00 73 65 63 72 65 74 31 32 33 00 16 55 6e 69 74 65 64 20 53 74 61 74 65 73 00>
Notice that the [PacketLength:2] value (1e 00) was inserted at position 2.
Reading back the packet we created above is just as easy:
const reader = SmartBuffer.fromBuffer(login);
const logininfo = {
packetType: reader.readUInt16LE(),
packetLength: reader.readUInt16LE(),
username: reader.readStringNT(),
password: reader.readStringNT(),
age: reader.readUInt8(),
country: reader.readStringNT()
};
/*
{
packetType: 96, (0x0060)
packetLength: 30,
username: 'Josh',
password: 'secret123',
age: 22,
country: 'United States'
}
*/
In prior versions of SmartBuffer, .writeXXX(value, offset) calls would insert data when an offset was provided. In version 4, this will now overwrite the data at the offset position. To insert data there are now corresponding .insertXXX(value, offset) methods.
SmartBuffer v3:
const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
buff.writeInt8(7, 2);
console.log(buff.toBuffer())
// <Buffer 01 02 07 03 04 05 06>
SmartBuffer v4:
const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
buff.writeInt8(7, 2);
console.log(buff.toBuffer());
// <Buffer 01 02 07 04 05 06>
To insert you instead should use:
const buff = SmartBuffer.fromBuffer(new Buffer([1,2,3,4,5,6]));
buff.insertInt8(7, 2);
console.log(buff.toBuffer());
// <Buffer 01 02 07 03 04 05 06>
Note: Insert/Writing to a position beyond the currently tracked internal Buffer will zero pad to your offset.
There are a few different ways to construct a SmartBuffer instance.
// Creating SmartBuffer from existing Buffer
const buff = SmartBuffer.fromBuffer(buffer); // Creates instance from buffer. (Uses default utf8 encoding)
const buff = SmartBuffer.fromBuffer(buffer, 'ascii'); // Creates instance from buffer with ascii encoding for strings.
// Creating SmartBuffer with specified internal Buffer size. (Note: this is not a hard cap, the internal buffer will grow as needed).
const buff = SmartBuffer.fromSize(1024); // Creates instance with internal Buffer size of 1024.
const buff = SmartBuffer.fromSize(1024, 'utf8'); // Creates instance with internal Buffer size of 1024, and utf8 encoding for strings.
// Creating SmartBuffer with options object. This one specifies size and encoding.
const buff = SmartBuffer.fromOptions({
size: 1024,
encoding: 'ascii'
});
// Creating SmartBuffer with options object. This one specified an existing Buffer.
const buff = SmartBuffer.fromOptions({
buff: buffer
});
// Creating SmartBuffer from a string.
const buff = SmartBuffer.fromBuffer(Buffer.from('some string', 'utf8'));
// Just want a regular SmartBuffer with all default options?
const buff = new SmartBuffer();
Note: SmartBuffer is fully documented with Typescript definitions as well as jsdocs so your favorite editor/IDE will have intellisense.
Table of Contents
options {SmartBufferOptions} An optional options object to construct a SmartBuffer with.Examples:
const buff = new SmartBuffer();
const buff = new SmartBuffer({
size: 1024,
encoding: 'ascii'
});
buffer {Buffer} The Buffer instance to wrap.encoding {string} The string encoding to use. Default: 'utf8'Examples:
const someBuffer = Buffer.from('some string');
const buff = SmartBuffer.fromBuffer(someBuffer); // Defaults to utf8
const buff = SmartBuffer.fromBuffer(someBuffer, 'ascii');
size {number} The size to initialize the internal Buffer.encoding {string} The string encoding to use. Default: 'utf8'Examples:
const buff = SmartBuffer.fromSize(1024); // Defaults to utf8
const buff = SmartBuffer.fromSize(1024, 'ascii');
options {SmartBufferOptions} The Buffer instance to wrap.interface SmartBufferOptions {
encoding?: BufferEncoding; // Defaults to utf8
size?: number; // Defaults to 4096
buff?: Buffer;
}
Examples:
const buff = SmartBuffer.fromOptions({
size: 1024
};
const buff = SmartBuffer.fromOptions({
size: 1024,
encoding: 'utf8'
});
const buff = SmartBuffer.fromOptions({
encoding: 'utf8'
});
const someBuff = Buffer.from('some string', 'utf8');
const buff = SmartBuffer.fromOptions({
buffer: someBuff,
encoding: 'utf8'
});
offset {number} Optional position to start reading data from. Default: Auto managed offsetRead a Int8 value.
offset {number} Optional position to start reading data from. Default: Auto managed offsetRead a 16 bit integer value.
offset {number} Optional position to start reading data from. Default: Auto managed offsetRead a 32 bit integer value.
value {number} The value to write.offset {number} An optional offset to write this value to. Default: Auto managed offsetWrite a Int8 value.
value {number} The value to insert.offset {number} The offset to insert this data at.Insert a Int8 value.
value {number} The value to write.offset {number} An optional offset to write this value to. Default: Auto managed offsetWrite a 16 bit integer value.
value {number} The value to insert.offset {number} The offset to insert this data at.Insert a 16 bit integer value.
value {number} The value to write.offset {number} An optional offset to write this value to. Default: Auto managed offsetWrite a 32 bit integer value.
value {number} The value to insert.offset {number} The offset to insert this data at.Insert a 32 bit integer value.
offset {number} Optional position to start reading data from. Default: Auto managed offsetRead a Float value.
offset {number} Optional position to start reading data from. Default: Auto managed offsetRead a Double value.
value {number} The value to write.offset {number} An optional offset to write this value to. Default: Auto managed offsetWrite a Float value.
value {number} The value to insert.offset {number} The offset to insert this data at.Insert a Float value.
value {number} The value to write.offset {number} An optional offset to write this value to. Default: Auto managed offsetWrite a Double value.
value {number} The value to insert.offset {number} The offset to insert this data at.Insert a Double value.
size {number} The number of bytes to read. Default: Reads to the end of the Buffer.encoding {string} The string encoding to use. Default: utf8.Read a string value.
Examples:
const buff = SmartBuffer.fromBuffer(Buffer.from('hello there', 'utf8'));
buff.readString(); // 'hello there'
buff.readString(2); // 'he'
buff.readString(2, 'utf8'); // 'he'
buff.readString('utf8'); // 'hello there'
value {string} The string value to write.offset {number} The offset to write this value to. Default: Auto managed offsetencoding {string} An optional string encoding to use. Default: utf8Write a string value.
Examples:
buff.writeString('hello'); // Auto managed offset
buff.writeString('hello', 2);
buff.writeString('hello', 'utf8') // Auto managed offset
buff.writeString('hello', 2, 'utf8');
value {string} The string value to write.offset {number} The offset to write this value to.encoding {string} An optional string encoding to use. Default: utf8Insert a string value.
Examples:
buff.insertString('hello', 2);
buff.insertString('hello', 2, 'utf8');
encoding {string} The string encoding to use. Default: utf8.Read a null terminated string value. (If a null is not found, it will read to the end of the Buffer).
Examples:
const buff = SmartBuffer.fromBuffer(Buffer.from('hello\0 there', 'utf8'));
buff.readStringNT(); // 'hello'
// If we called this again:
buff.readStringNT(); // ' there'
value {string} The string value to write.offset {number} The offset to write this value to. Default: Auto managed offsetencoding {string} An optional string encoding to use. Default: utf8Write a null terminated string value.
Examples:
buff.writeStringNT('hello'); // Auto managed offset <Buffer 68 65 6c 6c 6f 00>
buff.writeStringNT('hello', 2); // <Buffer 00 00 68 65 6c 6c 6f 00>
buff.writeStringNT('hello', 'utf8') // Auto managed offset
buff.writeStringNT('hello', 2, 'utf8');
value {string} The string value to write.offset {number} The offset to write this value to.encoding {string} An optional string encoding to use. Default: utf8Insert a null terminated string value.
Examples:
buff.insertStringNT('hello', 2);
buff.insertStringNT('hello', 2, 'utf8');
length {number} The number of bytes to read into a Buffer. Default: Reads to the end of the BufferRead a Buffer of a specified size.
value {Buffer} The buffer value to write.offset {number} An optional offset to write the value to. Default: Auto managed offsetvalue {Buffer} The buffer value to write.offset {number} The offset to write the value to.Read a null terminated Buffer.
value {Buffer} The buffer value to write.offset {number} An optional offset to write the value to. Default: Auto managed offsetWrite a null terminated Buffer.
value {Buffer} The buffer value to write.offset {number} The offset to write the value to.Insert a null terminated Buffer.
offset {number} The new read offset value to set.The current read offsetGets or sets the current read offset.
Examples:
const currentOffset = buff.readOffset; // 5
buff.readOffset = 10;
console.log(buff.readOffset) // 10
offset {number} The new write offset value to set.The current write offsetGets or sets the current write offset.
Examples:
const currentOffset = buff.writeOffset; // 5
buff.writeOffset = 10;
console.log(buff.writeOffset) // 10
encoding {string} The new string encoding to set.The current string encodingGets or sets the current string encoding.
Examples:
const currentEncoding = buff.encoding; // 'utf8'
buff.encoding = 'ascii';
console.log(buff.encoding) // 'ascii'
Clear and resets the SmartBuffer instance.
Remaining data left to be readGets the number of remaining bytes to be read.
Gets the internally managed Buffer (Includes unmanaged data).
Examples:
const buff = SmartBuffer.fromSize(16);
buff.writeString('hello');
console.log(buff.InternalBuffer); // <Buffer 68 65 6c 6c 6f 00 00 00 00 00 00 00 00 00 00 00>
Gets a sliced Buffer instance of the internally managed Buffer. (Only includes managed data)
Examples:
const buff = SmartBuffer.fromSize(16);
buff.writeString('hello');
console.log(buff.toBuffer()); // <Buffer 68 65 6c 6c 6f>
encoding {string} The string encoding to use when converting to a string. Default: utf8Gets a string representation of all data in the SmartBuffer.
Destroys the SmartBuffer instance.
This work is licensed under the MIT license.
FAQs
smart-buffer is a Buffer wrapper that adds automatic read & write offset tracking, string operations, data insertions, and more.
The npm package smart-buffer receives a total of 15,429,940 weekly downloads. As such, smart-buffer popularity was classified as popular.
We found that smart-buffer demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.