Allocates a new buffer containing the given {str}.
String to store in buffer.
Optional
encoding: BufferEncodingencoding to use, optional. Default is 'utf8'
Allocates a new buffer of {size} octets.
count of octets to allocate.
Allocates a new buffer containing the given {array} of octets.
The octets to store.
Produces a Buffer backed by the same allocated memory as the given {ArrayBuffer}/{SharedArrayBuffer}.
The ArrayBuffer with which to share memory.
Allocates a new buffer containing the given {array} of octets.
The octets to store.
Copies the passed {buffer} data onto a new {Buffer} instance.
The buffer to copy.
This is the size (in bytes) of pre-allocated internal Buffer
instances used
for pooling. This value may be modified.
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 Buffer
s.
A TypeError
will be thrown if size
is not a number.
The desired length of the new Buffer
.
Optional
fill: string | number | Uint8ArrayA value to pre-fill the new Buffer
with.
Optional
encoding: BufferEncodingIf fill
is a string, this is its encoding.
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 new Buffer
instances created using Buffer.allocUnsafe()
, Buffer.from(array)
,
and Buffer.concat()
only when size
is less than Buffer.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 Buffer
pool, 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.
The desired length of the new 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.
The desired length of the new Buffer
.
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 .byteLength
is returned.
A value to calculate the length of.
Optional
encoding: BufferEncodingIf string
is a string, this is its encoding.
The number of bytes contained within string
.
Compares buf1
to buf2
, typically for the purpose of sorting arrays of Buffer
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].)
Either -1
, 0
, or 1
, depending on the result of the comparison. See compare
for details.
Returns a new Buffer
which is the result of concatenating all the Buffer
instances in the list
together.
If the list has no items, or if the totalLength
is 0, then a new zero-length Buffer
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 Buffer
s 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.
List of Buffer
or Uint8Array instances to concatenate.
Optional
totalLength: numberTotal length of the Buffer
instances in list
when concatenated.
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
The {TypedArray} to copy.
Optional
offset: numberThe starting offset within view
.
Optional
length: numberThe number of elements from view
to copy.
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 an Array
. 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 internal Buffer
pool like Buffer.allocUnsafe()
does.
Optional
byteOffset: numberOptional
length: numberCreates a new Buffer using the passed {data}
data to create a new 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'.
Optional
encoding: BufferEncodingReturns 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
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
A character encoding name to check.
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'