Node.js Stream Module

A stream is an abstract interface for working with streaming data in Node.js. The node:stream module provides an API for implementing the stream interface.

There are many stream objects provided by Node.js. For instance, a request to an HTTP server and process.stdout are both stream instances.

There are four fundamental stream types within Node.js.

Readable: streams from which data can be read (for example, fs.createReadStream()).

Writable: streams to which data can be written (for example, fs.createWriteStream()).

The stream/promises API provides an alternative set of asynchronous utility functions for streams that return Promise objects rather than using callbacks.

The API is accessible via require('node:stream/promises') or require('node:stream').promises.

The function is a utility provided by the stream module to simplify working with streams.

It allows you to compose multiple streams into a pipeline and automatically handles errors, making it easier to manage the flow of data between streams.

To use an AbortSignal, pass it inside an options object, as the last argument.

When the signal is aborted, destroy will be called on the underlying pipeline, with an AbortError.

The pipeline API also supports async generators.

Remember to handle the signal argument passed into the async generator.

Especially in the case where the async generator is the source for the pipeline (i.e. first argument) or the pipeline will never complete.

It is a utility function provided by the stream module that allows you to detect when a stream has finished reading or writing, including handling errors and other termination conditions.

All streams created by Node.js APIs operate exclusively on strings, <Buffer>, <TypedArray> and <DataView> objects.

Strings and Buffers are the most common types used with streams.

Both Writable and Readable streams will store data in an internal buffer.

The amount of data potentially buffered depends on the highWaterMark option passed into the stream's constructor.

Almost all Node.js applications, no matter how simple, use streams in some manner.

The following is an example of using streams in a Node.js application that implements an HTTP server.

Writable streams are an abstraction for a destination to which data is written.

The 'close' event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed.

The event indicates that no more events will be emitted, and no further computation will occur.

If a call to stream.write(chunk) returns false, the 'drain' event will be emitted when it is appropriate to resume writing data to the stream.

The 'error' event is emitted if an error occurred while writing or piping data. The listener callback is passed a single Error argument when called.

The stream is closed when the 'error' event is emitted unless the autoDestroy option was set to false when creating the stream.

The 'finish' event is emitted after the stream.end() method has been called, and all data has been flushed to the underlying system.

src <stream.Readable> source stream that is piping to this writable

The 'pipe' event is emitted when the stream.pipe() method is called on a readable stream, adding this writable to its set of destinations.

src <stream.Readable> The source stream that unpiped this writable

The 'unpipe' event is emitted when the stream.unpipe() method is called on a Readable stream, removing this Writable from its set of destinations.

The writable.cork() method forces all written data to be buffered in memory. The buffered data will be flushed when either the stream.uncork() or stream.end() methods are called.

error <Error> Optional, an error to emit with 'error' event.

Returns: <this>

Destroy the stream. Optionally emit an 'error' event, and emit a 'close' event (unless emitClose is set to false).

<boolean>

Is true after 'close' has been emitted.

<boolean>

Is true after writable.destroy() has been called.

Calling the writable.end() method signals that no more data will be written to the Writable.

The optional chunk and encoding arguments allow one final additional chunk of data to be written immediately before closing the stream.

The writable.setDefaultEncoding() method sets the default encoding for a Writable stream.

The writable.uncork() method flushes all data buffered since stream.cork() was called.

<boolean>

Is true if it is safe to call writable.write(), which means the stream has not been destroyed, errored, or ended.

<boolean>

Is true after writable.end() has been called. This property does not indicate whether the data has been flushed, for this use writable.writableFinished instead.

<integer>

Number of times writable.uncork() needs to be called in order to fully uncork the stream.

<Error>

Returns error if the stream has been destroyed with an error.

<boolean>

Is set to true immediately before the 'finish' event is emitted.

<number>

Return the value of highWaterMark passed when creating this Writable.

<number>

This property contains the number of bytes (or objects) in the queue ready to be written. The value provides introspection data regarding the status of the highWaterMark.

<boolean>

Is true if the stream's buffer has been full and stream will emit 'drain'.

<boolean>

Getter for the property objectMode of a given Writable stream.

The writable.write() method writes some data to the stream, and calls the supplied callback once the data has been fully handled. If an error occurs, the callback will be called with the error as its first argument.

The callback is called asynchronously and before 'error' is emitted.

Readable streams are an abstraction for a source from which data is consumed.

Readable streams effectively operate in one of two modes: flowing and paused. These modes are separate from object mode.

A Readable stream can be in object mode or not, regardless of whether it is in flowing mode or paused mode.

The "two modes" of operation for a Readable stream are a simplified abstraction for the more complicated internal state management that is happening within the Readable stream implementation.

