BufferConstructor

Raw data is stored in instances of the Buffer class. A Buffer is similar to an array of integers but corresponds to a raw memory allocation outside the V8 heap. A Buffer cannot be resized. Valid string encodings: 'ascii'|'utf8'|'utf16le'|'ucs2'(alias of 'utf16le')|'base64'|'base64url'|'binary'(deprecated)|'hex'

Constructors

constructor

**new BufferConstructor**(str, encoding?)

Allocates a new buffer containing the given {str}.

Parameters

strstringRequired

String to store in buffer.

encodingBufferEncoding

encoding to use, optional. Default is 'utf8'

Deprecated

since v10.0.0 - Use Buffer.from(string[, encoding]) instead.

**new BufferConstructor**(size)

Allocates a new buffer of {size} octets.

Parameters

sizenumberRequired

count of octets to allocate.

Deprecated

since v10.0.0 - Use Buffer.alloc() instead (also see Buffer.allocUnsafe()).

**new BufferConstructor**(array)

Allocates a new buffer containing the given {array} of octets.

Parameters

arrayUint8ArrayRequired

The octets to store.

Deprecated

since v10.0.0 - Use Buffer.from(array) instead.

**new BufferConstructor**(arrayBuffer)

Produces a Buffer backed by the same allocated memory as the given {ArrayBuffer}/{SharedArrayBuffer}.

Parameters

arrayBufferArrayBuffer | SharedArrayBufferRequired

The ArrayBuffer with which to share memory.

Deprecated

since v10.0.0 - Use Buffer.from(arrayBuffer[, byteOffset[, length]]) instead.

**new BufferConstructor**(array)

Allocates a new buffer containing the given {array} of octets.

Parameters

arrayreadonly any[]Required

The octets to store.

Deprecated

since v10.0.0 - Use Buffer.from(array) instead.

**new BufferConstructor**(buffer)

Copies the passed {buffer} data onto a new {Buffer} instance.

Parameters

bufferBufferRequired

The buffer to copy.

Deprecated

since v10.0.0 - Use Buffer.from(buffer) instead.

Properties

poolSizenumberRequired

This is the size (in bytes) of pre-allocated internal Buffer instances used for pooling. This value may be modified.

Methods

alloc

