Node.js v4.9.1 Documentation

Table of Contents

Buffer#

Stability: 2 - Stable

Prior to the introduction of TypedArray in ECMAScript 2015 (ES6), the JavaScript language had no mechanism for reading or manipulating streams of binary data. The Buffer class was introduced as part of the Node.js API to make it possible to interact with octet streams in the context of things like TCP streams and file system operations.

Now that TypedArray has been added in ES6, the Buffer class implements the Uint8Array API in a manner that is more optimized and suitable for Node.js' use cases.

Instances of the Buffer class are similar to arrays of integers but correspond to fixed-sized, raw memory allocations outside the V8 heap. The size of the Buffer is established when it is created and cannot be resized.

The Buffer class is a global within Node.js, making it unlikely that one would need to ever use require('buffer').Buffer.

const buf1 = new Buffer(10);
  // creates a buffer of length 10
  // This is the same as Buffer.allocUnsafe(10), and the returned
  // Buffer instance might contain old data that needs to be
  // overwritten using either fill() or write().

const buf2 = new Buffer([1,2,3]);
  // creates a buffer containing [01, 02, 03]
  // This is the same as Buffer.from([1,2,3]).

const buf3 = new Buffer('test');
  // creates a buffer containing ASCII bytes [74, 65, 73, 74]
  // This is the same as Buffer.from('test').

const buf4 = new Buffer('tést', 'utf8');
  // creates a buffer containing UTF8 bytes [74, c3, a9, 73, 74]
  // This is the same as Buffer.from('tést', 'utf8').

const buf5 = Buffer.alloc(10);
  // Creates a zero-filled Buffer of length 10.

const buf6 = Buffer.alloc(10, 1);
  // Creates a Buffer of length 10, filled with 0x01.

const buf7 = Buffer.allocUnsafe(10);
  // Creates an uninitialized buffer of length 10.
  // This is faster than calling Buffer.alloc() but the returned
  // Buffer instance might contain old data that needs to be
  // overwritten using either fill() or write().

const buf8 = Buffer.from([1,2,3]);
  // Creates a Buffer containing [01, 02, 03].

const buf9 = Buffer.from('test');
  // Creates a Buffer containing ASCII bytes [74, 65, 73, 74].

const buf8 = Buffer.from('tést', 'utf8');
  // Creates a Buffer containing UTF8 bytes [74, c3, a9, 73, 74].

Buffer.from(), Buffer.alloc(), and Buffer.allocUnsafe()#

Historically, Buffer instances have been created using the Buffer constructor function, which allocates the returned Buffer differently based on what arguments are provided:

  • Passing a number as the first argument to Buffer() (e.g. new Buffer(10)), allocates a new Buffer object of the specified size. The memory allocated for such Buffer instances is not initialized and can contain sensitive data. Such Buffer objects must be initialized manually by using either buf.fill(0) or by writing to the Buffer completely. While this behavior is intentional to improve performance, development experience has demonstrated that a more explicit distinction is required between creating a fast-but-uninitialized Buffer versus creating a slower-but-safer Buffer.
  • Passing a string, array, or Buffer as the first argument copies the passed object's data into the Buffer.
  • Passing an ArrayBuffer returns a Buffer that shares allocated memory with the given ArrayBuffer.

Because the behavior of new Buffer() changes significantly based on the type of value passed as the first argument, applications that do not properly validate the input arguments passed to new Buffer(), or that fail to appropriately initialize newly allocated Buffer content, can inadvertently introduce security and reliability issues into their code.

To make the creation of Buffer objects more reliable and less error prone, new Buffer.from(), Buffer.alloc(), and