Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 133 ยท Streams

Writable Streams

Master Node.js writable streams - write() and end(), the return value and drain event, building a custom sink with _write and _final, writev, cork, errors and finished().

A writable stream is a destination: a file, a network socket, an HTTP response, standard output, or something you invent such as a database loader. You push data in with write(), say you are finished with end(), and the stream takes care of delivering the bytes at whatever pace the destination can manage.

That last part is the interesting one. A destination can be slower than your code, and a writable has a built-in way to tell you so. Understanding the return value of write() and the 'drain' event is the difference between a program that handles a 10 GB export gracefully and one that is killed for using all the memory. This lesson covers the API, how to write your own destination, and how to detect when everything has really been written. It builds on Streams Fundamentals and prepares you for pipeline and Backpressure.

write() and end()

The basic contract is small:

  • stream.write(chunk[, encoding][, callback]) queues a chunk. The optional callback runs when that chunk has been handled (or failed).
  • stream.end([chunk]) optionally writes a last chunk and then closes the writing side.
  • After end(), calling write() is an error (ERR_STREAM_WRITE_AFTER_END).
  • The stream emits 'finish' after end() once all data has been flushed to the destination, and 'close' once resources are released.

The easiest way to experiment is with a small in-memory sink, created by passing a write function to the Writable constructor.

Node.js write, end and the finish event

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.

The most important line is callback(). A writable processes one chunk at a time: it will not call your write method again until you call callback. Call it when the work for this chunk is done, which for async destinations means after the async operation completes. Pass an error to the callback (callback(err)) to fail the stream.

The return value of write() and 'drain'

Every writable has a buffer and a highWaterMark (16 KiB by default in byte mode, 16 objects in object mode). When you call write():

  • It returns true if the buffer is still below the mark: keep going.
  • It returns false once the buffered data reaches the mark: stop writing and wait for the 'drain' event, which fires when the buffer has emptied.

Note that false does not mean the chunk was dropped. It was accepted. The return value is advice, and ignoring it is allowed but dangerous, because the buffer will keep growing in memory.

Node.js Honoring write() and drain

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.

The loop pauses whenever the buffer fills, so no more than a handful of rows ever wait in memory, however many rows the loop produces. This is called backpressure: the slow end pushes back on the fast end. Production code uses pipeline() to do this automatically (see pipeline and Backpressure), but when you write a loop by hand, the if (!ok) await once(stream, 'drain') idiom is the pattern to remember. Notice that once comes from events.

Writing your own destination

A custom writable implements _write(chunk, encoding, callback), either by subclassing or by passing write in the options. Optionally:

  • _final(callback) runs after end() when every chunk has been processed, but before 'finish'. Use it to flush a last partial batch or close a connection.
  • _destroy(err, callback) cleans up when the stream is destroyed.
  • _writev(chunks, callback) handles several buffered chunks at once (more below).

Here is a realistic sink: a batch uploader that groups records in fives and sends each group in one go. It shows _write buffering, async work and _final flushing the remainder.

Node.js A batching sink with _write and _final

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.

Twelve records produce two full batches (1 to 5 and 6 to 10) and the leftover two (11, 12) are sent by _final. Without _final, those last two records would sit in the array forever and 'finish' would fire too early, which is a classic bug in custom sinks. Both async paths use .then(() => callback(), callback) so that a rejected promise is reported as a stream error instead of becoming an unhandled rejection.

Chunks, encodings and decodeStrings

By default a writable converts strings to Buffers before calling _write, so chunk is a Buffer and encoding is 'buffer'. Set decodeStrings: false if you want the original string and its encoding (rarely useful). In object mode none of this applies: you get the value as written.

Batching with writev and cork

If a stream implements _writev(chunks, callback), Node can hand it several buffered chunks at once, as an array of { chunk, encoding }. That is useful when one big write is cheaper than many small ones, like one socket send or one SQL INSERT with many rows.

Chunks accumulate while the stream is busy, or deliberately when you cork() it. cork() holds writes in the buffer; uncork() releases them, and on the next tick Node delivers them together through _writev (if present).

Node.js cork, uncork and _writev

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.

The three corked chunks arrived as one _writev call. The HTTP response stream and file streams use the same mechanism internally to turn many small writes into a few system calls. Call uncork() as many times as you called cork(), or the data stays held.

Errors, finished() and knowing when it is really done

Writables report failure with the 'error' event, after which the stream is destroyed. Two behaviors surprise people:

  1. 'finish' does not mean the data is on disk. It means every chunk was passed to your _write/_final and their callbacks succeeded. Whether the file system flushed to disk is another matter. For a file stream, 'close' is the safer signal that the file descriptor was released.
  2. 'finish' is not emitted on failure. Code waiting only for 'finish' hangs forever if the stream errors out.

stream.finished(stream, callback) (and its promise form in node:stream/promises) solves the second problem: it resolves when the stream is done in any way and rejects if it failed. It also handles streams destroyed prematurely.

Node.js finished() sees success and failure

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.

The same example without any error handling would throw an unhandled 'error' event. Whenever you create a writable by hand, either attach an 'error' listener, use finished, or hand it to pipeline.

Do not call write() after end(), and do not call end() twice with data. The first gives ERR_STREAM_WRITE_AFTER_END (delivered as an 'error' event and to the write callback). Also remember that process.stdout and process.stderr are writables too: they can be written to, but you should never end() them.

Useful properties

  • writableLength: bytes (or objects) currently queued.
  • writableHighWaterMark: the threshold in effect.
  • writableNeedDrain: true if a 'drain' is pending.
  • writableEnded: end() was called. writableFinished: 'finish' was emitted.
  • destroyed: the stream has been destroyed.

When to write a custom Writable

Most programs never need one: they use fs.createWriteStream, an HTTP response or a socket. Build your own for sinks that Node does not provide: batching database inserts, counting or hashing data, collecting output in tests, or adapting a third-party client with a callback API. If your sink is a function you call per item, a simple for await loop that awaits your own function is often clearer than a custom class. Reach for a Writable when you need the stream protocol itself, meaning backpressure and pipeline() compatibility.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does it mean when writable.write(chunk) returns false?

    The chunk was accepted. false is a signal to pause until the 'drain' event so that the buffer does not grow without limit.
  2. 2. When must the callback passed to _write be called?

    A writable handles one chunk at a time and waits for the callback. Calling it with an error fails the stream.
  3. 3. What is _final for?

    _final lets a sink flush partial batches or close connections before 'finish' is emitted.
  4. 4. Why can code that only waits for the 'finish' event hang?

    On failure the stream emits 'error' and is destroyed. Use stream/promises finished() or pipeline() to handle both outcomes.
  5. 5. What does cork() do?

    Corking groups several small writes into one batch, which is cheaper for many destinations.

Summary

  • write() queues data and end() closes the writing side; 'finish' fires after everything was flushed, 'close' after resources are released.
  • A false return from write() means the buffer is full: wait for 'drain' (await once(stream, 'drain')) to keep memory flat.
  • Implement _write(chunk, encoding, callback) and call callback when done or with an error; add _final to flush leftovers and _destroy for cleanup.
  • cork()/uncork() and _writev batch many small writes into one operation.
  • Errors destroy the stream and 'finish' is not emitted, so use finished() or pipeline() instead of waiting for 'finish' alone.
  • Writing after end() is an error, and standard output should never be ended.

Next: Transform and Duplex Streams