**alloc**(size, fill?, encoding?): [Buffer](/references/services/#buffer)

Allocates a new Buffer of size bytes. If fill is undefined, theBuffer will be zero-filled.

import { Buffer } from 'node:buffer';

const buf = Buffer.alloc(5);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00>

If size is larger than constants.MAX_LENGTH or smaller than 0, ERR_OUT_OF_RANGE is thrown.

If fill is specified, the allocated Buffer will be initialized by calling buf.fill(fill).

import { Buffer } from 'node:buffer';

const buf = Buffer.alloc(5, 'a');

console.log(buf);
// Prints: <Buffer 61 61 61 61 61>

If both fill and encoding are specified, the allocated Buffer will be initialized by calling buf.fill(fill, encoding).

import { Buffer } from 'node:buffer';

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');

console.log(buf);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>

Calling Buffer.alloc() can be measurably slower than the alternative Buffer.allocUnsafe() but ensures that the newly created Buffer instance contents will never contain sensitive data from previous allocations, including data that might not have been allocated for Buffers.

A TypeError will be thrown if size is not a number.

Parameters

sizenumberRequired

The desired length of the new Buffer.

fillstring | number | Uint8Array

A value to pre-fill the new Buffer with.

encodingBufferEncoding

If fill is a string, this is its encoding.

Returns

Buffer

BufferBufferRequired

Since

v5.10.0

---

allocUnsafe

**allocUnsafe**(size): [Buffer](/references/services/#buffer)

Allocates a new Buffer of size bytes. If size is larger than constants.MAX_LENGTH or smaller than 0, ERR_OUT_OF_RANGE is thrown.

The underlying memory for Buffer instances created in this way is _not_ _initialized_. The contents of the newly created Buffer are unknown and _may contain sensitive data_. Use Buffer.alloc() instead to initializeBuffer instances with zeroes.

import { Buffer } from 'node:buffer';

const buf = Buffer.allocUnsafe(10);

console.log(buf);
// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>

buf.fill(0);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>

A TypeError will be thrown if size is not a number.

The Buffer module pre-allocates an internal Buffer instance of size Buffer.poolSize that is used as a pool for the fast allocation of newBuffer instances created using Buffer.allocUnsafe(), Buffer.from(array), and Buffer.concat() only when size is less than or equal toBuffer.poolSize >> 1 (floor of Buffer.poolSize divided by two).

Use of this pre-allocated internal memory pool is a key difference between calling Buffer.alloc(size, fill) vs. Buffer.allocUnsafe(size).fill(fill). Specifically, Buffer.alloc(size, fill) will _never_ use the internal Bufferpool, while Buffer.allocUnsafe(size).fill(fill)_will_ use the internalBuffer pool if size is less than or equal to half Buffer.poolSize. The difference is subtle but can be important when an application requires the additional performance that Buffer.allocUnsafe() provides.

Parameters

sizenumberRequired

The desired length of the new Buffer.

Returns

Buffer

BufferBufferRequired

Since

v5.10.0

---

allocUnsafeSlow

**allocUnsafeSlow**(size): [Buffer](/references/services/#buffer)

Allocates a new Buffer of size bytes. If size is larger than constants.MAX_LENGTH or smaller than 0, ERR_OUT_OF_RANGE is thrown. A zero-length Buffer is created if size is 0.

The underlying memory for Buffer instances created in this way is _not_ _initialized_. The contents of the newly created Buffer are unknown and _may contain sensitive data_. Use buf.fill(0) to initialize such Buffer instances with zeroes.

When using Buffer.allocUnsafe() to allocate new Buffer instances, allocations under 4 KiB are sliced from a single pre-allocated Buffer. This allows applications to avoid the garbage collection overhead of creating many individually allocated Buffer instances. This approach improves both performance and memory usage by eliminating the need to track and clean up as many individual ArrayBuffer objects.

However, in the case where a developer may need to retain a small chunk of memory from a pool for an indeterminate amount of time, it may be appropriate to create an un-pooled Buffer instance using Buffer.allocUnsafeSlow() and then copying out the relevant bits.

import { Buffer } from 'node:buffer';

// Need to keep around a few small chunks of memory.
const store = [];

socket.on('readable', () => {
  let data;
  while (null !== (data = readable.read())) {
    // Allocate for retained data.
    const sb = Buffer.allocUnsafeSlow(10);

    // Copy the data into the new allocation.
    data.copy(sb, 0, 0, 10);

    store.push(sb);
  }
});

A TypeError will be thrown if size is not a number.

Parameters

sizenumberRequired

The desired length of the new Buffer.

Returns

Buffer

BufferBufferRequired

Since

v5.12.0

---

byteLength

**byteLength**(string, encoding?): number

Returns the byte length of a string when encoded using encoding. This is not the same as String.prototype.length, which does not account for the encoding that is used to convert the string into bytes.

For 'base64', 'base64url', and 'hex', this function assumes valid input. For strings that contain non-base64/hex-encoded data (e.g. whitespace), the return value might be greater than the length of a Buffer created from the string.

import { Buffer } from 'node:buffer';

const str = '\u00bd + \u00bc = \u00be';

console.log(`${str}: ${str.length} characters, ` +
            `${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes

When string is a Buffer/DataView/[TypedArray](https://developer.mozilla.org/en-US/docs/Web/JavaScript/- Reference/Global_Objects/TypedArray)/ArrayBuffer/[SharedArrayBuffer](https://develop- er.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer), the byte length as reported by .byteLengthis returned.

Parameters

stringstring | ArrayBuffer | SharedArrayBuffer | ArrayBufferViewRequired

A value to calculate the length of.

encodingBufferEncoding

If string is a string, this is its encoding.

Returns

number

numbernumber

The number of bytes contained within string.

Since

v0.1.90

---

compare

**compare**(buf1, buf2): 0 \| 1 \| -1

Compares buf1 to buf2, typically for the purpose of sorting arrays ofBuffer instances. This is equivalent to calling buf1.compare(buf2).

import { Buffer } from 'node:buffer';

const buf1 = Buffer.from('1234');
const buf2 = Buffer.from('0123');
const arr = [buf1, buf2];

console.log(arr.sort(Buffer.compare));
// Prints: [ <Buffer 30 31 32 33>, <Buffer 31 32 33 34> ]
// (This result is equal to: [buf2, buf1].)

Parameters

buf1Uint8ArrayRequired

buf2Uint8ArrayRequired

Returns

0 | 1 | -1

0 \| 1 \| -10 | 1 | -1

Either -1, 0, or 1, depending on the result of the comparison. See compare for details.

Since

v0.11.13

---

concat

**concat**(list, totalLength?): [Buffer](/references/services/#buffer)

Returns a new Buffer which is the result of concatenating all the Bufferinstances in the list together.

If the list has no items, or if the totalLength is 0, then a new zero-lengthBuffer is returned.

If totalLength is not provided, it is calculated from the Buffer instances in list by adding their lengths.

If totalLength is provided, it is coerced to an unsigned integer. If the combined length of the Buffers in list exceeds totalLength, the result is truncated to totalLength.

import { Buffer } from 'node:buffer';

// Create a single `Buffer` from a list of three `Buffer` instances.

const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;

console.log(totalLength);
// Prints: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);

console.log(bufA);
// Prints: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// Prints: 42

Buffer.concat() may also use the internal Buffer pool like Buffer.allocUnsafe() does.

Parameters

listreadonly Uint8Array[]Required

List of Buffer or Uint8Array instances to concatenate.

totalLengthnumber

Total length of the Buffer instances in list when concatenated.

Returns

Buffer

BufferBufferRequired

Since

v0.7.11

---

copyBytesFrom

**copyBytesFrom**(view, offset?, length?): [Buffer](/references/services/#buffer)

Copies the underlying memory of view into a new Buffer.

const u16 = new Uint16Array([0, 0xffff]);
const buf = Buffer.copyBytesFrom(u16, 1, 1);
u16[1] = 0;
console.log(buf.length); // 2
console.log(buf[0]); // 255
console.log(buf[1]); // 255

Parameters

viewTypedArrayRequired

The {TypedArray} to copy.

offsetnumber

The starting offset within view.

lengthnumber

The number of elements from view to copy.

Returns

Buffer

BufferBufferRequired

Since

v19.8.0

---

from

**from**(arrayBuffer, byteOffset?, length?): [Buffer](/references/services/#buffer)

Allocates a new Buffer using an array of bytes in the range 0 – 255. Array entries outside that range will be truncated to fit into it.

import { Buffer } from 'node:buffer';

// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'.
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);

If array is an Array-like object (that is, one with a length property of type number), it is treated as if it is an array, unless it is a Buffer or a Uint8Array. This means all other TypedArray variants get treated as anArray. To create a Buffer from the bytes backing a TypedArray, use Buffer.copyBytesFrom().

A TypeError will be thrown if array is not an Array or another type appropriate for Buffer.from() variants.

Buffer.from(array) and Buffer.from(string) may also use the internalBuffer pool like Buffer.allocUnsafe() does.

Parameters

arrayBufferWithImplicitCoercion<ArrayBuffer | SharedArrayBuffer>Required

byteOffsetnumber

lengthnumber

Returns

Buffer

BufferBufferRequired

Since

v5.10.0

**from**(data): [Buffer](/references/services/#buffer)

Creates a new Buffer using the passed {data}

Parameters

dataUint8Array | readonly number[]Required

data to create a new Buffer

Returns

Buffer

BufferBufferRequired

**from**(data): [Buffer](/references/services/#buffer)

Parameters

dataWithImplicitCoercion<string | Uint8Array | readonly number[]>Required

Returns

Buffer

BufferBufferRequired

**from**(str, encoding?): [Buffer](/references/services/#buffer)

Creates a new Buffer containing the given JavaScript string {str}. If provided, the {encoding} parameter identifies the character encoding. If not provided, {encoding} defaults to 'utf8'.

Parameters

strWithImplicitCoercion<string> | { [toPrimitive]: Method [toPrimitive] }Required

encodingBufferEncoding

Returns

Buffer

BufferBufferRequired

---

isBuffer

**isBuffer**(obj): obj is Buffer

Returns true if obj is a Buffer, false otherwise.

import { Buffer } from 'node:buffer';

Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false

Parameters

objanyRequired

Returns

obj is Buffer

objobj is Buffer

Since

v0.1.101

---

isEncoding

**isEncoding**(encoding): encoding is BufferEncoding

Returns true if encoding is the name of a supported character encoding, or false otherwise.

import { Buffer } from 'node:buffer';

console.log(Buffer.isEncoding('utf8'));
// Prints: true

console.log(Buffer.isEncoding('hex'));
// Prints: true

console.log(Buffer.isEncoding('utf/8'));
// Prints: false

console.log(Buffer.isEncoding(''));
// Prints: false

Parameters

encodingstringRequired

A character encoding name to check.

Returns

encoding is BufferEncoding

encodingencoding is BufferEncoding

Since

v0.9.1

---

of

**of**(...items): [Buffer](/references/services/#buffer)

Creates a new Buffer using the passed {data}

Parameters

itemsnumber[]Required

Returns

Buffer

BufferBufferRequired