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.
import { finished } from 'node:stream'; finished(stream, (err) => { if (err) console.error('stream failed', err); else console.log('stream done'); });
Try it
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.
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
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
DuplexorTransformcounts as done only when its readable side has ended and its writable side has finished. Usereadable: falseorwritable: falseto wait for just one half. - Always consume a readable. A readable that nobody reads never emits
end, sofinished()waits forever. Callresume(), attach adatahandler 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 asERR_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 withawait. It is the same function wrapped in a promise. - Not for sockets alone. On a
net.Socketthe 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
signaloption and web stream support arrived in later releases.