Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream.Writable class

Reference for stream.Writable in Node.js: writing chunks, write() return value and drain, end(), final(), events, cork() and implementing your own sink.

A Writable stream is a destination for data: a file opened for writing, an HTTP response, a socket, process.stdout, a zlib compressor input. You push chunks in with write() and finish with end(). The stream buffers what it cannot process immediately and tells you, through the return value of write(), when you should slow down.

To create a custom destination, pass a write(chunk, encoding, callback) function to the constructor. Call the callback when the chunk has been handled; call it with an error to fail the stream. The next chunk is only delivered after the callback, so chunks are processed strictly one at a time.

NODE
import { Writable } from 'node:stream';

const sink = new Writable({
  write(chunk, encoding, callback) {
    callback();
  },
});

Try it

Node.js A custom writable collecting chunks

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 Backpressure 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.

Node.js Errors in write and writes after end

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.

Syntax

NODE
new stream.Writable([options])
writable.write(chunk[, encoding][, callback]): boolean
writable.end([chunk[, encoding]][, callback]): this
Option Description
write(chunk, encoding, cb) Required implementation (unless you override _write or writev). Call cb() when done.
writev(chunks, cb) Optional batch implementation; receives an array of { chunk, encoding } after cork()/buffering.
final(cb) Called after end() and all writes, before 'finish'. Flush or close resources here.
destroy(err, cb) Custom cleanup for destroy().
highWaterMark Buffered size at which write() returns false. Bytes, or objects in object mode.
decodeStrings Convert string chunks to Buffer before write(). Default true.
objectMode Accept any value as a chunk.
defaultEncoding Encoding for strings when none is given. Default 'utf8'.
emitClose, autoDestroy, signal As for Readable.

Returns: write() gives true if you may write more now and false if the buffer reached highWaterMark; wait for 'drain'.

Events: drain, finish, close, error, pipe, unpipe. Properties: writableLength, writableHighWaterMark, writableNeedDrain, writableEnded, writableFinished, destroyed. Other methods: cork(), uncork(), destroy([err]), setDefaultEncoding().

Errors: writing after end() emits ERR_STREAM_WRITE_AFTER_END. Writing null throws ERR_STREAM_NULL_VALUES.

Usage notes

  • A false return from write() is advice, not an error. The data was accepted, but ignoring the advice lets memory grow without bound. Wait for 'drain' or use stream.pipeline().
  • 'finish' means all data was flushed to the underlying system; end() only means no more writes will come. Use finish for "done".
  • Always attach an 'error' listener. After an error the stream is destroyed and later writes fail.
  • cork() holds writes in memory so uncork() can pass them to writev() in one batch, which helps with syscalls or network frames.
  • A string chunk is converted to a Buffer by default, so chunk in write() is a Buffer. Set decodeStrings: false to receive strings.
  • stream.finished() and stream/promises helpers are the clean way to await completion.