ReadStream-Watcher

We got that fs.ReadStream, we got that FSWatcher, we got that combination fs.ReadStream and FSWatcher. (If the joke is lost on you, see this video.)

Installation

npm install [--save] readstream-watcher

Usage

A simple example, which prints the file's contents (entirely, unlike tail -f or similar) once every time the file changes.

var createReadStreamWatcher = require('readstream-watcher');

function printWaitLoop() {
  createReadStreamWatcher('./some-file')
    .once('change', function () {
      this.close();
      this.unpipe(process.stdout);
      printWaitLoop();
    })
    .pipe(process.stdout);
}

printWaitLoop();

ReadStreamWatcher interface

As it turns out, there are a lot of undocumented methods on ReadStream and FSWatcher instances. As a result, and to avoid confusing collisions, only a subset of their API is supported:

| Property | Origin | Description | |------------|----------|---------------| | path | ReadStream | The path to the file the stream is reading from. | | pipe(destination, [options]) | ReadStream | Writes all the data to the supplied destination. | | read([size]) | ReadStream | Returns size bytes of available data, returning null otherwise. | | close() | FSWatcher | Stop watching for changes on the given FSWatcher. No changes are made to the stream. |

| Event | Origin | Description | |---------|----------|---------------| | open | ReadStream | Emitted when the ReadStream's file is opened with the now-open file descriptor. | | close | ReadStream | Emitted when the stream and any of its underlying resources have been closed. | | data | ReadStream | Emitted when data is available, setting the stream into flowing mode. | | end | ReadStream | Emitted when there will be no more data to read. | | readable | ReadStream | Emitted when a chunk of data can be read from the stream. | | change | FSWatcher | Emitted when something changes in the watched file. | | error | ReadStream/FSWatcher | Emitted when an error occurs, passing along that Error instance. |

Finally, the constructor itself, returned when require-ing the module, accepts two arguments: the filename to watch, and options to pass into both the ReadStream and the FSWatcher. The supported options, then, are the sum of those two constructors. The most common options are:

| Option | Origin | Description | |----------|----------|---------------| | encoding | ReadStream | If specified, data read will be in the specified format in lieu of Buffers. Defaults to null. | | persistent | FSWatcher | If true, the process should continue to run as long as files are being watched. Defaults to true. |

Relevant Links

• Documentation for fs.ReadStream
• Documentation for fs.FSWatcher