Node.js' writeable stream and the drain event

Question

The documentation for write() says:

Returns false to indicate that the kernel buffer is full, and the data will be sent out in the future.

and the documentation for the drain event says:

After a write() method returned false, this event is emitted to indicate that it is safe to write again.

What does that mean? Do I have to wait for the drain event before I can write again? What happened to the data which I tried to write? Is that lost? What happens when I call write without waiting for the drain event?

Answer 1

@TooTallNate answer is wrong. You should absolutely care about .write return value.

What does that mean? Do I have to wait for the drain event before I can write again?

Yes, when .write returns false, you must wait.

What happened to the data which I tried to write? Is that lost?

No, it is not lost, it's buffered in the correct order.

What happens when I call write without waiting for the drain event?

If you don't handle the drain event correctly, your script will block the event loop, and eventually exhaust the memory limit crashing your application.

I give a detail explanation in this other question: why does attempting to write large a large file cause js heap to run out of memory

Answer 2

You can call write() without caring about the return value safely. Node will buffer any write calls while the kernel buffer is full, and push them in order as you would expect. You do not need to wait for the 'drain' event before writing again.

Optionally, you can check the return value of write() and then notify the thing that is writing to the Stream that the buffer is full. This is exactly what Stream#pipe() does.

So usually, just use Stream#pipe() and all the goodies are taken care of for you :)