Platform Support

The following shows stream module APIs available for each platform.

	Linux (Ubuntu)	Raspbian (Raspberry Pi)	NuttX (STM32F4-Discovery)	TizenRT (Artik053)
readable.isPaused	O	O	O	O
readable.pause	O	O	O	O
readable.read	O	O	O	O
readable.resume	O	O	O	O
writable.end	O	O	O	O
writable.write	O	O	O	O

Stream

A stream is an abstract interface for working with streaming data. Streams can be readable, writable, or both (duplex). All streams are instances of EventEmitter.

Class: Stream

new Stream()

This method is only for implementing a new stream type.

This function registers the common properties of all streams.

Example

var Stream = require('stream').Stream;

var stream = new Stream();

stream.read = function () {
  // A custom read function.
}

Class: Stream.Readable

Readable stream is an abstraction for a data source from which data will be read. At any time a readable stream operates in one of two modes: flowing and paused. All streams begin in paused mode.

In paused mode the stream emits 'readable' event every time a new data is available for read. This data can be read by calling the readable.read() function. A stream can be switched to paused mode by calling the readable.pause() function.

In flowing mode the stream emits 'data' events every time when data is received. The data buffer is passed to the callback function. A stream can be switched to flowing mode by calling the readable.resume() function or by adding a 'data' event handler.

Supported events:

Event: ‘close’

Emitted when the underlying resource has been closed and no more events will be emitted. Not all Readable streams will emit the 'close' event.

Event: ‘data’

• chunk {Buffer

  string}

Emitted when the stream passes the ownership of the data to a consumer. Only streams in flowing mode emit this event.

A stream can be switched to flowing mode by calling the readable.resume() function or by adding a 'data' event handler.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.on('data', function (chunk) {
  // prints: data received: message
  console.log('data received: ' + chunk);
})

readable.push("message");

Event: ‘end’

Emitted when there is no more data to be consumed from the stream.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.on('end', function () {
  // prints: no more data
  console.log('no more data');
})

readable.push(null);

Event: ‘error’

• error {Object}

Emitted when an error is detected by the readable stream. This event may occure any time.

Event: ‘readable’

Emitted when there is data available to be read from the stream. This event will also be emitted once the end of the stream data has been reached but before the ‘end’ event is emitted.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.on('readable', function () {
  // prints:.
  console.log('data received: ' + this.read());
})

readable.push('message');

new Readable(options)

• options {Object}
  • defaultEncoding {string} Default: utf8

This method is only for implementing a new Readable stream type.

This function registers the common properties of Readable streams.

The options object allows passing configuration arguments. The Readable constructor only supports a few members of the options object but descendants may supports more of them.

Example

var Readable = require('stream').Readable;

var readable = new Readable({ defaultEncoding: 'utf8' });

readable.isPaused()

• Returns: {boolean}

Returns true if the Readable stream is in paused mode. Otherwise the stream is in flowing mode. By default the stream starts in paused mode.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

// prints: true
console.log(readable.isPaused());

readable.pause()

• Returns: {Readable}

Stops emitting 'data' events if the stream is in flowing mode and sets paused mode. No effect otherwise.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.pause();

readable.read([size])

• size {number} Specify how much data will be read.

• Returns: {Buffer

  null}

The readable.read() method pulls some data out of the internal buffer and returns it. If no data is available null is returned instead.

Note: currently all data must be read.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

// prints: null
console.log(readable.read());

readable.push('message');

// prints: message
console.log(readable.read());

readable.resume()

• Returns: {Readable}

Starts emitting 'data' events if the stream is in paused mode and sets flowing mode. No effect otherwise.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.resume();

readable.push(chunk)

• chunk {Buffer

  string}

This method is only for implementing a new Readable stream type.

Push a chunk of data to the underlying Buffer of this stream. The data can be read by using either readable.read() method or 'data' event of this stream.

Example

var Readable = require('stream').Readable;

var readable = new Readable();

readable.push('message');

// prints: message
console.log(readable.read());

Class: Stream.Writable

Writable stream is an abstraction for a destination to which data is written. Several functions of the Stream.Writable class are abstract interfaces and descendants can override them. The new Stream.Writable() constructor must be used for initializing a writable stream and writable._write() method are required to be implemented.

Supported events:

Event: ‘drain’

If writable.write() returns false the stream emits a drain event when it is appropriate to resume writing data into the stream.

Example

var Writable = require('stream').Writable;

// Buffer is full after 1 byte of data.
var writable = new Writable({ highWaterMark:1 });

writable._write = function(chunk, callback, onwrite) {
  onwrite();
}

// Writes 1 byte data into the stream.
writable.write("X");

writable.on('drain', function() {
  // prints: can continue writing
  console.log('can continue writing');
});

writable._readyToWrite();

Event: ‘error’

• err {Error}

Emitted if an error occures during writing the data.

Event: ‘finish’

Emitted after writable.end() has been called and all pending data has been flushed.

Example

var Writable = require('stream').Writable;

var writable = new Writable();

writable.on('finish', function() {
  // prints: end of writing
  console.log('end of writing');
});

writable.end();

new Stream.Writable([options])

• options {Object}
  • highWaterMark {number}

This method is only for implementing a new Writable stream type.

This function registers the common properties of Writable streams.

When the size of the internal buffer reaches options.highWaterMark the writable.write() method starts returning with false and the data should be drained before further data is written.

Example

var Writable = require('stream').Writable;

var writable = new Writable({ highWaterMark:256 });

writable.end([chunk][, encoding][, callback])

• chunk {Buffer

  string} Final data to write.

• encoding {string} The encoding, if chunk is a string
• callback {Function}

Calling this function signals that no more data will be written to the Writable. The optional chunk argument allows writing a final chunk of data. If chunk is null no data is written.

The optional callback function is attached as a listener for the ‘finish’ event.

Example

var Writable = require('stream').Writable;

var writable = new Writable();

writable.end();

writable.write(chunk[, encoding][, callback])

• chunk {Buffer

  string} Data to write.

• encoding {string} The encoding, if chunk is a string
• callback {Function} Called when this chunk of data is flushed.
• Returns: {boolean}

Converts chunk into a sequence of bytes and writes this data to the stream. An optional callback function is called when the data is flushed.

The returned value is true if writing can be continued right after calling this method. Otherwise the returned value is false and no data should be written until the 'drain' event is received.

Example

var Writable = require('stream').Writable;

var writable = new Writable();

writable.write("String");

writable._readyToWrite()

This method is only for implementing a new Writable stream type.

This method informs the Writable stream that the implementation is ready for receiving data.

Example

var Writable = require('stream').Writable;

var writable = new Writable();

writable._readyToWrite();

writable._write(chunk, encoding, callback, onwrite)

• chunk {Buffer

  string} The data to be written by the stream.

• encoding {string} If the chunk is a string, then encoding is the character encoding of that string. If chunk is a Buffer, or if the stream is operating in object mode, encoding may be ignored.
• callback {Function} Callback to be called when the chunk of data is flushed.
• onwrite {Function} Internal Callback to be called for when the chunk of data is flushed.

This method is only for implementing a new Writable stream type.

This internal method is called by the Writable stream and the implementation must override it. The data to be written is passed as the chunk argument. After the operation is completed, both callback and onwrite function should be called.

Example

var Writable = require('stream').Writable;

var writable = new Writable();

writable._write = function(chunk, encoding, callback, onwrite) {
  // prints: message
  console.log(chunk);

  onwrite();
  if (callback)
    callback();
}

writable._readyToWrite();

writable.write('message');

Class: Stream.Duplex

Duplex streams are streams that implement both the Readable and Writable interfaces.