Buffer
Buffer objects are used to represent a fixed-length sequence of bytes. Many Node.js APIs support Buffers.
The Buffer class is a subclass of JavaScript’s Uint8Array class and extends it with methods that cover additional use cases. Node.js APIs accept plain Uint8Arrays wherever Buffers are supported as well.
import { Buffer } from 'node:buffer';
// Creates a zero-filled Buffer of length 10.
const buf1 = Buffer.alloc(10);
// Creates a Buffer of length 10, filled with bytes which all have the value 1.
const buf2 = Buffer.alloc(10, 1);
// Creates an uninitialized buffer of length 10.
const buf3 = Buffer.allocUnsafe(10);
// Creates a Buffer containing the bytes [1, 2, 3].
const buf4 = Buffer.from([1, 2, 3]);
// Creates a Buffer containing the UTF-8-encoded bytes for the string 'tést'.
const buf6 = Buffer.from('tést');
// Creates a Buffer containing the Latin-1 bytes.
const buf7 = Buffer.from('tést', 'latin1');
Buffers and Character Encodings
When converting between Buffers and strings, a character encoding may be specified. If no character encoding is specified, UTF-8 will be used as the default.
const buf = Buffer.from('hello world', 'utf8');
console.log(buf.toString('hex'));
// Prints: 68656c6c6f20776f726c64
console.log(buf.toString('base64'));
// Prints: aGVsbG8gd29ybGQ=
console.log(Buffer.from('fhqwhgads', 'utf8'));
// Prints: <Buffer 66 68 71 77 68 67 61 64 73>
console.log(Buffer.from('fhqwhgads', 'utf16le'));
// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>
Supported Encodings
- ‘utf8’ (alias: ‘utf-8’): Multi-byte encoded Unicode characters. Default encoding.
- ‘utf16le’ (alias: ‘utf-16le’): Multi-byte encoded Unicode characters.
- ‘latin1’: Latin-1 (ISO-8859-1). Supports Unicode characters from U+0000 to U+00FF.
- ‘base64’: Base64 encoding.
- ‘base64url’: Base64url encoding.
- ‘hex’: Encode each byte as two hexadecimal characters.
- ‘ascii’: For 7-bit ASCII data only.
- ‘binary’: Alias for ‘latin1’.
Class: Buffer
The Buffer class is a global type for dealing with binary data directly.
Static Methods
Buffer.alloc(size[, fill[, encoding]])
The desired length of the new Buffer
fill
string | Buffer | Uint8Array | integer
default:"0"
A value to pre-fill the new Buffer with
If fill is a string, this is its encoding
Buffer of size bytes. If fill is undefined, the Buffer will be zero-filled.
const buf = Buffer.alloc(5);
console.log(buf);
// Prints: <Buffer 00 00 00 00 00>
const buf2 = Buffer.alloc(5, 'a');
console.log(buf2);
// Prints: <Buffer 61 61 61 61 61>
const buf3 = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');
console.log(buf3);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
Buffer.allocUnsafe(size)
The desired length of the new Buffer
Buffer of size bytes. 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.
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>
Use Buffer.alloc() instead to initialize Buffer instances with zeroes to avoid sensitive data leakage.
Buffer.from(array)
An array of bytes in the range 0-255
Buffer using an array of bytes. Array entries outside the range 0-255 will be truncated.
const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]);
console.log(buf.toString());
// Prints: buffer
Buffer.from(string[, encoding])
Creates a new Buffer containing string. The encoding parameter identifies the character encoding to be used when converting string into bytes.
const buf1 = Buffer.from('this is a tést');
const buf2 = Buffer.from('7468697320697320612074c3a97374', 'hex');
console.log(buf1.toString());
// Prints: this is a tést
console.log(buf2.toString());
// Prints: this is a tést
console.log(buf1.toString('latin1'));
// Prints: this is a tést
Buffer.from(buffer)
buffer
Buffer | Uint8Array
required
An existing Buffer or Uint8Array from which to copy data
buffer data onto a new Buffer instance.
const buf1 = Buffer.from('buffer');
const buf2 = Buffer.from(buf1);
buf1[0] = 0x61;
console.log(buf1.toString()); // Prints: auffer
console.log(buf2.toString()); // Prints: buffer
Buffer.from(arrayBuffer[, byteOffset[, length]])
arrayBuffer
ArrayBuffer | SharedArrayBuffer
required
An ArrayBuffer or SharedArrayBuffer
Index of first byte to expose
Number of bytes to expose. Default: arrayBuffer.byteLength - byteOffset
const arr = new Uint16Array(2);
arr[0] = 5000;
arr[1] = 4000;
// Shares memory with arr
const buf = Buffer.from(arr.buffer);
console.log(buf);
// Prints: <Buffer 88 13 a0 0f>
// Changing the original Uint16Array changes the Buffer also
arr[1] = 6000;
console.log(buf);
// Prints: <Buffer 88 13 70 17>
Buffer.byteLength(string[, encoding])
string
string | Buffer | TypedArray | DataView | ArrayBuffer | SharedArrayBuffer
required
A value to calculate the length of
If string is a string, this is its encoding
encoding.
const str = '½ + ¼ = ¾';
console.log(`${str}: ${str.length} characters, ${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes
Buffer.compare(buf1, buf2)
buf1
Buffer | Uint8Array
required
First buffer to compare
buf2
Buffer | Uint8Array
required
Second buffer to compare
buf1 to buf2, typically for the purpose of sorting arrays of Buffer instances. Returns either -1, 0, or 1.
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])
Buffer.concat(list[, totalLength])
list
Buffer[] | Uint8Array[]
required
List of Buffer or Uint8Array instances to concatenate
Total length of the Buffer instances in list when concatenated
Buffer which is the result of concatenating all the Buffer instances in the list together.
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.isBuffer(obj)
Returns true if obj is a Buffer, false otherwise.
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
Buffer.isEncoding(encoding)
A character encoding name to check
true if encoding is the name of a supported character encoding, or false otherwise.
console.log(Buffer.isEncoding('utf8')); // true
console.log(Buffer.isEncoding('hex')); // true
console.log(Buffer.isEncoding('utf/8')); // false
console.log(Buffer.isEncoding('')); // false
Instance Methods
buf.length
Returns the number of bytes in buf.
const buf = Buffer.from('hello');
console.log(buf.length); // Prints: 5
buf.toString([encoding[, start[, end]]])
The character encoding to use
The byte offset to start decoding at
end
integer
default:"buf.length"
The byte offset to stop decoding at (not inclusive)
buf to a string according to the specified character encoding in encoding.
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
buf1[i] = i + 97; // 97 is the decimal ASCII value for 'a'
}
console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde
buf.write(string[, offset[, length]][, encoding])
Number of bytes to skip before starting to write string
length
integer
default:"buf.length - offset"
Maximum number of bytes to write
The character encoding of string
string to buf at offset according to the character encoding in encoding. Returns the number of bytes written.
const buf = Buffer.alloc(256);
const len = buf.write('\u00bd + \u00bc = \u00be', 0);
console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾
buf.fill(value[, offset[, end]][, encoding])
value
string | Buffer | Uint8Array | integer
required
The value with which to fill buf
Number of bytes to skip before starting to fill buf
end
integer
default:"buf.length"
Where to stop filling buf (not inclusive)
The encoding for value if value is a string
buf with the specified value.
const buf = Buffer.allocUnsafe(50).fill('h');
console.log(buf.toString());
// Prints: hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh
buf.slice([start[, end]])
Where the new Buffer will start
end
integer
default:"buf.length"
Where the new Buffer will end (not inclusive)
Buffer that references the same memory as the original, but offset and cropped by the start and end indices.
const buf1 = Buffer.allocUnsafe(26);
for (let i = 0; i < 26; i++) {
buf1[i] = i + 97;
}
const buf2 = buf1.slice(0, 3);
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: abc
buf1[0] = 33;
console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: !bc
buf.copy(target[, targetStart[, sourceStart[, sourceEnd]]])
target
Buffer | Uint8Array
required
A Buffer or Uint8Array to copy into
The offset within target at which to begin writing
The offset within buf from which to begin copying
sourceEnd
integer
default:"buf.length"
The offset within buf at which to stop copying (not inclusive)
buf to a region in target, even if the target memory region overlaps with buf.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');
for (let i = 0; i < 26; i++) {
buf1[i] = i + 97;
}
buf1.copy(buf2, 8, 16, 20);
console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!
Buffers and TypedArrays
Buffer instances are also JavaScript Uint8Array and TypedArray instances. All TypedArray methods are available on Buffers.
const buf = Buffer.from([1, 2, 3, 4]);
const uint32array = new Uint32Array(buf);
console.log(uint32array);
// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]
Buffers and Iteration
Buffer instances can be iterated over using for..of syntax:
const buf = Buffer.from([1, 2, 3]);
for (const b of buf) {
console.log(b);
}
// Prints:
// 1
// 2
// 3
