Italian Translation Report: Node.js [Part 25 - 1168 words]

Implementing a Transform Stream
A stream is a stream where the output is computed in some way from the input.
Examples include streams or streams that compress, encrypt, or decrypt data.
There is no requirement that the output be the same size as the input, the same number of chunks, or arrive at the same time.
For example, a stream will only ever have a single chunk of output which is provided when the input is ended.
A stream will produce output that is either much smaller or much larger than its input.
The class is extended to implement a stream.
The class prototypically inherits from and implements its own versions of the and methods
Custom implementations must implement the method and may also implement the method.
Care must be taken when using streams in that data written to the stream can cause the side of the stream to become paused if the output on the side is not consumed.
Also has the following fields:
Implementation for the method.
The and events are from the and classes, respectively.
The event is emitted after is called and all chunks have been processed by
The event is emitted after all data has been output, which occurs after the callback in has been called.
A callback function (optionally with an error argument and data) to be called when remaining data has been flushed.
In some cases, a transform operation may need to emit an additional bit of data at the end of the stream. For example, a compression stream will store an amount of internal state used to optimally compress the output. When the stream ends, however, that additional data needs to be flushed so that the compressed data will be complete.
Custom implementations may implement the method.
This will be called when there is no more written data to be consumed, but before the event is emitted signaling the end of the stream.
Within the implementation, the method may be called zero or more times, as appropriate.
The function must be called when the flush operation is complete.
The method is prefixed with an underscore because it is internal to the class that defines it, and should never be called directly by user programs.
The chunk to be transformed.
Will always be a buffer unless the option was set to or the stream is operating in object mode.
If the chunk is a string, then this is the encoding type.
If chunk is a buffer, then this is the special value - ignore it in this case.
A callback function (optionally with an error argument and data) to be called after the supplied has been processed.
All stream implementations must provide a method to accept input and produce output.
The implementation handles the bytes being written, computes an output, then passes that output off to the readable portion using the method.
The method may be called zero or more times to generate output from a single input chunk, depending on how much is to be output as a result of the chunk.
It is possible that no output is generated from any given chunk of input data.
The function must be called only when the current chunk is completely consumed.
The first argument passed to the must be an object if an error occurred while processing the input or otherwise.
If a second argument is passed to the, it will be forwarded on to the method.
In other words the following are equivalent:
The method is prefixed with an underscore because it is internal to the class that defines it, and should never be called directly by user programs.
is never called in parallel; streams implement a queue mechanism, and to receive the next chunk, must be called, either synchronously or asynchronously.
The class is a trivial implementation of a stream that simply passes the input bytes across to the output.
Its purpose is primarily for examples and testing, but there are some use cases where is useful as a building block for novel sorts of streams.
Additional Notes
Compatibility with Older Node.js Versions
In versions of Node.js prior to v0.10, the stream interface was simpler, but also less powerful and less useful.
Rather than waiting for calls the method, events would begin emitting immediately.
Applications that would need to perform some amount of work to decide how to handle data were required to store read data into buffers so the data would not be lost.
The method was advisory, rather than guaranteed.
This meant that it was still necessary to be prepared to receive events even when the stream was in a paused state
In Node.js v0.10, the class was added.
For backwards compatibility with older Node.js programs, streams switch into "flowing mode" when a event handler is added, or when the method is called.
The effect is that, even when not using the new method and event, it is no longer necessary to worry about losing chunks.
While most applications will continue to function normally, this introduces an edge case in the following conditions:
No event listener is added.
The method is never called.
The stream is not piped to any writable destination.
For example, consider the following code:
we add an listener, but never consume the data
It will never get here.
In versions of Node.js prior to v0.10, the incoming message data would be simply discarded.
However, in Node.js v0.10 and beyond, the socket remains paused forever.
The workaround in this situation is to call the method to begin the flow of data:
start the flow of data, discarding it.
In addition to new streams switching into flowing mode, pre-v0.10 style streams can be wrapped in a class using the method.
There are some cases where it is necessary to trigger a refresh of the underlying readable stream mechanisms, without actually consuming any data.
In such cases, it is possible to call, which will always return
If the internal read buffer is below the, and the stream is not currently reading, then calling will trigger a low-level call.
While most applications will almost never need to do this, there are situations within Node.js where this is done, particularly in the stream class internals.
Use of is not recommended.
Pushing a zero-byte string, or to a stream that is not in object mode has an interesting side effect.
Because it is a call to, the call will end the reading process.
However, because the argument is an empty string, no data is added to the readable buffer so there is nothing for a user to consume.
The use of will change the behavior of how the operates in non-object mode.
Typically, the size of the current buffer is measured against the in bytes
However, after is called, the comparison function will begin to measure the buffer's size in characters
This is not a problem in common cases with or
But it is advised to be mindful about this behavior when working with strings that could contain multi-byte characters.