# FS Stream : Stream file system

This module implements the file Readable stream and Writable stream.

User can use the following code to create the fs.ReadStream and fs.WriteStream module.

var fs = require('fs');

# Support

The following shows fs.ReadStream and fs.WriteStream module APIs available for each permissions.

# fs.ReadStream Class

# fs.createReadStream(path[, options])

• path {String} File path.
• options {Object}
  • flags {String} See support of file system flags. default: 'r'.
  • mode {Integer} default: 0o666.
  • start {Integer} Start of file, default: 0.
  • end {Integer} End of file, default: Infinity.
  • autoClose {Boolean} default: true.
  • emitClose {Boolean} default: true.
  • highWaterMark {Integer} default: 256KB.
  • maxChunkSize {Integer} JSRE expansion, default: half of highWaterMark.
• Returns: See Readable Stream.

Unlike the 16KB default highWaterMark for a readable stream, the stream returned by this method has a default highWaterMark of 256KB.

options can include start and end values to read a range of bytes from the file instead of the entire file. Both start and end are inclusive and start counting at 0, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range.

EdgerOS 1.7.3 and later version changed default value of options.emitClose to true.

By default, the stream will not emit a 'close' event after it has been destroyed. This is the opposite of the default for other Readable streams. Set the emitClose option to true to change this behavior.

If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak. If autoClose is set to true (default behavior), on 'error' or 'end' the file descriptor will be closed automatically.

mode sets the file mode (permission and sticky bits), but only if the file was created.

An example to read the last 10 bytes of a file which is 100 bytes long:

# Example

fs.createReadStream('sample.txt', { start: 90, end: 99 });

# fs.ReadStream Object

A successful call to fs.createReadStream() will return a new fs.ReadStream object.

# readStream.bytesRead

• {Integer} The number of bytes that have been read so far.

# readStream.path

• {String} The path to the file the stream is reading from as specified in the first argument to fs.createReadStream().

# readStream.pending

• {Boolean} This property is true if the underlying file has not been opened yet, i.e. before the 'ready' event is emitted.

# readable.destroy([error])

See stream.Readable from detail.

# readable.isPaused()

See stream.Readable from detail.

# readable.pause()

See stream.Readable from detail.

# readable.pipe(destination[, options])

See stream.Readable from detail.

# readable.read([size])

See stream.Readable from detail.

# readable.resume()

See stream.Readable from detail.

# readable.unpipe([destination])

See stream.Readable from detail.

# readable.destroyed

See stream.Readable from detail.

# readable.readable

See stream.Readable from detail.

# readable.readableEnded

See stream.Readable from detail.

# readable.readableFlowing

See stream.Readable from detail.

# readable.readableHighWaterMark

See stream.Readable from detail.

# readable.readableLength

See stream.Readable from detail.

# fs.ReadStream Events

# close

Emitted when the fs.ReadStream's underlying file descriptor has been closed.

# open

• fd {Integer} Integer file descriptor used by the ReadStream.

Emitted when the fs.ReadStream's file descriptor has been opened.

# ready

Emitted when the fs.ReadStream is ready to be used.

Fires immediately after 'open'.

# data

See stream.Readable from detail.

# end

See stream.Readable from detail.

# error

See stream.Readable from detail.

# pause

See stream.Readable from detail.

# readable

See stream.Readable from detail.

# resume

See stream.Readable from detail.

# fs.WriteStream Class

# fs.createWriteStream(path[, options])

• path {String} File path.
• options {Object}
  • flags {String} See support of file system flags. default: 'w'.
  • mode {Integer} default: 0o666.
  • start {Integer} Start of file, default: 0.
  • autoClose {Boolean} default: true.
  • emitClose {Boolean} default: true.
• Returns: See Writable Stream.

options may also include a start option to allow writing data at some position past the beginning of the file, allowed values are in the [0, Number.MAX_SAFE_INTEGER] range. Modifying a file rather than replacing it may require the flags option to be set to r+ rather than the default w.

