BufferList provides core buffer collection functionality for managing multiple Buffer objects as a unified collection. It offers efficient memory usage by avoiding unnecessary copying and provides a standard Buffer-like API for accessing data across buffer boundaries.
Creates a new BufferList instance with optional initial data.
/**
* Creates a BufferList instance for collecting buffers
* @param initData - Optional initial buffer data
*/
class BufferList {
constructor(initData?: BufferListAcceptedTypes);
}
// Factory function (new not required)
function BufferList(initData?: BufferListAcceptedTypes): BufferList;Usage Examples:
const { BufferList } = require('bl');
// Empty list
const bl1 = new BufferList();
const bl2 = BufferList(); // equivalent
// With initial data
const bl3 = new BufferList(Buffer.from('hello'));
const bl4 = new BufferList(['hello', ' world']);
const bl5 = new BufferList('initial string');Static method to determine if an object is a BufferList instance.
/**
* Determines if the passed object is a BufferList instance
* @param obj - Object to test
* @returns true if obj is BufferList or BufferListStream instance
*/
static BufferList.isBufferList(obj: unknown): boolean;Gets the total length of all buffers in the collection.
/**
* Total length of all buffers in bytes
*/
length: number;Adds data to the end or beginning of the buffer collection.
/**
* Adds buffer data to the end of the list
* @param buffer - Data to append
* @returns this for method chaining
*/
append(buffer: BufferListAcceptedTypes): this;
/**
* Adds buffer data to the beginning of the list
* @param buffer - Data to prepend
* @returns this for method chaining
*/
prepend(buffer: BufferListAcceptedTypes): this;Usage Examples:
const bl = new BufferList();
bl.append(Buffer.from('hello'))
.append(' ')
.append('world')
.prepend('>> ');
console.log(bl.toString()); // ">> hello world"Methods for accessing individual bytes and ranges of data.
/**
* Returns the byte value at the specified index
* @param index - Zero-based byte index
* @returns Byte value (0-255) or undefined if out of bounds
*/
get(index: number): number | undefined;
/**
* Returns a new Buffer containing bytes in the specified range
* @param start - Start index (inclusive), defaults to 0
* @param end - End index (exclusive), defaults to length
* @returns New Buffer with copied data
*/
slice(start?: number, end?: number): Buffer;
/**
* Returns a new BufferList containing bytes in the specified range
* @param start - Start index (inclusive), defaults to 0
* @param end - End index (exclusive), defaults to length
* @returns New BufferList sharing memory with original
*/
shallowSlice(start?: number, end?: number): BufferList;Usage Examples:
const bl = new BufferList('hello world');
console.log(bl.get(0)); // 104 (character code for 'h')
console.log(bl.get(6)); // 119 (character code for 'w')
console.log(bl.slice(0, 5).toString()); // "hello"
console.log(bl.slice(-5).toString()); // "world"
const shallow = bl.shallowSlice(6);
console.log(shallow.toString()); // "world"Operations for copying and manipulating buffer data.
/**
* Copies bytes from the list to a destination buffer
* @param dest - Destination Buffer to copy into
* @param destStart - Start position in destination buffer, defaults to 0
* @param srcStart - Start position in source list, defaults to 0
* @param srcEnd - End position in source list, defaults to length
* @returns The destination buffer
*/
copy(dest: Buffer, destStart?: number, srcStart?: number, srcEnd?: number): Buffer;
/**
* Creates a shallow copy of the BufferList
* @returns New BufferList sharing memory with original buffers
*/
duplicate(): BufferList;
/**
* Removes bytes from the start of the list
* @param bytes - Number of bytes to remove from start
* @returns this for method chaining
*/
consume(bytes?: number): this;Usage Examples:
const bl = new BufferList('hello world');
// Copy to existing buffer
const dest = Buffer.alloc(5);
bl.copy(dest, 0, 0, 5);
console.log(dest.toString()); // "hello"
// Duplicate for independent operations
const copy = bl.duplicate();
copy.consume(6); // Remove "hello "
console.log(copy.toString()); // "world"
console.log(bl.toString()); // "hello world" (original unchanged)Converts buffer data to string representations.
/**
* Converts the buffer list to a string
* @param encoding - Character encoding, defaults to 'utf8'
* @param start - Start index for conversion, defaults to 0
* @param end - End index for conversion, defaults to length
* @returns String representation of the data
*/
toString(encoding?: BufferEncoding, start?: number, end?: number): string;Methods for finding data within the buffer collection.
/**
* Finds the first occurrence of a value in the buffer list
* @param value - Value to search for
* @param byteOffset - Starting search position, defaults to 0
* @param encoding - Character encoding for string values
* @returns Index of first occurrence, or -1 if not found
*/
indexOf(
value: string | number | Uint8Array | BufferList | Buffer,
byteOffset?: number,
encoding?: BufferEncoding
): number;Usage Examples:
const bl = new BufferList('hello world hello');
console.log(bl.indexOf('world')); // 6
console.log(bl.indexOf('hello', 1)); // 12 (second occurrence)
console.log(bl.indexOf('goodbye')); // -1 (not found)Access to internal buffer structure.
/**
* Returns the internal array of Buffer objects
* @returns Array of Buffer objects in the list
*/
getBuffers(): Buffer[];Complete set of Buffer-compatible methods for reading binary data across buffer boundaries.
// 64-bit floating point
readDoubleBE(offset?: number): number;
readDoubleLE(offset?: number): number;
// 32-bit floating point
readFloatBE(offset?: number): number;
readFloatLE(offset?: number): number;
// 64-bit integers
readBigInt64BE(offset?: number): bigint;
readBigInt64LE(offset?: number): bigint;
readBigUInt64BE(offset?: number): bigint;
readBigUInt64LE(offset?: number): bigint;
// 32-bit integers
readInt32BE(offset?: number): number;
readInt32LE(offset?: number): number;
readUInt32BE(offset?: number): number;
readUInt32LE(offset?: number): number;
// 16-bit integers
readInt16BE(offset?: number): number;
readInt16LE(offset?: number): number;
readUInt16BE(offset?: number): number;
readUInt16LE(offset?: number): number;
// 8-bit integers
readInt8(offset?: number): number;
readUInt8(offset?: number): number;
// Variable-length integers
readIntBE(offset: number, byteLength: number): number;
readIntLE(offset: number, byteLength: number): number;
readUIntBE(offset: number, byteLength: number): number;
readUIntLE(offset: number, byteLength: number): number;Usage Examples:
const bl = new BufferList();
bl.append(Buffer.from([0x12, 0x34, 0x56, 0x78]));
console.log(bl.readUInt32BE(0)); // 305419896 (0x12345678)
console.log(bl.readUInt32LE(0)); // 2018915346 (0x78563412)
console.log(bl.readUInt16BE(0)); // 4660 (0x1234)
console.log(bl.readUInt8(0)); // 18 (0x12)type BufferListAcceptedTypes =
| Buffer
| BufferList
| Uint8Array
| BufferListAcceptedTypes[]
| string
| number;
type BufferEncoding =
| 'ascii'
| 'utf8'
| 'utf-8'
| 'utf16le'
| 'ucs2'
| 'ucs-2'
| 'base64'
| 'base64url'
| 'latin1'
| 'binary'
| 'hex';