Skip to content
Tutorials Center
My learning

Topics

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.

NODE
const buf = Buffer.from('héllo', 'utf8');
console.log(buf.length);          // 6 bytes for 5 characters
console.log(buf.toString('hex')); // '68c3a96c6c6f'

Try it

Node.js Creating and inspecting a buffer

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.

Node.js Views, copies and numbers

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

NODE
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.length counts bytes, not characters. Non-ASCII text takes two to four bytes per character in UTF-8; use Buffer.byteLength() to measure before allocating.
  • Assigning an out-of-range number to an index wraps it modulo 256 (300 becomes 44). The write... methods throw ERR_OUT_OF_RANGE instead.
  • subarray() returns a view over the same memory. Writes through either object are visible in both. Use Buffer.from(buf) for an independent copy.
  • Small buffers made by from() and allocUnsafe() can share one internal pool (its size is Buffer.poolSize, a few KiB to tens of KiB depending on version), so buf.buffer may be larger than the buffer and byteOffset may be non-zero. Never assume buf.buffer is 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; use StringDecoder or 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.