Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js readable.read() method

Reference for readable.read() in Node.js: pull chunks from a stream buffer, the size argument, null results, the readable event and read(0).

readable.read([size]) takes data out of a readable stream's internal buffer and returns it, or returns null if nothing is available right now. It is the low-level, pull-style way of consuming a stream, used in paused mode together with the 'readable' event.

Most code uses for await or 'data' listeners instead. read() is the right tool when you need exact control: reading a fixed number of bytes for a header, parsing a binary protocol, or taking data only when your own code is ready for it.

NODE
const chunk = readable.read();
const header = readable.read(4);

Try it

Node.js The readable event loop

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 Reading an exact size

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 Objects and null while waiting

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
readable.read([size]): Buffer | string | any | null
Name Description
size Optional number of bytes (or characters when an encoding is set) to read. Ignored in object mode, where one object is returned.

Returns: a Buffer (or string if setEncoding() was used, or an object in object mode), or null when not enough data is buffered.

Behavior by argument:

  • read() returns everything in the buffer in non-object mode, or one object in object mode.
  • read(n) returns exactly n units if that many are buffered. If fewer are buffered and the stream has not ended, it returns null and keeps the data; at the end of the stream it returns the remainder.
  • read(0) returns null but may trigger a refill of the buffer and a 'readable' event; it is used to start reading without consuming.

Usage notes

  • A null return does not mean the stream ended; it means "nothing right now". Wait for the next 'readable' event, and 'end' tells you the stream is finished.
  • Drain the buffer in a loop until read() returns null inside the 'readable' handler. If you stop early, another 'readable' event will not necessarily fire.
  • Adding a 'readable' listener takes priority over 'data' listeners: the stream stays paused and 'data' events only fire when you call read(). Do not mix both styles.
  • Calling read() on a stream with a 'data' listener in flowing mode is possible but confusing; pick one mode per stream.
  • read(size) with a size larger than highWaterMark makes the stream raise its high-water mark to fit.
  • Text: use setEncoding('utf8') so multi-byte characters are not split across reads.