All streams inherit from the EventEmitter class and emit a series of different events. When working with streams, it's a good idea to understand some of the more important events being emitted. Knowing what each event means will make debugging streams a lot easier:
- data: Emitted when new data is read from a readable stream. The data is provided as the first argument to the event handler. Beware that unlike other event handlers, attaching a data listener has side effects. When the first data listener is attached, our stream will be unpaused. We should never emit data ourselves. Instead, we should always use the push function.
- end: Emitted when a readable stream has no more data available and all the available data has been read. We should never emit end ourselves; instead, we should pass null to push to signify the end of the data.
- finish: Emitted when a writable stream has been ended and all pending writes have been completed. Similar to the aforementioned events, we should never emit finish ourselves. Use end() to trigger finish manually and pipe a readable stream to it.
- close: Loosely defined in the stream docs, close is usually emitted when the stream is fully closed. Contrary to end and finish, a stream is not guaranteed to emit this event. It is fully up to the implementer to do this.
- error: Emitted when a stream has experienced an error. This to be followed by a close event although, again, there are no guarantees that this will happen.
- pause: Emitted when a readable stream has been paused. Pausing will happen when either backpressure occurs or if the pause method is explicitly called. For most use cases, you can just ignore this event, although it is useful to listen for, for debugging purposes sometimes. See the There's more section of the Decoupling I/O recipe for an example of backpressure and pause usage.
- resume: Emitted when a readable stream goes from being paused to being resumed again. This will happen when the writable stream you are piping to has been drained or if resume has been explicitly called. See the There's more section of the Decoupling I/O recipe for an example of resume usage.