Italian Translation Report: Node.js [Part 20 - 1133 words]

Stability: 2 - Stable
A stream is an abstract interface for working with streaming data in Node.js.
The module provides a base API that makes it easy to build objects that implement the stream interface.
There are many stream objects provided by Node.js.
For instance, a and are both stream instances.
Streams can be readable, writable, or both. All streams are instances of
The module can be accessed using:
While it is important to understand how streams work, the module itself is most useful for developers that are creating new types of stream instances. Developers who are primarily consuming stream objects will rarely need to use the module directly.
Organization of this Document
This document is divided into two primary sections with a third section for additional notes. The first section explains the elements of the stream API that are required to use streams within an application. The second section explains the elements of the API that are required to implement new types of streams.
Types of Streams
There are four fundamental stream types within Node.js:
streams from which data can be read (for example
streams to which data can be written
streams that are both and
streams that can modify or transform the data as it is written and read
Additionally this module includes the utility functions and
All streams created by Node.js APIs operate exclusively on strings and (or) objects.
It is possible, however, for stream implementations to work with other types of JavaScript values (with the exception of, which serves a special purpose within streams).
Such streams are considered to operate in "object mode".
Stream instances are switched into object mode using the option when the stream is created. Attempting to switch an existing stream into object mode is not safe.
Both and streams will store data in an internal buffer that can be retrieved using or, respectively.
The amount of data potentially buffered depends on the option passed into the streams constructor.
For normal streams, the option specifies a total number of bytes
For streams operating in object mode, the specifies a total number of objects.
Data is buffered in streams when the implementation calls
If the consumer of the Stream does not call, the data will sit in the internal queue until it is consumed.
Once the total size of the internal read buffer reaches the threshold specified by, the stream will temporarily stop reading data from the underlying resource until the data currently buffered can be consumed (that is, the stream will stop calling the internal method that is used to fill the read buffer).
Data is buffered in streams when the method is called repeatedly.
While the total size of the internal write buffer is below the threshold set by, calls to will return
Once the size of the internal buffer reaches or exceeds the will be returned.
A key goal of the API, particularly the method, is to limit the buffering of data to acceptable levels such that sources and destinations of differing speeds will not overwhelm the available memory.
Because and streams are both and, each maintain two separate internal buffers used for reading and writing, allowing each side to operate independently of the other while maintaining an appropriate and efficient flow of data.
For example, instances are streams whose side allows consumption of data received from the socket and whose side allows writing data to the socket.
Because data may be written to the socket at a faster or slower rate than data is received, it is important for each side to operate (and buffer) independently of the other.
API for Stream Consumers
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:
streams (such as in the example) expose methods such as and  that are used to write data onto the stream.
streams use the API for notifying application code when data is available to be read off the stream.
That available data can be read from the stream in multiple ways.
Both and streams use the API in various ways to communicate the current state of the stream.
and streams are both and
Applications that are either writing data to or consuming data from a stream are not required to implement the stream interfaces directly and will generally have no reason to call
Developers wishing to implement new types of streams should refer to the section API for Stream Implementers.
Writable Streams
Writable streams are an abstraction for a destination to which data is written.
Examples of streams include:
Some of these examples are actually streams that implement the interface.
All streams implement the interface defined by the class.
While specific instances of streams may differ in various ways, all streams follow the same fundamental usage pattern as illustrated in the example below:
The 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.
Not all streams will emit the event.
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.
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.
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.
See also:
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