If autoClose is set to true (default behavior) on 'error' or 'finish' the file descriptor will be closed automatically. If autoClose is false, then the file descriptor won't be closed, even if there's an error. It is the application's responsibility to close it and make sure there's no file descriptor leak.

EdgerOS 1.7.3 and later version changed default value of options.emitClose to true.

By default, the stream will not emit a 'close' event after it has been destroyed. This is the opposite of the default for other Writable streams. Set the emitClose option to true to change this behavior.

# fs.WriteStream Object

# writeStream.bytesWritten

• {Integer} The number of bytes written so far. Does not include data that is still queued for writing.

# writeStream.path

• {String} The path to the file the stream is writing to as specified in the first argument to fs.createWriteStream().

# writeStream.pending

• {Boolean} This property is true if the underlying file has not been opened yet, i.e. before the 'ready' event is emitted.

# writable.destroy([error])

See stream.writable from detail.

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

See stream.writable from detail.

# writable.write(chunk[, callback])

See stream.writable from detail.

# writable.destroyed

See stream.writable from detail.

# writable.writable

See stream.writable from detail.

# writable.writableEnded

See stream.writable from detail.

# writable.writableFinished

See stream.writable from detail.

# writable.writableHighWaterMark

See stream.writable from detail.

# writable.writableLength

See stream.writable from detail.

# fs.WriteStream Events

# close

Emitted when the WriteStream's underlying file descriptor has been closed.

# open

• fd {Integer} Integer file descriptor used by the WriteStream.

Emitted when the WriteStream's file is opened.

# ready

Emitted when the fs.WriteStream is ready to be used.

Fires immediately after 'open'.

# drain

See stream.writable from detail.

# error

See stream.writable from detail.

# finish

See stream.writable from detail.

# pipe

See stream.writable from detail.

# unpipe

See stream.writable from detail.

# Example

• Write file:

var iosched = require('iosched');
var fs = require('fs');

var writeStream = fs.createWriteStream('./temfile.txt', {flags: 'w+'});

writeStream.on('ready', () => {
  console.log('on ready');

  for(var i = 0; i < 20; i++) {
    writeStream.write(`This is a file stream test.\n`);
  }
  writeStream.end('[File end]');
});

writeStream.on('error', (err) => {
  console.log('on error:', err);
});

writeStream.on('finish', () => {
  console.log('on finish');
});

while (true) {
  iosched.poll();
}

• Read file in paused mode:

var iosched = require('iosched');
var fs = require('fs');

var readStream = fs.createReadStream('./temfile.txt');

readStream.on('ready', () => {
  console.log('on ready');

  function onRead() {
    var buf = undefined;
    do {
      buf = readStream.read(28);
      if (buf) {
        console.info('read data:', buf.toString());
      } else if (readStream.readable) {
        readStream.once('readable', onRead);
      }
    } while(buf);
  }
  onRead();
});

readStream.on('error', (err) => {
  console.log('on error:', err);
});

readStream.on('end', () => {
  console.log('on end');
});

while (true) {
  iosched.poll();
}

• Read file in flowing mode:

var iosched = require('iosched');
var fs = require('fs');

var readStream = fs.createReadStream('./temfile.txt');

readStream.on('data', (chunk) => {
  console.info('recv data:', chunk.toString());
});

readStream.on('error', (err) => {
  console.log('on error:', err);
});

readStream.on('end', () => {
  console.log('on end');
});

while (true) {
  iosched.poll();
}

• Pipe:

var iosched = require('iosched');
var fs = require('fs');

var readStream = fs.createReadStream('./temfile.txt');
var writeStream = fs.createWriteStream('./pipestream.txt', {flags: 'w+'});

readStream.on('ready', () => {
  readStream.pipe(writeStream);
});

readStream.on('error', (err) => {
  console.log('on error:', err);
  writeStream.destroy();
});

while (true) {
  iosched.poll();
}