Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream events

Guide to Node.js stream events: data, readable, end, close, error, drain, finish, pipe and unpipe, in which order they fire and which ones to rely on.

Streams are event emitters, and their life cycle is announced through events. Readable streams emit 'data', 'readable', 'end'; writable streams emit 'drain', 'finish'; both emit 'error' and 'close'. Knowing what each one promises, and in what order they arrive, prevents the classic bugs: reading too early, exiting before data is flushed, and swallowing errors.

The short version: 'end' and 'finish' mean "the data side is done", while 'close' means "the resources are released". 'error' means the stream is broken and no more events other than 'close' will follow.

NODE
readable.on("data", (chunk) => {});
readable.on("end", () => {});
writable.on("finish", () => {});
stream.on("close", () => {});
stream.on("error", (err) => {});

Try it

Node.js Readable events in order

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 Writable events in order

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.

Readable events

Event When it fires
'data' A chunk is available. Adding a listener starts flowing mode.
'readable' Data can be pulled with read(), or the end of the stream was reached (then read() returns null).
'end' No more data will be delivered. Only fires once the data has been fully consumed.
'pause' / 'resume' Flow state changed.
'close' The stream and its resource are closed.
'error' A read failed or the stream was destroyed with an error.

Writable events

Event When it fires
'drain' The buffer emptied after write() returned false. Safe to write again.
'finish' end() was called and all data was flushed to the underlying system.
'pipe' / 'unpipe' A readable started or stopped piping into this stream.
'close' The stream is destroyed or finished and resources are released.
'error' A write failed. The stream is destroyed afterwards.

Usage notes

  • 'end' is never emitted if data is not consumed, for example a paused stream with no consumer, or a stream you destroyed. Use 'close' for guaranteed cleanup.
  • A stream that fails emits 'error' once and then 'close'. Never expect 'end' or 'finish' after an error.
  • An 'error' without a listener throws as an uncaught exception.
  • With autoDestroy: true (default), 'close' follows 'end' and 'finish' on the next tick. Duplex streams wait for both sides.
  • 'data' and 'readable' should not be mixed. If a 'readable' listener exists, it controls flow and 'data' stops being reliable.
  • Instead of wiring events by hand, use stream.pipeline(), events.once(stream, "finish") or async iteration, which translate the events into promises.
  • stream.finished() from node:stream (and node:stream/promises) resolves on the first of end, finish, error or premature close.