Writable Streams

What is a Writable stream?

A Writable is a stream to which data can be written. Node’s built-in examples include fs.createWriteStream (writing a file), process.stdout (terminal output), and HTTP response objects. You can also create custom writables by extending Writable and implementing the _write method.

write() and end()

The two primary methods on a Writable are:

• writable.write(chunk[, encoding][, callback]) — writes a chunk of data. Returns true if the internal buffer is below the high-water mark, false if the destination cannot keep up (backpressure signal).
• writable.end([chunk][, callback]) — signals that no more data will be written. Optionally writes one final chunk. Triggers the finish event once all data has been flushed.

const fs = require('node:fs');

const dest = fs.createWriteStream('./output.txt');

dest.write('first line\n');
dest.write('second line\n');
dest.end('last line\n', function() {
  console.log('all data flushed');
});

The finish event

After end() is called and all pending data has been flushed to the underlying system, the stream emits finish. This is the correct moment to know writing is truly complete:

const fs = require('node:fs');
const dest = fs.createWriteStream('./output.txt');

dest.on('finish', function() {
  console.log('write complete');
});

dest.end('done');

The drain event and flow control

write() returns a boolean. When it returns false, the internal buffer is full — you must stop writing and wait for the drain event before writing more. Ignoring this causes unbounded memory growth as buffered chunks accumulate.

function writeWithDrain(writable, chunks) {
  var i = 0;

  function next() {
    while (i < chunks.length) {
      var ok = writable.write(chunks[i]);
      i++;
      if (!ok) {
        // buffer full — wait for drain before continuing
        writable.once('drain', next);
        return;
      }
    }
    writable.end();
  }

  next();
}

This is the manual pattern that pipe and pipeline handle for you automatically. Understanding it explains why those higher-level APIs exist.

Measuring highWaterMark, write(), and writableLength

writable.writableLength reports exactly how many bytes (or objects, in object mode) are currently buffered and not yet flushed to the underlying destination. Watching it alongside write()’s return value makes the high-water mark concrete instead of abstract:

Node.jsOpen in StackBlitz ▸

