If a call to returns, the event will be emitted when it is appropriate to resume writing data to the stream.
// Write the data to the supplied writable stream one million times.
// Be attentive to back-pressure.
// last time!
// see if we should continue, or wait
// don't pass the callback, because we're not done yet.
// had to stop early!
// write some more once it drains
The event is emitted if an error occurred while writing or piping data.
The listener callback is passed a single argument when called.
The stream is not closed when the event is emitted.
The event is emitted after the method has been called, and all data has been flushed to the underlying system.
source stream that is piping to this writable
The event is emitted when the method is called on a readable stream, adding this writable to its set of destinations.
The source stream that this writable
The event is emitted when the method is called on a stream, removing this from its set of destinations.
This is also emitted in case this stream emits an error when a stream pipes into it.
The method forces all written data to be buffered in memory.
The buffered data will be flushed when either the or methods are called.
The primary intent of is to avoid a situation where writing many small chunks of data to a stream do not cause a backup in the internal buffer that would have an adverse impact on performance.
In such situations, implementations that implement the method can perform buffered writes in a more optimized manner.
Destroy the stream, and emit the passed and a event.
After this call, the writable stream has ended and subsequent calls to will give an error.
Implementors should not override this method, but instead implement
Optional data to write.
For streams not operating in object mode, must be a string, or
The encoding, if is a string
Optional callback for when the stream is finished
Calling the method signals that no more data will be written to the
The optional and arguments allow one final additional chunk of data to be written immediately before closing the stream.
If provided, the optional function is attached as a listener for the event.
Calling the method after calling will raise an error.
write and then end with
writing more now is not allowed
The method sets the default for a stream.
The method flushes all data buffered since was called.
When using and to manage the buffering of writes to a stream, it is recommended that calls to be deferred using
Doing so allows batching of all calls that occur within a given Node.js event loop phase.
If the method is called multiple times on a stream, the same number of calls to must be called to flush the buffered data.
The data will not be flushed until is called a second time.
Return the value of passed when constructing this
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
Callback for when this chunk of data is flushed
if the stream wishes for the calling code to wait for the event to be emitted before continuing to write additional data; otherwise
The method writes some data to the stream, and calls the supplied once the data has been fully handled.
If an error occurs, the may or may not be called with the error as its first argument.
To reliably detect write errors, add a listener for the event.
The return value is if the internal buffer is less than the configured when the stream was created after admitting
If is returned, further attempts to write data to the stream should stop until the event is emitted.
While a stream is not draining, calls to will buffer, and return false.
Once all currently buffered chunks are drained (accepted for delivery by the operating system), the event will be emitted.
It is recommended that once returns false, no more chunks be written until the event is emitted.
Even before it aborts, high memory usage will cause poor garbage collector performance and high RSS (which is not typically released back to the system, even after the memory is no longer required).
Since TCP sockets may never drain if the remote peer does not read the data, writing a socket that is not draining may lead to a remotely exploitable vulnerability.
Writing data while the stream is not draining is particularly problematic for a, because the streams are paused by default until they are piped or an or event handler is added.
If the data to be written can be generated or fetched on demand, it is recommended to encapsulate the logic into a and use
However, if calling is preferred, it is possible to respect backpressure and avoid memory issues using the event:
Wait for cb to be called before doing any other write.
A stream in object mode will always ignore the argument.
Readable streams are an abstraction for a from which data is consumed.
Examples of streams include:
HTTP responses, on the client
HTTP requests, on the server
All streams implement the interface defined by the class.
streams effectively operate in one of two modes: flowing and paused.
When in flowing mode, data is read from the underlying system automatically and provided to an application as quickly as possible using events via the interface.
In paused mode, the method must be called explicitly to read chunks of data from the stream.
All streams begin in paused mode but can be switched to flowing mode in one of the following ways:
Adding a event handler.
Calling the method.
Calling the method to send the data to a
The can switch back to paused mode using one of the following:
If there are no pipe destinations, by calling the method.
If there are pipe destinations, by removing all pipe destinations.
Multiple pipe destinations may be removed by calling the method.
The important concept to remember is that a will not generate data until a mechanism for either consuming or ignoring that data is provided.
If the consuming mechanism is disabled or taken away, the will attempt to stop generating the data.
For backwards compatibility reasons, removing event handlers will not automatically pause the stream.
Also, if there are piped destinations, then calling will not guarantee that the stream will paused once those destinations drain and ask for more data.
If a is switched into flowing mode and there are no consumers available to handle the data, that data will be lost.
This can occur, for
instance, when the method is called without a listener attached to the event, or when a event handler is removed from the stream.