CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-bl

Buffer List collector with standard readable Buffer interface and streaming capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

buffer-list.mddocs/

Buffer Collection

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.

Capabilities

Constructor

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');

Type Detection

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;

Length Property

Gets the total length of all buffers in the collection.

/**
 * Total length of all buffers in bytes
 */
length: number;

Append Operations

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"

Data Access

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"

Buffer Operations

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)

String Conversion

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;

Search Operations

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)

Buffer Access

Access to internal buffer structure.

/**
 * Returns the internal array of Buffer objects
 * @returns Array of Buffer objects in the list
 */
getBuffers(): Buffer[];

Binary Data Reading

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)

Types

type BufferListAcceptedTypes = 
  | Buffer 
  | BufferList 
  | Uint8Array 
  | BufferListAcceptedTypes[] 
  | string 
  | number;

type BufferEncoding = 
  | 'ascii' 
  | 'utf8' 
  | 'utf-8' 
  | 'utf16le' 
  | 'ucs2' 
  | 'ucs-2' 
  | 'base64' 
  | 'base64url' 
  | 'latin1' 
  | 'binary' 
  | 'hex';

docs

buffer-list-stream.md

buffer-list.md

index.md

tile.json