Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js WritableStream (web streams)

Reference for the global WritableStream in Node.js: define a sink with write, close and abort callbacks, use writers, backpressure and pipeTo.

WritableStream is the web-standard destination for chunks of data. You describe where data goes by passing an underlying sink with write, close and abort callbacks, and callers send data through a writer or by piping a ReadableStream into it. It is a global in Node.js and also exported from node:stream/web.

The stream handles queuing and backpressure for you: chunks are handed to write() strictly one at a time, and the next call happens only after the promise returned by the previous one settles. That makes it a good fit for sinks that are asynchronous, like a database insert or a network write.

NODE
const sink = new WritableStream({
  write(chunk) {
    console.log('got', chunk);
  },
});

Try it

Node.js A sink and a writer

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 Piping into a sink and handling abort

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 WritableStream(underlyingSink?, strategy?)
stream.getWriter()          // WritableStreamDefaultWriter
stream.close()
stream.abort(reason?)
stream.locked
Name Description
underlyingSink.start(controller) Runs once at construction.
underlyingSink.write(chunk, controller) Called per chunk, one at a time. Return a promise to apply backpressure.
underlyingSink.close() Called after the last chunk was written.
underlyingSink.abort(reason) Called when the stream is aborted.
strategy { highWaterMark, size } (default: 1 chunk) or a CountQueuingStrategy / ByteLengthQueuingStrategy.
controller error(e) and signal (an AbortSignal that aborts when the stream is aborted).

Writer members: write(chunk), close(), abort(reason), releaseLock(), ready (a promise), closed (a promise), desiredSize.

Errors: an exception or rejection in write() puts the stream in an errored state; later writes reject with that error. getWriter() throws a TypeError (ERR_INVALID_STATE) if the stream is already locked.

Usage notes

  • Await writer.ready. When desiredSize is zero or negative the queue is full. Awaiting writer.ready before each write() is the web equivalent of waiting for drain.
  • close() waits. It resolves after every queued chunk has been processed and the sink's close() callback has run.
  • abort() discards. Chunks still queued are dropped and never reach write().
  • Locking. A writer locks the stream; a pipeTo() locks it for the duration of the pipe. Release the writer to let someone else write.
  • Node.js interop. Wrap a Node.js writable with Writable.toWeb() and the reverse with Writable.fromWeb().
  • Chunks are any value. There is no encoding step: strings, buffers and objects are all valid unless your write() rejects them.