Italian Translation Report: Node.js [Part 22 - 1371 words]

Three States
The "two modes" of operation for a stream are a simplified abstraction for the more complicated internal state management that is happening within the stream implementation.
Specifically, at any given point in time, every is in one of three possible states:
When is, no mechanism for consuming the streams data is provided so the stream will not generate its data.
While in this state, attaching a listener for the event, calling the method, or calling the method will switch to, causing the, to begin actively emitting events as data is generated.
Calling, or receiving "back pressure" will cause the to be set as, temporarily halting the flowing of events but not halting the generation of data.
While in this state, attaching a listener for the event would not cause to switch to
is now false
will not emit
must be called to make being emitted
While is, data may be accumulating within the streams internal buffer.
Choose One
The 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.
Use of the method is recommended for most users as it has been implemented to provide the easiest way of consuming stream data.
Developers that require more fine-grained control over the transfer and generation of data can use the and APIs.
The chunk of data.
For streams that are not operating in object mode, the chunk will be either a string or
For streams that are in object mode, the chunk can be any JavaScript value other than
The 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, or by attaching a listener callback to the event.
The event will also be emitted whenever the method is called and a chunk of data is available to be returned.
Attaching a event listener to a stream that has not been explicitly paused will switch the stream into flowing mode.
Data will then be passed as soon as it is available.
The listener callback will be passed the chunk of data as a string if a default encoding has been specified for the stream using the method; otherwise the data will be passed as a
The event is emitted when there is no more data to be consumed from the stream.
The 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 repeatedly until all data has been consumed.
The event may be emitted by a 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 listener callback will be passed a single object.
The event is emitted when there is data available to be read from the stream
In some cases, attaching a listener for the event will cause some amount of data to be read into an internal buffer.
there is some data to read now
The event will also be emitted once the end of the stream data has been reached but before the event is emitted.
Effectively, the event indicates that the stream has new information: either new data is available or the end of the stream has been reached.
In the former case, will return the available data.
In the latter case, will return
For instance, in the following example, is an empty file:
The output of running this script is:
In general, the and event mechanisms are easier to understand than the event.
However, handling might result in increased throughput.
If both and are used at the same time, takes precedence in controlling the flow, i.e. will be emitted only when is called.
Error which will be passed as payload in event
Destroy the stream, and emit and
After this call, the readable stream will release any internal resources and subsequent calls to will be ignored.
Implementors should not override this method, but instead implement
The method returns the current operating state of the
This is used primarily by the mechanism that underlies the method.
In most typical cases, there will be no reason to use this method directly.
The method will cause a stream in flowing mode to stop emitting events, switching out of flowing mode.
Any data that becomes available will remain in the internal buffer.
The destination for writing data
Pipe options
End the writer when the reader ends.
making it possible to set up chains of piped streams
The method attaches a stream to the causing it to switch automatically into flowing mode and push all of its data to the attached
The flow of data will be automatically managed so that the destination stream is not overwhelmed by a faster stream.
The following example pipes all of the data from the into a file named
All the data from readable goes into
It is possible to attach multiple streams to a single stream.
The method returns a reference to the destination stream making it possible to set up chains of piped streams:
By default, is called on the destination stream when the source stream emits, so that the destination is no longer writable
To disable this default behavior, the option can be passed as, causing the destination stream to remain open, as illustrated in the following example:
One important caveat is that if the stream emits an error during processing, the destination is not closed automatically.
If an error occurs, it will be necessary to manually close each stream in order to prevent memory leaks.
The and streams are never closed until the Node.js process exits, regardless of the specified options.
Optional argument to specify how much data to read.
The method pulls some data out of the internal buffer and returns it.
If no data available to be read, is returned.
By default, the data will be returned as a object unless an encoding has been specified using the method or the stream is operating in object mode.
The optional argument specifies a specific number of bytes to read.
If bytes are not available to be read, will be returned unless the stream has ended, in which case all of the data remaining in the internal buffer will be returned.
If the argument is not specified, all of the data contained in the internal buffer will be returned.
The method should only be called on streams operating in paused mode.
In flowing mode, is called automatically until the internal buffer is fully drained.
A stream in object mode will always return a single item from a call to, regardless of the value of the argument.
If the method returns a chunk of data, a event will also be emitted.
Calling after the event has been emitted will return
No runtime error will be raised.
Returns the value of passed when constructing this
This property contains the number of bytes (or objects) in the queue ready to be read.
The method causes an explicitly paused stream to resume emitting events, switching the stream into flowing mode.
The method can be used to fully consume the data from a stream without actually processing any of that data as illustrated in the following example:
The method has no effect if there is a event listener.
The encoding to use.
The method sets the character encoding for data read from the stream.
By default, no encoding is assigned and stream data will be returned as objects.
Setting an encoding causes the stream data to be returned as strings of the specified encoding rather than as objects.
For instance, calling will cause the output data to be interpreted as UTF-8 data, and passed as strings.
Calling will cause the data to be encoded in hexadecimal string format.
The stream will properly handle multi-byte characters delivered through the stream that would otherwise become improperly decoded if simply pulled from the stream as objects.