import { Writable } from 'node:stream'; var sink = new Writable({ highWaterMark: 10, // bytes -- tiny on purpose so backpressure triggers fast write(chunk, encoding, callback) { setImmediate(callback); // simulate an async destination } }); console.log('highWaterMark:', sink.writableHighWaterMark); var okFirst = sink.write('12345'); // 5 bytes, still under 10 console.log('write() #1 returned:', okFirst, '| writableLength:', sink.writableLength); var okSecond = sink.write('1234567890'); // pushes past the high-water mark console.log('write() #2 returned:', okSecond, '| writableLength:', sink.writableLength); sink.once('drain', function() { console.log('drain fired -- writableLength now:', sink.writableLength); sink.end(); });

Output (verified on Node 24)

highWaterMark: 10
write() #1 returned: true | writableLength: 5
write() #2 returned: false | writableLength: 15
drain fired -- writableLength now: 0

Notice writableLength reaches 15 — above the high-water mark of 10. The high-water mark is a threshold that flips write()’s return value to false, not a hard cap: Node still accepts and buffers the chunk you just wrote, and it becomes your responsibility to stop calling write() until drain fires.

Runnable demo

The demo creates a custom Writable that logs each chunk to the console, simulating a slow sink. It then writes three chunks and closes the stream.

Node.jsOpen in StackBlitz ▸

const { Writable } = require('node:stream'); const sink = new Writable({ write(chunk, encoding, callback) { console.log('sink received: ' + chunk.toString()); callback(); // signal ready for next chunk } }); sink.on('finish', function() { console.log('stream finished'); }); sink.write('alpha'); sink.write('beta'); sink.end('gamma');

Output (verified on Node 24)

sink received: alpha
sink received: beta
sink received: gamma
stream finished

🟢 Respect the return value of write() for flow control

When writable.write() returns false, the destination buffer is full. Stop writing immediately and wait for the drain event before sending more data. Ignoring this signal causes the Node process to buffer unlimited data in memory, eventually causing an out-of-memory crash.

Mental Model

flowchart TB
  Write["writable.write(chunk)"] -->|"below high-water mark"| True["returns true -- keep writing"]
  Write -->|"at or above high-water mark"| False["returns false -- buffer is full"]
  False -->|"you must"| Pause["stop writing"]
  Pause -->|"wait for"| Drain["'drain' event"]
  Drain -->|"safe to"| Write
  End["writable.end()"] -->|"once all buffered data is flushed"| Finish["'finish' event"]

write()'s boolean return value is the whole backpressure contract: false means stop and wait for drain before writing again

Trade-offs

Choice	Benefit	Cost
Manual write()/drain handling	Full control over exactly when and how much to buffer	Verbose and easy to get wrong — one missed check and memory grows without bound
.pipe() / pipeline()	Handles the write()/drain dance for you automatically	Less direct control; you consume the higher-level API’s error/completion contract instead of rolling your own
Checking writableLength directly	Gives an exact, real-time buffered-byte (or object) count for monitoring/logging	One more thing to read correctly — it means nothing without also knowing the current writableHighWaterMark

Common Misconceptions

• “The high-water mark is a hard limit on how much writable can buffer” — fact: it’s a soft threshold that flips write()’s return value to false; Node still accepts and buffers the chunk that pushed you over it.
• “write() returning false means the write failed” — fact: the chunk was still accepted and will still be flushed; false is purely a signal to slow down, not an error.
• “finish and close mean the same thing” — fact: finish fires once all buffered data has been flushed after end(); close fires when the underlying resource (a file descriptor, a socket) has actually been released, which can happen at a different time.

Reading AI-generated code

• Does code call writable.write() in a loop without ever checking its boolean return value or listening for drain?
• Does a custom Writable’s write(chunk, encoding, callback) implementation forget to call callback() on every code path (including error paths), which stalls the stream forever waiting for a callback that never comes?
• Does code assume end() completing means the destination file/socket is fully closed, when it should wait for finish (data flushed) or close (resource released) depending on what it actually needs to know?

🐛 Spot the bug

const { Writable } = require('node:stream');
const fs = require('node:fs');

var dest = fs.createWriteStream('./output.log');

function writeAll(lines) {
for (var i = 0; i < lines.length; i++) {
  dest.write(lines[i] + '\n'); // return value never checked
}
dest.end();
}

writeAll(new Array(1000000).fill('a log line'));

Show the answer

writeAll calls dest.write() in a tight loop without ever checking its return value or pausing when it returns false. If the destination (a disk, a network socket) cannot keep up with a million synchronous write() calls, Node keeps buffering every chunk in memory regardless, and the process can OOM before end() is even reached. The fix is the manual pattern from earlier in this lesson — check write()’s return value and pause via writable.once('drain', next) — or, more simply, replace the whole loop with a Readable wrapping lines piped into dest.

🟢 The one-line takeaway

write()’s boolean return value is the entire backpressure contract — false means stop and wait for drain, and writableLength tells you exactly how much is buffered right now.

What does writable.write() return when the internal buffer is full?

null true false a Promise that resolves when drained

Which event fires after writable.end() is called and all data has been flushed?

end close drain finish

What is the correct action when writable.write() returns false?

Call writable.end() immediately Continue writing — false is just a warning Stop writing and wait for the drain event Destroy the stream and create a new one

A Writable has highWaterMark: 10 (bytes). After one write() call with a 15-byte chunk, what does writableLength report, and what did write() return?

writableLength: 10 (capped at the high-water mark), write() returned true writableLength: 15, write() returned false writableLength: 0 because the chunk was rejected, write() returned false writableLength: 15, write() returned true because it was a single call

A custom Writable's write(chunk, encoding, callback) throws an exception instead of calling callback() on an error path. What is the observable symptom?

Node automatically calls callback(err) for you The stream silently drops the chunk and continues normally The stream stalls indefinitely, since nothing signals that the write finished or failed The process crashes immediately with a clear error message pointing at the missing callback

What is the difference between the finish and close events on a Writable?

They are aliases for the same event finish fires when all buffered data has been flushed after end(); close fires when the underlying resource has actually been released, which can be a separate moment close always fires before finish finish only exists on Readable streams

Submit

Mark as complete