Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js stream.finished() function

Reference for stream.finished() in Node.js: get notified when a stream has ended, failed or been destroyed, with callback and promise forms and cleanup.

stream.finished(stream[, options], callback) calls your callback once a stream is no longer readable or writable, either because it completed normally or because something went wrong. It listens for end, finish, error and close for you and decides which of them really means "done", which is surprisingly easy to get wrong by hand.

Use it when you hold a single stream and need to know when it is over: after calling end() on a writable, after reading a readable to the end, or when you want to be sure a stream is cleaned up even if it is destroyed early. For a chain of streams, stream.pipeline() is usually the better tool.

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

finished(stream, (err) => {
  if (err) console.error('stream failed', err);
  else console.log('stream done');
});

Try it

Node.js Waiting for a writable to finish

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, early destroy and cleanup

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
stream.finished(stream, callback): () => void
stream.finished(stream, options, callback): () => void
// stream/promises
finished(stream[, options]): Promise<void>
Name Description
stream A Node.js Readable, Writable, Duplex or Transform, or a web stream (ReadableStream, WritableStream).
options.error Default true. When false, an error event is not treated as the end of the stream.
options.readable When false, the callback fires once the stream is done writing, even if the readable side has not ended.
options.writable When false, the callback fires once the stream is done reading, even if the writable side has not finished.
options.signal An AbortSignal. Aborting it stops the waiting (the stream itself is not destroyed) and the callback receives an AbortError.
callback Called once with an Error or nothing. Only the first completion is reported.

Returns: a cleanup function that removes every listener finished() added. The promise form (from node:stream/promises) resolves with undefined or rejects with the error.

Errors: the callback receives ERR_STREAM_PREMATURE_CLOSE when the stream closes before it ended or finished, for instance after destroy() without an error. It receives the stream's own error when one was emitted.

Usage notes

  • A duplex needs both sides. A Duplex or Transform counts as done only when its readable side has ended and its writable side has finished. Use readable: false or writable: false to wait for just one half.
  • Always consume a readable. A readable that nobody reads never emits end, so finished() waits forever. Call resume(), attach a data handler or iterate it.
  • Listeners are left behind. After the callback fires, finished() keeps its listeners on the stream. Call the returned cleanup function if you keep using the stream afterwards, or you will leak a few listeners.
  • Early destroy() is an error. Destroying a stream before it ended is reported as ERR_STREAM_PREMATURE_CLOSE, not as success. That is deliberate: the data may be incomplete.
  • Promise form. import { finished } from 'node:stream/promises' is the form to use with await. It is the same function wrapped in a promise.
  • Not for sockets alone. On a net.Socket the stream can end in many ways (peer reset, timeout). finished() reports whichever comes first, so check the error code before retrying.
  • Added in Node.js 10 (callback form); the signal option and web stream support arrived in later releases.