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.
readable.on("data", (chunk) => {}); readable.on("end", () => {}); writable.on("finish", () => {}); stream.on("close", () => {}); stream.on("error", (err) => {});
Try it
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.
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()fromnode:stream(andnode:stream/promises) resolves on the first of end, finish, error or premature close.