Node.js Buffer Tutorial

Feb 21, 2020

Node.js buffers are objects that store arbitary binary data. The most common reason for running into buffers is reading files using Node.js:

const fs = require('fs');

const buf = fs.readFileSync('./package.json');
buf instanceof Buffer; // true

buf; // '<Buffer 7b 0a 20 20 22 6e 61 6d 65 22 ...>'

Buffers have a toString() function that takes a single argument encoding. The toString() function lets you convert buffers into meaningful strings depending on encoding. For example, if you read an ordinary text file using fs.readFile(), you can convert the buffer into the text from the file using .toString('utf8'):

const fs = require('fs');

const buf = fs.readFileSync('./package.json');
buf.toString('utf8'); // '{ "name": "masteringjs.io", ...}'

Another common encoding is hex, which encodes the buffer as a string of characters [0-9A-F]. Hex encoding is useful because it doesn't require escaping - you can put a hex encoded buffer into a URI without using encodeURIComponent() or put it into JSON without escaping ", because hex encoding only contains alphanumeric characters.

const fs = require('fs');

const buf = fs.readFileSync('./package.json');
buf.toString('hex'); // '7b0a2020...'

Creating a New Buffer

You can create buffers from strings using the Buffer.from() function. Like toString(), you can pass an encoding argument to Buffer.from().

let buf = Buffer.from('Hello, World', 'utf8');

buf.toString('hex'); // '48656c6c6f2c20576f726c64'
buf.toString('utf8'); // 'Hello, World'

buf = Buffer.from('48656c6c6f2c20576f726c64', 'hex');
buf.toString('utf8'); // 'Hello, World'

The Buffer.from() function also accepts arrays and buffers. You can use Buffer.from() to clone a buffer:

const buf2 = Buffer.from(buf);

buf2 === buf; // false
buf2.toString('utf8'); // 'Hello, World'

Or from an array of numeric bytes:

const buf = Buffer.from([
  0x48,
  0x65,
  0x6c,
  0x6c,
  0x6f,
  0x2c,
  0x20,
  0x57,
  0x6f,
  0x72,
  0x6c,
  0x64
]);

buf.toString('utf8'); // Hello, World

With JSON.stringify()

The JSON.stringify() function converts buffers into objects. The raw data is encoded as an array of bytes that you can pass in to Buffer.from().

let buf = Buffer.from('Hello, World', 'utf8');

let obj = { buffer: buf };
obj = JSON.parse(JSON.stringify(obj));

// { type: 'Buffer',
//   data: [ 72, 101, 108, 108, 111, 44, 32, 87, 111, 114, 108, 100 ] }
obj.buffer;

// To convert from JSON representation back to a buffer, use `Buffer.from()`
obj.buffer = Buffer.from(obj.buffer);
obj.buffer.toString('utf8'); // 'Hello, World'

Did you find this tutorial useful? Say thanks by starring our repo on GitHub!

More Node Tutorials