Readable
Node: Readable Stream.
A Readable stream is an abstraction for a source from which data is consumed; an example of a Readable stream is the response object returned by http.get(), or the input stream provided to a running program.
Examples of Readable streams include:
HTTP responses, on the client
HTTP requests, on the server
fs read streams
zlib streams
crypto streams
TCP sockets
child process
stdoutandstderrprocess.stdin
All Readable streams implement the interface defined by the stream.Readable class.
Two reading modes
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.
In flowing mode, data is read from the underlying system automatically and provided to an application as quickly as possible using events via the EventEmitter interface.
In paused mode, the read method must be called explicitly to read chunks of data from the stream.
All Readable streams begin in paused mode but can be switched to flowing mode in one of the following ways:
Adding a
'data'event handler.Calling the resume method.
The Readable can switch back to paused mode using one of the following:
If there are no pipe destinations, by calling the pause method.
If there are pipe destinations, by removing all pipe destinations. Multiple pipe destinations may be removed by calling the unpipe method.
The important concept to remember is that a Readable 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 Readable will attempt to stop generating the data.
For backward compatibility reasons, removing 'data' event handlers will not automatically pause the stream. Also, if there are piped destinations, then calling pause will not guarantee that the stream will remain paused once those destinations drain and ask for more data.
If a Readable 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 resume method is called without a listener attached to the 'data' event, or when a 'data' event handler is removed from the stream.
Adding a 'readable' event handler automatically makes the stream stop flowing, and the data has to be consumed via read. If the 'readable' event handler is removed, then the stream will start flowing again if there is a 'data' event handler.
Three states
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.
Specifically, at any given point in time, every Readable is in one of three possible states:
readable.readableFlowing === nullreadable.readableFlowing === falsereadable.readableFlowing === true
When Readable.readableFlowing is null, no mechanism for consuming the stream's data is provided. Therefore, the stream will not generate data. While in this state, attaching a listener for the 'data' event, calling the Readable.pipe method, or calling the Readable.resume method will switch Readable.readableFlowing to true, causing the Readable to begin actively emitting events as data is generated.
Calling Readable.pause, Readable.unpipe, or receiving backpressure will cause the Readable.readableFlowing flag to be set as false, temporarily halting the flowing of events but not halting the generation of data. While in this state, attaching a listener for the 'data' event will not switch Readable.readableFlowing to true.
Event: 'close'
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.
See also
for the corresponding writable stream interface.
Inheritors
Types
Properties
Returns whether the stream was destroyed or errored before emitting 'end'.
Returns whether 'data' has been emitted.
Getter for the property encoding of a given Readable stream. The encoding property can be set using the readable.setEncoding() method.
Becomes true when 'end' event is emitted.
This property reflects the current state of a Readable stream as described in the "Three states" section.
Returns the value of highWaterMark passed when creating this Readable.
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.
Getter for the property objectMode of a given Readable stream.
Functions
Alias for emitter.on(eventName, listener).
Destroy the stream. Optionally emit an error event, and emit a close event (unless emitClose is set to false). After this call, the readable stream will release any internal resources and subsequent calls to push() will be ignored.
Dispatches the event to the list of handlers for Event.type.
Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.
Check if all items in this stream match the given predicate.
Find the first item in this stream that matches the given predicate.
Map over this stream to produce a new stream of items.
For each item in this stream, call the given callback.
Returns the current max listener value for the emitter.
Get an iterator for this stream.
Returns the number of listeners listening to the event named eventName.
Returns an array listing the listeners for the specified event.
Adds the listener function to the beginning of the listeners array for the event named eventName. No checks are made to see if the listener has already been added.
Adds a one-time listener function for the event named eventName to the beginning of the listener array. The next time eventName is triggered, this listener is removed, and then invoked.
Returns a copy of the array of listeners for the event named eventName, including any wrappers (such as those created by .once()).
The readable.read() method reads some data from the readable stream and returns it. The data will not be returned immediately if the readable stream is in flowing mode; in that case, the data will be buffered internally, and this method will return it when it is available.
Reduce this stream to a single value.
Removes all listeners, or those of the specified eventName.
Removes all listeners, or those of the specified eventName.
Removes the listener from the list of handlers for event type.
The readable.setEncoding() method sets the encoding for the Readable stream. This method must be called before the first 'data' event is emitted by the stream.
Sets the maximum number of listeners for the emitter.
Check if any item in this stream matches the given predicate.
The readable.unshift() method pushes a chunk of data back into the internal buffer for the stream.