The Readable stream API evolved across multiple Node.js versions and provides multiple methods of consuming stream data.

In general, developers should choose one of the methods of consuming data and should never use multiple methods to consume data from a single stream.

The 'close' event is emitted when the stream and any of its underlying resources (a file descriptor, for example) have been closed.

The event indicates that no more events will be emitted, and no further computation will occur.

The 'data' event is emitted whenever the stream is relinquishing ownership of a chunk of data to a consumer.

This may occur whenever the stream is switched in flowing mode by calling readable.pipe(), readable.resume(), or by attaching a listener callback to the 'data' event.

The 'end' event is emitted when there is no more data to be consumed from the stream.

The 'end' event will not be emitted unless the data is completely consumed. This can be accomplished by switching the stream into flowing mode, or by calling stream.read() repeatedly until all data has been consumed.

<Error>

The 'error' event may be emitted by a Readable implementation at any time. Typically, this may occur if the underlying stream is unable to generate data due to an underlying internal failure, or when a stream implementation attempts to push an invalid chunk of data.

The 'pause' event is emitted when stream.pause() is called and readableFlowing is not false.

The 'readable' event is emitted when there is data available to be read from the stream, up to the configured high water mark (state.highWaterMark).

Effectively, it indicates that the stream has new information within the buffer. If data is available within this buffer, stream.read() can be called to retrieve that data.

The 'resume' event is emitted when stream.resume() is called and readableFlowing is not true.

readable.destroy([error])

error <Error> Error which will be passed as payload in 'error' event

Returns: <this>

<boolean>

Is true after 'close' has been emitted.

<boolean>

Is true after readable.destroy() has been called.

Returns: <boolean>

The readable.isPaused() method returns the current operating state of the Readable.

Returns: <this>

The readable.pause() method will cause a stream in flowing mode to stop emitting 'data' events, switching out of flowing mode. Any data that becomes available will remain in the internal buffer.

The readable.pipe() method attaches a Writable stream to the readable, causing it to switch automatically into flowing mode and push all of its data to the attached Writable.

The readable.read() method reads data out of the internal buffer and returns it. If no data is available to be read, null is returned.

By default, the data is returned as a Buffer object unless an encoding has been specified using the readable.setEncoding() method or the stream is operating in object mode.

<boolean>

Is true if it is safe to call readable.read(), which means the stream has not been destroyed or emitted 'error' or 'end'.

<null> | <string>

Getter for the property encoding of a given Readable stream. The encoding property can be set using the readable.setEncoding() method.

<boolean>

Becomes true when 'end' event is emitted.

<Error>

Returns error if the stream has been destroyed with an error.

<boolean>

This property reflects the current state of a Readable stream as described in the Three states section.

<number>

Returns the value of highWaterMark passed when creating this Readable.

<number>

This property contains the number of bytes (or objects) in the queue ready to be read. The value provides introspection data regarding the status of the highWaterMark.

<boolean>

Getter for the property objectMode of a given Readable stream.

Returns: <this>

The readable.resume() method causes an explicitly paused Readable stream to resume emitting 'data' events, switching the stream into flowing mode.

The readable.setEncoding() method sets the character encoding for data read from the Readable stream.

The readable.unpipe() method detaches a Writable stream previously attached using the stream.pipe() method.

If the destination is not specified, then all pipes are detached.

If the destination is specified, but no pipe is set up for it, then the method does nothing.

The readable.unshift() method pushes a chunk of data back into the internal buffer.

This is useful in certain situations where a stream is being consumed by code that needs to "un-consume" some amount of data that it has optimistically pulled out of the source, so that the data can be passed on to some other party.

stream <Stream> An "old style" readable stream

Returns: <this>

Returns: <AsyncIterator> to fully consume the stream.

Duplex streams are streams that implement both the Readable and Writable interfaces.

<boolean>

If false then the stream will automatically end the writable side when the readable side ends. Set initially by the allowHalfOpen constructor option, which defaults to true.

Transform streams are Duplex streams where the output is in some way related to the input. Like all Duplex streams, Transform streams implement both the Readable and Writable interfaces.

Destroy the stream, and optionally emit an 'error' event.

The utility function duplexPair returns an Array with two items, each being a Duplex stream connected to the other side.

A function to get notified when a stream is no longer readable, writable or has experienced an error or a premature close event.

A module method to pipe between streams and generators forwarding errors and properly cleaning up and provide a callback when the pipeline is complete.

A utility method for creating readable streams out of iterators.

A utility method for creating duplex streams.

Attaches an AbortSignal to a readable or writeable stream.

This lets code control stream destruction using an AbortController.

Returns the default highWaterMark used by streams. Defaults to 65536 (64 KiB), or 16 for objectMode.

Sets the default highWaterMark used by streams.