Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Buffers and Encoding

Node.js buf.toJSON() method

Reference for Node.js buf.toJSON(): the { type, data } object that JSON.stringify produces for a Buffer, how to restore it, and why Base64 is usually better.

buf.toJSON() returns a plain object of the form { type: "Buffer", data: [ ...bytes ] }. You rarely call it yourself: JSON.stringify() calls it automatically whenever a Buffer appears inside the value being serialized, which is why a buffer in a response object turns into that shape.

The data array holds one number from 0 to 255 per byte. This form is easy to read but bulky: each byte becomes up to four characters plus a comma. For anything beyond tiny buffers, encode with Base64 or hex instead.

NODE
Buffer.from("hi").toJSON();
// { type: "Buffer", data: [ 104, 105 ] }
JSON.stringify({ id: Buffer.from("hi") });
// '{"id":{"type":"Buffer","data":[104,105]}}'

Try it

Node.js Buffers inside JSON

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 Restoring buffers and better options

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
buf.toJSON()
// returns { type: "Buffer", data: number[] }

This method takes no parameters.

Returns: a new plain object. The type property is the string "Buffer", and data is an array of the byte values.

Edge cases:

  • An empty buffer gives { type: "Buffer", data: [] }.
  • JSON.stringify() calls toJSON() once per buffer, but a custom replacer function receives the already converted object, not the buffer.
  • Only Buffer has this method. A Uint8Array or ArrayBuffer does not use this form: a typed array serializes as an object with index keys, and an ArrayBuffer as {}.

Usage notes

  • Restoring: Buffer.from(object) understands the { type: "Buffer", data } shape, so Buffer.from(JSON.parse(text)) works for one buffer. For buffers nested in a document, use a reviver that checks type === "Buffer". The check can in theory match user data that looks the same, so avoid the pattern for untrusted documents or validate more strictly.
  • Size: the bytes become decimal numbers, so the JSON is typically three to five times the buffer size, against a third more for Base64. Prefer buf.toString("base64") when you design a format. See buf.toString().
  • Accidental leaks: logging an object with JSON.stringify() that contains a key or token buffer prints the secret bytes as numbers. Redact buffers explicitly.
  • console.log(buf) is different: it prints <Buffer 68 69> through the inspect protocol and does not use toJSON().
  • structuredClone() and postMessage copy buffers as typed arrays and do not use this method.
  • Unusual but valid: you can override toJSON on a subclass or on a single buffer instance if your API wants a different serialization.