Node.js Reference · Buffers and Encoding
Node.js Buffer class
Reference for the Node.js Buffer class: a Uint8Array subclass for binary data, how to create, read, slice, compare and convert buffers, with limits and pitfalls.
Buffer is Node.js's type for a fixed-size sequence of bytes. Files, network sockets, compression, cryptography and most streams deal in bytes, and a Buffer is how you hold and inspect them. Buffer is a global; you can also import it from node:buffer.
Buffer is a subclass of Uint8Array. Every typed array method works on it (map, fill, set, indexOf, iteration), and a buffer can be passed anywhere a Uint8Array is accepted. On top of that it adds string encoding and decoding, integer and float readers and writers, and helpers such as concat() and compare(). A buffer's size is fixed when it is created: you cannot push to it or resize it.
const buf = Buffer.from('héllo', 'utf8'); console.log(buf.length); // 6 bytes for 5 characters console.log(buf.toString('hex')); // '68c3a96c6c6f'
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input · what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
import { Buffer, constants, INSPECT_MAX_BYTES } from 'node:buffer'; Buffer.from(value[, encodingOrOffset[, length]]) Buffer.alloc(size[, fill[, encoding]]) Buffer.allocUnsafe(size) Buffer.concat(list[, totalLength])
The main members, grouped:
| Group | Members |
|---|---|
| Creating | Buffer.from(), Buffer.alloc(), Buffer.allocUnsafe(), Buffer.allocUnsafeSlow() |
| Type checks and sizes | Buffer.isBuffer(), Buffer.isEncoding(), Buffer.byteLength(), buf.length, buf.byteOffset, buf.buffer |
| Text | buf.toString(), buf.write(), buf.toJSON() |
| Slicing and copying | buf.subarray(), buf.slice() (deprecated), buf.copy(), buf.fill() |
| Searching and comparing | buf.indexOf(), buf.includes(), buf.equals(), buf.compare(), Buffer.compare() |
| Numbers | readUInt8 to readBigInt64LE, readFloatBE, readDoubleLE and the matching write... methods, swap16(), swap32(), swap64() |
| Module values | buffer.constants.MAX_LENGTH, buffer.INSPECT_MAX_BYTES (default 50), buffer.transcode(), buffer.isUtf8(), buffer.isAscii(), Blob, File |
Errors: ERR_INVALID_ARG_TYPE for the wrong argument type, ERR_OUT_OF_RANGE for an offset outside the buffer or a size over constants.MAX_LENGTH, ERR_UNKNOWN_ENCODING for a bad encoding name.
Usage notes
buf.lengthcounts bytes, not characters. Non-ASCII text takes two to four bytes per character in UTF-8; useBuffer.byteLength()to measure before allocating.- Assigning an out-of-range number to an index wraps it modulo 256 (
300becomes44). Thewrite...methods throwERR_OUT_OF_RANGEinstead. subarray()returns a view over the same memory. Writes through either object are visible in both. UseBuffer.from(buf)for an independent copy.- Small buffers made by
from()andallocUnsafe()can share one internal pool (its size isBuffer.poolSize, a few KiB to tens of KiB depending on version), sobuf.buffermay be larger than the buffer andbyteOffsetmay be non-zero. Never assumebuf.bufferis exactly your bytes. console.log()shows at most 50 bytes of a buffer (INSPECT_MAX_BYTES).- Always decode with a complete chunk. Calling
toString()on one chunk of a multi-byte stream can split a character; useStringDecoderor set an encoding on the stream. new Buffer()is deprecated and unsafe. Use the factory methods.- The largest buffer is
buffer.constants.MAX_LENGTH, which is 2^53 - 1 bytes on 64-bit platforms in current versions, so in practice available memory is the limit.